# tny-robotics/tny-360 architecture

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

- Interactive diagram: https://gitdiagram.com/tny-robotics/tny-360
- Repository: https://github.com/tny-robotics/tny-360

## Overview

1. **Repository scope**
   - This repo is a full product stack for the TNY-360 quadruped robot: mechanical CAD, PCB manufacturing files, embedded firmware, and a small set of support tools.
   - The main runtime system is an **ESP32-S3-based robot controller**; the rest of the repo feeds that controller with physical parts, electronics, and build outputs.

2. **Physical product layer**
   - `CAD/` contains the FreeCAD source models for the chassis, legs, head, torso, battery enclosure, servo covers, and common clips.
   - `CAD/Exported/STLs/` is the print-ready fabrication output for the robot’s structural parts.
   - This layer defines the robot’s mechanical boundaries: where servos mount, how cable routing is handled, and how sensor/PCB modules fit into the body.

3. **Electronics and modular hardware**
   - `Electronics/PCBs/` holds the manufacturing package for multiple purpose-built boards: Main, Power, Battery, Motor Driver, Servomotor, Paw, Analog Reader, and Universal Mount.
   - These boards are the hardware integration layer between the MCU and the robot’s actuators, sensors, and power system.
   - The design is explicitly modular: standardized cable harnesses and separate PCBs reduce wiring complexity and isolate subsystems.

4. **Power subsystem**
   - The robot is powered by a **3S LiPo / 18650 battery pack** with monitoring via **INA219**.
   - The `Firmware/components/ina219` driver and the `Firmware/src/drivers/PowerDriver.cpp` path indicate a dedicated power-management boundary.
   - Power-related PCB files in `Electronics/PCBs/Battery` and `Electronics/PCBs/Power` suggest the power chain is treated as its own subsystem, not just a passive supply rail.

5. **Actuation and feedback subsystem**
   - The robot uses **12 MG996R servos for locomotion**, **2 SG90 servos for ears/head**, and a **PCA9685 PWM controller**.
   - The README highlights modified MG996R servos with **analog feedback buffering**; that shows the feedback path is a first-class architectural concern, not an afterthought.
   - Firmware separates this into motor-related drivers and controllers, with calibration utilities for deadband, inversion, latency, noise, and physical bounds.

6. **Core embedded firmware**
   - `Firmware/` is an **ESP-IDF / PlatformIO** project in C++.
   - The runtime is organized around major subsystems under `src/` and `include/`: `common`, `drivers`, `locomotion`, `network`, `ui`, `audio`, `boot`, and `decision`.
   - This is the central control plane: hardware drivers feed state into locomotion and decision logic, while UI and networking provide observability and remote control.

7. **Dual-core execution model**
   - The README states a split between **Core 0 (“Reflex”)** and **Core 1 (“Brain”)**.
   - Core 0 runs the strict **200 Hz control/kinematics loop**, which is the low-latency motion boundary.
   - Core 1 handles higher-level orchestration such as WebSockets, web UI, and system coordination.
   - For an architecture diagram, this is the key runtime separation: deterministic control versus interactive/networked control.

8. **Locomotion and kinematics pipeline**
   - `locomotion/` contains the body model, leg/joint abstractions, gait planner, kinematics engine, motor controller, and control loop.
   - The data path is likely: sensor feedback and pose state → kinematics/gait computation → motor target generation → actuator output.
   - Calibration helpers inside locomotion indicate that motion planning is constrained by measured hardware properties, not just ideal geometry.

9. **Sensor and driver layer**
   - `drivers/` contains dedicated drivers for **Analog**, **Camera**, **IMU**, **Motor**, **Power**, and **Screen**.
   - `components/` contains reusable lower-level libraries such as **MPU6050**, **INA219**, **PCA9685**, and **SH1106**.
   - This creates a clear boundary between reusable device access code and higher-level robot behavior.

10. **Network, web interface, and remote protocol**
    - `network/` provides **Wi‑Fi management, DNS, WebSocket communication, update handling, and a web interface**.
    - The protocol layer under `network/protocol/modules/` breaks telemetry/control into functional domains like body, gait, IMU, joint, leg, motor, system, and Wi‑Fi.
    - That structure suggests remote clients talk to the robot through a typed module-based protocol rather than raw ad hoc messages.

11. **On-device UI and local interaction**
    - `ui/` provides the OLED-facing interface and menu system, with screens for splash, system info, logs, calibration, network, Wi‑Fi, update, tests, and reset/reboot flows.
    - This UI is the local operator surface when the robot is not being controlled through the web interface.
    - The UI depends on the screen driver and system state exposed by the rest of the firmware.

12. **Boot, calibration, and update flow**
    - `boot/` contains the startup and calibration menus, including zero calibration and update/verification stages.
    - `network/UpdateManager.cpp` and boot update files indicate a firmware update path integrated into normal system startup.
    - Calibration is not a one-off tool; it is part of the boot-time and maintenance lifecycle of the robot.

13. **Audio and human interaction**
    - `audio/` includes a speaker, sound mixer, sine/music providers, and an audio manager.
    - This subsystem is separate from locomotion and UI, implying audio is used as a secondary interaction/output channel rather than part of motion control.

14. **Support tooling and ancillary apps**
    - `Extras/TNY-Servo_Tester/` is a standalone embedded tool for servo testing/calibration.
    - `Firmware/extras/WebPortal/` is a Nuxt/Vue-based companion web app that likely provides a richer operator interface and visualization layer for the robot.
    - These are support surfaces around the core firmware, not the main runtime itself.

15. **Build, packaging, and artifact boundaries**
    - The repo stores generated artifacts alongside source: STL exports, PCB Gerbers/BOM/PnP files, and firmware lock/config files.
    - Firmware build tooling includes board definitions, partitioning, version generation, and asset-copy scripts, which suggests the firmware can bundle web assets and release a packaged image.
    - A GitHub Actions workflow exists for deployment, but the main architectural point is that source and manufacturing outputs are both versioned in the same repository.

Main entry points: [`Firmware/src/main.cpp`](https://github.com/tny-robotics/tny-360/blob/main/Firmware/src/main.cpp) (Main runtime), [`Electronics/PCBs`](https://github.com/tny-robotics/tny-360/tree/main/Electronics/PCBs) (PCB packages), [`Firmware/src/network`](https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/network) (Network stack), [`Firmware/src/drivers`](https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/drivers) (Device drivers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_physical["Physical product"]
  node_cad_models["CAD models<br/>FreeCAD source"]
  node_cad_stls["STL exports<br/>print assets"]
end

subgraph group_electronics["Electronics"]
  node_pcbs["PCB packages<br/>manufacturing"]
  node_power_boards["Power chain<br/>hardware subsystem"]
  node_actuation_boards["Actuation boards<br/>hardware subsystem"]
end

subgraph group_firmware["Embedded firmware"]
  node_firmware_main["Main runtime<br/>ESP-IDF app<br/>[main.cpp]"]
  node_boot["Boot flow<br/>startup<br/>[BootManager.cpp]"]
  node_drivers["Device drivers<br/>hardware access"]
  node_components["Device libs<br/>reusable components"]
  node_locomotion["Locomotion<br/>motion stack"]
  node_decision["Decision loop<br/>orchestration<br/>[DecisionLoop.cpp]"]
  node_network["Network stack<br/>connectivity"]
  node_protocol["Protocol modules<br/>typed RPC"]
  node_ui["On-device UI<br/>OLED UI"]
  node_audio["Audio stack<br/>sound output"]
  node_board_def["Board config<br/>build target"]
  node_firmware_build["Build config<br/>packaging<br/>[partitions.csv]"]
end

subgraph group_support["Support tools"]
  node_webportal["WebPortal<br/>Nuxt app"]
  node_servo_tester["Servo tester<br/>embedded tool"]
end

node_cad_models -->|"exports"| node_cad_stls
node_cad_models -.->|"fits"| node_pcbs
node_pcbs -->|"contains"| node_power_boards
node_pcbs -->|"contains"| node_actuation_boards
node_board_def -->|"targets"| node_firmware_main
node_firmware_build -.->|"packages"| node_firmware_main
node_components -->|"supports"| node_drivers
node_drivers -->|"feeds state"| node_locomotion
node_locomotion -->|"reports"| node_decision
node_firmware_main -->|"starts"| node_boot
node_firmware_main -->|"initializes"| node_drivers
node_firmware_main -->|"runs"| node_locomotion
node_firmware_main -->|"orchestrates"| node_decision
node_firmware_main -->|"serves"| node_network
node_network -->|"encodes"| node_protocol
node_network -.->|"connects"| node_webportal
node_firmware_main -->|"displays"| node_ui
node_firmware_main -->|"outputs"| node_audio
node_servo_tester -.->|"validates"| node_actuation_boards

click node_cad_models "https://github.com/tny-robotics/tny-360/tree/main/CAD"
click node_cad_stls "https://github.com/tny-robotics/tny-360/tree/main/CAD/Exported/STLs"
click node_pcbs "https://github.com/tny-robotics/tny-360/tree/main/Electronics/PCBs"
click node_power_boards "https://github.com/tny-robotics/tny-360/tree/main/Electronics/PCBs/Power"
click node_actuation_boards "https://github.com/tny-robotics/tny-360/tree/main/Electronics/PCBs/Motor Driver"
click node_firmware_main "https://github.com/tny-robotics/tny-360/blob/main/Firmware/src/main.cpp"
click node_boot "https://github.com/tny-robotics/tny-360/blob/main/Firmware/src/boot/BootManager.cpp"
click node_drivers "https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/drivers"
click node_components "https://github.com/tny-robotics/tny-360/tree/main/Firmware/components"
click node_locomotion "https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/locomotion"
click node_decision "https://github.com/tny-robotics/tny-360/blob/main/Firmware/src/decision/DecisionLoop.cpp"
click node_network "https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/network"
click node_protocol "https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/network/protocol"
click node_ui "https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/ui"
click node_audio "https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/audio"
click node_board_def "https://github.com/tny-robotics/tny-360/blob/main/Firmware/boards/TNY-360_ESP32-S3_N16R8.json"
click node_firmware_build "https://github.com/tny-robotics/tny-360/blob/main/Firmware/partitions.csv"
click node_webportal "https://github.com/tny-robotics/tny-360/tree/main/Firmware/extras/WebPortal"
click node_servo_tester "https://github.com/tny-robotics/tny-360/tree/main/Extras/TNY-Servo_Tester"

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_cad_models,node_cad_stls toneBlue
class node_pcbs,node_power_boards,node_actuation_boards toneAmber
class node_firmware_main,node_boot,node_drivers,node_components,node_locomotion,node_decision,node_network,node_protocol,node_ui,node_audio,node_board_def,node_firmware_build toneMint
class node_webportal,node_servo_tester toneRose
```

## Components

### Physical product

Mechanical CAD and printable robot parts.

- [CAD models](https://github.com/tny-robotics/tny-360/tree/main/CAD): FreeCAD source · Chassis, legs, head, torso, battery enclosure, and mounts. · `CAD`
- [STL exports](https://github.com/tny-robotics/tny-360/tree/main/CAD/Exported/STLs): print assets · Print-ready structural parts exported from the CAD models. · `CAD/Exported/STLs`

### Electronics

Manufactured PCB assemblies and power/actuation hardware.

- [PCB packages](https://github.com/tny-robotics/tny-360/tree/main/Electronics/PCBs): manufacturing · Main, power, battery, motor, servo, paw, analog, and mount board outputs. · `Electronics/PCBs`
- [Power chain](https://github.com/tny-robotics/tny-360/tree/main/Electronics/PCBs/Power): hardware subsystem · Battery and power boards that handle LiPo/18650 supply and monitoring. · `Electronics/PCBs/Power`
- [Actuation boards](https://github.com/tny-robotics/tny-360/tree/HEAD/Electronics/PCBs/Motor%20Driver): hardware subsystem · Motor driver, servomotor, paw, and analog reader integration boards. · `Electronics/PCBs/Motor Driver`

### Embedded firmware

ESP32-S3 runtime and control software.

- [Main runtime](https://github.com/tny-robotics/tny-360/blob/main/Firmware/src/main.cpp): ESP-IDF app · Top-level robot application entry point and system wiring. · `Firmware/src/main.cpp`
- [Boot flow](https://github.com/tny-robotics/tny-360/blob/main/Firmware/src/boot/BootManager.cpp): startup · Startup, calibration, and firmware update lifecycle. · `Firmware/src/boot/BootManager.cpp`
- [Device drivers](https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/drivers): hardware access · Analog, camera, IMU, motor, power, and screen drivers. · `Firmware/src/drivers`
- [Device libs](https://github.com/tny-robotics/tny-360/tree/main/Firmware/components): reusable components · Shared low-level drivers such as INA219, MPU6050, PCA9685, and SH1106. · `Firmware/components`
- [Locomotion](https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/locomotion): motion stack · Body model, leg/joint abstractions, gait planning, kinematics, and control loop. · `Firmware/src/locomotion`
- [Decision loop](https://github.com/tny-robotics/tny-360/blob/main/Firmware/src/decision/DecisionLoop.cpp): orchestration · Higher-level behavior coordination and control policy. · `Firmware/src/decision/DecisionLoop.cpp`
- [Network stack](https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/network): connectivity · Wi-Fi, DNS, WebSocket, update handling, and web interface. · `Firmware/src/network`
- [Protocol modules](https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/network/protocol): typed RPC · Module-based telemetry and control surface for body, gait, IMU, joints, legs, motor, system, and Wi-Fi. · `Firmware/src/network/protocol`
- [On-device UI](https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/ui): OLED UI · Local menus, status, calibration, network, tests, and maintenance screens. · `Firmware/src/ui`
- [Audio stack](https://github.com/tny-robotics/tny-360/tree/main/Firmware/src/audio): sound output · Speaker, mixer, and music/sine providers for robot audio. · `Firmware/src/audio`
- [Board config](https://github.com/tny-robotics/tny-360/blob/main/Firmware/boards/TNY-360_ESP32-S3_N16R8.json): build target · ESP32-S3 board definition used by the firmware build. · `Firmware/boards/TNY-360_ESP32-S3_N16R8.json`
- [Build config](https://github.com/tny-robotics/tny-360/blob/main/Firmware/partitions.csv): packaging · Partitioning, dependency lock, and version/build helpers. · `Firmware/partitions.csv`

### Support tools

Companion tools and operator-facing extras.

- [WebPortal](https://github.com/tny-robotics/tny-360/tree/main/Firmware/extras/WebPortal): Nuxt app · Companion browser app for visualization and remote control. · `Firmware/extras/WebPortal`
- [Servo tester](https://github.com/tny-robotics/tny-360/tree/main/Extras/TNY-Servo_Tester): embedded tool · Standalone tool for servo testing and calibration. · `Extras/TNY-Servo_Tester`

## Connections

- CAD models → STL exports: exports · Source CAD generates print-ready parts.
- CAD models → PCB packages: fits · Mechanical envelopes and mounts constrain electronics integration.
- PCB packages → Power chain: contains · Power-related board set.
- PCB packages → Actuation boards: contains · Actuation and sensing board set.
- Board config → Main runtime: targets · Defines the ESP32-S3 runtime target.
- Build config → Main runtime: packages · Build and release configuration shapes the firmware image.
- Device libs → Device drivers: supports · Reusable device libraries back the higher-level drivers.
- Device drivers → Locomotion: feeds state · Motor, IMU, analog, and power data inform motion control.
- Locomotion → Decision loop: reports · Motion state and constraints inform behavioral decisions.
- Main runtime → Boot flow: starts · Main application enters boot, calibration, and update flows.
- Main runtime → Device drivers: initializes · Application wires hardware drivers into the runtime.
- Main runtime → Locomotion: runs · Deterministic motion control is part of the main runtime.
- Main runtime → Decision loop: orchestrates · Higher-level behavior and system coordination.
- Main runtime → Network stack: serves · Connectivity and remote control endpoints run on the main firmware.
- Network stack → Protocol modules: encodes · Telemetry and commands are organized into typed protocol modules.
- Network stack → WebPortal: connects · Browser UI consumes the robot web and websocket interfaces.
- Main runtime → On-device UI: displays · Local operator interface is driven by the core system state.
- Main runtime → Audio stack: outputs · Audio is managed as a separate interaction channel.
- Servo tester → Actuation boards: validates · Standalone tool supports servo and feedback calibration.
