| Age | Commit message (Collapse) | Author | Files | Lines |
|---|
|
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).
|
|
local_screens.{h,c}:
- Embedded 8x8 bitmap font sized to a 95-char table; only the glyphs
used by today's strings (viewport.local, the IPv4 string, Loading...)
are populated. Unsupported chars render blank.
- 768 KB PSRAM scratch FB at panel-native dims.
- local_screens_show_ip() ā two centered lines:
"viewport.local"
<current IP>
Scale 3x portrait / 4x landscape; centered vertically.
- local_screens_show_loading() ā centered "Loading..." at scale 4x/5x.
- local_screens_restore_for_state() ā repaint after BOOT-overlay expiry:
UNCONFIGURED -> IP screen; AWAKE/ASLEEP -> black FB (next /frame or
sleep handles the rest).
- All paths go through display_present_rgb565() so orientation rotation
is automatic.
button.{h,c}:
- Polling task at 30ms, active-low with internal pull-up.
- Short press (<5s, released) ā backlight on, IP overlay for 15s via
esp_timer one-shot, then restore.
- Hold ā„ 5s ā nvs_config_reset() + esp_restart().
- PIN_BOOT_BUTTON = GPIO 0 is a TODO placeholder. ESP32-P4 strap pin
GPIO35 is owned by RMII TXD1 at runtime so Waveshare must expose a
separate user button on a free pin; confirm against the schematic.
Fail-soft if mis-wired: input reads stuck-high and the task never
fires.
state_machine on AWAKE transition now calls local_screens_show_loading()
right after display_wake() ā so every wake (tap or POST /state) flashes
a clear "Loading..." until the next /frame paints over it.
app_main on boot:
- Calls local_screens_init() after display_init().
- UNCONFIGURED ā paint IP screen (replaces the M3 test pattern).
- ASLEEP ā backlight off (unchanged).
- After all subsystems: button_init().
Build clean against ESP-IDF 5.4 (binary ~870 KB; the font/glyph data is
under 800 bytes).
TESTING.md M8 documents the visual checks, the BOOT-pin placeholder
caveat, the AWAKE-overlay-overwrite behavior, the open follow-up about
post-overlay backlight when ASLEEP, and the font fallback policy.
|
|
state_client.{h,c}:
- Worker task drains a depth-1 queue (xQueueOverwrite gives the
replace-on-full semantics from the spec ā in-flight POST is never
cancelled; the next queued entry is overwritten by newer state).
- esp_http_client POST to <scrypted>/state with Content-Type application/
json, User-Agent ScryptedViewport/<version>, Connection: close, 1s
timeout. Body: {"viewport":"<name>","state":"wake"|"sleep"}.
- Any non-2xx or transport error increments state_post_failures and is
otherwise ignored. Silently drops if no Scrypted URL is configured.
touch.{h,c}:
- FT5426 capacitive touch on the shared I2C bus at 0x38.
- 30ms polling task; tracks down/up transitions, detects taps as
down-then-up within 500ms with a 150ms debounce.
- On tap, toggles wake/sleep via state_machine_set_local(), which drives
the local transition AND fires state_client_post() at Scrypted.
state_machine adds state_machine_set_local(): runs the same transition
as state_machine_set() then enqueues an outbound POST. Idle-timer
expiry now uses this path so Scrypted sees idle-driven sleeps too
(the spec's "tighten the race with /frame 409" path stays in place as
the fallback).
display.h exposes display_i2c_bus(); touch.c uses it instead of
re-initializing the same I2C port.
app_main starts state_client right after the state machine and starts
touch after display init (touch is skipped if display isn't up since
they share the bus).
CMakeLists.txt: add esp_http_client to REQUIRES.
Build clean against ESP-IDF 5.4 (binary ~860 KB; jumped ~210 KB from
M6 because esp_http_client + cJSON path pulls in tcp_transport, mbedtls,
http_parser).
TESTING.md M7: flask-based test receiver, tap dispatch verification,
failure-path check (kill receiver, confirm counter increments),
queue-coalescing behavior, no-POST-on-Scrypted-initiated, no-POST-
when-unconfigured.
|
|
state_machine.{h,c} ā central wake/sleep transitions:
- state_machine_init() creates the esp_timer one-shot for the idle timer.
- state_machine_set(target) is idempotent and atomic. On AWAKE: backlight
on, idle timer (re)armed. On ASLEEP: idle timer cancelled, backlight off.
Rejects with INVALID_STATE when the device is unconfigured.
- state_machine_frame_painted() restarts the idle timer if awake; called
by /frame after each successful paint.
- Idle-timer callback transitions to ASLEEP. TODO M7 hook: outbound POST
{viewport, state:sleep} to <scrypted>/state.
http_api.c:
- POST /state: parse {state}, accept "wake"/"sleep", reject others 400.
Unconfigured device ā 409 "device unconfigured". Already-in-state ā 204
(idempotent no-op). Successful transition ā 204.
- POST /frame: 409 Conflict when state != AWAKE. After successful paint,
call state_machine_frame_painted() so the idle clock keeps resetting
while frames stream.
app_main:
- Initialize state_machine before http_api so the route handler can drive
it from request 0.
- After display_init(), reconcile the panel with the boot state:
UNCONFIGURED ā test pattern (placeholder until M8 IP screen)
ASLEEP ā display_sleep() so a configured device boots dark
AWAKE ā leave on (not reached on fresh boot)
Disable path: idle_timeout_ms=0 in /config means the timer is never armed
and a wake state persists until /state {sleep} or a power cycle.
Build clean against ESP-IDF 5.4 (binary ~645 KB).
TESTING.md M6 expands with idempotency checks, 409-when-asleep, 409-when-
unconfigured, idle-timer firing within idle_timeout_ms+slack, /frame
restarting the idle timer, idle-timer disable via idle_timeout_ms=0, and
the M7 dependency note about the missing outbound sleep POST.
|
|
jpeg_decoder.{h,c} wraps esp_driver_jpeg (ESP32-P4 hardware decoder).
- One-time engine + DMA-aligned PSRAM scratch buffer setup (1 MB input,
768 KB output @ panel native 800x480 RGB565).
- try_lock + unlock so concurrent /frame POSTs get 503 instead of
queueing, per spec.
- jpeg_decoder_get_info() reports the dimensions; the http handler
validates them against the effective resolution before painting.
display.h adds display_present_rgb565(src, w, h):
- Landscape: src is 800x480, memcpy 1:1 into the panel framebuffer.
- Portrait: src is 480x800, software rotate 90Ā° CW into the 800x480
panel framebuffer. (PPA / 2D-DMA hardware rotation is a later
optimization if portrait latency matters.)
http_api.c adds POST /frame:
- Content-Type must be image/jpeg ā else 400.
- Empty body ā 400. > 1 MB ā 413. Display not initialized ā 500.
- jpeg_decoder_try_lock(0) for concurrency: second post returns 503.
- Body streamed into the decoder's input buffer in chunks.
- Decode failure or dimension mismatch ā 400 + decode_errors++.
- Paint failure ā 500.
- Success ā frames_received++, last_frame_us = esp_timer_get_time(),
204 No Content.
app_main initializes the JPEG decoder after display_init(). Both are
best-effort: failures log a warning and leave the rest of the firmware
running.
CMakeLists.txt: add esp_driver_jpeg to REQUIRES.
Known gap (M6 closes it): /frame currently paints regardless of
wake/sleep state. The 409-when-asleep rule lands with POST /state
in M6.
Build clean against ESP-IDF 5.4 (binary ~640 KB).
TESTING.md M5 expanded with portrait/landscape test commands,
ImageMagick test-image recipes, the full negative matrix (wrong
Content-Type, oversize, wrong dims, concurrent, garbage), and the
M6 dependency note.
|
|
nvs_config.{h,c} ā persist the runtime config (viewport, scrypted,
idle_timeout_ms, orientation, brightness) under a single NVS namespace.
nvs_config_load() applies persisted values over the in-RAM defaults on
boot and flips state from UNCONFIGURED to ASLEEP once both name and
Scrypted URL are present. nvs_config_save() commits the whole record
atomically.
http_api.c ā add GET /config and POST /config:
- GET serializes viewport_state to the spec's JSON shape, with null
for unset string fields and defaults filled in for the rest.
- POST is partial: each field is optional; only present fields are
validated and applied. Validation runs on a staged copy and errors
short-circuit with 400 + reason before any state mutation, so a
rejected request leaves the device untouched.
- Validation rules: viewport non-empty <64 chars; scrypted starts with
http:// and <256 chars; idle_timeout_ms 0 or >=5000; orientation in
{portrait,landscape}; brightness 0..100.
- Side-effects fire after the lock + save: brightness change pushes
PWM to the panel MCU; viewport/orientation change reapplies mDNS
hostname + TXT.
- 204 on success; 400 with a single-line reason on validation error.
app_main calls nvs_config_load() right after viewport_state_init(), so
mdns_service_start() and display_init() see the persisted hostname,
orientation, and brightness from the first packet/PWM.
Build clean against ESP-IDF 5.4 (binary ~620 KB).
TESTING.md M3 now documents the Hosyond jumper wiring (5V/GND/SDA=GPIO7/
SCL=GPIO8 from board to panel header; DSI FPC carries only the high-
speed lanes). M4 entry expands the validation matrix and side-effects
to verify.
|
|
- viewport_state.{h,c}: shared state struct (config, run-state, counters,
orientation, timestamps) behind a FreeRTOS mutex. Modules update it
under viewport_state_lock(); GET /state serializes a snapshot.
- http_api.{h,c}: starts esp_http_server on :80, registers GET /state.
Returns the full JSON shape from the spec (name, version, configured,
state, uptime_ms, last_frame_ms_ago, frames_received, decode_errors,
state_post_failures, resolution, ip, free_heap, free_psram).
- mdns_service.{h,c}: mdns_init + advertise _scrypted-viewport._tcp.local
on :80 with version/resolution/orientation/name TXT records.
mdns_service_refresh() reapplies hostname + TXT after /config writes
(called from M4 onward).
- main/CMakeLists.txt: add esp_http_server, esp_timer, json, mdns to
REQUIRES. espressif/mdns added as managed component via
main/idf_component.yml.
app_main calls viewport_state_init early so any module can read defaults
before /config arrives.
Also adds TESTING.md tracking per-milestone verification status and an
integration test plan to run after M9 (races, failure modes, longevity,
power cycles, negative protocol, multi-viewport).
M1 promoted to "š” builds clean" in TESTING.md; combined HW verification
of M1+M2 will be one flash session. Build verified against ESP-IDF 5.4
for target esp32p4 (binary ~550 KB).
|
