How engineai-robotics/engineai_ros2_workspace works
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: mujoco MuJoCo sim · interface_protocol Interface API · interface_example Examples · rl_basic_example.cc RL walking
Components 20
Shared contract
ROS2 interface definitions used by both example apps and simulator
- Interface API · Shared messages and service boundary for robot, examples, and simulator
src/interface_protocol - ROS msgs · Joint, motion, motor, IMU, power, LED, TTS, gamepad, alert, and override messages
src/interface_protocol/msg - Enable motor · Actuator power enable/disable service
src/interface_protocol/srv/EnableMotor.srv - Protocol docs · Message layout and protocol documentation
src/interface_protocol/new_msg_dsc.md
Host PC
Development and simulation runtime
- Host PC · Runs example nodes and the simulator during development
- Examples · Host-side example control nodes and scripts
src/interface_example - Demo scripts · Body velocity, joint bridge, LED, motion plan, override, and joint test examples
src/interface_example/scripts - RL walking · Loads a trained policy and publishes joint commands for walking
src/interface_example/src/rl_basic_example.cc - MNN policy · Pretrained walking policy and parameters
src/interface_example/config/pm01/rl_basic/basic/policies/pm01_v2_rough_ppo_42obs.mnn - RL params · Robot-specific parameters for the RL demo
src/interface_example/config/pm01/rl_basic/basic/rl_basic_param.yaml - Example core · Message handling, math, model inference, and parameter utilities
src/interface_example/src/components/message_handler.cc
Robot onboard
Onboard deployment runtime
- Robot board · Onboard ROS2 runtime on the robot computer
Simulation
MuJoCo-based simulator subsystem
- MuJoCo sim · ROS2 wrapper around the MuJoCo-based robot simulator
src/simulation/mujoco - ROS adapter · Translates ROS2 topics and services to simulator state
src/simulation/mujoco/src/ros_interface.cc - Sim manager · Controls simulation timing and state coordination
src/simulation/mujoco/src/sim_manager.cc - Config loader · Loads robot and simulation configuration
src/simulation/mujoco/src/config_loader.cc - Sim runtime · Lower-level MuJoCo application and UI/platform adapters
src/simulation/mujoco/simulate/simulate.cc - Robot assets · 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 · External source and binary payloads used for deterministic builds
src/third_party - Build scripts · Formatting, install, build, and source sync orchestration
scripts/build_nodes.sh
Connections 28
- 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