# design-os-robotics

> Open-source host tools, a 217.67 KB canonical Mochi-21 SoA scanline vector avatar pack (-91.3% vs the 2,560.27 KB default GIF pack), a 60 Hz 12-DOF spring-damper face solver, an autonomous Mochi-Soul self-evolution engine (EVO-01..03: Relative-Share Personality Genome, Dual-Track Phenotype, Idempotent Dream Consolidation, and 12-state USB-JTAG Watchdog Auto-Rescue FSM), and a no-reset USB-JTAG health probe for ESP32-S3 voice robots (Xiaozhi / Otto Quadruped / RoBot.5320).

## Primary Pages
- [Landing Page & Interactive 3D Specimen Viewer](https://morluto.github.io/design-os-robotics/): Facts, comparison table, interactive Three.js RB5320XZ78AI 3D chassis & 60fps authentic Mochi LCD face scrubber, worked builds, quick start, and FAQ.
- [Repository & Quick Start](https://github.com/morluto/design-os-robotics): Source code, CLI tools, and reproducible benchmark suites.
- [Domain Glossary (CONTEXT.md)](https://github.com/morluto/design-os-robotics/blob/main/CONTEXT.md): Canonical hardware offsets (`ota_1` at `0x560000`, `mmap_assets` at `0xAA0000`), Procedural Mochi-21 specification, and Homeostasis + EVO-01..03 definitions.

## Tools & Architecture
- [Canonical Mochi-21 Vector Table (tools/mochi_canonical_vectors.py)](https://github.com/morluto/design-os-robotics/blob/main/tools/mochi_canonical_vectors.py): 108,522 Structure-of-Arrays (SoA) horizontal scanline spans `(y, x0, w, color)` across 210 frames (`240x147` centered in `240x240`, 8-color `MOCHI_PALETTE_8`) reconstructing 100% pixel-identical Mochi animations in code.
- [Procedural Mochi-21 Avatar Cooker (tools/cook-procedural-avatar.py)](https://github.com/morluto/design-os-robotics/blob/main/tools/cook-procedural-avatar.py): Generates 21 unique 240x240 8-color GIF animations totaling 217.67 KB (`222,892` bytes, `-91.3%` vs the 2,560.27 KB default pack), supports `EVO-02` phenotype traits (`--stage`, `--curiosity`, `--affection`, `--playfulness`, `--resilience`), and packs the `0xAA0000` `esp_mmap_assets` image (with optional `--srmodels` `ESP-SR MultiNet6` `"Mochi / Hey Mochi / Hi Mochi"` wake-word model).
- [Mochi-Soul Engine (tools/mochi-soul-engine/engine.py)](https://github.com/morluto/design-os-robotics/blob/main/tools/mochi-soul-engine/engine.py): 4D homeostasis state machine (`Energy`, `Hunger`, `Bond`, and `Mood` as `Valence` + `Arousal`), `EVO-01` Relative-Share Personality Genome + bounded homeostatic set-point plasticity, `EVO-02` Dual-Track Morphological Phenotype, `EVO-03` idempotent SQLite WAL Dream Consolidation (`dream_journal`), and 5 growth stages (`Mochi-Egg` to `Mochi-Ascendant`).
- [60fps Spring-Damper & Lip-Sync Solver (tools/mochi-soul-engine/reflex_60fps.py)](https://github.com/morluto/design-os-robotics/blob/main/tools/mochi-soul-engine/reflex_60fps.py): Exact ZOH 12-DOF matrix exponential solver (~2.60 us/frame on host), 16 kHz PCM RMS lip-sync envelope tracker, HC-SR04 proximity reflex state machine, and `mochi_face_60fps.hpp` C++17 header generator.
- [Proactive ota_1 Bridge & HUD Renderer (tools/mochi-soul-engine/bridge.py)](https://github.com/morluto/design-os-robotics/blob/main/tools/mochi-soul-engine/bridge.py): Validates outgoing `Application::OnIncomingJson` (`0x4202c0c8`) packets and renders a 240x320 Tamagotchi HUD PNG (~2.19 ms/card) with a 12-color canonical Mochi palette.
- [USB-JTAG Serial Supervisor & WDT Auto-Rescue FSM (tools/mochi-soul-engine/serial_supervisor.py)](https://github.com/morluto/design-os-robotics/blob/main/tools/mochi-soul-engine/serial_supervisor.py): Single-owner passive USB-JTAG monitor (`DTR=False, RTS=False`) with a 12-state Watchdog Auto-Rescue FSM (`IDLE -> ACTIVE -> DEGRADED -> STALLED -> PROBING -> RESCUING -> REBOOTING -> COOLDOWN -> CIRCUIT_OPEN`) that detects `Task watchdog got triggered` or `Guru Meditation Error` and rescues the robot with bounded backoff.
- [Mochi-Soul Live Companion Studio (tools/mochi-soul-engine/app.py)](https://github.com/morluto/design-os-robotics/blob/main/tools/mochi-soul-engine/app.py): Local HTTP server on port `4390` serving the 60fps authentic Mochi vector studio UI, `/api/mochi-vectors`, `/api/evolve`, `/api/dream`, `/api/wdt`, `/ota` activation bypass, and `/api/hud.png`.
- [No-Reset Health & Robot CLI (tools/robotctl.py)](https://github.com/morluto/design-os-robotics/blob/main/tools/robotctl.py): Passive USB-JTAG and ICMP LAN probe (`robotctl.py health --wdt-rescue auto`) that never toggles DTR/RTS, plus HTML avatar preview (`robotctl.py preview`).

## Benchmark Reports (Single-Run Host Measurements on Apple Silicon Python 3.11)
- [Avatar Compression & Decode Report](https://github.com/morluto/design-os-robotics/blob/main/plans/reports/benchmark-avatar-perf.json)
- [Mochi-Soul Engine Report](https://github.com/morluto/design-os-robotics/blob/main/plans/reports/benchmark-mochi-soul-engine.json)
- [Proactive Bridge & HUD Report](https://github.com/morluto/design-os-robotics/blob/main/plans/reports/benchmark-proactive-bridge.json)
- [60fps Reflex & Lip-Sync Report](https://github.com/morluto/design-os-robotics/blob/main/plans/reports/benchmark-reflex-60fps.json)
- [Live Companion Studio Report](https://github.com/morluto/design-os-robotics/blob/main/plans/reports/benchmark-live-companion-app.json)