Next public mergeback: sensor DRDY and ESP32-S3 RGB/touch
Decision and evidence boundary
Prepare two independent tranches. First port the generic retained open-drain resolver and opt-in autonomous data-ready events, then apply the bounded LSM303AGR descriptors. Prepare RGB565/GT911 as a separate functional-model change. Integrate the output resolver with the existing open device-output PR before publishing it. RGB changes require an explicit validation-drift acknowledgement decision because they touch the S3 silicon watch.
This map compares upstream 3e227a9b3b8332b38d33a721d2662b237a185ebb with public fork d543a46bba894f9e7e3aa31cdba6feb561b2d08e. Findings below come from local source/diff inspection on 2026-11-10. Test names and commands describe available tests and required acceptance; this review did not run them. Fork documentation and commit messages are not independent test or silicon evidence.
Port selected hunks against current upstream. The fork rebased/reconciled its history: broad commits with unrelated subjects contain necessary registration and initialization lines. Whole-commit cherry-picks would also import unrelated models, receipts, performance changes or old examples. Keep the established release/CI lanes and performance thresholds. Keep user examples in the separate examples repository; use core test fixtures or an explicit pinned examples input for guest regression sources.
1. Retained open-drain outputs
Source and extraction order
| Step | Exact public source commits | Required scope |
|---|---|---|
| Resolver and retained pad state | ac659c89, 7cf71c2f | New crates/core/src/bus/open_drain.rs; named drivers keyed by device/role and sampled GPIO address/bit. |
| Attachment, resolution and clock-gated restoration | d85eef69, 30b8162f, ffd79fa2 | bus/device_hooks.rs, peripherals/kit/ctx.rs, resolver and tests/tier2_device_pins.rs. Explicit open_drain_pullups placement option. |
| Explicit collector inversion and configuration rejection | e1421d48, d0e46c74, ff5af144 | Same production files; inverting_collectors is explicitly opt-in. Preserve malformed-pad, duplicate/unknown-role and mixed-mode rejection. |
| Required initialization hunks hidden in broad commits | 4cdd97db, 952fa635 | Only pub mod open_drain, SystemBus.device_open_drain_nets, and its default initialization in bus/construct.rs, bus/from_config.rs, bus/tests_main.rs. Do not take the surrounding SAMD51/LEDC work. |
Already upstream: declarative output roles, output-pin binding, queued I2C device drives, GPIO sampling seams, timers/rule execution, and GPIO observers. Missing: retained multi-driver resolution, per-pad pull-up declaration and explicit collector inversion. This is distinct from existing MCU GPIO open-drain output semantics.
Current source contract: a registered driver starts released. A false level pulls low; a true level releases. All drivers must release before the pad reads high. Collector inversion maps a high source to a low shared line. A missing binding remains disconnected. A configured malformed binding is rejected. The resolver does not model floating voltage, propagation, push-pull contention or arbitrary circuit nets. Source: resolver, attachment.
Acceptance and integration requirements
- Exercise two independent sinks on one real GPIO: both released, A low, B low, release A while B remains low, then release B. Check the sampled pad and edge observation.
- Verify retained high/low state survives initial attachment while the GPIO clock is gated and becomes visible when it opens.
- Test direct plus inverted drivers; duplicate/unknown roles; inverted roles not declared open drain; mixed legacy/open-drain attachment in both orders; malformed present pad; and valid unconnected role.
- Preserve a cheap empty fast path. Measure the bound path with its retained-net service enabled; do not adopt unrelated fork performance rebaselines.
- Run
tier2_device_pinsplus the resolver unit tests. Use the fork's shared-line guest as the guest-level reference. Its current build assumesarm-none-eabi-gccand assembly underexamples/microbit-v2; resolve that fixture dependency without recreating the examples tree in core.
Guest provenance includes 0f0a3ee9, b7156579, 26cad6d3, f4be2b08, 5b87b328 and 68aa1c03. Select the final fixture behavior, including real TWIM transactions and absent-address rejection.
2. Autonomous data-ready and LSM303AGR
Source and scope
| Layer | Exact public sources | Port scope |
|---|---|---|
| Generic event | 91935e5c | crates/config/src/rules.rs; components/declarative_i2c.rs, declarative_gpio.rs, declarative_uart.rs, rule_machine.rs. Add Event::DataReady, serialization, declared-name validation and opted-in device-clock completion. |
| Cancellation and deterministic ordering | bfc30fb5, 097527df | declarative_i2c.rs; preserve legacy unsubscribed read-driven promotion. |
| Required validation hardening | c31cd9c5, 16c46a4e, 708af5f8, b190d804 | Reject ambiguous zero-time conversions and rule/FIFO/implicit writes to subscribed start controls. These are part of the feature, not optional cleanup. |
| Sensor descriptors and acknowledgement groups | e8e760bb, 1870ba54, 8c820d92 | crates/config/src/peripherals.rs adds DataReadyRead/clear_on_read_all; core acknowledgement state; configs/devices/lsm303agr_{accel,mag}.yaml; micro:bit placement and guest fixtures. |
| Scheduler-profile acceptance | 8f2d638c | Keep source-level scheduler-on/off guards and guest intervals. Extract relevant tests only. |
Already upstream: both LSM303AGR YAML devices, conversion readiness overlays, explicit simulation-time advancement, read acknowledgement, output rules and the micro:bit TWIM path. The old fork Rust LSM303AGR implementation is superseded; do not port it.
Current source contract: only subscribed conversions complete autonomously. The device orders multiple elapsed deadlines deterministically and fires once per conversion. Stopping an in-flight conversion cancels it; an already-ready result remains until acknowledged. The implementation rejects a descriptor that combines data-ready subscriptions with device timers. It also rejects other writers that bypass the subscribed start register's lifecycle, while preserving self-clearing GO-command behavior. Source: current engine.
The accelerometer requires every enabled output high byte, in any order, before group acknowledgement. The magnetometer accepts any output high byte. Neither a low byte nor a status read is an acknowledgement. The board configuration explicitly inverts the native sensor outputs into the shared P0.25 pulled-up line. The KL27 participant is absent.
Limit claims to the source: timing remains 10 ms regardless of selected ODR; samples remain live rather than BDU-latched; overrun/FIFO/threshold behavior is absent. Magnetometer qualification is bounded to continuous 100 Hz with threshold routing off. Idle reconfiguration retention is an internal consistency policy, not demonstrated silicon behavior. References: accelerometer descriptor, magnetometer descriptor.
Acceptance
- No register polling: advance time to just before and at the conversion deadline; require the pin edge exactly once. Stop/rearm before deadline and ensure no stale completion.
- Advance across two deadlines in one call and verify deterministic ordering. Require load errors for timer combinations, missing/duplicate conversion names, zero duration and lifecycle-bypassing writers.
- Check legacy descriptors without subscriptions retain prior behavior.
- Accelerometer: enabled-axis subsets, arbitrary high-byte order, low-byte/status non-acknowledgement, repeated reads, no enabled axes, route/polarity changes, enable-after-ready, active rearm and idle retention. Check ready bits and IRQ agree.
- Magnetometer: high-byte-only acknowledgement, route masking/reenabling, cancellation and ready retention.
- Run the focused config/engine tests and
microbit_v2_mag_drdy_guest,microbit_v2_sensor_drdy_guest,microbit_v2_open_drain_guestwith and withoutevent-scheduler, using the fixture's declared tick intervals. Add a negative control with autonomous completion disabled so guest assertions cannot pass through polling alone.
3. ESP32-S3 RGB565, ST7701 and GT911
Main source: 184359726288d048ef315d4fa4e99f1f737208a0. Its 16-file diff adds 2,226 lines and removes 19; it combines engine, board, fixture and optional browser-input work. Split the port by dependency.
| Slice | Actual production scope and dependencies |
|---|---|
| RGB transport | esp32s3/lcd_cam.rs, esp32s3/gdma.rs, new components/rgb_panel.rs; add the Peripheral::attach_rgb_panel capability from b627fafc. |
| Panel and touch | New components/st7701.rs and components/gt911.rs. Extract module exports and only these two kit registrations from broad 0efad509. Do not import its unrelated ST7735/legacy sensor registrations. |
| Board and regression fixtures | configs/systems/esp32-4848s040.yaml, crates/core/tests/esp32s3_rgb_s040.rs, tests/fixtures/esp32-4848s040/{build_probe.py,probe.elf,check_wasm.cjs,README.md}, bounded board documentation. Adapt semihost smoke/fixture registration only if needed for the existing test lane. |
| Optional browser pad stimulus | The same source commit adds wasm/src/inputs.rs set_gpio_external and wasm/src/lab_tools.rs journal/replay support. Pair with the S3 unbonded-pad guard from 952fa635. This is a separate generic API; touch uses the already-existing set_inputs interface. |
Already upstream: S3 CPU/boot, GPIO bank 1, PadPort external hold/release, I2C controller, LCD_CAM i80, GDMA, scheduler hooks, octal PSRAM/MMU, GPIO observers, component inputs and framebuffer artifacts. Absent at the pinned base: RGB frame receiver, RGB cyclic descriptor walker, ST7701, GT911 and RGB attachment capability. Bank-1 support is not a new fork feature; rejecting physical GPIO22–25 holes is a remaining fork delta.
Current source behavior: the RGB walker reads guest descriptors and data through the bus, rejects invalid/unaligned/CPU-owned descriptors and failed reads, observes ownership writeback, handles EOF within circular chains, and caps a burst at the active frame boundary. Odd descriptor splits preserve half pixels. LCD completion queues its existing scheduled event after the temporarily borrowed LCD model is restored. i80 retains its existing transfer path. ST7701 consumes GPIO 9-bit control edges and emits a 480×480 rgb565_be artifact with display/sleep/backlight state. GT911 keeps a report stable once observed until zero-write acknowledgement; later movement coalesces into the next report; held-contact refresh uses simulation time. See LCD_CAM, GDMA, GT911.
Do not promote fork claims beyond this boundary: VSYNC is a completed DMA active-area event, not calibrated PCLK/porch timing. RGB pin mux and waveform generation are absent. The GT911 I2C route is metadata, not a wrong-pin NACK check. Touch is one contact with a modeled 10 ms period; reset/address strapping, gestures and EEPROM persistence are absent. The committed original bare ELF does not qualify arbitrary Arduino/LVGL firmware. The fork's board guide itself records no physical S040 validation.
Acceptance
- Rebuild the original fixture from its Python generator and compare its artifact hash. Do not substitute host drawing hooks.
- Run
esp32s3_rgb_s040together with unchangedesp32s3_lcd_i80_pixels, both default and--features event-scheduler. - Require asymmetric corner/stride checks, odd descriptor boundaries, byte/bit order, finite completion and W1C VSYNC, cyclic memory resampling, reset/stop with a partial frame, real mapped-PSRAM reads, and owner/writeback behavior.
- Missing, short, inaccessible, malformed, CPU-owned and unsupported-format inputs must not manufacture a completed frame. Ensure failures surface as appropriate descriptor errors.
- Exercise ST7701 sleep/display/reset/backlight, GT911 status/coordinate/ack coherence, and an actual guest down/move/up redraw. Run the GT911 unit tests and the Node WASM fixture when shipping a browser bundle.
- If extracting the pad API, validate finite integer pins before narrowing, reject 22–25 and out-of-range pins, test bank-0/bank-1 independence, hold/release, failed-call non-journaling and replay equivalence.
- Test negative controls with RGB completion disabled and touch state fixed. The acceptance suite must detect missing model behavior, not merely firmware progress.
4. Open-PR overlap and publication gates
The cached 2026-11-10 open-PR list contains 51 entries. No title specifically names these sensor/RGB features. This is not proof of no code overlap. The following overlaps were checked from locally available commits; branch heads may advance.
| Open PR and locally inspected head | Concrete consequence |
|---|---|
| #1727, 946a5a5a8e558060440e4b4cb6164a2303a1ae94 | Direct semantic overlap. It adds device-to-device observers and all-pad fanout in device_hooks, plus bus fields/constructors, kit/ctx and tier2_device_pins. The fork still selects the first matching pad and rejects repeated device/role bindings globally. Preserve #1727's observer-only bus servicing and fanout; apply retained resolution independently per destination pad. Specify raw source-observer versus resolved-pad semantics and test both. |
| #1695, c1f4bcc7778688248cc8657305adf7e7b203019f | Confirmed shared device_hooks, bus constructors/config, Peripheral, component exports and kit registry. Reconcile its timing/control foundation rather than replacing shared files. |
| #1681, c72f25baedf3710152af3713f86b12d3ca841bcd | Confirmed overlaps in declarative I2C/config, output binding, bus setup and kit registry. Local branch differs from the older 100-file API cache; use the exact local commit noted here. |
| #1663, 0e53269478d47c4d85bbe30826bef580dc31389d | Confirmed declarative I2C/config and bus/Peripheral overlaps. Its broad platform work is not a prerequisite for these ports. |
| #1802, 5ebf4b591a77be1faa3e32f6e3417bc409921bb7; #1799, 116391f3c6e278027d135f1d0e81c6cc7084ee4c | Nearby S3 display/ADC work, but no source-path overlap found in this map's bus/component/LCD_CAM/GDMA/kit scope at these local heads. Recheck when rebasing. |
| #1739 | SAMD21 platform work may touch common paths. Its head was not present locally in this review; no exact code-overlap claim. |
The pinned validation manifest watches exact files and directory prefixes. For the proposed generic resolver/DRDY production paths, no silicon-backed watch overlaps were found; bus/from_config.rs participates in 22 simulation-derived records. RGB's esp32s3/lcd_cam.rs, gdma.rs and optional gpio.rs all match the silicon-backed esp32s3 directory watch, plus the simulation-only S3-Zero record. Peripheral also participates in three simulation-derived records.
Regenerate simulation-derived records through the existing tooling and preserve historical capture and acknowledgement values. The S3 source-content digest changes when RGB is ported. Source-only drift is informational and requires no human source-review acknowledgement. A passing test suite does not extend the old nine-register reset-state capture to RGB/touch. Qualify the tranche with the normal automated gates and describe its simulation evidence and physical capture limits accurately.
Next concrete work: compose retained-net + autonomous-event patches on a base reconciled with #1727, carry the validation guards with the feature, and prepare the sensor fixtures. Keep RGB transport, the board model and the optional browser pad API separately reviewable, with the acceptance evidence and S3 gate decision attached.