rclc_parameter package from rclc reporclc rclc_examples rclc_lifecycle rclc_parameter |
|
Package Summary
Tags | No category tags. |
Version | 4.0.2 |
License | Apache License 2.0 |
Build type | AMENT_CMAKE |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/ros2/rclc.git |
VCS Type | git |
VCS Version | humble |
Last Updated | 2023-12-15 |
Dev Status | DEVELOPED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Antonio Cuadros
Authors
- Antonio Cuadros
The rclc parameter package
ROS 2 parameters allow the user to create variables on a node and manipulate/read them with different ROS 2 commands. Further information about ROS 2 parameters can be found here
This package provides the rclc API with parameter server instances with full ROS 2 parameter client compatibility. A parameter client has not been implemented for rclc (yet).
Ready to use code examples related to this tutorial can be found in rclc/rclc_examples/src/example_parameter_server.c
.
Table of contents
- Initialization
- Memory requirements
- Callback
- Add a parameter
- Delete a parameter
- Parameter description
- Cleaning up
Initialization
- Default initialization:
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server with default configuration
rcl_ret_t rc = rclc_parameter_server_init_default(¶m_server, &node);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Custom options:
The following options can be configured:
- notify_changed_over_dds: Publish parameter events to other ROS 2 nodes as well.
- max_params: Maximum number of parameters allowed on the
rclc_parameter_server_t
object. - allow_undeclared_parameters: Allows creation of parameters from external parameter clients. A new parameter will be created if a
set
operation is requested on a non-existing parameter. - low_mem_mode: Reduces the memory used by the parameter server, functionality constrains are applied.
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server options
const rclc_parameter_options_t options = {
.notify_changed_over_dds = true,
.max_params = 4,
.allow_undeclared_parameters = true,
.low_mem_mode = false; };
// Initialize parameter server with configured options
rcl_ret_t rc = rclc_parameter_server_init_with_option(¶m_server, &node, &options);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Low memory mode:
This mode ports the parameter functionality to memory constrained devices. The following constrains are applied:
- Request size limited to one parameter on Set, Get, Get types and Describe services.
- List parameter request has no prefixes enabled nor depth.
- Parameter description strings not allowed,
rclc_add_parameter_description
is disabled.
Memory benchmark results on
STM32F4
for 7 parameters withRCLC_PARAMETER_MAX_STRING_LENGTH = 50
andnotify_changed_over_dds = true
:- Full mode: 11736 B
- Low memory mode: 4160 B
Memory requirements
The parameter server uses five services and an optional publisher. These need to be taken into account on the rmw-microxrcedds
package memory configuration:
# colcon.meta example with memory requirements to use a parameter server
{
"names": {
"rmw_microxrcedds": {
"cmake-args": [
"-DRMW_UXRCE_MAX_NODES=1",
"-DRMW_UXRCE_MAX_PUBLISHERS=1",
"-DRMW_UXRCE_MAX_SUBSCRIPTIONS=0",
"-DRMW_UXRCE_MAX_SERVICES=5",
"-DRMW_UXRCE_MAX_CLIENTS=0"
]
}
}
}
At runtime, the variable RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES
defines the necessary number of handles required by a parameter server for the rclc Executor:
// Executor init example with the minimum RCLC executor handles required
rclc_executor_t executor = rclc_executor_get_zero_initialized_executor();
rc = rclc_executor_init(
&executor, &support.context,
RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES, &allocator);
Callback
When adding the parameter server to the executor, a callback could to be configured. This callback would then be executed on the following events:
- Parameter value change: Internal and external parameter set on existing parameters.
- Parameter creation: External parameter set on unexisting parameter if
allow_undeclared_parameters
is set. - Parameter delete: External parameter delete on existing parameter.
- The user can allow or reject this operations using the
bool
return value.
Callback parameters:
-
old_param
: Parameter actual value,NULL
for new parameter request. -
new_param
: Parameter new value,NULL
for parameter removal request. -
context
: User context, configured onrclc_executor_add_parameter_server_with_context
.
bool on_parameter_changed(const Parameter * old_param, const Parameter * new_param, void * context)
{
(void) context;
if (old_param == NULL && new_param == NULL) {
printf("Callback error, both parameters are NULL\n");
return false;
}
if (old_param == NULL) {
printf("Creating new parameter %s\n", new_param->name.data);
} else if (new_param == NULL) {
printf("Deleting parameter %s\n", old_param->name.data);
} else {
printf("Parameter %s modified.", old_param->name.data);
switch (old_param->value.type) {
case RCLC_PARAMETER_BOOL:
printf(
" Old value: %d, New value: %d (bool)", old_param->value.bool_value,
new_param->value.bool_value);
break;
case RCLC_PARAMETER_INT:
printf(
" Old value: %ld, New value: %ld (int)", old_param->value.integer_value,
new_param->value.integer_value);
break;
case RCLC_PARAMETER_DOUBLE:
printf(
" Old value: %f, New value: %f (double)", old_param->value.double_value,
new_param->value.double_value);
break;
default:
break;
}
printf("\n");
}
return true;
}
Parameters modifications are disabled while the callback on_parameter_changed
is executed, causing the following methods to return RCLC_PARAMETER_DISABLED_ON_CALLBACK
if they are invoked:
- rclc_add_parameter
- rclc_delete_parameter
- rclc_parameter_set_bool
- rclc_parameter_set_int
- rclc_parameter_set_double
- rclc_set_parameter_read_only
- rclc_add_parameter_constraint_double
- rclc_add_parameter_constraint_integer
Once the parameter server and the executor are initialized, the parameter server must be added to the executor in order to accept parameter commands from ROS 2:
// Add parameter server to the executor including defined callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, on_parameter_changed);
Note that this callback is optional as its just an event information for the user. To use the parameter server without a callback:
// Add parameter server to the executor without a callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, NULL);
Configuration of the callback context:
// Add parameter server to the executor including defined callback and a context
rc = rclc_executor_add_parameter_server_with_context(&executor, ¶m_server, on_parameter_changed, &context);
Add a parameter
The micro-ROS parameter server supports the following parameter types:
- Boolean:
const char * parameter_name = "parameter_bool";
bool param_value = true;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_BOOL);
// Set parameter value (Triggers `on_parameter_changed` callback, if defined)
rc = rclc_parameter_set_bool(¶m_server, parameter_name, param_value);
// Get parameter value and store it in "param_value"
rc = rclc_parameter_get_bool(¶m_server, "param1", ¶m_value);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
- Integer:
const char * parameter_name = "parameter_int";
int param_value = 100;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_INT);
// Set parameter value
rc = rclc_parameter_set_int(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_int(¶m_server, parameter_name, ¶m_value);
- Double:
const char * parameter_name = "parameter_double";
double param_value = 0.15;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_DOUBLE);
// Set parameter value
rc = rclc_parameter_set_double(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_double(¶m_server, parameter_name, ¶m_value);
Parameters can also be created by external clients if the allow_undeclared_parameters
flag is set.
The client just needs to set a value on a non-existing parameter. Then this parameter will be created if the server has still capacity and the callback allows the operation.
Max name size is controlled by the compile-time option RCLC_PARAMETER_MAX_STRING_LENGTH
, default value is 50.
Delete a parameter
Parameters can be deleted by both, the parameter server and external clients:
rclc_delete_parameter(¶m_server, "param2");
Note that for external delete requests, the server callback will be executed, allowing the node to reject the operation.
Parameter description
- Parameter description
Adds a description of a parameter and its constrains, which will be returned on a describe parameter requests:
rclc_add_parameter_description(¶m_server, "param2", "Second parameter", "Only even numbers");
*The maximum string size is controlled by the compilation time option `RCLC_PARAMETER_MAX_STRING_LENGTH`, default value is 50.*
- Parameter constraints
Informative numeric constraints can be added to int and double parameters, returning this values on describe parameter requests:-
from_value
: Start value for valid values, inclusive. -
to_value
: End value for valid values, inclusive. -
step
: Size of valid steps between the from and to bound.
-
int64_t int_from = 0;
int64_t int_to = 20;
uint64_t int_step = 2;
rclc_add_parameter_constraint_integer(¶m_server, "param2", int_from, int_to, int_step);
double double_from = -0.5;
double double_to = 0.5;
double double_step = 0.01;
rclc_add_parameter_constraint_double(¶m_server, "param3", double_from, double_to, double_step);
*This constrains will not be applied by the parameter server, leaving values filtering to the user callback.*
- Read-only parameters:
The new API offers a read-only flag. This flag blocks parameter changes from external clients, but allows changes on the server side:
bool read_only = true;
rclc_set_parameter_read_only(¶m_server, "param3", read_only);
Cleaning up
To destroy an initialized parameter server:
// Delete parameter server
rclc_parameter_server_fini(¶m_server, &node);
This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.
Changelog for package rclc_parameter
4.0.2 (2023-03-22)
- Fix parameter change event (#310)
4.0.1 (2022-07-20)
- improved doxygen-generated API documentation (#301) (#302)
4.0.0 (2022-04-28)
- updated version for Humble release
3.0.8 (2022-04-14)
- Parameters fini memory (#253)
- Fix RCLC int parameter get (cherry-pick) (#272)
- rclc_parameter: Fix rcl return values (#270)
- Upgrade parameters (#274)
3.0.7 (2022-02-17)
- no changes
3.0.6 (2022-01-25)
- Add thread dependency to examples (Rolling) (#237) (resolves in this package only cpplint errors)
3.0.5 (2021-11-23)
- no change
3.0.4 (2021-11-17)
- Add rclc_parameter Quality Declaration (#144)
- Check all dynamic allocations in parameter server init (#169)
3.0.3 (2021-07-28)
- Version bump
3.0.2 (2021-07-26)
- Add test dependencies for rclc_parameter
3.0.1 (2021-07-17)
- Removed shared from rclc_parameter
- Ensure clean message when set_parameter
- Added QoS entity creation API
- Updated CMakeLists.txt
- Major vesion bump was neccessary because API change in rcl_lifecycle package
0.1.0 (2021-05-27)
- Initial release
Wiki Tutorials
Package Dependencies
System Dependencies
Dependant Packages
Name | Deps |
---|---|
rclc_examples |
Launch files
Messages
Services
Plugins
Recent questions tagged rclc_parameter at Robotics Stack Exchange
rclc_parameter package from rclc reporclc rclc_examples rclc_lifecycle rclc_parameter |
|
Package Summary
Tags | No category tags. |
Version | 5.0.1 |
License | Apache License 2.0 |
Build type | AMENT_CMAKE |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/ros2/rclc.git |
VCS Type | git |
VCS Version | iron |
Last Updated | 2023-12-14 |
Dev Status | DEVELOPED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Antonio Cuadros
Authors
- Antonio Cuadros
The rclc parameter package
ROS 2 parameters allow the user to create variables on a node and manipulate/read them with different ROS 2 commands. Further information about ROS 2 parameters can be found here
This package provides the rclc API with parameter server instances with full ROS 2 parameter client compatibility. A parameter client has not been implemented for rclc (yet).
Ready to use code examples related to this tutorial can be found in rclc/rclc_examples/src/example_parameter_server.c
.
Table of contents
- Initialization
- Memory requirements
- Callback
- Add a parameter
- Delete a parameter
- Parameter description
- Cleaning up
Initialization
- Default initialization:
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server with default configuration
rcl_ret_t rc = rclc_parameter_server_init_default(¶m_server, &node);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Custom options:
The following options can be configured:
- notify_changed_over_dds: Publish parameter events to other ROS 2 nodes as well.
- max_params: Maximum number of parameters allowed on the
rclc_parameter_server_t
object. - allow_undeclared_parameters: Allows creation of parameters from external parameter clients. A new parameter will be created if a
set
operation is requested on a non-existing parameter. - low_mem_mode: Reduces the memory used by the parameter server, functionality constrains are applied.
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server options
const rclc_parameter_options_t options = {
.notify_changed_over_dds = true,
.max_params = 4,
.allow_undeclared_parameters = true,
.low_mem_mode = false; };
// Initialize parameter server with configured options
rcl_ret_t rc = rclc_parameter_server_init_with_option(¶m_server, &node, &options);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Low memory mode:
This mode ports the parameter functionality to memory constrained devices. The following constrains are applied:
- Request size limited to one parameter on Set, Get, Get types and Describe services.
- List parameter request has no prefixes enabled nor depth.
- Parameter description strings not allowed,
rclc_add_parameter_description
is disabled.
Memory benchmark results on
STM32F4
for 7 parameters withRCLC_PARAMETER_MAX_STRING_LENGTH = 50
andnotify_changed_over_dds = true
:- Full mode: 11736 B
- Low memory mode: 4160 B
Memory requirements
The parameter server uses five services and an optional publisher. These need to be taken into account on the rmw-microxrcedds
package memory configuration:
# colcon.meta example with memory requirements to use a parameter server
{
"names": {
"rmw_microxrcedds": {
"cmake-args": [
"-DRMW_UXRCE_MAX_NODES=1",
"-DRMW_UXRCE_MAX_PUBLISHERS=1",
"-DRMW_UXRCE_MAX_SUBSCRIPTIONS=0",
"-DRMW_UXRCE_MAX_SERVICES=5",
"-DRMW_UXRCE_MAX_CLIENTS=0"
]
}
}
}
At runtime, the variable RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES
defines the necessary number of handles required by a parameter server for the rclc Executor:
// Executor init example with the minimum RCLC executor handles required
rclc_executor_t executor = rclc_executor_get_zero_initialized_executor();
rc = rclc_executor_init(
&executor, &support.context,
RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES, &allocator);
Callback
When adding the parameter server to the executor, a callback could to be configured. This callback would then be executed on the following events:
- Parameter value change: Internal and external parameter set on existing parameters.
- Parameter creation: External parameter set on unexisting parameter if
allow_undeclared_parameters
is set. - Parameter delete: External parameter delete on existing parameter.
- The user can allow or reject this operations using the
bool
return value.
Callback parameters:
-
old_param
: Parameter actual value,NULL
for new parameter request. -
new_param
: Parameter new value,NULL
for parameter removal request. -
context
: User context, configured onrclc_executor_add_parameter_server_with_context
.
bool on_parameter_changed(const Parameter * old_param, const Parameter * new_param, void * context)
{
(void) context;
if (old_param == NULL && new_param == NULL) {
printf("Callback error, both parameters are NULL\n");
return false;
}
if (old_param == NULL) {
printf("Creating new parameter %s\n", new_param->name.data);
} else if (new_param == NULL) {
printf("Deleting parameter %s\n", old_param->name.data);
} else {
printf("Parameter %s modified.", old_param->name.data);
switch (old_param->value.type) {
case RCLC_PARAMETER_BOOL:
printf(
" Old value: %d, New value: %d (bool)", old_param->value.bool_value,
new_param->value.bool_value);
break;
case RCLC_PARAMETER_INT:
printf(
" Old value: %ld, New value: %ld (int)", old_param->value.integer_value,
new_param->value.integer_value);
break;
case RCLC_PARAMETER_DOUBLE:
printf(
" Old value: %f, New value: %f (double)", old_param->value.double_value,
new_param->value.double_value);
break;
default:
break;
}
printf("\n");
}
return true;
}
Parameters modifications are disabled while the callback on_parameter_changed
is executed, causing the following methods to return RCLC_PARAMETER_DISABLED_ON_CALLBACK
if they are invoked:
- rclc_add_parameter
- rclc_delete_parameter
- rclc_parameter_set_bool
- rclc_parameter_set_int
- rclc_parameter_set_double
- rclc_set_parameter_read_only
- rclc_add_parameter_constraint_double
- rclc_add_parameter_constraint_integer
Once the parameter server and the executor are initialized, the parameter server must be added to the executor in order to accept parameter commands from ROS 2:
// Add parameter server to the executor including defined callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, on_parameter_changed);
Note that this callback is optional as its just an event information for the user. To use the parameter server without a callback:
// Add parameter server to the executor without a callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, NULL);
Configuration of the callback context:
// Add parameter server to the executor including defined callback and a context
rc = rclc_executor_add_parameter_server_with_context(&executor, ¶m_server, on_parameter_changed, &context);
Add a parameter
The micro-ROS parameter server supports the following parameter types:
- Boolean:
const char * parameter_name = "parameter_bool";
bool param_value = true;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_BOOL);
// Set parameter value (Triggers `on_parameter_changed` callback, if defined)
rc = rclc_parameter_set_bool(¶m_server, parameter_name, param_value);
// Get parameter value and store it in "param_value"
rc = rclc_parameter_get_bool(¶m_server, "param1", ¶m_value);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
- Integer:
const char * parameter_name = "parameter_int";
int param_value = 100;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_INT);
// Set parameter value
rc = rclc_parameter_set_int(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_int(¶m_server, parameter_name, ¶m_value);
- Double:
const char * parameter_name = "parameter_double";
double param_value = 0.15;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_DOUBLE);
// Set parameter value
rc = rclc_parameter_set_double(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_double(¶m_server, parameter_name, ¶m_value);
Parameters can also be created by external clients if the allow_undeclared_parameters
flag is set.
The client just needs to set a value on a non-existing parameter. Then this parameter will be created if the server has still capacity and the callback allows the operation.
Max name size is controlled by the compile-time option RCLC_PARAMETER_MAX_STRING_LENGTH
, default value is 50.
Delete a parameter
Parameters can be deleted by both, the parameter server and external clients:
rclc_delete_parameter(¶m_server, "param2");
Note that for external delete requests, the server callback will be executed, allowing the node to reject the operation.
Parameter description
- Parameter description
Adds a description of a parameter and its constrains, which will be returned on a describe parameter requests:
rclc_add_parameter_description(¶m_server, "param2", "Second parameter", "Only even numbers");
*The maximum string size is controlled by the compilation time option `RCLC_PARAMETER_MAX_STRING_LENGTH`, default value is 50.*
- Parameter constraints
Informative numeric constraints can be added to int and double parameters, returning this values on describe parameter requests:-
from_value
: Start value for valid values, inclusive. -
to_value
: End value for valid values, inclusive. -
step
: Size of valid steps between the from and to bound.
-
int64_t int_from = 0;
int64_t int_to = 20;
uint64_t int_step = 2;
rclc_add_parameter_constraint_integer(¶m_server, "param2", int_from, int_to, int_step);
double double_from = -0.5;
double double_to = 0.5;
double double_step = 0.01;
rclc_add_parameter_constraint_double(¶m_server, "param3", double_from, double_to, double_step);
*This constrains will not be applied by the parameter server, leaving values filtering to the user callback.*
- Read-only parameters:
The new API offers a read-only flag. This flag blocks parameter changes from external clients, but allows changes on the server side:
bool read_only = true;
rclc_set_parameter_read_only(¶m_server, "param3", read_only);
Cleaning up
To destroy an initialized parameter server:
// Delete parameter server
rclc_parameter_server_fini(¶m_server, &node);
This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.
Changelog for package rclc_parameter
5.0.1 (2023-06-15)
- Add empty set_atomically parameter service (#354)
3.0.9 (2023-03-22)
- Added documentation (#301)
- Fix parameter change event (#310) (#311)
3.0.8 (2022-04-14)
- Parameters fini memory (#253)
- Fix RCLC int parameter get (cherry-pick) (#272)
- rclc_parameter: Fix rcl return values (#270)
- Upgrade parameters (#274)
3.0.7 (2022-02-17)
- no changes
3.0.6 (2022-01-25)
- Add thread dependency to examples (Rolling) (#237) (resolves in this package only cpplint errors)
3.0.5 (2021-11-23)
- no change
3.0.4 (2021-11-17)
- Add rclc_parameter Quality Declaration (#144)
- Check all dynamic allocations in parameter server init (#169)
3.0.3 (2021-07-28)
- Version bump
3.0.2 (2021-07-26)
- Add test dependencies for rclc_parameter
3.0.1 (2021-07-17)
- Removed shared from rclc_parameter
- Ensure clean message when set_parameter
- Added QoS entity creation API
- Updated CMakeLists.txt
- Major vesion bump was neccessary because API change in rcl_lifecycle package
0.1.0 (2021-05-27)
- Initial release
Wiki Tutorials
Package Dependencies
System Dependencies
Dependant Packages
Name | Deps |
---|---|
rclc_examples |
Launch files
Messages
Services
Plugins
Recent questions tagged rclc_parameter at Robotics Stack Exchange
rclc_parameter package from rclc reporclc rclc_examples rclc_lifecycle rclc_parameter |
|
Package Summary
Tags | No category tags. |
Version | 6.1.0 |
License | Apache License 2.0 |
Build type | AMENT_CMAKE |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/ros2/rclc.git |
VCS Type | git |
VCS Version | rolling |
Last Updated | 2024-09-24 |
Dev Status | DEVELOPED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Antonio Cuadros
Authors
- Antonio Cuadros
The rclc parameter package
ROS 2 parameters allow the user to create variables on a node and manipulate/read them with different ROS 2 commands. Further information about ROS 2 parameters can be found here
This package provides the rclc API with parameter server instances with full ROS 2 parameter client compatibility. A parameter client has not been implemented for rclc (yet).
Ready to use code examples related to this tutorial can be found in rclc/rclc_examples/src/example_parameter_server.c
.
Table of contents
- Initialization
- Memory requirements
- Callback
- Add a parameter
- Delete a parameter
- Parameter description
- Cleaning up
Initialization
- Default initialization:
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server with default configuration
rcl_ret_t rc = rclc_parameter_server_init_default(¶m_server, &node);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Custom options:
The following options can be configured:
- notify_changed_over_dds: Publish parameter events to other ROS 2 nodes as well.
- max_params: Maximum number of parameters allowed on the
rclc_parameter_server_t
object. - allow_undeclared_parameters: Allows creation of parameters from external parameter clients. A new parameter will be created if a
set
operation is requested on a non-existing parameter. - low_mem_mode: Reduces the memory used by the parameter server, functionality constrains are applied.
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server options
const rclc_parameter_options_t options = {
.notify_changed_over_dds = true,
.max_params = 4,
.allow_undeclared_parameters = true,
.low_mem_mode = false; };
// Initialize parameter server with configured options
rcl_ret_t rc = rclc_parameter_server_init_with_option(¶m_server, &node, &options);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Low memory mode:
This mode ports the parameter functionality to memory constrained devices. The following constrains are applied:
- Request size limited to one parameter on Set, Get, Get types and Describe services.
- List parameter request has no prefixes enabled nor depth.
- Parameter description strings not allowed,
rclc_add_parameter_description
is disabled.
Memory benchmark results on
STM32F4
for 7 parameters withRCLC_PARAMETER_MAX_STRING_LENGTH = 50
andnotify_changed_over_dds = true
:- Full mode: 11736 B
- Low memory mode: 4160 B
Memory requirements
The parameter server uses five services and an optional publisher. These need to be taken into account on the rmw-microxrcedds
package memory configuration:
# colcon.meta example with memory requirements to use a parameter server
{
"names": {
"rmw_microxrcedds": {
"cmake-args": [
"-DRMW_UXRCE_MAX_NODES=1",
"-DRMW_UXRCE_MAX_PUBLISHERS=1",
"-DRMW_UXRCE_MAX_SUBSCRIPTIONS=0",
"-DRMW_UXRCE_MAX_SERVICES=5",
"-DRMW_UXRCE_MAX_CLIENTS=0"
]
}
}
}
At runtime, the variable RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES
defines the necessary number of handles required by a parameter server for the rclc Executor:
// Executor init example with the minimum RCLC executor handles required
rclc_executor_t executor = rclc_executor_get_zero_initialized_executor();
rc = rclc_executor_init(
&executor, &support.context,
RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES, &allocator);
Callback
When adding the parameter server to the executor, a callback could to be configured. This callback would then be executed on the following events:
- Parameter value change: Internal and external parameter set on existing parameters.
- Parameter creation: External parameter set on unexisting parameter if
allow_undeclared_parameters
is set. - Parameter delete: External parameter delete on existing parameter.
- The user can allow or reject this operations using the
bool
return value.
Callback parameters:
-
old_param
: Parameter actual value,NULL
for new parameter request. -
new_param
: Parameter new value,NULL
for parameter removal request. -
context
: User context, configured onrclc_executor_add_parameter_server_with_context
.
bool on_parameter_changed(const Parameter * old_param, const Parameter * new_param, void * context)
{
(void) context;
if (old_param == NULL && new_param == NULL) {
printf("Callback error, both parameters are NULL\n");
return false;
}
if (old_param == NULL) {
printf("Creating new parameter %s\n", new_param->name.data);
} else if (new_param == NULL) {
printf("Deleting parameter %s\n", old_param->name.data);
} else {
printf("Parameter %s modified.", old_param->name.data);
switch (old_param->value.type) {
case RCLC_PARAMETER_BOOL:
printf(
" Old value: %d, New value: %d (bool)", old_param->value.bool_value,
new_param->value.bool_value);
break;
case RCLC_PARAMETER_INT:
printf(
" Old value: %ld, New value: %ld (int)", old_param->value.integer_value,
new_param->value.integer_value);
break;
case RCLC_PARAMETER_DOUBLE:
printf(
" Old value: %f, New value: %f (double)", old_param->value.double_value,
new_param->value.double_value);
break;
default:
break;
}
printf("\n");
}
return true;
}
Parameters modifications are disabled while the callback on_parameter_changed
is executed, causing the following methods to return RCLC_PARAMETER_DISABLED_ON_CALLBACK
if they are invoked:
- rclc_add_parameter
- rclc_delete_parameter
- rclc_parameter_set_bool
- rclc_parameter_set_int
- rclc_parameter_set_double
- rclc_set_parameter_read_only
- rclc_add_parameter_constraint_double
- rclc_add_parameter_constraint_integer
Once the parameter server and the executor are initialized, the parameter server must be added to the executor in order to accept parameter commands from ROS 2:
// Add parameter server to the executor including defined callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, on_parameter_changed);
Note that this callback is optional as its just an event information for the user. To use the parameter server without a callback:
// Add parameter server to the executor without a callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, NULL);
Configuration of the callback context:
// Add parameter server to the executor including defined callback and a context
rc = rclc_executor_add_parameter_server_with_context(&executor, ¶m_server, on_parameter_changed, &context);
Add a parameter
The micro-ROS parameter server supports the following parameter types:
- Boolean:
const char * parameter_name = "parameter_bool";
bool param_value = true;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_BOOL);
// Set parameter value (Triggers `on_parameter_changed` callback, if defined)
rc = rclc_parameter_set_bool(¶m_server, parameter_name, param_value);
// Get parameter value and store it in "param_value"
rc = rclc_parameter_get_bool(¶m_server, "param1", ¶m_value);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
- Integer:
const char * parameter_name = "parameter_int";
int param_value = 100;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_INT);
// Set parameter value
rc = rclc_parameter_set_int(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_int(¶m_server, parameter_name, ¶m_value);
- Double:
const char * parameter_name = "parameter_double";
double param_value = 0.15;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_DOUBLE);
// Set parameter value
rc = rclc_parameter_set_double(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_double(¶m_server, parameter_name, ¶m_value);
Parameters can also be created by external clients if the allow_undeclared_parameters
flag is set.
The client just needs to set a value on a non-existing parameter. Then this parameter will be created if the server has still capacity and the callback allows the operation.
Max name size is controlled by the compile-time option RCLC_PARAMETER_MAX_STRING_LENGTH
, default value is 50.
Delete a parameter
Parameters can be deleted by both, the parameter server and external clients:
rclc_delete_parameter(¶m_server, "param2");
Note that for external delete requests, the server callback will be executed, allowing the node to reject the operation.
Parameter description
- Parameter description
Adds a description of a parameter and its constrains, which will be returned on a describe parameter requests:
rclc_add_parameter_description(¶m_server, "param2", "Second parameter", "Only even numbers");
*The maximum string size is controlled by the compilation time option `RCLC_PARAMETER_MAX_STRING_LENGTH`, default value is 50.*
- Parameter constraints
Informative numeric constraints can be added to int and double parameters, returning this values on describe parameter requests:-
from_value
: Start value for valid values, inclusive. -
to_value
: End value for valid values, inclusive. -
step
: Size of valid steps between the from and to bound.
-
int64_t int_from = 0;
int64_t int_to = 20;
uint64_t int_step = 2;
rclc_add_parameter_constraint_integer(¶m_server, "param2", int_from, int_to, int_step);
double double_from = -0.5;
double double_to = 0.5;
double double_step = 0.01;
rclc_add_parameter_constraint_double(¶m_server, "param3", double_from, double_to, double_step);
*This constrains will not be applied by the parameter server, leaving values filtering to the user callback.*
- Read-only parameters:
The new API offers a read-only flag. This flag blocks parameter changes from external clients, but allows changes on the server side:
bool read_only = true;
rclc_set_parameter_read_only(¶m_server, "param3", read_only);
Cleaning up
To destroy an initialized parameter server:
// Delete parameter server
rclc_parameter_server_fini(¶m_server, &node);
This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.
Changelog for package rclc_parameter
6.1.0 (2023-06-15)
- Add empty set_atomically parameter service (#354)
3.0.9 (2023-03-22)
- Added documentation (#301)
- Fix parameter change event (#310) (#311)
3.0.8 (2022-04-14)
- Parameters fini memory (#253)
- Fix RCLC int parameter get (cherry-pick) (#272)
- rclc_parameter: Fix rcl return values (#270)
- Upgrade parameters (#274)
3.0.7 (2022-02-17)
- no changes
3.0.6 (2022-01-25)
- Add thread dependency to examples (Rolling) (#237) (resolves in this package only cpplint errors)
3.0.5 (2021-11-23)
- no change
3.0.4 (2021-11-17)
- Add rclc_parameter Quality Declaration (#144)
- Check all dynamic allocations in parameter server init (#169)
3.0.3 (2021-07-28)
- Version bump
3.0.2 (2021-07-26)
- Add test dependencies for rclc_parameter
3.0.1 (2021-07-17)
- Removed shared from rclc_parameter
- Ensure clean message when set_parameter
- Added QoS entity creation API
- Updated CMakeLists.txt
- Major vesion bump was neccessary because API change in rcl_lifecycle package
0.1.0 (2021-05-27)
- Initial release
Wiki Tutorials
Package Dependencies
System Dependencies
Dependant Packages
Name | Deps |
---|---|
rclc_examples |
Launch files
Messages
Services
Plugins
Recent questions tagged rclc_parameter at Robotics Stack Exchange
rclc_parameter package from rclc reporclc rclc_examples rclc_lifecycle rclc_parameter |
|
Package Summary
Tags | No category tags. |
Version | 6.1.0 |
License | Apache License 2.0 |
Build type | AMENT_CMAKE |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/ros2/rclc.git |
VCS Type | git |
VCS Version | rolling |
Last Updated | 2024-09-24 |
Dev Status | DEVELOPED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Antonio Cuadros
Authors
- Antonio Cuadros
The rclc parameter package
ROS 2 parameters allow the user to create variables on a node and manipulate/read them with different ROS 2 commands. Further information about ROS 2 parameters can be found here
This package provides the rclc API with parameter server instances with full ROS 2 parameter client compatibility. A parameter client has not been implemented for rclc (yet).
Ready to use code examples related to this tutorial can be found in rclc/rclc_examples/src/example_parameter_server.c
.
Table of contents
- Initialization
- Memory requirements
- Callback
- Add a parameter
- Delete a parameter
- Parameter description
- Cleaning up
Initialization
- Default initialization:
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server with default configuration
rcl_ret_t rc = rclc_parameter_server_init_default(¶m_server, &node);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Custom options:
The following options can be configured:
- notify_changed_over_dds: Publish parameter events to other ROS 2 nodes as well.
- max_params: Maximum number of parameters allowed on the
rclc_parameter_server_t
object. - allow_undeclared_parameters: Allows creation of parameters from external parameter clients. A new parameter will be created if a
set
operation is requested on a non-existing parameter. - low_mem_mode: Reduces the memory used by the parameter server, functionality constrains are applied.
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server options
const rclc_parameter_options_t options = {
.notify_changed_over_dds = true,
.max_params = 4,
.allow_undeclared_parameters = true,
.low_mem_mode = false; };
// Initialize parameter server with configured options
rcl_ret_t rc = rclc_parameter_server_init_with_option(¶m_server, &node, &options);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Low memory mode:
This mode ports the parameter functionality to memory constrained devices. The following constrains are applied:
- Request size limited to one parameter on Set, Get, Get types and Describe services.
- List parameter request has no prefixes enabled nor depth.
- Parameter description strings not allowed,
rclc_add_parameter_description
is disabled.
Memory benchmark results on
STM32F4
for 7 parameters withRCLC_PARAMETER_MAX_STRING_LENGTH = 50
andnotify_changed_over_dds = true
:- Full mode: 11736 B
- Low memory mode: 4160 B
Memory requirements
The parameter server uses five services and an optional publisher. These need to be taken into account on the rmw-microxrcedds
package memory configuration:
# colcon.meta example with memory requirements to use a parameter server
{
"names": {
"rmw_microxrcedds": {
"cmake-args": [
"-DRMW_UXRCE_MAX_NODES=1",
"-DRMW_UXRCE_MAX_PUBLISHERS=1",
"-DRMW_UXRCE_MAX_SUBSCRIPTIONS=0",
"-DRMW_UXRCE_MAX_SERVICES=5",
"-DRMW_UXRCE_MAX_CLIENTS=0"
]
}
}
}
At runtime, the variable RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES
defines the necessary number of handles required by a parameter server for the rclc Executor:
// Executor init example with the minimum RCLC executor handles required
rclc_executor_t executor = rclc_executor_get_zero_initialized_executor();
rc = rclc_executor_init(
&executor, &support.context,
RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES, &allocator);
Callback
When adding the parameter server to the executor, a callback could to be configured. This callback would then be executed on the following events:
- Parameter value change: Internal and external parameter set on existing parameters.
- Parameter creation: External parameter set on unexisting parameter if
allow_undeclared_parameters
is set. - Parameter delete: External parameter delete on existing parameter.
- The user can allow or reject this operations using the
bool
return value.
Callback parameters:
-
old_param
: Parameter actual value,NULL
for new parameter request. -
new_param
: Parameter new value,NULL
for parameter removal request. -
context
: User context, configured onrclc_executor_add_parameter_server_with_context
.
bool on_parameter_changed(const Parameter * old_param, const Parameter * new_param, void * context)
{
(void) context;
if (old_param == NULL && new_param == NULL) {
printf("Callback error, both parameters are NULL\n");
return false;
}
if (old_param == NULL) {
printf("Creating new parameter %s\n", new_param->name.data);
} else if (new_param == NULL) {
printf("Deleting parameter %s\n", old_param->name.data);
} else {
printf("Parameter %s modified.", old_param->name.data);
switch (old_param->value.type) {
case RCLC_PARAMETER_BOOL:
printf(
" Old value: %d, New value: %d (bool)", old_param->value.bool_value,
new_param->value.bool_value);
break;
case RCLC_PARAMETER_INT:
printf(
" Old value: %ld, New value: %ld (int)", old_param->value.integer_value,
new_param->value.integer_value);
break;
case RCLC_PARAMETER_DOUBLE:
printf(
" Old value: %f, New value: %f (double)", old_param->value.double_value,
new_param->value.double_value);
break;
default:
break;
}
printf("\n");
}
return true;
}
Parameters modifications are disabled while the callback on_parameter_changed
is executed, causing the following methods to return RCLC_PARAMETER_DISABLED_ON_CALLBACK
if they are invoked:
- rclc_add_parameter
- rclc_delete_parameter
- rclc_parameter_set_bool
- rclc_parameter_set_int
- rclc_parameter_set_double
- rclc_set_parameter_read_only
- rclc_add_parameter_constraint_double
- rclc_add_parameter_constraint_integer
Once the parameter server and the executor are initialized, the parameter server must be added to the executor in order to accept parameter commands from ROS 2:
// Add parameter server to the executor including defined callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, on_parameter_changed);
Note that this callback is optional as its just an event information for the user. To use the parameter server without a callback:
// Add parameter server to the executor without a callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, NULL);
Configuration of the callback context:
// Add parameter server to the executor including defined callback and a context
rc = rclc_executor_add_parameter_server_with_context(&executor, ¶m_server, on_parameter_changed, &context);
Add a parameter
The micro-ROS parameter server supports the following parameter types:
- Boolean:
const char * parameter_name = "parameter_bool";
bool param_value = true;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_BOOL);
// Set parameter value (Triggers `on_parameter_changed` callback, if defined)
rc = rclc_parameter_set_bool(¶m_server, parameter_name, param_value);
// Get parameter value and store it in "param_value"
rc = rclc_parameter_get_bool(¶m_server, "param1", ¶m_value);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
- Integer:
const char * parameter_name = "parameter_int";
int param_value = 100;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_INT);
// Set parameter value
rc = rclc_parameter_set_int(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_int(¶m_server, parameter_name, ¶m_value);
- Double:
const char * parameter_name = "parameter_double";
double param_value = 0.15;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_DOUBLE);
// Set parameter value
rc = rclc_parameter_set_double(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_double(¶m_server, parameter_name, ¶m_value);
Parameters can also be created by external clients if the allow_undeclared_parameters
flag is set.
The client just needs to set a value on a non-existing parameter. Then this parameter will be created if the server has still capacity and the callback allows the operation.
Max name size is controlled by the compile-time option RCLC_PARAMETER_MAX_STRING_LENGTH
, default value is 50.
Delete a parameter
Parameters can be deleted by both, the parameter server and external clients:
rclc_delete_parameter(¶m_server, "param2");
Note that for external delete requests, the server callback will be executed, allowing the node to reject the operation.
Parameter description
- Parameter description
Adds a description of a parameter and its constrains, which will be returned on a describe parameter requests:
rclc_add_parameter_description(¶m_server, "param2", "Second parameter", "Only even numbers");
*The maximum string size is controlled by the compilation time option `RCLC_PARAMETER_MAX_STRING_LENGTH`, default value is 50.*
- Parameter constraints
Informative numeric constraints can be added to int and double parameters, returning this values on describe parameter requests:-
from_value
: Start value for valid values, inclusive. -
to_value
: End value for valid values, inclusive. -
step
: Size of valid steps between the from and to bound.
-
int64_t int_from = 0;
int64_t int_to = 20;
uint64_t int_step = 2;
rclc_add_parameter_constraint_integer(¶m_server, "param2", int_from, int_to, int_step);
double double_from = -0.5;
double double_to = 0.5;
double double_step = 0.01;
rclc_add_parameter_constraint_double(¶m_server, "param3", double_from, double_to, double_step);
*This constrains will not be applied by the parameter server, leaving values filtering to the user callback.*
- Read-only parameters:
The new API offers a read-only flag. This flag blocks parameter changes from external clients, but allows changes on the server side:
bool read_only = true;
rclc_set_parameter_read_only(¶m_server, "param3", read_only);
Cleaning up
To destroy an initialized parameter server:
// Delete parameter server
rclc_parameter_server_fini(¶m_server, &node);
This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.
Changelog for package rclc_parameter
6.1.0 (2023-06-15)
- Add empty set_atomically parameter service (#354)
3.0.9 (2023-03-22)
- Added documentation (#301)
- Fix parameter change event (#310) (#311)
3.0.8 (2022-04-14)
- Parameters fini memory (#253)
- Fix RCLC int parameter get (cherry-pick) (#272)
- rclc_parameter: Fix rcl return values (#270)
- Upgrade parameters (#274)
3.0.7 (2022-02-17)
- no changes
3.0.6 (2022-01-25)
- Add thread dependency to examples (Rolling) (#237) (resolves in this package only cpplint errors)
3.0.5 (2021-11-23)
- no change
3.0.4 (2021-11-17)
- Add rclc_parameter Quality Declaration (#144)
- Check all dynamic allocations in parameter server init (#169)
3.0.3 (2021-07-28)
- Version bump
3.0.2 (2021-07-26)
- Add test dependencies for rclc_parameter
3.0.1 (2021-07-17)
- Removed shared from rclc_parameter
- Ensure clean message when set_parameter
- Added QoS entity creation API
- Updated CMakeLists.txt
- Major vesion bump was neccessary because API change in rcl_lifecycle package
0.1.0 (2021-05-27)
- Initial release
Wiki Tutorials
Package Dependencies
System Dependencies
Dependant Packages
Name | Deps |
---|---|
rclc_examples |
Launch files
Messages
Services
Plugins
Recent questions tagged rclc_parameter at Robotics Stack Exchange
rclc_parameter package from rclc reporclc rclc_examples rclc_lifecycle rclc_parameter |
|
Package Summary
Tags | No category tags. |
Version | 6.0.0 |
License | Apache License 2.0 |
Build type | AMENT_CMAKE |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/ros2/rclc.git |
VCS Type | git |
VCS Version | master |
Last Updated | 2023-06-23 |
Dev Status | DEVELOPED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Antonio Cuadros
Authors
- Antonio Cuadros
The rclc parameter package
ROS 2 parameters allow the user to create variables on a node and manipulate/read them with different ROS 2 commands. Further information about ROS 2 parameters can be found here
This package provides the rclc API with parameter server instances with full ROS 2 parameter client compatibility. A parameter client has not been implemented for rclc (yet).
Ready to use code examples related to this tutorial can be found in rclc/rclc_examples/src/example_parameter_server.c
.
Table of contents
- Initialization
- Memory requirements
- Callback
- Add a parameter
- Delete a parameter
- Parameter description
- Cleaning up
Initialization
- Default initialization:
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server with default configuration
rcl_ret_t rc = rclc_parameter_server_init_default(¶m_server, &node);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Custom options:
The following options can be configured:
- notify_changed_over_dds: Publish parameter events to other ROS 2 nodes as well.
- max_params: Maximum number of parameters allowed on the
rclc_parameter_server_t
object. - allow_undeclared_parameters: Allows creation of parameters from external parameter clients. A new parameter will be created if a
set
operation is requested on a non-existing parameter. - low_mem_mode: Reduces the memory used by the parameter server, functionality constrains are applied.
// Parameter server object
rclc_parameter_server_t param_server;
// Initialize parameter server options
const rclc_parameter_options_t options = {
.notify_changed_over_dds = true,
.max_params = 4,
.allow_undeclared_parameters = true,
.low_mem_mode = false; };
// Initialize parameter server with configured options
rcl_ret_t rc = rclc_parameter_server_init_with_option(¶m_server, &node, &options);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
-
Low memory mode:
This mode ports the parameter functionality to memory constrained devices. The following constrains are applied:
- Request size limited to one parameter on Set, Get, Get types and Describe services.
- List parameter request has no prefixes enabled nor depth.
- Parameter description strings not allowed,
rclc_add_parameter_description
is disabled.
Memory benchmark results on
STM32F4
for 7 parameters withRCLC_PARAMETER_MAX_STRING_LENGTH = 50
andnotify_changed_over_dds = true
:- Full mode: 11736 B
- Low memory mode: 4160 B
Memory requirements
The parameter server uses five services and an optional publisher. These need to be taken into account on the rmw-microxrcedds
package memory configuration:
# colcon.meta example with memory requirements to use a parameter server
{
"names": {
"rmw_microxrcedds": {
"cmake-args": [
"-DRMW_UXRCE_MAX_NODES=1",
"-DRMW_UXRCE_MAX_PUBLISHERS=1",
"-DRMW_UXRCE_MAX_SUBSCRIPTIONS=0",
"-DRMW_UXRCE_MAX_SERVICES=5",
"-DRMW_UXRCE_MAX_CLIENTS=0"
]
}
}
}
At runtime, the variable RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES
defines the necessary number of handles required by a parameter server for the rclc Executor:
// Executor init example with the minimum RCLC executor handles required
rclc_executor_t executor = rclc_executor_get_zero_initialized_executor();
rc = rclc_executor_init(
&executor, &support.context,
RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES, &allocator);
Callback
When adding the parameter server to the executor, a callback could to be configured. This callback would then be executed on the following events:
- Parameter value change: Internal and external parameter set on existing parameters.
- Parameter creation: External parameter set on unexisting parameter if
allow_undeclared_parameters
is set. - Parameter delete: External parameter delete on existing parameter.
- The user can allow or reject this operations using the
bool
return value.
Callback parameters:
-
old_param
: Parameter actual value,NULL
for new parameter request. -
new_param
: Parameter new value,NULL
for parameter removal request. -
context
: User context, configured onrclc_executor_add_parameter_server_with_context
.
bool on_parameter_changed(const Parameter * old_param, const Parameter * new_param, void * context)
{
(void) context;
if (old_param == NULL && new_param == NULL) {
printf("Callback error, both parameters are NULL\n");
return false;
}
if (old_param == NULL) {
printf("Creating new parameter %s\n", new_param->name.data);
} else if (new_param == NULL) {
printf("Deleting parameter %s\n", old_param->name.data);
} else {
printf("Parameter %s modified.", old_param->name.data);
switch (old_param->value.type) {
case RCLC_PARAMETER_BOOL:
printf(
" Old value: %d, New value: %d (bool)", old_param->value.bool_value,
new_param->value.bool_value);
break;
case RCLC_PARAMETER_INT:
printf(
" Old value: %ld, New value: %ld (int)", old_param->value.integer_value,
new_param->value.integer_value);
break;
case RCLC_PARAMETER_DOUBLE:
printf(
" Old value: %f, New value: %f (double)", old_param->value.double_value,
new_param->value.double_value);
break;
default:
break;
}
printf("\n");
}
return true;
}
Parameters modifications are disabled while the callback on_parameter_changed
is executed, causing the following methods to return RCLC_PARAMETER_DISABLED_ON_CALLBACK
if they are invoked:
- rclc_add_parameter
- rclc_delete_parameter
- rclc_parameter_set_bool
- rclc_parameter_set_int
- rclc_parameter_set_double
- rclc_set_parameter_read_only
- rclc_add_parameter_constraint_double
- rclc_add_parameter_constraint_integer
Once the parameter server and the executor are initialized, the parameter server must be added to the executor in order to accept parameter commands from ROS 2:
// Add parameter server to the executor including defined callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, on_parameter_changed);
Note that this callback is optional as its just an event information for the user. To use the parameter server without a callback:
// Add parameter server to the executor without a callback
rc = rclc_executor_add_parameter_server(&executor, ¶m_server, NULL);
Configuration of the callback context:
// Add parameter server to the executor including defined callback and a context
rc = rclc_executor_add_parameter_server_with_context(&executor, ¶m_server, on_parameter_changed, &context);
Add a parameter
The micro-ROS parameter server supports the following parameter types:
- Boolean:
const char * parameter_name = "parameter_bool";
bool param_value = true;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_BOOL);
// Set parameter value (Triggers `on_parameter_changed` callback, if defined)
rc = rclc_parameter_set_bool(¶m_server, parameter_name, param_value);
// Get parameter value and store it in "param_value"
rc = rclc_parameter_get_bool(¶m_server, "param1", ¶m_value);
if (RCL_RET_OK != rc) {
... // Handle error
return -1;
}
- Integer:
const char * parameter_name = "parameter_int";
int param_value = 100;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_INT);
// Set parameter value
rc = rclc_parameter_set_int(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_int(¶m_server, parameter_name, ¶m_value);
- Double:
const char * parameter_name = "parameter_double";
double param_value = 0.15;
// Add parameter to the server
rcl_ret_t rc = rclc_add_parameter(¶m_server, parameter_name, RCLC_PARAMETER_DOUBLE);
// Set parameter value
rc = rclc_parameter_set_double(¶m_server, parameter_name, param_value);
// Get parameter value on param_value
rc = rclc_parameter_get_double(¶m_server, parameter_name, ¶m_value);
Parameters can also be created by external clients if the allow_undeclared_parameters
flag is set.
The client just needs to set a value on a non-existing parameter. Then this parameter will be created if the server has still capacity and the callback allows the operation.
Max name size is controlled by the compile-time option RCLC_PARAMETER_MAX_STRING_LENGTH
, default value is 50.
Delete a parameter
Parameters can be deleted by both, the parameter server and external clients:
rclc_delete_parameter(¶m_server, "param2");
Note that for external delete requests, the server callback will be executed, allowing the node to reject the operation.
Parameter description
- Parameter description
Adds a description of a parameter and its constrains, which will be returned on a describe parameter requests:
rclc_add_parameter_description(¶m_server, "param2", "Second parameter", "Only even numbers");
*The maximum string size is controlled by the compilation time option `RCLC_PARAMETER_MAX_STRING_LENGTH`, default value is 50.*
- Parameter constraints
Informative numeric constraints can be added to int and double parameters, returning this values on describe parameter requests:-
from_value
: Start value for valid values, inclusive. -
to_value
: End value for valid values, inclusive. -
step
: Size of valid steps between the from and to bound.
-
int64_t int_from = 0;
int64_t int_to = 20;
uint64_t int_step = 2;
rclc_add_parameter_constraint_integer(¶m_server, "param2", int_from, int_to, int_step);
double double_from = -0.5;
double double_to = 0.5;
double double_step = 0.01;
rclc_add_parameter_constraint_double(¶m_server, "param3", double_from, double_to, double_step);
*This constrains will not be applied by the parameter server, leaving values filtering to the user callback.*
- Read-only parameters:
The new API offers a read-only flag. This flag blocks parameter changes from external clients, but allows changes on the server side:
bool read_only = true;
rclc_set_parameter_read_only(¶m_server, "param3", read_only);
Cleaning up
To destroy an initialized parameter server:
// Delete parameter server
rclc_parameter_server_fini(¶m_server, &node);
This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.
Changelog for package rclc_parameter
6.0.0 (2023-06-15)
- Add empty set_atomically parameter service (#354)
3.0.9 (2023-03-22)
- Added documentation (#301)
- Fix parameter change event (#310) (#311)
3.0.8 (2022-04-14)
- Parameters fini memory (#253)
- Fix RCLC int parameter get (cherry-pick) (#272)
- rclc_parameter: Fix rcl return values (#270)
- Upgrade parameters (#274)
3.0.7 (2022-02-17)
- no changes
3.0.6 (2022-01-25)
- Add thread dependency to examples (Rolling) (#237) (resolves in this package only cpplint errors)
3.0.5 (2021-11-23)
- no change
3.0.4 (2021-11-17)
- Add rclc_parameter Quality Declaration (#144)
- Check all dynamic allocations in parameter server init (#169)
3.0.3 (2021-07-28)
- Version bump
3.0.2 (2021-07-26)
- Add test dependencies for rclc_parameter
3.0.1 (2021-07-17)
- Removed shared from rclc_parameter
- Ensure clean message when set_parameter
- Added QoS entity creation API
- Updated CMakeLists.txt
- Major vesion bump was neccessary because API change in rcl_lifecycle package
0.1.0 (2021-05-27)
- Initial release
Wiki Tutorials
Package Dependencies
System Dependencies
Dependant Packages
Name | Deps |
---|---|
rclc_examples |
Launch files
Messages
Services
Plugins
Recent questions tagged rclc_parameter at Robotics Stack Exchange
rclc_parameter package from rclc reporclc rclc_examples rclc_lifecycle rclc_parameter |
|
Package Summary
Tags | No category tags. |
Version | 2.0.6 |
License | Apache License 2.0 |
Build type | AMENT_CMAKE |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/ros2/rclc.git |
VCS Type | git |
VCS Version | galactic |
Last Updated | 2023-01-25 |
Dev Status | DEVELOPED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Antonio Cuadros
Authors
- Antonio Cuadros
Changelog for package rclc_parameter
2.0.6 (2022-01-25)
- no change
2.0.5 (2021-11-08)
- Fix parameter init
2.0.4 (2021-08-19)
- Added Quality Declaration Statement
2.0.3 (2021-07-26)
- Added test dependencies for rclc_parameter
2.0.2 (2021-07-17)
- Removed shared from rclc_parameter
- Ensure clean message when set_parameter
- Added QoS entity creation API
- Updated CMakeLists.txt
- Major vesion bump was neccessary because API change in rcl_lifecycle package
0.1.0 (2021-05-27)
- Initial release
Wiki Tutorials
Package Dependencies
System Dependencies
Dependant Packages
Name | Deps |
---|---|
rclc_examples |
Launch files
Messages
Services
Plugins
Recent questions tagged rclc_parameter at Robotics Stack Exchange
rclc_parameter package from rclc reporclc rclc_examples rclc_lifecycle rclc_parameter |
|
Package Summary
Tags | No category tags. |
Version | 1.1.2 |
License | Apache License 2.0 |
Build type | AMENT_CMAKE |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/ros2/rclc.git |
VCS Type | git |
VCS Version | foxy |
Last Updated | 2023-06-12 |
Dev Status | DEVELOPED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Antonio Cuadros
Authors
- Antonio Cuadros
Changelog for package rclc_parameter
1.1.2 (2023-03-31)
- Fix parameter tests timeout (backport #283) (#284)
- rclc_parameter: Fix rcl return values (backport #270) (#276)
- added documentation (#301) (#304)
1.1.1 (2022-03-16)
- Backport parameters (#263)
Wiki Tutorials
Package Dependencies
System Dependencies
Dependant Packages
Name | Deps |
---|---|
rclc_examples |