ESP32 Robot Face
Note: This document was generated by an AI agent.
A small ESP32-based robot face: a monochrome OLED driven entirely by procedural animation (no pre-rendered images), plus voice hardware for conversational interaction with a local or cloud speech agent. This is the concept-level, sharable write-up — the version meant to be read without the firmware repository open, and the one posted to the blog.
These documents are a reading sequence, not a reference pile. The folders and filenames are numbered in the order they are meant to be read: each part assumes the ones before it and nothing after it. Each explains the theory behind the thing it describes before describing this project's use of it, derives its numbers rather than asserting them, and ends with the failure modes that subsystem actually produces.
01 — Foundations
What the device is, and the constraints every later decision answers to.
| # | Document | Contents |
|---|---|---|
| 01 | Overview | What this is, what it does, the resource envelope everything else spends |
| 02 | Module map | Domain ownership, dependencies, the host-testable boundary |
| 03 | Hardware | Board, panel, touch, wiring, pin constraints, the I2C frame cost |
| 04 | Runtime | Boot, the fixed frame budget, task ownership, controller modes, ambient |
| 05 | One core, no FPU | The ESP32-C6 target: bus time against CPU, the partial flush, fixed-point audio, what it leaves stale |
02 — The face
Everything that puts pixels on the panel.
| # | Document | Contents |
|---|---|---|
| 01 | Rendering and effects | Pose data, the tween, easing curves, drawing layers, effect extension points |
| 02 | The 2.5D face rig | Ellipsoid projection, pose channels, authored scenes, interruption blending |
| 03 | Procedural head turn | Isolated rig, authored movement, foreshortening, exact-pixel preview |
| 04 | Ambient scenes | The blob eye shape, the merge geometry, the idle morph loop |
| 05 | Animation asset format | The user scene slots and the fixed-point keyframe wire format |
03 — Voice and audio
Getting sound in and out of a microcontroller in real time.
| # | Document | Contents |
|---|---|---|
| 00 | Decibels, from scratch | What a decibel is, the two formulas, and every unit this section quotes — background, skip if familiar |
| 01 | Voice hardware | Why a bare mic and a GPIO cannot do this job; the electrical and power design |
| 02 | I2S audio runtime | How I2S works, the ESP-IDF channel and DMA model, both core-0 tasks, the failure modes |
| 03 | Making the agent audible | dBFS, peak versus RMS, the compressor that bought +8.9 dB, and what it broke |
| 04 | Audio diagnostics | Capture gain, the capture guard, the browser test surface, the bring-up procedure |
04 — The agent
Turning speech into an answer, and an answer into an action.
| # | Document | Contents |
|---|---|---|
| 01 | The conversational agent | The wake word, silence-ended turns, the follow-up window, the face through a turn |
| 02 | Local agent pipeline | Provider boundary, task and data flow, service contracts, timing and memory budgets |
| 03 | Device actions | Why a small model's structured output cannot be trusted, and the validator that fixes it |
05 — Network and state
Everything that outlives a frame or leaves the board.
| # | Document | Contents |
|---|---|---|
| 01 | Web management and HTTP API | What the management site and its API do, authentication, discovery, browser firmware uploads |
| 02 | Data, network, weather, and OTA | External data lifecycle, failure handling, recovery-safe network updates |
| 03 | Settings, persistence, and assets | What survives a reboot, every runtime setting and what uses it |
Outside the sequence
Build, test, and troubleshooting material is deliberately not here: it describes operating the firmware repository rather than the design of the device, and is developer-only content this vault doesn't carry.