Skip to content

Light HUB75 panels from a Pi 5's PIO - #260

Merged
ewowi merged 2 commits into
MoonModules:mainfrom
AnjinMeili:pr3b
Nov 21, 2026
Merged

ewowi merged 2 commits into
MoonModules:mainfrom
AnjinMeili:pr3b

Conversation

@AnjinMeili

@AnjinMeili AnjinMeili commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

PR 3b of the Pi HUB75 series: the light side of the Raspberry Pi 5 output, on the engine and seam #258 merged. The HUB75 driver drives panels from a Pi 5's 40-pin header through the PIO: a Hub75PioOutput on PR 2's Hub75Output interface, the layout cut into lanes of panels, the driver's case tree over the machine query, and the bench page #258 pointed to, with the A/B/A' table retaken on the kernel's ioctl backend and a 6.12 run.

What it changes.

  • On a Pi 5 the HUB75 card offers the PIO as its peripheral and shows the Pi's settings: rows and columns of one panel, panels per lane, the pixel clock and the latch blank. A saved card keeps them, the 8-bit depth included, through a boot where the PIO refuses.
  • The layout sets the geometry: its lights, cut into whole panels, become the panels, up to 32 in series on each lane, on up to three lanes. A layout that does not cable into the lanes is refused, and the status says why and, unless the layout holds less than one panel, the arrangements that would cable. Panel rows are 16, 32 or 64.
  • The card's shown control reads the refresh the panels run at. The status warns while submits fail, while a submit stalls, above the benched 20 MHz, or after a close the kernel left unfinished.
  • On a Pi 3 or 4 the card shows the Pi card and says HUB75 in this build needs a Pi 5's PIO.
  • One driver per peripheral, on every machine: a second driver that asks for LCD_CAM, Parlio or the Pi's header while another holds it stays idle and says why (siblingClaims() and kBlockInUse, the guard ParallelLedDriver.h held, moved up into DriverBase.h). On an ESP32 this is new for HUB75: a HUB75 driver now yields LCD_CAM to a strip driver holding it.
  • Every HUB75 driver, the ESP32's included: the status is computed from state in one order (a light-scratch shortage, the output's warning, a gain-table shortage, then the output's description), so a shortage the base raises stays visible through a prepare and the per-second refresh.
  • Every driver that reports heap beside its ScratchBuffers (HUB75, parallel LED, preview, RMT): publishHeapBytes() moves the memory readout by the change in the driver's own allocations, so each ScratchBuffer's count stays in it. Before, it set an absolute total that left the scratch buffers out, and a release with a wiring wider than RGB wrapped the readout below zero (2^64 - 32 with a 32-channel wiring, measured on this branch before the fix; main has the same lines). The commit review met it here, and it is fixed here.
  • New files: Hub75PioOutput.h (the output), Hub75PiOutput.h (what a Pi output shares: the cut, the fit, the lane canvas, the status), Hub75Canvas.h (where a light sits on the lane canvas, and the cabling arrangements with the refresh each predicts), Hub75Fit.h (whether the panels cable into the lanes, and the messages).
  • platform/Hub75Pio.h states the lane count and the panels-per-lane limit once; the light side and platform/rpi read them, so light/ includes no platform/rpi header. hasHub75Pio in the three platform_config.h.
  • Docs: hub75-panels.md gains the Pi 5 section (the kernel interface, its kernels, the pins the kernel may own, the pixel clock and refresh, 8-bit color); hub75-bench.md is new, the bench record; help.json regenerated. The two references Add the Pi 5 PIO engine for HUB75, through the kernel's /dev/pio0 interface #258 made ahead to 3b (hub75_pio_engine.h citing the bench page, and the pico-examples row linking drivers.md#hub75) now land.
  • Tests: five new test files and a shared bench (hub75_pi_bench.h) that reads what the host port's recording seam kept of what the output handed it; cases in two existing files (unit_Hub75Driver_output.cpp, unit_Hub75Encode.cpp), the Hub75Driver row in unit_ModuleContract.cpp, and helpers in correction_presets.h and hub75_port.h.
  • No MIGRATING entry: the new controls take their defaults, and the card's other controls are main's.

The size is over the guideline. 36 files, +3,142/−104 against 8044271 (main with #259), against 400 lines and ten files:

Part Files Lines
src/light/drivers/ 10 +992/−74: four new headers (737), the driver, the output interface, the base, and small changes to the ESP32 output, ParallelLedDriver and LedPeripheral
src/platform/ 9 +29/−18: the two limits, hasHub75Pio, the hold-word formula
Tests 13 +1,940/−9
Docs 4 +181/−3: the Pi 5 section, the bench page, help.json, mkdocs.yml

It is the second half of PR 3, split at the pre-flight; 3a, the platform, merged as #258. It was cut from c9b8baf and rebased onto main after #259, with one conflict in Hub75Driver.h (main's hasWindowControls() beside a reworded comment, both kept). The generated metrics are left to the merge.

Costs, stated rather than fixed.

  • Memory: with more than one panel per lane, a lane canvas of 3 bytes a light, which the readout counts; 147,456 bytes on the 256x192 wall. With one panel per lane, none.
  • On a host build the driver object is over the 2 KB inline budget (unit_ModuleContract.cpp's row): the PIO output sits inline with its 512-byte status text. An ESP32 image carries none of the PIO output.
  • CPU on the wall at 6.18 (below): the process used 52.7 to 58.8% with live content, against the piolib build's 53.8 to 69.5%; its busiest thread held 20.5 to 20.9% at every clock.
  • Once a second, and on prepare and a rewiring, the status is chosen again by a size check, the output's warning, the gain flag and the output's text, and stored as a pointer; nothing is formatted for it.

On the wall. My Pi 5 wall: three lanes of two 128x64 panels, 256x192, built as a release is by release.yml's build-linux-arm64 job (GCC 12.3, under act). Full tables and settings are on the bench page; its 6.12 column is the build before the commit review's fixes, which the final build matches within 1 fps.

  • Kernel 6.18.60, A/B/A' against the piolib build, three readings of 5 s at every bit depth and clock: shown within 2 fps of piolib everywhere. This ran on the build before the commit review's fixes; the fixes touch the status, the readout, the rows refusal, where two limits are stated, two lines of the predicted refresh that give the same value on the wall, and comments, and leave the engine, the frame path and the panel timing as they were.
  • Kernel 6.12.109 on Raspberry Pi OS Lite, this change before its rebase onto Add the fleet clock, looks pushed to a group, and a wall of devices drawing one picture #259, installed from its .deb; the package from Add the Pi 5 PIO engine for HUB75, through the kernel's /dev/pio0 interface #258 had given the service user /dev/pio0's group at the first install: 75 / 149 / 182 fps at 8-bit 5 / 10 / 20 MHz, within 1 fps of the earlier build on the same card. Within 1 fps of 6.18 at 5 MHz and higher above it with the same Hub75 settings; the cause is untraced, the kernel the hypothesis.
  • Ten close-and-reopen cycles in one process on each kernel (on 6.18 with the build before the fixes): a median 2.01 s (6.18) and 1.99 s (6.12) to a shown rate. OE read high after a service stop on both, so the panel is dark; no timeout line in the 6.12 kernel log.

Look at these first.

  1. Hub75Driver.h: the machine case tree (one case per machine, no default), the output swap (quiesce, stop the scan, move the depth into range), and showStatus()'s order.
  2. DriverBase.h's publishHeapBytes(): the readout by deltas, the one path by which a driver reports its heap beside its ScratchBuffers.
  3. Hub75PiOutput.h's open(): the cut into panels, the fit, the seam's open, the lane canvas, and what each open resets.
  4. Hub75Canvas.h's placement and plain-rows walk, which decide whether a layout's lights reach the right panel pixel.
  5. Hub75Fit.h's messages, sized to fit whole for a board of up to six lanes.

Open.

  • PreviewDriver's status replaces a gain-table shortage the same way the HUB75 driver's did; it is outside this pull request.
  • While the light scratch is short, each correction change quiesces the worker before retrying a small allocation, and the status can read the gain warning during that wait.
  • A stopped HUB75 driver's refusal can be covered by a gain-table shortage raised later; older than this pull request.
  • The Pi output holds GPIO 2 to 27 and reports none to the pin map, which takes 16 pins a module.
  • hub75-panels.md's container line names --device /dev/pio0 and not the group the service user needs.
  • MSVC: host builds set hasHub75Pio, so this code is in a Windows build; no MSVC compile ran here.

Deferred.

Who did what. I work with agents, and I call them all Friday. This pull request is mostly theirs.

  • The design: credit to the MoonModules crew. It follows MoonLight's patterns: PR 2's output interface, the machine query Add the Pi 5 PIO engine for HUB75, through the kernel's /dev/pio0 interface #258 added, allocate-and-degrade with the reason in the status, and ewowi's points from Drive HUB75 panels through an output strategy #257 and Add the Pi 5 PIO engine for HUB75, through the kernel's /dev/pio0 interface #258 (final on the bus output, lights() read once a prepare, the 1/8-scan height case, why selectedBackend() stays virtual, the reworded comments).
  • Mine: the series and its split; the decisions in each round (the readout fix here rather than later, every finding of the second commit round taken, the Pi 3/4 wording); my Pi 5 wall and a second boot card on 6.12, which the agents may bench on; and the boards on my bench, which I set up and provisioned (the P4 I flashed myself over USB; the agents flashed the others, over the air or over USB).
  • The agents': the code, the tests, the docs and this description. Claude Opus 5.5 coordinating; a Sonnet developer kept on across three build batches, and a second Sonnet developer kept on across the three fix batches; an Opus reviewer kept on across the first two build batches; a fresh reader at each commit round, a different model each (Fable, then Opus, then Sonnet); a claim check of this description and the commit message; and Haiku Runners that installed and benched the builds on the wall (the coordinator built them with release.yml under act).
  • I directed the work and decided the open questions, and I read and commit the change myself.

Tested.

  • Host (macOS), run_gates.py on main 8044271 with this change staged over it, started from the tree's real path (run-20261120-190858): 14 passed, 0 failed, 8 skipped (7 because no file they read changed, 1 needing a port); check_code 1,721 findings, nothing risen; the write-time hook over the 33 changed source files, nothing raised. The host tests: 3,826 of 3,826, 796,914 assertions.
  • Each test added in the commit review was checked by a mutant of the code it pins, failing with it and passing without. The first commit reader ran the Hub75 cases under ASan with UBSan (310 cases, no report), on the tree before its fixes.
  • On these boards, this change before its rebase onto Add the fleet clock, looks pushed to a group, and a wall of devices drawing one picture #259, built from the one tree:
    • the Pi 5 wall on 6.12 (above);
    • an ESP32-S3 MatrixPortal with two 64x64 panels: LCD_CAM at "128x64, 1/32 scan, 6-bit", 27 fps;
    • an ESP32-P4: boots on Ethernet (no HUB75 adapter fitted);
    • a classic ESP32 driving 20 lights at 60 channels through RmtLed: the readout 60 B, 0 B switched off, 60 B on again;
    • an ESP32-PICO-V3-02 driving 128 lights at 384 channels: 384 B, as on its earlier build;
    • two ESP32-U4WDH picos and an ESP32-C3: boot and join WiFi.
  • The Teensy 4.1 firmware builds from the same tree (its platform_config.h gains hasHub75Pio = false).

Not tested: CI on this pull request (it runs when pushed); TSan (it does not run on macOS arm64; CI's thread lane will); the test suite on Linux or the Pi 5, where the ModuleContract survey's Record-mode guard matters; MSVC; the Teensy 4.1 on a board; panels on the P4; a real Pi 3 or 4; the A/B/A' table on the final build (the wall was on the 6.12 card); and the readings under Deferred.

🤖 Generated with Claude Code

Copilot AI balanced review requested due to automatic review settings November 21, 2026 02:31
@coderabbitai

coderabbitai Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review

Note

.coderabbit.yaml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

Parsing warnings: 1

Validation error: Unrecognized key: "instructions" at "reviews"
Configuration instructions

  • Please see the configuration documentation for more information.
  • You can also validate your configuration using the online YAML validator.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The fixture leaks the driver-owned correction frame without an explicit release, and the documentation misstates frame length and blanking’s effect on refresh timing.

2 open issues
What changed in this PR

Adds Raspberry Pi 5 HUB75 panel output to MoonLight, connecting the existing output strategy to the PIO engine introduced in #258.

Changes:

  • Adds Pi-specific controls, layout-to-lane mapping, geometry validation, and refresh/status reporting.
  • Shares peripheral ownership checks across drivers and preserves scratch-buffer allocations in heap accounting.
  • Adds regression coverage, setup documentation, and hardware benchmark records.
File Description
test/​unit/​light/​unit_Hub75PiOutput.cpp Tests shared Pi output mapping, lifecycle, warnings, and memory accounting.
test/​unit/​light/​unit_Hub75PioOutput.cpp Tests PIO options, scan geometry, brightness, and predicted refresh.
test/​unit/​light/​unit_Hub75Fit.cpp Tests geometry refusals and cabling suggestions.
test/​unit/​light/​unit_Hub75Encode.cpp Adds row-pairing geometry coverage.
test/​unit/​light/​unit_Hub75Driver_pi.cpp Tests machine selection, persistence, ownership, and status.
test/​unit/​light/​unit_Hub75Driver_output.cpp Extends output-contract, memory, and warning-priority tests.
test/​unit/​light/​unit_Hub75Driver_frame.cpp Clarifies test comments only.
test/​unit/​light/​unit_Hub75Canvas.cpp Tests lane placement, refresh calculations, and panel walks.
test/​unit/​light/​hub75_port.h Adds a machine-identity test guard.
test/​unit/​light/​hub75_pi_bench.h Adds shared Pi driver fixtures and recorder helpers.
test/​unit/​light/​correction_presets.h Adds a wide-channel correction fixture.
test/​unit/​core/​unit_ModuleContract.cpp Records inline-size allowance and isolates PIO during surveys.
test/​CMakeLists.txt Registers five new test files.
src/​platform/​teensy/​platform_config.h Declares PIO support unavailable.
src/​platform/​rpi/​hub75_rpi_common.h Clarifies the lane-count include comment only.
src/​platform/​rpi/​hub75_pio_repack.h Clarifies the lane-count include comment only.
src/​platform/​rpi/​hub75_pio_options.h Uses shared PIO limits.
src/​platform/​rpi/​hub75_board_pins.h Reads the lane count from the public seam.
src/​platform/​Hub75Pio.h Centralizes lane and chain-length limits.
src/​platform/​Hub75Bus.h Extracts the shared hold-word calculation.
src/​platform/​host/​platform_config.h Declares host PIO seam support.
src/​platform/​esp32/​platform_config.h Declares PIO support unavailable.
src/​light/​drivers/​ParallelLedDriver.h Reuses the shared peripheral ownership guard.
src/​light/​drivers/​LedPeripheral.h Adds the Pi header ownership identifier.
src/​light/​drivers/​Hub75PiOutput.h Implements shared Pi geometry, canvas, lifecycle, and warnings.
src/​light/​drivers/​Hub75PioOutput.h Connects the Pi output to the PIO seam.
src/​light/​drivers/​Hub75Output.h Extends settings and output contracts for Pi support.
src/​light/​drivers/​Hub75Fit.h Validates cabling and formats corrective suggestions.
src/​light/​drivers/​Hub75Driver.h Selects machine-specific outputs and coordinates controls and status.
src/​light/​drivers/​Hub75Canvas.h Provides placement, refresh estimates, and layout validation.
src/​light/​drivers/​Hub75BusOutput.h Adapts the bus output to the extended interface.
src/​light/​drivers/​DriverBase.h Shares ownership checks and publishes heap changes by delta.
mkdocs.yml Adds the benchmark page to navigation.
docs/​reference/​hardware/​hub75-panels.md Documents Pi wiring, geometry, permissions, kernels, and timing.
docs/​reference/​hardware/​hub75-bench.md Records Pi refresh, resource usage, and reopen measurements.
docs/​help/​help.json Adds generated help for Pi controls and readouts.

Review effort: Balanced

mm::PanelsLayout panels; ///< panels in cabling order, for a case that adds it
mm::Layer layer; ///< the layer the driver reads
mm::Buffer source; ///< the rendered frame the driver corrects
mm::Hub75Driver driver; ///< the driver under test
Comment thread docs/reference/hardware/hub75-panels.md Outdated

### Pixel clock and refresh

The frame is `bitDepth` x scan rows x lane width pixel clocks, so one state machine sets the refresh by the clock: `pixelClock` runs from 1 to 40 MHz, and `latchBlank` adds 0 to 8 dark words before each latch, for a panel that ghosts. The card quotes the computed wire rate, 203.5 Hz on the default wall at 10 MHz and 6-bit, and `shown` is the measured rate, 169 to 170 fps on the bench on kernel 6.18 and 198 on 6.12.
The light side of the Pi 5 HUB75 output, on the engine and seam MoonModules#258 merged: a PIO output for the HUB75 driver, the layout cut into lanes of panels, and the bench record with the A/B/A' table on the kernel-interface backend and a 6.12 run.

What changes for a user:
- On a Pi 5, the HUB75 driver drives panels from the 40-pin header through the PIO, on the active 3-channel board's pins. The card offers the PIO as its peripheral and shows the Pi's settings: rows and columns of one panel, panels per lane, the pixel clock and the latch blank.
- The layout sets the geometry: its lights, cut into whole panels, become the panels, up to 32 in series on each lane, on up to three lanes. A layout that does not cable into the lanes is refused, and the status says why and, unless the layout holds less than one panel, the arrangements that would cable. Panel rows are 16, 32 or 64.
- The card's `shown` control reads the refresh the panels run at. The status warns while submits fail, while a submit stalls, above the benched 20 MHz, or after a close the kernel left unfinished.
- A saved card keeps the Pi's settings, the 8-bit depth included, through a boot where the PIO refuses.
- On a Pi 3 or 4 the card shows the Pi card and says HUB75 in this build needs a Pi 5's PIO.
- One driver per peripheral, on every machine: a second driver that asks for LCD_CAM, Parlio or the Pi's header while another holds it stays idle and says why. On an ESP32 this is new for HUB75: a HUB75 driver now yields LCD_CAM to a strip driver holding it.
- Every HUB75 driver, the ESP32's included: a gain-table shortage stays in the status through a prepare (before, the prepare's status line replaced it). Every driver that reports heap beside its ScratchBuffers: the memory readout reads 0 after a release (before, a release with a wiring wider than RGB wrapped it below zero: 2^64 - 32 with a 32-channel wiring on a 64-bit host).
- No MIGRATING entry: the new controls take their defaults, and the card's other controls are main's.

KPI: 256lights | Host:2843KB | tick:9/7/6/7/1/7/163/8/6/7us(FPS:111111/142857/166666/142857/1000000/142857/6134/125000/166666/142857) | ESP32:2420KB | src:446(110353) | test:318(80708) | functions-over:330
Commit: src +1021/-92 lines | test +1940/-9 lines | duplicated lines 3559 -> 3559 (+0)

**Light domain**
- Hub75PioOutput.h (new): the output on a Pi 5's PIO. It hands the corrected frame to the PIO seam, takes 2 to 8 planes (6 by default), refuses panel rows other than 16, 32 or 64, derives the scan from half the panel's rows, quotes rates computed from the pixel clock in the cabling suggestions for a layout that does not fit, and shows the seam's warning above the benched 20 MHz.
- Hub75PiOutput.h (new): what a Pi output shares. open() closes, cuts the layout into panels, refuses a geometry that does not cable into the lanes, opens the seam, sizes the lane canvas and formats the status; each open judges stalls and failed submits afresh. With several panels per lane, each panel row is copied to its place on the lane canvas before the push.
- Hub75Canvas.h (new): where a light sits on the lane canvas, the cabling arrangements with the refresh each predicts, and the plain-rows walk that tells whether a layout's lights run panel by panel.
- Hub75Fit.h (new): whether a layout's panels cable into lanes of `panelsPerLane` on the board's lanes, and the status messages, sized so each fits whole for a board of up to six lanes.
- Hub75Driver.h:
  - The output follows the machine (platform/machine.h), one case per machine and no default: an ESP32 takes the bus output, a Pi 5 the PIO output, an earlier Pi a refusal, any other host the bus output and its refusal.
  - The PIO output is held by value; where no Pi 5 can have one, an empty type stands in, so an ESP32 image carries none of it.
  - The Pi's settings live on the driver, bound on every build where `hasHub75Pio` holds (the host builds; not an ESP32 or a Teensy), and shown only on the Pi card.
  - Swapping outputs quiesces the render worker, stops the scan and moves the depth into the new output's range.
  - lights() is read once, in prepare().
  - A sibling that holds the block leaves this driver idle with `kBlockInUse`.
  - The status is computed from state on prepare, on a correction change and every second, in one order: the light scratch missing, the output's warning, the gains waiting for tables, the output's description.
  - onCorrectionChanged() retries a light-scratch shortage at the next correction change, at the same width too.
- DriverBase.h:
  - `siblingClaims()` and `kBlockInUse`: the sibling guard's loop and its status text, moved up from ParallelLedDriver.h (where they were `siblingClaimsBlock()` and a literal; it keeps `siblingClaimsBlock()` as a one-line wrapper), so the HUB75 driver uses the same guard.
  - publishHeapBytes() moves the readout by the change in the driver's own allocations, so every ScratchBuffer's count stays in it; before, it set an absolute total that left the scratch buffers out. Older than this change (main has the same lines); met here and fixed here.
  - `kNoLightMemory` and `lightScratchShort()`, which the HUB75 driver reads.
- Hub75Output.h: `DepthRange` and `depthRange()`, `warning()` and `drivenLayer()`; the Pi's settings with their defaults from the seam's `Hub75PioOptions`; why `selectedBackend()` stays virtual.
- Hub75BusOutput.h: `final`; its depth range and a null warning, which the base now asks of every output.
- LedPeripheral.h: `LedHwBlock::PiHeader`. Hub75Bus.h: `hub75HoldWords()`, the hold-word formula as a free function, which Hub75Geometry and the canvas both call.

**Core**
- platform/Hub75Pio.h: `kHub75Lanes` and `kHub75PanelsPerLaneMax`, stated once; the light side and platform/rpi read them, so light includes no platform/rpi header. The first line of its doc comment names `hasHub75Pio`.
- `hasHub75Pio` in the three platform_config.h (host true, ESP32 and Teensy false).

**Tests**
- unit_Hub75PioOutput.cpp, unit_Hub75PiOutput.cpp, unit_Hub75Canvas.cpp, unit_Hub75Fit.cpp, unit_Hub75Driver_pi.cpp (new), with hub75_pi_bench.h, what their cases share: the rig a driver is wired on, and a view of what the host port's recording seam kept of what the output opened and handed over.
- unit_Hub75Driver_output.cpp:
  - lights() read once in prepare(), with a counting output; read again on every prepare, so the next frame has the new length.
  - 48 rows offered at 1/8 scan and refused at 1/16, so the scan select reaches the geometry.
  - The status order, both ways: a memory shortage through a rewiring and the tick, a gain shortage through prepare and the tick, an output warning over a gain warning and back, an error over an output warning.
  - The readout with gain and 16-bit tables and a 32-channel wiring, and 0 after a release.
- unit_Hub75Fit.cpp's sweep of every geometry: its loops in a helper and a flat index, so no function nests past three levels or takes more than seven parameters (the hook MoonModules#259 added).
- unit_Hub75Encode.cpp: 96 rows pair at 1/8 and 1/16 and leave an odd three a scan at 1/32.
- unit_Hub75Driver_frame.cpp: its lead and three comments reworded (the two "16x32" comments, and the lead's and the re-init comment's negations); no case changed.
- unit_ModuleContract.cpp: the Hub75Driver row (over the 2 KB inline budget on a host build, where the PIO output sits inline with its 512-byte status text), and the survey holds the PIO seam in Record mode so no module lights real panels. hub75_port.h: `MachineGuard`, which sets the machine for a case and puts it back. correction_presets.h: `WideProfile`, a 32-channel wiring.
- Host, on main 8044271: 3,826 of 3,826 cases, 796,914 assertions.

**Docs/CI**
- hub75-panels.md: the Pi 5 section, with the kernel-interface backend (`/dev/pio0`), its kernels, the pins the kernel may own, the pixel clock and refresh, and 8-bit color. help.json regenerated, so drivers.md#hub75 shows the Pi controls; with hub75-bench.md, both references MoonModules#258 made ahead to 3b now land.
- hub75-bench.md (new, and its mkdocs.yml line): the bench record. The piolib readings of 2026-11-13 and 2026-11-18, and the kernel-interface backend of 2026-11-20: A/B/A' against the piolib build, a 6.12 column, the reopen cycles, OE after a stop and the kernel log.
- Gates by run_gates.py on main 8044271 (with MoonModules#259) with this change staged over it, Vale 3.21 on the PATH and ESP-IDF set, started from the tree's real path (run-20261120-190858): 14 passed, 0 failed, 8 skipped (7 because no file they read changed, 1 needing a port). check_code: 1,721 findings, nothing risen; the write-time hook over the 33 changed source files: nothing raised.
- Bench, the Pi 5 wall, three lanes of two 128x64 panels (256x192), built as a release is, by release.yml's build-linux-arm64 job (GCC 12.3) under act, where the build and package step completes and the later step that installs the program on the runner fails in act's container:
  - On kernel 6.18.60 (DietPi, Debian 13), the build before the commit review's fixes (program md5 8ef6e72e; the fixes touch the status, the memory readout, the rows refusal, where two limits are stated, two lines of the predicted refresh that give the same value on the wall, and comments, and leave the engine, the frame path and the panel timing as they were). A/B/A' (the piolib build, md5 d0bcb409; this change; the piolib build again), three readings of 5 s per setting: `shown` within 2 fps of the piolib build at every bit depth and clock. With live content, MoonLight's CPU 52.7 to 58.8% against 53.8 to 69.5%; the busiest thread 20.5 to 20.9% at every clock, against 26.8 to 28.2%. RSS 224 to 528 kB more. Ten reopen cycles in one process: 136 fps shown each time, a median 2.01 s to a shown rate. OE high after a service stop.
  - On kernel 6.12.109 (Raspberry Pi OS Lite, Debian 12), this change before its rebase onto MoonModules#259 (program md5 72cec8b6, build a8daa1b3), installed from its .deb over the earlier one, whose postinst (from MoonModules#258, unchanged here) had given the service user /dev/pio0's group (gpio). `shown` 75 / 149 / 182 fps at 8-bit 5 / 10 / 20 MHz and 101 / 198 / 242 at 6-bit, within 1 fps of the build before the fixes on the same card: within 1 fps of 6.18 at 5 MHz (75 against 76 at 8-bit, 101 at 6-bit) and higher above it, with the same Hub75 settings; the cause is untraced, the kernel the hypothesis. Ten reopen cycles: a median 1.99 s, 147 to 149 fps, one process. OE high after a stop, and no timeout line in the kernel log.
- This change before its rebase onto MoonModules#259, on the ESP32 boards it reached: an ESP32-S3 MatrixPortal (two 64x64 panels) runs the LCD_CAM backend at "128x64, 1/32 scan, 6-bit", 27 fps; an ESP32-P4 boots on Ethernet; a classic ESP32 drives 20 lights at 60 channels through RmtLed, its memory readout 60 B, 0 B switched off and 60 B on again; an ESP32-PICO-V3-02 drives 128 lights at 384 channels, 384 B; two ESP32-U4WDH and an ESP32-C3 boot and join WiFi. The Teensy 4.1 firmware builds from the same tree; it was not run on a board.
- Not run: CI, TSan, an MSVC build, the test suite on Linux or the Pi 5, the Teensy 4.1 on a board, panels on the P4, and the A/B/A' table on the final build.

**Reviews**
- ewowi on MoonModules#257 and MoonModules#258, the points for 3b:
  - `final` on Hub75BusOutput: done.
  - lights() read once in prepare(): done, with two cases.
  - The 1/8-scan height case: tests for 48 rows at 1/8 and 96 rows; the code already handled it.
  - selectedBackend() virtual: kept, with its reason in Hub75Output.h.
  - Three negations, Hub75Driver.h's reversed comment, the "16x32" helper comment: reworded.
  - His closing note on MoonModules#258 looked forward to the bench page with the A/B/A' table on the ioctl backend, and a 6.12 run if we got the chance: both above.
- piolib in 3b's docs, since 3a moved to the kernel's ioctls: rewritten for the kernel-interface backend; the piolib readings are labeled as such.
- The earlier reviews' items deferred to 3b: batch 4's six (the should-fix R-01, R-02 and R-05, the nits R-07 to R-09), the split review's S-03, U5's open K-items, U6's D1 to D7. Each checked against the tree and done or answered, except D1's group half for a container: the page names `--device /dev/pio0` and not the group, left open. K4 noted the light-side cases had no sanitizer run and named TSan as worth having: ASan and UBSan ran over the 310 Hub75 cases of the tree before the commit review's fixes, no report, and were not rerun after them; TSan did not run here (it does not run on macOS arm64) and is left to CI's thread lane.
- Built in three batches by one developer (Sonnet) kept on across them; one reviewer (Opus), kept on, read the first two, and neither review found a bug or a behavior should-fix; the third batch took the second review's doc fixes and nits, and the commit review read it.
- At commit, a fresh reader per round, a different model each, under the convergence rule (stop at no bug and no behavior should-fix):
  - Fable on the whole change as first staged (31 paths, +2,872/-84): 0 bug, 2 behavior should-fix (the status tick replaced a memory or gain shortage the base raised, on the ESP32 bus too; the readout wrapped after a release with a wide wiring, older than this change), 3 test, 2 doc, 12 nits, 5 wording. All done but three nits: two left as the owner's call (a pixel-clock phrase in the board-neutral Hub75Fit.h; the Pi output's header pins in the pin map, which takes 16 a module) and one outside this diff (the repo's HUB75 plan page, the maintainer's to update).
  - Opus on the fixes: 0 bug, 2 behavior should-fix, one brought in by the fixes (a stall hidden across a reopen) and one the first fix left open (the gain warning still lost at prepare, as on main). Every finding of this round done, on the owner's word: the status made one computed order, the readout moved by deltas, and the nits.
  - Sonnet on those fixes: converged. Its 2 doc fixes, 3 nits and 1 wording done by the coordinator; 3 named and left: a quiesce per correction change while memory is short, a brief status gap during that quiesce, and a stopped driver whose refusal a gain shortage can cover (older). PreviewDriver loses the gain warning the same way; outside this change.
- A claim check of this message and the pull request's description against the tree, the bench notes, the gate records and the review reports; its corrections are in both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@AnjinMeili

Copy link
Copy Markdown
Contributor Author

I rushed a big at the end, and missed the most basic of things. When the package swells, not from code, but mostly all the rest, the time from saying 'Send it!' to PR can take what feels like an ever longer growing path. We are audit our methods against the gates demands. This particular module started small, but scope grew. The goal remained the same, but the means to that end felt like it touched deep into everything. Learn I have, alway MoMo to understand. We will address the remaining as all the check point grind to a halt.

Copilot's review of MoonModules#260, both comments taken:

- hub75_pi_bench.h: `~Hub75Bench()` releases the driver as its owner does before destroying it, while the layer and the frame it reads still stand. The driver frees its correction frame in release(), not in its destructor, and the rigs did not all release. Measured with macOS `leaks` over the 58 cases of the three Pi test files: 18 leaks before and after, all from the test harness's scheduler setup and none from the driver, so no case leaked today; the destructor keeps a future one from it.
- hub75-panels.md and Hub75PioOutput.h: the frame is bitDepth x scan rows x (lane width + the encoder's hold words) pixel clocks. A lane of at most 2^(bitDepth - 2) words carries hold words; the wall's 256 carries 0, so its 203.5 Hz stands. `latchBlank` blanks words before each latch rather than adding any: the frame keeps its length and only the lit time shortens.

Gates by run_gates.py on main 8044271 with MoonModules#260 and this change staged over it, from the tree's real path (run-20261120-195414): 14 passed, 0 failed, 8 skipped. Host: 3,826 of 3,826 cases, 796,920 assertions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ewowi
ewowi merged commit cdf7ff1 into MoonModules:main Nov 21, 2026
23 checks passed
@AnjinMeili

Copy link
Copy Markdown
Contributor Author

Wall run on the merged head a514231, after the merge, on the Pi 5 wall (256x192, DietPi, kernel 6.18.60), with ColorTrails running.

Built by release.yml's build-linux-arm64 job under act (binary md5 4c1d9965), installed as /usr/bin/MoonLight. Benched the same way as the 11-20 rows in hub75-bench.md: three 5 s readings per setting.

shown at 5 / 10 / 11.446 / 20 MHz:

a514231 8ef6e72e (11-20, B)
8-bit live 76 / 127 / 136 / 169 76 / 127 / 136 / 169
6-bit live 101 / 170 / 181 / 225 101 / 170 / 182 / 227
8-bit static, 11.446 / 20 136 / 168 136 / 169

Within 2 fps of B at every setting, so the 3b commits leave refresh as it was. I'm not comparing CPU, because the wall ran different effects than on 11-20.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants