How tny-robotics/tny-360 works
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: main.cpp Main runtime · PCBs PCB packages · network Network stack · drivers Device drivers
Components 19
Physical product
Mechanical CAD and printable robot parts.
- CAD models · Chassis, legs, head, torso, battery enclosure, and mounts.
CAD - STL exports · Print-ready structural parts exported from the CAD models.
CAD/Exported/STLs
Electronics
Manufactured PCB assemblies and power/actuation hardware.
- PCB packages · Main, power, battery, motor, servo, paw, analog, and mount board outputs.
Electronics/PCBs - Power chain · Battery and power boards that handle LiPo/18650 supply and monitoring.
Electronics/PCBs/Power - Actuation boards · Motor driver, servomotor, paw, and analog reader integration boards.
Electronics/PCBs/Motor Driver
Embedded firmware
ESP32-S3 runtime and control software.
- Main runtime · Top-level robot application entry point and system wiring.
Firmware/src/main.cpp - Boot flow · Startup, calibration, and firmware update lifecycle.
Firmware/src/boot/BootManager.cpp - Device drivers · Analog, camera, IMU, motor, power, and screen drivers.
Firmware/src/drivers - Device libs · Shared low-level drivers such as INA219, MPU6050, PCA9685, and SH1106.
Firmware/components - Locomotion · Body model, leg/joint abstractions, gait planning, kinematics, and control loop.
Firmware/src/locomotion - Decision loop · Higher-level behavior coordination and control policy.
Firmware/src/decision/DecisionLoop.cpp - Network stack · Wi-Fi, DNS, WebSocket, update handling, and web interface.
Firmware/src/network - Protocol modules · Module-based telemetry and control surface for body, gait, IMU, joints, legs, motor, system, and Wi-Fi.
Firmware/src/network/protocol - On-device UI · Local menus, status, calibration, network, tests, and maintenance screens.
Firmware/src/ui - Audio stack · Speaker, mixer, and music/sine providers for robot audio.
Firmware/src/audio - Board config · ESP32-S3 board definition used by the firmware build.
Firmware/boards/TNY-360_ESP32-S3_N16R8.json - Build config · Partitioning, dependency lock, and version/build helpers.
Firmware/partitions.csv
Support tools
Companion tools and operator-facing extras.
- WebPortal · Companion browser app for visualization and remote control.
Firmware/extras/WebPortal - Servo tester · Standalone tool for servo testing and calibration.
Extras/TNY-Servo_Tester
Connections 19
- 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.