# micro-ros/micro_ros_arduino architecture

> Architecture diagram of the GitHub repository micro-ros/micro_ros_arduino, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/micro-ros/micro_ros_arduino
- Repository: https://github.com/micro-ros/micro_ros_arduino

## Overview

##### Project Type and Purpose
- This is an embedded client-side library (“micro-ROS for Arduino”) that lets Arduino sketches participate as ROS 2 nodes.
- It provides a pre-compiled cross-platform C library wrapping ROS 2 client APIs (rcl, rclc) and the RMW transport (microxrcedds), plus message/service definitions.

##### High-Level Architecture Components
a. **User Application (Arduino Sketches)**
- Reside in `examples/*` or user projects
- `micro_ros_arduino.h` and call the micro-ROS client API (publishers, subscribers, services, actions)
b. **micro-ROS Arduino Library**
- Precompiled `.a` libraries under `src/<board>/libmicroros.a` (e.g. `cortex-m4/libmicroros.a`)
- Exposes a thin Arduino-friendly wrapper over:
- **rcl** (ROS 2 client library, nodes, publishers, subscribers)
- **rclc** (convenience C API over rcl)
- **rmw_microros** (transport binding layer)
- **rmw_microxrcedds_c** (lightweight XRCE-DDS implementation)
- **uxr** (XRCE-DDS client core for serialization, session, streams)
- **rcutils**, **rosidl_runtime_c**, **rosidl_typesupport_*** (message type support)
c. **Transport Layer**
- Default serial transport (`default_transport.cpp`)
- Optional Ethernet or Wi-Fi transports (`native_ethernet_transport.cpp`, `wifi_transport.cpp`)
- Implements physical I/O to the host running the micro-ROS Agent
d. **micro-ROS Agent** (out of repo, Docker container)
- Runs on a PC/RPi, presents a middleware bridge
- Talks to the embedded XRCE client over serial/TCP/UDP
- Bridges XRCE-DDS packets to native ROS 2 (DDS) topics/services, making the Arduino board appear as a regular ROS 2 node
e. **ROS 2 Core**
- DDS network, other ROS 2 nodes, tooling (rviz, ros2 topic, etc.)

##### Component Relationships & Data Flow
- The **Arduino Sketch** invokes publisher/subscriber APIs → links to
- **micro-ROS Library Layers** (wrapper → rcl/rclc → rmw_microros → rmw_microxrcedds) → hands off serialized messages to
- **uxr Client** → uses **Transport** (serial / Ethernet / Wi-Fi) over USB/UART or network → lands on
- **micro-ROS Agent** process → forwards packets over DDS → to **ROS 2 Core**

##### Architectural Patterns & Principles
- **Layered Abstraction**: application → client API → middleware → transport
- **Separation of Concerns**: transport is pluggable (serial vs. Ethernet vs. Wi-Fi), application code remains unchanged
- **Client-Server**: the embedded board is an XRCE-DDS client; the Agent is the server/gateway
- **Cross-Compilation / Meta-Build**: extras/library_generation uses CMake meta files (`colcon_*.meta`) to produce per-board static libraries

##### Technologies & Frameworks
- CMake / Docker (for library generation)
- Arduino IDE / CLI / PlatformIO (to compile sketches)
- eProsima Micro XRCE-DDS (lightweight DDS)
- ROS 2 client libraries (rcl, rclc, rcutils)
- Arduino cores for various MCUs (Cortex-M, ESP32, Teensy, etc.)

## Diagram (Mermaid)

```mermaid
graph TB
    Sketch["Arduino Sketches"]:::application
    Wrapper["micro_ros_arduino.h"]:::library
    rcl["rcl"]:::library
    rclc["rclc"]:::library
    rmw1["rmw_microros"]:::library
    rmw2["rmw_microxrcedds_c"]:::library
    uxr["UXRCE client (session & streams)"]:::library
    subgraph "Precompiled .a Libraries"
        cortexm0["cortex-m0plus/libmicroros.a"]:::library
        cortexm3["cortex-m3/libmicroros.a"]:::library
        cortexm4["cortex-m4/libmicroros.a"]:::library
        cortexm7["cortex-m7/.../libmicroros.a"]:::library
        esp32["esp32/libmicroros.a"]:::library
        imxrt["imxrt1062/.../libmicroros.a"]:::library
        mk20["mk20dx256/libmicroros.a"]:::library
        mk64["mk64fx512/.../libmicroros.a"]:::library
        mk66["mk66fx1m0/.../libmicroros.a"]:::library
    end
    subgraph "Message/Service Definitions"
        msgs["src/<*_msgs>/"]:::library
    end
    utilities["src/micro_ros_utilities/"]:::library
    subgraph "Transport Layer"
        serial["Serial Transport (default)"]:::transport
        eth["Ethernet Transport"]:::transport
        wifi["Wi-Fi Transport"]:::transport
    end
    Agent["micro-ROS Agent (Docker)"]:::external
    ROS2["ROS 2 Core / DDS Network"]:::external
    extras["extras/library_generation/"]:::external

    Sketch --> Wrapper --> rcl --> rclc --> rmw1 --> rmw2 --> uxr
    uxr --> serial
    uxr -.-> eth
    uxr -.-> wifi
    serial --> Agent
    eth --> Agent
    wifi --> Agent
    Agent --> ROS2

    extras --> cortexm0
    extras --> cortexm3
    extras --> cortexm4
    extras --> cortexm7
    extras --> esp32
    extras --> imxrt
    extras --> mk20
    extras --> mk64
    extras --> mk66

    click Sketch "https://github.com/micro-ros/micro_ros_arduino/tree/kilted/examples/"
    click Wrapper "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/micro_ros_arduino.h"
    click cortexm0 "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/cortex-m0plus/libmicroros.a"
    click cortexm3 "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/cortex-m3/libmicroros.a"
    click cortexm4 "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/cortex-m4/libmicroros.a"
    click cortexm7 "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/cortex-m7/.../libmicroros.a"
    click esp32 "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/esp32/libmicroros.a"
    click imxrt "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/imxrt1062/.../libmicroros.a"
    click mk20 "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/mk20dx256/libmicroros.a"
    click mk64 "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/mk64fx512/.../libmicroros.a"
    click mk66 "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/mk66fx1m0/.../libmicroros.a"
    click rcl "https://github.com/micro-ros/micro_ros_arduino/tree/kilted/src/rcl/"
    click rclc "https://github.com/micro-ros/micro_ros_arduino/tree/kilted/src/rclc/"
    click rmw1 "https://github.com/micro-ros/micro_ros_arduino/tree/kilted/src/rmw_microros/"
    click rmw2 "https://github.com/micro-ros/micro_ros_arduino/tree/kilted/src/rmw_microxrcedds_c/"
    click uxr "https://github.com/micro-ros/micro_ros_arduino/tree/kilted/src/uxr/"
    click serial "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/default_transport.cpp"
    click eth "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/native_ethernet_transport.cpp"
    click wifi "https://github.com/micro-ros/micro_ros_arduino/blob/kilted/src/wifi_transport.cpp"
    click msgs "https://github.com/micro-ros/micro_ros_arduino/tree/kilted/src/<*_msgs>/"
    click utilities "https://github.com/micro-ros/micro_ros_arduino/tree/kilted/src/micro_ros_utilities/"
    click extras "https://github.com/micro-ros/micro_ros_arduino/tree/kilted/extras/library_generation/"

    classDef application fill:#D0E6FA,stroke:#0066CC,color:#000
    classDef library fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef transport fill:#FFE6BF,stroke:#B5651D,color:#000
    classDef external fill:#E0E0E0,stroke:#666,color:#000
```
