From eb9ccf16793aff733236385ca5841872e1e040a3 Mon Sep 17 00:00:00 2001 From: Jan Staschulat Date: Thu, 9 Feb 2023 07:09:56 +0100 Subject: [PATCH] updating README: updated table of contents and adding missing examples. (#335) Signed-off-by: Jan Staschulat (cherry picked from commit 3b4ff9e46ad63ca08a1131760a86b0f42c2bba63) --- rclc_examples/README.md | 146 +++++++++++++++++++++++----------------- 1 file changed, 83 insertions(+), 63 deletions(-) diff --git a/rclc_examples/README.md b/rclc_examples/README.md index 9df83471..b82f526b 100644 --- a/rclc_examples/README.md +++ b/rclc_examples/README.md @@ -4,21 +4,22 @@ General information about this repository, including legal information, build in The rclc_examples package provides examples for using the RCLC-Exector and convenience functions for creating RCL objects like subscriptions and timers. -- [example_executor.c](src/example_executor.c) provides the example for the RCLC-Executor with the convenience functions from rclc. It creates one publisher and one subscriber and configures the RCLC-Executor accordingly. -- [example_executor_trigger.c](src/example_executor_trigger.c) demonstrates the trigger condition of the RCLC-Executor. -- [example_service_node.c](src/example_service_node.c) implements a service node with the RCLC-Executor. -- [example_client_node.c](src/example_client_node.c) implements a client node with RCLC-Executor. -- [example_executor_only_rcl.c](src/example_executor_only_rcl.c) provides the example for the RCLC-Executor. It creates one publisher and one subscriber and configures the RCLC-Executor using only the RCL API. -- [example_short_timer_long_subscription.c](src/example_short_timer_long_subscription.c) demo with high frequency timer and subscription with long processing time with one executor. +## Table of contents + +- [Minimal publisher-subscriber](#minimal-publisher-subscriber) +- [Minimal publisher-subscriber only with RCL-API](#minimal-publisher-subscriber-only-with-rcl-api) +- [RCLC-Executor with trigger function](#rclc-executor-with-trigger-function) +- [Service and client node](#service-and-client-node) +- [Action server and client](#action-server-and-client) +- [Lifecycle node](#lifecycle-node) +- [Parameter server](#parameter-server) +- [Subscription callback with C++ class method](#subscription-callback-with-c++-class-method) +- [Subscription with context](#subscription-with-context) +- [Real-time concurrency with slow timer and long subscription](#real-time-concurrency-with-slow-timer-and-long-subscription) + +## Minimal publisher-subscriber +The example [example_executor.c](src/example_executor.c) demonstrates basic features of the rclc package and the rclc-Executor to setup a publisher and a subscriber. This example uses also the convenience functions to configure rcl objects, like subscriptions, timers, etc. This saves in this case about 24% of lines of code compared the the same application with direct rcl-API, as described in the setup [Minimal publisher-subscriber only with RCL-API](#minimal-publisher-subscriber-only-with-rcl-api). - -The reduction of code lines for configuring the necessary RCL objects for RCLC-Executor directly with RCL objects compared to using the convenience functions is about 24%: -- example_executor.c: 92 LoC (lines 56-148) -- example_executor_convenience.c: 70 LoC (line 17 + lines 57-126) - - counting only the lines of code in which the RCL objects are defined). - -## Example RCLC-Executor **Step 1** Setup ROS 2 Workspace Open a terminal with ROS 2 workspace. Assuming that the ROS 2 installation resides in `/opt/ros/ROSDISTRO`, setup the ROS2 environment by: @@ -59,10 +60,60 @@ Published message Hello World! Callback: I heard: Hello World! ``` -## Example RCLC-Executor with trigger function +## Minimal publisher-subscriber only with RCL-API + +**Step 1** Setup ROS 2 Workspace + +Open a terminal with ROS 2 workspace. Assuming that the ROS 2 installation resides in `/opt/ros/ROSDISTRO`, setup the ROS2 environment by: +```C +~$ source /opt/ros/ROSDISTRO/setup.bash +``` + +**Step 2** Build the package +Download the rclc repository in a workspace (for example `ros2_ws`). Then source the workspace: +```C +~/ros2_ws/$ colcon build --packages-up-to rclc_examples +~/ros2_ws/$ source ./install/local_setup.bash +``` +It should build these packages: +- rcl_yaml_param_parser +- rcl +- rclc +- rclc_examples + + +**Step 3** Run the example executor. + +The binary of the example is `example_executor_only_rcl`. + +```C +~/ros2_ws/$ ros2 run rclc_examples example_executor_only_rcl +``` +The publisher publishes the message `Hello World!`in `topic_0` at a rate of 1Hz and the subscriber prints out in the callback `Callback: I heard: Hello World!`. + +You should see the following output: + +```C +Created timer with timeout 1000 ms. +Created subscriber topic_0: +Debug: number of DDS handles: 2 +Published message Hello World! +Callback: I heard: Hello World! +Published message Hello World! +Callback: I heard: Hello World! +Published message Hello World! +Callback: I heard: Hello World! +Published message Hello World! +Callback: I heard: Hello World! +Published message Hello World! +Callback: I heard: Hello World! +``` + +## RCLC-Executor with trigger function +[example_executor_trigger.c](src/example_executor_trigger.c) demonstrates the rclc-Executor with a trigger function. **Step 1, Step 2** -To setup ROS2 workspace and build the package refer to Step 1 and Step 2 in the [Example RCLC-Executor](#example-rclc-executor). +To setup ROS2 workspace and build the package refer to Step 1 and Step 2 in the [Minimal publisher-subscriber](#minimal-publisher-subscriber). **Step 3** This example implements two RCLC Executors, one for publishing `executor_pub`and one for subscribing messages `executor_sub`. @@ -129,10 +180,11 @@ Callback 2: 1 <--- ``` The results show, that the callbacks are triggered together, only when the integer message `topic_1` was published and received. At that moment the current string message of the `topic_0` is processed as well. -## Example Service/client with RCLC-Executor +## Service and client node +The two files [example_service_node.c](src/example_service_node.c) and [example_client_node.c](src/example_client_node.c) demonstrate service/client functionality in micro-ROS. **Step 1, Step 2** -To setup ROS2 workspace and build the package refer to Step 1 and Step 2 in the [Example RCLC-Executor](#example-rclc-executor). +To setup ROS2 workspace and build the package refer to Step 1 and Step 2 in the [Minimal publisher-subscriber](#minimal-publisher-subscriber). **Step 3** Open two Terminal windows and source the ROS 2 distribution/install/setup.bash and rclc repository/install/local_setup.bash. @@ -154,54 +206,22 @@ INFO: rcl_wait timeout 10 ms A request message is sent from the client node to the service node and answered. -## Example RCLC-Executor using RCL objects directly -**Step 1** Setup ROS 2 Workspace -Open a terminal with ROS 2 workspace. Assuming that the ROS 2 installation resides in `/opt/ros/ROSDISTRO`, setup the ROS2 environment by: -```C -~$ source /opt/ros/$ROSDISTRO/setup.bash -``` +## Action server and client +The files [example_action_client.c](src/example_action_client.c) and [example_action_server.c](src/example_action_server.c) demonstrate the action client and action server functionality in micro-ROS. -**Step 2** Build the package -Download the rclc repository in a workspace (for example `ros2_ws`). Then source the workspace: -```C -~/ros2_ws/$ colcon build --packages-up-to rclc_examples -~/ros2_ws/$ source ./install/local_setup.bash -``` -It should build these packages: -- rcl_yaml_param_parser -- rcl -- rclc -- rclc_examples +## Lifecycle node +The file [example_lifecycle_node.c](src/example_lifecycle_node.c) demonstrates the lifecycle node functionality in micro-ROS. +## Parameter server +The file [example_parameter_server.c](src/example_parameter_server.c) demonstrates the parameter server functionality in micro-ROS. -**Step 3** Run the example executor. +## Subscription callback with C++ class method +The files [example_pingpong.cpp](src/example_pingpong.cpp), [example_pingpong_helper.h](src/example_pingpong_helper.h), [example_pingpong_helper.c](src/example_pingpong_helper.c) implement a ping-pong demo using a method of a C++ class as subscription callback. -The binary of the example is `example_executor_only_rcl`. +## Subscription with context +The file [example_sub_context.c](src/example_sub_context.c) shows, how to use a subscription with a context. This allows the subscription to access some other data structure additionally to the message data. -```C -~/ros2_ws/$ ros2 run rclc_examples example_executor_only_rcl -``` -The publisher publishes the message `Hello World!`in `topic_0` at a rate of 1Hz and the subscriber prints out in the callback `Callback: I heard: Hello World!`. - -You should see the following output: - -```C -Created timer with timeout 1000 ms. -Created subscriber topic_0: -Debug: number of DDS handles: 2 -Published message Hello World! -Callback: I heard: Hello World! -Published message Hello World! -Callback: I heard: Hello World! -Published message Hello World! -Callback: I heard: Hello World! -Published message Hello World! -Callback: I heard: Hello World! -Published message Hello World! -Callback: I heard: Hello World! -``` -## Example real-time concurrency slow timer and long subscription -This example demonstrates what happens, if a high frequency timer (every 100ms) and -a subscription with a long processing time is managed by one executor. This demo shows, -that the timer events are dropped during the long processing time of the subscription and are also not caught-up when there would be sufficient time. \ No newline at end of file +## Real-time concurrency with slow timer and long subscription +The example [example_short_timer_long_subscription.c](src/example_short_timer_long_subscription.c) demonstrates what happens, if a high frequency timer (every 100ms) and +a subscription with a long processing time is managed by one executor. This demo shows, that the timer events are dropped during the long processing time of the subscription and are also not caught-up when there would be sufficient time. \ No newline at end of file