Ros2 Microros

micro-ROS Instructions (Ubuntu 24.04 LTS & ROS 2 Jazzy)

1. Core Principles & Architecture

• Target OS & ROS Distro: Ubuntu 24.04 LTS & ROS 2 Jazzy Jalisco.
• Embedded Integration: micro-ROS connects resource-constrained microcontrollers (STM32, ESP32, FreeRTOS, Zephyr) to the ROS 2 DDS graph via micro_ros_agent and rclc client library using Micro XRCE-DDS protocol.
• Zero Dynamic Allocation: Uses compile-time static memory pools (rmw_microxrcedds) to guarantee zero heap allocation during steady-state execution when dynamic allocation fallback (RMW_UXRCE_ALLOW_DYNAMIC_ALLOCATIONS=OFF) is configured.

2. Official Documentation Catalog

A. Master Documentation & Repositories

• Official micro-ROS Portal: https://micro.ros.org/
• micro-ROS GitHub Organization: https://github.com/micro-ROS
• micro-ROS Agent Repository: https://github.com/micro-ROS/micro-ros-agent
• microrossetup Build System: https://github.com/micro-ROS/micro_ros_setup
• rclc Client Library: https://github.com/ros2/rclc

3. Key Concepts & Patterns

A. Embedded Client Node Setup (rclc in C)

#include 
#include 
#include 
#include 

int main(void) {
  rcl_allocator_t allocator = rcl_get_default_allocator();
  rclc_support_t support = {0};
  rcl_node_t node = {0};
  rcl_publisher_t pub = {0};

  rclc_support_init(&support, 0, NULL, &allocator);
  rclc_node_init_default(&node, "mcu_node", "", &support);
  rclc_publisher_init_default(&pub, &node, ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, Int32), "chatter");

  // Clean up
  rcl_publisher_fini(&pub, &node);
  rcl_node_fini(&node);
  rclc_support_fini(&support);
  return 0;
}

B. Micro-ROS Agent Execution

# Serial Transport (e.g. UART to USB)
ros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyUSB0 -b 115200

# UDP Transport
ros2 run micro_ros_agent micro_ros_agent udp4 --port 8888

4. Symptom -> Root Cause -> Action

| Symptom | Likely root cause | Action | | :--- | :--- | :--- | | MCU node vanishes from graph after MCU reset, agent still running | XRCE session not re-created; firmware assumes a one-time init | Add a reconnect state machine: rmw_uros_ping_agent() periodically, re-init entities on failure | | rclc_support_init returns error on the MCU | Transport not reachable (wrong serial dev/baud, UDP port/IP) | Run the agent with -v6 verbose and watch for session establishment; verify transport config in firmware | | Publisher works but subscriber callback never fires | Executor never spun, or rclc_executor_init handle count smaller than the number of subscriptions/timers | Spin the executor in the main loop; count every subscription+timer+service in num_handles | | Hard fault / crash when publishing string or sequence messages | Message memory not allocated — rclc doesn't auto-allocate unbounded fields | Allocate with micro_ros_utilities_create_message_memory or assign static buffers before publishing | | Large messages never arrive | Payload exceeds XRCE-DDS stream/MTU buffer configured in the firmware | Increase the transport MTU/stream buffer in the colcon.meta / transport config, or shrink the message | | Best-effort topics flood then stall on serial | Serial bandwidth saturated: publish rate x message size exceeds baud rate | Lower publish rate, raise baud rate, or switch to UDP transport |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Leehyunbin0131
• Source: Leehyunbin0131/claude-ros2-skills
• License: MIT

Install and usage instructions live in the source repository linked above.