The problem Tamagotchi solves

Gochi is a real, physical Tamagotchi — a virtual pet that actually lives on a tiny ESP32-C3 SuperMini wired to a 0.96" SSD1306 OLED, a piezo buzzer, and buttons. Unlike the 90s keychain toys with pre-baked sprite frames, every one of Gochi's 10+ expressions is drawn fully procedurally from primitives (rounded rects, arcs, lines, circles, triangles) — no bitmaps anywhere. Each face has its own idle animation: a happy bob, a sad sliding tear, sleepy floating "Z"s with a breathing chest, an excited fast bounce, an angry tremble, pulsing love hearts with blush, and dead X-eyes.

The pet runs autonomously. It boots into Free Mode, wandering a shared mood (content / playful / grumpy / sleepy / affectionate), picking mood-appropriate expressions every ~10-17s and drifting its mood over minutes. The buzzer plays a short jingle matched to each face, kept in sync no matter what triggered the change.

You can also drive it like a desktop companion. A cross-platform gochi CLI mirrors a serial line protocol (show face, set mood, get state, ping...) and even streams live images — point it at any PNG/JPG and it Floyd–Steinberg-dithers the frame down to 128×64 and renders it on the OLED. A background daemon owns the single connection, auto-detects the device, and exposes a REST API so AI agents (like this one!) can reflect task outcomes on the pet's face. The whole thing works cable-free over Bluetooth LE once paired over USB.

Challenges I ran into

Cable-free without a desktop Bluetooth stack to lean on. The C3 is BLE-only (no Classic/SPP), so wireless control is a Nordic UART Service mirroring the serial protocol. The hard bug: NimBLE "just-works" bonding silently connects but never bonds (getNumBonds() stays 0, encrypted characteristics unusable) unless you call BOTH setSecurityInitKey/RespKey(ENC|ID) and NimBLEDevice::startSecurity(connHandle) in onConnect. Pairing is USB-gated for safety — BLE only advertises after a USB command opens a window — and bonds auto-reconnect on boot.

Truncated frames over USB. Streaming a base64 image frame kept failing with mbedtls_base64_decode returning -44 (INVALID_CHARACTER). Root cause: HWCDC's default 256-byte RX FIFO overruns mid-payload. Raising Serial.setRxBufferSize(2048) and the line cap to 1536 fixed it cleanly.

Frame-rate bottleneck. Bit-banged I2C capped the OLED at ~15-25 fps. Switching to the C3's hardware I2C peripheral at 400 kHz (routed to GPIO5/6 via the GPIO matrix) unblocked smooth animation.

A wedged radio, not a stale bond. After re-pairing, "no BLE connection" turned out not to be a macOS bond issue but the daemon's long-lived noble stack getting wedged — the connect-failure path called scan() while still busy, so it no-op'd forever. Fixed with a coalesced scheduleScan() and a force stop→start; gochi kill (fresh CoreBluetooth) became the reliable recovery.

No IDE. Everything is built, flashed, and linted from the terminal with arduino-cli, a Makefile, and a portable clangd config — reproducible on any machine.