# xarm-developer/xarm_ros2 architecture

> Architecture diagram of the GitHub repository xarm-developer/xarm_ros2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xarm-developer/xarm_ros2
- Repository: https://github.com/xarm-developer/xarm_ros2

## Overview

##### Project type and purpose
- This is a “full-stack” ROS2 robotics framework (named xarm_ros2) that integrates robot description, simulation (Gazebo), motion planning (MoveIt2), control (ros2_control), API wrappers, and demonstration applications for the UFACTORY xArm series.
- It provides end-to-end support for real hardware and simulated robots: URDF/meshes → ROS nodes → controllers → planner → user interfaces (CLI, RViz, joystick, keyboard).

##### File structure
- Top-level packages (each a ROS2 or Python package):
- demo/mbot_demo – chassis+arm demo
- thirdparty/realsense_gazebo_plugin – Gazebo sensor plugin
- uf_ros_lib – common Python utilities and builder for MoveIt2 config
- xarm_msgs – ROS message/service definitions
- xarm_sdk – C++ SDK for low-level robot communication
- xarm_api – ROS service/topic wrapper around xarm_sdk
- xarm_controller – ros2_control hardware interface for real or fake robots
- xarm_description – URDF, SRDF, meshes, launch files for robot models
- xarm_gazebo – Gazebo world and plugin integration for simulation
- xarm_moveit_config – MoveIt2 configuration (planning pipelines, launch files, RViz)
- xarm_moveit_servo – Real-time servoing demo (joystick, keyboard) via moveit_servo
- xarm_planner – High-level planning node using MoveIt2 APIs and services
- Build and config files: CMakeLists.txt, package.xml, Python setup.py, YAML.

##### Extract architecture insights from README
- ROS2 Foxy–Rolling support, multiple branches
- Launch-driven architecture: each package exposes ROS2 launch points for simulation vs. real hardware
- Clear separation of concerns: description → Gazebo → controllers → API → planning → user interfaces

##### Detailed capture of essential elements
- Topics and services between them (e.g., /<hw_ns>/joint_states, trajectory execution interfaces)
- External dependencies (Gazebo, MoveIt2, controller_manager, xarm_sdk)
- Don’t omit uf_ros_lib or xarm_msgs—they are foundation blocks for message definitions and config building

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Robot Description Layer
    subgraph "Robot Description Layer"
        direction TB
        Desc["xarm_description"]:::description
        URDF["URDF/SRDF & Meshes"]:::document
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        direction TB
        RSPlugin["RealSense Gazebo Plugin"]:::simulation
        GazeboInt["xarm_gazebo"]:::simulation
        GazeboSim["Gazebo Simulator"]:::external
    end

    %% Control & Hardware Interface Layer
    subgraph "Control & Hardware Interface Layer"
        direction TB
        Controller["xarm_controller"]:::hardware
        APIWrapper["xarm_api"]:::hardware
        SDK["xarm_sdk"]:::hardware
        CtrlMgr["ros2_control / controller_manager"]:::external
    end

    %% Motion Planning Layer
    subgraph "Motion Planning Layer"
        direction TB
        UFBuilder["uf_ros_lib"]:::utility
        MoveItCfg["xarm_moveit_config"]:::planning
        Planner["xarm_planner"]:::planning
    end

    %% Servo & Teleop Layer
    subgraph "Servo & Teleop Layer"
        direction TB
        Servo["xarm_moveit_servo"]:::teleop
    end

    %% Utilities & Common Interfaces
    subgraph "Utilities & Common Interfaces"
        direction TB
        Msgs["xarm_msgs"]:::utility
    end

    %% Demo & CLI Applications
    subgraph "Demo & CLI Applications"
        direction TB
        Demo["demo/mbot_demo"]:::demo
        APITest["xarm_api tests"]:::demo
        PlannerTest["xarm_planner tests"]:::demo
    end

    %% Data Stores / Topics
    JointStates["/joint_states"]:::topic
    TrajCmds["/trajectory_commands"]:::topic
    RobotState["/robot_states"]:::topic

    %% Relationships
    Desc -->|provides URDF/SRDF| URDF
    URDF -->|loaded by| GazeboSim
    URDF -->|used by| MoveItCfg
    GazeboSim -->|spawns with plugins| RSPlugin
    GazeboSim -->|spawns with integration| GazeboInt
    RSPlugin -->|publishes| JointStates
    GazeboInt -->|publishes| JointStates
    GazeboSim -->|interfaces via| CtrlMgr
    CtrlMgr -->|manages| Controller
    CtrlMgr -->|manages simulated controllers from xarm_gazebo| GazeboInt
    Controller -->|hardware interface| CtrlMgr
    APIWrapper -->|calls| SDK
    APIWrapper -->|exposes ROS2 services/topics| Msgs
    SDK -->|TCP/IP to real robot| externalHardware["Real xArm Hardware"]:::external
    JointStates -->|input to| MoveItCfg
    MoveItCfg -->|generates pipelines| Planner
    Planner -->|sends trajectories| TrajCmds
    TrajCmds -->|to| CtrlMgr
    Servo -->|subscribes joystick/keyboard| UserInput["Joystick/Keyboard"]:::external
    Servo -->|sends servo cmds| TrajCmds
    Msgs -->|used by| Planner
    Msgs -->|used by| APIWrapper
    Demo -->|orchestrates| Controller
    Demo -->|uses| Planner
    APITest -->|tests| APIWrapper
    PlannerTest -->|tests| Planner

    %% Click Events
    click Desc "https://github.com/xarm-developer/xarm_ros2/tree/humble/xarm_description/"
    click RSPlugin "https://github.com/xarm-developer/xarm_ros2/tree/humble/thirdparty/realsense_gazebo_plugin/"
    click GazeboInt "https://github.com/xarm-developer/xarm_ros2/tree/humble/xarm_gazebo/"
    click Controller "https://github.com/xarm-developer/xarm_ros2/tree/humble/xarm_controller/"
    click APIWrapper "https://github.com/xarm-developer/xarm_ros2/tree/humble/xarm_api/"
    click SDK "https://github.com/xarm-developer/xarm_ros2/tree/humble/xarm_sdk/"
    click UFBuilder "https://github.com/xarm-developer/xarm_ros2/tree/humble/uf_ros_lib/"
    click MoveItCfg "https://github.com/xarm-developer/xarm_ros2/tree/humble/xarm_moveit_config/"
    click Planner "https://github.com/xarm-developer/xarm_ros2/tree/humble/xarm_planner/"
    click Servo "https://github.com/xarm-developer/xarm_ros2/tree/humble/xarm_moveit_servo/"
    click Msgs "https://github.com/xarm-developer/xarm_ros2/tree/humble/xarm_msgs/"
    click Demo "https://github.com/xarm-developer/xarm_ros2/tree/humble/demo/mbot_demo/"

    %% Styles
    classDef description fill:#D0E4F5,stroke:#0366D6,color:#0366D6;
    classDef simulation fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32;
    classDef hardware fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef planning fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    classDef teleop fill:#FFFDE7,stroke:#FBC02D,color:#F57F17;
    classDef utility fill:#ECEFF1,stroke:#607D8B,color:#37474F;
    classDef demo fill:#FBE9E7,stroke:#D84315,color:#BF360C;
    classDef external fill:#FFFFFF,stroke:#AAAAAA,color:#555555,stroke-dasharray: 5 5;
    classDef document fill:#FFFBEE,stroke:#B18904,color:#B18904;
    classDef topic fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 2 2;
```
