# engineai-robotics/engineai_humanoid architecture

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

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

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Sensors
    subgraph "Sensors" 
        direction TB
        IMU["IMU"]:::external
        Gamepad["Gamepad"]:::external
        SpineBoard["SpineBoard"]:::external
        OtherBoards["Other Boards"]:::external
    end

    %% Messaging Layer
    LCMBus["LCM Bus"]:::lcm

    %% Core Engine Process
    subgraph "EngineAI_Controller Process" 
        direction TB
        EACP["EngineAI_Controller"]:::core
        subgraph "State Estimation"
            direction TB
            PVE["PositionVelocityEstimator"]:::core
            OE["OrientationEstimator"]:::core
            CE["ContactEstimator"]:::core
        end
        FSM["FSM Manager"]:::core
        subgraph "Controller Modules"
            direction TB
            subgraph "Model-Based Controller"
                direction TB
                DS["DynamicsSimulator"]:::core
                FBM["FloatingBaseModel"]:::core
                AM["ActuatorModel"]:::core
            end
            subgraph "Learning-Based Controller"
                direction TB
                LBC["LearningBasedController"]:::core
                ONNX["ONNX Policy"]:::config
                RLYAML["RL Config YAML"]:::config
            end
        end
        RR["RobotRunner"]:::core
    end

    %% Bridges
    subgraph "Bridges"
        direction TB
        HB["HardwareBridge"]:::core
        SB["SimulationBridge"]:::core
    end

    %% Environments
    subgraph "Environments"
        direction TB
        RobotEnv["Robot / Hardware"]:::external
        SimEnv["Simulation Environment"]:::external
    end

    %% Configuration & Storage
    Config["YAML Config Files"]:::config
    LCMTypes["LCM Definitions"]:::config
    CommonUtils["Common Utilities & Filters"]:::core
    MathColl["Math & Collision Lib"]:::core
    ThirdParty["Third-Party Libs"]:::core
    Scripts["Deployment & Helper Scripts"]:::external

    %% Data Flows
    IMU -->|Publishes| LCMBus
    Gamepad -->|Publishes| LCMBus
    SpineBoard -->|Publishes| LCMBus
    OtherBoards -->|Publishes| LCMBus

    LCMBus -->|Subscribes| PVE
    LCMBus -->|Subscribes| OE
    LCMBus -->|Subscribes| CE

    PVE --> FSM
    OE --> FSM
    CE --> FSM

    FSM --> DS
    FSM --> LBC

    DS --> RR
    FBM --> RR
    AM --> RR
    LBC --> RR

    RR --> HB
    RR --> SB

    HB -->|EtherCAT| RobotEnv
    SB -->|Sim2Sim| SimEnv

    Scripts -->|Invokes| EACP
    Scripts -->|Uses| Config
    Scripts -->|Uses| LCMBus

    Config -->|Loads| EACP
    LCMTypes -->|Provides| EACP
    CommonUtils -->|Linked| EACP
    MathColl -->|Linked| EACP
    ThirdParty -->|Embedded| EACP

    %% Click Events
    click EACP "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/EngineAI_Controller.cpp"
    click CMake "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/CMakeLists.txt"
    click cmakeDir "https://github.com/engineai-robotics/engineai_humanoid/tree/master/EngineAI_Controller/cmake/"
    click PVE "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/common/include/Controllers/PositionVelocityEstimator.h"
    click OE "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/common/include/Controllers/OrientationEstimator.h"
    click CE "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/common/include/Controllers/ContactEstimator.h"
    click FSM "https://github.com/engineai-robotics/engineai_humanoid/tree/master/EngineAI_Controller/user/EngineAI_Humanoid_Controller/FSM_States/"
    click DS "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/common/include/Dynamics/DynamicsSimulator.h"
    click FBM "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/common/include/Dynamics/FloatingBaseModel.h"
    click AM "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/common/include/Dynamics/ActuatorModel.h"
    click LBC "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/user/EngineAI_Humanoid_Controller/Controllers/RL_Controller/include/rl_controllers/LearningBasedController.h"
    click LBCcpp "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/user/EngineAI_Humanoid_Controller/Controllers/RL_Controller/src/LearningBasedController.cpp"
    click ONNX "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/user/EngineAI_Humanoid_Controller/Controllers/RL_Controller/policy/zqsa01/zqsa01_policy.onnx"
    click RLYAML "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/user/EngineAI_Humanoid_Controller/Controllers/RL_Controller/config/zqsa01_rl.yaml"
    click HB "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/robot/include/HardwareBridge.h"
    click HBcpp "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/robot/src/HardwareBridge.cpp"
    click SB "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/robot/include/SimulationBridge.h"
    click SBcpp "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/robot/src/SimulationBridge.cpp"
    click RR "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/robot/include/RobotRunner.h"
    click RRcpp "https://github.com/engineai-robotics/engineai_humanoid/blob/master/EngineAI_Controller/robot/src/RobotRunner.cpp"
    click LCMTypes "https://github.com/engineai-robotics/engineai_humanoid/tree/master/EngineAI_Controller/lcm-types/"
    click Config "https://github.com/engineai-robotics/engineai_humanoid/tree/master/EngineAI_Controller/config/"
    click CommonUtils "https://github.com/engineai-robotics/engineai_humanoid/tree/master/EngineAI_Controller/common/include/Utilities/"
    click MathColl "https://github.com/engineai-robotics/engineai_humanoid/tree/master/EngineAI_Controller/common/include/Math/"
    click MathColl2 "https://github.com/engineai-robotics/engineai_humanoid/tree/master/EngineAI_Controller/common/include/Collision/"
    click ThirdParty "https://github.com/engineai-robotics/engineai_humanoid/tree/master/EngineAI_Controller/third-party/"
    click Scripts "https://github.com/engineai-robotics/engineai_humanoid/tree/master/EngineAI_Controller/scripts/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef lcm fill:#90EE90,stroke:#000,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px
```
