Skip to content
Open
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
16 changes: 12 additions & 4 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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"]
}
```
Expand Down Expand Up @@ -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" \
Expand All @@ -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}'
Expand Down Expand Up @@ -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
}
Expand Down Expand Up @@ -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 <field>`. A field with the wrong type or out of range → **400** `invalid <field>` (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 <field>`. A field with the wrong type or out of range → **400** `invalid <field>` (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`

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
}
Expand Down
4 changes: 2 additions & 2 deletions docs/hardware/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
8 changes: 8 additions & 0 deletions docs/robot-movement.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions docs/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions openspec/changes/face-me/.openspec.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-18
Loading
Loading