Skip to content

Commit bac44c5

Browse files
Acuadros95Acuadros95
committed
Doc update for parameters upgrade
1 parent c74a65d commit bac44c5

1 file changed

Lines changed: 254 additions & 69 deletions

File tree

‎_docs/tutorials/programming_rcl_rclc/parameters/parameters.md‎

Lines changed: 254 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,20 @@ ROS 2 parameters allow the user to create variables on a node and manipulate/rea
99

1010
Ready to use code related to this tutorial can be found in [`rclc/rclc_examples/src/example_parameter_server.c`](https://github.com/ros2/rclc/blob/master/rclc_examples/src/example_parameter_server.c). Fragments of code from this example is used on this tutorial.
1111

12-
Note: micro-ROS parameter server is only supported on ROS 2 Galactic distribution
12+
micro-ROS parameters implementation has been upgraded in the latest micro-ROS Rolling distribution, two approaches are presented in this tutorial: micro-ROS Foxy/Galactic and micro-ROS Rolling and beyond:
1313

1414
- [Initialization](#initialization)
1515
- [Memory requirements](#memory-requirements)
16-
- [Callback](#callback)
1716
- [Add a parameter](#add-a-parameter)
1817
- [Cleaning up](#cleaning-up)
18+
- [micro-ROS Foxy/Galactic](#micro-ros-foxygalactic)
19+
- [Initialization options](#initialization-options)
20+
- [Callback](#callback)
21+
- [micro-ROS Rolling](#micro-ros-rolling)
22+
- [Initialization options](#initialization-options-1)
23+
- [Callback](#callback-1)
24+
- [Delete a parameter](#delete-a-parameter)
25+
- [Parameters description](#parameters-description)
1926

2027
## Initialization
2128

@@ -33,28 +40,6 @@ Note: micro-ROS parameter server is only supported on ROS 2 Galactic distributio
3340
}
3441
```
3542

36-
- Custom options:
37-
38-
The user can configure whether to notify parameter changes to the rest of nodes (`notify_changed_over_dds`) and the maximum number of parameters (`max_params`) allowed on the `rclc_parameter_server_t` object:
39-
40-
```c
41-
// Parameter server object
42-
rclc_parameter_server_t param_server;
43-
44-
// Initialize parameter server options
45-
const rclc_parameter_options_t options = {
46-
.notify_changed_over_dds = true,
47-
.max_params = 4 };
48-
49-
// Initialize parameter server with configured options
50-
rcl_ret_t rc = rclc_parameter_server_init_with_option(&param_server, &node, &options);
51-
52-
if (RCL_RET_OK != rc) {
53-
... // Handle error
54-
return -1;
55-
}
56-
```
57-
5843
## Memory requirements
5944

6045
The parameter server uses 5 services and an optional publisher, this needs to be taken into account on the `rmw-microxredds` package memory configuration:
@@ -86,50 +71,6 @@ rc = rclc_executor_init(
8671
RCLC_PARAMETER_EXECUTOR_HANDLES_NUMBER, &allocator);
8772
```
8873

89-
## Callback
90-
91-
When adding the parameter server to the executor, a callback can be configured.
92-
This callback will be executed after a parameter value is modified.
93-
94-
A pointer to the changed parameter is passed as first and only argument. Example:
95-
```c
96-
void on_parameter_changed(Parameter * param)
97-
{
98-
// Get parameter name
99-
printf("Parameter %s modified.", param->name.data);
100-
101-
// Get parameter type
102-
switch (param->value.type)
103-
{
104-
// Get parameter value acording type
105-
case RCLC_PARAMETER_BOOL:
106-
printf(" New value: %d (bool)", param->value.bool_value);
107-
break;
108-
case RCLC_PARAMETER_INT:
109-
printf(" New value: %ld (int)", param->value.integer_value);
110-
break;
111-
case RCLC_PARAMETER_DOUBLE:
112-
printf(" New value: %f (double)", param->value.double_value);
113-
break;
114-
default:
115-
break;
116-
}
117-
118-
printf("\n");
119-
}
120-
```
121-
Once the parameter server and the executor are initialized, the parameter server must be added to the executor in order to accept parameters commands from ROS2:
122-
```c
123-
// Add parameter server to executor including defined callback
124-
rc = rclc_executor_add_parameter_server(&executor, &param_server, on_parameter_changed);
125-
```
126-
127-
Note that this callback is optional as its just an event information for the user. To use the parameter server without a callback:
128-
```c
129-
// Add parameter server to executor without callback
130-
rc = rclc_executor_add_parameter_server(&executor, &param_server, NULL);
131-
```
132-
13374
## Add a parameter
13475

13576
micro-ROS parameter server supports the following parameter types:
@@ -183,7 +124,9 @@ micro-ROS parameter server supports the following parameter types:
183124
// Get parameter value on param_value
184125
rc = rclc_parameter_get_double(&param_server, parameter_name, &param_value);
185126
```
186-
127+
128+
*Max name size is controlled by the compilation time option `RCLC_PARAMETER_MAX_STRING_LENGTH`, default value is 50.*
129+
187130
## Cleaning up
188131

189132
To destroy an initialized parameter server:
@@ -194,3 +137,245 @@ rclc_parameter_server_fini(&param_server, &node);
194137
```
195138
196139
This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the client side.
140+
141+
## micro-ROS Foxy/Galactic
142+
143+
### Initialization options
144+
145+
- Custom options:
146+
147+
The following options can be configured:
148+
- notify_changed_over_dds: Publish parameters events to the rest of nodes.
149+
- max_params: Maximum number of parameters allowed on the `rclc_parameter_server_t` object.
150+
151+
```c
152+
// Parameter server object
153+
rclc_parameter_server_t param_server;
154+
155+
// Initialize parameter server options
156+
const rclc_parameter_options_t options = {
157+
.notify_changed_over_dds = true,
158+
.max_params = 4 };
159+
160+
// Initialize parameter server with configured options
161+
rcl_ret_t rc = rclc_parameter_server_init_with_option(&param_server, &node, &options);
162+
163+
if (RCL_RET_OK != rc) {
164+
... // Handle error
165+
return -1;
166+
}
167+
```
168+
169+
### Callback
170+
171+
When adding the parameter server to the executor, a callback can be configured.
172+
This callback will be executed after a parameter value is modified.
173+
174+
A pointer to the changed parameter is passed as first and only argument. Example:
175+
```c
176+
void on_parameter_changed(Parameter * param)
177+
{
178+
// Get parameter name
179+
printf("Parameter %s modified.", param->name.data);
180+
181+
// Get parameter type
182+
switch (param->value.type)
183+
{
184+
// Get parameter value acording type
185+
case RCLC_PARAMETER_BOOL:
186+
printf(" New value: %d (bool)", param->value.bool_value);
187+
break;
188+
case RCLC_PARAMETER_INT:
189+
printf(" New value: %ld (int)", param->value.integer_value);
190+
break;
191+
case RCLC_PARAMETER_DOUBLE:
192+
printf(" New value: %f (double)", param->value.double_value);
193+
break;
194+
default:
195+
break;
196+
}
197+
198+
printf("\n");
199+
}
200+
```
201+
Once the parameter server and the executor are initialized, the parameter server must be added to the executor in order to accept parameters commands from ROS2:
202+
```c
203+
// Add parameter server to executor including defined callback
204+
rc = rclc_executor_add_parameter_server(&executor, &param_server, on_parameter_changed);
205+
```
206+
207+
Note that this callback is optional as its just an event information for the user. To use the parameter server without a callback:
208+
```c
209+
// Add parameter server to executor without callback
210+
rc = rclc_executor_add_parameter_server(&executor, &param_server, NULL);
211+
```
212+
213+
## micro-ROS Rolling
214+
215+
### Initialization options
216+
217+
- Custom options:
218+
219+
The following options can be configured:
220+
- notify_changed_over_dds: Publish parameters events to the rest of nodes.
221+
- max_params: Maximum number of parameters allowed on the `rclc_parameter_server_t` object.
222+
- allow_undeclared_parameters: Allows creation of parameters from external parameters clients. A new parameter will be created if a `set` operation is requested on a non-existing parameter.
223+
- low_mem_mode: Reduces the memory used by the parameter server, functionality constrains are applied.
224+
225+
```c
226+
// Parameter server object
227+
rclc_parameter_server_t param_server;
228+
229+
// Initialize parameter server options
230+
const rclc_parameter_options_t options = {
231+
.notify_changed_over_dds = true,
232+
.max_params = 4,
233+
.allow_undeclared_parameters = true,
234+
.low_mem_mode = false; };
235+
236+
// Initialize parameter server with configured options
237+
rcl_ret_t rc = rclc_parameter_server_init_with_option(&param_server, &node, &options);
238+
239+
if (RCL_RET_OK != rc) {
240+
... // Handle error
241+
return -1;
242+
}
243+
```
244+
245+
- Low memory mode:
246+
This mode ports the parameters functionality to memory constrained devices. The following constrains are applied:
247+
- Request size limited to 1 parameter on Set, Get, Get types and Describe services.
248+
- List parameters request has no prefixes enabled nor depth.
249+
- Parameter description strings not allowed, `rclc_add_parameter_description` is disabled.
250+
251+
Memory benchmark on `STM32F4` for 7 parameters with `RCLC_PARAMETER_MAX_STRING_LENGTH = 50` and `notify_changed_over_dds = true`:
252+
- Full mode: 11736 B
253+
- Low memory mode: 4160 B
254+
255+
### Callback
256+
257+
When adding the parameter server to the executor, a callback can be configured. This callback will be executed on the following events:
258+
- Parameter value change: Internal and external parameter set on existing parameters.
259+
- Parameter creation: External parameter set on unexisting parameter if `allow_undeclared_parameters` is set.
260+
- Parameter delete: External parameter delete on existing parameter.
261+
- The user can allow or reject this operations using the `bool` return value.
262+
263+
Callback parameters:
264+
- old_param: Parameter actual value, `NULL` for new parameter request.
265+
- new_param: Parameter new value, `NULL` for parameter removal request.
266+
- context: User context, configured on `rclc_executor_add_parameter_server_with_context`.
267+
268+
```c
269+
bool on_parameter_changed(const Parameter * old_param, const Parameter * new_param, void * context)
270+
{
271+
(void) context;
272+
273+
if (old_param == NULL) {
274+
printf("Creating new parameter %s\n", new_param->name.data);
275+
} else if (new_param == NULL) {
276+
printf("Deleting parameter %s\n", old_param->name.data);
277+
} else {
278+
printf("Parameter %s modified.", old_param->name.data);
279+
switch (old_param->value.type) {
280+
case RCLC_PARAMETER_BOOL:
281+
printf(
282+
" Old value: %d, New value: %d (bool)", old_param->value.bool_value,
283+
new_param->value.bool_value);
284+
break;
285+
case RCLC_PARAMETER_INT:
286+
printf(
287+
" Old value: %ld, New value: %ld (int)", old_param->value.integer_value,
288+
new_param->value.integer_value);
289+
break;
290+
case RCLC_PARAMETER_DOUBLE:
291+
printf(
292+
" Old value: %f, New value: %f (double)", old_param->value.double_value,
293+
new_param->value.double_value);
294+
break;
295+
default:
296+
break;
297+
}
298+
printf("\n");
299+
}
300+
301+
return true;
302+
}
303+
```
304+
305+
Parameters modifications are disabled while this callback is executed, causing this methods to return `RCLC_PARAMETER_DISABLED_ON_CALLBACK`:
306+
- rclc_add_parameter
307+
- rclc_delete_parameter
308+
- rclc_parameter_set_bool
309+
- rclc_parameter_set_int
310+
- rclc_parameter_set_double
311+
- rclc_set_parameter_read_only
312+
- rclc_add_parameter_constraints_double
313+
- rclc_add_parameter_constraints_integer
314+
315+
316+
Once the parameter server and the executor are initialized, the parameter server must be added to the executor in order to accept parameters commands from ROS2:
317+
```c
318+
// Add parameter server to executor including defined callback
319+
rc = rclc_executor_add_parameter_server(&executor, &param_server, on_parameter_changed);
320+
```
321+
322+
Note that this callback is optional as its just an event information for the user. To use the parameter server without a callback:
323+
```c
324+
// Add parameter server to executor without callback
325+
rc = rclc_executor_add_parameter_server(&executor, &param_server, NULL);
326+
```
327+
328+
To configure the callback context:
329+
```c
330+
// Add parameter server to executor including defined callback and a context
331+
rc = rclc_executor_add_parameter_server_with_context(&executor, &param_server, on_parameter_changed, &context);
332+
```
333+
334+
### Delete a parameter
335+
Parameters can be deleted both by the parameter server and external clients:
336+
Example usage:
337+
```c
338+
rclc_delete_parameter(&param_server, "param2");
339+
```
340+
341+
Note that for external delete requests the server callback will be executed, allowing the user to reject the operation.
342+
343+
### Parameters description
344+
345+
- Parameter description
346+
Adds a description of a parameter and its constrains. This descriptors will be returned to describe parameters requests.
347+
Example usage:
348+
```c
349+
rclc_add_parameter_description(&param_server, "param2", "Second parameter", "Only even numbers");
350+
```
351+
352+
*The maximum string size is controlled by the compilation time option `RCLC_PARAMETER_MAX_STRING_LENGTH`, default value is 50.*
353+
354+
- Parameter constrains
355+
Informative numeric constrains can be added to int and double parameters, returning this values on describe parameters requests.
356+
Note that this constrains will not be applied by the parameter server, leaving values filtering to the user callback.
357+
358+
The following values can be configured:
359+
- from_value: Start value for valid values, inclusive.
360+
- to_value: End value for valid values, inclusive.
361+
- step: Size of valid steps between the from and to bound.
362+
363+
Example usage:
364+
```c
365+
int64_t int_from = 0;
366+
int64_t int_to = 20;
367+
uint64_t int_step = 2;
368+
rclc_add_parameter_constraints_integer(&param_server, "param2", int_from, int_to, int_step);
369+
370+
double double_from = -0.5;
371+
double double_to = 0.5;
372+
double double_step = 0.01;
373+
rclc_add_parameter_constraints_double(&param_server, "param3", double_from, double_to, double_step);
374+
```
375+
376+
- Read only parameters:
377+
The new API offers a read only flag. This flag blocks parameter changes from external clients, but allows changes on the server side. Example usage:
378+
```c
379+
bool read_only = true;
380+
rclc_set_parameter_read_only(&param_server, "param3", read_only);
381+
```

0 commit comments

Comments
 (0)