You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
ROS 2 nodes are the ground element on ROS2 ecosystem. They will contain communicate between each other using publishers, subscriptions, services, ... .Further information about ROS 2 nodes can be found [here](https://docs.ros.org/en/galactic/Tutorials/Understanding-ROS2-Nodes.html)
6
+
ROS 2 nodes are the main participants on ROS2 ecosystem. They will communicate between each other using publishers, subscriptions, services, ... Further information about ROS 2 nodes can be found [here](https://docs.ros.org/en/galactic/Tutorials/Understanding-ROS2-Nodes.html)
7
7
8
-
// TODO: explain general micro-ROS initialization (allocator and support)
8
+
// TODO: explain general micro-ROS initialization (allocator and support). Where?
9
9
## <aname="init_node"/>Initialization
10
10
11
11
- Create a node with default configuration:
@@ -33,12 +33,9 @@ ROS 2 nodes are the ground element on ROS2 ecosystem. They will contain communic
33
33
```
34
34
35
35
- Create a node with custom options:
36
+
// TODO: explain possible options
36
37
37
-
Node configuration will also be applied to its future elements (Publishers, subscribers, services, ...).
38
-
39
-
// TODO: explain possible options and their meaning
40
-
41
-
The API used to customize the node options differs between ROS2 distributions:
38
+
The configuration of the node will also be applied to its future elements (Publishers, subscribers, services, ...).The API used to customize the node options differs between ROS2 distributions:
42
39
43
40
Foxy: The `rcl_node_options_t` is used to configure the node
44
41
@@ -67,7 +64,7 @@ ROS 2 nodes are the ground element on ROS2 ecosystem. They will contain communic
67
64
return -1;
68
65
}
69
66
```
70
-
67
+
71
68
Galactic: In this case, the node options are configured on the `rclc_support_t` object with a custom API
72
69
73
70
```C
@@ -101,14 +98,15 @@ ROS 2 nodes are the ground element on ROS2 ecosystem. They will contain communic
101
98
102
99
### <a name="node_end"/>Cleaning Up
103
100
104
-
To destroy a initialized node all entities owned by the node (Publishers, subscribers, services, ...) needs to be destroyed before the node itself:
101
+
To destroy a initialized node all entities owned by the node (Publishers, subscribers, services, ...) have to be destroyed before the node itself:
105
102
106
103
```C
107
-
// Destroy created entities
104
+
// Destroy created entities (Example)
105
+
rcl_publisher_fini(&publisher, &node);
108
106
...
109
107
110
-
// Destroy a node
108
+
// Destroy the node
111
109
rcl_node_fini(&node);
112
110
```
113
111
114
-
This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the client side.
112
+
This will delete the node from ROS2 graph, including any generated infrastructure on the agent (if possible) and used memory on the client.
Copy file name to clipboardExpand all lines: _docs/tutorials/programming_rcl_rclc/overview/index.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,9 +5,9 @@ redirect_from:
5
5
- /docs/tutorials/programming_rcl_rclc/
6
6
---
7
7
8
-
In this tutorial, you'll learn the basics of the micro-ROS C API. The major concepts (publishers, subscriptions, services,timers, ...) are identical with ROS 2. They even rely on the *same* implementation, as the micro-ROS C API is based on the ROS 2 client support library (rcl), enriched with a set of convenience functions by the package [rclc](https://github.com/ros2/rclc/). That is, rclc does not add a new layer of types on top of rcl (like rclcpp and rclpy do) but only provides functions that ease the programming with the rcl types. New types are introduced only for concepts that are missing in rcl, such as the concept of an executor.
8
+
In this tutorial, you'll learn the basics of the micro-ROS C API. The major concepts (publishers, subscriptions, services,timers, ...) are identical with ROS 2. They even rely on the *same* implementation, as the micro-ROS C API is based on the ROS 2 client support library (rcl), enriched with a set of convenience functions by the package [rclc](https://github.com/ros2/rclc/). That is, rclc does not add a new layer of types on top of rcl (like rclcpp and rclpy do) but only provides functions that ease the programming with the rcl types. New types are introduced only for concepts that are missing in rcl, such as the concept of an executor.
ROS 2 publishers and subscribers are the basic communication mechanism between nodes using topics. Further information about ROS 2 publish–subscribe pattern can be found [here](https://docs.ros.org/en/foxy/Tutorials/Topics/Understanding-ROS2-Topics.html).
7
7
8
-
Ready to use code related to this tutorial can be found in [`micro-ROS-demos/rclc/int32_publisher`](https://github.com/micro-ROS/micro-ROS-demos/blob/foxy/rclc/int32_publisher/main.c) and [`micro-ROS-demos/rclc/int32_subscriber`](https://github.com/micro-ROS/micro-ROS-demos/blob/foxy/rclc/int32_subscriber/main.c) folders. Fragments of code from this examples are used on this tutorial.
8
+
Ready to use code related to this concepts can be found in [`micro-ROS-demos/rclc/int32_publisher`](https://github.com/micro-ROS/micro-ROS-demos/blob/foxy/rclc/int32_publisher/main.c) and [`micro-ROS-demos/rclc/int32_subscriber`](https://github.com/micro-ROS/micro-ROS-demos/blob/foxy/rclc/int32_subscriber/main.c) folders. Fragments of code from this examples are used on this tutorial.
9
+
10
+
// TODO: add index?
9
11
10
12
## <aname="pub"/>Publisher
11
13
12
14
### <aname="pub_init"/>Initialization
13
15
14
16
Starting from a code where RCL is initialized and a micro-ROS node is created, there are tree ways to initialize a publisher depending on the desired quality-of-service configuration:
15
17
16
-
// TODO: explain and link diferences between each approach on QoS section
17
-
18
-
- Reliable:
18
+
- Reliable (default):
19
19
```C
20
20
// Publisher object
21
21
rcl_publisher_t publisher;
@@ -27,28 +27,12 @@ Starting from a code where RCL is initialized and a micro-ROS node is created, t
Reliable publishers will wait for confirmation for each published message, which leads to blocking `rcl_publish` calls, `rmw-microxrcedds` offers an API to configure the acknowledgement timeout for each publisher:
The default value for all publishers is configured at compilation time by the cmake variable `RMW_UXRCE_PUBLISH_RELIABLE_TIMEOUT`.
51
-
52
36
- Best effort:
53
37
```C
54
38
// Publisher object
@@ -66,7 +50,7 @@ Starting from a code where RCL is initialized and a micro-ROS node is created, t
66
50
return -1;
67
51
}
68
52
```
69
-
53
+
70
54
- Custom QoS:
71
55
72
56
```C
@@ -88,11 +72,13 @@ Starting from a code where RCL is initialized and a micro-ROS node is created, t
88
72
return -1;
89
73
}
90
74
```
75
+
76
+
For a detail on the avaliable QoS options and the advantages and disadvantages between reliable and best effort modes, check the [QoS tutorial](../qos/).
91
77
92
78
## <a name="pub_publish"/>Publish a message
93
79
94
-
// TODO: explain message memory allocation and link to tutorial
95
-
// TODO: explain periodic publication and link to timers
For periodic publications, `rcl_publish` can be placed inside a timer callback. Check the [Executor and timers](../executor/) section for details.
99
+
111
100
Note: `rcl_publish` is thread safe and can be called from multiple threads.
112
101
113
102
## <aname="sub"/>Subscription
@@ -153,7 +142,7 @@ The suscriptor initialization is almost identical to the publisher one:
153
142
}
154
143
```
155
144
156
-
-Add QoS API
145
+
-Custom QoS:
157
146
158
147
```C
159
148
// Subscription object
@@ -175,8 +164,13 @@ The suscriptor initialization is almost identical to the publisher one:
175
164
}
176
165
```
177
166
167
+
For a detail on the avaliable QoS options and the advantages and disadvantages between reliable and best effort modes, check the [QoS tutorial](../qos/).
168
+
178
169
### <a name="sub_callback"/>Callbacks
170
+
The executor is responsible to call the configured callback when a message is published.
171
+
The function will have the message as its only argument, containing the values sended by the publisher:
Once the subscriber and the executor are initialized, the subscriber callback must be added to the executor to receive incoming publications once the executor is spinning:
192
185
186
+
Once the subscriber and the executor are initialized, the subscriber callback must be added to the executor to receive incoming publications once its spinning:
// Add benchmark results for Throughput and RTT to compare both modes?
7
+
// Explain custom QoS options
8
+
9
+
## <aname="qos"/>Reliable QoS
7
10
8
-
```C
11
+
Reliable communication implies a confirmation for each message sended. This mode can detect errors in the communication process at the cost of increasing the message latency and the resources usage.
12
+
13
+
This message confirmation proccess can increase blocking time on `rcl_publish` or executor spin calls as reliable publishers, services and clients will wait for acknowledgement for each sended message. `rmw-microxrcedds` offers an API to individually configure the acknowledgement timeout on them:
The default value for all publishers is configured at compilation time by the cmake variable `RMW_UXRCE_PUBLISH_RELIABLE_TIMEOUT`.
9
35
36
+
## <a name="qos"/>Best Effort
37
+
38
+
In best effort mode no acknowledgement is needed, the messages sended are expected to be received. This method improves publication throughput and reduces resources usage but is vulnerable to communication errors.
0 commit comments