README.md 8.91 KB
Newer Older
Florian Roth committed
1
# Documentation - ADTF3 ROS2 Bridge
Sebastian Stern committed
2

Florian Roth committed
3
This Document describes the intended usage of the code generator script to create adtfplugins (Streaming Source / Sink) which provide a bridge between ROS2 and ADTF 3.x
Sebastian Stern committed
4

Sebastian Stern committed
5
## Prerequisites
Sebastian Stern committed
6

Sebastian Stern committed
7
### Python
Sebastian Stern committed
8

Florian Roth committed
9
* Version - depends on the installed ROS2-Version
10 11
* cogapp >= 2.5.1 (MIT)
* colorama >= 0.3.9 (BSD)
12
* prettytable >= 0.7.2 (BSD-3-Clause)
Sebastian Stern committed
13

Sebastian Stern committed
14
### ROS2
Sebastian Stern committed
15 16
* How to install ROS2 <https://index.ros.org/doc/ros2/Installation/>
* You can use `ament` und `colcon` as build system define it within the `Settings`.
Sebastian Stern committed
17

Florian Roth committed
18
Only those ROS2 distributions are tested with the script.
Sebastian Stern committed
19 20 21 22 23 24 25 26 27
<table>
  <tr>
    <th>ROS2 Version </th>
    <th>Buildsystem</th>
  </tr>
  <tr>
    <td>Ardent Apalone</td>
    <td>ament</td>
  </tr>
Sebastian Stern committed
28
  <tr>
Sebastian Stern committed
29 30 31
    <td>Bouncy Bolson</td>
    <td>colcon</td>
  </tr>
32 33 34 35
  </tr>
    <td>Crystal Clemmys</td>
    <td>colcon</td>
  </tr>
Sebastian Stern committed
36
</table>
Florian Roth committed
37 38

Make sure to use the correct build system for the corresponding ROS2 version, otherwise the installation of ROS2 can be corrputed.
Sebastian Stern committed
39

Sebastian Stern committed
40
### ADTF
Florian Roth committed
41
* Version >= 3.3.1 (recommend latest)
Sebastian Stern committed
42

Sebastian Stern committed
43
### Compliler 
Florian Roth committed
44
* Depends on the ROS2 Version, in general on Windows MSVC2017 (toolchain VC141) and on Linux the GCC-Version delivered with Ubuntu 18.04.
Sebastian Stern committed
45

Sebastian Stern committed
46
## Overview
47 48
<img src="./documentation/pics/ADTF_ROS2_codegen.png" alt="overview"/>

Sebastian Stern committed
49
## First Steps
Sebastian Stern committed
50

Sebastian Stern committed
51
### System Service
Florian Roth committed
52
The provided ADTF System Service must be built from its sources and can be found in `plugins/adtf_system_service`.
Sebastian Stern committed
53
Copy the folder to `path_to_ros\ros2_ws\src\ros2` and adjust the `CMakeLists.txt` if necessary.
Sebastian Stern committed
54 55


Sebastian Stern committed
56
Afterwards use a VisualStudio command line(Windows)
Sebastian Stern committed
57 58 59 60
```
  cd path_to_ros2
  install\local_setup.bat
```
Sebastian Stern committed
61
or a terminal(Unix) with the provided commands
Sebastian Stern committed
62 63
```
  cd path_to_ros2
Sebastian Stern committed
64
  ./install/local_setup.bash
Sebastian Stern committed
65 66
```

Florian Roth committed
67 68
This activates the ROS2 environment within the terminal.
Afterwards the service can be installed using the following commands:
Sebastian Stern committed
69

70
**ament**
Sebastian Stern committed
71 72 73 74
```
ament build --only-package adtf_ros2_system_service
```

75
**colcon**
Sebastian Stern committed
76 77 78
```
colcon build --packages-select adtf_ros2_system_service
```
Florian Roth committed
79 80
It is possible you have to set the ADTF_DIR as environment variable.
After the compilation and install process the plugins can be found within `ADTF_DIR/bin/ros2`.
81

Sebastian Stern committed
82
### Environment within ADTF
Florian Roth committed
83
In Order to use ROS2 within ADTF 3.x the environment needs to be extended.
Sebastian Stern committed
84 85

#### Windows 
Florian Roth committed
86
Just use the ADTF Configuration Editor and navigate to System Editor >> Environment variables and add these entries.
Sebastian Stern committed
87

Sebastian Stern committed
88 89 90
* PYTHONPATH = path_to_ros\install\Lib\site-packages
* Path= path_to_ros\install\Scripts;path_to_ros\install\bin;$(Path)

Sebastian Stern committed
91 92

#### Linux
Florian Roth committed
93
For Linux the best way to use ROS2 within ADTF 3.x is to write a small launcher script which we than add as custom ADTF Launcher within the ADTF Configuration Editor.
Sebastian Stern committed
94

Sebastian Stern committed
95
```bash
Sebastian Stern committed
96 97 98 99 100 101 102 103 104 105 106
#!/bin/bash
# starter script for ADTF with ROS2 environment

echo 'Running: '$0
echo 'Setting up ROS2 Environment with script '$1
source $1

echo 'Starting: '$3 
$2/bin/adtf_launcher --session $3 --console --run
```

Florian Roth committed
107
We can store this script for exanmple within ADTF_DIR/bin/ros2/ros_launcher.sh and add it afterwards in the ADTF Configuration Editor.
Sebastian Stern committed
108 109 110
Navigate to Tools >> Options >> Launchers and press the Add-Button.

Fill in the Dialog with the following:
Sebastian Stern committed
111
* Name: LauncherWithRos2
Florian Roth committed
112
* Command: xterm -hold -e path/to/your/starter/bash path/to/ros2/local_setup.bash $(ADTF_DIR) $(ADTF_SESSION_FILENAME) 
Sebastian Stern committed
113
* Working Directory: $(ADTF_DIR) 
114

Florian Roth committed
115
Afterwards you can launch any given Session from the ADTF Configuration Editor in a ROS2 environment
Sebastian Stern committed
116

Sebastian Stern committed
117 118
## Functions
The Python script can be launched with any terminal. The starting point will be the main menu.
Sebastian Stern committed
119
<img src="./documentation/pics/main.gif" alt="main"/>
120

Sebastian Stern committed
121
### Settings
Sebastian Stern committed
122 123
When launching the script for the first time, you will be prompted to adjust the settings.
The settings are located within the submenu (5). After adjusting the necessary parameters you can start using the script.
Sebastian Stern committed
124

Sebastian Stern committed
125
<img src="./documentation/pics/settings.PNG" alt="settings"/>
126

Sebastian Stern committed
127 128
**ros_path:**

Sebastian Stern committed
129
Path to your local ROS2 installation for example `C:\dev\ros2`. Please don't use any overlays here the script needs to know the root install path.
Sebastian Stern committed
130 131 132

**adtf_path:**

Florian Roth committed
133
This setting describes the absolute path to your ADTF 3.x installation `C:\ADTF\3.x.y`
Sebastian Stern committed
134 135 136

**adtf_plugin_install_path:**

Florian Roth committed
137
With this setting you can define the path, in which the generated plugins will be installed for example `C:\ADTF\3.x.y\addons\adtf3_ros2_bridge\bin`.
Sebastian Stern committed
138 139 140

**visual_studio_path:**

Sebastian Stern committed
141 142 143 144
This setting is only relevant when using the script on a windows OS.
It should point to the VisualStudio-Commandline-Batch file which enables the usage if MSBuild within the current environment.
For Example `"C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\Tools\VsDevCmd.bat"`

Sebastian Stern committed
145 146

**ros_subscriber_pkg:**
Sebastian Stern committed
147 148 149

Defines the name of the ROS2 package under which the generated Subscriber/Streaming Source plugins are installed.
The default value `adtf_generated_subscriber` may be changed.
Sebastian Stern committed
150 151

**ros_publisher_pkg:**
Sebastian Stern committed
152 153 154 155

Defines the name of the ROS2 package under which the generated Publisher/Streaming Sink plugins are installed.
The default value `adtf_generated_publisher` may be changed.

Sebastian Stern committed
156 157

**ros_msg_pkg:**
Sebastian Stern committed
158 159 160

Defines the name of the ROS2 package under which the generated ROS2 messages are installed.
The default value `adtf_generated_msgs` may be changed.
Sebastian Stern committed
161 162 163

**ros_build_command:**

Sebastian Stern committed
164 165 166 167 168 169
This setting defines the command which is used to compile and install the generated plugins with the ROS2 buildsystem.

The command `colcon build --merge-install --packages-select` uses `colcon` as build system
with a merge installation of ROS2. The argument `--packages-select` is used to built exactly one defined package  
without it all packages within the ROS2 installation would be rebuilt.
Own CMake arguments can be used with the `--cmake-args` argument for example ` --cmake-args -DCMAKE_BUILD_TYPE=Debug`.
Sebastian Stern committed
170 171 172 173

[ROS2 Ament](https://github.com/ros2/ros2/wiki/Ament-Tutorial)

[ROS2 Colcon](https://github.com/ros2/ros2/wiki/Colcon-Tutorial)
Sebastian Stern committed
174

Sebastian Stern committed
175
### Create Subscriber
Sebastian Stern committed
176 177
With this functions you can create a ROS2 Subscriber/ADTF Streaming Source from a ROS2 message file(*.msg).
The available message files can be displayed with the submenu(6) `Show ROS2 msg files`.
178

Sebastian Stern committed
179
<img src="./documentation/pics/show_msgs.PNG" alt="show_msgs"/>
180

Sebastian Stern committed
181 182
**Example:**
From a message file `IntegerArray.msg` with the following content:
Sebastian Stern committed
183
```
Sebastian Stern committed
184
int32[100] data
Sebastian Stern committed
185
```
Sebastian Stern committed
186
a streamign source is generated with the following stream type:
Sebastian Stern committed
187
```C++
Sebastian Stern committed
188 189 190 191 192 193 194
StreamName = "IntegerArray"; 
DDL =
"<structs>"
  "<struct alignment=\"1\" name=\"IntegerArray\" version=\"1\">"
    "<element alignment=\"1\" arraysize=\"100\" byteorder=\"LE\" bytepos=\"0\" name=\"data\" type=\"tInt32\"/>"
  "</struct>"
"</structs>"
Sebastian Stern committed
195
```
Sebastian Stern committed
196
The generated streamign source sends a new sample everytime a data package is received over the ROS2 DDS network.
Sebastian Stern committed
197
<img src="./documentation/pics/create_sub.gif" alt="create_sub"/>
Sebastian Stern committed
198 199


Sebastian Stern committed
200 201
### Create Publisher
This function generates ROS2 Publisher/ADTF Streaming Sink with a given DDL-Description as xml or string.
Sebastian Stern committed
202 203


Sebastian Stern committed
204 205
**Example:**
The following file *.xml (*.txt) with given content:
Sebastian Stern committed
206
```XML
Sebastian Stern committed
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225
<structs>
  <struct alignment="1" name="tHeaderStruct" version="1">
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="0" name="ui32HeaderVal" type="tUInt32" />
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="4" name="f64HeaderVal" type="tFloat64" />
  </struct>
  <struct alignment="1" name="tNestedStruct" version="1">
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="0" name="sHeaderStruct" type="tHeaderStruct" />
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="12" name="sSimpleStruct" type="tSimpleStruct" />
  </struct>
  <struct alignment="1" name="tSimpleStruct" version="1">
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="0" name="ui8Val" type="tUInt8" />
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="1" name="ui16Val" type="tUInt16" />
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="3" name="ui32Val" type="tUInt32" />
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="7" name="i32Val" type="tInt32" />
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="11" name="i64Val" type="tInt64" />
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="19" name="f64Val" type="tFloat64" />
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="27" name="f32Val" type="tFloat32" />
  </struct>
</structs>
Sebastian Stern committed
226
```
Sebastian Stern committed
227

Sebastian Stern committed
228
Will generate the following ROS2 message files if not already present within you ROS2 installation.
Sebastian Stern committed
229
```
Sebastian Stern committed
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
TSimpleStruct.msg
uint8 ui8_val
uint16 ui16_val
uint32 ui32_val
int32 i32_val
int64 i64_val
float64 f64_val
float32 f32_val

THeaderStruct.msg
uint32 ui32_header_val
float64 f64_header_val

TNestedStruct.msg
THeaderStruct s_header_struct
TSimpleStruct s_simple_struct
Sebastian Stern committed
246
```
Sebastian Stern committed
247 248
After the ROS2 build system has generated all the neccessary files a second step will use these files to generate
a Publisher/Streaming Sinks. These plugins will publish with each reserve sample a ROS2 message with the corresponding data within the ROS2 DDS network.
Sebastian Stern committed
249

Sebastian Stern committed
250
<img src="./documentation/pics/create_pub.gif" alt="create_pub"/>
Sebastian Stern committed
251