DESIGN:OS · ROBOTICS & MOCHI-SOUL ENGINE
Non-intrusive NVS & esp_mmap_assets compiler, 4-layer hardware health telemetry, 4D homeostasis Tamagotchi engine, and 60Hz spring kinematics for RB5320XZ78AI (ESP32-S3 N16R8 + ST7789 240×320).
-202020?style=for-the-badge&labelColor=09090b){kind=icon}
Procedural Mochi-21 draws 21 faces in code: 217.67 KB of GIFs in total (21 files) instead of 2,560.27 KB for the default 21, full-bleed on the 240x320 display.
RoBot.5320 · 0xAA0000 verified · 8/8 OKThe toolchain draws a full-bleed 240×240 face on the 240×320 panel. A battery HUD reads GPIO 17 and GPIO 38. Conversation text is hidden for a pure face mode. Health checks never toggle DTR/RTS.
cook-procedural-avatar.py synthesizes all 21 emotions in 217.67 KB of GIFs in total (down from 2,560.27 KB).
engine.py ticks a 4D biological state vector (energy, hunger, bond, mood) in ~0.76 µs/tick (measured idle median) with SQLite WAL persistence and Quiet Hours (23:00–07:30), matched 100% to Application::OnIncomingJson (bridge.py).
reflex_60fps.py and mochi_face_60fps.hpp solve 10-DOF spring kinematics in 2.60 µs/frame (single run) (420/420 pairs converged, lip-sync r=0.9592).
robotctl.py probes USB-JTAG with ~HUPCL, ARP/ICMP LAN, cloud TLS, NVS CRC32, and live UART telemetry without resetting the chip.
Honest limits. Benchmarks are host-only. The toolchain is calibrated for RB5320XZ78AI only. It has no cloud assistant of its own.
Inspect the 6-layer RB5320XZ78AI (RoBot.5320) hardware stack directly in the browser via Three.js. Explode the enclosure layers, isolate BOM subsystems, or scrub the live 60fps second-order spring Mochi-21 display on the ST7789 240×320 screen.
Initializing 3D assembly…
Serve the docs/ folder over HTTP to inspect the 3D assembly locally:
python3 -m http.server 4180 --directory docsEvery theme binary and Spec-Driven engine module below is accompanied by its flash checksum, measured runtime latency, and the benchmark JSON committed in plans/reports/.
All 21 emotions generated mathematically at 240×240 px with a locked 8-colour indexed LZW palette (robot_2 reuses the neutral GIF), for a 91.3% smaller GIF total than the factory GIFs (the packed .bin is 62.9% smaller: 5,636,096 → 2,092,592 B).
Source: plans/reports/benchmark-avatar-perf.json
Continuous Energy / Hunger / Bond / Mood (Valence, Arousal) solver (~0.76 µs/tick measured idle median) + 240×320 HUD card renderer (2,716 B, 1.22 ms/card, single run) and OnIncomingJson bridge.
Source: plans/reports/benchmark-proactive-bridge.json
10-DOF second-order differential spring kinematics in 2.60 µs/frame (single run) (420/420 pairs converged, lip-sync r=0.9592, C++17 alignas(64) header).
Source: plans/reports/benchmark-reflex-60fps.json
Non-intrusive ~HUPCL USB-JTAG, ARP/ICMP LAN, cloud TLS, NVS CRC32, and passive UART telemetry check with 0% conversation drop.
Operate-mode companion studio (tools/mochi-soul-engine/app.py + studio.html) coupling the 240×240 Mochi-21 OLED face, 4D homeostasis register, custom DS sensor scrubbers, workspace symbiosis triggers, and 20-tool JSON-RPC 2.0 MCP dispatch (37.39 µs/event, single run).
Source: plans/reports/benchmark-live-companion-app.json
Photos of the physical RB5320XZ78AI build running the firmware, taken by the repository owner. The network name, setup address, serial prints and QR codes are blurred or covered by a solid bar. Third-party silkscreen art and logos (a ring logo, a ribbed oval emblem, a poster, a lion drawing and a few small symbols, on the board edges and in the line-art drawings shown on the screen), the embossed brand marks on a cable plug and a bottle, and the module model text are blurred in every photo where they appear. Generic board labels such as pin names, part numbers and the SPI, PWR ON and PCM labels stay visible. Photo 05 (back of the board) shows no such art, and the files carry no metadata. Select a photo for the full-size version.
A 6-part tool-free 3D-printable unibody housing engineered for the RB5320XZ78AI companion platform (86.0 × 48.1 × 104.0 mm). Features continuous superellipse curvature, 11° twin hook-hinges with 0.25 mm elastic cantilever snaps, 3 living-hinge rear tactile buttons, 132 parametric Apple-style micro-apertures, and an open-floor 50 mm USB-C pass-through weighted desk dock.
Download the 6 watertight STL files from the hardware/mc-rb5320-r03/stl directory. Full CAD specifications, production receipts, gate reports, and clearance audits are documented in hardware/mc-rb5320-r03/README.md.
Clone the repository and run the two commands that work on a clean clone.
git clone https://github.com/jangtrinh/design-os-robotics.git
cd design-os-robotics
python3 tools/robotctl.py health
python3 tools/mochi-soul-engine/engine.py benchmarkengine.py benchmark overwrites the committed plans/reports/benchmark-mochi-soul-engine.json. reflex_60fps.py, bridge.py benchmark and tools/benchmark-avatar-perf.py also run on a clean clone; the avatar benchmark reads the committed GIFs when no .bin pack is built. tools/cook-procedural-avatar.py needs your own assets dump (see below).
~HUPCL so a connected robot is never reset).
python3 tools/robotctl.py healthrobotctl.py status and optimize read your own NVS dump at profiles/example-esp32s3-n16r8/partitions/03-nvs-0x009000.bin; it is gitignored and not in the repo, so both print an error and exit with status 2 until you supply it.bridge.py benchmark) runs offline too.
python3 tools/mochi-soul-engine/reflex_60fps.pyThe benchmarks that run (engine.py benchmark and reflex_60fps.py) write a JSON report into plans/reports/.
Four steps cover diagnostics, procedural asset compilation, soul simulation, and hardware flashing. Diagnostics and the soul benchmark run on a clean clone; the other two need your own device dumps.
healthAudits USB-JTAG, LAN ARP/ICMP latency, Tenclass TLS, NVS CRC32, and passive UART logs via python3 tools/robotctl.py health.
cook-proceduralSynthesizes all 21 procedural Mochi GIFs (217.67 KB) and packs the Procedural Mochi-21 240×320 asset binary (checksum 0x5867). Needs your own base assets dump, which is not in the repo; the packed binary is built locally and is not tracked.
soul-benchmarkRun engine.py benchmark for Spec 02 (~0.76 µs/tick measured idle, median of 12 runs) and reflex_60fps.py for Spec 04 (2.60 µs/frame (single run) 60fps spring + lip-sync). bridge.py benchmark runs the Spec 03 bridge suite.
optimize --flashWrites only the NVS partition at 0x9000, through uvx esptool. It needs your own NVS dump and exits with an error without it. Back up NVS first.
DESIGN:OS Robotics is a source-available hardware control CLI, esp_mmap_assets theme compiler, 4-layer non-intrusive diagnostic dashboard, and Spec-Driven Generative AI Tamagotchi runtime (Project Mochi-Soul) built for ESP32-S3 N16R8 voice robots (RB5320XZ78AI / XiaoZhi78).
Instead of shipping the default GIF pack of 2.50 MiB (2,621,717 bytes) of 100x100 bitmap GIFs, cook-procedural-avatar.py synthesizes all 21 emotions from 582 lines of geometric math at 240x240 px with a locked 8-colour indexed LZW palette, achieving 681 average scanline RLE spans per frame.
Standard esptool invocations toggle DTR and RTS lines on the USB-Serial/JTAG controller, triggering a hard chip reset. robotctl.py opens USB-JTAG with the termios ~HUPCL flag so DTR is never dropped, auditing USB-JTAG, ARP/ICMP LAN latency, voice-server TLS, NVS CRC32, and passive UART telemetry with zero conversation interruption.
Spec 02 (engine.py) evolves a continuous 4D biological state vector (energy, hunger, bond, and mood as valence and arousal) in ~0.76 us/tick (measured idle median) with SQLite WAL persistence (~4.0 us/tx, median of 12 runs) and Quiet Hours guardrails (23:00–07:30). Spec 04 (reflex_60fps.py and mochi_face_60fps.hpp) integrates a 10-DOF second-order differential spring equation in 2.36 us/frame (single run) at 60Hz with r = 0.9592 lip-sync correlation.
DESIGN:OS Robotics is source-available under PolyForm Shield 1.0.0: any purpose is permitted except providing a product that competes with this software or with a product the licensor provides using it. You may use, study, modify and distribute it if you keep the licence terms and the Required Notice line. Third-party works (Be Vietnam Pro under SIL OFL 1.1, three.js under MIT) keep their own licences; see THIRD_PARTY_NOTICES.md.
EVO-01 (Personality Genome & Set-Point Plasticity) evolves 5 persistent traits (curiosity, affection, playfulness, resilience, chronotype_shift) using zero-sum Relative-Share drift (RS_k - 0.25) so dominant care patterns grow while unexercised traits gently recede toward 0.5. EVO-02 (Dual-Track Phenotype) renders continuous 60fps morphological traits in Studio and enforces a 5-step Flash Budget Degradation Ladder in tools/cook-procedural-avatar.py (leaving +64.9 KB headroom in 0xAA0000 even when packing the 3.67 MB ESP-SR MultiNet6 "Mochi / Hey Mochi / Hi Mochi" wake-word model alongside all 21 authentic Mochi GIFs). EVO-03 (Dream Consolidation & WDT Auto-Rescue) runs an idempotent SQLite WAL dream journal once per quiet-hours window and supervises USB-JTAG health via a 12-state Watchdog Auto-Rescue FSM (tools/mochi-soul-engine/serial_supervisor.py).
Explore companion toolchains, hardware showcases, and source-available infrastructure from the DESIGN:OS ecosystem.