From b7cf2f533749a577cc801ddf317691995d0bd23f Mon Sep 17 00:00:00 2001 From: Luke Hoersten Date: Sun, 14 Jun 2026 11:15:09 -0500 Subject: Consolidate docs: merge DESIGN.md into README; sharpen status + roadmap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DESIGN.md was ~80% redundant with README.md (project summary, hardware, API contract, callback contract, scrypted integration, milestone acceptance criteria) and ~20% implementation guidance that's now better served by the source code itself + TESTING.md. Removed it and folded the unique parts into README. README.md additions: - "Status" table at the top: firmware, Scrypted side, hardware ā€” each with where-we-are + what's-pending columns. - "Firmware implementation notes" section: source map (one-line per main/*.{h,c} module), memory strategy, display strategy, error handling, coding standards. Replaces DESIGN.md sections 7-11, 15, 17. - "What's next" section before Philosophy: nine items in priority order, each linking the specific TESTING.md or scrypted/ section. Makes "pick up cold" trivial. - Philosophy section absorbed DESIGN.md's "Guiding Rule" as a blockquote at the bottom. - "Related docs" rewritten ā€” TESTING.md is now described as *the* self-contained verification reference. TESTING.md additions: - Preamble now describes the five-layer structure and the ā¬œ/šŸŸ”/āœ… legend. - New "Status snapshot" table ā€” milestones + code + HW at a glance. - New "Hardware prerequisites" ā€” table of what to confirm/order, plus a numbered list of the four open unknowns (DSI FPC pin count, IĀ²C jumper destinations, BOOT GPIO, flash silkscreen). - New "Recommended bench order" ā€” seven stages from "board on Ethernet over USB" through "integration suite," each with the commands or where-to-look. DESIGN.md deleted. Single source of truth is now README.md (spec + implementation notes + roadmap) and TESTING.md (verification reference). --- TESTING.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 5 deletions(-) (limited to 'TESTING.md') diff --git a/TESTING.md b/TESTING.md index 151fff2..20f377d 100644 --- a/TESTING.md +++ b/TESTING.md @@ -1,12 +1,97 @@ # Testing & Verification -This file tracks which milestones have been verified on hardware and how. Per-milestone entries below each list: +This file is the self-contained reference for verifying the firmware on real hardware. It has three layers: -- **Acceptance** ā€” what "done" means (mirrors the impl guide). -- **How to verify** ā€” exact commands or actions. -- **Status** ā€” ā¬œ not verified / šŸŸ” partial / āœ… verified, with a one-line note (date, board rev, anything weird). +1. **Status snapshot** ā€” at-a-glance state of every milestone. +2. **Hardware prerequisites** ā€” what to confirm or order before flashing anything. +3. **Recommended bench order** ā€” the sequence to flip šŸŸ” ā†’ āœ…, stage by stage. +4. **Per-milestone entries** (M1ā€“M9) ā€” acceptance criteria + exact commands/actions + status. +5. **Integration & system tests** ā€” to run after every per-milestone test passes. -Hardware-required milestones can't be verified by a clean build alone ā€” a checked-in build success counts as šŸŸ” (compiles, not yet run). +Status legend: + +- ā¬œ not verified ā€” code not yet exercised at all. +- šŸŸ” partial ā€” compiles cleanly, builds against ESP-IDF 5.4 for `esp32p4`, but not yet run on a board. +- āœ… verified ā€” confirmed on hardware. Annotate with the date and board rev. + +--- + +## Status snapshot + +| # | Milestone | Code | HW | +| --- | --- | --- | --- | +| M1 | Board Bring-Up ā€” Ethernet + DHCP | āœ… | šŸŸ” | +| M2 | HTTP + mDNS (`GET /state`) | āœ… | šŸŸ” | +| M3 | Display Bring-Up (Hosyond panel) | āœ… | šŸŸ” | +| M4 | Config Persistence (NVS, partial updates) | āœ… | šŸŸ” | +| M5 | JPEG Frame Push (`POST /frame`) | āœ… | šŸŸ” | +| M6 | State + Idle Timer (`POST /state`, 409 guard) | āœ… | šŸŸ” | +| M7 | Touch + Outbound `/state` POST | āœ… | šŸŸ” | +| M8 | Local Screens + BOOT button | āœ… | šŸŸ” | +| M9 | Live Stream (`POST /stream`) | ā¬œ | ā¬œ | + +--- + +## Hardware prerequisites + +Before flashing anything, confirm or acquire: + +| Item | Status as of this writing | How to resolve | +| --- | --- | --- | +| Waveshare ESP32-P4-ETH board | shipped | check silkscreen for flash size (16 vs 32 MB) ā€” adjust `sdkconfig.defaults` if 32 | +| Hosyond 5" 800Ɨ480 panel | shipped | n/a | +| 15-pin Pi-FPC ā†’ Waveshare-side DSI adapter cable | **unknown ā€” order before M3** | check Waveshare board DSI connector pin count, buy matching adapter | +| 4Ɨ jumper wires (5V / GND / SDA / SCL) | trivial | bench supply | +| Ethernet cable + DHCP-serving switch | trivial | LAN already in place | +| (optional) PoE injector | nice-to-have | for M1/M2 a USB-only power path is fine | + +Hardware unknowns that gate work: + +1. **DSI FPC pin count on the Waveshare board.** Research found 2-lane MIPI-DSI confirmed; pin count not verified. Open the schematic PDF and count. +2. **IĀ²C jumper destinations.** `display.c` defaults `PIN_I2C_SDA=7`, `PIN_I2C_SCL=8` ā€” matches Waveshare's BSP convention for their bundled panel kit but not specifically verified for this board. Confirm against schematic; adjust `display.c` if wrong. +3. **BOOT button GPIO.** ESP32-P4's strap pin (GPIO 35) is owned by RMII TXD1 at runtime, so the on-board user/BOOT button must be on a different GPIO. `button.c` currently uses `PIN_BOOT_BUTTON = 0` as a placeholder. Confirm from schematic; if wrong, the button silently never fires but the rest of M8 still works. +4. **Flash size silkscreen.** `sdkconfig.defaults` declares 16 MB. If your SKU shipped with 32 MB the build still works but you waste half the flash. + +--- + +## Recommended bench order + +Work through these stages in order. Each stage builds on the previous one's verified state. + +### Stage 1 ā€” board comes alive (M1 + M2) + +No display, no panel, no jumpers. Just board on Ethernet over USB. + +```bash +source ~/Dev/code/git/esp32/env.sh +idf.py -p /dev/cu.usbmodem* flash monitor +``` + +Check serial for `net_eth: got ip` then `curl http:///state | jq .` and `dns-sd -B _scrypted-viewport._tcp local.`. If both pass, flip M1 + M2 to āœ…. Stop here if you hit any issue ā€” debug Ethernet before adding more variables. + +### Stage 2 ā€” display panel (M3) + +Confirm the schematic-driven unknowns above, wire the four IĀ²C/power jumpers, plug the DSI cable, reflash, and look for `panel MCU id 0xC3` in serial. Color bars on screen ā†’ M3 āœ…. + +### Stage 3 ā€” protocol (M4 + M5 + M6) + +No new wiring. POST `/config`, send a JPEG, exercise wake/sleep, watch the idle timer fire. Run through the per-milestone curls below. + +### Stage 4 ā€” touch (M7) + +Tap the screen. Confirm the FT5426 acks on IĀ²C in the boot log. Stand up the flask receiver, configure the device to point at it, and watch outbound `/state` POSTs arrive. + +### Stage 5 ā€” local screens + BOOT (M8) + +Visual: fresh boot shows IP screen; wake shows loading screen; tap-press of the BOOT button overlays IP. If BOOT GPIO is wrong, the screens still work ā€” only the button feature stays cold. + +### Stage 6 ā€” end-to-end with Scrypted + +Paste `scrypted/scrypted-viewport.ts` into Scrypted's Scripts plugin, add a viewport device with the binding (camera picker dropdown), trigger the bound camera, watch the panel light up. + +### Stage 7 ā€” integration + +Run the suite at the bottom of this file (races, failures, longevity, etc.). --- -- cgit v1.2.3