Laurence
87a00265a3
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>
78 lines
3.8 KiB
Markdown
78 lines
3.8 KiB
Markdown
# 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)
|