# xarm-developer/xarm_ros architecture

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

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

## Overview

##### Project type and purpose
- This is a robotics integration framework built on ROS (1) for UFACTORY xArm series arms (xArm5/6/7, Lite6/UF850).
- It comprises multiple ROS packages for description (URDF/Xacro/meshes), simulation (Gazebo), hardware drivers, controllers, MoveIt! configurations, planning services, API wrappers, vision demos, and example launch scripts.

##### File structure
- Top-level ROS packages:
- xarm_description: URDF/Xacro, meshes, gazebo plugins
- xarm_gazebo: Gazebo worlds, launch files, plugins
- xarm_controller: ros_control hardware_interface, controller definitions, C++ nodes
- xarm_bringup: driver launch files for real hardware
- xarm_api and xarm_msgs: C++/Python SDK wrappers, ROS services, messages
- xarm_planner: simple MoveIt!-based planning service
- xarm_***moveit_config / uf_robot_moveit_config***: MoveIt! setup for each robot model
- xarm_moveit_servo: real-time jog interface (joystick/keyboard/SpaceMouse)
- xarm_vision: sample vision demos (hand-eye calibration, object detection, grasping)
- examples: various usage demos
- ROS build files: CMakeLists.txt, package.xml, launch/*.launch, config/*.yaml
- Documentation in doc/ and README files

##### README
- Describes system capabilities: direct driver control, MoveIt! planning, Gazebo simulation, joystick/keyboard servo, vision demos.
- Lists dependencies: ros_control, gazebo_ros_pkgs, MoveIt!, RealSense libraries, easy_handeye, find_object_2d.
- Defines ROS topics (/xarm/xarm_states, /joint_states, /controller_gpio_states), services (/xarm/move_joint, /xarm/set_mode, etc.), actions (gripper_move).
- Explains “mode” architecture (position, velocity, online replanning, free-drive).

##### Be very detailed
- Launch files as orchestrators that wire simulation vs real hardware, MoveIt! config selection, add_realsense_d435i, add_gripper flags.
- Essential elements: hardware, simulation plugin, URDF model, controllers, API, planning, application.
- Don’t overcomplicate: group low-level nodes into logical layers and show their interactions clearly.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef roscore fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef driver fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef simulation fill:#FFA500,stroke:#333,stroke-width:1px
    classDef planning fill:#90EE90,stroke:#333,stroke-width:1px
    classDef application fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef messaging fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef userinput fill:#FFE4B5,stroke:#333,stroke-width:1px

    %% ROS Core Layer
    subgraph "ROS Core Layer"
        ROSMaster(("ROS Master")):::roscore
    end

    %% Hardware Abstraction & Driver Layer
    subgraph "Hardware Abstraction & Driver Layer"
        xarm_bringup["xarm_bringup: xarm_driver_node"]:::driver
        xarm_controller_node["xarm_controller: control_node"]:::driver
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        xarm_description["xarm_description: URDF/Xacro"]:::simulation
        xarm_gazebo["xarm_gazebo: Gazebo Simulation"]:::simulation
    end

    %% API & Messaging Layer
    subgraph "API & Messaging Layer"
        xarm_msgs["xarm_msgs: Message/Service Definitions"]:::messaging
        xarm_api["xarm_api: SDK Wrapper & Client"]:::messaging
    end

    %% Planning & Control Layer
    subgraph "Planning & Control Layer"
        move_group["MoveIt! move_group"]:::planning
        xarm_planner["xarm_planner: Simple Planner"]:::planning
        xarm_moveit_servo["xarm_moveit_servo: Jog Interface"]:::application
    end

    %% Vision & Perception Layer
    subgraph "Vision & Perception Layer"
        xarm_vision["xarm_vision: Vision Demos"]:::application
    end

    %% User Interface Layer
    subgraph "User Interface Layer"
        user_inputs[(Joystick/Keyboard/SpaceMouse)]:::userinput
        rviz["RViz / MoveIt! GUI"]:::application
        examples["examples: Demo Launches"]:::application
    end

    %% Topics & Services
    topic_states["/xarm/xarm_states\n/joint_states\n/controller_gpio_states"]:::roscore
    service_moves["/xarm/move_joint\n/xarm/set_mode"]:::roscore
    action_gripper["gripper_move (action)"]:::roscore
    camera_topic["/camera/color/image_raw"]:::roscore

    %% Connections
    ROSMaster --- topic_states
    ROSMaster --- service_moves
    ROSMaster --- action_gripper
    ROSMaster --- camera_topic

    xarm_bringup -->|publishes| topic_states
    xarm_bringup -->|offers| service_moves
    xarm_controller_node -->|controls hardware| xarm_bringup
    xarm_controller_node -->|subscribes| topic_states
    xarm_controller_node -->|publishes| topic_states

    xarm_description -->|provides model| xarm_gazebo
    xarm_gazebo -->|publishes fake state| topic_states
    xarm_gazebo -->|subscribes| service_moves

    xarm_msgs -->|definitions| xarm_api
    xarm_api -->|calls| xarm_bringup
    xarm_api -->|offers| service_moves

    move_group -->|subscribes| topic_states
    move_group -->|calls| service_moves
    move_group -->|action| action_gripper

    xarm_planner -->|calls| move_group
    xarm_planner -->|offers| service_moves

    xarm_moveit_servo -->|subscribes| user_inputs
    xarm_moveit_servo -->|publishes| service_moves

    xarm_vision -->|subscribes| camera_topic
    xarm_vision -->|broadcast TF| move_group
    xarm_vision -->|requests| service_moves

    rviz -->|visualizes| topic_states
    rviz -->|interacts| move_group

    examples -->|launch| xarm_bringup
    examples -->|launch| xarm_gazebo
    examples -->|launch| move_group
    examples -->|launch| xarm_planner
    examples -->|launch| xarm_moveit_servo
    examples -->|launch| xarm_vision

    %% Click Events
    click xarm_bringup "https://github.com/xarm-developer/xarm_ros/blob/master/xarm_bringup/launch/xarm_driver_common.launch"
    click xarm_controller_node "https://github.com/xarm-developer/xarm_ros/blob/master/xarm_controller/src/xarm_control_node.cpp"
    click xarm_description "https://github.com/xarm-developer/xarm_ros/blob/master/xarm_description/urdf/xarm5.urdf.xacro"
    click xarm_gazebo "https://github.com/xarm-developer/xarm_ros/blob/master/xarm_gazebo/launch/xarm5_beside_table.launch"
    click xarm_msgs "https://github.com/xarm-developer/xarm_ros/blob/master/xarm_msgs/msg/RobotMsg.msg"
    click xarm_api "https://github.com/xarm-developer/xarm_ros/blob/master/xarm_api/src/xarm_driver_node.cpp"
    click xarm_planner "https://github.com/xarm-developer/xarm_ros/blob/master/xarm_planner/src/xarm_simple_planner.cpp"
    click xarm_moveit_servo "https://github.com/xarm-developer/xarm_ros/blob/master/xarm_moveit_servo/src/xarm_joystick_input.cpp"
    click xarm_vision "https://github.com/xarm-developer/xarm_ros/blob/master/xarm_vision/camera_demo/scripts/color_recognition.py"
    click examples "https://github.com/xarm-developer/xarm_ros/blob/master/examples/multi_xarm5/launch/two_sim_xarm5.launch"
```
