Skip to content

Commit 5e3533a

Browse files
pablogs9Julián Bermúdez Ortega
andauthored
Ref #7868. RMW Configuration tutorial (#111)
* Initial tutorial * Fix CI * Adding header Fix permalink * Minor changes Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Update _docs/tutorials/basic/microxrcedds_rmw_configuration/index.md Co-Authored-By: Julián Bermúdez Ortega <julianbermudez@eprosima.com> Co-authored-by: Julián Bermúdez Ortega <julianbermudez@eprosima.com>
1 parent 8c011fa commit 5e3533a

2 files changed

Lines changed: 89 additions & 0 deletions

File tree

‎_data/docs.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@
4747
- tutorials/advanced/tracing
4848
- tutorials/advanced/microros_nuttx_bsp
4949

50+
- title: Micro-XRCE-DDS RMW Configuration
51+
docs:
52+
- tutorials/basic/microxrcedds_rmw_configuration
53+
5054
- title: Demos
5155
docs:
5256
- tutorials/demos/kobuki_demo
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: RMW Micro-XRCE-DDS Configuration
3+
permalink: /docs/tutorials/basic/microxrcedds_rmw_configuration/
4+
---
5+
6+
Since micro-ROS is intended to work on extremely low resources systems, its middleware layer is highly configurable. This configurability, along with the fact that the middleware layer does not use dynamic memory, allows the users to determine how much static memory is going to be allocated.
7+
8+
If you want to read more about the middleware layer follow this link: [Micro XRCE-DDS](https://micro-xrce-dds.readthedocs.io/en/latest/)
9+
10+
The ROS 2 middleware layer for Micro XRCE-DDS or rmw_microxrcedds allows two types of configuration:
11+
- Compile-time configuration.
12+
- Run-time configuration.
13+
14+
Ready to use code related to this tutorial can be found in `micro-ROS-demos/rcl/configuration_example/` folder in [`micro-ROS-demos` repo](https://github.com/micro-ROS/micro-ROS-demos/tree/dashing/rcl/configuration_example).
15+
16+
## Compile-time configuration
17+
18+
The following parameters can be configured through CMake arguments:
19+
20+
<!-- TODO: Related errors (FAQ) -->
21+
22+
| Parameter name | Description | Default value |
23+
| - | - | - |
24+
| RMW_UXRCE_TRANSPORT | Sets Micro XRCE-DDS transport to use: udp, serial or custom. | udp |
25+
| RMW_UXRCE_CREATION_MODE | Sets creation mode in Micro XRCE-DDS: xml or refs. | xml |
26+
| RMW_UXRCE_MAX_HISTORY | This value sets the number of MTUs to buffer. Micro XRCE-DDS client configuration provides its size. | 4 |
27+
| RMW_UXRCE_MAX_NODES | This value sets the maximum number of nodes. | 4 |
28+
| RMW_UXRCE_MAX_PUBLISHERS | This value sets the maximum number of publishers available. | 4 |
29+
| RMW_UXRCE_MAX_SUBSCRIPTIONS | This value sets the maximum number of subscriptions available. | 4 |
30+
| RMW_UXRCE_MAX_SERVICES | This value sets the maximum number of services available. | 4 |
31+
| RMW_UXRCE_MAX_CLIENTS | This value sets the maximum number of clients available. | 4 |
32+
| RMW_UXRCE_NODE_NAME_MAX_LENGTH | This value sets the maximum number of characters for a node name. | 128 |
33+
| RMW_UXRCE_TOPIC_NAME_MAX_LENGTH | This value sets the maximum number of characters for a topic name. | 100 |
34+
| RMW_UXRCE_TYPE_NAME_MAX_LENGTH | This value sets the maximum number of characters for a type name. | 128 |
35+
| RMW_UXRCE_XML_BUFFER_LENGTH | This value sets the maximum number of characters for a XML buffer used internally. | 600 |
36+
| RMW_UXRCE_REF_BUFFER_LENGTH | This value sets the maximum number of characters for a reference buffer used internally. | 100 |
37+
| RMW_UXRCE_DEFAULT_SERIAL_DEVICE | Sets the agent default serial port. | /dev/ttyAMA0 |
38+
| RMW_UXRCE_DEFAULT_UDP_IP | Sets the agent default IP address. | 127.0.0.1 |
39+
| RMW_UXRCE_DEFAULT_UDP_PORT | Sets the agent default IP port. | 8888 |
40+
41+
The micro-ROS way to pass CMake arguments to the build system is using `colcon.meta` file. For example, increasing the number of statically allocated publishers looks like that:
42+
43+
```
44+
{
45+
"names": {
46+
"rmw_microxrcedds": {
47+
"cmake-args": [
48+
"-DRMW_UXRCE_MAX_PUBLISHERS=6"
49+
]
50+
}
51+
}
52+
}
53+
```
54+
55+
## Run-time configuration
56+
57+
Although there are some build time parameters related to client to agent connection (such as **CONFIG_RMW_DEFAULT_UDP_PORT**, **CONFIG_RMW_DEFAULT_UDP_IP** and **CONFIG_RMW_DEFAULT_SERIAL_DEVICE**) these kinds of parameters can also be configured at run-time. The following example code shows the API calls needed to set the agent's IP address, port or serial device:
58+
59+
```c
60+
#include <rmw_uros/options.h>
61+
62+
// Init RCL options and context
63+
rcl_init_options_t init_options = rcl_get_zero_initialized_init_options();
64+
rcl_context_t context = rcl_get_zero_initialized_context();
65+
rcl_init_options_init(&init_options, rcl_get_default_allocator());
66+
67+
// Take RMW options from RCL options
68+
rmw_init_options_t* rmw_options = rcl_init_options_get_rmw_init_options(&init_options);
69+
70+
// TCP/UDP case: Set RMW IP parameters
71+
rmw_uros_options_set_udp_address("127.0.0.1", "8888", rmw_options);
72+
73+
// Serial case: Set RMW serial device parameters
74+
mw_uros_options_set_serial_device("/dev/ttyAMA0", rmw_options)
75+
76+
// Set RMW client key
77+
rmw_uros_options_set_client_key(0xBA5EBA11, rmw_options);
78+
79+
// Init RCL
80+
rcl_init(0, NULL, &init_options, &context);
81+
82+
// ... micro-ROS code ...
83+
```
84+
85+
Notice that is also possible to set the Micro XRCE-DDS `client_key`, which would otherwise be set randomly. This feature is useful for reusing DDS entities already created on the agent side. Further information can be found [here](https://micro-xrce-dds.readthedocs.io/en/latest/deployment.html#configurate-the-publisher).

0 commit comments

Comments
 (0)