updating README: updated table of contents and adding missing example…

…s. (#335) Signed-off-by: Jan Staschulat <[email protected]> (cherry picked from commit 3b4ff9e)
ros2 · Feb 9, 2023 · eb9ccf1 · eb9ccf1
1 parent 6d83359
commit eb9ccf1
Showing 1 changed file with 83 additions and 63 deletions.
diff --git 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. 
+## 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.