Add Waveshare S3 Tubes remote shell

[theysayheygreg]

Summary

Adds a Waveshare ESP32-S3-Touch-AMOLED-2.16 Tubes v14 remote target with a 16 MB partition contract, 60-pixel null virtual strip, local AMOLED/touch field shell, and additive canonical device-report identity.

The local UI provides Home, Conductor, Surveyor, and read-only Updater surfaces. It observes display, touch, power-monitor/IMU presence, and local radio status; it cannot claim conductor authority, drive a physical LED bus, or write peer firmware.

Scope and caveats

• Based independently on canonical main; RELEASE_VERSION remains 14.
• Adds TubeHardwareWaveshareS3 to the existing versioned device-report family enum; no packet/action ID changes.
• Does not include Anchor, spatial, Mobile Conductor, Pattern/Hello/Purple experiments, host diagnostics, promo/reference assets, or actual peer update enablement.
• Changes platformio_tubes.ini, not global platformio.ini. The new custom environment, partition CSV, null bus type, and pinned display/touch libraries warrant maintainer review.
• Display, touch, PMU/IMU presence, and radio behavior are compile/contract verified only; exact-board runtime behavior remains untested.

Validation

• npm ci && npm run build
• npm test — 28 tests passed in the combined run
• node --test tools/s3-partition-contract-test.js tools/tubes-s3-virtual-output-test.js — 12 tests passed
• test/tubes_mesh/run.sh
• test/tubes_upgrade/run.sh
• pio run -e waveshare_s3_tubes_remote — success; RAM 14.7%, flash 18.9%
• git diff --check

No physical device was contacted or flashed. No generated web headers are included.

---

Working-set coordination — 2026-08-14

This draft is one of three independent contribution rails based on Steve's main:

• Easy Flash: Add participant-safe Easy Flash recovery #65
• Waveshare S3 Remote: Add Waveshare S3 Tubes remote shell #66
• P2P Updater Foundations: Add peer updater foundations #67

Shared rules:

• Steve's packet, hardware-identity, and release-metadata contracts remain canonical.
• Keep the deployed 84-byte Tubes v2 State frame unchanged during migration.
• Distinguish Tubes protocol version, Tubes release, WLED base version, hardware target, and runtime profile.
• Use broad firmware classes: Legacy (pre-v14), Current (v14/WLED 16), Next (v15/new protocol), and Unknown. Missing evidence remains Unknown.
• v15 should advertise release/build identity and capabilities through Steve's additive versioned protocol—not a branch-local packet ID.
• Firmware variants represent hardware/compiled boundaries only. Art, role, palette, tempo, pattern, spatial policy, and installation identity remain runtime configuration.
• Any shared contract change is checked against all three drafts before one advances.

Current thinking

The S3 is a self-running local instrument and operator surface. Surveyor and Updater consume nearby-device identity; they do not define the canonical identity protocol. Updater remains read-only until exact target, image, lease, transfer, and health contracts are available.

Firmware display should use Legacy / Current / Next / Unknown. A valid v14 device report can prove Current. No reply must remain Unknown. v15 should identify itself explicitly through Steve's new protocol.

TODO

• Validate display, touch, AMOLED brightness, PMU/IMU presence, and ESP-NOW behavior on the exact Waveshare board.
• Consume nonce/MAC-validated v14 device-report replies in Surveyor.
• Consume the future canonical v15 identity/capability broadcast without changing legacy State packets.
• Show broad firmware classes without guessing from protocol v2 or a missing reply.
• Keep the nearby-device Updater surface read-only until the P2P admission/session contracts are integrated.
• Preserve local Conductor strip state; incoming sync may inform diagnostics but must not overwrite it.

---

Recursive review hardening — 2026-08-14

Follow-up commit c99960cf resolves the recursive review blockers without importing protocol or authority changes from the richer S3 worktree.

• Replaced the product-specific type-95 null bus with generic TYPE_VIRTUAL_FRAMEBUFFER_RGB (83) inside the documented virtual-output class, with compile-time range/uniqueness assertions and explicit non-network dispatch.
• Restored normal BusManager::add() behavior. The S3 target rejects incompatible physical/network or extra framebuffer configuration before mutation or pin allocation; Tubes idempotently owns exactly one logical framebuffer. Allocation failure returns -1 and ERR_NORAM_PX.
• Added a bounded read-only Tubes snapshot adapter. The shell now separates hardware family, report protocol, Tubes release, WLED version, and compatibility; unproven compatibility stays Unknown with explicit future v14/v15 adapter boundaries.
• Enforced S3 update/reboot/selection denial at the controller receive/operation boundary, isolated one-time I2C probes, and bounded preview redraws to changed cells.
• Added AI/source attribution and mixed-family/golden-layout host invariants. Dig2Go receives no S3 logical-output or read-only flags; deployed packet/action IDs and layouts remain unchanged.
• platformio_tubes.ini remains explicitly maintainer-approval-gated; global platformio.ini is unchanged.

Validation: npm ci && npm run build; npm test (34 tests); focused S3/mixed-family tests (10/10); native Tubes mesh tests (10/10); Tubes upgrade tests; S3 firmware compile (RAM 14.8%, flash 19.0%); S3 partition/application contract; Dig2Go compile regression (RAM 25.8%, flash 79.7%); git diff --check. No device was contacted or flashed.

---

Final authority capability correction — 2026-08-14

Commit 23d294e4 closes the remaining recursive-review Important finding at the owning Tubes controller/API boundary.

• Under TUBES_READ_ONLY_FIELD_SHELL, RoleOperation is rejected before the role switch. Local lowercase r and selected/incoming/forwarded uppercase R therefore cannot reach setRole(), EEPROM persistence, reboot scheduling, or role relay effects on the Waveshare S3 target.
• Command parsing, r/R bindings, operation/wire IDs, action layout, and the legacy RoleOperation implementation are unchanged. Dig2Go and other families do not define the S3 capability flag and retain existing role behavior.
• The S3 UI statement “Authority changes disabled” now matches the controller boundary.

Validation: focused S3/mixed-family invariants 10/10; npm test 34/34; native tubes_mesh 10/10; S3 compile RAM 14.8% / flash 19.0%; Dig2Go compile RAM 25.8% / flash 79.7%; git diff --check. The first concurrent compile attempt encountered an npm dependency-install race; both targets then passed sequential clean reruns. No device was contacted or flashed. No reviewer was requested and the PR remains draft.

Central update-contract integration checkpoint — 2026-08-14

This source PR remains independently based on Steve main. A disposable integration worktree proved read-only consumption of PR #67's generated contract. Reviewed adapter commits: bd476b6f and 5f484469.

• Canonical S3 target and partition facts feed the existing copied Tubes snapshot/UI adapter.
• Installed classification remains Unknown without complete positive evidence.
• No canonical S3 artifact exists; real, mutated, and fabricated artifacts are rejected.
• Updater remains capability-denied for update, erase, reboot, role, session, and source behavior.
• The PlatformIO target/partition change still requires maintainer approval.
• Reconstruct these adapter commits only after the canonical contract is accepted; do not permanently stack the open PRs.

Zero-pixel logical framebuffer hardening — 2026-08-15

Commit adad692c fixes the confirmed zero-count logical framebuffer failure without changing palette behavior, physical buses, network buses, or Dig2Go.

• TUBES_NULL_OUTPUT now compile-time asserts PIXEL_COUNTS > 0, so the fixed Waveshare S3 logical-output profile cannot silently build a zero-pixel framebuffer.
• BusVirtualFramebuffer refuses zero before allocation and cannot become valid from allocator-specific calloc(0, ...) behavior.
• BusManager::add() rejects a zero-count logical framebuffer with the normal ERR_NORAM_PX path before idempotence or insertion; the bus collection remains unchanged.
• Added a compiled host C++ regression using a zero-byte allocator sentinel, plus structural S3/manager ordering coverage. Positive framebuffer counts still allocate and insert.
• The separate latent palette-count modulo candidate remains ledger-only and is intentionally unchanged in this commit.

Validation: host framebuffer regression passed; focused S3/mixed/partition tests 18/18; npm test 34/34; native Tubes mesh tests 10/10; S3 partition/application contract passed; S3 compile succeeded (RAM 14.8%, flash 19.0%); Dig2Go regression compile succeeded (RAM 25.8%, flash 79.7%); git diff --check passed. No device was contacted or flashed. No reviewer was requested and the PR remains draft.

[theysayheygreg]

The clean Waveshare S3 work is superseded by PR #69, whose third commit (1343f099) carries the product value and truthful limitations. Retaining this branch for history; closing this PR.

[theysayheygreg]

Correction: the replacement updater PR #70 is target-only for Waveshare S3. Product direction for Home, Conductor, Surveyor, touch/display development remains independent and is not superseded by this updater work; no reopen is needed.