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