From f6192a8061d794fee2e7552320aa6d1b2a41c5ac Mon Sep 17 00:00:00 2001 From: acuadros95 Date: Wed, 7 Jun 2023 12:09:38 +0200 Subject: [PATCH 1/6] Initial iron release Signed-off-by: acuadros95 --- .github/workflows/generate_api_reference.yml | 2 +- .../execution_management/index.md | 4 +- _docs/overview/ext_tools/index.md | 2 +- _docs/overview/license/index.md | 2 +- .../microxrcedds_rmw_configuration/index.md | 2 +- .../core/first_application_linux/index.md | 2 +- .../core/first_application_rtos/freertos.md | 2 +- .../core/first_application_rtos/zephyr.md | 2 +- .../programming_rcl_rclc/executor/executor.md | 6 +- .../micro-ROS/micro-ROS.md | 8 +- .../programming_rcl_rclc/node/node.md | 36 +-- .../parameters/parameters.md | 272 ++++++------------ .../programming_rcl_rclc/pub_sub/pub_sub.md | 2 +- .../tutorials/programming_rcl_rclc/qos/QoS.md | 2 +- .../programming_rcl_rclc/service/services.md | 2 +- index.html | 4 +- 16 files changed, 115 insertions(+), 235 deletions(-) diff --git a/.github/workflows/generate_api_reference.yml b/.github/workflows/generate_api_reference.yml index f55aa4c8..37b03085 100644 --- a/.github/workflows/generate_api_reference.yml +++ b/.github/workflows/generate_api_reference.yml @@ -68,7 +68,7 @@ jobs: unzip doxybook2-linux-amd64-v1.3.3.zip -d doxybook2 mkdir -p ros2_ws/src; cd ros2_ws - git clone -b humble https://github.com/micro-ROS/micro_ros_utilities src/micro_ros_utilities + git clone -b Iron https://github.com/micro-ROS/micro_ros_utilities src/micro_ros_utilities source /opt/ros/$ROS_DISTRO/setup.bash colcon build --packages-up-to micro_ros_utilities --cmake-args -DBUILD_DOCUMENTATION=ON diff --git a/_docs/concepts/client_library/execution_management/index.md b/_docs/concepts/client_library/execution_management/index.md index 619d5130..a376db71 100644 --- a/_docs/concepts/client_library/execution_management/index.md +++ b/_docs/concepts/client_library/execution_management/index.md @@ -75,7 +75,7 @@ Our approach is to provide a real-time-capable Executor for the rcl+rclc layer ( As the first step, we propose the rclc Executor for the rcl-layer in C programming language with several new features to support real-time and deterministic execution: It supports 1.) user-defined static sequential execution, 2) conditional execution semantics, 3) multi-threaded execution with scheduling configuration, and 4) logical execution semantics (LET). Sequential execution refers to the runtime behavior, that all callbacks are executed in a pre-defined order independent of the arrival time of messages. Conditional execution is available with a trigger condition which enables typical processing patterns in robotics (which are analyzed in detail in section [Analysis of processing patterns](#analysis-of-processing-patterns). Configuration of scheduling parameters for multi-threaded application accomplishes prioritized execution. The logical execution time concept (LET) provides data synchronization for fixed periodic task scheduling of embedded applications. -Beyond the advanced execution management mechanisms for micro-ROS, we also contributed to improving and extending the Executor concept in rclcpp for standard ROS 2: the callback group-level Executor. It is not a new Executor but rather a refinement of the ROS 2 Executor API allowing to prioritize a group of callbacks which is not possible with the ROS 2 default Executor in its current Humble release. +Beyond the advanced execution management mechanisms for micro-ROS, we also contributed to improving and extending the Executor concept in rclcpp for standard ROS 2: the callback group-level Executor. It is not a new Executor but rather a refinement of the ROS 2 Executor API allowing to prioritize a group of callbacks which is not possible with the ROS 2 default Executor in its current Iron release. ## Analysis of rclcpp standard Executor @@ -581,7 +581,7 @@ The slides can be downloaded [here](https://ec2a4d36-bac8-4759-b25e-bb1f794177f4 - Multi-threaded executor with assignment of scheduling policies of underlying operating system. [[Pull Request](https://github.com/ros2/rclc/pull/87), pre-print [SLD2021](#SLD2021)]. ### Download -The rclc Executor can be downloaded from the [ros2/rclc repository](https://github.com/ros2/rclc). It is available for the ROS 2 versions Foxy, Galactic, Humble and Rolling. The repository provides several packages including the [rclc Executor](https://github.com/ros2/rclc/tree/master/rclc) and an [rclc_examples package](https://github.com/ros2/rclc/tree/master/rclc_examples) with several application examples. +The rclc Executor can be downloaded from the [ros2/rclc repository](https://github.com/ros2/rclc). It is available for the ROS 2 versions Humble, Iron and Rolling. The repository provides several packages including the [rclc Executor](https://github.com/ros2/rclc/tree/master/rclc) and an [rclc_examples package](https://github.com/ros2/rclc/tree/master/rclc_examples) with several application examples. ## Callback-group-level Executor diff --git a/_docs/overview/ext_tools/index.md b/_docs/overview/ext_tools/index.md index 03057515..64942d6d 100644 --- a/_docs/overview/ext_tools/index.md +++ b/_docs/overview/ext_tools/index.md @@ -41,7 +41,7 @@ The modules that exist up to date for integrating into external build systems ar
- Vulcanexus is an all-in-one ROS 2 tool set for easy and customized robotics development. It offers natively integrated solutions for ROS 2 networks in terms of performance improvement, simulation, cloud/edge communication, and microcontroller integration. The latter relies on micro-ROS. Vulcanexus is free and open source, and available as a Docker image for Galactic and Humble. All components enjoy continuous updates so users benefit from the latest features at all times. + Vulcanexus is an all-in-one ROS 2 tool set for easy and customized robotics development. It offers natively integrated solutions for ROS 2 networks in terms of performance improvement, simulation, cloud/edge communication, and microcontroller integration. The latter relies on micro-ROS. Vulcanexus is free and open source, and available as a Docker image for Humble and Iron. All components enjoy continuous updates so users benefit from the latest features at all times.
diff --git a/_docs/overview/license/index.md b/_docs/overview/license/index.md index d9d60913..4fd84bf1 100644 --- a/_docs/overview/license/index.md +++ b/_docs/overview/license/index.md @@ -28,4 +28,4 @@ We are aware of the following important license specifics in the RTOS supported * GPL-licensed build scripts in Zepyhr: The third-party licenses are given directly [in the source tree](https://github.com/zephyrproject-rtos/zephyr/), but [docs.zephyrproject.org/latest/LICENSING.html](https://docs.zephyrproject.org/latest/LICENSING.html) states explicitly that few build scripts are used under GPL v2. * GPL-licensed build tool files in ESP-IDF: The Espressif IoT Development Framework used for the ESP32 includes files menuconfig (Kconfig) and several other build tooling files licensed under GPL v2 or v3. -* Static library for Arduino IDE: The [micro_ros_arduino repository](https://github.com/micro-ROS/micro_ros_arduino) provides a static library `libmicroros.a` of the micro-ROS stack for use with the Arduino IDE. In detail, multiple versions of this library are provided, built for different microcontroller families using suitable cross-compiler configurations. The list of repositories included in the library can be found in the [`built_packages`](https://github.com/micro-ROS/micro_ros_arduino/blob/galactic/built_packages) file in the root of the repository. \ No newline at end of file +* Static library for Arduino IDE: The [micro_ros_arduino repository](https://github.com/micro-ROS/micro_ros_arduino) provides a static library `libmicroros.a` of the micro-ROS stack for use with the Arduino IDE. In detail, multiple versions of this library are provided, built for different microcontroller families using suitable cross-compiler configurations. The list of repositories included in the library can be found in the [`built_packages`](https://github.com/micro-ROS/micro_ros_arduino/blob/iron/built_packages) file in the root of the repository. \ No newline at end of file diff --git a/_docs/tutorials/advanced/microxrcedds_rmw_configuration/index.md b/_docs/tutorials/advanced/microxrcedds_rmw_configuration/index.md index 4a524d1c..08e3c190 100644 --- a/_docs/tutorials/advanced/microxrcedds_rmw_configuration/index.md +++ b/_docs/tutorials/advanced/microxrcedds_rmw_configuration/index.md @@ -90,7 +90,7 @@ For example, in the [ping-pong application](https://micro-ros.github.io//docs/tu There are some build time parameters related to Client-to-Agent connection (such as **CONFIG_RMW_DEFAULT_UDP_PORT**, **CONFIG_RMW_DEFAULT_UDP_IP** and **CONFIG_RMW_DEFAULT_SERIAL_DEVICE**) that can be configured either at build time or at run-time. This means that you can set them in the [configuration file](https://github.com/micro-ROS/micro_ros_setup/blob/foxy/config/host/generic/client-host-colcon.meta) mentioned above and that micro-ROS provides a user configuration API for setting some RMW and middleware parameters at run-time. -The following example code shows the [API](https://github.com/micro-ROS/rmw_microxrcedds/blob/humble/rmw_microxrcedds_c/include/rmw_microros/init_options.h) calls needed to set the agent's IP address, port or serial device: +The following example code shows the [API](https://github.com/micro-ROS/rmw_microxrcedds/blob/iron/rmw_microxrcedds_c/include/rmw_microros/init_options.h) calls needed to set the agent's IP address, port or serial device: ```c #include diff --git a/_docs/tutorials/core/first_application_linux/index.md b/_docs/tutorials/core/first_application_linux/index.md index 24ec6976..21044eb1 100644 --- a/_docs/tutorials/core/first_application_linux/index.md +++ b/_docs/tutorials/core/first_application_linux/index.md @@ -3,7 +3,7 @@ title: First micro-ROS Application on Linux permalink: /docs/tutorials/core/first_application_linux/ --- - + In this tutorial, you’ll learn the use of micro-ROS with Linux by testing a Ping Pong application. In the follow-up tutorial [*First micro-ROS application on an RTOS*](/docs/tutorials/core/first_application_rtos/), diff --git a/_docs/tutorials/core/first_application_rtos/freertos.md b/_docs/tutorials/core/first_application_rtos/freertos.md index 3c4ef484..b247ae6a 100644 --- a/_docs/tutorials/core/first_application_rtos/freertos.md +++ b/_docs/tutorials/core/first_application_rtos/freertos.md @@ -5,7 +5,7 @@ redirect_from: - /docs/tutorials/advanced/freertos/freertos_getting_started/ --- - + In this tutorial, you'll learn the use of micro-ROS with FreeRTOS by testing a Ping Pong application. {% include first_application_common/target_hardware.md %} diff --git a/_docs/tutorials/core/first_application_rtos/zephyr.md b/_docs/tutorials/core/first_application_rtos/zephyr.md index 7090fab9..2eea974d 100644 --- a/_docs/tutorials/core/first_application_rtos/zephyr.md +++ b/_docs/tutorials/core/first_application_rtos/zephyr.md @@ -5,7 +5,7 @@ redirect_from: - /docs/tutorials/advanced/zephyr/zephyr_getting_started/ --- - + In this tutorial, you'll learn the use of micro-ROS with Zephyr by testing a Ping Pong application. {% include first_application_common/target_hardware.md %} diff --git a/_docs/tutorials/programming_rcl_rclc/executor/executor.md b/_docs/tutorials/programming_rcl_rclc/executor/executor.md index 9bab34fa..7598585a 100644 --- a/_docs/tutorials/programming_rcl_rclc/executor/executor.md +++ b/_docs/tutorials/programming_rcl_rclc/executor/executor.md @@ -3,7 +3,7 @@ title: Executor and timers permalink: /docs/tutorials/programming_rcl_rclc/executor/ --- - + - [Timers](#timers) - [Initialization](#initialization) @@ -53,7 +53,7 @@ void timer_callback(rcl_timer_t * timer, int64_t last_call_time) } ``` -During the callback the timer can be canceled or have its period and/or callback modified using the passed pointer. Check [rcl/timer.h](https://github.com/ros2/rcl/blob/galactic/rcl/include/rcl/timer.h) for details. +During the callback the timer can be canceled or have its period and/or callback modified using the passed pointer. Check [rcl/timer.h](https://github.com/ros2/rcl/blob/iron/rcl/include/rcl/timer.h) for details. ### Cleaning Up @@ -821,6 +821,6 @@ The following code will setup the executor accordingly: The custom structs `pub_trigger_object_t` are used to save the pointer of the handles. The timers `my_string_timer` and `my_int_timer` for the publishing executor; and, likewise, the subscriptions `my_string_sub` and `my_int_sub` for the subscribing executor. The configuration is done also with the `rclc_executor_set_trigger` by passing the trigger function and the trigger object, e.g. `pub_trigger` and `comm_obj_pub` for the `executor_pub`, respectivly. -The complete source code of this example can be found in the file [rclc-examples/example_executor_trigger.c](https://github.com/ros2/rclc/blob/humble/rclc_examples/src/example_executor_trigger.c). +The complete source code of this example can be found in the file [rclc-examples/example_executor_trigger.c](https://github.com/ros2/rclc/blob/iron/rclc_examples/src/example_executor_trigger.c). diff --git a/_docs/tutorials/programming_rcl_rclc/micro-ROS/micro-ROS.md b/_docs/tutorials/programming_rcl_rclc/micro-ROS/micro-ROS.md index be38b663..32cb1be9 100644 --- a/_docs/tutorials/programming_rcl_rclc/micro-ROS/micro-ROS.md +++ b/_docs/tutorials/programming_rcl_rclc/micro-ROS/micro-ROS.md @@ -5,7 +5,7 @@ permalink: /docs/tutorials/programming_rcl_rclc/micro-ROS/ - + - [Allocators](#allocators) - [Custom allocator](#custom-allocator) @@ -124,7 +124,7 @@ Custom methods prototypes and examples: ## Time sync micro-ROS Clients can synchronize their epoch time with the connected Agent, this can be very useful when working in embedded environments that do not provide any time synchronization mechanism. -This utility is based on the NTP protocol, taking into account delays caused by the transport layer. An usage example can be found on [`micro-ROS-demos/rclc/epoch_synchronization`](https://github.com/micro-ROS/micro-ROS-demos/blob/galactic/rclc/epoch_synchronization/main.c). +This utility is based on the NTP protocol, taking into account delays caused by the transport layer. An usage example can be found on [`micro-ROS-demos/rclc/epoch_synchronization`](https://github.com/micro-ROS/micro-ROS-demos/blob/iron/rclc/epoch_synchronization/main.c). ```c // Sync timeout @@ -142,7 +142,7 @@ if (rmw_uros_epoch_synchronized()) ``` ## Ping agent -The Client can test the connection with the Agent with the ping utility. This functionality can be used even when the micro-ROS context has not yet been initialized, which is useful to test the connection before trying to connect to the Agent. An example can be found on [`micro-ROS-demos/rclc/ping_uros_agent`](https://github.com/micro-ROS/micro-ROS-demos/blob/galactic/rclc/ping_uros_agent/main.c). +The Client can test the connection with the Agent with the ping utility. This functionality can be used even when the micro-ROS context has not yet been initialized, which is useful to test the connection before trying to connect to the Agent. An example can be found on [`micro-ROS-demos/rclc/ping_uros_agent`](https://github.com/micro-ROS/micro-ROS-demos/blob/iron/rclc/ping_uros_agent/main.c). ```c // Timeout for each attempt @@ -170,7 +170,7 @@ else ## Continous serialization -This utility allows the client to serialize and send data up to a customized size. The user can set the topic lenght and then serialize the data within the publish process. An example can be found on [`micro-ROS-demos/rclc/ping_uros_agent`](https://github.com/micro-ROS/micro-ROS-demos/blob/galactic/rclc/ping_uros_agent/main.c), where fragments from an image are requested and serialized on the spot. +This utility allows the client to serialize and send data up to a customized size. The user can set the topic lenght and then serialize the data within the publish process. An example can be found on [`micro-ROS-demos/rclc/ping_uros_agent`](https://github.com/micro-ROS/micro-ROS-demos/blob/iron/rclc/ping_uros_agent/main.c), where fragments from an image are requested and serialized on the spot. The user needs to define two callbacks, then set them on the `rmw`. It is recommended to clean the callbacks after the publication, to avoid interferences with other topics on the same process: diff --git a/_docs/tutorials/programming_rcl_rclc/node/node.md b/_docs/tutorials/programming_rcl_rclc/node/node.md index b092fee6..abd76b0f 100644 --- a/_docs/tutorials/programming_rcl_rclc/node/node.md +++ b/_docs/tutorials/programming_rcl_rclc/node/node.md @@ -3,9 +3,9 @@ title: Nodes permalink: /docs/tutorials/programming_rcl_rclc/node/ --- - + -ROS 2 nodes are the main participants on ROS 2 ecosystem. They will communicate between each other using publishers, subscriptions, services, etc. Further information about ROS 2 nodes can be found [here](https://docs.ros.org/en/galactic/Tutorials/Understanding-ROS2-Nodes.html) +ROS 2 nodes are the main participants on ROS 2 ecosystem. They will communicate between each other using publishers, subscriptions, services, etc. Further information about ROS 2 nodes can be found [here](https://docs.ros.org/en/iron/Tutorials/Understanding-ROS2-Nodes.html) - [Initialization](#initialization) @@ -45,37 +45,7 @@ ROS 2 nodes are the main participants on ROS 2 ecosystem. They will communicate - Create a node with custom options: - The configuration of the node will also be applied to its future elements (Publishers, subscribers, services, ...).The API used to customize the node options differs between ROS2 distributions: - - Foxy: The `rcl_node_options_t` is used to configure the node - - ```c - // Initialize allocator and support objects - ... - - // Create node object - rcl_node_t node; - const char * node_name = "test_node"; - - // Node namespace (Can remain empty "") - const char * namespace = "test_namespace"; - - // Get default node options and modify them - rcl_node_options_t node_ops = rcl_node_get_default_options(); - - // Set node ROS domain ID to 10 - node_ops.domain_id = (size_t)(10); - - // Init node with custom options - rc = rclc_node_init_with_options(&node, node_name, namespace, &support, &node_ops); - - if (rc != RCL_RET_OK) { - ... // Handle error - return -1; - } - ``` - - Galactic and beyond: In this case, the node options are configured on the `rclc_support_t` object with a custom API + The configuration of the node will also be applied to its future elements (Publishers, subscribers, services, ...). The node options are configured on the `rclc_support_t` object with a custom API: ```c // Initialize micro-ROS allocator diff --git a/_docs/tutorials/programming_rcl_rclc/parameters/parameters.md b/_docs/tutorials/programming_rcl_rclc/parameters/parameters.md index d8bd36cd..3a25a1b6 100644 --- a/_docs/tutorials/programming_rcl_rclc/parameters/parameters.md +++ b/_docs/tutorials/programming_rcl_rclc/parameters/parameters.md @@ -3,31 +3,21 @@ title: Parameter server permalink: /docs/tutorials/programming_rcl_rclc/parameters/ --- - + 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](https://docs.ros.org/en/rolling/Tutorials/Parameters/Understanding-ROS2-Parameters.html) Ready to use code examples related to this tutorial can be found in [`rclc/rclc_examples/src/example_parameter_server.c`](https://github.com/ros2/rclc/blob/master/rclc_examples/src/example_parameter_server.c). -micro-ROS parameters implementation has been upgraded in the latest micro-ROS Humble distribution, two approaches are presented in this tutorial: micro-ROS Foxy/Galactic and micro-ROS Humble and beyond: - -- [General implementation](#general-implementation) - - [Initialization](#initialization) - - [Memory requirements](#memory-requirements) - - [Add a parameter](#add-a-parameter) - - [Cleaning up](#cleaning-up) -- [micro-ROS Foxy/Galactic](#micro-ros-foxygalactic) - - [Initialization options](#initialization-options) - - [Callback](#callback) -- [micro-ROS Humble](#micro-ros-humble) - - [Initialization options](#initialization-options-1) - - [Callback](#callback-1) - - [Add a parameter](#add-a-parameter-1) - - [Delete a parameter](#delete-a-parameter) - - [Parameters description](#parameters-description) - -## General implementation -### Initialization +- [Initialization](#initialization) +- [Memory requirements](#memory-requirements) +- [Add a parameter](#add-a-parameter) +- [Delete a parameter](#delete-a-parameter) +- [Parameters description](#parameters-description) +- [Callback](#callback) +- [Cleaning up](#cleaning-up) + +## Initialization - Default initialization: ```c @@ -43,7 +33,47 @@ micro-ROS parameters implementation has been upgraded in the latest micro-ROS Hu } ``` -### Memory requirements +- Initialization with 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. + + ```c + // 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 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: @@ -76,7 +106,7 @@ rc = rclc_executor_init( *Humble: the variable is `RCLC_PARAMETER_EXECUTOR_HANDLES_NUMBER` has been renamed to `RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES`.* -### Add a parameter +## Add a parameter The micro-ROS parameter server supports the following parameter types: @@ -130,140 +160,57 @@ The micro-ROS parameter server supports the following parameter types: rc = rclc_parameter_get_double(¶m_server, parameter_name, ¶m_value); ``` -*Max name size is controlled by the compile-time option `RCLC_PARAMETER_MAX_STRING_LENGTH`, default value is 50.* - -### Cleaning up +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. -To destroy an initialized parameter server: +*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: ```c -// Delete parameter server -rclc_parameter_server_fini(¶m_server, &node); +rclc_delete_parameter(¶m_server, "param2"); ``` -This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side. - -## micro-ROS Foxy/Galactic - -### Initialization options - - - Custom options: +*For external delete requests, the server callback will be executed, allowing the node to reject the operation.* - 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. +## Parameters description +- Parameter description + Adds a description of a parameter and its constrains, which will be returned on a describe parameter requests: ```c - // 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 }; - - // 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; - } + rclc_add_parameter_description(¶m_server, "param2", "Second parameter", "Only even numbers"); ``` -### Callback - -When adding the parameter server to the executor, a callback could be configured. -This callback would then be executed after a parameter value is modified. - -A pointer to the changed parameter is passed as first and only argument. Example: -```c -void on_parameter_changed(Parameter * param) -{ - if (param == NULL) { - printf("Callback error, parameter is NULL\n"); - return; - } - - // Get parameter name - printf("Parameter %s modified.", param->name.data); - - // Get parameter type - switch (param->value.type) - { - // Get parameter value acording type - case RCLC_PARAMETER_BOOL: - printf(" New value: %d (bool)", param->value.bool_value); - break; - case RCLC_PARAMETER_INT: - printf(" New value: %ld (int)", param->value.integer_value); - break; - case RCLC_PARAMETER_DOUBLE: - printf(" New value: %f (double)", param->value.double_value); - break; - default: - break; - } - - printf("\n"); -} -``` -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: -```c -// Add parameter server to 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: -```c -// Add parameter server to executor without callback -rc = rclc_executor_add_parameter_server(&executor, ¶m_server, NULL); -``` + *The maximum string size is controlled by the compilation time option `RCLC_PARAMETER_MAX_STRING_LENGTH`, default value is 50.* -## micro-ROS Humble +- 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. -### Initialization options + ```c + 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); -- Custom options: + 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); + ``` - 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. + *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: ```c - // 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; - } + bool read_only = true; + rclc_set_parameter_read_only(¶m_server, "param3", read_only); ``` -- 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 - -### Callback +## 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. @@ -346,51 +293,14 @@ Configuration of the callback context: rc = rclc_executor_add_parameter_server_with_context(&executor, ¶m_server, on_parameter_changed, &context); ``` -### Add a parameter -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. +## Cleaning up + +To destroy an initialized parameter server: -### Delete a parameter -Parameters can be deleted by both, the parameter server and external clients: ```c -rclc_delete_parameter(¶m_server, "param2"); +// Delete parameter server +rclc_parameter_server_fini(¶m_server, &node); ``` -*For external delete requests, the server callback will be executed, allowing the node to reject the operation.* - -### Parameters description - -- Parameter description - Adds a description of a parameter and its constrains, which will be returned on a describe parameter requests: - ```c - 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. - - ```c - 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.* +This will delete any automatically created infrastructure on the agent (if possible) and deallocate used memory on the parameter server side. -- 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: - ```c - bool read_only = true; - rclc_set_parameter_read_only(¶m_server, "param3", read_only); - ``` diff --git a/_docs/tutorials/programming_rcl_rclc/pub_sub/pub_sub.md b/_docs/tutorials/programming_rcl_rclc/pub_sub/pub_sub.md index ba055233..00326e37 100644 --- a/_docs/tutorials/programming_rcl_rclc/pub_sub/pub_sub.md +++ b/_docs/tutorials/programming_rcl_rclc/pub_sub/pub_sub.md @@ -3,7 +3,7 @@ title: Publishers and subscribers permalink: /docs/tutorials/programming_rcl_rclc/pub_sub/ --- - + ROS 2 publishers and subscribers are the basic communication mechanism between nodes using topics. Further information about ROS 2 publish–subscribe pattern can be found [here](https://docs.ros.org/en/foxy/Tutorials/Topics/Understanding-ROS2-Topics.html). diff --git a/_docs/tutorials/programming_rcl_rclc/qos/QoS.md b/_docs/tutorials/programming_rcl_rclc/qos/QoS.md index d5404d28..30203177 100644 --- a/_docs/tutorials/programming_rcl_rclc/qos/QoS.md +++ b/_docs/tutorials/programming_rcl_rclc/qos/QoS.md @@ -3,7 +3,7 @@ title: Quality of service permalink: /docs/tutorials/programming_rcl_rclc/qos/ --- - + - [Reliable QoS](#reliable-qos) - [Best Effort](#best-effort) diff --git a/_docs/tutorials/programming_rcl_rclc/service/services.md b/_docs/tutorials/programming_rcl_rclc/service/services.md index f117354b..abfc972d 100644 --- a/_docs/tutorials/programming_rcl_rclc/service/services.md +++ b/_docs/tutorials/programming_rcl_rclc/service/services.md @@ -3,7 +3,7 @@ title: Services permalink: /docs/tutorials/programming_rcl_rclc/service/ --- - + ROS 2 services are another communication mechanism between nodes. Services implement a client-server paradigm based on ROS 2 messages and types. Further information about ROS 2 services can be found [here](https://index.ros.org/doc/ros2/Tutorials/Services/Understanding-ROS2-Services/) diff --git a/index.html b/index.html index f5a9036f..0968c062 100644 --- a/index.html +++ b/index.html @@ -129,8 +129,8 @@