SKU-01 Zero-Code Skin Studio (.gndskin v1.0) & OpenGND AgentHUD Setup Guide
Byte-level specification of the .gndskin v1.0 POSIX ustar container (OGS1 Big-Endian RGB565 sprites + 16kHz PCM WAV), <5s zero-reboot HTTP hot-reload, and pairing AI Buddy (ConvoAI) v1.1.0, PocketNote Standalone AI Recorder v2.0.0 (3 visual FX modes, local Whisper / BYOK live subtitles, SVG mindmap & Obsidian export), AgentHUD v2.4.1, and VoxDeck v1.1.1 with OpenGND Hub v3.0.4 (macOS & Windows).
1. The .gndskin v1.0 Binary Container Contract
OpenGND physically decouples compiled C firmware from visual/audio persona assets. Any .gndskin file generated in /studio?tab=skin is an uncompressed POSIX ustar TAR archive (512-byte headers with octal checksums) padded with 0x00 to a 4,096-byte Flash sector boundary so the ESP32-S3 can either stream-unpack it onto /sdcard/skins/<id>/ or memory-map (mmap) it directly inside the 1,024 KB emote_gen partition.
| Archive Entry | Binary Format | Byte-Level Contract |
|---|---|---|
| manifest.json | UTF-8 JSON (v1.0) | Declares palette, layout (digital-mono | flip-card | nixie-tube | minimal-rams | arcade-hud), persona prompt/wakeWord, and asset paths. |
| sprites/*.rgb565 | OGS1 Header + RGB565_BE | Bytes 0..3 'OGS1', LE uint16 width, height, frame_count (1..24), fps (1..30), LE uint32 payload_bytes, followed by high-byte-first RGB565 pixels for NV3031A DMA. |
| audio/*.wav | RIFF WAVE PCM | 16-bit signed PCM, Mono (1 ch), 16,000 Hz sample rate for wake, knobTick, alarm, and celebrate. |
2. Zero-Reboot LAN Hot-Swap (< 5 Seconds)
Upload a compiled .gndskin directly from the browser Skin Studio (when running over HTTP) or via curl/local device portal. The clock stages the upload atomically, verifies the header, remounts the theme, refreshes the 320×240 IPS display, and plays wake.wav without rebooting:
# Direct binary octet-stream upload to SKU-01 Skin Runtime
curl -X POST http://opengnd-clock.local/api/v1/skin/upload \
-H "Content-Type: application/octet-stream" \
--data-binary "@pixel-coder.gndskin"When visiting https://opengnd.com over HTTPS, Chromium blocks plain HTTP XHR requests to local LAN IPs. Either download the .gndskin and drag it onto http://opengnd-clock.local/ directly, or run http://localhost:3000/studio?tab=skin locally.
3. Pairing OpenGND AgentHUD v2.4.1 with Claude Code, Codex CLI, Antigravity & OpenGND Hub v3.0.4
Flash opengnd-clock-agent-hud.bin (v2.4.1) onto SKU-01 (or switch cable-free on-device via right SW4 SETTINGS_MENU across all 8 SKU-01 firmwares), pick one of 4 built-in neural default human voices per language (Warm Female, Clear Male, Bright Female, Deep Male) or OS voices, configure knob mode (including up to 16 newest-first tasks), live ES8311 volume calibration, localized character names, ADSR chimes, Cloud Text-to-SFX & cloned voices via /configure or our CLI bridge, or install OpenGND Hub v3.0.4 (/downloads/OpenGND-Hub-3.0.4-macos-arm64.dmg):
- 6-Character Cartoon Desk Pets & Official Rounded UI: Features 6 original 88×88 × 5-frame mascots (Nova, Dr.Quack, Neko, PocketBit, Sparky, Mochi in Flash XIP .rodata), capsule slot headers, rounded cards, and an interactive tap-to-cycle touch pet stage (TZ_PET_STAGE).
- OpenGND Hub v3.0.4 (Unified Companion Workspace · 4 Built-in Neural Voices/Lang, Stop Completion Voice Sync, Unified Config, 3-Mode Sound Sources & 3-Scene Rules, Cloud Text-to-SFX + Voice Cloning, LAN Direct OpenClaw :18790 & Cursor Dictation): Download /downloads/OpenGND-Hub-3.0.4-macos-arm64.dmg (Apple Silicon arm64) for opengnd.device.config.v1 sync across SKU-01 / SKU-02 / Focus Radar Bot / SKU-08 / MHL-01, 5-mode rotary knob + THREAD_LIST setup, streamlined Mechanical/Built-in+System+Cloud Voice/Cloning modes & Done/Confirm/Notify scene rules, ADSR Signature Sound Studio & Cloud AI Text-to-SFX / Voice Cloning / Multi-Voice TTS (ElevenLabs, Fish Audio, MiniMax), LAN Direct OpenClaw/Ollama voice gateway (:18790), global cursor voice dictation, PocketNote Markdown meeting minutes, VoxDeck 6-pad macro setup, OpenGND Cloud credits & live 320×240 screen mirror.
- 4bpp Antialiased Multi-Size XIP UTF-8 Font + 40 MHz SPI3 + Knob Scrolling: Renders crisp 16-level grayscale antialiased 16px/12px/28px Helvetica Neue + PingFang SC/TC directly from Flash .rodata (0B SRAM overhead) over a 40 MHz SPI3 display bus with IO47/IO21 rotary scrolling for long up-to-1024B detail cards.
- Full-Duplex ES8311/ES7210 Voice & 8-Tool Stdio MCP: Procedural chimes + 16kHz IMA-ADPCM TTS playback via agent_hud_speak, Hold-to-Talk dual-mic capture via agent_hud_listen (IO45 PA auto-muted), CST226SE touch action bar + IO14/SW3 approval, and 8 stdio MCP tools.
# 1. Auto-configure Claude Code, Codex CLI & Google Antigravity (agy) hooks/plugin + MCP
npx @opengnd/agent-hud init
# 2. Check live device status or capture a lossless 320x240 framebuffer screenshot
npx @opengnd/agent-hud status
npx @opengnd/agent-hud screenshot --out agent-hud-screen.png
# 3. Start 8-tool stdio MCP server or macOS focus + Stripe webhook watcher
npx @opengnd/agent-hud mcp