Laurence
f84bbca80b
Answers "how do we emulate/lint this?" with runnable tooling for every part, and factors the pure firmware logic out so it is unit-testable on the host. What changed: - firmware/src/wav.h, firmware/src/httprange.h: pure, header-only WAV header builder and HTTP Range parser (no Arduino deps), so the tricky byte-layout and range logic can be tested on a PC. storage.cpp and api_http.cpp refactored to use them. - firmware/test/test_pure/: Unity tests for the WAV header fields and Range parsing (start-end, open-ended, clamped, unsatisfiable, non-bytes). Run: pio test -e native. - firmware/platformio.ini: add [env:native] (host tests) and [env:esp32s3_wokwi] (emulator build with default WiFi = Wokwi-GUEST so the API comes up in the sim). - firmware/wokwi.toml + firmware/diagram.json: Wokwi emulator harness (ESP32-S3 + microSD + button + LED). Note: Wokwi has no I2S mic part, so audio isn't emulated; the harness targets boot + WiFi + REST API. - firmware/src/main.cpp + config.cpp: bring up WiFi + API even if audio/SD init fails (device stays reachable, reports the fault via GET /device); compile-time default WiFi honoured when NVS is empty (used by the Wokwi build). - .forgejo/workflows/ci.yml: add native tests + cppcheck to the firmware job; new openapi job (openapi-spec-validator) and emulator job (Wokwi build, plus a full run when WOKWI_CLI_TOKEN is set). - docs/testing.md: the full emulate/lint guide for firmware, server, API, app, case. - state/: NOTES points at the guide; TODO reflects this branch. Why: - The firmware can't be flashed yet (no parts) and doesn't build on this dev host, so we need host-runnable checks. Pure-logic unit tests + OpenAPI validation run anywhere; Wokwi emulates boot/WiFi/API; CI compiles the real firmware. Verified locally: the OpenAPI spec validates (12 paths, 10 schemas). Notes: - Native tests and cppcheck run in CI (no compiler on the dev host). The Wokwi full run is skipped unless a WOKWI_CLI_TOKEN secret is present; the build is still verified. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|---|---|---|
| .forgejo/workflows | ||
| api | ||
| app | ||
| case | ||
| docs | ||
| firmware | ||
| hardware | ||
| LICENSES | ||
| server | ||
| state | ||
| .gitignore | ||
| CLAUDE.md | ||
| LICENSE | ||
| LICENSING.md | ||
| README.md | ||
OpenScribe
An open-source, self-hosted AI voice recorder in the style of the Plaud Note / NotePin. A small wearable device records audio to local storage, syncs to a mobile app and to a server you run, and produces transcripts and summaries, through a completely open API. No proprietary cloud, no lock-in.
Status: early scaffold (M0). The design, hardware BOM, and open API are defined; component code is being built milestone by milestone. See
state/TODO.md.
Why
Commercial AI recorders send your conversations to a vendor's cloud. OpenScribe keeps the whole pipeline (capture, storage, transcription, summarisation, export) on hardware you own, under open licences, with an API documented so you can build against it.
What it does
- Records voice to microSD on a small ESP32-S3 device (button start/stop, LED status).
- Syncs three ways:
- BLE for control, status and WiFi provisioning.
- WiFi to the mobile app for fast bulk transfer.
- Independent WiFi upload to your storage when on charge / hard-powered, with no phone present.
- Transcribes (faster-whisper) and summarises (local LLM via Ollama) on a server you host.
- Exposes a completely open REST API with exports: audio, TXT, SRT, VTT, Markdown, JSON.
- Ships a Flutter app (Android + iOS) and a 3D-printed parametric case.
Architecture at a glance
mic -> ESP32-S3 (record to microSD)
| BLE: control / provision
| WiFi REST API: transfer to app
| WiFi uploader (on charge) -> object storage (MinIO / WebDAV / NAS)
|
self-hosted server (FastAPI)
faster-whisper -> Ollama -> open API + exports
|
Flutter app (Android + iOS)
Full detail: state/ARCHITECTURE.md. The API contract:
api/openapi.yaml.
Repository layout
firmware/ ESP32-S3 recorder firmware (PlatformIO, Arduino-ESP32)
server/ Self-hosted FastAPI server: ingest, transcribe, summarise, serve API
app/ Flutter mobile app (Android + iOS)
hardware/ BOM, wiring/pinout, build notes (off-the-shelf modules, no PCB in v1)
case/ Parametric 3D-printed enclosure (OpenSCAD)
api/ openapi.yaml - the single source of truth for the open API
docs/ Workflow docs (this project follows the Default Workflow SOP)
state/ Project memory: PROJECT, ARCHITECTURE, DECISIONS, TODO, NOTES
LICENSES/ Full licence texts
Hardware
You build the device from off-the-shelf parts. See hardware/BOM.md
for the shopping list, wiring and pinout. Core: an ESP32-S3 board with PSRAM, an I2S MEMS
microphone, a microSD card, a LiPo battery and a charge IC.
Self-hosted stack
Everything runs on hardware you own: Forgejo for the forge, faster-whisper for transcription, Ollama for summaries, MinIO (or WebDAV / NAS) for storage. Plain recording and transfer work without any server; the server adds transcription and summaries.
Getting started
Nothing to run end to end yet (M0 scaffold). To follow along:
- Read
state/PROJECT.mdandstate/TODO.md. - Per-component build/run commands are in
state/NOTES.mdand each component'sREADME.md.
Licensing
Multi-part, copyleft. Code is GPL-3.0-only, hardware is CERN-OHL-S-2.0, case and docs are
CC-BY-SA-4.0. See LICENSING.md.
OpenScribe is an independent open-source project inspired by the Plaud class of device. It is not affiliated with or endorsed by Plaud.