Subscribing to the PWM Servo Topic

1. Experiment Objective

In this experiment, you will learn how to control the two PWM servos on the MicroROS-V2 control board through micro-ROS topics. Through this example, you will master multiple-subscriber management, the use of FreeRTOS Task Notifications, and the design pattern of using critical sections to protect shared data. This example subscribes to Int32 messages on the topics /servo_s1 and /servo_s2 respectively. The lower 8 bits of the message are parsed as an angle value of type int8_t, controlling the corresponding servo to rotate to the target angle.

2. Experiment Principle

1. Keyword Explanation

2. Technical Architecture

This experiment builds a control chain from the ROS2 host to the two PWM servos on the ESP32:

• Hardware layer: The MicroROS-V2 control board (ESP32), with servo S1 connected to GPIO8 and servo S2 connected to GPIO16, driven by the MCPWM peripheral

• Transport layer: Uses the UDP protocol, communicating with the ROS2 host through the micro-ROS Agent

• Node configuration: Node name servo_subscriber, subscribing to topics /servo_s1 and /servo_s2

• Message type: std_msgs/msg/Int32, with the lower 8 bits parsed as an angle value of type int8_t

• QoS mode: Reliable (default), ensuring servo control commands are reliably delivered

• Data flow: ROS2 host publishes a message → Agent → UDP → micro-ROS stack → executor → subscription callback (updates the shared angle values + task notification) → servo worker thread → reads the target angle in a critical section → Servo_Set_Angle() → MCPWM hardware control

• Design pattern: Three-task separation (micro-ROS communication task + servo execution task), critical sections protect shared data, and task notifications serve as wake-up signals

3. Core Topic Quick Reference

Firmware Downlink (Control Commands)

Usage Example:

# Servo S1 rotates to 90°
ros2 topic pub /servo_s1 std_msgs/msg/Int32 "data: 90"
# Servo S2 rotates to -45° (camera facing straight ahead)
ros2 topic pub /servo_s2 std_msgs/msg/Int32 "data: -45"

4. Middleware Configuration

micro-ROS uses a static memory model (RCUTILS_AVOID_DYNAMIC_ALLOCATION=ON), all entity memory is pre-allocated at compile time, and runtime dynamic creation is not supported.

Configuration file: ~/esp/extra_components/micro_ros_espidf_component/colcon.meta

| RMW_UXRCE_TRANSPORT | udp | UDP transport (Wi-Fi communication) | | RMW_UXRCE_MAX_PUBLISHERS | 6 | Maximum number of publishers | | RMW_UXRCE_MAX_SUBSCRIPTIONS | 6 | Maximum number of subscribers | | RMW_UXRCE_MAX_NODES | 1 | Maximum number of nodes | | RMW_UXRCE_MAX_SERVICES | 0 | Services not supported | | RMW_UXRCE_MAX_CLIENTS | 0 | Clients not supported | | RMW_UXRCE_MAX_HISTORY | 1 | History depth = 1, no message queuing | | UCLIENT_UDP_TRANSPORT_MTU | 4096 | Maximum UDP packet size 4 KB | | UCLIENT_MIN_HEARTBEAT_TIME_INTERVAL | 1 | Agent heartbeat interval 1 ms |

Key Constraints:

• MAX_HISTORY=1 means there is no message buffer queue, so uplink topics (firmware → host) uniformly use best_effort QoS

• MAX_SERVICES=0, MAX_CLIENTS=0 means only topic communication is supported, not Service/Client

• After modifying colcon.meta, the micro-ROS library must be recompiled for the changes to take effect: run idf.py clean-microros in the project directory to clean and rebuild the micro-ROS library, then idf.py build to compile the firmware

3. Experiment Steps

1. Hardware Preparation

2. Prerequisites

1. The ESP32-IDF development environment has been set up

2. The MicroROS-V2 control board is connected to the computer via USB

3. Configure the Wi-Fi SSID, password, Agent IP and port via idf.py menuconfig (the micro_ros menu item)

   xxxxxxxxxx
   cd ~/esp/microROS_samples/servo_subscriber
   source ~/esp/esp-idf/export.sh
   idf.py menuconfig
   

   

   4. Select example-app setting to set the domain ID to be consistent with the virtual machine

   

   After configuration, press "s" to save and press "q" to exit the configuration interface.

4. Connect servo S1 to GPIO8 and servo S2 to GPIO16

3. Start micro_ros_agent (Terminal 1)

Start the micro-ROS Agent on the ROS2 host:

xxxxxxxxxx
cd ~/uros_ws
source install/local_setup.bash
ros2 run micro_ros_agent micro_ros_agent udp4 --port 8090 -v4

4. Build and Flash (Terminal 2)

​x

cd ~/esp/microROS_samples/servo_subscriber
source ~/esp/esp-idf/export.sh
idf.py build flash monitor

5. How to Stop

1. Press Ctrl+] in Terminal 2 to exit the serial monitor (stop firmware execution)

2. Press Ctrl+C in Terminal 1 to stop micro_ros_agent

4. Experiment Result

After the build and flash succeed, publish servo control commands on the ROS2 host:

xxxxxxxxxx
# Servo S1 rotates to 90°
ros2 topic pub /servo_s1 std_msgs/msg/Int32 "data: 90"

# Servo S1 rotates to -90°
ros2 topic pub /servo_s1 std_msgs/msg/Int32 "data: -90"

# Servo S2 rotates to 0° (camera facing upward)
ros2 topic pub /servo_s2 std_msgs/msg/Int32 "data: 0"

# Servo S2 rotates to -45° (camera facing straight ahead, default angle)
ros2 topic pub /servo_s2 std_msgs/msg/Int32 "data: -45"

The control board serial port will output:

xxxxxxxxxx
I (xxx) MAIN: Agent reachable: 192.168.x.x:8888
I (xxx) MAIN: micro-ROS servo subscriber init done
I (xxx) MAIN: Servo S1: 90
I (xxx) MAIN: Servo S2: -45

Data encoding quick reference table:

Tip: The data field of std_msgs/msg/Int32 is the signed int32 type. On the ROS2 command line, you can directly use the signed decimal value (such as data: -45), without manually converting to an unsigned representation.

5. Program Analysis

Source code paths:

• Firmware source code: ~/esp/microROS_samples/servo_subscriber/main/main.c

• Servo driver: ~/esp/microROS_samples/servo_subscriber/components/servo/servo.h, servo.c

1. Main Program Logic

main/main.c adopts a three-task separation design:

1. In app_main():

   • Calls Servo_Init() to initialize the MCPWM peripherals for the two servos

   • Creates the servo_worker_task task

   • Initializes the Wi-Fi network

   • Creates the micro_ros_task task

2. In micro_ros_task:

   • Creates the node servo_subscriber

   • Subscribes to topics /servo_s1 and /servo_s2 in Reliable mode (servo control requires reliable transmission)

   • The two subscription callbacks update the target angle of the corresponding servo and wake up the execution task via task notification

3. In servo_worker_task:

   • Waits for the task notification

   • Reads the target angles under the protection of a critical section

   • Calls Servo_Set_Angle() to drive the servos

2. Key Components

components/servo/servo.h — Servo driver interface:

Parameter definition file: ~/esp/microROS_samples/servo_subscriber/components/servo/servo.h

Servo angle limits:

components/servo/servo.c — Core servo driver functions:

Angle encoding/decoding rules:

The angle command uses the lower 8 bits of the Int32 message, parsed as int8_t:

xxxxxxxxxx
static inline int8_t servo_decode_angle_compat(int32_t raw_value)
{
    return (int8_t)(raw_value & 0xFF);
}

Examples:

• data: 90 (hexadecimal 0x0000005A) → lower 8 bits 0x5A = 90 → 90°

• data: -90 (hexadecimal 0xFFFFFFA6) → lower 8 bits 0xA6 = -90 → -90°

Task notification and critical section design:

Source file: ~/esp/microROS_samples/servo_subscriber/main/main.c

xxxxxxxxxx
/* Subscription callback: only updates the target value, does not directly drive the servo */
static void servo_s1_callback(const void *msgin)
{
    const std_msgs__msg__Int32 *msg = (const std_msgs__msg__Int32 *)msgin;
    const int8_t angle = servo_decode_angle_compat(msg->data);

    taskENTER_CRITICAL(&s_servo_lock);
    s_servo_target_s1 = angle;
    taskEXIT_CRITICAL(&s_servo_lock);

    (void)xTaskNotify(s_servo_worker_handle, SERVO_NOTIFY_S1, eSetBits);
}

/* Servo execution task: all actual Servo_Set_Angle calls are executed here uniformly */
static void servo_worker_task(void *arg)
{
    while (1) {
        uint32_t notify_value = 0;
        xTaskNotifyWait(0, UINT32_MAX, &notify_value, portMAX_DELAY);

        taskENTER_CRITICAL(&s_servo_lock);
        int8_t angle_s1 = s_servo_target_s1;
        int8_t angle_s2 = s_servo_target_s2;
        taskEXIT_CRITICAL(&s_servo_lock);

        if ((notify_value & SERVO_NOTIFY_S1) != 0U) {
            Servo_Set_Angle(SERVO_ID_S1, angle_s1);
        }
        if ((notify_value & SERVO_NOTIFY_S2) != 0U) {
            Servo_Set_Angle(SERVO_ID_S2, angle_s2);
        }
    }
}

Topic configuration:

Parameter definition file: ~/esp/microROS_samples/servo_subscriber/main/main.c

6. Common Problems

Safety tip: The servo angles are automatically limited to the defined ranges (see SERVO_Sx_MIN_ANGLE and SERVO_Sx_MAX_ANGLE in servo.h). Out-of-range values are clamped to protect the servos from damage.