ws-ESP32-S3-CAM

ws-ESP32-S3-CAM

Workspace for the Waveshare ESP32-S3-CAM-GC2145 (SKU 33702, P/N ESP32-S3-CAM-GC2145) — the GC2145 DVP sensor variant of Waveshare's ESP32-S3-CAM-OVxxxx carrier board.

Full context, pinout, and vendor quirks live in CLAUDE.md.

Repo philosophy

This repo publishes firmware + tooling only — recordings, derived labels, trained classifier weights, and analyses that narrate real captures stay local. The datasets/ tree, lab notebooks under projects/*/ml-experiments/, and date-stamped narrative docs are gitignored. See CLAUDE.md "Publish boundary" for the full list.

Repo layout

ws-ESP32-S3-CAM/
├── CLAUDE.md                 # authoritative board notes + publish boundary
├── README.md                 # this file
├── .claude/
│   └── commands/             # /build /flash /monitor /ml-researcher /restore-factory ...
├── docs/
│   ├── blog/                 # public-facing writeups
│   └── research/             # public-info-sourced surveys, design + method docs
├── projects/
│   └── cry-detect-01/        # YAMNet-on-S3 baby-cry detector + auto-ensemble tooling
└── ref/                      # vendor docs + repos (gitignored, ~1.2 GB)
    ├── datasheets/           # ESP32-S3, GC2145, ES8311, ES7210
    ├── schematic/            # ESP32-S3-CAM schematic
    ├── wiki/                 # offline docs.waveshare.com snapshot
    └── demo/                 # ESP32-S3-CAM-OVxxxx + display-support vendor clones

Active projects

projects/cry-detect-01

Discreet bedroom baby-cry monitor. No camera, no screen — ES7210 mic → YAMNet-1024 INT8 (TFLite Micro) → SD-card CSV + SSE web UI + red-LED alert. Host-side data tools turn the resulting captures into auto-labelled training material via a 4-oracle ensemble (no human in the label loop).

Status (2026-04-25):

• Detector firing on real cries. After two firmware fixes — double-sigmoid removal in the YAMNet output path and a mel-feature magnitude-vs-power correction — the on-device cry_conf reaches 0.934 on real cries (matching FP32 YAMNet) versus 0.000 on silence. First ALERT_FIRED events (n=6 in one night) landed under the fixed firmware.
• Stage 2.7 file API live: remote /files/ls, /files/get, /files/tail, /files/df — pull logs without pulling the SD card.
• Local timezone: Sydney AEST/AEDT. Timestamps RFC-3339 with numeric offset (e.g. 2026-04-18T08:13:53.726+10:00).
• Host-side auto-ensemble label pipeline (tools/ensemble_audit.py) merges YAMNet wide-class scores, an acoustic-feature classifier, an embedding classifier on YAMNet's 2048-d meanmax, a sub-type cluster, and temporal context into per-capture confidence tiers. Method documented in docs/research/host-side-auto-ensemble-method.md.
• ML work follows the /ml-researcher discipline: pre-register hypothesis, stamp model versions, lab-notebook gitignored, conclusions only land as research notes.

Research notes

Public-eligible surveys, design docs, and method writeups under docs/research/:

ESP-IDF

• Version required: ≥ v5.5.1 (we use 5.5.3 at ~/esp/esp-idf)
• Activate: . ~/esp/esp-idf/export.sh (source it; Claude Code will prompt for the . builtin — answer yes once per session)

Build / flash / monitor

. ~/esp/esp-idf/export.sh
idf.py -C projects/cry-detect-01 -B /tmp/ws-cry-detect-01-build build
idf.py -C projects/cry-detect-01 -B /tmp/ws-cry-detect-01-build -p /dev/cu.usbmodem3101 flash

Monitoring: idf.py monitor is broken in non-TTY shells — use the pyserial snippet in .claude/commands/monitor.md.

Hardware quick-reference

Full authoritative pinout in CLAUDE.md.

Differences from sibling repos

The sibling C6 project's rule-based detector serves as the empirical baseline for judging whether cry-detect-01's ML model is finding events that actually occurred.

Sibling repos

Waveshare board workspaces built with the same agentic-first workflow. If a technique is missing here, it is probably solved in one of the others.