Update parameters

Author: Acuadros95

_docs/tutorials/programming_rcl_rclc/parameters/parameters.md

@@ -1,38 +1,79 @@
 ---
-title: Parameters
+title: Parameter server
 permalink: /docs/tutorials/programming_rcl_rclc/parameters/
 ---
 
-## <a name="parameters"/>Parameters
-// TODO: add link to example
+ROS 2 parameter allow the user to create variables on a node and manipulate/read them with different ROS2 commands. Further information about ROS 2 parameters can be found [here](https://docs.ros.org/en/galactic/Tutorials/Parameters/Understanding-ROS2-Parameters.html)
 
-## <a name="parameters_server"/>Creating a parameter server
- 
+Ready to use code related to this tutorial can be found in [`micro-ROS-demos/rclc/parameter_server`](https://github.com/micro-ROS/micro-ROS-demos/blob/galactic/rclc/parameter_server/main.c) folder. Fragments of code from this example is used on this tutorial.
 
-```C
-// Parameter server object
-rclc_parameter_server_t param_server;
+Note: micro-ROS parameter server is only supported on ROS2 galactic distribution
 
-// Initialize parameter server with default configuration
-rcl_ret_t rc = rclc_parameter_server_init_default(&param_server, &node);
+## <a name="parameters_init"/>Initialization
 
-if (RCL_RET_OK != rc) {
-  printf("Error creating parameter server\n");
-  return -1;
-}
+- Default initialization:
+    ```C
+    // Parameter server object
+    rclc_parameter_server_t param_server;
 
-// Configure executor with atleast RCLC_PARAMETER_EXECUTOR_HANDLES_NUMBER handles
-rclc_executor_t executor;
-rclc_executor_init(&executor, &support.context, RCLC_PARAMETER_EXECUTOR_HANDLES_NUMBER, &allocator);
+    // Initialize parameter server with default configuration
+    rcl_ret_t rc = rclc_parameter_server_init_default(&param_server, &node);
 
-// Add parameter server to executor
-rc = rclc_executor_add_parameter_server(&executor, &param_server, NULL);
-```
+    if (RCL_RET_OK != rc) {
+    ... // Handle error
+    return -1;
+    }
+    ```
 
-- Parameter changed callback
+// TODO: explain options
+- Custom options:
+    ```C
+    // Parameter server object
+    rclc_parameter_server_t param_server;
 
-When adding the paramater server to the executor, a callback for parameter changes can be passed.
-This callback will be called after a parameter value is modified.
+    // Define 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(&param_server, &node, &options);
+
+    if (RCL_RET_OK != rc) {
+    ... // Handle error
+    return -1;
+    }
+    ```
+
+- Memory and executor requirements:
+    The variable `RCLC_PARAMETER_EXECUTOR_HANDLES_NUMBER` defines the RCLC executor handles required for a parameter server. 
+    This needs to be taken into account when initializing the executor and on the colcon memory configuration of the `rmw-microxredds` package, which will need atleast 4 services and 1 publisher:
+
+    ```C
+    # colcon.meta example with minimum memory requirements to use 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=4",
+                    "-DRMW_UXRCE_MAX_CLIENTS=0"
+                ]
+            }
+        }
+    }
+    ```
+    
+    ```C
+    // 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_PARAMETER_EXECUTOR_HANDLES_NUMBER, &allocator);
+    ```
+  
+## <a name="parameters_callback"/>Callback
+
+When adding the paramater server to the executor, a callback can be configured.
+This callback will be executed after a parameter value is modified.
 
 A pointer to the changed parameter is passed as first and only argument. Example:
 ```C
@@ -60,14 +101,19 @@ void on_parameter_changed(Parameter * param)
 
     printf("\n");
 }
-
+```
+Once the parameter server and the executor are initialized, the parameter server must be added to the executor in order to accept parameters commands from ROS2:
+```C
 // Add parameter server to executor including defined callback
 rc = rclc_executor_add_parameter_server(&executor, &param_server, on_parameter_changed);
 ```
 
-// TODO: explain options on creation
-// TODO: explain destruction
-// TODO: explain memory requirements
+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, &param_server, NULL);
+```
+
 
 ## <a name="parameters_add"/>Add a parameter
 
@@ -88,7 +134,7 @@ rc = rclc_parameter_set_bool(&param_server, parameter_name, param_value);
 rc = rclc_parameter_get_bool(&param_server, "param1", &param_value);
 
 if (RCL_RET_OK != rc) {
-  // Handle error
+  ... // Handle error
   return -1;
 }
 ```
@@ -122,3 +168,15 @@ 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);
 ```
+
+## <a name="parameters_end"/>Destroy the parameter server
+
+```C
+// Delete parameter server
+rcl_ret_t rc = rclc_parameter_server_fini(&param_server, &node);
+
+if (rc == RCL_RET_OK) {
+  ...  // Handle error
+  return -1;
+}
+```

_docs/tutorials/programming_rcl_rclc/pub_sub/pub_sub.md

@@ -3,39 +3,43 @@ title: Publishers and Subscriptions
 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)
+
+Ready to use code related to this tutorial can be found in [`micro-ROS-demos/rclc/int32_publisher`](https://github.com/micro-ROS/micro-ROS-demos/blob/foxy/rclc/int32_publisher/main.c) and [`micro-ROS-demos/rclc/int32_subscriber`](https://github.com/micro-ROS/micro-ROS-demos/blob/foxy/rclc/int32_subscriber/main.c) folders. Fragments of code from this examples are used on this tutorial.
+
 ## <a name="pub"/>Publisher
 
 ### <a name="pub_init"/>Initialization
 
-Starting from a code where RCL is initialized and a micro-ROS node is created, there are tree ways to initialize a publisher:
+Starting from a code where RCL is initialized and a micro-ROS node is created, there are tree ways to initialize a publisher depending on the desired quality-of-service configuration:
 
 // TODO: explain and link diferences between each approach on QoS section
 
-- Reliable publisher:
+- Reliable:
   ```C
   // Publisher object
   rcl_publisher_t publisher;
   const char * topic_name = "test_topic";
 
-  // TODO: explain type_support?
   // Get message type support
   const rosidl_message_type_support_t * type_support = ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, Int32);
 
-  // Create a reliable rcl publisher.
+  // Creates a reliable rcl publisher
   rcl_ret_t rc = rclc_publisher_init_default(&publisher, &node, &type_support, &topic_name);
 
   if (RCL_RET_OK != rc) {
     ...  // Handle error
     return -1;
   }
   ```
-  
-  Reliable publishers will wait for confirmation for each published message, which leads to blocking `rcl_publish` calls. The `rmw-microxrcedds` offer an API to configure the acknowledgement timeout for each publisher:
+
+  // TODO: move to micro-ROS features section?
+  Reliable publishers will wait for confirmation for each published message, which leads to blocking `rcl_publish` calls, `rmw-microxrcedds` offers an API to configure the acknowledgement timeout for each publisher:
 
   ```C
   // Set confirmation timeout in milliseconds
-  int publish_timeout = 1000; 
-  rc = rmw_uros_set_publisher_session_timeout(&publisher, publish_timeout);
+  int ack_timeout = 1000; 
+  rc = rmw_uros_set_publisher_session_timeout(&publisher, ack_timeout);
 
   if (RCL_RET_OK != rc) {
     ...  // Handle error
@@ -45,11 +49,7 @@ Starting from a code where RCL is initialized and a micro-ROS node is created, t
 
   The default value for all publishers is configured at compilation time by the cmake variable `RMW_UXRCE_PUBLISH_RELIABLE_TIMEOUT`.
 
-- Best effort publisher:
-
-  // TODO: explain in QoS section?
-  Publish the message without reception confirmation, allowing a faster publish rate.
-
+- Best effort:
   ```C
   // Publisher object
   rcl_publisher_t publisher;
@@ -58,7 +58,7 @@ Starting from a code where RCL is initialized and a micro-ROS node is created, t
   // Get message type support
   const rosidl_message_type_support_t * type_support = ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, Int32);
 
-  // Creates an rcl publisher with quality-of-service option best effort
+  // Creates a best effort rcl publisher
   rcl_ret_t rc = rclc_publisher_init_best_effort(&publisher, &node, &type_support, &topic_name);
 
   if (RCL_RET_OK != rc) {
@@ -67,7 +67,7 @@ Starting from a code where RCL is initialized and a micro-ROS node is created, t
   }
   ```
 
-- Add QoS API
+- Custom QoS:
 
   ```C
   // Publisher object
@@ -80,7 +80,7 @@ Starting from a code where RCL is initialized and a micro-ROS node is created, t
   // Set publisher QoS
   const rmw_qos_profile_t * qos_profile = &rmw_qos_profile_default;
 
-  // Creates an rcl publisher with customized quality-of-service options
+  // Creates a rcl publisher with customized quality-of-service options
   rcl_ret_t rc = rclc_publisher_init(&publisher, &node, &type_support, &topic_name, qos_profile);
 
   if (RCL_RET_OK != rc) {
@@ -108,12 +108,12 @@ if (rc != RCL_RET_OK) {
 }
 ```
 
-Note: `rcl_publish` is thread safe and can be called from multiple threads
+Note: `rcl_publish` is thread safe and can be called from multiple threads.
 
 ## <a name="pub_end"/>Destroy a publisher
 
 Deallocates memory
-After calling, the node will no longer be advertising that it is publishing
+After finishing the publisher, the node will no longer be advertising that it is publishing
 on this topic (assuming this is the only publisher on this topic).
 
 ```C
@@ -143,10 +143,7 @@ The suscriptor initialization is almost identical to the publisher one:
   // Get message type support
   const rosidl_message_type_support_t * type_support = ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, Int32);
 
-  // Set client QoS
-  const rmw_qos_profile_t * qos_profile = &rmw_qos_profile_default;
-
-  // Initialize subscriber with default configuration
+  // Initialize a realiable subscriber
   rcl_ret_t rc = rclc_subscription_init_default(&subscriber, &node, &type_support, &topic_name);
 
   if (RCL_RET_OK != rc) {
@@ -187,7 +184,7 @@ The suscriptor initialization is almost identical to the publisher one:
   // Set client QoS
   const rmw_qos_profile_t * qos_profile = &rmw_qos_profile_default;
 
-  // Initialize server with customized quality-of-service options
+  // Initialize a subscriber with customized quality-of-service options
   rcl_ret_t rc = rclc_subscription_init(&subscriber, &node, &type_support, &topic_name, qos_profile);
 
   if (RCL_RET_OK != rc) {
@@ -198,8 +195,6 @@ The suscriptor initialization is almost identical to the publisher one:
 
 ### <a name="sub_callback"/>Callbacks
 
-// TODO: explain message memory allocation and link to tutorial
-
 ```C
 void subscription_callback(const void * msgin)
 {
@@ -214,7 +209,7 @@ void subscription_callback(const void * msgin)
 Once the subscriber and the executor are initialized, the subscriber callback must be added to the executor to receive incoming publications once the executor is spinning:
 
 ```C
-// Message object
+// Message object to save publication data
 std_msgs__msg__Int32 msg;
 
 // Add subscription to the executor
@@ -234,7 +229,8 @@ Destroys any automatically created infrastructure and deallocates memory.
 // Destroy
 rcl_ret_t rc = rcl_publisher_fini(&subscriber, &node);
 
-if (rc == RCL_RET_OK) {
-  printf("Published message with value: %d\n", msg.data);
+if (RCL_RET_OK != rc) {
+  ...  // Handle error
+  return -1;
 }
 ```

_docs/tutorials/programming_rcl_rclc/service/services.md

@@ -33,8 +33,21 @@ Starting from a code where RCL is initialized and a micro-ROS node is created, t
   }
   ```
   
-  // TODO: Add timeout API for reliable service
+  A reliable service server will wait for confirmation for each response sended, which can increase the blocking time of the executor spins, `rmw-microxrcedds` offers an API to configure the acknowledgement timeout for each service:
 
+  ```C
+  // Set confirmation timeout in milliseconds
+  int ack_timeout = 1000; 
+  rc = rmw_uros_set_service_session_timeout(&service, ack_timeout);
+
+  if (RCL_RET_OK != rc) {
+    ...  // Handle error
+    return -1;
+  }
+  ```
+
+  The default value for all clients is configured at compilation time by the cmake variable `RMW_UXRCE_PUBLISH_RELIABLE_TIMEOUT`.
+  
 - Best effort:  
 
   ```C
@@ -154,8 +167,21 @@ The service client initialization is almost identical to the server one:
   }
   ```
   
-  // TODO: Add timeout API for reliable service
+  A reliable service client will wait for confirmation for each request sended, which can increase the blocking time of the executor spins, `rmw-microxrcedds` offers an API to configure the acknowledgement timeout for each client:
+
+  ```C
+  // Set confirmation timeout in milliseconds
+  int ack_timeout = 1000; 
+  rc = rmw_uros_set_client_session_timeout(&client, ack_timeout);
+
+  if (RCL_RET_OK != rc) {
+    ...  // Handle error
+    return -1;
+  }
+  ```
 
+  The default value for all clients is configured at compilation time by the cmake variable `RMW_UXRCE_PUBLISH_RELIABLE_TIMEOUT`.
+
 - Best effort:  
 
   ```C