Laurence
031074c9a9
Bootstrap of the project (M0). Sets up the monorepo, design docs, hardware BOM, the open API contract, component skeletons, licensing and CI, following the Default Workflow SOP. What changed: - CLAUDE.md + docs/: copied the Default Workflow so sessions load the SOP. - state/: PROJECT, ARCHITECTURE, DECISIONS, TODO, NOTES filled in for OpenScribe. ARCHITECTURE captures the four-part design (firmware, server, app, case) and the three sync paths; DECISIONS records the hardware, AI-stack, storage, app and licensing choices; TODO lays out milestones M1-M9. - hardware/BOM.md: two build options (compact XIAO ESP32-S3 Sense; dev ESP32-S3 + I2S mic + SD), wiring/pinout, indicative cost. - api/openapi.yaml: the completely open API (device + server surfaces), including recording list/download/delete and exports (wav/ogg/txt/srt/vtt/md/json). - firmware/: PlatformIO ESP32-S3 project, two board profiles, pin map, boot scaffold with module seams for M1-M4. - server/: FastAPI skeleton mirroring the OpenAPI, config for self-hosted MinIO, faster-whisper and Ollama; stub routes browsable at /docs. - app/, case/: Flutter app plan; parametric OpenSCAD enclosure. - Licensing: GPL-3.0 (code), CERN-OHL-S-2.0 (hardware), CC-BY-SA-4.0 (case/docs), REUSE-style LICENSES/ with SPDX headers; LICENSING.md explains the split. - CI: Forgejo Actions workflow builds firmware (both profiles) and lints/imports server. Why: - Everything self-hosted and openly licensed per the user's requirements: an open API, three sync paths (BLE control, WiFi transfer, independent WiFi upload on charge to generic cloud storage), and a full self-hosted transcription+summary stack. Notes: - No custom PCB in v1; off-the-shelf modules. Physical verification waits on parts. - Component code is stubs at M0; features land milestone by milestone, each as its own branch/PR per the workflow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
47 lines
2 KiB
Markdown
47 lines
2 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.
|
|
|
|
## Dead ends
|
|
|
|
- (none yet)
|