# engineai-robotics/engineai_ros2_workspace architecture

> Architecture diagram of the GitHub repository engineai-robotics/engineai_ros2_workspace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/engineai-robotics/engineai_ros2_workspace
- Repository: https://github.com/engineai-robotics/engineai_ros2_workspace

## Overview

1. **Repository purpose**
   - This is a ROS2 workspace for EngineAI robots.
   - Its architecture is organized around a shared ROS2 interface contract, example control apps, and a MuJoCo-based simulator that can exercise the same interface as the real robot.

2. **Top-level runtime split: host PC vs robot onboard computer**
   - The README explicitly separates **host-side development/simulation** from **robot onboard deployment**.
   - Host PC runs the simulator and example nodes; the onboard Orin board can run the same workspace after syncing source.
   - ROS networking is configured for the robot’s domain and LAN, so the system is designed as a distributed ROS2 network rather than a single process app.

3. **Shared interface layer: `src/interface_protocol`**
   - This package is the main contract boundary for the whole workspace.
   - It defines the ROS2 messages and service used across examples and simulation: joint, motor, motion, body velocity, IMU, power, heartbeat, LED, TTS, gamepad, alerts, and override/control request types.
   - A single service, `EnableMotor`, indicates the interface includes explicit actuator power enable/disable control.
   - The package also contains protocol documentation and a layout descriptor, making it the canonical schema layer for both robot and simulator integration.

4. **Robot/application layer: `src/interface_example`**
   - This package contains the example control applications, mostly meant to run on the host while talking to the robot over ROS2.
   - It includes both **Python scripts** and **C++ nodes**, so the architecture supports lightweight demos and compiled control components.
   - Examples cover multiple control modes: body velocity, joint bridge, LED control, joint motion planning, upper-body override, and joint tests.

5. **Example control flow**
   - Example scripts publish control commands and consume robot state using the shared protocol messages.
   - The likely pattern is:
     - read robot state topics,
     - compute a command in application logic,
     - publish joint/body/motion/LED commands,
     - optionally request motion state changes or motor enablement.
   - This keeps application logic separate from transport and protocol definitions.

6. **RL walking deployment path**
   - The `rl_basic` example is a dedicated subsystem for deploying a learned walking policy.
   - It loads a pretrained **MNN** model file plus YAML parameters from `config/pm01/rl_basic/...`.
   - Supporting math and utility code in `src/interface_example/src/math` and `src/interface_example/src/components` handles model inference, vector concatenation, rotation math, and message handling.
   - This part of the repo is the bridge between high-level policy inference and low-level joint command publishing.

7. **Configuration and robot-specific assets in examples**
   - The `config/pm01` tree contains robot-specific YAML files for motor settings, joint tests, motion plans, and RL parameters.
   - This shows the examples are parameterized per robot model rather than hardcoded.
   - The launch file `rl_basic_example.launch.py` is the entry point for the RL demo within the ROS2 launch system.

8. **Simulation subsystem: `src/simulation/mujoco`**
   - The simulator is a separate package with its own build and launch entry points.
   - It wraps **MuJoCo** and provides a ROS interface so simulated robot behavior can be driven through the same message contracts as the physical robot.
   - The simulator package has three key roles:
     - load robot/environment assets,
     - run the physics simulation,
     - translate between ROS2 topics/services and MuJoCo internal state.

9. **Simulation internals and boundaries**
   - `ros_interface.cc` is the adapter boundary between ROS2 and the simulator.
   - `sim_manager.cc` is the orchestration layer for simulation state and timing.
   - `config_loader.cc` loads robot/simulation configuration.
   - The `simulate/` subproject contains the lower-level MuJoCo application/runtime, with platform-specific UI support and GLFW adapters.
   - This cleanly separates the ROS-facing integration layer from the actual simulation engine.

10. **Simulation assets and model definition**
   - The simulator ships with robot assets for `pm_v2`: URDFs, MuJoCo XML fragments, STL meshes, and environment models such as ground and chair scenes.
   - This indicates the simulator is built from authored robot geometry and physics descriptions, not generated at runtime.
   - The asset/config split lets the same simulator code support multiple scenes or robot variants by swapping configuration and XML assets.

11. **Third-party dependency handling: `src/third_party`**
   - External binary/source bundles are managed separately from the main code.
   - The presence of install/make scripts and archived third-party payloads suggests these dependencies are fetched or unpacked locally for deterministic builds.
   - This package is a build-time dependency boundary, not part of the application protocol or runtime control logic.

12. **Build and orchestration scripts**
   - Repository-level scripts coordinate formatting, dependency install, node builds, and source sync.
   - The workspace is built as ROS2 packages, with separate build targets for the simulator and example nodes.
   - Launch files are used as the runtime entry points, while shell scripts handle environment setup and source distribution to the robot board.

13. **End-to-end data flow**
   - In all modes, the architecture centers on ROS2 message exchange:
     - **state flows** from robot/simulator to examples,
     - **command flows** from examples to robot/simulator,
     - **policy inference** sits inside the RL example before command publication.
   - The same protocol layer supports both physical hardware and simulation, which is the key architectural goal of the repo.

14. **What to show in an architecture diagram**
   - Draw four major boxes: **interface_protocol**, **interface_example**, **simulation/mujoco**, and **third_party/build support**.
   - Show `interface_protocol` as the shared schema boundary feeding both the example apps and the simulator adapter.
   - Show separate deployment contexts for **host PC** and **robot onboard computer**, connected by ROS2 networking.
   - Place the RL policy file and MuJoCo assets as data inputs to the application and simulation subsystems, respectively.

Main entry points: [`src/simulation/mujoco`](https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/simulation/mujoco) (MuJoCo sim), [`src/interface_protocol`](https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_protocol) (Interface API), [`src/interface_example`](https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_example) (Examples), [`src/interface_example/src/rl_basic_example.cc`](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_example/src/rl_basic_example.cc) (RL walking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared contract"]
  node_iface_protocol["Interface API<br/>ros2 contract"]
  node_iface_msgs["ROS msgs<br/>message schema"]
  node_enable_motor["Enable motor<br/>[EnableMotor.srv]"]
  node_iface_docs["Protocol docs<br/>spec docs<br/>[new_msg_dsc.md]"]
end

subgraph group_host["Host PC"]
  node_host_pc(("Host PC<br/>runtime context"))
  node_examples_pkg["Examples<br/>control apps"]
  node_example_scripts["Demo scripts<br/>python/cpp apps"]
  node_rl_basic{{"RL walking<br/>policy runner"}}
  node_rl_model["MNN policy<br/>model asset"]
  node_rl_params["RL params<br/>yaml config"]
  node_example_support["Example core<br/>support library<br/>[message_handler.cc]"]
end

subgraph group_robot["Robot onboard"]
  node_robot_onboard(("Robot board<br/>runtime context"))
end

subgraph group_sim["Simulation"]
  node_mujoco_pkg["MuJoCo sim<br/>simulator package"]
  node_ros_adapter["ROS adapter<br/>bridge layer<br/>[ros_interface.cc]"]
  node_sim_manager["Sim manager<br/>orchestrator<br/>[sim_manager.cc]"]
  node_config_loader["Config loader<br/>[config_loader.cc]"]
  node_sim_engine["Sim runtime<br/>physics engine<br/>[simulate.cc]"]
  node_sim_assets["Robot assets<br/>asset bundle<br/>[serial_pm_v2.xml]"]
end

subgraph group_support["Build support"]
  node_third_party[("Third-party<br/>dependency bundle")]
  node_build_scripts["Build scripts<br/>workspace scripts<br/>[build_nodes.sh]"]
end

node_host_pc -->|"runs"| node_examples_pkg
node_host_pc -->|"runs"| node_mujoco_pkg
node_robot_onboard -->|"speaks"| node_iface_protocol
node_examples_pkg -->|"imports"| node_iface_protocol
node_mujoco_pkg -->|"adapts"| node_iface_protocol
node_iface_protocol -->|"defines"| node_iface_msgs
node_iface_protocol -->|"defines"| node_enable_motor
node_iface_protocol -->|"documents"| node_iface_docs
node_examples_pkg -->|"contains"| node_example_scripts
node_examples_pkg -->|"contains"| node_rl_basic
node_rl_basic -->|"loads"| node_rl_model
node_rl_basic -->|"configures"| node_rl_params
node_rl_basic -->|"uses"| node_example_support
node_example_scripts -->|"publishes"| node_iface_protocol
node_example_support -->|"handles"| node_iface_protocol
node_mujoco_pkg -->|"contains"| node_ros_adapter
node_mujoco_pkg -->|"contains"| node_sim_manager
node_mujoco_pkg -->|"contains"| node_config_loader
node_mujoco_pkg -->|"contains"| node_sim_engine
node_mujoco_pkg -->|"loads"| node_sim_assets
node_ros_adapter -->|"bridges"| node_iface_protocol
node_sim_manager -->|"orchestrates"| node_sim_engine
node_config_loader -->|"loads"| node_sim_assets
node_third_party -.->|"supports build"| node_mujoco_pkg
node_build_scripts -.->|"builds"| node_examples_pkg
node_build_scripts -.->|"builds"| node_mujoco_pkg
node_build_scripts -.->|"fetches"| node_third_party
node_host_pc -.->|"syncs to"| node_robot_onboard

click node_iface_protocol "https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_protocol"
click node_iface_msgs "https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_protocol/msg"
click node_enable_motor "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_protocol/srv/EnableMotor.srv"
click node_iface_docs "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_protocol/new_msg_dsc.md"
click node_examples_pkg "https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_example"
click node_example_scripts "https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_example/scripts"
click node_rl_basic "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_example/src/rl_basic_example.cc"
click node_rl_model "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_example/config/pm01/rl_basic/basic/policies/pm01_v2_rough_ppo_42obs.mnn"
click node_rl_params "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_example/config/pm01/rl_basic/basic/rl_basic_param.yaml"
click node_example_support "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_example/src/components/message_handler.cc"
click node_mujoco_pkg "https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/simulation/mujoco"
click node_ros_adapter "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/src/ros_interface.cc"
click node_sim_manager "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/src/sim_manager.cc"
click node_config_loader "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/src/config_loader.cc"
click node_sim_engine "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/simulate/simulate.cc"
click node_sim_assets "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/assets/resource/robot/pm_v2/xml/serial_pm_v2.xml"
click node_third_party "https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/third_party"
click node_build_scripts "https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/scripts/build_nodes.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_iface_protocol,node_iface_msgs,node_enable_motor,node_iface_docs toneBlue
class node_host_pc,node_examples_pkg,node_example_scripts,node_rl_basic,node_rl_model,node_rl_params,node_example_support toneAmber
class node_robot_onboard toneMint
class node_mujoco_pkg,node_ros_adapter,node_sim_manager,node_config_loader,node_sim_engine,node_sim_assets toneRose
class node_third_party,node_build_scripts toneIndigo
```

## Components

### Shared contract

ROS2 interface definitions used by both example apps and simulator

- [Interface API](https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_protocol): ros2 contract · Shared messages and service boundary for robot, examples, and simulator · `src/interface_protocol`
- [ROS msgs](https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_protocol/msg): message schema · Joint, motion, motor, IMU, power, LED, TTS, gamepad, alert, and override messages · `src/interface_protocol/msg`
- [Enable motor](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_protocol/srv/EnableMotor.srv): service · Actuator power enable/disable service · `src/interface_protocol/srv/EnableMotor.srv`
- [Protocol docs](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_protocol/new_msg_dsc.md): spec docs · Message layout and protocol documentation · `src/interface_protocol/new_msg_dsc.md`

### Host PC

Development and simulation runtime

- **Host PC**: runtime context · Runs example nodes and the simulator during development
- [Examples](https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_example): control apps · Host-side example control nodes and scripts · `src/interface_example`
- [Demo scripts](https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/interface_example/scripts): python/cpp apps · Body velocity, joint bridge, LED, motion plan, override, and joint test examples · `src/interface_example/scripts`
- [RL walking](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_example/src/rl_basic_example.cc): policy runner · Loads a trained policy and publishes joint commands for walking · `src/interface_example/src/rl_basic_example.cc`
- [MNN policy](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_example/config/pm01/rl_basic/basic/policies/pm01_v2_rough_ppo_42obs.mnn): model asset · Pretrained walking policy and parameters · `src/interface_example/config/pm01/rl_basic/basic/policies/pm01_v2_rough_ppo_42obs.mnn`
- [RL params](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_example/config/pm01/rl_basic/basic/rl_basic_param.yaml): yaml config · Robot-specific parameters for the RL demo · `src/interface_example/config/pm01/rl_basic/basic/rl_basic_param.yaml`
- [Example core](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/interface_example/src/components/message_handler.cc): support library · Message handling, math, model inference, and parameter utilities · `src/interface_example/src/components/message_handler.cc`

### Robot onboard

Onboard deployment runtime

- **Robot board**: runtime context · Onboard ROS2 runtime on the robot computer

### Simulation

MuJoCo-based simulator subsystem

- [MuJoCo sim](https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/simulation/mujoco): simulator package · ROS2 wrapper around the MuJoCo-based robot simulator · `src/simulation/mujoco`
- [ROS adapter](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/src/ros_interface.cc): bridge layer · Translates ROS2 topics and services to simulator state · `src/simulation/mujoco/src/ros_interface.cc`
- [Sim manager](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/src/sim_manager.cc): orchestrator · Controls simulation timing and state coordination · `src/simulation/mujoco/src/sim_manager.cc`
- [Config loader](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/src/config_loader.cc): loader · Loads robot and simulation configuration · `src/simulation/mujoco/src/config_loader.cc`
- [Sim runtime](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/simulate/simulate.cc): physics engine · Lower-level MuJoCo application and UI/platform adapters · `src/simulation/mujoco/simulate/simulate.cc`
- [Robot assets](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/src/simulation/mujoco/assets/resource/robot/pm_v2/xml/serial_pm_v2.xml): asset bundle · URDF, XML, meshes, and environment scenes for pm_v2 · `src/simulation/mujoco/assets/resource/robot/pm_v2/xml/serial_pm_v2.xml`

### Build support

Third-party payloads and workspace scripts

- [Third-party](https://github.com/engineai-robotics/engineai_ros2_workspace/tree/community/src/third_party): dependency bundle · External source and binary payloads used for deterministic builds · `src/third_party`
- [Build scripts](https://github.com/engineai-robotics/engineai_ros2_workspace/blob/community/scripts/build_nodes.sh): workspace scripts · Formatting, install, build, and source sync orchestration · `scripts/build_nodes.sh`

## Connections

- Host PC → Examples: runs · Host runtime executes example control nodes
- Host PC → MuJoCo sim: runs · Host runtime can launch the simulator
- Robot board → Interface API: speaks · Robot-side nodes use the shared ROS2 contract
- Examples → Interface API: imports · Examples build against shared messages and services
- MuJoCo sim → Interface API: adapts · Simulator exposes the same ROS2 interface as hardware
- Interface API → ROS msgs: defines · Message schema package is the core contract surface
- Interface API → Enable motor: defines · Service schema for actuator enable control
- Interface API → Protocol docs: documents · Protocol package includes schema docs and layout metadata
- Examples → Demo scripts: contains · Demo applications live as Python and C++ entry points
- Examples → RL walking: contains · RL walking demo is a major example path
- RL walking → MNN policy: loads · Policy runner consumes the pretrained MNN model
- RL walking → RL params: configures · Robot-specific YAML parameters tune the policy runtime
- RL walking → Example core: uses · Policy runner relies on message and math utilities
- Demo scripts → Interface API: publishes · Control demos send commands and read state via shared topics
- Example core → Interface API: handles · Utility layer marshals protocol messages
- MuJoCo sim → ROS adapter: contains · ROS-facing boundary inside the simulator package
- MuJoCo sim → Sim manager: contains · Simulation orchestration layer
- MuJoCo sim → Config loader: contains · Configuration loading boundary
- MuJoCo sim → Sim runtime: contains · Lower-level MuJoCo runtime subproject
- MuJoCo sim → Robot assets: loads · Physics and scene assets drive the simulator
- ROS adapter → Interface API: bridges · Adapter maps ROS2 commands and state to simulator internals
- Sim manager → Sim runtime: orchestrates · Manager coordinates the underlying physics runtime
- Config loader → Robot assets: loads · Configuration selects robot and environment assets
- Third-party → MuJoCo sim: supports build · External libraries support simulator compilation and runtime
- Build scripts → Examples: builds · Scripts install and build the example workspace
- Build scripts → MuJoCo sim: builds · Scripts also build the simulator package
- Build scripts → Third-party: fetches · Scripts install or unpack third-party dependencies
- Host PC → Robot board: syncs to · Source is mirrored from host development to the robot computer
