Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 27 additions & 5 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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` |
Expand Down Expand Up @@ -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).

Expand All @@ -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

Expand Down Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/hardware/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
9 changes: 9 additions & 0 deletions platformio.ini
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,15 @@ build_src_filter =
+<actions/pattern.cpp>
+<actions/migrate.cpp>
+<display/eyes/styles/eye_style_ids.cpp>
+<display/eyes/styles/kawaii/face.cpp>
+<display/eyes/styles/kawaii/expression.cpp>
+<display/eyes/styles/kawaii/animator.cpp>
+<display/eyes/styles/kawaii/director.cpp>
+<display/eyes/styles/kawaii/speech.cpp>
+<display/eyes/styles/kawaii/compose.cpp>
+<display/eyes/styles/kawaii/tracker.cpp>
+<display/eyes/styles/kawaii/lines.cpp>
+<display/eyes/styles/kawaii/burst.cpp>
+<audio/wav_parser.cpp>
+<audio/audio_motion.cpp>
+<serial/frame.cpp>
Expand Down
25 changes: 15 additions & 10 deletions scripts/upload_fs_after_upload.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,17 +20,22 @@ def upload_filesystem(source, target, env):
# Build the argument vector ourselves instead of handing SCons a command
# string: SCons splits on whitespace, so a $PROJECT_DIR containing a space
# would arrive at PlatformIO as two separate arguments.
# Upload LittleFS to the same board the firmware just went to. The child
# PlatformIO run does not inherit --upload-port, and auto-detection picks
# the first serial port it finds when several devices are plugged in.
upload_port = env.subst("$UPLOAD_PORT")

def run_pio(pio_target):
subprocess.run(
[
env.subst("$PYTHONEXE"),
"-m", "platformio", "run",
"-t", pio_target,
"-e", env.subst("$PIOENV"),
"-d", str(project_dir),
],
check=True,
)
args = [
env.subst("$PYTHONEXE"),
"-m", "platformio", "run",
"-t", pio_target,
"-e", env.subst("$PIOENV"),
"-d", str(project_dir),
]
if upload_port and pio_target == "uploadfs":
args += ["--upload-port", upload_port]
subprocess.run(args, check=True)

try:
if not fs_image.is_file():
Expand Down
3 changes: 2 additions & 1 deletion src/display/eyes/modes/attention.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,9 @@ void updateAttentionEyes(uint32_t now) {
(float)halfBlink
: (float)(ATTENTION_AUDIO_BLINK_END_MS - audioElapsed) /
(float)halfBlink;
// blinkT runs 0 → 1 → 0 across the window: closed in the middle.
const float open = anim::easeInOutCubic(
constrain(blinkT, 0.0f, 1.0f)
constrain(1.0f - blinkT, 0.0f, 1.0f)
);
leftHeight = (int16_t)(2.0f + 14.0f * open);
rightHeight = leftHeight;
Expand Down
3 changes: 2 additions & 1 deletion src/display/eyes/modes/welcome.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,9 @@ void updateWelcomeEyes(uint32_t now) {
(float)halfBlink
: (float)(WELCOME_AUDIO_BLINK_END_MS - audioElapsed) /
(float)halfBlink;
// blinkT runs 0 → 1 → 0 across the window: closed in the middle.
const float open = anim::easeInOutCubic(
constrain(blinkT, 0.0f, 1.0f)
constrain(1.0f - blinkT, 0.0f, 1.0f)
);
leftHeight = (int16_t)(2.0f + 14.0f * open);
rightHeight = leftHeight;
Expand Down
1 change: 1 addition & 0 deletions src/display/eyes/styles/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ Extensible eye renderers selected by Config / `POST /settings` `{"eyes_style":"
| `kaomoji` | Animated faces from TinyEngineerExpressions |
| `cover` | Full-half bars for mods with a mask with eye holes; height changes via top and/or bottom black margins |
| `dots` | 12×12 filled circles; diameter tracks pose height, center tracks pose |
| `kawaii` | Round eyes with big moving pupils, a talking mouth, and blush. Each animation has its own mood (with occasional accents while idle, typing, reading, or thinking), the mouth says the stock voice clips in sync, and the bell gets a celebration ([`kawaii/`](kawaii/)) |

## Add a style

Expand Down
1 change: 1 addition & 0 deletions src/display/eyes/styles/eye_style_ids.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ constexpr const char* kEyeStyleIds[] = {
"kaomoji",
"cover",
"dots",
"kawaii",
};

} // namespace
Expand Down
Loading
Loading