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
28 changes: 24 additions & 4 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` (sparkly round eyes with a little 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 ([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 @@ -630,7 +630,7 @@ Durations and quoted lines below are the stock clips in [`assets/`](../assets/).
| `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. |
| `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,26 @@ 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. It has two sparkle highlights, a small mouth between the eyes, and dithered blush under the outer corners. The classic pose still drives position, height, glances, and blinks. 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.

| 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` | Focused: lids slightly lowered, short mouth |
| `reading` | Lids barely lowered, small `ω` |
| `thinking` | Lids slightly lowered, wobbly mouth off to one side |
| `ring` | Surprised: wide eyes, `o` mouth |
| `welcome` | Excited |
| `attention` | Curious: slightly wide eyes, small `o` |
| `error` | Angry: lids tilted down at the inner corners, frown |
| `abort` | Panic: `> <` eyes, wavy mouth |
| `wakeup` | Sleepy: heavy lids, yawn |
| `talking` | Smile; mouth opens with speech loudness from `/play` |
| `sleep` / sleep-close | Lids close, small `ω` |
| `dead` | Sad (lids tilted down at the outer corners, frown), then `x x` eyes during the X hold |

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
2 changes: 2 additions & 0 deletions platformio.ini
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,8 @@ 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/mood.cpp>
+<audio/wav_parser.cpp>
+<audio/audio_motion.cpp>
+<serial/frame.cpp>
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` | Sparkly round eyes, little mouth, blush; moods ease per animation, idle mixes smiles with winks and excitement ([`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
138 changes: 138 additions & 0 deletions src/display/eyes/styles/kawaii.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
#include "display/eyes/styles/eye_style.h"

#include <Adafruit_SSD1306.h>

#include "animation/dead.h"
#include "animation/util.h"
#include "audio/audio_motion.h"
#include "display/eyes/core/blink.h"
#include "display/eyes/core/constants.h"
#include "display/eyes/styles/kawaii/face.h"
#include "display/eyes/styles/kawaii/mood.h"
#include "display/oled.h"
#include "display/oled_internal.h"

namespace {

// A longer gap means the style was just selected or the eyes restarted:
// jump straight to the mood instead of easing from a stale face.
constexpr uint32_t kSnapAfterGapMs = 250;

uint8_t g_frame[kawaii::kFrameBytes];
kawaii::Animator g_animator;
kawaii::IdleDirector g_idle(anim::randRangeMs);
uint32_t g_lastFrameMs = 0;
bool g_armed = false;
bool g_wasIdle = false;

kawaii::Mood modeMood(EyeMode mode) {
switch (mode) {
case EyeMode::Idle:
return kawaii::Mood::Content;
case EyeMode::Typing:
return kawaii::Mood::Focused;
case EyeMode::Reading:
return kawaii::Mood::Reading;
case EyeMode::Thinking:
return kawaii::Mood::Thinking;
case EyeMode::Ring:
return kawaii::Mood::Surprised;
case EyeMode::Welcome:
return kawaii::Mood::Excited;
case EyeMode::Attention:
return kawaii::Mood::Curious;
case EyeMode::Error:
return kawaii::Mood::Angry;
case EyeMode::Abort:
return kawaii::Mood::Panic;
case EyeMode::Wakeup:
return kawaii::Mood::Sleepy;
case EyeMode::Dead:
return deadShowingX() ? kawaii::Mood::Dizzy : kawaii::Mood::Sad;
case EyeMode::Talking:
return kawaii::Mood::Talking;
}

return kawaii::Mood::Content;
}

kawaii::EyePose eyePose(const Eye& eye) {
return {
eye.x + eye.width * 0.5f,
eye.y + eye.height * 0.5f,
(float)eye.height / (float)eyes::DEFAULT_LEFT.height
};
}

void drawKawaii(
EyeMode mode,
AnimationId animation,
uint32_t /*modeStartedMs*/,
uint32_t now,
EyeStyleSleepPhase sleepPhase
) {
if (!oledAvailable) {
return;
}

const bool sleeping = sleepPhase == EyeStyleSleepPhase::Closing ||
animation == AnimationId::Sleep;
const bool idle = !sleeping && mode == EyeMode::Idle;

if (idle && !g_wasIdle) {
g_idle.reset(now);
}
g_wasIdle = idle;

kawaii::Mood mood = kawaii::Mood::Asleep;
if (!sleeping) {
mood = idle ? g_idle.update(now) : modeMood(mode);
}

kawaii::Expression target = kawaii::expressionFor(mood);
if (mood == kawaii::Mood::Talking) {
const AudioMotionSnapshot speech = audioMotionSnapshot(now);
kawaii::applySpeech(target, speech.level, speech.streamActive && speech.speaking);
}

const uint32_t gap = now - g_lastFrameMs;
if (!g_armed || gap > kSnapAfterGapMs) {
g_animator.snap(target);
g_armed = true;
} else {
g_animator.update(target, gap);
}
g_lastFrameMs = now;

const kawaii::Pose pose = {
eyePose(leftEye()),
eyePose(rightEye()),
blinkOpenAmount()
};

kawaii::Face face = {};
kawaii::composeFace(pose, g_animator, now, face);
if (!kawaii::render(face, g_frame, sizeof(g_frame))) {
return;
}

display.clearDisplay();
display.drawBitmap(
0,
0,
g_frame,
kawaii::kWidth,
kawaii::kHeight,
SSD1306_WHITE
);
display.display();
}

} // namespace

extern const EyeStyleRenderer kKawaiiEyeStyle = {
"kawaii",
true,
true,
drawKawaii,
};
Loading