updated pub_sub and rclc_executor section.

JanStaschulat · ralph-lange · commit 720afd02ba6c · 2020-04-29T09:26:00.000+02:00
Signed-off-by: Staschulat Jan &lt;jan.staschulat@de.bosch.com&gt;
diff --git a/_docs/tutorials/core/programming_rcl_rclc/index.md b/_docs/tutorials/core/programming_rcl_rclc/index.md
@@ -35,17 +35,61 @@ if (rc != RCL_RET_OK) {
 }
 ```
 
-
 ## <a name="pub_sub"/>Publishers and Subscriptions
+Publisher and subscribers are created with the rclc-package with the following functions
+`rclc_publisher_init_default(..)` and `rclc_subscription_init_default(..)` in [rclc/publisher.h](https://github.com/micro-ROS/rclc/blob/master/rclc/include/rclc/publisher.h) and [rclc/node.h](https://github.com/micro-ROS/rclc/blob/master/rclc/include/rclc/subscription.h), respectively:
 
 
+```c
+// create publisher
+rcl_publisher_t my_pub;
+std_msgs__msg__String pub_msg;
+const char * topic_name = "topic_0";
+const rosidl_message_type_support_t * my_type_support =
+  ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, String);
+
+rc = rclc_publisher_init_default(
+  &my_pub,
+  &my_node,
+  my_type_support,
+  topic_name);
+if (RCL_RET_OK != rc) {
+  printf("Error in rclc_publisher_init_default %s.\n", topic_name);
+  return -1;
+}
+// create publisher message
+std_msgs__msg__String__init(&pub_msg);
+const unsigned int PUB_MSG_SIZE = 20;
+char pub_string[PUB_MSG_SIZE];
+snprintf(pub_string, 13, "%s", "Hello World!");
+rosidl_generator_c__String__assignn(&pub_msg, pub_string, PUB_MSG_SIZE);
+
+// create subscription
+rcl_subscription_t my_sub = rcl_get_zero_initialized_subscription();
+rc = rclc_subscription_init_default(
+  &my_sub,
+  &my_node,
+  my_type_support,
+  topic_name);
+if (rc != RCL_RET_OK) {
+  printf("Failed to create subscriber %s.\n", topic_name);
+  return -1;
+} else {
+  printf("Created subscriber %s:\n", topic_name);
+}
+
+// initialize string message for subscriber
+std_msgs__msg__String__init(&sub_msg);
+```
 
 ## <a name="services"/>Services
 
 ROS 2 services is 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/)
 
 Ready to use code related to this tutorial can be found in [`micro-ROS-demos/rcl/addtwoints_server`](https://github.com/micro-ROS/micro-ROS-demos/blob/dashing/rcl/addtwoints_server/main.c) and [`micro-ROS-demos/rcl/addtwoints_client`](https://github.com/micro-ROS/micro-ROS-demos/blob/dashing/rcl/addtwoints_client/main.c) folders.
 
+Note: Services are not supported in rclc package yet. Therefore the configuration is described using RCL layer.
+
 Starting from a code where RCL is initialized and a micro-ROS node is created, these steps are required in order to generate a service server:
 
 ```c
@@ -90,7 +134,7 @@ Once service client and server are configured, service client can perform a requ
 
 ```c
 // Creating a service request
-int64_t seq; 
+int64_t seq;
 example_interfaces__srv__AddTwoInts_Request req;
 req.a = 24;
 req.b = 42;
@@ -116,7 +160,7 @@ do {
         // Create a service response struct
         example_interfaces__srv__AddTwoInts_Response res;
 
-        // Take the response 
+        // Take the response
         rcl_ret_t rc = rcl_take_response(&client, &req_id, &res);
 
         if (RCL_RET_OK == rc) {
@@ -132,7 +176,7 @@ On service server side, the ROS 2 node should be waiting for service requests an
 ```c
 while(1){
     rcl_wait_set_clear(&wait_set);
-        
+
     size_t index;
     rcl_wait_set_add_service(&wait_set, &service, &index);
 
@@ -145,7 +189,7 @@ while(1){
         // Create a service request struct
         example_interfaces__srv__AddTwoInts_Request req;
 
-        // Take the request 
+        // Take the request
         rcl_take_request(&service, &req_id, &req);
 
         printf("Service request value: %d + %d. Seq %d\n", (int)req.a, (int)req.b, (int)req_id.sequence_number);
@@ -161,7 +205,88 @@ while(1){
 
 
 ## <a name="timers"/>Timers
-
+A timer can be created with the rclc-package with the function
+`rclc_timer_init_default(..)` in [rclc/timer.h](https://github.com/micro-ROS/rclc/blob/master/rclc/include/rclc/timer.h):
+```c
+// create a timer, which will call the publisher with period=`timer_timeout` ms in the 'my_timer_callback'
+rcl_timer_t my_timer = rcl_get_zero_initialized_timer();
+const unsigned int timer_timeout = 1000;
+rc = rclc_timer_init_default(
+  &my_timer,
+  &support,
+  RCL_MS_TO_NS(timer_timeout),
+  my_timer_callback);
+if (rc != RCL_RET_OK) {
+  printf("Error in rcl_timer_init_default.\n");
+  return -1;
+} else {
+  printf("Created timer with timeout %d ms.\n", timer_timeout);
+}
+```
 
 ## <a name="rclc_executor"/>Rclc Executor
+The Executor is configured and setup with the functions
+`rclc_executor_get_zero_initialized_executor(..)`, `rclc_executor_set_timeout(..)`, `rclc_executor_add_subscription(...)`, `rclc_executor_add_timer(...)`, `rclc_executor_spin_some(...)` and `rclc_executor_fini(...)` in [rclc/executor.h](https://github.com/micro-ROS/rclc/blob/master/rclc/include/rclc/executor.h).
+
+Assuming that you have created a subscription and a timer, as described above, the following code snippet shows the configuration of the RCLC-executor.
+
+The executor is configured with 2 handles, aka one subscription and one timer. The `support.context` is the ROS 2 context, as shown above with `rclc_support_init(...)`.
+
+The timeout is the waiting time for new handles to get ready, for example new messages arrive or timers are ready. The unit of the timeout is milliseconds.
 
+A subscription `my_sub`, a place-holder for it's message `sub_msg` and it's corresponding callback `my_subscriber_callback` is added to the executor with the function `rclc_executor_add_subscription(...)`
+
+A timers is added to the executor with the function `rclc_executor_add_timer(...)`
+
+A key feature of the rclc-Executor is, that the order of these functions to add handles matters. It defines the processing order when multiple messages have arrived or timers are ready. This provides full control over the execution order to the user.
+
+There are are several functions, how to start the executor, one is `rclc_executor_spin_some(...)`, which allows the user to specify a timeout in nanoseconds.
+
+Finally the code snippet shows how to destroy the objects for the node, publisher, subscriber and the executor with the respective fini-methods.
+
+```c
+rclc_executor_t executor;
+
+  // compute total number of subsribers and timers
+  unsigned int num_handles = 1 + 1;
+  printf("Debug: number of DDS handles: %u\n", num_handles);
+  executor = rclc_executor_get_zero_initialized_executor();
+  rclc_executor_init(&executor, &support.context, num_handles, &allocator);
+
+  // set timeout for rcl_wait()
+  unsigned int rcl_wait_timeout = 1000;   // in ms
+  rc = rclc_executor_set_timeout(&executor, RCL_MS_TO_NS(rcl_wait_timeout));
+  if (rc != RCL_RET_OK) {
+    printf("Error in rclc_executor_set_timeout.");
+  }
+
+  // add subscription to executor
+  rc = rclc_executor_add_subscription(&executor, &my_sub, &sub_msg, &my_subscriber_callback,
+      ON_NEW_DATA);
+  if (rc != RCL_RET_OK) {
+    printf("Error in rclc_executor_add_subscription. \n");
+  }
+
+  rclc_executor_add_timer(&executor, &my_timer);
+  if (rc != RCL_RET_OK) {
+    printf("Error in rclc_executor_add_timer.\n");
+  }
+
+  for (;;) {
+    // timeout specified in ns (here 1s)
+    rclc_executor_spin_some(&executor, 1000 * (1000 * 1000));
+  }
+
+  // clean up
+  rc = rclc_executor_fini(&executor);
+  rc += rcl_publisher_fini(&my_pub, &my_node);
+  rc += rcl_timer_fini(&my_timer);
+  rc += rcl_subscription_fini(&my_sub, &my_node);
+  rc += rcl_node_fini(&my_node);
+  rc += rclc_support_fini(&support);
+
+  if (rc != RCL_RET_OK) {
+    printf("Error while cleaning up!\n");
+    return -1;
+  }
+  ```
