Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
35b8a77
feat(extension): add Waveshare LCD1602 support with REST API for text…
jamro Nov 14, 2026
cd6820d
feat(extension): implement serial support for LCD1602 with unified AP…
jamro Nov 14, 2026
43567ed
feat(firmware): enhance Waveshare LCD1602 support with auto-detection…
jamro Nov 16, 2026
2a3f989
feat(extension): add RGB color control for Waveshare LCD1602 with upd…
jamro Nov 16, 2026
c67f74a
feat(firmware): implement smooth brightness fading for Waveshare LCD1…
jamro Nov 17, 2026
4e95e14
feat(cursor): add LCD1602 support for displaying remaining AI budget …
jamro Nov 17, 2026
45bb8e0
feat(cursor): enhance LCD1602 integration with opt-in AI budget displ…
jamro Nov 17, 2026
5442d44
feat(firmware): rename `lcd1602_backlight_boot` to `lcd1602_backlight…
jamro Nov 17, 2026
7ff68c6
feat(firmware): add `lcd1602_welcome_hello` setting for optional HELL…
jamro Nov 17, 2026
683a8c7
docs(firmware): introduce LCD1602 welcome overlay feature with settin…
jamro Nov 17, 2026
7ff5527
refactor(firmware): optimize row key management by introducing unique…
jamro Nov 17, 2026
3ec4035
fix(ui): improve formatting in ApiReference and Extensions views for …
jamro Nov 17, 2026
c82646f
docs(api): update LCD1602 settings examples and clarify backlight beh…
jamro Nov 17, 2026
68b8cb2
refactor(api): streamline LCD1602 settings application by introducing…
jamro Nov 17, 2026
09c856d
refactor(cli): enhance error handling in parseFlags and runLcd1602 fu…
jamro Nov 17, 2026
66d6453
refactor(api): update LCD1602 settings handling to enforce stricter v…
jamro Nov 17, 2026
ec259ec
refactor(cursor): enhance cookie resolution and command spawning with…
jamro Nov 17, 2026
a0d94ae
refactor(api): enhance extension-serial method handling to support bo…
jamro Nov 17, 2026
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
68 changes: 66 additions & 2 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Listens on **port 80** after STA Wi-Fi connects, or during setup AP mode at `htt

Outbound events (device → host) use a separate WebSocket on **port 81** at path `/events` while this HTTP server is running, and the same JSON on USB serial as `Evt` frames. See [Outbound events](#outbound-events).

Optional auth: when an `access_token` is configured in settings, all JSON API routes require `Authorization: Bearer <token>`. Empty token (default) means no auth. `GET /auth` is always public and reports whether auth is required. Missing/wrong token → **401** `{"ok":false,"error":"unauthorized"}`. HTML panel routes stay public (the UI prompts for the token). Replies are `Content-Type: application/json`. Routes that take parameters (except `POST /anim` and `/play`) read a JSON object body sent with `Content-Type: application/json`; query parameters or form fields on those routes → **400** `send a JSON body with Content-Type: application/json`, and a body that is not a JSON object → **400** `body must be a JSON object`. CORS: requests with an `Origin` header get `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Headers: Authorization, Content-Type` and `Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS`; a preflight `OPTIONS` gets **200**.
Optional auth: when an `access_token` is configured in settings, all JSON API routes require `Authorization: Bearer <token>`. Empty token (default) means no auth. `GET /auth` is always public and reports whether auth is required. Missing/wrong token → **401** `{"ok":false,"error":"unauthorized"}`. HTML panel routes stay public (the UI prompts for the token). Replies are `Content-Type: application/json`. Routes that take parameters (except `POST /anim` and `/play`) read a JSON object body sent with `Content-Type: application/json`; query parameters or form fields on those routes → **400** `send a JSON body with Content-Type: application/json`, and a body that is not a JSON object → **400** `body must be a JSON object`. CORS: requests with an `Origin` header get `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Headers: Authorization, Content-Type` and `Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`; a preflight `OPTIONS` gets **200**.

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)).

Expand Down Expand Up @@ -171,6 +171,12 @@ curl http://tiny-engineer.local/settings
"serial_log": false,
"push_button": false,
"push_button_pin": 20,
"lcd1602": false,
"lcd1602_backlight_sleep": true,
"lcd1602_welcome_hello": false,
"lcd1602_boot": "none",
"lcd1602_line1": "",
"lcd1602_line2": "",
"continuous_timeout": 5,
"loading": "progress",
"eyes_style": "classic",
Expand All @@ -194,6 +200,11 @@ curl http://tiny-engineer.local/settings
| `serial_log` | USB serial debug logging (default **false**). When off, diagnostic `Serial` output is suppressed |
| `push_button` | Extension-port push-button reader (default **false**). When on, publishes immediate `button.down` / `button.up` plus `button.click` / `button.double_click` / `button.long_click` (see [Outbound events](#outbound-events)). Applies **immediately**. Local reactions use [Actions](#get-settingsactions) |
| `push_button_pin` | GPIO on the Extension port for the push-button: **6**, **7**, **20**, or **21** (default **20**). Persists when `push_button` is off. Applies **immediately** when the extension is on |
| `lcd1602` | Waveshare LCD1602 I2C extension (default **false**). When on, serves `/extensions/lcd1602/…`. Applies **immediately**. Emits no events |
| `lcd1602_backlight_sleep` | Follow sleep: dim backlight on sleep and light to **100** on wake (default **true**). When false, enable/boot turns backlight on (including when `last` brightness is 0) and sleep/wake leave brightness alone. Persists when off. Applies **immediately** |
| `lcd1602_welcome_hello` | Show centered **HELLO** / **HUMAN** on the LCD during every `welcome` animation (default **false**). Text/clear during the overlay queues (last-wins); `GET` returns logical stash/pending, not HELLO. Persists when off. Applies **immediately** |
| `lcd1602_boot` | Boot content: `none`, `last`, or `config` (default **`none`**). Persists when off. Applies **immediately** |
| `lcd1602_line1` / `lcd1602_line2` | Configured boot lines when `lcd1602_boot` is `config` (max **64** chars each, no C0 control bytes, default empty). Persists when off. Applies **immediately** |
| `continuous_timeout` | Minutes a continuous animation (`typing` / `reading` / `thinking` / `talking`) may run before the firmware switches to `attention` then idle (default **5**) |
| `loading` | Boot loading screen: `progress` (bar + large IP for 3 s) or `sleep_inertia` (eyes wake; no bar/IP). Default **`progress`**. Applies on **next reboot** |
| `eyes_style` | OLED eyes look: `classic` (procedural rounded eyes), `kaomoji` (animated faces), `cover` (full-half bars for an eye-hole mask), `dots` (12×12 circles), or `kawaii` (round eyes with big moving pupils, a talking mouth, and blush). Default **`classic`**. Applies **immediately**. Classic, cover, and dots sequences are described under [`POST /anim`](#post-anim); kaomoji face mapping is under [Kaomoji eyes](#kaomoji-eyes); cover drawing is under [Cover eyes](#cover-eyes); dots drawing is under [Dots eyes](#dots-eyes); kawaii moods are under [Kawaii eyes](#kawaii-eyes) |
Expand All @@ -209,12 +220,15 @@ curl http://tiny-engineer.local/settings

### `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`, `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`, 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.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

```bash
curl -X POST "http://tiny-engineer.local/settings" \
-H "Content-Type: application/json" \
-d '{"volume":40,"welcome":false,"eyes_style":"kaomoji"}'
curl -X POST "http://tiny-engineer.local/settings" \
-H "Content-Type: application/json" \
-d '{"lcd1602":true,"lcd1602_boot":"config","lcd1602_line1":"HELLO","lcd1602_line2":"HUMAN"}'
curl -X POST "http://tiny-engineer.local/settings" \
-H "Content-Type: application/json" \
-d '{"access_token":""}'
Expand All @@ -233,6 +247,12 @@ curl -X POST "http://192.168.4.1/settings" \
"serial_log": false,
"push_button": false,
"push_button_pin": 20,
"lcd1602": false,
"lcd1602_backlight_sleep": true,
"lcd1602_welcome_hello": false,
"lcd1602_boot": "none",
"lcd1602_line1": "",
"lcd1602_line2": "",
"continuous_timeout": 5,
"loading": "progress",
"eyes_style": "classic",
Expand All @@ -257,6 +277,11 @@ curl -X POST "http://192.168.4.1/settings" \
| `serial_log` | boolean | USB serial debug logging |
| `push_button` | boolean | Extension-port push-button (default **false**) |
| `push_button_pin` | integer | Extension-port GPIO **6**, **7**, **20**, or **21** (default **20**); persists when off |
| `lcd1602` | boolean | Waveshare LCD1602 extension (default **false**) |
| `lcd1602_backlight_sleep` | boolean | Dim on sleep / light on wake (default **true**) |
| `lcd1602_welcome_hello` | boolean | HELLO/HUMAN on welcome (default **false**) |
| `lcd1602_boot` | string | `none` / `last` / `config` (default **`none`**) |
| `lcd1602_line1` / `lcd1602_line2` | string | Boot lines for `config` (max **64**, no C0 control bytes) |
| `continuous_timeout` | integer | 1–1440 minutes (positive) |
| `loading` | string | `progress` or `sleep_inertia` |
| `eyes_style` | string | `classic`, `kaomoji`, `cover`, `dots`, or `kawaii` |
Expand Down Expand Up @@ -352,6 +377,12 @@ curl -X POST "http://tiny-engineer.local/settings/reset"
"serial_log": false,
"push_button": false,
"push_button_pin": 20,
"lcd1602": false,
"lcd1602_backlight_sleep": true,
"lcd1602_welcome_hello": false,
"lcd1602_boot": "none",
"lcd1602_line1": "",
"lcd1602_line2": "",
"continuous_timeout": 5,
"loading": "progress",
"eyes_style": "classic",
Expand Down Expand Up @@ -538,6 +569,39 @@ Wrong fields return **400**:

Save with `POST /settings` `{"oled_rotate_180":true}` (setup AP only). The saved value applies immediately and on the next boot.

### LCD 1602 extension (`/extensions/lcd1602/…`)

Waveshare LCD1602 I2C (AiP31068 @ `0x3E`; controllable backlight SN3193 @ `0x6B` or PCA9633 @ `0x60`, auto-detected) on the Extension I2C port. Off until `lcd1602` is true. Same access class as `POST /anim` (`Configured`). When the extension is off → **503** `extension disabled`. When on but the LCD (`0x3E`) does not ACK → text **POST**/`DELETE` **503** `lcd not found` (settings stay enabled); **GET** text still returns the cached logical state with **200**. When the LCD is up but neither backlight chip ACKs → brightness **POST** **503** `backlight not found`; **GET** brightness still returns the cached value with **200**. On PCA9633, brightness scales the base RGB color (`PWM = channel × brightness / 100`); use `/color` for base R/G/B. Color on SN3193 → **400** `rgb not supported`. When `lcd1602_backlight_sleep` is true, entering sleep (`sleep` anim or idle `sleep_timeout`) fades backlight to **0** over ~2 s; wakeup / wake-from-sleep fades to **100** over ~2 s (persists last state). When false, sleep/wake do not change backlight. When `lcd1602_welcome_hello` is true, every `welcome` animation overlays centered **HELLO** / **HUMAN**; text/clear during that overlay queues until welcome ends; `GET` text returns logical content (pending or pre-overlay), not HELLO. No outbound events.

#### `GET` / `POST` / `DELETE /extensions/lcd1602/text`

`GET` returns the full logical lines (not only the 16-column viewport), including when the LCD does not ACK (**200** cached state). `POST` / `DELETE` without an ACK → **503** `lcd not found`.

```json
{
"line1": { "text": "HELLO", "align": "left" },
"line2": { "text": "", "align": "left" }
}
```

`POST` accepts a partial JSON body. Omitted `line1` / `line2` leave that line unchanged. Each present line object needs `text` (0–64 chars; empty clears the line) and optional `align` (`left` / `right` / `center`, default **`left`**). Lines longer than 16 characters ignore align and marquee LTR.

```bash
curl -X POST "http://tiny-engineer.local/extensions/lcd1602/text" \
-H "Content-Type: application/json" \
-d '{"line1":{"text":"HELLO","align":"center"}}'
```

`DELETE` clears both lines and leaves brightness unchanged.

#### `GET` / `POST /extensions/lcd1602/brightness`

`GET` → `{"brightness":50}` (cached logical value; **200** even when no backlight chip ACKs). `POST` body `{"brightness":0..100}` (0 = backlight off). Neither SN3193 nor PCA9633 ACK on **POST** → **503** `backlight not found`. On PCA9633, brightness scales the stored base color (default white `255,255,255`). Successful text/clear/brightness/color updates persist **last** state for `lcd1602_boot=last`.

#### `GET` / `POST /extensions/lcd1602/color`

PCA9633 RGB modules only. `GET` → `{"r":255,"g":255,"b":255}`. `POST` body `{"r":0..255,"g":0..255,"b":0..255}` sets the base color (PWM scaled by current brightness). SN3193 (or other non-RGB backlight) → **400** `rgb not supported`. No backlight chip → **503** `backlight not found`.

### `POST /servos/park`

Flash-safe park: stop the current animation, smoothly move every joint to its calibrated mid, persist the pose to NVS, and keep PWM enabled until the next reboot (skips idle limp). No body. Requires Bearer when auth is enabled. Available in setup AP and after provisioning (does not require a chosen connection mode).
Expand Down
5 changes: 4 additions & 1 deletion docs/hardware/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,10 @@ 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`, `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`, `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 |
Expand Down
1 change: 1 addition & 0 deletions docs/hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,5 +198,6 @@ Config: [`.cursor/hooks.json`](../.cursor/hooks.json). Local anim hook: [`.curso
- Robot offline → hook still exits 0; no agent stall.
- Animation API holds each pose ≥1s and keeps only the latest pending switch — see [`api.md`](api.md).
- The onboard RGB LED follows the active animation (white for typing/reading/thinking/talking/welcome/ring/wakeup, pulsing red for attention/error/dead, solid red for abort, off for `none`/`sleep`) with 1 s fades between non-pulse states — see [RGB LED](api.md#rgb-led).
- After a completed turn (`stop` → `ring`), the CLI may update an enabled LCD1602 with remaining Cursor AI budget (`AI BUDGET:` / `NN.NN%`). **Opt-in:** set `TINY_ENGINEER_AI_USAGE_LCD=1` in user config (`~/.config/tiny-engineer/env`) or enable during `tiny-engineer setup` (interactive prompt, or `--ai-usage-lcd` / `--no-ai-usage-lcd`). Uses the local Cursor web session (Keychain / IDE state DB). The LCD extension is optional: missing session, slow cursor.com, disabled LCD, or robot errors are silent and never change the hook exit code.
- To change the map, edit [`packages/tiny-engineer-cli/src/integrations/cursor/map.js`](../packages/tiny-engineer-cli/src/integrations/cursor/map.js).
- Custom agents or non-Cursor IDEs: call the [REST API](integration.md#2-rest-api-advanced--custom).
6 changes: 5 additions & 1 deletion docs/serial.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,11 @@ Before another program opens the USB serial device, run `tiny-engineer daemon re
- **Provisioning:** while unprovisioned or in setup AP, only sync/ping and `servos_park`. Full API after a connection mode is chosen (Wi‑Fi or USB-only). Serial does **not** use Bearer auth.
- **Busy:** long play holds a global busy lock; a second play (HTTP or serial) gets `busy`.

Ops (JSON `op`): `ping`/`sync`, `servos_park`, `anim`, `settings.get`/`settings.set`, `test`, `servo`, `health`, `factory_reset`, `play` / `play_end`, plus stream data/credit/error frames.
Ops (JSON `op`): `ping`/`sync`, `servos_park`, `anim`, `settings.get`/`settings.set`, `ext`, `test`, `servo`, `health`, `factory_reset`, `play` / `play_end`, plus stream data/credit/error frames.

`settings.get` / `settings.set` over serial include a **LCD slice** (`lcd1602`, `lcd1602_backlight_sleep`, `lcd1602_welcome_hello`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`) so USB-only hosts can enable the Waveshare module. Other HTTP settings fields (wifi list, actions, push_button, …) may still be missing on serial — full GET `/settings` parity is a follow-up.

`ext` mirrors HTTP `/extensions/<id>/<suffix>`: `{ "op":"ext", "id":"lcd1602", "suffix":"text"|"brightness"|"color", "method":"GET"|"POST"|"DELETE", ...body }`. Same disabled/validation/hardware errors as HTTP. CLI: `tiny-engineer ext lcd1602 text|brightness|color …`.

## PlatformIO monitor

Expand Down
Loading
Loading