Release Version 4.1.0

Version 4.1.0 contains a few improvements to the behaviour and usage of the libraries,
namely to the Python bindings and the `clproto` serialization library.

See the CHANGELOG and release notes for more details.

.github/actions/build-test-python/entrypoint.sh

@@ -2,7 +2,7 @@
 
 echo ">>> Installing control libraries..."
 bash /github/workspace/source/install.sh --auto --no-controllers --no-dynamical-systems --no-robot-model || exit 1
-ldconfig
+bash /github/workspace/protocol/install.sh --auto || exit 1
 
 echo ">>> Building Python bindings..."
 pip3 install /github/workspace/python || (echo ">>> [ERROR] Build stage failed!" && exit 2) || exit $?

.github/workflows/build-push.yml

@@ -9,7 +9,29 @@ on:
 
 jobs:
 
+  build-publish-proto-dependencies:
+    runs-on: ubuntu-latest
+    name: Build and publish proto dependencies image
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v2
+
+      - name: Build image
+        run: |
+          docker build . --file ./Dockerfile.proto  --tag proto-dependencies
+
+      - name: Login to GitHub Container Registry
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
+
+      - name: Push image
+        run: |
+          IMAGE_NAME=${{ github.repository }}/proto-dependencies:latest
+          IMAGE_NAME=${IMAGE_NAME/_/-}
+          docker tag proto-dependencies ghcr.io/${IMAGE_NAME}
+          docker push ghcr.io/${IMAGE_NAME}
+
   build-publish-development-dependencies:
+    needs: build-publish-proto-dependencies
     runs-on: ubuntu-latest
     name: Build and publish development dependencies image
     steps:

.github/workflows/generate-docs.yml

@@ -5,6 +5,7 @@ on:
       - main
       - develop
   release:
+    types: [published]
   workflow_dispatch:
 
 jobs:
@@ -24,7 +25,7 @@ jobs:
         if: ${{ github.event_name == 'release' }}
         shell: bash
         run: |
-          TAG="${GITHUB_REF#refs/heads/}"
+          TAG="${GITHUB_REF#refs-tags/}"
           TAG="${TAG/\//-}"
           mkdir -p doxygen/docs/versions
           sudo mv doxygen/docs/html doxygen/docs/versions/${TAG}

CHANGELOG.md

@@ -1,12 +1,43 @@
 # CHANGELOG
 
 Release Versions:
+- [4.1.0](#410)
 - [4.0.0](#400)
 - [3.1.0](#310)
 - [3.0.0](#300)
 - [2.0.0](#200)
 - [1.0.0](#100)
 
+## 4.1.0
+
+Version 4.1.0 contains a few improvements to the behaviour and usage of the libraries,
+namely to the Python bindings and the `clproto` serialization library.
+
+### Fixes and improvements
+
+**clproto**
+- JSON conversion support for clproto (#205)
+- Support empty state objects in clproto (#207)
+- Add int and int array parameters (#208)
+- Add build testing option to clproto install (#216)
+- Fix the field size type for clproto pack_fields (#222)
+
+**python**
+- Python bindings for clproto (#204)
+- Add Python bindings for Parameter class (#209)
+- Add possibility to have a ssh server for Python testing (#211)
+- Add Python bindings for clproto encode / decode of Parameter class (#214)
+
+**state_representation**
+- Add method to get a joint state by name or index of the joint,
+  and to get the index of the joint by its name (#210)
+- Improve CartesianState tests in C++ and Python (#213)
+- Add method to set a joint state by name or index of the joint (#217)
+- Add the `set_timestamp` method to the `State` base class (#218)
+
+**general**
+- Add proto Dockerfile to copy protobuf files from (#221)
+
 ## 4.0.0
 
 Version 4.0.0 introduces some powerful new features for using `state_representation` objects

Dockerfile.base

@@ -50,7 +50,6 @@ RUN rm -rf /tmp/*
 
 
 FROM core-build-dependencies as google-dependencies
-ENV PROTOBUF_VERSION 3.17.0
 
 RUN apt-get update && apt-get install -y \
     libgtest-dev \
@@ -63,19 +62,6 @@ RUN cmake /usr/src/gtest \
     && make \
     && cp lib/* /usr/local/lib || cp *.a /usr/local/lib
 
-# install protobuf
-WORKDIR /tmp
-RUN wget -O protobuf-cpp-"${PROTOBUF_VERSION}".tar.gz \
-    https://github.com/protocolbuffers/protobuf/releases/download/v"${PROTOBUF_VERSION}"/protobuf-cpp-"${PROTOBUF_VERSION}".tar.gz \
-    && tar -xzf protobuf-cpp-"${PROTOBUF_VERSION}".tar.gz \
-    && rm protobuf-cpp-"${PROTOBUF_VERSION}".tar.gz
-
-WORKDIR /tmp/protobuf-"${PROTOBUF_VERSION}"
-RUN ./autogen.sh \
-    &&./configure \
-    && make \
-    && make install
-
 WORKDIR /home
 RUN rm -rf /tmp/*
 
@@ -103,8 +89,8 @@ RUN pip3 install numpy setuptools pybind11
 
 # install google dependencies
 COPY --from=google-dependencies /usr/include/gtest /usr/include/gtest
-COPY --from=google-dependencies /usr/local/include/google /usr/local/include/google
+COPY --from=ghcr.io/epfl-lasa/control-libraries/proto-dependencies /usr/local/include/google /usr/local/include/google
 COPY --from=google-dependencies /usr/local/lib/libgtest* /usr/local/lib/
-COPY --from=google-dependencies /usr/local/lib/libproto* /usr/local/lib/
-COPY --from=google-dependencies /usr/local/bin/protoc /usr/local/bin
+COPY --from=ghcr.io/epfl-lasa/control-libraries/proto-dependencies /usr/local/lib/libproto* /usr/local/lib/
+COPY --from=ghcr.io/epfl-lasa/control-libraries/proto-dependencies /usr/local/bin/protoc /usr/local/bin
 RUN ldconfig

Dockerfile.proto

@@ -0,0 +1,32 @@
+FROM ubuntu:20.04 AS build-stage
+ARG PROTOBUF_VERSION=3.17.0
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y \
+    autoconf \
+    cmake \
+    g++ \
+    gcc \
+    libtool \
+    make \
+    wget \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /tmp
+RUN wget -O protobuf-cpp-"${PROTOBUF_VERSION}".tar.gz \
+    https://github.com/protocolbuffers/protobuf/releases/download/v"${PROTOBUF_VERSION}"/protobuf-cpp-"${PROTOBUF_VERSION}".tar.gz \
+    && tar -xzf protobuf-cpp-"${PROTOBUF_VERSION}".tar.gz \
+    && rm protobuf-cpp-"${PROTOBUF_VERSION}".tar.gz
+
+WORKDIR /tmp/protobuf-"${PROTOBUF_VERSION}"
+RUN ./autogen.sh \
+    && ./configure \
+    && make \
+    && make install
+
+FROM ubuntu:20.04 AS google-dependencies
+COPY --from=build-stage /usr/local/include/google /usr/local/include/google
+COPY --from=build-stage /usr/local/lib/libproto* /usr/local/lib/
+COPY --from=build-stage /usr/local/bin/protoc /usr/local/bin
+RUN ldconfig

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         = 4.0.0
+PROJECT_NUMBER         = 4.1.0
 
 # 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,8 +1,9 @@
 cmake_minimum_required(VERSION 3.9)
-project(clproto VERSION 4.0.0)
+project(clproto VERSION 4.1.0)
 
 set(CMAKE_CXX_STANDARD 17)
 
+include(FindProtobuf)
 find_package(Protobuf REQUIRED)
 find_package(Eigen3 REQUIRED)
 find_library(state_representation REQUIRED)
@@ -38,7 +39,7 @@ add_library(${PROJECT_NAME} SHARED
 )
 target_include_directories(${PROJECT_NAME} PUBLIC ${PROJECT_SOURCE_DIR}/include)
 set_target_properties(${PROJECT_NAME} PROPERTIES PUBLIC_HEADER ${PROJECT_SOURCE_DIR}/include/clproto.h)
-target_link_libraries(${PROJECT_NAME} PUBLIC protobuf state_representation PRIVATE ${PROJECT_NAME}_bindings)
+target_link_libraries(${PROJECT_NAME} PUBLIC ${PROTOBUF_LIBRARY} state_representation PRIVATE ${PROJECT_NAME}_bindings)
 
 install(TARGETS ${PROJECT_NAME}
     PUBLIC_HEADER DESTINATION include

protocol/clproto_cpp/README.md

@@ -80,14 +80,14 @@ clproto::pack_fields(encoded_robot_state, encoded_packet_buffer);
 
 // The message fields can also be packed into a std::string,
 // provided that sufficient space is reserved for all messages
-std::string encoded_packet_str();
+std::string encoded_packet_str;
 encoded_packet_str.reserve(2 * CLPROTO_PACKING_MAX_FIELD_LENGTH);
 clproto::pack_fields(encoded_robot_state, encoded_packet_str.data());
 
 // Unpack a combined message packet back into an ordered vector of encoded state variables
-std::vector<std::string> unpacked_encoded_robot_state = clproto::unpack(encoded_packet_buffer);
+std::vector<std::string> unpacked_encoded_robot_state = clproto::unpack_fields(encoded_packet_buffer);
 // (or, for a string type encoded packet:)
-unpacked_encoded_robot_state = clproto::unpack(encoded_packet_str.c_str());
+unpacked_encoded_robot_state = clproto::unpack_fields(encoded_packet_str.c_str());
 
 // Finally, decode the encoded fields in the same order as the original packing
 auto decoded_cart_state = clproto::decode<CartesianState>(unpacked_encoded_robot_state.at(0));
@@ -137,10 +137,10 @@ If bandwidth is limited, the following formula can be used to calculate the mini
 ```c++
 std::vector<std::string> encoded_fields = ...;
 
-// The packet header starts with N + 1 values of size proto::field_length_t,
+// The packet header starts with N + 1 values of size clproto::field_length_t,
 // where N is the number of fields N. The first value stores the number of fields,
 // while the following N values store the data length of each respective field.
-std::size_t packet_size = sizeof(proto::field_length_t) * (encoded_fields.size() + 1);
+std::size_t packet_size = sizeof(clproto::field_length_t) * (encoded_fields.size() + 1);
 
 // Add the size of each field
 for (const auto& field : encoded_fields) {

protocol/clproto_cpp/include/clproto.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <cstdint>
+#include <chrono>
 #include <stdexcept>
 #include <string>
 #include <vector>
@@ -19,7 +21,14 @@ namespace clproto {
  * and field data length in ::pack_fields() and
  * ::unpack_fields() methods
  */
-typedef std::size_t field_length_t;
+typedef uint32_t field_length_t;
+
+/**
+ * @typedef timestamp_duration_t
+ * @brief Duration type to use when representing
+ * chrono timestamps as integer count since epoch
+ */
+typedef std::chrono::nanoseconds timestamp_duration_t;
 
 /**
  * @class DecodingException
@@ -31,6 +40,16 @@ class DecodingException : public std::runtime_error {
   explicit DecodingException(const std::string& msg);
 };
 
+/**
+ * @class JsonParsingException
+ * @brief A JsonParsingException is raised whenever a
+ * JSON conversion operation fails due to invalid encoding.
+ */
+class JsonParsingException : public std::runtime_error {
+public:
+  explicit JsonParsingException(const std::string& msg);
+};
+
 /**
  * @enum MessageType
  * @brief The MessageType enumeration contains the possible
@@ -71,6 +90,8 @@ enum MessageType {
  */
 enum ParameterMessageType {
   UNKNOWN_PARAMETER = 0,
+  INT = 9,
+  INT_ARRAY = 10,
   DOUBLE = 1,
   DOUBLE_ARRAY = 2,
   BOOL = 3,
@@ -118,9 +139,9 @@ std::string encode(const T& obj);
 /**
  * @brief Decode a serialized binary string from
  * wire format into a control libraries object instance.
- * Throws an exception if the message cannot be decoded
+ * @details Throws an exception if the message cannot be decoded
  * into the desired type.
- * @tparam The desired control libraries object type
+ * @tparam T The desired control libraries object type
  * @param msg The serialized binary string to decode
  * @return A new instance of the control libraries object
  */
@@ -130,7 +151,7 @@ T decode(const std::string& msg);
 /**
  * @brief Exception safe decoding of a serialized binary string
  * wire format into a control libraries object instance.
- * It modifies the object by reference if the decoding is
+ * @details It modifies the object by reference if the decoding is
  * successful, and leaves it unmodified otherwise.
  * @tparam T The desired control libraries object type
  * @param msg The serialized binary string to decode
@@ -168,4 +189,47 @@ void pack_fields(const std::vector<std::string>& fields, char* data);
  */
 std::vector<std::string> unpack_fields(const char* data);
 
+/**
+ * @brief Convert a serialized binary string from
+ * wire format into a JSON formatted state message description.
+ * @param msg The serialized binary string to decode
+ * @return The JSON formatted state message description
+ */
+std::string to_json(const std::string& msg);
+
+/**
+ * @brief Convert a control libraries object into
+ * into a JSON formatted state message description.
+ * @tparam T The provided control libraries object type
+ * @param obj The control libraries object to encode
+ * @return The JSON formatted state message description
+ */
+template<typename T>
+std::string to_json(const T& obj) {
+  return to_json(encode<T>(obj));
+}
+
+/**
+ * @brief Convert a JSON formatted state message description
+ * into a serialized binary string representation (wire format).
+ * @details Throws an exception if the message cannot be decoded
+ * into the desired type.
+ * @param json The JSON formatted state message description
+ * @return The serialized binary string encoding
+ */
+std::string from_json(const std::string& json);
+
+/**
+ * @brief Convert a JSON formatted state message description
+ * into a control libraries object instance.
+ * @details Throws an exception if the message cannot be
+ * converted into the desired type.
+ * @tparam T The desired control libraries object type
+ * @param json The JSON formatted state message description
+ * @return A new instance of the control libraries object
+ */
+template<typename T>
+T from_json(const std::string& json) {
+  return decode<T>(from_json(json));
+}
 }

protocol/clproto_cpp/include/clproto/encoders.h

@@ -9,6 +9,7 @@
 #include <state_representation/robot/JointState.hpp>
 #include <state_representation/parameters/Parameter.hpp>
 
+#include "clproto.h"
 #include "state_representation/state_message.pb.h"
 
 namespace clproto {