Update to v2.1.0 (#69)

* Update to v2.1.0 Signed-off-by: Pablo Garrido <pablogs9@gmail.com> * Release notes Signed-off-by: Pablo Garrido <pablogs9@gmail.com> * Update binary API Signed-off-by: Pablo Garrido <pablogs9@gmail.com> * Lock prepares Signed-off-by: Pablo Garrido <pablogs9@gmail.com> * Update ping API Signed-off-by: Pablo Garrido <pablogs9@gmail.com> * Add stop agent API * Update agent.rst * Update CAN client * Minor changes * Bump version Signed-off-by: Pablo Garrido <pablogs9@gmail.com> Co-authored-by: acuadros95 <acuadros1995@gmail.com>
eProsima · Dec 9, 2021 · 0678376 · 0678376
1 parent cf96f46
commit 0678376
Show file tree

Hide file tree

Showing 8 changed files with 472 additions and 51 deletions.
diff --git a/docs/agent.rst b/docs/agent.rst
@@ -12,7 +12,7 @@ The *Agents* receive messages containing operations from the *Clients*, and keep
 create.
 These entities are used by the *Agents* to interact with the DDS Global Data Space on behalf of the *Clients*.
 
-The communication between a *Client* and an *Agent* currently supports UDP, TCP, Serial, and Custom transports, depending
+The communication between a *Client* and an *Agent* currently supports UDP, TCP, Serial, CAN FD, and Custom transports, depending
 on the peripherals and communication technologies offered by the platforms.
 A section dedicated to the configuration and use of the Custom Transport can be found
 at the end of this :ref:`page <custom_transport_agent>`.
@@ -71,12 +71,50 @@ Communication via Serial transport (only Linux)
         Options:
           -h,--help                                    Print the help message.
           -D,--dev FILE REQUIRED                       Specify the serial device.
+          -f,--file FILE REQUIRED                      Specify a text file with the serial device name.
+          -b,--baudrate TEXT=115200                    Select the baudrate.
+          -m,--middleware TEXT in {ced,rtps,dds}=dds   Select the kind of middleware among the supported ones. By default, it will be FastDDS.
+          -r,--refs FILEPATH                           Load a references file from the given path.
+          -v,--verbose UINT in {0,1,2,3,4,5,6}=4       Select log level from none (0) to full verbosity (6).
+
+.. note::
+    The *Agent* will check and wait for the proper availability of the Serial port to start the connection.
+    Its expected to start the transport with a disconnected Serial port.
+
+Communication via Multiserial transport (only Linux)
+    This transport allows multiple serial connections on the same *Agent* instance.
+    The communication via Multiserial transport can be executed and configured as follows: ::
+
+        $ ./MicroXRCEAgent multiserial [OPTIONS]
+
+        Options:
+          -h,--help                                    Print the help message.
+          -D,--devs FILE REQUIRED                      Specify the serial devices.
+          -f,--file FILE REQUIRED                      Specify a text file with one serial device per line.
           -b,--baudrate TEXT=115200                    Select the baudrate.
           -m,--middleware TEXT in {ced,rtps,dds}=dds   Select the kind of middleware among the supported ones. By default, it will be FastDDS.
           -r,--refs FILEPATH                           Load a references file from the given path.
           -v,--verbose UINT in {0,1,2,3,4,5,6}=4       Select log level from none (0) to full verbosity (6).
-          -d,--discovery UINT=7400                     Activate the Discovery server. If no port is specified, 7400 will be used.
-          --p2p UINT                                   Activate the P2P profile, using the given port.
+
+.. note::
+    The *Agent* will check and wait for the proper availability of each Serial port to start the connection.  
+    Its expected to start the transport with multiple disconnected ports.
+
+Communication via CAN FD transport (only Linux)
+    The communication via CAN FD transport can be executed and configured as follows: ::
+
+        $ ./MicroXRCEAgent canfd [OPTIONS]
+
+        Options:
+          -h,--help                                    Print the help message.
+          -D,--dev INTERFACE REQUIRED                  Specify the CAN interface.
+          -m,--middleware TEXT in {ced,rtps,dds}=dds   Select the kind of middleware among the supported ones. By default, it will be FastDDS.
+          -r,--refs FILEPATH                           Load a references file from the given path.
+          -v,--verbose UINT in {0,1,2,3,4,5,6}=4       Select log level from none (0) to full verbosity (6).
+
+.. note::
+    The used interface must support CAN FD frames with a maximum payload of 64 bytes.
+    The agent will use the received message identifiers from each client on its output frames.
 
 Communication via pseudo terminal (only Linux)
     The communication via pseudo serial can be executed and configured as follow: ::
@@ -90,8 +128,6 @@ Communication via pseudo terminal (only Linux)
           -m,--middleware TEXT in {ced,rtps,dds}=dds   Select the kind of middleware among the supported ones. By default, it will be FastDDS.
           -r,--refs FILEPATH                           Load a references file from the given path.
           -v,--verbose UINT in {0,1,2,3,4,5,6}=4       Select log level from none (0) to full verbosity (6).
-          -d,--discovery UINT=7400                     Activate the Discovery server. If no port is specified, 7400 will be used.
-          --p2p UINT                                   Activate the P2P profile, using the given port.
 
 * The reference file shall be composed by a set of Fast DDS profiles following the
   `XML syntax <https://fast-dds.docs.eprosima.com/en/latest/fastdds/xml_configuration/xml_configuration.html>`_
@@ -107,7 +143,7 @@ Communication via pseudo terminal (only Linux)
 * The option :code:`-m,--middleware <middleware-impl>` sets the middleware implementation to use.
   There are three: RTPS (based on eProsima Fast RTPS), DDS (specified by the XRCE standard and using Fast DDS) and Centralized (topic are managed by the Agent similarly to MQTT).
   More information about the supported middlewares can be found :ref:`here <middleware_abstraction_layer>`.
-* The ``--p2p <port>`` option enables P2P communication. Centralized middleware is necessary for this option.
+* The ``--p2p <port>`` option enables P2P communication, this option is only available on network transports. Centralized middleware is necessary for this option.
 
 .. _custom_transport_agent:
 

diff --git a/docs/agent_api.rst b/docs/agent_api.rst
@@ -28,7 +28,7 @@ eprosima::uxr::AgentInstance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The CLI manager, along with all the built-in *Agents* available for the supported transports
-(UDP, TCP, Serial) are encapsulated in the ``eprosima::uxr::AgentInstance`` class.
+(UDP, TCP, Serial, CAN) are encapsulated in the ``eprosima::uxr::AgentInstance`` class.
 
 ------
 
@@ -45,7 +45,8 @@ which allows launching a *Micro XRCE-DDS Agent* with user-given parameters.
 
     bool create(int argc, char** argv);
 
-This function creates a UDP/TCP/Serial *Micro XRCE-DDS Agent*, based on the given arguments.
+This function creates a UDP/TCP/Serial/CAN *Micro XRCE-DDS Agent*, based on the given arguments.
+The created *Agent* will start automatically on success.
 
 Returns ``true`` if the arguments were valid and an *Agent* was successfully created, ``false`` otherwise.
 
@@ -57,9 +58,20 @@ Returns ``true`` if the arguments were valid and an *Agent* was successfully cre
 
 .. code-block:: cpp
 
-    bool run();
+    void run();
 
-This function starts the execution of the previously created *Agent*, until it's ended by a user's interrupt or a process error.
+This function blocks until the previously created *Agent* is ended by the stop function, a user's interrupt or a process error.
+
+------
+
+.. code-block:: cpp
+
+    void stop();
+
+Stops a previously created *Agent*, blocking until the stop process is completed.
+Note that this will trigger a call on the ``transport::fini`` method.
+
+To restart a stopped agent, the ``create`` method should be used.
 
 ------
 

diff --git a/docs/client.rst b/docs/client.rst
@@ -47,7 +47,7 @@ Best-effort streams
 Reliable streams
     Reliable streams perform the communication without loss, regardless of the transport layer used,
     and allow for message fragmentation to send and receive messages longer than the *MTU*.
-    
+
     To avoid loss of data, reliable streams use additional messages to confirm the delivery.
     Moreover, reliable streams have a history associated, used to store messages that can not be processed
     due to issues such as delivery order or incomplete fragments or messages that can not be confirmed yet.
@@ -65,9 +65,9 @@ Reliable streams
     Summarizing:
 
     * A short history causes more messages to be discarded, increasing the data traffic because they need to be sent again.
-      At the same time, it consumes less memory. 
+      At the same time, it consumes less memory.
     * A long history will reduce the traffic of confirmation messages when the loss rate is high.
-  
+
     This internal management of the communication implies that a reliable stream is more expensive than a best-effort
     stream, in both memory and bandwidth, but it is possible to play with these values using the history size.
 
@@ -108,6 +108,10 @@ discovery and framing functionalities.
         - Enables or disables the possibility to connect with the *Agent* by Serial.
         - :code:`<bool>`
         - :code:`ON`
+    *   - :code:`UCLIENT_PROFILE_CAN`
+        - Enables or disables the possibility to connect with the *Agent* by CAN FD.
+        - :code:`<bool>`
+        - :code:`OFF`
     *   - :code:`UCLIENT_PROFILE_CUSTOM_TRANSPORT`
         - Enables or disables the possibility to connect with the *Agent* by Custom Transport.
         - :code:`<bool>`
@@ -121,6 +125,14 @@ discovery and framing functionalities.
         - Enables or disables the stream framing protocol.
         - :code:`<bool>`
         - :code:`ON`
+    *   - :code:`UCLIENT_PROFILE_MULTITHREAD`
+        - Enables or disables the multithread locking operation of the library.
+        - :code:`<bool>`
+        - :code:`ON`
+    *   - :code:`UCLIENT_PROFILE_SHARED_MEMORY`
+        - Enables or disables a basic local memory transport operation between entities in the same application.
+        - :code:`<bool>`
+        - :code:`ON`
 
 Transport profiles
 ^^^^^^^^^^^^^^^^^^
@@ -134,16 +146,17 @@ with the transports supported by the *eProsima Micro XRCE-DDS Client*.
 The table below shows the current implementation.
 
 ============ ========== =========
-Transport     POSIX      Windows   
-============ ========== ========= 
-UDP           X           X        
-TCP           X           X        
-Serial        X                  
+Transport     POSIX      Windows
+============ ========== =========
+UDP           X           X
+TCP           X           X
+Serial        X
+CAN FD        X
 Custom        X           X
 ============ ========== =========
 
 Each available transport can be activated or desactivated via the opportune CMake flag:
-:code:`UCLIENT_PROFILE_<transport>`, where :code:`<transport> = UDP, TCP, SERIAL`, or
+:code:`UCLIENT_PROFILE_<transport>`, where :code:`<transport> = UDP, TCP, SERIAL, CAN`, or
 :code:`UCLIENT_PROFILE_CUSTOM_TRANSPORT` in the case Custom transport is to be used.
 
 *eProsima Micro XRCE-DDS* provides a user API that allows interfacing with the lowest level transport layer at runtime. In this way, a user is enabled to implement its own transports based on one of the two communication approaches: stream-oriented or packet-oriented.
@@ -171,6 +184,17 @@ Framing profile
 
 The framing profile enables :ref:`HDLC Framing <stream_framing_label>` for using :ref:`stream-oriented transports <intro_transport>` such as Serial transports or Custom transports that require framing.
 
+Multithread profile
+^^^^^^^^^^^^^^^
+
+The multithread profile enables the thread-safe operation with the Micro XRCE-DDS Client library. It lockguards all the critical sections of the API and allows the usage from concurrent tasks.
+
+Shared memory profile
+^^^^^^^^^^^^^^^
+
+The multithread profile enables a simple intraprocess communication. This profile is intended to be used whithin devices without memory protection units where all tasks or processes have access to the whole memory space.
+
+
 .. _configurations:
 
 Configurations
@@ -227,7 +251,7 @@ By means of these flags, the user can change the default value of all the parame
           the first heartbeat to be sent. The wait time for the next heartbeat will be |br|
           double. It is measured in milliseconds.
         - :code:`<number>`
-        - :code:`1`
+        - :code:`100`
     *   - :code:`UCLIENT_BIG_ENDIANNESS`
         - This value must correspond to the memory endianness of the device in |br|
           which the *Client* is running. :code:`OFF` implies that the machine is little-endian |br|
@@ -258,6 +282,18 @@ By means of these flags, the user can change the default value of all the parame
           internally, it corresponds to the creation of a buffer this size.
         - :code:`<number>`
         - :code:`512`
+    *   - :code:`UCLIENT_SHARED_MEMORY_MAX_ENTITIES`
+        - This value corresponds to the *Max number of entities involved in shared memory.
+        - :code:`<number>`
+        - :code:`4`
+    *   - :code:`UCLIENT_SHARED_MEMORY_STATIC_MEM_SIZE`
+        - This value corresponds to the *Max number data buffers stored in shared memory.
+        - :code:`<number>`
+        - :code:`10`
+
+.. note::
+    The MTU of the CAN transport is fixed to 64 bytes, which is the maximum payload supported by CAN FD frames.
+    Take this into account to calculate the size of the streams for the requirements of the application.
 
 .. _read_access:
 
@@ -281,8 +317,8 @@ Creation Mode: Client
 ---------------------
 
 The creation of :ref:`entities_label` on the *Agent* which can act on behalf of the *Clients*
-in the DDS world can be done in two ways: by XML, or by reference. In this section, we explain
-these two creation modes and provide guidance on their usage.
+in the DDS world can be done in three ways: by XML, by reference or by binary. In this section, we explain
+these three creation modes and provide guidance on their usage.
 
 XML
     In the XML case, when creating the entities in the *Client* application, the user must provide each :code:`entity`
@@ -293,16 +329,16 @@ XML
     For instance, when creating a *participant* or a *topic*, the profiles shall look as follows:
 
     .. code-block:: C
-    
-        <!-- PARTICIPANT -->    
+
+        <!-- PARTICIPANT -->
         const char* participant_xml = "<dds>"
                                           "<participant>"
                                               "<rtps>"
                                                   "<name>[PARTICIPANT NAME]</name>"
                                               "</rtps>"
                                           "</participant>"
                                       "</dds>";
-        
+
         <!-- TOPIC -->
         const char* topic_xml = "<dds>"
                                     "<topic>"
@@ -313,7 +349,7 @@ XML
 
     As detailed in the :ref:`getting_started_label` section, *participants*, *topics*, *datawriters*, *datareaders*, *requesters* and *repliers* work similarly.
     *Publishers* and *subscribers*, instead, inherit their XML fields from their associated *dataWriters* and *dataReaders*.
-    
+
     Creation by XML has the advantage of being configurable direclty within the *Client* application,
     but comes with the drawback of offering a very limited set of options as regards the QoS with which the DDS entities
     profiles can be configured. Indeed, only best-effort or reliable communication streams can be set with this creation mode.
@@ -324,20 +360,39 @@ References
     Creation by references happens by feeding the *Agent* with an XML profile containing a string of text similar to the snippets
     provided above, with a label associated to it. Therefore, when creating an entity, the *Client* will only need to provide a reference
     to this label in spite of the complete XML profile. This creation mode comes with two advantages:
-    
+
     - It consumes less *Client* memory, making the application more lightweight.
     - It allows the *Clients* to write their own XML QoS and run the *Agent* with a custom configuration which can benefit of the *full set* of QoS available in DDS.
 
     For instance, when creating a *participant* or a *topic*, the profiles shall look as follows:
 
     .. code-block:: C
-    
-        <!-- PARTICIPANT -->    
+
+        <!-- PARTICIPANT -->
         const char* participant_ref = "participant_label";
-        
+
         <!-- TOPIC -->
         const char* topic_ref = "topic_label"
 
+Binary
+
+    Creation by binary provides a comprehensive API in the Micro XRCE-DDS Client library that can be used to generate and send over the
+    XRCE-DDS middleware binary representations of the entities that are being created. This creation mode comes with two advantages:
+
+    - It consumes less *Client* memory than XML mode, making the application more lightweight.
+    - It provides much more flexibility than the REF mode in the client side.
+
+    For instance, when creating a *participant* or a *topic*, the profiles shall look as follows:
+
+    .. code-block:: C
+
+      uxrQoS_t qos = {
+        .reliability = UXR_RELIABILITY_RELIABLE, .durability = UXR_DURABILITY_TRANSIENT_LOCAL,
+        .history = UXR_HISTORY_KEEP_LAST, .depth = 0
+      };
+      uxr_buffer_create_topic_bin(&session, reliable_out, topic_id, participant_id, "ExampleTopic", "ExampleType", UXR_REPLACE);
+      uxr_buffer_create_datawriter_bin(&session, reliable_out, datawriter_id, publisher_id, topic_id, qos, UXR_REPLACE);
+
 Find more information in the :ref:`creation_mode_agent` section in the :ref:`micro_xrce_dds_agent_label` page.