-
 

rclc_parameter package from rclc repo

rclc 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

Parameter server implementation for micro-ROS nodes

Additional Links

No 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

  • 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(&param_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(&param_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 with RCLC_PARAMETER_MAX_STRING_LENGTH = 50 and notify_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 on rclc_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, &param_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, &param_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, &param_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(&param_server, parameter_name, RCLC_PARAMETER_BOOL);

    // Set parameter value (Triggers `on_parameter_changed` callback, if defined)
    rc = rclc_parameter_set_bool(&param_server, parameter_name, param_value);

    // Get parameter value and store it in "param_value"
    rc = rclc_parameter_get_bool(&param_server, "param1", &param_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(&param_server, parameter_name, RCLC_PARAMETER_INT);

    // Set parameter value
    rc = rclc_parameter_set_int(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_int(&param_server, parameter_name, &param_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(&param_server, parameter_name, RCLC_PARAMETER_DOUBLE);

    // Set parameter value
    rc = rclc_parameter_set_double(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_double(&param_server, parameter_name, &param_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(&param_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(&param_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(&param_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(&param_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(&param_server, "param3", read_only);
    

Cleaning up

To destroy an initialized parameter server:

// Delete parameter server
rclc_parameter_server_fini(&param_server, &node);

This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.

CHANGELOG

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

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged rclc_parameter at Robotics Stack Exchange

rclc_parameter package from rclc repo

rclc 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

Parameter server implementation for micro-ROS nodes

Additional Links

No 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

  • 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(&param_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(&param_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 with RCLC_PARAMETER_MAX_STRING_LENGTH = 50 and notify_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 on rclc_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, &param_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, &param_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, &param_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(&param_server, parameter_name, RCLC_PARAMETER_BOOL);

    // Set parameter value (Triggers `on_parameter_changed` callback, if defined)
    rc = rclc_parameter_set_bool(&param_server, parameter_name, param_value);

    // Get parameter value and store it in "param_value"
    rc = rclc_parameter_get_bool(&param_server, "param1", &param_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(&param_server, parameter_name, RCLC_PARAMETER_INT);

    // Set parameter value
    rc = rclc_parameter_set_int(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_int(&param_server, parameter_name, &param_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(&param_server, parameter_name, RCLC_PARAMETER_DOUBLE);

    // Set parameter value
    rc = rclc_parameter_set_double(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_double(&param_server, parameter_name, &param_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(&param_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(&param_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(&param_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(&param_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(&param_server, "param3", read_only);
    

Cleaning up

To destroy an initialized parameter server:

// Delete parameter server
rclc_parameter_server_fini(&param_server, &node);

This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.

CHANGELOG

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

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged rclc_parameter at Robotics Stack Exchange

rclc_parameter package from rclc repo

rclc 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

Parameter server implementation for micro-ROS nodes

Additional Links

No 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

  • 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(&param_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(&param_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 with RCLC_PARAMETER_MAX_STRING_LENGTH = 50 and notify_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 on rclc_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, &param_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, &param_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, &param_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(&param_server, parameter_name, RCLC_PARAMETER_BOOL);

    // Set parameter value (Triggers `on_parameter_changed` callback, if defined)
    rc = rclc_parameter_set_bool(&param_server, parameter_name, param_value);

    // Get parameter value and store it in "param_value"
    rc = rclc_parameter_get_bool(&param_server, "param1", &param_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(&param_server, parameter_name, RCLC_PARAMETER_INT);

    // Set parameter value
    rc = rclc_parameter_set_int(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_int(&param_server, parameter_name, &param_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(&param_server, parameter_name, RCLC_PARAMETER_DOUBLE);

    // Set parameter value
    rc = rclc_parameter_set_double(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_double(&param_server, parameter_name, &param_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(&param_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(&param_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(&param_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(&param_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(&param_server, "param3", read_only);
    

Cleaning up

To destroy an initialized parameter server:

// Delete parameter server
rclc_parameter_server_fini(&param_server, &node);

This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.

CHANGELOG

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

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged rclc_parameter at Robotics Stack Exchange

rclc_parameter package from rclc repo

rclc 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

Parameter server implementation for micro-ROS nodes

Additional Links

No 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

  • 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(&param_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(&param_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 with RCLC_PARAMETER_MAX_STRING_LENGTH = 50 and notify_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 on rclc_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, &param_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, &param_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, &param_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(&param_server, parameter_name, RCLC_PARAMETER_BOOL);

    // Set parameter value (Triggers `on_parameter_changed` callback, if defined)
    rc = rclc_parameter_set_bool(&param_server, parameter_name, param_value);

    // Get parameter value and store it in "param_value"
    rc = rclc_parameter_get_bool(&param_server, "param1", &param_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(&param_server, parameter_name, RCLC_PARAMETER_INT);

    // Set parameter value
    rc = rclc_parameter_set_int(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_int(&param_server, parameter_name, &param_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(&param_server, parameter_name, RCLC_PARAMETER_DOUBLE);

    // Set parameter value
    rc = rclc_parameter_set_double(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_double(&param_server, parameter_name, &param_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(&param_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(&param_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(&param_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(&param_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(&param_server, "param3", read_only);
    

Cleaning up

To destroy an initialized parameter server:

// Delete parameter server
rclc_parameter_server_fini(&param_server, &node);

This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.

CHANGELOG

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

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged rclc_parameter at Robotics Stack Exchange

rclc_parameter package from rclc repo

rclc 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

Parameter server implementation for micro-ROS nodes

Additional Links

No 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

  • 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(&param_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(&param_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 with RCLC_PARAMETER_MAX_STRING_LENGTH = 50 and notify_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 on rclc_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, &param_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, &param_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, &param_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(&param_server, parameter_name, RCLC_PARAMETER_BOOL);

    // Set parameter value (Triggers `on_parameter_changed` callback, if defined)
    rc = rclc_parameter_set_bool(&param_server, parameter_name, param_value);

    // Get parameter value and store it in "param_value"
    rc = rclc_parameter_get_bool(&param_server, "param1", &param_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(&param_server, parameter_name, RCLC_PARAMETER_INT);

    // Set parameter value
    rc = rclc_parameter_set_int(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_int(&param_server, parameter_name, &param_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(&param_server, parameter_name, RCLC_PARAMETER_DOUBLE);

    // Set parameter value
    rc = rclc_parameter_set_double(&param_server, parameter_name, param_value);

    // Get parameter value on param_value
    rc = rclc_parameter_get_double(&param_server, parameter_name, &param_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(&param_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(&param_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(&param_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(&param_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(&param_server, "param3", read_only);
    

Cleaning up

To destroy an initialized parameter server:

// Delete parameter server
rclc_parameter_server_fini(&param_server, &node);

This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side.

CHANGELOG

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

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged rclc_parameter at Robotics Stack Exchange

rclc_parameter package from rclc repo

rclc 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

Parameter server implementation for micro-ROS nodes

Additional Links

No additional links.

Maintainers

  • Antonio Cuadros

Authors

  • Antonio Cuadros
README
No README found. See repository README.
CHANGELOG

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

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged rclc_parameter at Robotics Stack Exchange

rclc_parameter package from rclc repo

rclc 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

Parameter server implementation for micro-ROS nodes

Additional Links

No additional links.

Maintainers

  • Antonio Cuadros

Authors

  • Antonio Cuadros
README
No README found. See repository README.
CHANGELOG

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

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged rclc_parameter at Robotics Stack Exchange