Update documentation (#294)

* Small updates in READMEs

* Update the DS README

* 5.2.10 -> 5.2.11

* Update CHANGELOG

* Add external resources section

CHANGELOG.md

@@ -23,6 +23,7 @@ Release Versions:
 - Add CartesianState attribute setters from std vector and coefficients (#291)
 - Add CMake config for clproto (#292)
 - Update and extend demos with Python examples and migrate ROS demos away (#293)
+- Update documentation (#294)
 
 ## 5.2.0
 

README.md

@@ -12,7 +12,7 @@
         </td>
     </tr>
     <tr>
-        <td width="25%"><a href="https://github.com/epfl-lasa/control-libraries/tree/develop">Development</a></td>
+        <td width="25%"><a href="https://github.com/epfl-lasa/control-libraries/tree/develop">Develop</a></td>
         <td width="75%"><img src="https://github.com/epfl-lasa/control-libraries/actions/workflows/build-test.yml/badge.svg?branch=develop"></td>
     </tr>
 </table>
@@ -21,18 +21,30 @@
 A set of libraries to facilitate the creation of full control loop algorithms,
 including trajectory planning, kinematics, dynamics and control.
 
-Documentation is available at <a href="https://epfl-lasa.github.io/control-libraries/versions/main/">epfl-lasa.github.io/control-libraries</a>
+Documentation is available at <a href="https://epfl-lasa.github.io/control-libraries/versions/">epfl-lasa.github.io/control-libraries</a>.
 
 ## Core libraries
 
-For the implementation, installation and documentation of the core libraries, see the
-<a href="https://github.com/epfl-lasa/control-libraries/tree/main/source">source</a> folder.
+For the implementation, installation and documentation of the core libraries, see the [source](./source) folder.
+
+## Protocol
+
+There is a module that defines the protocol for sending and receiving messages containing control libraries
+data across any network, based on the Google Protocol Buffer. For its implementation, installation and
+documentation, see the [protocol](./protocol) folder.
 
 ## Python bindings
 
-There exist Python bindings for core control library modules. See the <a href="https://github.com/epfl-lasa/control-libraries/tree/main/python">python</a>
-folder for installation instructions and currently supported libraries.
+There exist Python bindings for the control library modules and the protocol module. See the [python](./python)</a>
+folder for installation instructions.
 
 ## Demos
 
-For examples and demos in plain C++, ROS, and ROS2, refer to the <a href="https://github.com/epfl-lasa/control-libraries/tree/main/demos">demos</a> folder.
+For examples and demos in C++ and Python, refer to the [demos](./demos) folder.
+TODO link ros demos repo
+
+## External resources
+
+- C++ remote development in CLion [here](https://github.com/eeberhard/docker-clion-cpp-env)
+- ROS and ROS2 demos using control libraries [here](https://github.com/domire8/control-libraries-ros-demos)
+- ROS and ROS2 control libraries images [here](https://github.com/aica-technology/docker-images)

VERSION

@@ -1 +1 @@
-5.2.10
+5.2.11

doxygen/doxygen.conf

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Control Libraries"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER = 5.2.10
+PROJECT_NUMBER = 5.2.11
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

protocol/clproto_cpp/CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.15)
 
-project(clproto VERSION 5.2.10)
+project(clproto VERSION 5.2.11)
 
 # Default to C99
 if(NOT CMAKE_C_STANDARD)

python/README.md

@@ -18,6 +18,9 @@ git clone https://github.com/epfl-lasa/control-libraries
 ## install control-libraries (skip this stage if already done)
 sudo control-libraries/source/install.sh
 
+## install protocol (skip this stage if already done or not desired)
+sudo control-libraries/protocol/install.sh
+
 ## install the bindings using the pip installer
 pip3 install control-libraries/python
 ```
@@ -49,18 +52,18 @@ import dynamical_systems
 print(sr.__version__)
 print(dynamical_systems.__version__)
 
-A = sr.CartesianState.Random("A")
+A = sr.CartesianState().Random("A")
 print(A)
 ```
 
 Or, directly import specific classes from the module.
 ```python
 #!/usr/bin/env python
 from state_representation import JointState
-from dynamical_systems import create_cartesian_ds, DYNAMICAL_SYSTEM
+from dynamical_systems import create_cartesian_ds, DYNAMICAL_SYSTEM_TYPE
 
-B = JointState.Random("B", 3)
-ds = create_cartesian_ds(DYNAMICAL_SYSTEM.POINT_ATTRACTOR)
+B = JointState().Random("B", 3)
+ds = create_cartesian_ds(DYNAMICAL_SYSTEM_TYPE.POINT_ATTRACTOR)
 ```
 
 If the `clproto` C++ library is installed, the installation steps above will automatically install the `clproto`
@@ -70,7 +73,7 @@ Python module which can be used to encode and decode objects into bytes of seria
 from state_representation import JointState
 import clproto
 
-B = JointState.Random("B", 3)
+B = JointState().Random("B", 3)
 encoded_msg = clproto.encode(B, clproto.MessageType.JOINT_STATE_MESSAGE)
 
 decoded_object = clproto.decode(encoded_msg)

python/setup.py

@@ -10,7 +10,7 @@
 osqp_path_var = 'OSQP_INCLUDE_DIR'
 openrobots_path_var = 'OPENROBOTS_INCLUDE_DIR'
 
-__version__ = "5.2.10"
+__version__ = "5.2.11"
 __libraries__ = ['state_representation', 'clproto', 'controllers', 'dynamical_systems', 'robot_model']
 __include_dirs__ = ['include']
 

source/CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.15)
 
-project(control_libraries VERSION 5.2.10)
+project(control_libraries VERSION 5.2.11)
 
 # Build options
 option(BUILD_TESTING "Build all tests." OFF)

source/README.md

@@ -2,7 +2,7 @@
 
 ## `state_representation`
 
-This library provides a set of classes to represent **states** in **Cartesian** or **joint** spaces.
+This library provides a set of classes to represent **states** in **Cartesian** or **joint** space.
 The classes define and combine variables such as position, velocity, acceleration and force into
 a consistent internal representation used across the other libraries.
 
@@ -188,29 +188,3 @@ lines to the CMakeLists file:
 list(APPEND CMAKE_PREFIX_PATH /opt/openrobots)
 include_directories(/opt/openrobots/include)
 ```
-
-## Troubleshooting
-
-This section lists common problems that might come up when using the `control-libraries` modules.
-
-### Boost container limit compile error in ROS
-When using the `robot_model` module in ROS and trying to `catkin_make` the workspace, it might produce the following error:
-```bash
-/opt/openrobots/include/pinocchio/container/boost-container-limits.hpp:29:7: error: #error "BOOST_MPL_LIMIT_LIST_SIZE value is lower than the value of PINOCCHIO_BOOST_MPL_LIMIT_CONTAINER_SIZE"
-#23 2.389    29 |     # error "BOOST_MPL_LIMIT_LIST_SIZE value is lower than the value of PINOCCHIO_BOOST_MPL_LIMIT_CONTAINER_SIZE"
-```
-In order to avoid this error and successfully `catkin_make` the workspace, make sure that the `CMakeList.txt` of the ROS
-package contains all the necessary directives, i.e. on top of
-
-```cmake
-list(APPEND CMAKE_PREFIX_PATH /opt/openrobots)
-include_directories(/opt/openrobots/include)
-find_package(control_libraries REQUIRED)
-```
-it should also have
-```bash
-find_package(Boost REQUIRED COMPONENTS system)
-add_compile_definitions(BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS)
-add_compile_definitions(BOOST_MPL_LIMIT_LIST_SIZE=30)
-```
-For a comprehensive example, please check the [`CMakeLists.txt` of the ROS demos](../demos/ros_examples/CMakeLists.txt).

source/controllers/README.md

@@ -3,7 +3,14 @@
 This library introduces a set of controllers to be used in robotic control-loop schemes. 
 
 All controllers have a common interface inheriting from the `IController<S>` class, which is templated to 
-operate in a particular space `S`, namely joint space or Cartesian space.
+operate in a particular space `S`, namely Cartesian or joint space.
+
+## Table of contents
+* [Constructing a controller](#constructing-a-controller)
+* [Using a controller](#using-a-controller)
+  * [Parameters](#parameters)
+  * [Compute command](#compute-command)
+* [Developing a new controller](#developing-a-new-controller)
 
 ## Constructing a controller
 
@@ -201,7 +208,7 @@ protected:
 // MyCartesianController.cpp
 #include "MyCartesianController.hpp"
 
-#include "controllers/exceptions/InvalidParameterException.hpp"
+#include "state_representation/exceptions/InvalidParameterException.hpp"
 
 using namespace state_representation;