diff --git a/docs/api.md b/docs/api.md index 628bfbe3..e9188f26 100644 --- a/docs/api.md +++ b/docs/api.md @@ -10,7 +10,7 @@ Optional auth: when an `access_token` is configured in settings, all JSON API ro When the robot is not yet provisioned (no connection mode chosen), control APIs (`/anim`, `/test/*`, `/play`) return **503** `{"ok":false,"error":"not provisioned"}`. Setup routes (`/`, `/config`, `/auth`, `/health`, `/settings`, `/setup/servo`, `/setup/led`, `/setup/audio`, `/setup/oled`, `/servos/park`) stay available on the setup AP. Connection mode is `wifi` or `usb` (`link_mode` in settings/auth/health). USB-only mode disables Wi‑Fi station and the HTTP API after reboot; control then uses the USB serial protocol ([serial.md](serial.md)). -If boot WiFi credentials are missing, the device opens setup AP mode (`TinyEngineer-XXXX`) and serves a five-step setup wizard at `/config` (servo hub: guided calibration / skip / assembly centering, then OLED orientation, RGB LED, speaker test, then connection). If saved credentials fail, it reopens setup AP mode. The setup AP acts as a captive portal: DHCP sends the portal URL (option 114) and DNS answers every name with the AP IP, so a phone that joins the network opens the wizard on its own. Hardware tests: [`docs/hardware/testing.md`](hardware/testing.md). How to wire this API into AI tools: [`integration.md`](integration.md). +If boot WiFi credentials are missing, the device opens setup AP mode (`TinyEngineer-XXXX`) and serves a six-step setup wizard at `/config` (servo hub: guided calibration / skip / assembly centering, then an optional "face me" pose, then OLED orientation, RGB LED, speaker test, then connection). If saved credentials fail, it reopens setup AP mode. The setup AP acts as a captive portal: DHCP sends the portal URL (option 114) and DNS answers every name with the AP IP, so a phone that joins the network opens the wizard on its own. Hardware tests: [`docs/hardware/testing.md`](hardware/testing.md). How to wire this API into AI tools: [`integration.md`](integration.md). Firmware answers mDNS A and AAAA (IPv6 link-local) so macOS does not wait 2–3s on a missing AAAA. If a client still pauses on the hostname, force IPv4 (`curl -4`). The IP on the OLED skips DNS entirely. @@ -187,6 +187,7 @@ curl http://tiny-engineer.local/settings "servo_maxs": [100, 100, 100, 100, 100], "rgb_order": "GRB", "oled_rotate_180": false, + "face_pose": [], "wifi_networks": ["MyNetwork", "Office"] } ``` @@ -216,11 +217,12 @@ curl http://tiny-engineer.local/settings | `servo_maxs` | Per-joint safe maximum degrees (stock defaults **100, 100, 100, 100, 100**). Each max must be greater than the matching min | | `rgb_order` | Onboard WS2812 wire-byte order (`RGB`, `RBG`, `GRB`, `GBR`, `BRG`, `BGR`). Default **`GRB`**. Survives factory reset | | `oled_rotate_180` | OLED 180° rotation (`true` → `setRotation(2)`). Default **`false`**. Setup AP only. Survives factory reset | +| `face_pose` | Optional "face me" pose `[head, neck, body]` in animation units (`-1` = saved min, `0` = mid, `1` = saved max) that points the robot at the user. `[]` = not set (default). When set, the `talking` animation rests and sways around it; when not set, the robot moves as before. Relative to the saved servo ranges, so check it again after a servo calibration. Cleared by factory reset. See [robot-movement.md](robot-movement.md#face-me) | | `reboot_required` | `true` once the saved `hostname`, `loading` or WiFi networks differ from what this boot started with; those apply only after a reboot | ### `POST /settings` -Update one or more settings from a JSON object body. Values are written to NVS. `sleep_timeout`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `lcd1602`, `lcd1602_backlight_sleep`, `lcd1602_welcome_hello`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`, `continuous_timeout`, `eyes_style`, and `access_token` apply immediately; a changed `hostname` or `loading` takes effect on the **next reboot**. WiFi networks are set with [`PUT /settings/wifi`](#put-settingswifi). On-device Actions are set with [`PUT /settings/actions`](#put-settingsactions). Servo ranges (`servo_mins` + `servo_maxs`), RGB LED mapping (`rgb_order`) and OLED rotation (`oled_rotate_180`) are **setup AP only** and apply immediately. Requires Bearer when auth is enabled. +Update one or more settings from a JSON object body. Values are written to NVS. `sleep_timeout`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `lcd1602`, `lcd1602_backlight_sleep`, `lcd1602_welcome_hello`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`, `continuous_timeout`, `eyes_style`, `access_token`, and `face_pose` apply immediately (`face_pose` from the next time `talking` starts); a changed `hostname` or `loading` takes effect on the **next reboot**. WiFi networks are set with [`PUT /settings/wifi`](#put-settingswifi). On-device Actions are set with [`PUT /settings/actions`](#put-settingsactions). Servo ranges (`servo_mins` + `servo_maxs`), RGB LED mapping (`rgb_order`) and OLED rotation (`oled_rotate_180`) are **setup AP only** and apply immediately. Requires Bearer when auth is enabled. ```bash curl -X POST "http://tiny-engineer.local/settings" \ @@ -232,6 +234,9 @@ curl -X POST "http://tiny-engineer.local/settings" \ curl -X POST "http://tiny-engineer.local/settings" \ -H "Content-Type: application/json" \ -d '{"access_token":""}' +curl -X POST "http://tiny-engineer.local/settings" \ + -H "Content-Type: application/json" \ + -d '{"face_pose":[0.15,-0.3,0.1]}' curl -X POST "http://192.168.4.1/settings" \ -H "Content-Type: application/json" \ -d '{"servo_mins":[80,80,80,80,80],"servo_maxs":[100,100,100,100,100],"rgb_order":"GRB","oled_rotate_180":true}' @@ -263,6 +268,7 @@ curl -X POST "http://192.168.4.1/settings" \ "servo_maxs": [100, 100, 100, 100, 100], "rgb_order": "GRB", "oled_rotate_180": false, + "face_pose": [0.15, -0.3, 0.1], "wifi_networks": ["MyNetwork"], "reboot_required": true } @@ -291,8 +297,9 @@ curl -X POST "http://192.168.4.1/settings" \ | `servo_maxs` | integer array | Five integers `0`–`180`; setup AP only; each value must be greater than the matching min | | `rgb_order` | string | `RGB`, `RBG`, `GRB`, `GBR`, `BRG`, or `BGR`; setup AP only; default `GRB` | | `oled_rotate_180` | boolean | Setup AP only; default `false` | +| `face_pose` | number array | Three numbers -1 to 1 (`head, neck, body`), or `[]` to clear; default `[]` (not set) | -Leave out a field to keep its saved value. An empty object → **400** `send at least one setting`. A field this route does not know → **400** `unknown field `. A field with the wrong type or out of range → **400** `invalid ` (servo ranges that overlap or exceed 180: `invalid servo_mins or servo_maxs`). Only one of `servo_mins` / `servo_maxs` → **400** `servo_mins and servo_maxs go together`. Enabling extensions (or changing their pins) so two enabled extensions would share a GPIO → **400** `pin conflict on GP… (…)` and nothing is saved. Outside setup AP mode, servo ranges → **400** `servo setup only in AP mode`, `rgb_order` → **400** `rgb setup only in AP mode`, `oled_rotate_180` → **400** `oled setup only in AP mode`. On any 400, nothing is saved. Replies carry `reboot_required` as in `GET /settings`. +Leave out a field to keep its saved value. An empty object → **400** `send at least one setting`. A field this route does not know → **400** `unknown field `. A field with the wrong type or out of range → **400** `invalid ` (servo ranges that overlap or exceed 180: `invalid servo_mins or servo_maxs`; a `face_pose` that is not `[]` or three numbers in -1..1: `invalid face_pose`). Only one of `servo_mins` / `servo_maxs` → **400** `servo_mins and servo_maxs go together`. Enabling extensions (or changing their pins) so two enabled extensions would share a GPIO → **400** `pin conflict on GP… (…)` and nothing is saved. Outside setup AP mode, servo ranges → **400** `servo setup only in AP mode`, `rgb_order` → **400** `rgb setup only in AP mode`, `oled_rotate_180` → **400** `oled setup only in AP mode`. On any 400, nothing is saved. Replies carry `reboot_required` as in `GET /settings`. ### `PUT /settings/wifi` @@ -359,7 +366,7 @@ curl -X POST "http://tiny-engineer.local/actions/test" \ ### `POST /settings/reset` -Factory reset: clears the NVS `te` namespace and restores settings to compile-time defaults and clears every saved WiFi network and Actions list. **Servo min/max, RGB LED mapping (`rgb_order`), and OLED rotation (`oled_rotate_180`) are kept.** Internal last-pose blob (`spose`) is cleared/reset with defaults. After reset, power-cycle (or press reset) so the device reopens setup AP mode and WiFi can be configured again; the servo, screen, and LED steps are pre-filled with the saved values and can be retuned. Until reboot, credentials are cleared in NVS but the radio may still be on the previous STA network. No body. Requires Bearer when auth is enabled. Same JSON shape as `GET /settings`. +Factory reset: clears the NVS `te` namespace and restores settings to compile-time defaults and clears every saved WiFi network and Actions list. **Servo min/max, RGB LED mapping (`rgb_order`), and OLED rotation (`oled_rotate_180`) are kept.** The face pose (`face_pose`) is cleared. Internal last-pose blob (`spose`) is cleared/reset with defaults. After reset, power-cycle (or press reset) so the device reopens setup AP mode and WiFi can be configured again; the servo, screen, and LED steps are pre-filled with the saved values and can be retuned. Until reboot, credentials are cleared in NVS but the radio may still be on the previous STA network. No body. Requires Bearer when auth is enabled. Same JSON shape as `GET /settings`. The Config web UI clears the browser-stored Bearer token and shows a one-shot gate: power-cycle the device, then join the robot WiFi shown on the OLED and open the setup wizard. It does not poll for reconnect. @@ -392,6 +399,7 @@ curl -X POST "http://tiny-engineer.local/settings/reset" "servo_maxs": [100, 100, 100, 100, 100], "rgb_order": "GRB", "oled_rotate_180": false, + "face_pose": [], "wifi_networks": [], "reboot_required": true } diff --git a/docs/hardware/testing.md b/docs/hardware/testing.md index 46309e1f..388341bc 100644 --- a/docs/hardware/testing.md +++ b/docs/hardware/testing.md @@ -112,13 +112,13 @@ curl -X POST "http://tiny-engineer.local/test/servo" -H "Content-Type: applicati | `GET` | `/health` | Health JSON — full field list in [api.md](../api.md#get-health) | | `GET` / `POST` | `/anim` | Current animation / start one (`name`, optional `interrupt`) — full params in [api.md](../api.md#post-anim) | | `POST` | `/play` | Stream a WAV while `talking` (or `/play/{name}`) runs; answers when the clip ends — full params in [api.md](../api.md#post-play) | -| `GET` | `/settings` | Persistent settings (`sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `lcd1602`, `lcd1602_backlight_sleep`, `lcd1602_welcome_hello`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`, `continuous_timeout`, `loading`, `eyes_style`, `access_token_set`, `wifi_configured`, `servo_mins`, `servo_maxs`, `rgb_order`, `oled_rotate_180`, `wifi_networks`) | +| `GET` | `/settings` | Persistent settings (`sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `lcd1602`, `lcd1602_backlight_sleep`, `lcd1602_welcome_hello`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`, `continuous_timeout`, `loading`, `eyes_style`, `access_token_set`, `wifi_configured`, `servo_mins`, `servo_maxs`, `rgb_order`, `oled_rotate_180`, `face_pose`, `wifi_networks`) | | `GET` / `POST` / `DELETE` | `/extensions/lcd1602/text` | LCD 1602 text (extension off → 503) | | `GET` / `POST` | `/extensions/lcd1602/brightness` | LCD 1602 backlight 0–100 | | `GET` / `POST` | `/extensions/lcd1602/color` | LCD 1602 RGB base color (PCA9633 only) | | `GET` / `PUT` | `/settings/actions` | On-device Actions list (event patterns → sound / anim) | | `POST` | `/actions/test` | Simulate an event type for Actions (no outbound publish) | -| `POST` | `/settings` | Update NVS settings from a JSON object; the reply carries `reboot_required`, true once `hostname`, `loading` or the WiFi networks differ from what the robot booted with. `servo_mins` / `servo_maxs` (integer arrays), `rgb_order` and `oled_rotate_180` (boolean) are setup-AP-only | +| `POST` | `/settings` | Update NVS settings from a JSON object; the reply carries `reboot_required`, true once `hostname`, `loading` or the WiFi networks differ from what the robot booted with. `servo_mins` / `servo_maxs` (integer arrays), `rgb_order` and `oled_rotate_180` (boolean) are setup-AP-only. `face_pose` (`[head, neck, body]` in -1..1, `[]` clears) works in both modes | | `PUT` | `/settings/wifi` | Replace the saved WiFi networks (JSON array of 1 to 5); first one tested in setup AP mode | | `POST` | `/settings/reset` | Factory reset settings to defaults (clears WiFi, keeps servo ranges, RGB mapping, and screen rotation); power-cycle to reopen setup AP | | `POST` | `/servos/park` | Center all servos at mid, flush pose NVS, hold PWM until reboot | diff --git a/docs/robot-movement.md b/docs/robot-movement.md index c6971adb..203a24a7 100644 --- a/docs/robot-movement.md +++ b/docs/robot-movement.md @@ -16,6 +16,14 @@ Animations author poses in **−1..1** relative to each joint’s saved min/max **Head** tilts the face toward or away from the laptop. **Neck** pans the head side to side. **Hands** lift and lower over the keyboard; the forearms have no elbow servo — the arm linkage is fixed, so only the hand joint moves. **Left** and **right** hand servos use opposite scales: on the left, higher angle is down; on the right, higher angle is up (rest pose for typing is left at `max`, right at `min` — both over the keyboard). Setup AP guided calibration sets those keyboard bounds first, then the upper bounds. **Body** rotates the whole upper body in the chair while the base stays put. +## Face me + +Each desk is different, so the robot does not know where the user sits. The optional **face me** pose stores the head, neck and body pose that looks at the user, in the same −1..1 units as the animations. Set it on the web UI **Servo** page (section **Face me**), in the optional **Face me** step of the setup wizard, or with `POST /settings` `{"face_pose":[head, neck, body]}` ([api.md](api.md#post-settings)). Send `[]` to clear it. + +When it is set, `talking` rests on that pose and nods, drifts and sways around it. Other animations do not use it yet. When it is not set, `talking` rests at head `1/7`, neck `0`, body `0`, as before. The pose is relative to the saved servo min/max, so check it again after a servo calibration. Factory reset clears it. + +## Bench checks + Command a single joint for bench checks: ```bash diff --git a/docs/settings.md b/docs/settings.md index af15ef3f..6e8a9777 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -2,9 +2,9 @@ Persistent settings live in NVS (namespace `te`) under [`src/settings/`](../src/settings/). They are exposed on `GET`/`POST /settings`, the Config web UI, and must stay in sync with API docs. -**HTTP / JSON** (`POST /settings` body and `GET /settings` fields — see [api.md](api.md)): `sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `lcd1602`, `lcd1602_backlight_sleep`, `lcd1602_welcome_hello`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`, `continuous_timeout`, `loading`, `eyes_style`, `access_token`, `servo_mins` / `servo_maxs`, `rgb_order`, `oled_rotate_180`. WiFi networks have their own endpoint, `PUT /settings/wifi`, and show as `wifi_networks`. On-device Actions use `GET`/`PUT /settings/actions`. +**HTTP / JSON** (`POST /settings` body and `GET /settings` fields — see [api.md](api.md)): `sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `lcd1602`, `lcd1602_backlight_sleep`, `lcd1602_welcome_hello`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`, `continuous_timeout`, `loading`, `eyes_style`, `access_token`, `servo_mins` / `servo_maxs`, `rgb_order`, `oled_rotate_180`, `face_pose`. WiFi networks have their own endpoint, `PUT /settings/wifi`, and show as `wifi_networks`. On-device Actions use `GET`/`PUT /settings/actions`. -**NVS keys** (≤15 chars; defined in [`nvs.h`](../src/settings/nvs.h)): `sleep_m`, `host`, `vol`, `welcome`, `serial_log`, `ext_btn` (`push_button`), `ext_btn_pin` (`push_button_pin`), `ext_lcd` (`lcd1602`), `ext_lcd_bl` (`lcd1602_backlight_sleep`), `ext_lcd_hi` (`lcd1602_welcome_hello`), `ext_lcd_boot`, `ext_lcd_l1`, `ext_lcd_l2`, `ext_lcd_last` (LCD last-state blob; not a settings API field), `cont_to`, `loading`, `eyes_sty`, `access_tok`, `wifi_nets` (blob of up to 5 networks; replaces the older single-network `wifi_ssid` / `wifi_pass`, which are migrated on load), `actions` (Actions blob, up to 16 rows), `sranges`, `rgb_ord`, `oled_rot`. Last commanded servo angles live in the same namespace as key `spose` (internal; not a settings API field). Boot migrates legacy `btn_snd_*` keys into Actions then removes them, and drops leftover `srv_hold`. Add new short keys there — do not reuse HTTP names as NVS keys unless they already fit the length limit. +**NVS keys** (≤15 chars; defined in [`nvs.h`](../src/settings/nvs.h)): `sleep_m`, `host`, `vol`, `welcome`, `serial_log`, `ext_btn` (`push_button`), `ext_btn_pin` (`push_button_pin`), `ext_lcd` (`lcd1602`), `ext_lcd_bl` (`lcd1602_backlight_sleep`), `ext_lcd_hi` (`lcd1602_welcome_hello`), `ext_lcd_boot`, `ext_lcd_l1`, `ext_lcd_l2`, `ext_lcd_last` (LCD last-state blob; not a settings API field), `cont_to`, `loading`, `eyes_sty`, `access_tok`, `wifi_nets` (blob of up to 5 networks; replaces the older single-network `wifi_ssid` / `wifi_pass`, which are migrated on load), `actions` (Actions blob, up to 16 rows), `sranges`, `rgb_ord`, `oled_rot`, `face_pose` (blob of three floats; no key = not set). Last commanded servo angles live in the same namespace as key `spose` (internal; not a settings API field). Boot migrates legacy `btn_snd_*` keys into Actions then removes them, and drops leftover `srv_hold`. Add new short keys there — do not reuse HTTP names as NVS keys unless they already fit the length limit. Follow the same pattern for a new setting. @@ -78,7 +78,7 @@ Flash only when you want to try it on hardware (`pio run -t upload`). ## Pitfalls - **Partial writes:** validate first; never write NVS then fail validation mid-way. -- **Factory reset:** `factoryResetSettings()` in [`nvs.cpp`](../src/settings/nvs.cpp) clears NVS namespace `te` and writes defaults, which clears every saved WiFi network. Servo min/max (`sranges`), RGB LED mapping (`rgb_ord`), and OLED rotation (`oled_rot`) are written back unchanged. Internal pose blob (`spose`) is not rewritten (next boot uses mid). Exposed as `POST /settings/reset`. After reset, power-cycle into setup AP mode to configure WiFi again. Servo ranges, LED mapping, and screen rotation can be retuned in that wizard. +- **Factory reset:** `factoryResetSettings()` in [`nvs.cpp`](../src/settings/nvs.cpp) clears NVS namespace `te` and writes defaults, which clears every saved WiFi network. Servo min/max (`sranges`), RGB LED mapping (`rgb_ord`), and OLED rotation (`oled_rot`) are written back unchanged. The face pose (`face_pose`) is not: it belongs to the desk setup, so reset clears it. Internal pose blob (`spose`) is not rewritten (next boot uses mid). Exposed as `POST /settings/reset`. After reset, power-cycle into setup AP mode to configure WiFi again. Servo ranges, LED mapping, and screen rotation can be retuned in that wizard. - **Hostname-style settings:** freeze the boot value separately if live change cannot apply (see `g_bootSettings` and `settingsRebootRequired()`). - **UI size:** the panel is embedded gzipped in the firmware; keep controls compact. - **Doc drift:** HTML param tables must match `api.md` exactly. diff --git a/openspec/changes/face-me/.openspec.yaml b/openspec/changes/face-me/.openspec.yaml new file mode 100644 index 00000000..41484f31 --- /dev/null +++ b/openspec/changes/face-me/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-18 diff --git a/openspec/changes/face-me/design.md b/openspec/changes/face-me/design.md new file mode 100644 index 00000000..174c0ae8 --- /dev/null +++ b/openspec/changes/face-me/design.md @@ -0,0 +1,66 @@ +# Design + +## Context + +- Animations author poses in −1..1 relative to each joint's saved min/max and map them with `servoNormToDeg` (`src/hardware/servo_wrapper.cpp`). Saved ranges (`sranges`) are setup-AP-only. +- Talking (`src/animation/talking.cpp`) rests at `TALKING_HEAD_MID` (1/7), neck 0 and body 0. Neck drift is `±TALKING_NECK_SWAY` around 0. Body sway is `±TALKING_BODY_SWAY` around 0, biased opposite the neck. `startTalking()` calls `parkNonePose()`, which moves neck and body to 0. +- Settings follow the layer checklist in `docs/settings.md`: `SettingsValues`, `SettingsPatch` with `std::optional` fields, NVS keys in `nvs.h`, `readPatch()` / `settingsJson()` in `src/http/settings_handlers.cpp`. `SettingsPatch::setupOnlyStep()` lists setup-AP-only fields. +- `/test/servo` (Configured) moves one joint in degrees inside the saved range. `/setup/servo` (Setup) does slow 0–180° moves in setup AP mode. `/anim` is Configured, so it is not available in setup AP mode. +- Each web UI page needs its own `handleIndex` entry in `kRoutes` (`src/http/routes.cpp`). + +## Goals / Non-Goals + +**Goals:** +- Zero behavior change when `face_pose` is not set. +- One small helper that animations call to get the face pose, so later animations can adopt it with a one-line change. + +**Non-Goals:** +- Welcome, attention and other animations (later changes). +- Serial `settings.get` / `settings.set` and CLI support for `face_pose`. +- Changing the transition park: between animations, neck and body still park at 0. +- Auto-adjusting the pose after a servo range recalibration. + +## Decisions + +### D1. Storage: three floats plus a "set" flag, one NVS blob +`SettingsValues` gets `bool facePoseSet` and `float facePose[3]` (head, neck, body). NVS key `face_pose` (9 chars) holds a 12-byte blob of three floats; no key means not set. Clearing removes the key. +- *Alternative:* three `int8` values in hundredths. Smaller, but adds a scale factor in API, UI and firmware for no real gain. +- *Alternative:* NaN as "not set". Fragile with JSON and comparisons. + +### D2. API shape: array, `[]` clears +`GET` returns `[h, n, b]` or `[]`. `POST` takes three numbers or `[]`. `null` stays a wrong type, matching the existing `readPatch()` rule "an explicit null is a wrong type". The patch type is `std::optional`, where `FacePose` has `set` and `values[3]`. Validation lives in `FacePose::valid()` (same pattern as `ServoRanges::valid()`) and runs in `SettingsPatch::invalidField()`, so the whole patch is rejected before any NVS write. `face_pose` is not added to `setupOnlyStep()`. The `known[]` array in `readPatch()` grows by one. +- *Alternative:* separate `face_pose_set` boolean. Two fields that must agree; more checks. + +### D3. Normalized units (user choice) +The pose uses the same −1..1 units as animations, so talking adds offsets with no conversion. The trade-off (direction shift after recalibration) is handled in the UI text (see Risks). + +### D4. Helper: `anim::facePose()` +In `src/animation/util.*`: `struct FacePose { float head, neck, body; }` and `FacePose facePose()`. It returns the saved pose, or `{TALKING_HEAD_MID, 0, 0}` when not set. The fallback is the current talking rest pose, which gives the goal "zero change". Targets with offsets go through the existing `servoSaturateNorm()` (`include/servos.h`), which limits them to −1..1; no new clamp helper. + +### D5. Talking changes +- `startTalking()`: after `parkNonePose()`, set head, neck and body targets to the face pose (when not set, the targets equal today's: head 1/7, neck 0, body 0). +- `TALKING_HEAD_MID` uses → `facePose().head`. Nod and level offsets stay the same and are clamped. +- `commandNeckDrift()`: `face.neck + TALKING_NECK_SWAY * u`, clamped. +- `commandBodyDrift()`: `face.body + TALKING_BODY_SWAY * u`, clamped. The opposite-neck bias compares the neck to `face.neck`, not to 0. +- `settleReactivePose()`: body returns to `face.body`. +Read `facePose()` once per `startTalking()` and keep it in a file-local variable, so a mid-animation save does not jump the pose. A new save applies the next time talking starts (spec: "without reboot"). + +### D6. Web UI: section on the Servo control page +A `FacePoseSection` component on `ServoControl.tsx` (`/servo`), so no new route in `kRoutes`. A shared `FacePoseControls` component: a joint picker (Head / Neck / Body, each showing its angle), a large angle readout in whole degrees, a bar that spans the joint's saved min..max with a marker at the current angle, and ±1° / ±5° nudge buttons (the guided calibration buttons without ±10°: the face range is narrow). A nudge adds degrees to the rounded current angle, limits it to the saved range, moves the joint at once, and stores the result back in −1..1 units (`normToDeg` / `degToNorm` in `ui/src/servos.ts`, the same mapping as the firmware). A failed move restores the previous value. The section has extra top margin so it does not touch the move form above it. +- *Replaced:* −1..1 sliders (first version), then ±10° buttons and decimal angles with no range bar (second version). The user found both not precise or clear enough on the robot. Buttons: Save, Clear (with confirm), Preview (`POST /anim` `name=talking`). The section shows "Set" or "Not set" and the recalibration note. + +### D7. Wizard step +`STEPS` gets `{ id: "face", title: "Face me" }` after `servos`. The step reuses the three controls in a shared component, moves joints with `useSetupServo` (`/setup/servo`, degrees from the ranges just saved by the servos step). Footer: Skip (advances, sends nothing) and "Save and continue" (POST `face_pose`, then advance). No preview, because `/anim` is not available in setup AP mode. + +## Risks / Trade-offs + +- [Servo range recalibration shifts the physical direction] → UI note on the Face me section and on the wizard step; the face pose stays valid (still inside −1..1), only the direction can change. +- [Face neck near ±1 makes drift hit the limit and look stuck on one side] → clamp keeps it safe; acceptable for v1, users can pick a pose away from the limit. +- [Moving joints from the UI while an animation runs] → `/test/servo` already handles that case for the Servo control page; same behavior. +- [Transition into reading turned the neck too slowly] A transition does not wait for the neck to park, so after talking with a face pose the neck can start far from mid. Reading turned it at its slow 8–16°/s scan speed. → The first reading neck turn now uses the typing sway speed (12–30°/s, shared constants in `constants.h`); later turns keep the scan speed. Found during the robot test. +- [Turn to the face pose was too slow when talking started] `startTalking()` aimed neck and body at the face pose, but the first neck drift (after 0.5–1.1 s, 8–16°/s) and body sway or reactive settle (10–14°/s) replaced that target, so most of a long turn ran at drift speed. → Neck and body turn at `TALKING_FACE_ARRIVE_SPEED_DEG_S` (40°/s), and neck drift, body sway and the reactive body settle wait until both arrive. The same applies when a cancelled transition resumes talking. Second robot test: still slower than typing, because the head moved to the face pose at 25°/s and the reactive settle held it at 22°/s, while typing snaps the head at 0.85 × max speed. → The head now uses that same snap (`snapHeadToRangeHigh`), the arrival waits for head, neck and body, and the reactive head settle and emphasis nod also wait. Without a face pose this changes only the speed of the short turn to the rest pose, not any pose. +- [Upstream review: new field on a shared API] → additive field, empty by default; docs synced in the same change per CLAUDE.md. + +## Migration Plan + +No migration. Older firmware ignores the missing key; new firmware treats a missing key as not set. Rollback: flash the older firmware; the `face_pose` NVS key stays unused. diff --git a/openspec/changes/face-me/proposal.md b/openspec/changes/face-me/proposal.md new file mode 100644 index 00000000..5677061d --- /dev/null +++ b/openspec/changes/face-me/proposal.md @@ -0,0 +1,31 @@ +# Proposal + +## Why + +Users put the robot on their desk in different positions relative to where they sit. The talking animation "faces the user" with a fixed guess (neck mid, body mid, head slightly up), so on most desks the robot talks to an empty spot. A per-user "face me" pose lets each user point the robot at themselves once, and animations that address the user can use it. + +## What Changes + +- New optional setting `face_pose`: a head (pitch), neck (yaw) and body (yaw) pose in the normalized −1..1 animation units. Empty (`[]`) means not set. Not set is the default. +- When `face_pose` is not set, the robot moves exactly as today. No user has to do this setup. +- The talking animation centers its head nods, neck drift and body sway on the face pose when it is set. Other animations do not change in this change. +- `GET /settings` returns `face_pose`. `POST /settings` accepts `face_pose` (three numbers to set, `[]` to clear) in normal mode and in setup AP mode. Factory reset clears it. +- Web UI: a new **Face me** section on the Servo control page (`/servo`) to move head, neck and body to the user, save, clear and preview the talking animation. No new page route. +- Setup AP wizard: an optional **Face me** step after the servos step, with Skip. +- Docs: `docs/api.md`, `docs/settings.md`, the web UI API reference, `README.md`, `docs/robot-movement.md`. + +## Capabilities + +### New Capabilities +- `face-pose`: the per-user "face me" pose — storage, settings API, default behavior when not set, calibration in the web UI and the setup wizard, and which animations use it. + +### Modified Capabilities +- `setup-servo-calibration`: the "Guided calibration is strict forward with Back" requirement names the "outer five-step wizard progress". The wizard now has six steps, so the text says "outer wizard progress" (no count). The servos step itself does not change; the new Face me step is a `face-pose` requirement. + +## Impact + +- Firmware: `src/settings/` (new field, NVS key, validation, getter), `src/http/settings_handlers.cpp`, `src/animation/talking.cpp`, `src/animation/util.*` (face pose helper). +- Web UI: `ui/src/api/types.ts`, new Face me section on `ui/src/views/ServoControl.tsx`, `ui/src/setup/Wizard.tsx` and a new wizard step, `ui/src/views/ApiReference.tsx`. +- Tests: `test/test_settings_validate` (native), UI unit tests. +- API: additive field on `/settings`. No breaking change. Clients that do not know `face_pose` keep working. +- Known trade-off: the pose is stored relative to the saved servo min/max. After a servo range recalibration the physical direction can shift, so the UI tells the user to check Face me again. diff --git a/openspec/changes/face-me/specs/face-pose/spec.md b/openspec/changes/face-me/specs/face-pose/spec.md new file mode 100644 index 00000000..94fa986b --- /dev/null +++ b/openspec/changes/face-me/specs/face-pose/spec.md @@ -0,0 +1,138 @@ +# Spec Delta + +## Purpose + +Lets each user store an optional "face me" pose (head, neck, body) that points the robot at where they sit, so animations that address the user look at them. When the pose is not set, the robot behaves exactly as it does without the feature. + +## ADDED Requirements + +### Requirement: Face pose is an optional persistent setting +The device MUST store an optional face pose of three values: head, neck and body, in that order, each in normalized pose units from −1 to 1 (−1 = saved min, 0 = mid, 1 = saved max). The pose MUST persist across reboot. A device with no stored pose MUST treat the face pose as not set. + +#### Scenario: Fresh device has no face pose +- **WHEN** settings load on a device that never saved a face pose +- **THEN** the face pose is not set + +#### Scenario: Saved pose survives reboot +- **WHEN** a client saves face pose `[0.2, -0.4, 0.1]` and the device reboots +- **THEN** the face pose is `[0.2, -0.4, 0.1]` + +### Requirement: Settings API exposes face pose +`GET /settings` MUST include `face_pose`: a three-number array `[head, neck, body]` when set, or an empty array when not set. `POST /settings` MUST accept `face_pose` as three numbers from −1 to 1 to set it, or as an empty array to clear it, in normal mode and in setup AP mode. + +#### Scenario: Read when not set +- **WHEN** a client sends `GET /settings` and no face pose is set +- **THEN** the response contains `"face_pose": []` + +#### Scenario: Set the pose +- **WHEN** a provisioned client sends `POST /settings` with `{"face_pose":[0.15,-0.3,0.1]}` +- **THEN** the device answers success and the next `GET /settings` returns `"face_pose": [0.15,-0.3,0.1]` + +#### Scenario: Clear the pose +- **WHEN** a client sends `POST /settings` with `{"face_pose":[]}` +- **THEN** the face pose is not set and `GET /settings` returns `"face_pose": []` + +#### Scenario: Set in setup AP mode +- **WHEN** setup AP mode is active and a client sends `POST /settings` with a valid `face_pose` +- **THEN** the device saves it and does not answer `setup only in AP mode` or any other mode error + +### Requirement: Invalid face pose is rejected without change +The device MUST answer `400` with `invalid face_pose` and MUST NOT change any setting from that request when `face_pose` is not an array, has a length other than 0 or 3, contains a non-number, or contains a value outside −1..1. + +#### Scenario: Value out of range +- **WHEN** a client sends `POST /settings` with `{"face_pose":[0,1.5,0],"volume":40}` +- **THEN** the device answers `400` `invalid face_pose` +- **AND** neither the face pose nor the volume changes + +#### Scenario: Wrong length +- **WHEN** a client sends `POST /settings` with `{"face_pose":[0,0]}` +- **THEN** the device answers `400` `invalid face_pose` + +#### Scenario: Null is a wrong type +- **WHEN** a client sends `POST /settings` with `{"face_pose":null}` +- **THEN** the device answers `400` `invalid face_pose` + +### Requirement: Factory reset clears face pose +A factory reset MUST clear the face pose, because it depends on the desk setup and not on the robot build. + +#### Scenario: Reset then read +- **WHEN** a face pose is set and the user performs a factory reset +- **THEN** after reset `GET /settings` returns `"face_pose": []` +- **AND** the saved servo ranges are unchanged + +### Requirement: Talking faces the user when face pose is set +When the face pose is set, the talking animation MUST use the face head, neck and body as its rest pose, and MUST apply its head nods, neck drift and body sway as offsets from that rest pose, limited to −1..1. A change to the face pose MUST apply the next time talking starts, without reboot. + +#### Scenario: Talking settles on the face pose +- **WHEN** the face pose is `[0.3, -0.5, 0.2]` and talking starts with no audio +- **THEN** the head, neck and body move toward `0.3`, `-0.5` and `0.2` +- **AND** later neck drift and body sway stay within their normal sway width around `-0.5` and `0.2` + +#### Scenario: Offsets are limited +- **WHEN** the face neck is `1` and talking drifts the neck to a positive offset +- **THEN** the neck target is `1`, not a value above the saved max + +#### Scenario: New pose applies without reboot +- **WHEN** a client saves a new face pose and then starts talking +- **THEN** talking uses the new face pose + +### Requirement: No face pose keeps current motion +When the face pose is not set, every animation MUST use the same poses it uses without this feature. Talking MUST use head `1/7`, neck `0` and body `0` as its rest pose. + +#### Scenario: Talking without face pose +- **WHEN** no face pose is set and talking starts +- **THEN** talking rests at head `1/7`, neck `0` and body `0`, as before this change + +#### Scenario: Other animations ignore the face pose +- **WHEN** a face pose is set and typing, reading, thinking, welcome, attention or ring plays +- **THEN** those animations use the same poses as when no face pose is set + +### Requirement: Web UI calibrates the face pose +After provisioning, the Servo control page of the web UI MUST provide a Face me section that moves head, neck and body one at a time inside their saved ranges with nudge steps of ±1° and ±5° in whole degrees, shows the selected joint on a bar that spans its saved min to max, saves the current pose as the face pose, clears it, and plays the talking animation as a preview. The section MUST show whether a face pose is set. + +#### Scenario: Start from the saved or default pose +- **WHEN** the user opens the Servo control page +- **THEN** the controls start at the saved face pose, or at head `1/7`, neck `0`, body `0` when none is set +- **AND** the Face me section states whether a face pose is set + +#### Scenario: Adjust a joint +- **WHEN** the user picks head, neck or body and chooses a ±1° or ±5° nudge +- **THEN** the robot moves that joint to the shown whole-degree angle plus that step, limited to its saved range +- **AND** the bar marker moves to the new angle between the saved min and max +- **AND** the stored value is the matching −1..1 pose unit + +#### Scenario: Save +- **WHEN** the user chooses Save +- **THEN** the UI sends the three current values as `face_pose` via `POST /settings` + +#### Scenario: Clear +- **WHEN** the user chooses Clear and confirms +- **THEN** the UI sends `"face_pose": []` and the section shows that no face pose is set + +#### Scenario: Preview +- **WHEN** the user chooses Preview +- **THEN** the robot plays the talking animation + +#### Scenario: Recalibration notice +- **WHEN** the Face me section shows a set face pose +- **THEN** the section tells the user to check the face pose again after a servo range calibration + +### Requirement: Setup wizard offers an optional Face me step +The setup AP wizard MUST show a Face me step directly after the servos step. The step MUST let the user move head, neck and body and save the face pose, and MUST offer Skip. Skip MUST advance without changing the face pose. + +#### Scenario: Step order +- **WHEN** the user leaves the servos step +- **THEN** the next wizard step is Face me + +#### Scenario: Skip keeps the current value +- **WHEN** the user chooses Skip on the Face me step +- **THEN** the wizard advances to the next step +- **AND** no `face_pose` is sent + +#### Scenario: Save and continue +- **WHEN** the user moves the joints and chooses Save and continue +- **THEN** the UI sends the three current values as `face_pose` via `POST /settings` and advances + +#### Scenario: Wizard moves use the setup move +- **WHEN** the user nudges a joint on the Face me step +- **THEN** the UI uses the setup servo move endpoint with the matching angle inside the saved range diff --git a/openspec/changes/face-me/specs/setup-servo-calibration/spec.md b/openspec/changes/face-me/specs/setup-servo-calibration/spec.md new file mode 100644 index 00000000..7ea96338 --- /dev/null +++ b/openspec/changes/face-me/specs/setup-servo-calibration/spec.md @@ -0,0 +1,24 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Guided calibration is strict forward with Back +Guided range calibration MUST proceed in a fixed joint order with only forward confirmation and Back to the previous substep (or to the hub from the first substep). Free joint-tab switching MUST NOT be offered during this path. + +#### Scenario: Joint order +- **WHEN** the user completes guided calibration from the start +- **THEN** the path visits Body, then Neck, then Head, then Hands, in that order + +#### Scenario: Back from first substep +- **WHEN** the user is on the first guided substep and chooses Back +- **THEN** the UI returns to the servos hub + +#### Scenario: Back within the path +- **WHEN** the user is past the first guided substep and chooses Back +- **THEN** the UI returns to the previous guided substep + +#### Scenario: Progress shows joint context +- **WHEN** the user is on a guided substep +- **THEN** the section heading shows the joint and center/min/max or hand landmark role once +- **AND** a separate line shows `Servo calibration` and the current substep out of all guided substeps +- **AND** an internal progress indicator advances independently of the outer wizard progress diff --git a/openspec/changes/face-me/tasks.md b/openspec/changes/face-me/tasks.md new file mode 100644 index 00000000..be04f362 --- /dev/null +++ b/openspec/changes/face-me/tasks.md @@ -0,0 +1,48 @@ +# Tasks + +## 1. Settings core + +- [x] 1.1 Add `FacePose` (`set`, `values[3]`), `SettingsValues` fields with not-set default, `SettingsValues::log()` output, and `settingsFacePose()` getter; verify `pio run` compiles +- [x] 1.2 Add `FacePose::valid()` (not set, or each value finite and −1..1; mirrors `ServoRanges::valid()`) and wire it into `SettingsPatch::invalidField()` and `SettingsValues::apply()`; do not add it to `setupOnlyStep()`; verify new cases in `test/test_settings_validate` (valid set, valid clear, out of range, NaN) pass with `pio test -e native` +- [x] 1.3 Add NVS key `kKeyFacePose = "face_pose"` as a 12-byte float blob: load (missing or wrong size = not set), write on set, remove key on clear; verify factory reset leaves it cleared by reading `factoryResetSettings()` and that `pio run` compiles +- [x] 1.4 Document the field in `docs/settings.md` (HTTP field list, NVS key list, factory-reset pitfall) and verify the lists match `nvs.h` and `readPatch()` + +## 2. HTTP API + +- [x] 2.1 Add `face_pose` to `settingsJson()` (`[h,n,b]` or `[]`) and to `readPatch()` with a `readField` overload for the 0-or-3 float array (null = wrong type); grow `known[]`; verify `pio run` compiles +- [x] 2.2 Update `docs/api.md` (GET example, field table, POST param table, `[]` clears, apply timing, factory reset) and the `/settings` param list in `ui/src/views/ApiReference.tsx` with identical values; verify both texts match +- [x] 2.3 Add `face_pose` to the `docs/hardware/testing.md` settings rows (`README.md` lists no settings fields, so it needs no change); verify with `grep -n face_pose docs/hardware/testing.md` + +## 3. Talking animation + +- [x] 3.1 Add `anim::FacePose` and `anim::facePose()` (fallback `{TALKING_HEAD_MID, 0, 0}`) in `src/animation/util.*`; limit targets with the existing `servoSaturateNorm()`; verify `pio run` compiles +- [x] 3.2 Update `src/animation/talking.cpp` per design D5: read the face pose once in `startTalking()`, rest head/neck/body on it, neck drift and body sway around it with clamp, body bias relative to face neck, settle body to face body; verify by code review that every former `TALKING_HEAD_MID` / `0.0f` neck and body target now uses the cached pose and that the not-set pose gives the same numbers as before; `pio run` passes +- [x] 3.3 Add a "Face me" paragraph to `docs/robot-movement.md` (what it is, units, only talking uses it, recalibration note); verify the doc links to `docs/api.md` + +## 4. Web UI: Servo control section + +- [x] 4.1 Add `face_pose: number[]` to `Settings` in `ui/src/api/types.ts` and a `normToDeg(n, range)` helper in `ui/src/servos.ts`; verify `npm run lint --prefix ui` +- [x] 4.2 Add a shared `FacePoseControls` component in `ui/src/components/` (three −1..1 range inputs for head, neck, body; calls an injected move function with degrees) and a `FacePoseSection` on `ServoControl.tsx` (status Set / Not set, Save, Clear with confirm, Preview via `POST /anim` `name=talking`, recalibration note); verify with new cases in `ui/test/servo.test.tsx` (start values, move request angle, save body, clear body) and `npm test --prefix ui` + +## 5. Web UI: setup wizard step + +- [x] 5.1 Add step `{ id: "face", title: "Face me" }` after `servos` in `ui/src/setup/Wizard.tsx` with a `FaceStep` that uses `FacePoseControls` with `useSetupServo`, Skip (sends nothing) and Save and continue (posts `face_pose`); verify with new cases in `ui/test/wizard.test.tsx` (step order, Skip sends no `face_pose`, Save sends it) and `npm test --prefix ui`, plus `npm run lint --prefix ui` + +## 6. Integration + +- [x] 6.1 Run `pio run`, `pio test -e native`, `npm run lint --prefix ui` and `npm test --prefix ui`; verify all pass +- [x] 6.2 Run `openspec validate face-me --strict`; verify it passes +- [x] 6.3 On the real robot: with no face pose, talking looks as before; set a face pose from `/servo`, preview talking, and confirm the robot rests and sways around the user; clear it and confirm talking returns to the old pose; run the wizard Face me step with Skip and with Save (user test) + +## 7. Feedback from the first robot test + +- [x] 7.1 Add top margin to the Face me section on `/servo`; verify by `npm run lint --prefix ui` and a visual check on the robot +- [x] 7.2 Replace the face sliders with a joint picker, a min..max range bar with a marker, whole-degree angles and ±1° / ±5° nudge buttons (shared `FacePoseControls`, used on `/servo` and in the wizard); verify updated cases in `ui/test/servo.test.tsx` and `ui/test/wizard.test.tsx` pass with `npm test --prefix ui` +- [x] 7.3 Make the first reading neck turn use the typing sway speed (shared `TYPING_SWAY_SPEED_*` constants); verify `pio run -e supermini` passes and, on the robot, the transition into reading feels like typing +- [x] 7.4 Make talking turn neck and body to the face pose at 40°/s and the head with the typing head snap, and hold neck drift, body sway, reactive head settle and emphasis nod until all three arrive (also on resume after a cancelled transition); verify `pio run -e supermini` passes +- [x] 7.5 On the real robot: confirm 7.1–7.4 (user test) + +## Workflow follow-up + +- After the robot test passes, rebase the branch onto `main` in a separate worktree (`git rebase --onto main custom_setup feat/face-me`), run `pio run`, push to `fork` and open the PR to `jamro/tiny-engineer` after user approval. +- Archive the change after the PR is merged. diff --git a/src/animation/constants.h b/src/animation/constants.h index c5e75107..f0b1ddc6 100644 --- a/src/animation/constants.h +++ b/src/animation/constants.h @@ -14,6 +14,10 @@ constexpr float READING_NECK_SWAY = 2.0f / 9.0f; constexpr float TRANSITION_TORSO_SPEED_DEG_S = 25.0f; constexpr float TRANSITION_HAND_SPEED_DEG_S = 90.0f; +// Typing body/neck sway speed (deg/s): min + span * random. Reading reuses it +// for its first neck turn after a transition. +constexpr float TYPING_SWAY_SPEED_MIN_DEG_S = 12.0f; +constexpr float TYPING_SWAY_SPEED_SPAN_DEG_S = 18.0f; constexpr float TYPING_RIGHT_LOW = -1.0f; constexpr float TYPING_RIGHT_HIGH = TYPING_RIGHT_LOW + TYPING_HAND_BAND; @@ -28,11 +32,17 @@ constexpr float TYPING_NECK_MID = 0.0f; // Talking faces the user: head just above mid, nodding on emphasis, neck drifting. constexpr float TALKING_HEAD_MID = 1.0f / 7.0f; +// Rest pose when no "face me" pose is saved (see anim::facePose()). +constexpr float TALKING_NECK_MID = 0.0f; +constexpr float TALKING_BODY_MID = 0.0f; constexpr float TALKING_HEAD_NOD = 2.0f / 7.0f; constexpr float TALKING_HEAD_NOD_AMBIENT = 1.0f / 7.0f; constexpr float TALKING_HEAD_LEVEL = 1.0f / 14.0f; constexpr float TALKING_NECK_SWAY = 1.0f / 6.0f; constexpr float TALKING_BODY_SWAY = 1.0f / 10.0f; +// Neck and body turn to the face pose at this speed when talking starts; the +// slow drift and sway begin only after they arrive. +constexpr float TALKING_FACE_ARRIVE_SPEED_DEG_S = 40.0f; constexpr float TALKING_HAND_LIFT = TYPING_HAND_BAND * 2.0f; constexpr float TALKING_HAND_LIFT_AMBIENT = TYPING_HAND_BAND * 1.4f; constexpr float TALKING_EMPHASIS_NOD = 0.18f; diff --git a/src/animation/reading.cpp b/src/animation/reading.cpp index 900f392f..2a817176 100644 --- a/src/animation/reading.cpp +++ b/src/animation/reading.cpp @@ -35,8 +35,7 @@ void commandReadingHead() { } } -void commandReadingNeck() { - const float speed = 8.0f + 8.0f * randUnit(); +void commandReadingNeck(float speed) { if (g_neckAngleHigh) { servoAt(SERVO_NECK).setNormTarget( anim::READING_NECK_MID + anim::READING_NECK_SWAY, @@ -85,10 +84,14 @@ void beginScrollBurst() { commandScrollPress(); } +float readingNeckSpeed() { + return 8.0f + 8.0f * randUnit(); +} + void endScrollBurst(uint32_t now) { scheduleNextScrollBurst(now); commandReadingHead(); - commandReadingNeck(); + commandReadingNeck(readingNeckSpeed()); } void advanceReadingHeadStep() { @@ -116,7 +119,7 @@ void advanceReadingNeckStep() { void beginNextReadingNeck() { g_neckPauseUntilMs = 0; - commandReadingNeck(); + commandReadingNeck(readingNeckSpeed()); } } // namespace @@ -130,7 +133,10 @@ void startReading() { g_headPauseUntilMs = 0; g_neckPauseUntilMs = 0; snapHeadToRangeHigh(anim::READING_HEAD_HIGH); - commandReadingNeck(); + // The neck can start far from mid (a transition does not wait for the park, + // and talking may face the user), so the first turn uses the typing sway speed. + commandReadingNeck(anim::TYPING_SWAY_SPEED_MIN_DEG_S + + anim::TYPING_SWAY_SPEED_SPAN_DEG_S * randUnit()); scheduleNextScrollBurst(millis()); } diff --git a/src/animation/talking.cpp b/src/animation/talking.cpp index 3c59c499..343b2e42 100644 --- a/src/animation/talking.cpp +++ b/src/animation/talking.cpp @@ -25,31 +25,46 @@ uint32_t g_bodyNextMs = 0; uint32_t g_nodCooldownUntilMs = 0; uint32_t g_lastPhraseId = 0; bool g_wasStreamActive = false; +// Read once per start, so saving a new face pose never jumps a running animation. +anim::FacePose g_face = {anim::TALKING_HEAD_MID, anim::TALKING_NECK_MID, anim::TALKING_BODY_MID}; +// True until head, neck and body reach the face pose; drift, sway and the settle +// step would slow that turn. +bool g_arriving = false; + +bool arriving() { + if (g_arriving && !servoAt(SERVO_HEAD).isMoving() && !servoAt(SERVO_NECK).isMoving() && + !servoAt(SERVO_BODY).isMoving()) { + g_arriving = false; + } + + return g_arriving; +} void commandAmbientHeadBeat() { g_headUp = !g_headUp; const float target = g_headUp - ? anim::TALKING_HEAD_MID + anim::TALKING_HEAD_NOD_AMBIENT * (0.35f + 0.65f * randUnit()) - : anim::TALKING_HEAD_MID; + ? servoSaturateNorm(g_face.head + anim::TALKING_HEAD_NOD_AMBIENT * (0.35f + 0.65f * randUnit())) + : g_face.head; const float speed = g_headUp ? 40.0f + 25.0f * randUnit() : 18.0f + 12.0f * randUnit(); servoAt(SERVO_HEAD).setNormTarget(target, speed); } void commandNeckDrift() { - const float target = anim::TALKING_NECK_SWAY * (2.0f * randUnit() - 1.0f); + const float target = + servoSaturateNorm(g_face.neck + anim::TALKING_NECK_SWAY * (2.0f * randUnit() - 1.0f)); servoAt(SERVO_NECK).setNormTarget(target, 8.0f + 8.0f * randUnit()); } void commandBodyDrift() { // Bias opposite the current neck so the face stays roughly aimed at the user. - const float neckNorm = servoDegToNorm(SERVO_NECK, servoAt(SERVO_NECK).angle()); + const float neckNorm = servoDegToNorm(SERVO_NECK, servoAt(SERVO_NECK).angle()) - g_face.neck; float unit = 2.0f * randUnit() - 1.0f; if (neckNorm > 0.05f && unit > 0.0f) { unit = -unit; } else if (neckNorm < -0.05f && unit < 0.0f) { unit = -unit; } - const float target = anim::TALKING_BODY_SWAY * unit; + const float target = servoSaturateNorm(g_face.body + anim::TALKING_BODY_SWAY * unit); servoAt(SERVO_BODY).setNormTarget(target, 10.0f + 4.0f * randUnit()); } @@ -64,41 +79,44 @@ void commandAmbientGesture() { void settleReactivePose() { g_headUp = false; - if (!servoAt(SERVO_HEAD).isMoving() || - fabsf(servoDegToNorm(SERVO_HEAD, servoAt(SERVO_HEAD).angle()) - anim::TALKING_HEAD_MID) > 0.05f) { - servoAt(SERVO_HEAD).setNormTarget(anim::TALKING_HEAD_MID, 22.0f); + if (!g_arriving && + (!servoAt(SERVO_HEAD).isMoving() || + fabsf(servoDegToNorm(SERVO_HEAD, servoAt(SERVO_HEAD).angle()) - g_face.head) > 0.05f)) { + servoAt(SERVO_HEAD).setNormTarget(g_face.head, 22.0f); } if (g_gestureRaised) { g_gestureRaised = false; servoAt(SERVO_HAND_RIGHT).setNormTarget(anim::TYPING_RIGHT_LOW, 45.0f); } - if (!servoAt(SERVO_BODY).isMoving() || - fabsf(servoDegToNorm(SERVO_BODY, servoAt(SERVO_BODY).angle())) > 0.03f) { - servoAt(SERVO_BODY).setNormTarget(0.0f, 12.0f); + if (!g_arriving && + (!servoAt(SERVO_BODY).isMoving() || + fabsf(servoDegToNorm(SERVO_BODY, servoAt(SERVO_BODY).angle()) - g_face.body) > 0.03f)) { + servoAt(SERVO_BODY).setNormTarget(g_face.body, 12.0f); } } void commandEmphasisNod(float emphasis) { g_headUp = true; const float amount = 0.45f + 0.55f * emphasis; - const float target = - anim::TALKING_HEAD_MID + anim::TALKING_HEAD_NOD * amount; + const float target = servoSaturateNorm(g_face.head + anim::TALKING_HEAD_NOD * amount); const float speed = 50.0f + 40.0f * emphasis; servoAt(SERVO_HEAD).setNormTarget(target, speed); } void updateAmbientTalking(uint32_t now) { + const bool turning = arriving(); + if (!servoAt(SERVO_HEAD).isMoving() && now >= g_headPauseUntilMs) { commandAmbientHeadBeat(); g_headPauseUntilMs = now + (g_headUp ? randRangeMs(80, 180) : randRangeMs(280, 850)); } - if (now >= g_neckNextMs) { + if (!turning && now >= g_neckNextMs) { commandNeckDrift(); g_neckNextMs = now + randRangeMs(1100, 2600); } - if (now >= g_bodyNextMs && !servoAt(SERVO_BODY).isMoving()) { + if (!turning && now >= g_bodyNextMs && !servoAt(SERVO_BODY).isMoving()) { commandBodyDrift(); g_bodyNextMs = now + randRangeMs(3000, 8000); } @@ -110,7 +128,9 @@ void updateAmbientTalking(uint32_t now) { } void updateReactiveTalking(uint32_t now, const AudioMotionSnapshot& snap) { - if (now >= g_neckNextMs) { + const bool turning = arriving(); + + if (!turning && now >= g_neckNextMs) { commandNeckDrift(); g_neckNextMs = now + randRangeMs(1200, 2800); } @@ -122,17 +142,15 @@ void updateReactiveTalking(uint32_t now, const AudioMotionSnapshot& snap) { // Hold near mid with a small loudness offset (not sample-rate bobbing). if (!g_headUp && !servoAt(SERVO_HEAD).isMoving()) { - const float target = - anim::TALKING_HEAD_MID + anim::TALKING_HEAD_LEVEL * snap.level; + const float target = servoSaturateNorm(g_face.head + anim::TALKING_HEAD_LEVEL * snap.level); servoAt(SERVO_HEAD).setNormTarget(target, 28.0f); } else if (g_headUp && !servoAt(SERVO_HEAD).isMoving()) { g_headUp = false; - const float target = - anim::TALKING_HEAD_MID + anim::TALKING_HEAD_LEVEL * snap.level; + const float target = servoSaturateNorm(g_face.head + anim::TALKING_HEAD_LEVEL * snap.level); servoAt(SERVO_HEAD).setNormTarget(target, 24.0f); } - if (snap.emphasis >= anim::TALKING_EMPHASIS_NOD && now >= g_nodCooldownUntilMs) { + if (!turning && snap.emphasis >= anim::TALKING_EMPHASIS_NOD && now >= g_nodCooldownUntilMs) { commandEmphasisNod(snap.emphasis); g_nodCooldownUntilMs = now + anim::TALKING_NOD_COOLDOWN_MS; } @@ -149,7 +167,7 @@ void updateReactiveTalking(uint32_t now, const AudioMotionSnapshot& snap) { 70.0f ); g_gestureNextMs = now + randRangeMs(700, 1600); - } else if (!servoAt(SERVO_BODY).isMoving() && anim::randChance(40)) { + } else if (!turning && !servoAt(SERVO_BODY).isMoving() && anim::randChance(40)) { commandBodyDrift(); g_bodyNextMs = now + randRangeMs(4000, 9000); } @@ -172,7 +190,7 @@ void updateReactiveTalking(uint32_t now, const AudioMotionSnapshot& snap) { g_gestureNextMs = now + randRangeMs(600, 1400); } - if (now >= g_bodyNextMs && !servoAt(SERVO_BODY).isMoving()) { + if (!turning && now >= g_bodyNextMs && !servoAt(SERVO_BODY).isMoving()) { commandBodyDrift(); g_bodyNextMs = now + randRangeMs(4000, 9000); } @@ -194,7 +212,13 @@ void startTalking() { g_nodCooldownUntilMs = now; g_lastPhraseId = 0; g_wasStreamActive = false; - servoAt(SERVO_HEAD).setNormTarget(anim::TALKING_HEAD_MID, anim::TRANSITION_TORSO_SPEED_DEG_S); + g_face = anim::facePose(); + // parkNonePose() aims neck and body at mid; aim them at the user instead. + servoAt(SERVO_NECK).setNormTarget(g_face.neck, anim::TALKING_FACE_ARRIVE_SPEED_DEG_S); + servoAt(SERVO_BODY).setNormTarget(g_face.body, anim::TALKING_FACE_ARRIVE_SPEED_DEG_S); + g_arriving = true; + // Same fast head move as typing and reading use when they start. + anim::snapHeadToRangeHigh(g_face.head); } void updateTalking(uint32_t now) { @@ -211,6 +235,11 @@ void updateTalking(uint32_t now) { if (g_poseFrozen) { // The pending switch was cancelled (talking requested again): resume from here. g_poseFrozen = false; + // The freeze parked neck and body at mid; turn back to the user first. + servoAt(SERVO_NECK).setNormTarget(g_face.neck, anim::TALKING_FACE_ARRIVE_SPEED_DEG_S); + servoAt(SERVO_BODY).setNormTarget(g_face.body, anim::TALKING_FACE_ARRIVE_SPEED_DEG_S); + anim::snapHeadToRangeHigh(g_face.head); + g_arriving = true; g_headPauseUntilMs = now; g_neckNextMs = now; g_gestureNextMs = now + randRangeMs(2000, 4500); diff --git a/src/animation/typing.cpp b/src/animation/typing.cpp index 24e43c33..0b59f589 100644 --- a/src/animation/typing.cpp +++ b/src/animation/typing.cpp @@ -33,7 +33,7 @@ void commandBodyNeckSway() { const float offset = g_bodySwayPositive ? anim::TYPING_SWAY : -anim::TYPING_SWAY; const float speedDegS = - 12.0f + 18.0f * randUnit(); + anim::TYPING_SWAY_SPEED_MIN_DEG_S + anim::TYPING_SWAY_SPEED_SPAN_DEG_S * randUnit(); servoAt(SERVO_BODY).setNormTarget( anim::TYPING_BODY_MID + offset, diff --git a/src/animation/util.cpp b/src/animation/util.cpp index 679dd415..71abda97 100644 --- a/src/animation/util.cpp +++ b/src/animation/util.cpp @@ -5,9 +5,20 @@ #include "hardware/servo_wrapper.h" #include "servos.h" #include "serial_log.h" +#include "settings/settings.h" namespace anim { +FacePose facePose() { + const ::FacePose& saved = settingsFacePose(); + + if (!saved.set) { + return {TALKING_HEAD_MID, TALKING_NECK_MID, TALKING_BODY_MID}; + } + + return {saved.values[0], saved.values[1], saved.values[2]}; +} + float randUnit() { return (float)(esp_random() & 0xFFFFu) / 65535.0f; } diff --git a/src/animation/util.h b/src/animation/util.h index 1cedcdb7..f03b8b76 100644 --- a/src/animation/util.h +++ b/src/animation/util.h @@ -12,6 +12,16 @@ struct EasedMove { bool active; }; +// Pose that looks at the user, in -1..1 units. The saved "face me" pose when +// the user set one, else the talking rest pose (head 1/7, neck 0, body 0). +struct FacePose { + float head; + float neck; + float body; +}; + +FacePose facePose(); + float randUnit(); bool randChance(uint32_t percent); uint32_t randRangeMs(uint32_t lo, uint32_t hi); diff --git a/src/http/settings_handlers.cpp b/src/http/settings_handlers.cpp index a43dc0d8..d0bdfebd 100644 --- a/src/http/settings_handlers.cpp +++ b/src/http/settings_handlers.cpp @@ -67,10 +67,41 @@ bool readField(JsonVariantConst list, uint8_t (&out)[SETTINGS_SERVO_COUNT]) { return true; } +// [] clears the face pose; [head, neck, body] sets it. Range checks run later +// in SettingsPatch::invalidField(). +bool readField(JsonVariantConst list, std::optional& out) { + if (!list.is()) { + return false; + } + + FacePose pose{}; + + if (list.size() == 0) { + out = pose; + return true; + } + + if (list.size() != SETTINGS_FACE_POSE_COUNT) { + return false; + } + + for (size_t i = 0; i < SETTINGS_FACE_POSE_COUNT; i++) { + if (!list[i].is()) { + return false; + } + + pose.values[i] = list[i].as(); + } + + pose.set = true; + out = pose; + return true; +} + // Fills the patch from the body. Returns the 400 message, or an empty string // when every field is known and has the right JSON type. String readPatch(JsonObjectConst body, SettingsPatch& patch) { - const char* known[24] = {}; + const char* known[25] = {}; size_t knownCount = 0; const char* wrong = nullptr; @@ -118,6 +149,7 @@ String readPatch(JsonObjectConst body, SettingsPatch& patch) { read("link_mode", patch.linkMode); read("rgb_order", patch.rgbOrder); read("oled_rotate_180", patch.oledRotate180); + read("face_pose", patch.facePose); ServoRanges ranges{}; read("servo_mins", ranges.mins); @@ -183,6 +215,15 @@ JsonDocument settingsJson() { doc["rgb_order"] = settingsRgbOrder(); doc["oled_rotate_180"] = settingsOledRotate180(); + const FacePose& face = settingsFacePose(); + JsonArray facePose = doc["face_pose"].to(); + + if (face.set) { + for (const float value : face.values) { + facePose.add(value); + } + } + const WifiNetworkList& networks = settingsWifiNetworks(); JsonArray ssids = doc["wifi_networks"].to(); diff --git a/src/settings/getters.cpp b/src/settings/getters.cpp index 94dce878..b59cb5d8 100644 --- a/src/settings/getters.cpp +++ b/src/settings/getters.cpp @@ -126,3 +126,7 @@ const char* settingsRgbOrder() { bool settingsOledRotate180() { return g_settings.oledRotate180; } + +const FacePose& settingsFacePose() { + return g_settings.facePose; +} diff --git a/src/settings/nvs.cpp b/src/settings/nvs.cpp index 9848376e..62b0c6f6 100644 --- a/src/settings/nvs.cpp +++ b/src/settings/nvs.cpp @@ -10,6 +10,7 @@ namespace { // Stored as min,max pairs, one per servo. constexpr size_t kServoRangesLen = SETTINGS_SERVO_COUNT * 2; +constexpr size_t kFacePoseLen = SETTINGS_FACE_POSE_COUNT * sizeof(float); template void loadText(char (&dest)[N], const char* key, bool (*valid)(const char*)) { @@ -122,6 +123,16 @@ void SettingsValues::load() { if (g_settingsPrefs.isKey(kKeyOledRot)) { oledRotate180 = g_settingsPrefs.getBool(kKeyOledRot, oledRotate180); } + + if (g_settingsPrefs.isKey(kKeyFacePose)) { + FacePose stored{}; + stored.set = g_settingsPrefs.getBytes(kKeyFacePose, stored.values, kFacePoseLen) == + kFacePoseLen; + + if (stored.set && stored.valid()) { + facePose = stored; + } + } } namespace { @@ -194,6 +205,18 @@ bool writeValues(const SettingsValues& values, const SettingsValues& before, boo ok &= g_settingsPrefs.putBytes(kKeyServoRanges, blob, kServoRangesLen) == kServoRangesLen; } + const FacePose& face = values.facePose; + const FacePose& oldFace = before.facePose; + const bool faceChanged = face.set != oldFace.set || + (face.set && memcmp(face.values, oldFace.values, kFacePoseLen) != 0); + + if (all || faceChanged) { + // Not set = no key. Preferences writes nothing for an empty blob. + ok &= face.set + ? g_settingsPrefs.putBytes(kKeyFacePose, face.values, kFacePoseLen) == kFacePoseLen + : !g_settingsPrefs.isKey(kKeyFacePose) || g_settingsPrefs.remove(kKeyFacePose); + } + return ok; } diff --git a/src/settings/nvs.h b/src/settings/nvs.h index c66c2992..caa55c30 100644 --- a/src/settings/nvs.h +++ b/src/settings/nvs.h @@ -36,5 +36,7 @@ constexpr const char* kKeyLcd1602Boot = "ext_lcd_boot"; constexpr const char* kKeyLcd1602L1 = "ext_lcd_l1"; constexpr const char* kKeyLcd1602L2 = "ext_lcd_l2"; constexpr const char* kKeyLcd1602Last = "ext_lcd_last"; +// Three floats (head, neck, body). No key = no face pose. +constexpr const char* kKeyFacePose = "face_pose"; extern Preferences g_settingsPrefs; diff --git a/src/settings/settings.h b/src/settings/settings.h index 143e150e..e6498ea7 100644 --- a/src/settings/settings.h +++ b/src/settings/settings.h @@ -48,6 +48,7 @@ constexpr uint8_t SETTINGS_SERVO_ANGLE_MAX = 180; constexpr size_t SETTINGS_RGB_ORDER_MAX_LEN = 3; constexpr const char* SETTINGS_DEFAULT_RGB_ORDER = "GRB"; constexpr bool SETTINGS_DEFAULT_OLED_ROTATE_180 = false; +constexpr size_t SETTINGS_FACE_POSE_COUNT = 3; struct ServoRanges { uint8_t mins[SETTINGS_SERVO_COUNT]; @@ -57,6 +58,16 @@ struct ServoRanges { bool valid() const; }; +// Optional "face me" pose in animation units (-1 = saved min, 0 = mid, 1 = max), +// in the order head, neck, body. `set` false means the user did not set one. +struct FacePose { + bool set; + float values[SETTINGS_FACE_POSE_COUNT]; + + // Not set, or every value finite and within -1..1. + bool valid() const; +}; + // Fields left empty, or nullptr for text, keep their saved value. struct SettingsPatch { std::optional sleepTimeoutMin; @@ -80,6 +91,8 @@ struct SettingsPatch { std::optional servoRanges; const char* rgbOrder = nullptr; std::optional oledRotate180; + // A FacePose with `set` false clears the saved pose. + std::optional facePose; // API name of the first field set to an invalid value, or nullptr. const char* invalidField() const; @@ -129,6 +142,7 @@ float settingsServoMin(int index); float settingsServoMax(int index); const char* settingsRgbOrder(); bool settingsOledRotate180(); +const FacePose& settingsFacePose(); // True once the saved hostname, loading screen or WiFi networks differ from // what this boot started with; those apply only after a reboot. @@ -171,4 +185,5 @@ bool saveActions(const ActionList& actions); // Clears the NVS namespace and restores the defaults, WiFi networks included, // but keeps the servo min/max, RGB LED byte order and OLED 180° rotation. +// The face pose is cleared: it belongs to the desk setup, not to the build. bool factoryResetSettings(); diff --git a/src/settings/validate.cpp b/src/settings/validate.cpp index e1f1772b..28ab0b47 100644 --- a/src/settings/validate.cpp +++ b/src/settings/validate.cpp @@ -1,5 +1,6 @@ #include "settings/settings.h" +#include #include #include "display/eyes/styles/eye_style.h" @@ -253,6 +254,10 @@ const char* SettingsPatch::invalidField() const { return "rgb_order"; } + if (facePose && !facePose->valid()) { + return "face_pose"; + } + return nullptr; } @@ -292,3 +297,17 @@ const char* SettingsPatch::setupOnlyStep() const { return nullptr; } + +bool FacePose::valid() const { + if (!set) { + return true; + } + + for (const float value : values) { + if (!std::isfinite(value) || value < -1.0f || value > 1.0f) { + return false; + } + } + + return true; +} diff --git a/src/settings/values.cpp b/src/settings/values.cpp index 66edbd8b..812420d9 100644 --- a/src/settings/values.cpp +++ b/src/settings/values.cpp @@ -63,6 +63,7 @@ SettingsValues SettingsValues::defaults() { strlcpy(values.rgbOrder, SETTINGS_DEFAULT_RGB_ORDER, sizeof(values.rgbOrder)); values.oledRotate180 = SETTINGS_DEFAULT_OLED_ROTATE_180; + values.facePose = FacePose{}; return values; } @@ -79,6 +80,7 @@ void SettingsValues::apply(const SettingsPatch& patch) { continuousTimeoutMin = patch.continuousTimeoutMin.value_or(continuousTimeoutMin); servoRanges = patch.servoRanges.value_or(servoRanges); oledRotate180 = patch.oledRotate180.value_or(oledRotate180); + facePose = patch.facePose.value_or(facePose); if (patch.hostname != nullptr) { strlcpy(hostname, patch.hostname, sizeof(hostname)); @@ -123,7 +125,20 @@ void SettingsValues::log(const char* prefix) const { } const ServoRanges& r = servoRanges; - char line[512]; + char face[48] = "unset"; + + if (facePose.set) { + snprintf( + face, + sizeof(face), + "%.2f,%.2f,%.2f", + facePose.values[0], + facePose.values[1], + facePose.values[2] + ); + } + + char line[560]; snprintf( line, sizeof(line), @@ -131,7 +146,7 @@ void SettingsValues::log(const char* prefix) const { "push_button=%s push_button_pin=%u lcd1602=%s lcd1602_boot=%s actions=%u " "continuous_timeout=%umin loading=%s eyes_style=%s " "access_token=%s link_mode=%s wifi_networks=%u servos=%u-%u;%u-%u;%u-%u;%u-%u;%u-%u " - "rgb_order=%s oled_rotate_180=%s", + "rgb_order=%s oled_rotate_180=%s face_pose=%s", prefix, static_cast(sleepTimeoutMin), hostname, @@ -151,7 +166,8 @@ void SettingsValues::log(const char* prefix) const { r.mins[0], r.maxs[0], r.mins[1], r.maxs[1], r.mins[2], r.maxs[2], r.mins[3], r.maxs[3], r.mins[4], r.maxs[4], rgbOrder, - oledRotate180 ? "on" : "off" + oledRotate180 ? "on" : "off", + face ); serialLogPrintln(line); } diff --git a/src/settings/values.h b/src/settings/values.h index f034f3d1..46cb71b3 100644 --- a/src/settings/values.h +++ b/src/settings/values.h @@ -37,6 +37,7 @@ struct SettingsValues { ServoRanges servoRanges; char rgbOrder[SETTINGS_RGB_ORDER_MAX_LEN + 1]; bool oledRotate180; + FacePose facePose; static SettingsValues defaults(); diff --git a/test/test_settings_validate/test_settings_validate.cpp b/test/test_settings_validate/test_settings_validate.cpp index 94166d91..95ee4f4c 100644 --- a/test/test_settings_validate/test_settings_validate.cpp +++ b/test/test_settings_validate/test_settings_validate.cpp @@ -1,3 +1,4 @@ +#include #include #include @@ -174,6 +175,40 @@ void test_servo_ranges() { TEST_ASSERT_FALSE(over.valid()); } +void test_face_pose() { + const FacePose unset{}; + const FacePose valid = {true, {0.2f, -0.4f, 0.1f}}; + const FacePose edges = {true, {-1.0f, 1.0f, 0.0f}}; + const FacePose over = {true, {0.0f, 1.01f, 0.0f}}; + const FacePose under = {true, {-1.5f, 0.0f, 0.0f}}; + const FacePose notNumber = {true, {0.0f, 0.0f, NAN}}; + // Values are ignored while the pose is not set. + const FacePose clearedWithJunk = {false, {5.0f, NAN, -9.0f}}; + + TEST_ASSERT_TRUE(unset.valid()); + TEST_ASSERT_TRUE(valid.valid()); + TEST_ASSERT_TRUE(edges.valid()); + TEST_ASSERT_FALSE(over.valid()); + TEST_ASSERT_FALSE(under.valid()); + TEST_ASSERT_FALSE(notNumber.valid()); + TEST_ASSERT_TRUE(clearedWithJunk.valid()); +} + +void test_face_pose_patch() { + SettingsPatch patch; + + patch.facePose = FacePose{true, {0.15f, -0.3f, 0.1f}}; + TEST_ASSERT_NULL(patch.invalidField()); + // Face me is a desk setting, not a setup-only calibration. + TEST_ASSERT_NULL(patch.setupOnlyStep()); + + patch.facePose = FacePose{}; + TEST_ASSERT_NULL(patch.invalidField()); + + patch.facePose = FacePose{true, {0.0f, 2.0f, 0.0f}}; + TEST_ASSERT_EQUAL_STRING("face_pose", patch.invalidField()); +} + void test_patch_names_the_first_invalid_field() { SettingsPatch patch; @@ -271,6 +306,8 @@ int main() { RUN_TEST(test_wifi_ssid); RUN_TEST(test_wifi_password); RUN_TEST(test_servo_ranges); + RUN_TEST(test_face_pose); + RUN_TEST(test_face_pose_patch); RUN_TEST(test_patch_names_the_first_invalid_field); RUN_TEST(test_patch_names_its_setup_only_step); RUN_TEST(test_rgb_order); diff --git a/ui/src/api/types.ts b/ui/src/api/types.ts index 0ea256a9..b30c8122 100644 --- a/ui/src/api/types.ts +++ b/ui/src/api/types.ts @@ -54,6 +54,8 @@ export interface Settings { servo_maxs: number[]; rgb_order: string; oled_rotate_180: boolean; + // [head, neck, body] in -1..1, or [] when no face pose is set. + face_pose: number[]; wifi_networks: string[]; reboot_required?: boolean; wifi_connect_success?: boolean; diff --git a/ui/src/components/FacePoseControls.tsx b/ui/src/components/FacePoseControls.tsx new file mode 100644 index 00000000..e5509f91 --- /dev/null +++ b/ui/src/components/FacePoseControls.tsx @@ -0,0 +1,92 @@ +import { useState } from "preact/hooks"; +import { clamp } from "../lib/math"; +import { degToNorm, FACE_JOINTS, normToDeg, type Range } from "../servos"; +import { Button } from "./Button"; +import { ServoTrack } from "./ServoTrack"; + +const NUDGES = [-5, -1, 1, 5]; + +const wholeDegrees = (n: number, range: Range) => Math.round(normToDeg(n, range)); + +// Pick a joint, then nudge it in whole degrees like the guided calibration. The +// bar spans the joint's saved min..max. The pose stays in -1..1 units; every nudge +// moves the robot at once, inside the saved range. +export function FacePoseControls({ + pose, + ranges, + onPose, + onMove, +}: { + pose: readonly number[]; + ranges: readonly Range[]; + onPose: (pose: number[]) => void; + onMove: (index: number, angle: number) => Promise; +}) { + const [slot, setSlot] = useState(0); + const { index, name, low, high } = FACE_JOINTS[slot]; + const range = ranges[index]; + const [min, max] = range; + const angle = wholeDegrees(pose[slot], range); + const percent = (degrees: number) => `${((degrees - min) / Math.max(1, max - min)) * 100}%`; + + async function nudge(delta: number) { + const target = clamp(angle + delta, min, max); + + if (target === angle) { + return; + } + + const next = [...pose]; + + next[slot] = degToNorm(target, range); + onPose(next); + + if (!(await onMove(index, target))) { + onPose([...pose]); + } + } + + return ( +
+
+ {FACE_JOINTS.map((joint, each) => ( + + ))} +
+
+ {angle}° +
+ +

+ {name}: − turns {low}, + turns {high}. Saved range:{" "} + + {min}°–{max}° + +

+
+ {NUDGES.map((delta) => ( + + ))} +
+
+ ); +} diff --git a/ui/src/config/FactoryReset.tsx b/ui/src/config/FactoryReset.tsx index b0c62e35..41f99581 100644 --- a/ui/src/config/FactoryReset.tsx +++ b/ui/src/config/FactoryReset.tsx @@ -10,7 +10,7 @@ export function FactoryReset() { async function reset() { const confirmed = confirm( - "Reset settings to factory defaults? WiFi credentials will be cleared. Servo ranges, RGB LED mapping, and screen rotation stay. Power-cycle the device to reopen setup AP mode and configure WiFi again.", + "Reset settings to factory defaults? WiFi credentials and the face me pose will be cleared. Servo ranges, RGB LED mapping, and screen rotation stay. Power-cycle the device to reopen setup AP mode and configure WiFi again.", ); if (!confirmed) { @@ -31,9 +31,9 @@ export function FactoryReset() { return (

- Erases saved settings and restores defaults. WiFi credentials are cleared. Servo ranges, RGB - LED mapping, and screen rotation stay. Power-cycle the device to reopen setup AP mode and - configure WiFi again. + Erases saved settings and restores defaults. WiFi credentials and the face me pose are + cleared. Servo ranges, RGB LED mapping, and screen rotation stay. Power-cycle the device to + reopen setup AP mode and configure WiFi again.

- {nextStep && ( + {step.id === "face" && } + {step.id === "face" && nextStep && ( + + )} + {step.id !== "face" && nextStep && ( diff --git a/ui/src/style.css b/ui/src/style.css index b46bd7a0..531387f1 100644 --- a/ui/src/style.css +++ b/ui/src/style.css @@ -771,6 +771,21 @@ code { } } +.face-me-section { + margin-top: 1.5rem; +} + +.calib-nudge.face-nudge { + grid-template-columns: repeat(4, 1fr); +} + +.face-pose-joints { + display: grid; + grid-template-columns: repeat(3, 1fr); + gap: 0.5rem; + margin-bottom: 0.5rem; +} + .servo-actions { display: grid; grid-template-columns: 1fr 1fr; diff --git a/ui/src/views/ApiReference.tsx b/ui/src/views/ApiReference.tsx index f82d4ab9..b99b5e69 100644 --- a/ui/src/views/ApiReference.tsx +++ b/ui/src/views/ApiReference.tsx @@ -258,6 +258,16 @@ export function ApiReference() { Setup AP only; default false + + + face_pose + + number array + + Three numbers -1 to 1 (head, neck, body), or [] to clear; + default [] (not set) + +

diff --git a/ui/src/views/FacePoseSection.tsx b/ui/src/views/FacePoseSection.tsx new file mode 100644 index 00000000..2cf5671e --- /dev/null +++ b/ui/src/views/FacePoseSection.tsx @@ -0,0 +1,91 @@ +import { useState } from "preact/hooks"; +import type { AnimationReply, Settings } from "../api/types"; +import { Button } from "../components/Button"; +import { ConfigSection } from "../components/ConfigSection"; +import { FacePoseControls } from "../components/FacePoseControls"; +import { useRobot } from "../robot"; +import { savedFacePose, type Range } from "../servos"; +import { useStatus } from "../status/status"; + +export function FacePoseSection({ settings, ranges }: { settings: Settings; ranges: Range[] }) { + const { applySettings } = useRobot(); + const { perform } = useStatus(); + const [pose, setPose] = useState(() => savedFacePose(settings)); + const [previewing, setPreviewing] = useState(false); + const isSet = settings.face_pose.length > 0; + + async function playAnimation(name: string) { + const result = await perform({ + path: "/anim", + request: { method: "POST", params: { name } }, + pending: "Setting animation…", + failure: "Failed", + }); + + return result?.ok === true; + } + + async function move(index: number, angle: number) { + // A running preview would fight the manual move. + if (previewing && (await playAnimation("none"))) { + setPreviewing(false); + } + + const result = await perform({ + path: "/test/servo", + request: { method: "POST", json: { index, angle } }, + pending: "Moving servo…", + failure: "Move failed", + }); + + return result?.ok === true; + } + + async function save(facePose: number[], done: string) { + await perform({ + path: "/settings", + request: { method: "POST", json: { face_pose: facePose } }, + pending: "Saving face pose…", + failure: "Save failed", + done, + onSuccess: applySettings, + }); + } + + async function clear() { + if (!confirm("Clear the face me pose? Talking goes back to the default pose.")) { + return; + } + + await save([], "Face pose cleared."); + } + + async function togglePreview() { + if (await playAnimation(previewing ? "none" : "talking")) { + setPreviewing(!previewing); + } + } + + return ( + +

+ Optional. Pick a joint and nudge it until the robot looks at you. Do this + for head, neck and body, then save. The talking animation then faces you. Status:{" "} + {isSet ? "Set" : "Not set (default pose)"} +

+ + {isSet && ( +

+ The pose follows the saved servo limits. Check it again after a servo calibration. +

+ )} +
+ + {isSet && } + +
+
+ ); +} diff --git a/ui/src/views/ServoControl.tsx b/ui/src/views/ServoControl.tsx index 24dc5570..0c8af95e 100644 --- a/ui/src/views/ServoControl.tsx +++ b/ui/src/views/ServoControl.tsx @@ -4,6 +4,7 @@ import { Button } from "../components/Button"; import { ServoTrack } from "../components/ServoTrack"; import { DEFAULT_SERVO_RANGES, inRange, SERVO_NAMES, savedRanges } from "../servos"; import { useStatus } from "../status/status"; +import { FacePoseSection } from "./FacePoseSection"; export function ServoControl() { const { settings } = useRobot(); @@ -109,6 +110,7 @@ export function ServoControl() { + {settings && } ); } diff --git a/ui/test/robot.tsx b/ui/test/robot.tsx index 0a50506e..9002c5c9 100644 --- a/ui/test/robot.tsx +++ b/ui/test/robot.tsx @@ -30,6 +30,7 @@ const DEFAULT_SETTINGS: Settings = { servo_maxs: [100, 100, 100, 100, 100], rgb_order: "GRB", oled_rotate_180: false, + face_pose: [], }; export interface RecordedRequest { diff --git a/ui/test/servo.test.tsx b/ui/test/servo.test.tsx index eca0773a..f2ed2d71 100644 --- a/ui/test/servo.test.tsx +++ b/ui/test/servo.test.tsx @@ -1,5 +1,5 @@ import { screen, waitFor } from "@testing-library/preact"; -import { describe, expect, it } from "vitest"; +import { describe, expect, it, vi } from "vitest"; import { fakeRobot, renderApp } from "./robot"; async function typeAngle(user: ReturnType["user"], value: string) { @@ -46,3 +46,126 @@ describe("servo page", () => { ); }); }); + +const faceAngle = () => screen.getByTestId("face-angle").textContent; + +describe("face me section", () => { + it("starts at the default pose and says no pose is set", async () => { + fakeRobot(); + renderApp("/servo"); + + expect(await screen.findByText("Not set (default pose)")).toBeTruthy(); + // Head 1/7 of the half-span above mid 90 is 91.4°, shown in whole degrees. + expect(faceAngle()).toBe("91"); + expect(screen.getByRole("button", { name: "Neck 90°" })).toBeTruthy(); + }); + + it("starts at the saved pose", async () => { + fakeRobot({ settings: { face_pose: [0.2, -0.5, 0.25] } }); + renderApp("/servo"); + + expect(await screen.findByRole("button", { name: "Neck 85°" })).toBeTruthy(); + expect(screen.getByText("Set")).toBeTruthy(); + expect(screen.getByText(/Check it again after a servo calibration/)).toBeTruthy(); + }); + + it("nudges the picked joint in degrees inside its saved range", async () => { + const robot = fakeRobot({ + settings: { servo_mins: [70, 40, 45, 35, 60], servo_maxs: [110, 130, 135, 125, 120] }, + }); + const { click } = renderApp("/servo"); + + await click(/^Body/); + await click("+5°"); + + await waitFor(() => + expect(robot.lastPost("/test/servo")?.json).toEqual({ index: 4, angle: 95 }), + ); + + for (let i = 0; i < 6; i++) { + await click("+5°"); + } + + // Body max is 120: the last nudges stop there. + await waitFor(() => expect(faceAngle()).toBe("120")); + expect(robot.lastPost("/test/servo")?.json).toEqual({ index: 4, angle: 120 }); + expect(screen.queryByRole("button", { name: "+10°" })).toBeNull(); + }); + + it("shows the picked joint's whole saved range on the bar", async () => { + fakeRobot({ + settings: { servo_mins: [70, 40, 45, 35, 60], servo_maxs: [110, 130, 135, 125, 120] }, + }); + const { click } = renderApp("/servo"); + + await click(/^Neck/); + + expect(document.querySelector(".face-pose .servo-scale")?.textContent).toBe("40°85°130°"); + // Neck at mid 85 sits in the middle of 40..130. + expect(document.querySelector(".face-pose .calib-marker")?.style.left).toBe("50%"); + }); + + it("nudges whole degrees from a rounded start", async () => { + const robot = fakeRobot(); + const { click } = renderApp("/servo"); + + await screen.findByText("Not set (default pose)"); + await click("+1°"); + + // Head starts at 91.4°, shown as 91; +1 goes to 92. + await waitFor(() => + expect(robot.lastPost("/test/servo")?.json).toEqual({ index: 0, angle: 92 }), + ); + expect(faceAngle()).toBe("92"); + }); + + it("keeps the pose when a move fails", async () => { + const robot = fakeRobot(); + const { click } = renderApp("/servo"); + + robot.failing.add("/test/servo"); + await click(/^Neck/); + await click("−5°"); + + await waitFor(() => expect(robot.sent("POST", "/test/servo")).toHaveLength(1)); + expect(faceAngle()).toBe("90"); + }); + + it("saves the current pose", async () => { + const robot = fakeRobot(); + const { click } = renderApp("/servo"); + + await click(/^Neck/); + await click("−1°"); + await click("Save face pose"); + + // Neck 89° in the stock 80–100 range is -0.1. + await waitFor(() => + expect(robot.lastPost("/settings")?.json).toEqual({ face_pose: [1 / 7, -0.1, 0] }), + ); + expect(await screen.findByText("Set")).toBeTruthy(); + }); + + it("clears the pose after a confirm", async () => { + const robot = fakeRobot({ settings: { face_pose: [0.2, -0.5, 0.25] } }); + + vi.spyOn(window, "confirm").mockReturnValueOnce(true); + const { click } = renderApp("/servo"); + + await click("Clear"); + + await waitFor(() => expect(robot.lastPost("/settings")?.json).toEqual({ face_pose: [] })); + expect(await screen.findByText("Not set (default pose)")).toBeTruthy(); + }); + + it("previews talking and stops it", async () => { + const robot = fakeRobot(); + const { click } = renderApp("/servo"); + + await click("Preview talking"); + await waitFor(() => expect(robot.lastPost("/anim")?.params).toEqual({ name: "talking" })); + + await click("Stop preview"); + await waitFor(() => expect(robot.lastPost("/anim")?.params).toEqual({ name: "none" })); + }); +}); diff --git a/ui/test/wizard.test.tsx b/ui/test/wizard.test.tsx index 0802aa76..1ec25fc0 100644 --- a/ui/test/wizard.test.tsx +++ b/ui/test/wizard.test.tsx @@ -3,7 +3,7 @@ import { describe, expect, it } from "vitest"; import { fakeRobot, renderApp } from "./robot"; const angle = () => screen.getByTestId("calib-angle").textContent; -const stepLabel = () => screen.getByText(/^Step \d of 5/).textContent; +const stepLabel = () => screen.getByText(/^Step \d of 6/).textContent; const statusText = () => screen.queryByRole("status")?.textContent; async function openWizard(settings = {}) { @@ -15,11 +15,20 @@ async function openWizard(settings = {}) { return { robot, ...app }; } -async function skipCalibration(settings = {}) { +async function skipToFace(settings = {}) { const ctx = await openWizard(settings); await ctx.click("Skip"); - await waitFor(() => expect(stepLabel()).toBe("Step 2 of 5 · Screen")); + await waitFor(() => expect(stepLabel()).toBe("Step 2 of 6 · Face me")); + + return ctx; +} + +async function skipCalibration(settings = {}) { + const ctx = await skipToFace(settings); + + await ctx.click("Skip"); + await waitFor(() => expect(stepLabel()).toBe("Step 3 of 6 · Screen")); return ctx; } @@ -40,7 +49,7 @@ describe("setup wizard", () => { await screen.findByRole("heading", { name: "Tiny Engineer setup" }); expect(screen.queryByRole("navigation")).toBeNull(); - expect(stepLabel()).toBe("Step 1 of 5 · Servos"); + expect(stepLabel()).toBe("Step 1 of 6 · Servos"); }); it("opens the servos hub before assembly or guided calibration", async () => { @@ -404,7 +413,7 @@ describe("setup wizard", () => { await click("Save and continue"); - await waitFor(() => expect(stepLabel()).toBe("Step 2 of 5 · Screen")); + await waitFor(() => expect(stepLabel()).toBe("Step 2 of 6 · Face me")); const saved = robot.lastPost("/settings")?.json as Record; @@ -416,6 +425,44 @@ describe("setup wizard", () => { expect(Object.keys(saved)).toEqual(["servo_mins", "servo_maxs"]); }); + it("offers an optional Face me step after the servos step; Skip sends no face pose", async () => { + const { robot, click } = await skipToFace({ face_pose: [0.2, -0.5, 0.25] }); + + expect(screen.getByRole("heading", { name: "Face me" })).toBeTruthy(); + expect(screen.getByRole("button", { name: "Neck 85°" })).toBeTruthy(); + + await click("Skip"); + + await waitFor(() => expect(stepLabel()).toBe("Step 3 of 6 · Screen")); + expect( + robot + .sent("POST", "/settings") + .some((request) => JSON.stringify(request.json).includes("face_pose")), + ).toBe(false); + }); + + it("moves face joints with the setup move and saves the pose", async () => { + const { robot, click } = await skipToFace({ + servo_mins: [70, 40, 45, 35, 60], + servo_maxs: [110, 130, 135, 125, 120], + }); + + await click(/^Neck/); + await click("−5°"); + await click("−5°"); + + // Neck (index 1): mid 85 − 10 = 75, which is -0.2222 of the 45° half-span. + await waitFor(() => + expect(robot.lastPost("/setup/servo")?.json).toEqual({ index: 1, angle: 75 }), + ); + expect(robot.sent("POST", "/test/servo")).toHaveLength(0); + + await click("Save and continue"); + + await waitFor(() => expect(stepLabel()).toBe("Step 3 of 6 · Screen")); + expect(robot.lastPost("/settings")?.json).toEqual({ face_pose: [1 / 7, -0.2222, 0] }); + }); + it("restores the setup screen when leaving the screen step", async () => { const { robot, click } = await skipCalibration(); @@ -423,7 +470,11 @@ describe("setup wizard", () => { await click("Back"); await waitFor(() => expect(robot.lastPost("/setup/oled")?.json).toBeUndefined()); - expect(stepLabel()).toBe("Step 1 of 5 · Servos"); + expect(stepLabel()).toBe("Step 2 of 6 · Face me"); + + await click("Back"); + + expect(stepLabel()).toBe("Step 1 of 6 · Servos"); expect(screen.getByRole("button", { name: "Calibrate servos" })).toBeTruthy(); }); @@ -467,7 +518,7 @@ describe("setup wizard", () => { await click("Next: Speaker"); await click("Next: Connection"); - expect(stepLabel()).toBe("Step 5 of 5 · Connection"); + expect(stepLabel()).toBe("Step 6 of 6 · Connection"); await user.click(screen.getByRole("radio", { name: /USB connection only/i })); await click("Use USB only"); @@ -503,7 +554,7 @@ describe("setup wizard", () => { await click("Next: RGB mapping"); await click("Change color mapping"); - expect(stepLabel()).toBe("Step 3 of 5 · RGB mapping"); + expect(stepLabel()).toBe("Step 4 of 6 · RGB mapping"); const byte = (name: string) => within(screen.getByRole("group", { name })); const next = () => screen.getByRole("button", { name: "Next: Speaker" }); @@ -518,7 +569,7 @@ describe("setup wizard", () => { await click("Next: Speaker"); - await waitFor(() => expect(stepLabel()).toBe("Step 4 of 5 · Speaker")); + await waitFor(() => expect(stepLabel()).toBe("Step 5 of 6 · Speaker")); expect(robot.lastPost("/settings")?.json).toEqual({ rgb_order: "RGB" }); }); });