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>
88 lines
No EOL
5 KiB
Markdown
88 lines
No EOL
5 KiB
Markdown
# Hardware - Bill of Materials and wiring
|
|
|
|
<!-- SPDX-License-Identifier: CERN-OHL-S-2.0 -->
|
|
|
|
OpenScribe v1 is built from off-the-shelf modules (no custom PCB). There are two build
|
|
options: a **compact** build for a wearable, and a **breadboard/dev** build that is easier
|
|
to bring up and debug. Pick one; the firmware and case are parametric to suit either.
|
|
|
|
## Build A - Compact (recommended for the wearable)
|
|
|
|
Uses the Seeed Studio XIAO ESP32-S3 Sense, which puts the MCU, PSRAM, a microphone and a
|
|
microSD slot on a thumb-sized board. Fewer wires, smallest case.
|
|
|
|
| # | Part | Spec / why | Qty | Notes |
|
|
|---|------|-----------|-----|-------|
|
|
| 1 | **Seeed XIAO ESP32-S3 Sense** | ESP32-S3, 8 MB PSRAM, 8 MB flash, WiFi + BLE 5, onboard PDM mic + microSD slot, USB-C, LiPo charge circuit | 1 | The mic + SD + charger are already on the "Sense" expansion board |
|
|
| 2 | **microSD card** | 16-32 GB, Class 10 / A1 | 1 | FAT32 |
|
|
| 3 | **LiPo battery** | 3.7 V, 400-600 mAh, JST-PH 1.25 mm | 1 | Fits the XIAO battery pads |
|
|
| 4 | **Tactile button** | momentary, 6 mm | 1 | Record start/stop, long-press = pair/config |
|
|
| 5 | **Status LED** | XIAO onboard user LED (or add 1 external + resistor) | 1 | Optional external RGB for richer status |
|
|
| 6 | (optional) **Vibration motor** | coin ERM + driver transistor | 1 | Haptic feedback like a NotePin |
|
|
| 7 | (optional) **Slide switch** | SPDT, for hard power cut | 1 | In line with the battery |
|
|
|
|
Notes on Build A:
|
|
- The XIAO Sense onboard mic is **PDM**, not I2S. The firmware supports both; PDM keeps the
|
|
compact build to one board. For best audio quality use Build B with an I2S MEMS mic.
|
|
- USB-C present = "on charge / hard-powered"; the firmware reads VBUS to switch to the
|
|
independent WiFi upload mode.
|
|
|
|
## Build B - Dev / best audio (breadboard or protoboard)
|
|
|
|
Discrete modules, easiest to probe, best microphone.
|
|
|
|
| # | Part | Spec / why | Qty | Notes |
|
|
|---|------|-----------|-----|-------|
|
|
| 1 | **ESP32-S3 dev board with PSRAM** | e.g. ESP32-S3-DevKitC-1 **N16R8** (16 MB flash, 8 MB PSRAM), WiFi + BLE 5, USB | 1 | PSRAM is required for audio buffering |
|
|
| 2 | **I2S MEMS microphone** | **INMP441** (default, cheap) or **ICS-43434** (better SNR ~65 dB) | 1 | Digital I2S, clean audio, no analogue front-end |
|
|
| 3 | **microSD breakout** | SPI or SDMMC (1-bit) microSD module | 1 | SDMMC 1-bit is faster if pins allow |
|
|
| 4 | **microSD card** | 16-32 GB, Class 10 / A1 | 1 | FAT32 |
|
|
| 5 | **LiPo battery** | 3.7 V, 500-1000 mAh, JST | 1 | Bigger cell OK on the dev build |
|
|
| 6 | **LiPo charger + protection** | **TP4056 with DW01 protection** module (USB-C), or **MCP73831** | 1 | STAT pin -> GPIO to detect charging |
|
|
| 7 | **Boost/regulator** | only if the board lacks a suitable 3V3 LDO from battery | 0-1 | Most dev boards handle this |
|
|
| 8 | **Tactile button** | momentary, 6 mm | 1 | Record start/stop, long-press = pair |
|
|
| 9 | **RGB status LED** | common-cathode or WS2812 | 1 | Idle / recording / uploading / error states |
|
|
| 10 | (optional) **Vibration motor + transistor** | coin ERM + 2N2222/AO3400 + flyback diode | 1 | Haptic feedback |
|
|
| 11 | Wires / protoboard / headers | - | - | For bring-up |
|
|
|
|
## Pinout (default, Build B - ESP32-S3)
|
|
|
|
These are the firmware defaults; all are overridable in `firmware/include/pins.h` (added
|
|
in M1). Avoid strapping pins (0, 3, 45, 46) and USB pins (19, 20).
|
|
|
|
| Signal | ESP32-S3 GPIO | Notes |
|
|
|--------|---------------|-------|
|
|
| I2S mic BCLK (SCK) | 4 | to mic SCK |
|
|
| I2S mic WS (LRCL) | 5 | to mic WS |
|
|
| I2S mic SD (DOUT) | 6 | mic data out -> ESP32 in |
|
|
| I2S mic L/R select | GND | selects left channel (mono) |
|
|
| microSD CLK | 12 | SPI SCK (or SDMMC CLK) |
|
|
| microSD CMD/MOSI | 11 | |
|
|
| microSD D0/MISO | 13 | |
|
|
| microSD CS (SPI) | 10 | SPI mode only |
|
|
| Record button | 7 | active-low, internal pull-up, other side to GND |
|
|
| Status LED (WS2812 data) | 48 | or plain LED via 330R on any free GPIO |
|
|
| Charger STAT (charging?) | 14 | input, from TP4056 STAT (open-drain) |
|
|
| VBUS present (on-charge) | 15 | via divider from 5V USB, or board VBUS sense |
|
|
| Vibration motor (optional) | 16 | via transistor |
|
|
|
|
For **Build A (XIAO Sense)** the mic is PDM and the microSD uses the Sense board's fixed
|
|
pins; the firmware ships a XIAO pin profile so no manual wiring table is needed.
|
|
|
|
## Power and modes
|
|
|
|
- **Portable (battery):** low-power; record on button; BLE advertising; WiFi on demand.
|
|
- **On charge / hard-powered:** detected via VBUS/STAT; device joins configured WiFi, runs
|
|
the REST API on the LAN, and uploads new recordings to the configured object store.
|
|
|
|
## Rough cost (indicative, GBP)
|
|
|
|
- Build A (compact): XIAO ESP32-S3 Sense ~£14, microSD ~£5, LiPo ~£5, button/bits ~£3.
|
|
**~£27** plus a printed case.
|
|
- Build B (dev): S3 devkit ~£10, INMP441 ~£4, SD module ~£3, TP4056 ~£2, LiPo ~£6, LED +
|
|
button + wires ~£5. **~£30** plus a printed case.
|
|
|
|
## Assembly
|
|
|
|
Wiring diagrams and assembly photos are added alongside the case in milestone M8. Until
|
|
then this table plus `firmware/include/pins.h` is the source of truth for connections. |