# ucla-robot-intelligence-lab/realman-env architecture

> Architecture diagram of the GitHub repository ucla-robot-intelligence-lab/realman-env, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ucla-robot-intelligence-lab/realman-env
- Repository: https://github.com/ucla-robot-intelligence-lab/realman-env

## Overview

##### Project type and purpose
- This is a robotics middleware workspace built on ROS 2 Foxy. It combines Python and C++ packages to control AGVs, dual-arm robotic manipulators, Realsense cameras, servo drivers, and demos (both real and simulated via Gazebo & MoveIt). It is not a web app but a multi‐package ROS 2 system orchestrating sensors, controllers, drivers, planners, and simulators.

##### Top-level components
a. ROS 2 Core
- The ROS 2 middleware (DDS) that underpins all inter‐node communication.
b. Sensor subsystem
- Packages: ros2_realsense2 → realsense2_camera (node publishes Image/PointCloud/IMU topics)
c. Controller subsystem
- python_controller (keyboard_base_controller, joystick_base_controller) publishes control topics
d. AGV & mobility subsystem
- ros2_agv_robot (C++ nodes: exec_pre_task, exectask, goto_mark, monitor, stepctrl)
e. Dual-arm manipulator subsystem
- ros2_rm_robot packages:
- dual_rm_driver (C++ rm_driver node providing low-level servo interface)
- dual_rm_control (trajectory generation via cubicSpline)
- dual_rm_moveit_config + demos (MoveIt planners & demo nodes)
- dual_rm_description + dual_rm_gazebo (URDF/XACRO description and Gazebo plugins)
- rm_ros2_interfaces (custom message definitions for arm commands & states)
f. Servo driver subsystem
- ros2_servo_driver (C++ servo_driver_node, example clients)
g. Orchestration & demo subsystem
- ros2_total_demo (total_demo_node, scripts that tie sensors, AGV, arms together)
h. External tools
- RViz (visualization)
- Gazebo (simulation)
- MoveIt2 (motion planning)

##### Relationships and interactions
- python_controller subscribes user inputs and publishes control commands (e.g., /cmd_vel or arm-specific topics).
- AGV & arm drivers subscribe command topics and send actuator commands over serial/ethernet to hardware or simulated interfaces.
- dual_rm_driver exposes ROS 2 topics/services for low-level control; dual_rm_control subscribes state topics to compute smooth trajectories.
- MoveIt2 nodes subscribe the robot’s joint state, offer planning services/actions, and send joint trajectories to dual_rm_control or dual_rm_driver.
- ros2_total_demo node aggregates sensor feeds, computes object poses, then dispatches tasks to AGV controller and dual-arm planner.
- Gazebo plugin node (mimic_joint_plugin) subscribes joint commands for simulated robot.
- RViz connects to topics for visualization.

##### Architectural patterns and principles
- Pub/Sub messaging for decoupled nodes.
- Service/Action interfaces for planning and pre-programmed tasks.
- Layered driver → control → planning → orchestration.
- Modular ROS 2 packages; clear separation of description (URDF), driver, control, planning, and demos.
- Use of ROS 2 launch files to compose systems.

a. Sketch the ROS 2 Core in the center (a cloud symbol).
b. Around it place:
– AGV subsystem (bottom-left): ros2_agv_robot nodes → subscribe cmd_vel → drive AGV.
– Dual-arm subsystem (bottom-right): driver, control, description, moveit config, gazebo plugin.
– Orchestration & demo (center-right): ros2_total_demo node.
e. Launch files used to bring up each subsystem (e.g., start_65_agv.launch.py, demo.launch.py).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core
    Core(["ROS 2 Core\n(DDS)"]):::core

    %% Sensor Subsystem
    subgraph "Sensor Subsystem"
        RS_node["realsense2_camera_node"]:::sensor
        T_img((" /camera/color/image_raw ")):::topic
        T_pc((" /camera/depth/points ")):::topic
        T_imu((" /imu/data ")):::topic
    end

    %% Controller Subsystem
    subgraph "Controller Subsystem"
        kb["keyboard_base_controller"]:::controller
        js["joystick_base_controller"]:::controller
    end

    %% AGV & Mobility Subsystem
    subgraph "AGV & Mobility Subsystem"
        ep["exec_pre_task"]:::driver
        et["exectask"]:::driver
        gm["goto_mark"]:::driver
        mon["monitor"]:::driver
        sc["stepctrl"]:::driver
    end

    %% Servo Driver Subsystem
    subgraph "Servo Driver Subsystem"
        sd["servo_driver_node"]:::driver
        sevecli["servo_example_clients"]:::driver
    end

    %% Dual-Arm Manipulator Subsystem
    subgraph "Dual-Arm Subsystem"
        subgraph Driver
            dr["rm_driver node"]:::driver
        end
        subgraph Control
            ctrl["dual_rm_control"]:::driver
        end
        subgraph Description
            desc["dual_rm_description"]:::driver
            simplug["mimic_joint_plugin"]:::sim
        end
        subgraph Planning
            moveit["MoveIt2 planners/actions"]:::planning
        end
        subgraph Interfaces
            iface["rm_ros_interfaces msgs"]:::driver
        end
    end

    %% Orchestration & Demo
    subgraph "Orchestration & Demo"
        demo["total_demo_node"]:::controller
    end

    %% External Tools
    RViz["RViz"]:::sim
    Gazebo["Gazebo"]:::sim
    MoveIt2["MoveIt2"]:::planning

    %% Connections
    Core --- RS_node
    RS_node -->|"/camera/color/image_raw"| T_img
    RS_node -->|"/camera/depth/points"| T_pc
    RS_node -->|"/imu/data"| T_imu
    T_img -->|"feeds"| demo
    T_pc -->|"feeds"| demo
    T_imu -->|"feeds"| demo
    T_img -->|"visualization"| RViz
    demo -->|"/cmd_vel"| ep
    kb -->|"/cmd_vel"| ep
    js -->|"/cmd_vel"| ep
    ep -->|"drive command"| Core
    et -->|"task service"| Core
    gm -->|"goto_mark service"| Core
    mon -->|"/status"| demo
    sc -->|"/step_control"| demo
    sd -->|"servo control topics"| Core
    sevecli -->|"example calls"| sd
    dr -->|"/rm_driver/commands"| ctrl
    ctrl -->|"/joint_states"| moveit
    moveit -->|"/plan_trajectory (action)"| ctrl
    moveit -->|"/execute_trajectory"| dr
    iface -->|"custom msgs"| dr
    demo -->|"dispatch tasks"| et
    demo -->|"dispatch tasks"| ctrl
    Gazebo -->|"/joint_commands"| simplug
    simplug -->|"simulated joints"| Core
    RViz -->|"/joint_states"| demo
    MoveIt2 -->|"planning"| moveit

    %% Click Events
    click RS_node "https://github.com/ucla-robot-intelligence-lab/realman-env/tree/main/src/rmc_aida_l_ros2-develop/ros2_realsense2/realsense2_camera"
    click kb "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/python_controller/python_controller/keyboard_base_controller.py"
    click js "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/python_controller/python_controller/joystick_base_controller.py"
    click ep "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_agv_robot/src/exec_pre_task.cpp"
    click et "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_agv_robot/src/exectask.cpp"
    click gm "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_agv_robot/src/goto_mark.cpp"
    click mon "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_agv_robot/src/monitor.cpp"
    click sc "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_agv_robot/src/stepctrl.cpp"
    click dr "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_rm_robot/dual_rm_driver/rm_driver/src/rm_driver.cpp"
    click ctrl "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_rm_robot/dual_rm_control/src/rm_control.cpp"
    click desc "https://github.com/ucla-robot-intelligence-lab/realman-env/tree/main/src/rmc_aida_l_ros2-develop/ros2_rm_robot/dual_rm_description"
    click simplug "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_rm_robot/dual_rm_gazebo/src/mimic_joint_plugin.cpp"
    click moveit "https://github.com/ucla-robot-intelligence-lab/realman-env/tree/main/src/rmc_aida_l_ros2-develop/ros2_rm_robot/dual_rm_moveit_config"
    click iface "https://github.com/ucla-robot-intelligence-lab/realman-env/tree/main/src/rmc_aida_l_ros2-develop/ros2_rm_robot/dual_rm_ros2_interfaces/rm_ros_interfaces/msg"
    click sd "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_servo_driver/servo_driver/src/servo_driver_node.cpp"
    click sevecli "https://github.com/ucla-robot-intelligence-lab/realman-env/tree/main/src/rmc_aida_l_ros2-develop/ros2_servo_driver/servo_example/src"
    click demo "https://github.com/ucla-robot-intelligence-lab/realman-env/blob/main/src/rmc_aida_l_ros2-develop/ros2_total_demo/src/total_demo_node.cpp"

    %% Styles
    classDef sensor fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef controller fill:#90EE90,stroke:#333,stroke-width:1px
    classDef driver fill:#FFA500,stroke:#333,stroke-width:1px
    classDef planning fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef sim fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef core fill:#FFFFFF,stroke:#333,stroke-width:1px
    classDef topic fill:#EEEEEE,stroke:#666,stroke-dasharray: 5 5,stroke-width:1px
```
