diff --git a/docs/_static/css/is_theme.css b/docs/_static/css/is_theme.css index b252eae..f5cb679 100644 --- a/docs/_static/css/is_theme.css +++ b/docs/_static/css/is_theme.css @@ -71,6 +71,10 @@ src:url("Fonts/742885/39974d8a-38de-4853-a4d1-778234a08061.eot?#iefix") format(" text-align: justify !important; } +.wy-menu-vertical { + width: 320px; +} + /* Centering figures captions */ .figure.align-center .caption{ text-align: center !important; diff --git a/docs/api_reference/ros2_sh/api_is_ros2_sh.rst b/docs/api_reference/ros2_sh/api_is_ros2_sh.rst index e4497ad..bea1859 100644 --- a/docs/api_reference/ros2_sh/api_is_ros2_sh.rst +++ b/docs/api_reference/ros2_sh/api_is_ros2_sh.rst @@ -1,13 +1,15 @@ .. _api_is_ros2_sh: -ROS 2 System Handle -------------------- +ROS 2 System Handles +-------------------- This section presents the API provided by the *Integration Service* :code:`is-ros2` library. +This library contains two different implementations: :code:`static` and :code:`dynamic`, each one with a different API. +That's why this section will be divided into two parts: + .. toctree:: :maxdepth: 1 - factory - metapublisher - systemhandle + static/api_is_ros2_static_sh + dynamic/api_is_ros2_dynamic_sh diff --git a/docs/api_reference/ros2_sh/dynamic/api_is_ros2_dynamic_sh.rst b/docs/api_reference/ros2_sh/dynamic/api_is_ros2_dynamic_sh.rst new file mode 100644 index 0000000..dc414d2 --- /dev/null +++ b/docs/api_reference/ros2_sh/dynamic/api_is_ros2_dynamic_sh.rst @@ -0,0 +1,15 @@ +.. _api_is_ros2_dynamic_sh: + +Dynamic ROS 2 System Handle +--------------------------- + +This section presents the API provided by the *Integration Service* :code:`is-ros2` library when +the *Dynamic ROS 2 System Handle* is used. + +.. toctree:: + :maxdepth: 1 + + ros2middlewareexception + participant + publisher + subscriber diff --git a/docs/api_reference/ros2_sh/dynamic/participant.rst b/docs/api_reference/ros2_sh/dynamic/participant.rst new file mode 100644 index 0000000..98233ed --- /dev/null +++ b/docs/api_reference/ros2_sh/dynamic/participant.rst @@ -0,0 +1,10 @@ +.. _api_ros2_dyancmic_sh_participant: + +.. rst-class:: api-ref + +Participant +----------- + +.. doxygenclass:: eprosima::is::sh::ros2::Participant + :project: ROS2-SH + :members: diff --git a/docs/api_reference/ros2_sh/dynamic/publisher.rst b/docs/api_reference/ros2_sh/dynamic/publisher.rst new file mode 100644 index 0000000..5b6b7c0 --- /dev/null +++ b/docs/api_reference/ros2_sh/dynamic/publisher.rst @@ -0,0 +1,10 @@ +.. _api_ros2_dynamic_sh_publisher: + +.. rst-class:: api-ref + +Publisher +--------- + +.. doxygenclass:: eprosima::is::sh::ros2::Publisher + :project: ROS2-SH + :members: diff --git a/docs/api_reference/ros2_sh/dynamic/ros2middlewareexception.rst b/docs/api_reference/ros2_sh/dynamic/ros2middlewareexception.rst new file mode 100644 index 0000000..4ceb2b5 --- /dev/null +++ b/docs/api_reference/ros2_sh/dynamic/ros2middlewareexception.rst @@ -0,0 +1,10 @@ +.. _api_ros2_dynamic_sh_ros2middlewareexception: + +.. rst-class:: api-ref + +ROS2MiddlewareException +----------------------- + +.. doxygenclass:: eprosima::is::sh::ros2::ROS2MiddlewareException + :project: ROS2-SH + :members: diff --git a/docs/api_reference/ros2_sh/dynamic/subscriber.rst b/docs/api_reference/ros2_sh/dynamic/subscriber.rst new file mode 100644 index 0000000..8afa2fe --- /dev/null +++ b/docs/api_reference/ros2_sh/dynamic/subscriber.rst @@ -0,0 +1,10 @@ +.. _api_ros2_dynamic_sh_subscriber: + +.. rst-class:: api-ref + +Subscriber +---------- + +.. doxygenclass:: eprosima::is::sh::ros2::Subscriber + :project: ROS2-SH + :members: diff --git a/docs/api_reference/ros2_sh/static/api_is_ros2_static_sh.rst b/docs/api_reference/ros2_sh/static/api_is_ros2_static_sh.rst new file mode 100644 index 0000000..12d0297 --- /dev/null +++ b/docs/api_reference/ros2_sh/static/api_is_ros2_static_sh.rst @@ -0,0 +1,14 @@ +.. _api_is_ros2_static_sh: + +Static ROS 2 System Handle +-------------------------- + +This section presents the API provided by the *Integration Service* :code:`is-ros2` library when the +*Static ROS 2 System Handle* is used. + +.. toctree:: + :maxdepth: 1 + + factory + metapublisher + systemhandle diff --git a/docs/api_reference/ros2_sh/factory.rst b/docs/api_reference/ros2_sh/static/factory.rst similarity index 100% rename from docs/api_reference/ros2_sh/factory.rst rename to docs/api_reference/ros2_sh/static/factory.rst diff --git a/docs/api_reference/ros2_sh/metapublisher.rst b/docs/api_reference/ros2_sh/static/metapublisher.rst similarity index 100% rename from docs/api_reference/ros2_sh/metapublisher.rst rename to docs/api_reference/ros2_sh/static/metapublisher.rst diff --git a/docs/api_reference/ros2_sh/systemhandle.rst b/docs/api_reference/ros2_sh/static/systemhandle.rst similarity index 100% rename from docs/api_reference/ros2_sh/systemhandle.rst rename to docs/api_reference/ros2_sh/static/systemhandle.rst diff --git a/docs/examples/different_protocols/pubsub/dds-ros2.rst b/docs/examples/different_protocols/pubsub/dds-ros2.rst index 016e19f..8caf493 100644 --- a/docs/examples/different_protocols/pubsub/dds-ros2.rst +++ b/docs/examples/different_protocols/pubsub/dds-ros2.rst @@ -31,7 +31,7 @@ Also, to get this example working, the following requirements must be met: * Having **ROS 2** (*Foxy* or superior) installed, with the :code:`talker-listener` example working. -* Having the **ROS 2 System Handle** installed. You can download it from the +* Having the **Static ROS 2 System Handle** installed. You can download it from the `ROS2-SH dedicated repository `_ into the :code:`is-workspace` where you have *Integration Service* installed: diff --git a/docs/examples/different_protocols/pubsub/fiware-ros2.rst b/docs/examples/different_protocols/pubsub/fiware-ros2.rst index 6739d4c..2064ef5 100644 --- a/docs/examples/different_protocols/pubsub/fiware-ros2.rst +++ b/docs/examples/different_protocols/pubsub/fiware-ros2.rst @@ -25,7 +25,7 @@ Also, to get this example working, the following requirements must be met: * Having **ROS 2** (*Foxy* or superior) installed, with the :code:`talker-listener` example working. -* Having the **ROS 2 System Handle** installed. You can download it from the +* Having the **Static ROS 2 System Handle** installed. You can download it from the `ROS2-SH dedicated repository `_ into the :code:`is-workspace` where you have *eProsima Integration Service* installed: diff --git a/docs/examples/different_protocols/pubsub/ros1-ros2.rst b/docs/examples/different_protocols/pubsub/ros1-ros2.rst index 62b47be..3b51403 100644 --- a/docs/examples/different_protocols/pubsub/ros1-ros2.rst +++ b/docs/examples/different_protocols/pubsub/ros1-ros2.rst @@ -7,7 +7,7 @@ Another typical situation of systems using different protocols is that of *ROS 1* and *ROS 2*. By using *Integration Service*, this communication can be achieved with minimum user's effort. -As both a **ROS 1 System Handle** and a *ROS 2 System Handle* already exist, the communication is straightforward. +As both a **ROS 1 System Handle** and a *Static ROS 2 System Handle* already exist, the communication is straightforward. In the example below, we show how *Integration Service* puts into communication two :code:`pub-echo` examples, one from *ROS 2*, and the other from *ROS 1*. @@ -27,7 +27,7 @@ Also, to get this example working, the following requirements must be met: * Having **ROS 2** (*Foxy* or superior) installed, with the :code:`talker-listener` example working. -* Having the **ROS 2 System Handle** installed. You can download it from the +* Having the **Static ROS 2 System Handle** installed. You can download it from the `ROS2-SH dedicated repository `_ into the :code:`is-workspace` where you have *Integration Service* installed: diff --git a/docs/examples/different_protocols/pubsub/ros2-websocket.rst b/docs/examples/different_protocols/pubsub/ros2-websocket.rst index 1fdac60..5db765a 100644 --- a/docs/examples/different_protocols/pubsub/ros2-websocket.rst +++ b/docs/examples/different_protocols/pubsub/ros2-websocket.rst @@ -24,7 +24,7 @@ Also, to get this example working, the following requirements must be met: * Having **ROS 2** (*Foxy* or superior) installed, with the :code:`talker-listener` example working. -* Having the **ROS 2 System Handle** installed. You can download it from the +* Having the **Static ROS 2 System Handle** installed. You can download it from the `ROS2-SH dedicated repository `_ into the :code:`is-workspace` where you have *Integration Service* installed: .. code-block:: bash diff --git a/docs/examples/different_protocols/services/dds-server.rst b/docs/examples/different_protocols/services/dds-server.rst index a768814..d638f61 100644 --- a/docs/examples/different_protocols/services/dds-server.rst +++ b/docs/examples/different_protocols/services/dds-server.rst @@ -80,7 +80,7 @@ Also, to get this example working, the following requirements must be met: apt install ros-$-example-interfaces -* Having the **ROS 2 System Handle** installed. You can download it from the +* Having the **Static ROS 2 System Handle** installed. You can download it from the `ROS2-SH dedicated repository `_ into the :code:`is-workspace` where you have *Integration Service* installed: diff --git a/docs/examples/different_protocols/services/ros1-server.rst b/docs/examples/different_protocols/services/ros1-server.rst index 87e4f7d..d8d2deb 100644 --- a/docs/examples/different_protocols/services/ros1-server.rst +++ b/docs/examples/different_protocols/services/ros1-server.rst @@ -82,7 +82,7 @@ Also, to get this example working, the following requirements must be met: apt install ros-$-example-interfaces -* Having the **ROS 2 System Handle** installed. You can download it from the +* Having the **Static ROS 2 System Handle** installed. You can download it from the `ROS2-SH dedicated repository `_ into the :code:`is-workspace` where you have *Integration Service* installed: diff --git a/docs/examples/different_protocols/services/ros2-server.rst b/docs/examples/different_protocols/services/ros2-server.rst index 795eb26..dbd828b 100644 --- a/docs/examples/different_protocols/services/ros2-server.rst +++ b/docs/examples/different_protocols/services/ros2-server.rst @@ -81,7 +81,7 @@ Also, to get this example working, the following requirements must be met: apt install ros-$-demo-nodes-cpp -* Having the **ROS 2 System Handle** installed. You can download it from the +* Having the **Static ROS 2 System Handle** installed. You can download it from the `ROS2-SH dedicated repository `_ into the :code:`is-workspace` where you have *Integration Service* installed: diff --git a/docs/examples/different_protocols/services/websocket-server.rst b/docs/examples/different_protocols/services/websocket-server.rst index 62327a0..dd8f60b 100644 --- a/docs/examples/different_protocols/services/websocket-server.rst +++ b/docs/examples/different_protocols/services/websocket-server.rst @@ -80,7 +80,7 @@ Also, to get this example working, the following requirements must be met: apt install ros-$-example-interfaces -* Having the **ROS 2 System Handle** installed. You can download it from the +* Having the **Static ROS 2 System Handle** installed. You can download it from the `ROS2-SH dedicated repository `_ into the :code:`is-workspace` where you have *Integration Service* installed: diff --git a/docs/examples/same_protocol/ros2_change_domain.rst b/docs/examples/same_protocol/ros2_change_domain.rst index 4acc887..f0b8bcb 100644 --- a/docs/examples/same_protocol/ros2_change_domain.rst +++ b/docs/examples/same_protocol/ros2_change_domain.rst @@ -25,7 +25,7 @@ Also, to get this example working, the following requirements must be met: * Having **ROS 2** (*Foxy* or superior) installed, with the :code:`talker-listener` example working. -* Having the **ROS 2 System Handle** installed. You can download it from the `dedicated repository `_ +* Having the **Static ROS 2 System Handle** installed. You can download it from the `dedicated repository `_ into the :code:`is-workspace` where you have *Integration Service* installed: .. code-block:: bash diff --git a/docs/examples/wan_communication/wan_tcp_dds.rst b/docs/examples/wan_communication/wan_tcp_dds.rst index 3497813..c9f98ba 100644 --- a/docs/examples/wan_communication/wan_tcp_dds.rst +++ b/docs/examples/wan_communication/wan_tcp_dds.rst @@ -47,7 +47,7 @@ Also, to get this example working, the following requirements must be met in bot * Having **ROS 2** (*Foxy* or superior) installed, with the :code:`talker-listener` example working. -* Having the **ROS 2 System Handle** installed. You can download it from the +* Having the **Static ROS 2 System Handle** installed. You can download it from the `ROS2-SH dedicated repository `_ into the :code:`is-workspace` where you have *Integration Service* installed: .. code-block:: bash diff --git a/docs/installation_manual/external_dep.rst b/docs/installation_manual/external_dep.rst index d84058d..db1c927 100644 --- a/docs/installation_manual/external_dep.rst +++ b/docs/installation_manual/external_dep.rst @@ -115,7 +115,7 @@ The *ROS 1 System Handle* has the following requirements: :raw-html:`

ROS 2 System Handle

` -The *ROS 2 System Handle* has the following requirements: +The *Static ROS 2 System Handle* has the following requirements: .. list-table:: :header-rows: 1 @@ -129,6 +129,19 @@ The *ROS 2 System Handle* has the following requirements: - `Foxy installation guide `_ :raw-html:`
` `Galactic installation guide `_ +The *Dynamic ROS 2 System Handle* has the following requirements: + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - Dependency + - Description + - Installation + * - `FastDDS (v2.0.0 or superior) `_ + - eProsima C++ implementation for *DDS*. + - `Binaries installation guide `_ :raw-html:`
` + `Sources installation guide `_ :raw-html:`

WebSocket System Handle

` diff --git a/docs/introduction.rst b/docs/introduction.rst index 2ee2b13..3e2f897 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -73,7 +73,7 @@ Available *System Handles* up-to-date are listed below: - https://github.com/eProsima/FIWARE-SH * - **ROS 1 System Handle** - https://github.com/eProsima/ROS1-SH - * - **ROS 2 System Handle** + * - **ROS 2 System Handles** - https://github.com/eProsima/ROS2-SH * - **WebSocket System Handle** - https://github.com/eProsima/WebSocket-SH diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index f8bf6f0..9c06014 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -40,6 +40,7 @@ Noetic nullptr ostream parameterizable +preprocess preprocessor QoS remappings diff --git a/docs/user_manual/systemhandle/ros1_sh.rst b/docs/user_manual/systemhandle/ros1_sh.rst index f61784a..5c111ef 100644 --- a/docs/user_manual/systemhandle/ros1_sh.rst +++ b/docs/user_manual/systemhandle/ros1_sh.rst @@ -89,7 +89,7 @@ whole *Integration Service* product suite, there are some specific flags which a * :code:`MIX_ROS_PACKAGES`: It accepts as an argument a list of `ROS packages `_, such as :code:`std_msgs`, :code:`geometry_msgs`, :code:`sensor_msgs`, :code:`nav_msgs`... for which the required transformation library to convert the specific *ROS 1* type definitions into *xTypes*, - and the other way around, will be built. This list is shared with the `ROS 2 System Handle `_, + and the other way around, will be built. This list is shared with the `Static ROS 2 System Handle `_, meaning that the ROS packages specified in the `MIX_ROS_PACKAGES` variable will also be built for *ROS 2* if the corresponding *System Handle* is present within the *Integration Service* workspace. To avoid possible errors, if a certain package is only present in *ROS 1*, @@ -114,7 +114,7 @@ whole *Integration Service* product suite, there are some specific flags which a allowing to compile specific *ROS 1* packages independently. For example, if a user wants to compile a certain package `dummy_msgs` independently from *ROS 1*, - but compiling `std_msgs` and `geometry_msgs` for both the *ROS 1* and *ROS 2 System Handles*, + but compiling `std_msgs` and `geometry_msgs` for both the *ROS 1* and *Static ROS 2 System Handle*, the following command should be executed: .. code-block:: bash diff --git a/docs/user_manual/systemhandle/ros2_sh.rst b/docs/user_manual/systemhandle/ros2_sh.rst index ad270da..4b39251 100644 --- a/docs/user_manual/systemhandle/ros2_sh.rst +++ b/docs/user_manual/systemhandle/ros2_sh.rst @@ -1,30 +1,50 @@ .. _ros2_sh: -ROS 2 System Handle -=================== +ROS 2 System Handles +==================== -The *ROS 2 System Handle* can be used for two main purposes: +The *ROS 2 System Handles* can be used for two main purposes: * Connection between a *ROS 2* application and an application running over a different middleware implementation. This is the classic use-case for *Integration Service*. * Connecting two *ROS 2* applications running under different Domain IDs. +Two implementations can be distinguished: *static* one based on *ROS 2* :code:`rclcpp` and *dynamic* one based on *Fast DDS* +(by the moment it is only available for the Publisher-Subscriber paradigm). + +The main advantages of the *Dynamic ROS 2 System Handle* over the *Static ROS 2 System Handle* are the following ones: + +* It allows using types defined by *IDL* without previously generating and installing the *ROS 2 Type Support* for that type, + which gives it a greater versatility with respect to the *Static ROS 2 System Handle*. + +* It is not necessary to decide which *ROS 2 Built-in Types* you are going to use during the compilation phase, + as it allows you to use any of them. + + Dependencies ^^^^^^^^^^^^ -The only dependency of this *System Handle* is to have a ROS 2 installation (`Foxy `_ or superior) in your system. +Depending on the *ROS 2 System Handle* mode that wants to be used the list of dependencies varies. + +**Static ROS 2 System Handle** + + The only dependency is to have a ROS 2 installation (`Foxy `_ or superior) in your system. + +**Dynamic ROS 2 System Handle** + + The only dependency is to have a `Fast DDS installation `_ (v2.0.0 or superior) in your system. Configuration ^^^^^^^^^^^^^ -Regarding the *ROS 2 System Handle*, there are several specific parameters which can be configured +Regarding the *ROS 2 System Handles*, there are several specific parameters which can be configured for the *ROS 2* middleware. All of these parameters are optional, and are suboptions of the main five sections: * :code:`systems`: The system :code:`type` must be :code:`ros2`. In addition to the :code:`type` and :code:`types-from` fields, - the *ROS 2 System Handle* accepts the following specific configuration fields: + the *ROS 2 System Handles* accept the following specific configuration fields: .. code-block:: yaml @@ -42,11 +62,25 @@ five sections: * :code:`domain`: Provides with an easy way to change the *Domain ID* of the ROS 2 entities created by the *ROS 2 System Handle*. + The *Dynamic ROS 2 System Handle* has an additional parameter: + + .. code-block:: yaml + + systems: + ros2: + type: ros2 + namespace: "/" + node_name: "my_ros2_node" + domain: 4 + using: [std_msgs/String, geometry_msgs] + + * :code:`using`: List of the *ROS 2* Built-in types or packages that want to be used in the communication. + Examples ^^^^^^^^ There are several examples that you can find in this documentation in which the -*ROS 2 System Handle* is employed in the communication process. Some of them are presented here: +*Static ROS 2 System Handle* is employed in the communication process. Some of them are presented here: * :ref:`ros1_ros2_bridge_pubsub` * :ref:`dds_ros2_bridge_pubsub` @@ -63,7 +97,7 @@ Compilation flags Besides the :ref:`global_compilation_flags` available for the whole *Integration Service* product suite, there are some specific flags which apply only to the -*ROS 2 System Handle*; they are listed below: +*ROS 2 System Handles*; they are listed below: * :code:`BUILD_ROS2_TESTS`: Allows to specifically compile the *ROS 2 System Handle* unitary and integration tests. It is useful to avoid compiling each *System Handle*'section test suite present @@ -80,6 +114,12 @@ whole *Integration Service* product suite, there are some specific flags which a the compilation environment; this means that if the last *ROS* environment sourced corresponds to *ROS 1*, the compilation process will stop and warn the user about it. +* :code:`IS_ROS2_SH_MODE`: This flag is to decide which *ROS 2 System Handle* mode will be compiled, as the + static and dynamic modes are exclusive which means that they cannot be compiled at the same time. + It accepts two different values: :code:`static` or :code:`dynamic`. + +The following flags are only applicable for the *Static ROS 2 System Handle*: + * :code:`MIX_ROS_PACKAGES`: It accepts as an argument a list of `ROS packages `_, such as :code:`std_msgs`, :code:`geometry_msgs`, :code:`sensor_msgs`, :code:`nav_msgs`... for which the required transformation library to convert the specific *ROS 2* type definitions into *xTypes*, @@ -108,7 +148,7 @@ whole *Integration Service* product suite, there are some specific flags which a allowing to compile specific *ROS 2* packages independently. For example, if a user wants to compile a certain package `dummy_msgs` independently from *ROS 2*, - but compiling `std_msgs` and `geometry_msgs` for both the *ROS 1* and *ROS 2 System Handles*, + but compiling `std_msgs` and `geometry_msgs` for both the *ROS 1* and *Static ROS 2 System Handle*, the following command should be executed: .. code-block:: bash diff --git a/docs/user_manual/yaml_config.rst b/docs/user_manual/yaml_config.rst index 8f30277..7c552ba 100644 --- a/docs/user_manual/yaml_config.rst +++ b/docs/user_manual/yaml_config.rst @@ -38,6 +38,7 @@ an *Integration Service* instance, while others are optional. Both kinds are lis idls: - > #include + struct HelloWorld { string data; @@ -74,8 +75,8 @@ an *Integration Service* instance, while others are optional. Both kinds are lis In relation to the common parameters, their behavior is explained in the following section: - * :code:`type`: Middleware or protocol kind. To date, the supported middlewares are: *fastdds*, *ros1*, *ros2*, *fiware*, *websocket_server* and *websocket_client*. - There is also a *mock* option, mostly used for testing purposes. + * :code:`type`: Middleware or protocol kind. To date, the supported middlewares are: *fastdds*, *ros1*, *ros2*, *ros2_dynamic*, + *fiware*, *websocket_server* and *websocket_client*. There is also a *mock* option, mostly used for testing purposes. * :code:`types-from` *(optional)*: Configures the types inheritance from a given system to another. This allows to use types defined within *Middleware Interface Extension* files for a certain middleware into another middleware, @@ -320,7 +321,7 @@ If :code:`type` is omitted, the key of the *YAML* entry will be used as :code:`t The snippet above will create three *System Handles* instances: * A *DDS System Handle* instance, with default configuration. -* A *ROS 2 System Handle* instance, named :code:`ros2_domain` with :code:`domain = 5` and +* A *Static ROS 2 System Handle* instance, named :code:`ros2_domain` with :code:`domain = 5` and :code:`node_name = "is_5"`. * A *FIWARE System Handle* instance, with :code:`host = 192.168.1.59` and :code:`port = 1026`.