diff --git a/docs/api.md b/docs/api.md index 59755746..343a52cf 100644 --- a/docs/api.md +++ b/docs/api.md @@ -185,7 +185,7 @@ curl http://tiny-engineer.local/settings | `push_button_pin` | GPIO on the Extension port for the push-button: **6**, **7**, **20**, or **21** (default **20**). Persists when `push_button` is off. Applies **immediately** when the extension is on | | `continuous_timeout` | Minutes a continuous animation (`typing` / `reading` / `thinking` / `talking`) may run before the firmware switches to `attention` then idle (default **5**) | | `loading` | Boot loading screen: `progress` (bar + large IP for 3 s) or `sleep_inertia` (eyes wake; no bar/IP). Default **`progress`**. Applies on **next reboot** | -| `eyes_style` | OLED eyes look: `classic` (procedural rounded eyes), `kaomoji` (animated faces), `cover` (full-half bars for an eye-hole mask), or `dots` (12×12 circles). Default **`classic`**. Applies **immediately**. Classic, cover, and dots sequences are described under [`POST /anim`](#post-anim); kaomoji face mapping is under [Kaomoji eyes](#kaomoji-eyes); cover drawing is under [Cover eyes](#cover-eyes); dots drawing is under [Dots eyes](#dots-eyes) | +| `eyes_style` | OLED eyes look: `classic` (procedural rounded eyes), `kaomoji` (animated faces), `cover` (full-half bars for an eye-hole mask), `dots` (12×12 circles), or `kawaii` (round eyes with big moving pupils, a talking mouth, and blush). Default **`classic`**. Applies **immediately**. Classic, cover, and dots sequences are described under [`POST /anim`](#post-anim); kaomoji face mapping is under [Kaomoji eyes](#kaomoji-eyes); cover drawing is under [Cover eyes](#cover-eyes); dots drawing is under [Dots eyes](#dots-eyes); kawaii moods are under [Kawaii eyes](#kawaii-eyes) | | `access_token_set` | `true` when a non-empty access token is stored (secret itself is never returned) | | `link_mode` | `""` unprovisioned, `"wifi"`, or `"usb"` (connection mode; see [`serial.md`](serial.md)) | | `wifi_configured` | `true` when at least one WiFi network is saved | @@ -248,7 +248,7 @@ curl -X POST "http://192.168.4.1/settings" \ | `push_button_pin` | integer | Extension-port GPIO **6**, **7**, **20**, or **21** (default **20**); persists when off | | `continuous_timeout` | integer | 1–1440 minutes (positive) | | `loading` | string | `progress` or `sleep_inertia` | -| `eyes_style` | string | `classic`, `kaomoji`, `cover`, or `dots` | +| `eyes_style` | string | `classic`, `kaomoji`, `cover`, `dots`, or `kawaii` | | `access_token` | string | 0–64 printable ASCII, no space at either end; empty string clears the token and disables auth. Setting or rotating a non-empty value disconnects WebSocket `/events` subscribers (they must reconnect with the new token); clearing does not | | `link_mode` | string | `wifi` or `usb`; setup Connection step uses `usb` for USB-only; Wi-Fi mode is usually set when saving networks via [`PUT /settings/wifi`](#put-settingswifi) | | `servo_mins` | integer array | Five integers `0`–`180` (`head, neck, left, right, body`); setup AP only; must be sent with `servo_maxs` | @@ -612,7 +612,7 @@ curl -X POST "http://tiny-engineer.local/anim?name=none" { "ok": true, "animation": "typing" } ``` -Eye detail below for `eyes_style=classic` (default). With `eyes_style=cover`, the same sequences drive full-half bars ([Cover eyes](#cover-eyes)). With `eyes_style=dots`, the same sequences drive 12×12 circles ([Dots eyes](#dots-eyes)). With `eyes_style=kaomoji`, faces follow [Kaomoji eyes](#kaomoji-eyes) instead of procedural blinks, glances, flicker, or X eyes. Servo/audio behavior is the same for every style. +Eye detail below for `eyes_style=classic` (default). With `eyes_style=cover`, the same sequences drive full-half bars ([Cover eyes](#cover-eyes)). With `eyes_style=dots`, the same sequences drive 12×12 circles ([Dots eyes](#dots-eyes)). With `eyes_style=kawaii`, the same sequences move and blink a kawaii face whose expression follows the animation and whose mouth says the voice clips ([Kawaii eyes](#kawaii-eyes)). With `eyes_style=kaomoji`, faces follow [Kaomoji eyes](#kaomoji-eyes) instead of procedural blinks, glances, flicker, or X eyes. Servo/audio behavior is the same for every style. Durations and quoted lines below are the stock clips in [`assets/`](../assets/). A filesystem built with `custom_audio_mod` can replace some of those WAVs. Phrase timing then follows that clip's `.cue` file on LittleFS (`/welcome.cue` and the same pattern for `attention`, `error`, `abort`, and `dead`). See [flash.md](flash.md). @@ -628,9 +628,9 @@ Durations and quoted lines below are the stock clips in [`assets/`](../assets/). | `attention` | Friendly input-request gesture synced to `attention.wav` (~3.0 s, "pst... human.... you might want to take a look"). Moves into a calm prompt pose first (centered body/neck, head slightly up, right hand raised partway), waits until all servos stop, then plays audio with light neck/head/hand motion during playback (whisper hold → lean toward user → glance/point on "take a look"). **Classic eyes:** phased blink/look cues during audio. After audio ends (or if audio fails to start), holds a gentle waiting loop for **1 minute** (soft head/neck drifts plus occasional slight right-hand waves), then returns to `none`. Requires `attention.wav` on LittleFS (same `uploadfs` flow as `bell.wav`). | | `error` | Critical task-obstacle gesture synced to `error.wav` (~2.2 s, "Uh-oh. Human, we have a problem."). Moves into an obstacle-presenting pose first (body/neck angled toward the task, head concerned/down, right hand presenting the blocker, left hand indicating task area), waits until the pose settles, then plays audio with small nervous head/neck glances during playback. After audio ends (or if audio fails to start), holds a subtle blocked loop for **1 minute**, then returns to `none`. Requires `error.wav` on LittleFS (same `uploadfs` flow as `bell.wav`). | | `abort` | **One-shot** resigned abort gesture synced to `abort.wav` (~2.5 s, "Fine. I didn't want to finish it anyway."). Raises both hands, lifts the head, and twists the neck sideways before audio starts. During playback it shrugs, dips the head, and adds a dismissive side twist. **Classic eyes:** matching glances/squints. Requires `abort.wav` on LittleFS (same `uploadfs` flow as `bell.wav`). After completion, returns to `none` pose and `GET /anim` reports `none`. | -| `dead` | **Hold.** Out-of-power: same obstacle pose as `error`, then `dead.wav` (~3.4 s, "Insufficient resources, shutting doooooowwwwnnnn..."). **Classic eyes:** failing-display flicker (irregular heights + brief blank pulses, denser near the end of the first line); at ~1.7 s ("shutting down") eyes squeeze nearly shut (~300 ms) while head/hands collapse over **~500 ms**, hold shut briefly (~200 ms), then snap to **X X** while the drawn-out shutdown still plays. If audio fails to start, collapse immediately. Stays with X eyes and pulsing red until another animation is requested. **Cover:** same flicker and squeeze as height changes, then both halves stay black (no X). **Dots:** same flicker and squeeze as circle size, then X marks in 12×12 boxes. **Kaomoji:** Sad face (no X). Does not auto-return to `none`. Requires `dead.wav` on LittleFS. | +| `dead` | **Hold.** Out-of-power: same obstacle pose as `error`, then `dead.wav` (~3.4 s, "Insufficient resources, shutting doooooowwwwnnnn..."). **Classic eyes:** failing-display flicker (irregular heights + brief blank pulses, denser near the end of the first line); at ~1.7 s ("shutting down") eyes squeeze nearly shut (~300 ms) while head/hands collapse over **~500 ms**, hold shut briefly (~200 ms), then snap to **X X** while the drawn-out shutdown still plays. If audio fails to start, collapse immediately. Stays with X eyes and pulsing red until another animation is requested. **Cover:** same flicker and squeeze as height changes, then both halves stay black (no X). **Dots:** same flicker and squeeze as circle size, then X marks in 12×12 boxes. **Kaomoji:** Sad face (no X). **Kawaii:** Sad face, then `x x` eyes during the X hold. Does not auto-return to `none`. Requires `dead.wav` on LittleFS. | | `wakeup` | **One-shot** sleep-inertia wake (~5.5 s + settle), same sequence as boot `loading=sleep_inertia`. Plays only while asleep or entering sleep (`sleep` nod-off / OLED-off sleep). If already awake (or mid eye-open), request is a no-op: current animation stays, a pending `sleep` is cancelled, and the idle sleep timer resets; HTTP still returns success. **Classic eyes:** open over 2 s (cubic ease) from closed, two blinks at 2.4 s and 3.8 s. Head rises from chin-down with a fading neck wave. Always moves head/neck/hands when it plays (API path). After completion, `GET /anim` reports `none`. Does not play welcome audio — use `welcome` for that. | -| `sleep` | **One-shot** nod-off (~2 s). Lids droop toward nearly shut (0–0.7 s) while the head barely moves, then a small resist: lids ease back toward half open as the head starts down (0.7–1.1 s). Lids then shut and the head eases to chin-down (`SLEEP_HEAD_DOWN`, same pose `wakeup` starts from) by 2.0 s. OLED blanks when the lids hit shut (`DISPLAYOFF`). **Classic, cover, dots:** that lid curve. **Kaomoji:** Sleep face during the close window, then blank. Same path as the idle `sleep_timeout`. Holds `sleep` until the head settles; then `GET /anim` reports `none` while the device stays asleep until another non-`sleep`/`none` animation wakes it. After the sleep pose is still for 2 s, PWM is full-off (same limp as `none`). | +| `sleep` | **One-shot** nod-off (~2 s). Lids droop toward nearly shut (0–0.7 s) while the head barely moves, then a small resist: lids ease back toward half open as the head starts down (0.7–1.1 s). Lids then shut and the head eases to chin-down (`SLEEP_HEAD_DOWN`, same pose `wakeup` starts from) by 2.0 s. OLED blanks when the lids hit shut (`DISPLAYOFF`). **Classic, cover, dots, kawaii:** that lid curve. **Kaomoji:** Sleep face during the close window, then blank. Same path as the idle `sleep_timeout`. Holds `sleep` until the head settles; then `GET /anim` reports `none` while the device stays asleep until another non-`sleep`/`none` animation wakes it. After the sleep pose is still for 2 s, PWM is full-off (same limp as `none`). | #### Kaomoji eyes @@ -658,6 +658,28 @@ When `eyes_style=cover`, each eye is a solid white rectangle filling one half of When `eyes_style=dots`, each eye is a filled circle. At the classic open height the circle’s bounding box is 12×12 px, centered on the classic eye. Diameter scales with rendered height (`12 * height / 14`), so blinks, squints, wide looks, and the `dead` flicker shrink or grow the dots. Height 0 draws nothing (full blink or sleep close). Glance, scan, and look-up/down move the circle with the classic center. The `dead` X hold draws X marks in 12×12 boxes at those centers. Diameter is capped at the 32 px panel height. +#### Kawaii eyes + +When `eyes_style=kawaii`, each eye is a round eye about 23 px across with a big dark pupil and white catch-lights in it (one round light and two small dots). A small mouth sits between the eyes, with dithered blush under the outer corners. The classic pose still drives position, height, glances, and blinks, and the pupils look where its glances point: at the task or the human, up while thinking. Two animations lead the eyes themselves: `typing` reads code instead of following the typing jitter, and `ring` keeps the eyes full size instead of the classic small circles. Moods change pupil size (small when surprised or angry, large when sad). A pupil otherwise keeps its size: lids, smiles, and blinks cover it like eyelids, and a white rim always stays around it. A closed eye draws a `‿` lid line (`∩` while smiling). Each animation picks a mood, and the face eases into it. Eye size, happy crescents, and mouth opening use springs with a little overshoot. Shape changes that cannot morph (round eyes to `> <`, `x x`, or hearts) happen behind a quick blink. + +While `welcome`, `attention`, `error`, `abort`, or `dead` plays its stock clip, the mouth says the words in sync (quoted below), closing on p, b, m, t, d, and k. A custom clip with its own `.cue` file says something else, so the mouth babbles through it instead. + +| Animation / phase | Mood | +| --- | --- | +| `none` (idle) | Mostly a `ω` or `‿` smile. Every 4.5–10 s, a short accent: `^ ^` grin, a wink, excited (bigger eyes, hop, twinkles, open grin), or rarely heart eyes | +| `typing` | Mostly focused: lids slightly lowered, short mouth. The eyes read code: a few lines word by word, then a dart to another spot, and again. Now and then a pleased smile, a quick `^ ^` grin, or a wink; these come more often the longer it has been since an `error`, `abort`, or `dead` (most often after about 90 s) | +| `reading` | Mostly lids barely lowered, small `ω`. Now and then a pleased, happy read, an "ooh" (`o` mouth, wider eyes), or a grin; more often while work goes well | +| `thinking` | Mostly lids slightly lowered, wobbly mouth off to one side. Now and then an "aha!": eyes widen and look up, star glints, a little hop, open smile; then back to thinking | +| `ring` | A celebration, keyed to the bell's ding. Wind-up: a deep breath that deepens until the strike (the face rises, eyes widen, pupils tighten, cheeks flush, the mouth draws in a big `o`). The ding: an excited yell (eyes pop, huge open mouth) and stars burst from the outer sides of the eyes, swirling off-screen with trails that shorten as the bell fades. Only the pupils shake, with the bell's own loudness, from the strike to the last of the ring (about 1.4 s). Then a dreamy afterglow (half-closed happy eyes, `ω`). Without a bell clip the ding comes after 1.5 s | +| `welcome` | Excited; says "Hello, human. What are we building today?" | +| `attention` | Curious: slightly wide eyes, small `o`; says "Psst... human... you might want to take a look." | +| `error` | Angry: lids tilted down at the inner corners, frown; says "Uh-oh. Human, we have a problem." | +| `abort` | Panic: `> <` eyes, wavy mouth; says "Fine. I didn't want to finish it anyway." | +| `wakeup` | Sleepy: heavy lids, yawn | +| `talking` | The mouth talks in syllables, shaped as `ah` (tall), `ee` (wide), or `o` (round). With `/play` audio it opens with the speech loudness and changes shape on each syllable onset. Without audio it babbles in short phrases with pauses | +| `sleep` / sleep-close | Lids close, small `ω` | +| `dead` | Sad (lids tilted down at the outer corners, frown), then `x x` eyes during the X hold. Says "Insufficient resources... shutting doooowwwnnn" | + Wrong params return **400**: | `error` | When | diff --git a/docs/hardware/testing.md b/docs/hardware/testing.md index c8eae7cc..e820ebf1 100644 --- a/docs/hardware/testing.md +++ b/docs/hardware/testing.md @@ -53,7 +53,7 @@ code remains the no-cable signal. 4. `Checking OLED at 0x3C...` → found or `ERROR: OLED not found` (continues) 5. Settings load from NVS (`loading` = `progress` or `sleep_inertia`) 6. **Progress loading (default):** OLED progress steps (Display → WiFi → Servos → Audio → Storage → Ready), then large full-width IP (or `No IP`) for 3 s, then idle eyes -7. **Sleep inertia loading:** wakeup frame 0 during init (classic: closed lids; cover: black halves; kaomoji: Sleepy; dots: no circles). Smooth move to sleep pose if `welcome` is on. After init, wake plays from t=0: slow eye open + blinks (~5.5 s). Head/neck wave only if `welcome` is on; otherwise eyes only +7. **Sleep inertia loading:** wakeup frame 0 during init (classic: closed lids; cover: black halves; kaomoji: Sleepy; dots: no circles; kawaii: `‿` lids with a yawn). Smooth move to sleep pose if `welcome` is on. After init, wake plays from t=0: slow eye open + blinks (~5.5 s). Head/neck wave only if `welcome` is on; otherwise eyes only 8. `WIFI SETUP` on serial — connect OK + IP, open setup AP, or saved credentials failed (setup AP for reconfiguration) 9. `Starting MAX98357A` → `I2S OK` 10. `Centering servos` — smooth move to per-channel mid (progress path only; skipped if sleep pose already applied) diff --git a/platformio.ini b/platformio.ini index 6571439d..d2316dc6 100644 --- a/platformio.ini +++ b/platformio.ini @@ -74,6 +74,15 @@ build_src_filter = + + + + + + + + + + + + + + + + + + + + + +