Ceilingpuck v3 final v0-2

CeilingPuck v4

160 mm circular ceiling-mount carrier board for an ESP32-S3-DevKitC-1, providing voice, audio, lighting, sensing, and field outputs in a single ESPHome device.

Status: active. Working board is hardware/ceilingpuck_v4_working.kicad_pcb. v4 is the cleanup/extension of v3, adding a PCM1808 ADC input.

What this is

• 160 mm round 4-layer PCB (F.Cu / GND inner / +24V inner / B.Cu)
• ESP32-S3-DevKitC-1 socketed via two 1x22 headers (J100/J101)
• Room-facing side (F.Cu): mics, PIR, mmWave, environmental sensors, XVF voice
• Ceiling-facing side (B.Cu): regulators, relays, Ethernet, audio I/O, LED outputs
• Powered from 24 V house feed, with 24V→5V and 5V→3V3 buck regulators
• Runs on ESPHome 2026.4.5

Repository layout

Documentation index

Start at docs/DESIGN.md and docs/PINOUT.md.

Hardware workflow

KiCad versions

• KiCad 10.0 (Docker kicad/kicad:10.0) for headless DRC/ERC, DSN export, SES import
• Local KiCad AppImage at ~/Desktop/kicad/ for interactive edits
• Freerouting v2.2.4 (hardware/tools/freerouting.jar) inside eclipse-temurin:25-jre

Backups (mandatory before edits)

python3 hardware/tools/backup_project_file.py <files...>

Backups land in backups/ with vYYYYMMDD-HHMM timestamps. KiCad files (*.kicad_sch, *.kicad_pcb, *.kicad_pro), markdown docs, YAML, and writer scripts under tools/ are protected.

Rerouting from scratch

Full runbook: rerouting.md. Short version:

1. Back up hardware/ceilingpuck_v4_working.kicad_pcb.
2. Strip routing inside KiCad 10 Docker (inline pcbnew script — do NOT use strip_all_routing_v4.py for the working board).
3. Export DSN with pcbnew, then patch it (clearance 200→300, In1/In2 → power, empty wiring, rectangular boundary).
4. Run Freerouting headless: --gui.enabled=false -da -dct 0 -mp 10 -mt 3.
5. Import SES + refill zones via ZONE_FILLER.
6. Run DRC and update hardware/logs_reports/.

Verification

After every KiCad edit, before considering the task done:

# Paren balance
python3 -c "from pathlib import Path; t=Path('hardware/ceilingpuck_v4_working.kicad_pcb').read_text(); d=sum(1 if c=='(' else -1 if c==')' else 0 for c in t); assert d==0; print('OK')"

# DRC
docker run --rm --platform linux/amd64 \
  -v "/home/mike/workspace/ceilingpuck_v4:/workspace" \
  kicad/kicad:10.0 \
  bash -c "kicad-cli pcb drc --format json \
    -o /workspace/hardware/logs_reports/drc_<label>.json \
    /workspace/hardware/ceilingpuck_v4_working.kicad_pcb"

Update the schematic version stamp in the top-left when changing *.kicad_sch: (at 25.4 12.7 0) → SCH YYYYMMDD-HHMM <prefix> (replace, do not stack).

Firmware workflow

ESPHome version pinned to 2026.4.5 (ghcr.io/esphome/esphome:2026.4.5). Do not pull :latest or :stable.

Top-level config: firmware/ceilingpuck.yaml. It includes packages from firmware/packages/:

Build / upload

Pre-OTA gate (per AGENTS.md): turn the device backlight off and set input_boolean.ota_in_progress = on in Home Assistant first.

docker run --rm \
  -v "$PWD/firmware:/config" \
  ghcr.io/esphome/esphome:2026.4.5 \
  run /config/ceilingpuck.yaml --device <ip-or-hostname> 2>&1 | tee /tmp/esphome-ceilingpuck.log

After OTA: clear input_boolean.ota_in_progress, review logs, disconnect after 15 minutes idle.

Tests

python3 -m pytest tests/test_properties.py

Validates pin assignments against the frozen v4 GPIO map in memory.md.

v4 GPIO map (frozen)

Source: memory.md. Canonical doc: docs/PINOUT.md.

Conventions

• All edits follow AGENTS.md (root). Smaller, evidence-driven changes; explicit backups; project log entries for approved changes.
• Do not commit, push, or create PRs unless explicitly asked.
• Long-running commands stream to /tmp/*.log via tee.
• KiCad and ESPHome work runs in Docker — no host installs.
• File backup format: backups/<rel-path>.bak.YYYYMMDD-HHMM. Cite the version as vYYYYMMDD-HHMM in chat.

License

(Add your chosen license here.)