laurence/openscribe
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
openscribe/state/NOTES.md
Laurence 87a00265a3
Some checks failed
ci / server (pull_request) Failing after 27s
Details
ci / firmware (pull_request) Failing after 36s
Details
feat(firmware): M2 WiFi + on-device REST API 
Adds the WiFi-to-app sync path and the on-device open REST API implementing the
device paths of api/openapi.yaml, plus persistent config in NVS.

What changed:
- firmware/src/config.{h,cpp}: NVS (Preferences) store - stable device id from MAC,
  WiFi SSID/PSK, API bearer token, upload settings. Secrets stay off the SD card.
- firmware/src/net_wifi.{h,cpp}: station join with stored creds; SoftAP provisioning
  fallback when no creds / join fails; mDNS openscribe.local; reconnect in loop().
- firmware/src/api_http.{h,cpp}: synchronous WebServer on :80. Routes: GET /device,
  GET/PUT /device/config, GET /recordings, GET /recordings/{id}, GET
  /recordings/{id}/audio (HTTP Range -> 206 + Content-Range), DELETE /recordings/{id},
  POST /record/start|stop. Bearer-token auth on mutating calls (open when no token).
- firmware/src/storage.{h,cpp}: list/read/delete/count helpers + path builders.
- firmware/src/main.cpp: wire config + WiFi + API into setup/loop; bump fw to 0.2.0.
- firmware/platformio.ini: add bblanchon/ArduinoJson@^7 (only new dep).
- state/: ARCHITECTURE, NOTES, TODO updated; security + NTP follow-ups recorded.

Why:
- This is the WiFi transfer channel and the device half of the "completely open API":
  clients can list, download (resumable), delete and control without any cloud.

Notes:
- Not compiled locally (no PlatformIO on the dev host) or hardware-verified; CI builds
  both board profiles. Security follow-ups logged: API is open when no token is set,
  and the SoftAP uses a fixed default passphrase (make user-set at M4/BLE).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-03 12:09:41 +01:00

3.8 KiB
Raw Blame History

Notes

Working notes, gotchas, environment quirks, and dead ends to avoid. Free form. The point is to save a future session from rediscovering something the hard way.

How to run / build / test

Per component (see each component's README for detail):

  • Firmware (firmware/): PlatformIO.
    • pio run - build for the ESP32-S3 target.
    • pio run -t upload - flash over USB.
    • pio device monitor - serial console.
  • Server (server/): Python 3.11+.
    • python -m venv .venv && . .venv/Scripts/activate (Windows) or .venv/bin/activate.
    • pip install -r requirements.txt
    • uvicorn app.main:app --reload - dev server (OpenAPI at /docs).
  • App (app/): Flutter.
    • flutter pub get then flutter run. (Full Flutter project is created in M7.)
  • Case (case/): OpenSCAD. Open case/openscribe_case.scad; render/export STL.

Environment

  • Forge: https://git.discworld.casa/laurence/openscribe (Forgejo). Git auth via Windows Credential Manager (user laurence); the Forgejo API accepts it via basic auth. Never print or commit the token.
  • Dev host: Windows 11, PowerShell primary + Git Bash. Project root c:\temp\dev\openscribe.
  • Self-hosted services for the server (run on a NAS / mini-PC, not required for plain recording): MinIO (S3), Ollama (LLM), and faster-whisper (pip install, downloads models on first run).

Gotchas

  • ESP32-S3 board choice matters: pick a variant WITH PSRAM (e.g. N16R8, or XIAO ESP32-S3) for audio ring buffers. Classic ESP32 / Pico W are fallbacks with less headroom.
  • Windows + PlatformIO: install the CP210x/CH34x USB serial driver or the board will not enumerate a COM port.
  • WAV at 16 kHz mono 16-bit is ~115 MB/hour; transfer over WiFi, not BLE. Opus is a later size win but costs CPU on the S3.
  • iOS restricts background BLE: use BLE only for control/provisioning; do bulk transfer over WiFi.
  • Do not put object-store credentials or WiFi passwords on the microSD in clear; they live in ESP32 NVS.

Firmware specifics (M1)

  • I2S/PDM via the core-bundled ESP_I2S (I2SClass) - no extra lib_deps. Dev board uses I2S_MODE_STD (INMP441/ICS-43434); XIAO uses I2S_MODE_PDM_RX (onboard mic).
  • SD uses a dedicated HSPI bus (SPIClass(HSPI)) so it does not clash with other SPI use.
  • WAV writer streams a 44-byte header then patches RIFF/data sizes on close by seeking.
  • Recording ids are uptime-based until NTP lands (M2); metadata started_at is null until then. See the follow-ups in TODO.md.
  • Not yet compiled locally (no PlatformIO on the dev host) - CI builds both profiles.

Firmware specifics (M2)

  • REST API served by the core-bundled synchronous WebServer on port 80. Path params via server.on("/.../{}" , ...) + server.pathArg(0). collectHeaders is required to read Authorization and Range. Register /recordings/{}/audio before /recordings/{}.
  • Audio download implements HTTP Range (206 + Content-Range) by seeking the file and streaming with sendContent; full GET sends Accept-Ranges: bytes.
  • Only new dep is bblanchon/ArduinoJson@^7 (request parse + JSON responses). WiFi, WebServer, ESPmDNS, Preferences, SD are all core-bundled.
  • WiFi: station mode with stored creds; on no-creds/failure it opens a SoftAP OpenScribe-<macsuffix> (pass openscribe) so the API is reachable to provision WiFi. mDNS name is openscribe.local.
  • Config/secrets live in NVS (Preferences namespace openscribe), never on the SD card.

Security follow-ups (before any real deployment)

  • API auth is open when no token is set (convenient on a trusted LAN). Set an api_token via PUT /device/config to require Authorization: Bearer on mutating calls; consider requiring it for reads too. Tracked in TODO.
  • SoftAP uses a fixed default passphrase; make it user-set during provisioning (M4/BLE).

Dead ends

  • (none yet)