zeroth-robotics/zeroth-bot

<explanation>

1. Identify the project type and purpose

- This is an open‑source robotics platform (“Zeroth Bot”), combining hardware, firmware, simulation, ML models, and user‑level experiment scripts into one monorepo.

- Purpose: Provide an end‑to‑end humanoid robot stack—3D‑printed hardware with sensors/actuators, embedded firmware, host‑side SDK, simulation (URDF/meshes), ML inference, and high‑level Python experiments (teleop, plotting, training).

2. Analyze the file structure

- Top‑level directories:

• buildroot – embedded Linux build for on‑board computer

• experiments – Python scripts for running sim and real‑robot experiments (IMU logging, teleop, model evaluation)

• kos-zbot – Rust code for the robot SDK & firmware drivers, plus tonic (gRPC) support

• models – ML model artifacts and conversion scripts

• public – static assets for site/documentation

• runtime/firmware – older or auxiliary firmware utilities

- Key config and CI: .gitlab‑ci.yml, Dockerfile for toolchain, Cargo.toml

3. Readme insights

- Confirms end‑to‑end sim2real robotics platform, with community SDK, docs, and hardware files (URDF + STL meshes).

4. Main components to show in the diagram

a. Hardware Layer

- Actuators (Feetech servos, STS3215, zero‑position drivers)

- Sensors (IMU BMI088/BNO055, LED matrix, TPU accelerator)

- On‑board compute (embedded Linux via buildroot or microcontroller)

b. Firmware & Drivers (Rust & C wrappers)

- kos-zbot/src/firmware modules (cvitek, feetech_servo, efuse, servo_driver)

- C wrappers under firmware/cviwrapper, efuse, feetech in kos-zbot/firmware

c. Middleware & Communication

- gRPC interface (tonic folder) between host SDK and on‑board agent

- Serial/USB links for real‑robot communication

d. Host‑side SDK & Tools

- Rust library (kos-zbot/src/lib.rs) and binaries (bin/*) for calibration, scanning, etc.

- Python experiment scripts (experiments/run.py, imu.py, model.py, robot.py, teleop/main.py)

- URDF, STL meshes for sim in experiments/teleop/urdf

e. Simulation & ML

- URDF‑based sim environment (mesh assets + ROS/Gazebo or custom sim)

- ML models (models/standing.pt, TPU‑MLIR pipeline)

f. CI/CD and Toolchain

- Docker toolchain (toolchain-docker-img/Dockerfile)

- GitLab CI for automated build/test

5. Relationships and interactions

- Host SDK ↔ on‑board firmware: via gRPC or serial commands

- Python experiments ↔ Host SDK: through SDK’s CLI or Python bindings (via cffi or subprocess)

- Simulation uses URDF and meshes to emulate hardware, feeding back simulated sensor data to experiments

- ML inference runs on embedded TPU or on host (depending on configuration)

- CI/CD builds Docker images → cross‑compile firmware & Rust SDK → deploy artifacts

6. Architectural patterns and principles

- Layered architecture: hardware → firmware → middleware → SDK → user‑level applications

- Clear separation of concerns:

• Low‑level drivers in Rust/C

• Comm layer (gRPC/serial)

• High‑level logic in Python experiments

- Extensibility: plugin‑style servo drivers, model conversion scripts, support for multiple IMUs/servos

- Sim2Real: same SDK & scripts work in both sim and real hardware

7. Tailoring the diagram

- Emphasize front‑end (Python/experiments) vs. back‑end (Rust SDK & firmware) for a robotics full‑stack app

- Show sim environment as a parallel path to real hardware

- Highlight the ML inference path (model → TPU → control loop)

8. Diagram guidelines for the principal engineer

- Components as boxes, arranged in layers from bottom (hardware) to top (experiments)

- Label each box clearly: “Feetech Servo Driver”, “IMU Driver”, “gRPC Server”, “Python Teleop”

- Use directional arrows:

• Solid lines for real‑robot data flows (serial → firmware → SDK → Python)

• Dashed lines for simulation flows (URDF mesh → sim engine → Python)

• Dotted lines for build/CI pipelines

- Color‑code by type:

• Blue for hardware/drivers

• Green for middleware/communication

• Orange for SDK/tools

• Purple for user‑level scripts & simulation

- Group related files under folder icons or swimlanes (e.g., “kos-zbot/” folder → firmware & SDK cluster)

- Include callouts for external services: “GitLab CI”, “Docker Registry”, “Docs Site”

9. Emphasize detail

- Capture each major folder as an architectural component

- Call out the dual sim/real paths

- Show ML model conversion & deployment pipeline

Following these steps and guidelines will yield a precise, detailed system architecture diagram that reflects the full-stack nature of Zeroth Bot—from 3D‑printed hardware all the way up to Python‑based experiments.