How engineai-robotics/engineai_humanoid works
Project Type and Purpose
• This is a robotics control software for bipedal humanoid robots combining model-based and learning-based (RL) locomotion algorithms.
• Core components: real-time control loop (EngineAI_Controller), state estimation, dynamics simulation, hardware interface, RL policy deployment.
• Uses C++, CMake, LCM for messaging, ONNX Runtime for RL policies, SOEM for EtherCAT, various third-party optimization and sensor libraries.
High-Level File-Structure Analysis
• EngineAI_Controller/
• CMakeLists and main EngineAI_Controller.cpp: entry point and CMake build.
• common/: reusable libraries (Collision, Controllers, Dynamics, Math, Utilities).
• config/: YAML defaults for simulators and robot parameters.
• lcm-types/: LCM message definitions and generated language bindings.
• robot/: hardware and simulation bridges (HardwareBridge, SimulationBridge, RobotRunner).
• scripts/: shell and Python helper scripts for deployment, LCM logs, network config.
• third-party/: embedded dependencies (OSQP, qpOASES, SOEM, vectornav, yaml-cpp, etc.).
• user/: user-provided algorithms (FSM states, RL controller, policy ONNX files, user parameters).
Relevant README Insights
• Describes modular structure: “common”, “config”, “lcm-types”, “robot”, “scripts”, “third-party”, “user”.
• Explains deployment flow: compile on PC → generate binaries/libraries → deploy to mainboard NaZha.
• Emphasizes RT control, RL policy loading, network & LCM configuration.
a. Main Components
1. Sensor Interfaces
• IMU, Gamepad, SpineBoard, other boards → data fed via LCM messages and/or direct bridge.
2. EngineAI_Controller Process (C++ binary)
• State Estimator (PositionVelocityEstimator, OrientationEstimator, ContactEstimator)
• FSM Manager (FSM_States)
• Controller Modules
· Model-based (DynamicsSimulator, FloatingBaseModel, close_chain_mapping)
· Learning-based (ONNXRuntime policy via LearningBasedController)
• Contact & Collision Handling
• Utilities & Filters
3. Hardware Bridge (HardwareBridge / SOEM)
• EtherCAT communication to motor controllers
4. Simulation Bridge
• Sim2Sim environment interface for testing (ImuSimulator, sim utilities)
5. LCM Bus
• Pub/Sub for logging, telemetry, control_parameter_request, state_estimator_lcmt, leg_control_command/data
6. Configuration & Onnx Policy
• YAML files for robot/simulator parameters
• ONNX model loaded at runtime
7. Scripts & Deployment Tools
• run_biped.sh, network_config.py, lcm-log2smat, autostart, etc.
b. Relationships and Data Flows
• Sensors → (LCM) → State Estimator → FSM → Controller (model RL hybrid) → Actuator Model → HardwareBridge or SimulationBridge → Robot / Sim Environment → back to Sensors
• User scripts invoke binaries, configure network & LCM, deploy ONNX/YAML → Environment
• Third-party libs used by common modules and hardware/simulation bridges
c. Architectural Patterns & Principles
• Modular library layering: common (core algorithms) vs. user (extensions) vs. third-party
• Plugin-style controllers: ability to swap model-based and RL controllers via interface
• Clear separation: state estimation, decision (FSM), control, hardware I/O
• Pub/Sub message bus (LCM) decouples components and supports logging/monitoring
d. Key Technologies & Frameworks
• C++17, CMake, LCM (1.5.0), ONNX Runtime (v1.19.0), SOEM (EtherCAT), yaml-cpp, Eigen, IPOPT/CASADI (optional)
Essential Details to Capture
• Dependency on third-party libs embedded under third-party/
• Dual deployment targets (SimulationBridge vs. HardwareBridge)
• LCM message flows for telemetry and commands
• Interface between FSM and controller modules
• Configuration and policy management via YAML and ONNX