HUB75: allow non-horizontal panel arrangements (e.g. vertically stacked panels) - #372
HUB75: allow non-horizontal panel arrangements (e.g. vertically stacked panels)#372atlan wants to merge 2 commits into
Conversation
A HUB75 chain is electrically always horizontal, so N panels always form an area of (panel width * N) x panel height. Declaring a different 2D layout in the panel configuration only changes the logical area - BusHub75Matrix::show() still iterates over display->width(), so the image gets wrapped onto the physical chain width. Measured on device: a logical 64x128 area came out as 128x64, with the upper half red on BOTH panels instead of left red/right blue. VirtualMatrixPanel from the DMA library already does the logical-to-physical mapping, but it was only ever created for four-scan panels, and there hard-coded as (1, chain_length) - always a single row. This adds a default branch to the panel type switch that creates a VirtualMatrixPanel for normal panels as well, as soon as rows or columns exceed 1. The arrangement is carried in the existing bus "pin" field: [0] chain length [1] rows [2] columns [3] PANEL_CHAIN_TYPE nPins for HUB75 goes from 1 to 4 and getPins() reports the arrangement back, otherwise only the chain length survives a config save. Unset values are normalised to 1, so an existing pin: [2] becomes [2, 1, 1, 0] and the arrangement stays dormant - behaviour is unchanged for existing setups. rows * columns must equal the chain length, otherwise the arrangement is ignored and a warning is printed. Also adds a safety fuse: a bad arrangement could in theory stall during panel initialisation, leaving a device without USB access unreachable. wled.cpp writes /vpanel_try.txt before beginStrip() and removes it once the main loop has run for 20 s. If the marker is still there at boot, the arrangement is skipped so the device comes up normally; deleting the file from /edit arms it again. Parts of this change were drafted with AI assistance; they are marked as such in the code and were reviewed and tested on hardware by the author.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughHUB75 configurations now preserve virtual layout parameters and create validated ChangesHUB75 virtual panel arrangement
Sequence Diagram(s)sequenceDiagram
participant WLED_setup as WLED::setup()
participant Filesystem
participant BusHub75Matrix
participant VirtualMatrixPanel
participant WLED_loop as WLED::loop()
WLED_setup->>Filesystem: Check /vpanel_try.txt
WLED_setup->>BusHub75Matrix: Enable or disarm arrangement
BusHub75Matrix->>VirtualMatrixPanel: Create validated mapping
WLED_loop->>Filesystem: Remove marker after 20 seconds
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
wled00/bus_manager.cpp (1)
1104-1105: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winMark the AI-assisted block with the required
// AI:/// AI: endmarkers.This block is documented as "drafted with AI assistance," but it does not use the exact
// AI: below section was generated by an AI ... // AI: endmarker format required by the coding guidelines.As per coding guidelines: "Mark AI-generated code blocks with
// AI: below section was generated by an AI ... // AI: endcomments."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@wled00/bus_manager.cpp` around lines 1104 - 1105, Update the AI-assisted block identified by the WLEDMM+ comment in bus manager code to use the required AI marker format: add a starting `// AI: below section was generated by an AI ...` comment before the block and `// AI: end` immediately after it, replacing the existing informal AI-assistance note as appropriate.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@wled00/bus_manager.cpp`:
- Around line 1121-1146: In the default HUB75 arrangement handling, move the
assignments to _vRows, _vCols, and _vChainType out of the if (!fourScanPanel)
creation guard so they always reflect the current bc.pins values, including when
fourScanPanel is reused. Preserve the existing validation and panel-creation
behavior while ensuring getPins() reports the resynchronized arrangement
metadata.
---
Nitpick comments:
In `@wled00/bus_manager.cpp`:
- Around line 1104-1105: Update the AI-assisted block identified by the WLEDMM+
comment in bus manager code to use the required AI marker format: add a starting
`// AI: below section was generated by an AI ...` comment before the block and
`// AI: end` immediately after it, replacing the existing informal AI-assistance
note as appropriate.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: c40dbb96-b6b9-471b-92ad-a5455f5008be
📒 Files selected for processing (3)
wled00/bus_manager.cppwled00/bus_manager.hwled00/wled.cpp
…e-used Addresses the review on MoonModules#372. `_vRows` / `_vCols` / `_vChainType` are per-instance members defaulting to (1, 1, 0), and they were assigned only inside the `if (!fourScanPanel)` creation guard. When a bus is re-created while the display object is re-used, the fresh BusHub75Matrix already has `fourScanPanel = activeFourScanPanel` before the switch, so that block is skipped and the members keep their defaults. Since `getPins()` reports exactly those members — and does so specifically to make the arrangement survive a config save — the next config save after the first re-creation silently rewrote a working arrangement to "none". The boot fuse cannot help at that point, because the data it protects is already gone; for a panel in a closed enclosure that is the one failure mode this feature was supposed to avoid. The resync now happens on every pass, before the creation guard. Validation and panel creation are unchanged. Deliberately, the metadata is also assigned when the arrangement is skipped (fuse not armed) or rejected (rows * cols != chain_length): reporting (1, 1, 0) there would erase what the user configured. The warning already repeats on every boot — better to keep the configuration and keep complaining about it than to discard it quietly. Also marks the block with the `// AI: below section was generated by an AI` / `// AI: end` comments required by AGENTS.md and docs/cpp.instructions.md, replacing the informal note. Build checked: adafruit_matrixportal_esp32s3_tinyUF2 SUCCESS.
|
Both points were valid — thanks. The first one is a real bug, and I could not only follow 1. Arrangement metadata lost — confirmedVerified against the code:
Fixed by moving the resync out of the creation guard so it always reflects the current One deliberate detail: the metadata is now also assigned when the arrangement is Verified on hardwareMatrixPortal-S3, two 64x64 panels,
The last row is the scenario from the review: a config save that does not mention the 2.
|
1 participant
What this is trying to achieve
Allow HUB75 panels to be arranged in something other than a single horizontal row — for
example four 64x32 panels stacked vertically into a 64x128 display.
Today this is not possible. A HUB75 chain is electrically always horizontal, so N panels
always form an area of
(panel width * N) x panel height. Declaring a different layout inthe 2D panel configuration only changes the logical area —
BusHub75Matrix::show()stillwalks the buffer using
display->width():So the same linear buffer is written with the logical width and read with the physical one,
and the image gets wrapped onto the chain. Measured on hardware: two 64x64 panels declared
as 64x128 with the upper half red showed red on the top half of both panels, instead of
red on the left panel and blue on the right.
Note the built-in preview (WebSocket live view) shows the logical area and therefore looks
correct — it is not usable as evidence for what actually reaches the panels.
How the code works
VirtualMatrixPanelfrom the DMA library already performs the logical-to-physical mapping,including all the chain-type variants. WLED-MM only ever creates it for four-scan panels, and
there hard-coded as
(1, chain_length, …)— always a single row.bus_manager.cpp— adefault:branch in the panel type switch now creates aVirtualMatrixPanelfor normal panel types too, as soon as rows or columns exceed 1.rows * columnsmust equal the chain length; otherwise the arrangement is ignored and awarning is printed.
bus_manager.h— the arrangement is carried in the existing buspinfield:[0][1][2][3]PANEL_CHAIN_TYPE(0 =CHAIN_NONE, 1..4 = the plain variants, 5..8 = the ZigZag variants)nPinsfor HUB75 goes from 1 to 4 andgetPins()reports the arrangement back — otherwiseonly the chain length survives a config save and the arrangement is silently lost.
Example for four 64x32 panels stacked vertically, chained bottom-left up in a zigzag:
pin: [4, 4, 1, 8].Backwards compatibility: unset values are normalised to 1, so an existing
pin: [2]becomes
[2, 1, 1, 0]. The arrangement stays dormant and behaviour is unchanged for everyexisting configuration.
wled.cpp— safety fuse. A bad arrangement could in theory stall during panelinitialisation; the web server would never come up and a device without USB access would be
unreachable. So
/vpanel_try.txtis written beforebeginStrip()and removed once the mainloop has been running for 20 s. If the marker is still present at boot, the arrangement is
skipped and the device boots normally. Deleting the file from the
/editpage arms it again.Both
wled.cppblocks are inside#ifdef WLED_ENABLE_HUB75MATRIX.Testing performed
adafruit_matrixportal_esp32s3_tinyUF2(HUB75 enabled) andesp32dev(HUB75 not enabled) both compile clean.
pin: [2, 2, 1, 8]): WLEDdistributes the logical image onto the correct chain positions. The panels are physically
mounted side by side, so this shows up as left/right — stacked it would be top/bottom.
21 s; a boot with the marker left in place skips the arrangement as intended.
Known limitations / where I'd like a second opinion
being built. Verified so far is the two-panel case above, which exercises the same code
path.
getCoords(), not by tryingthem on physical hardware. All eight stay within the area bounds (no out-of-range
writes), but I cannot claim from measurement which one matches a given physical wiring.
Only type 8 has actually been on a panel.
pinarray; there is no UI for it. I didnot want to touch the settings pages without knowing whether you'd want it there at all,
and if so, in what form. Happy to add it if you point me at the preferred place.
_vRows/_vColsasuint8_tto fit the existing pin array. That caps thearrangement at 255 in each direction, which seems far beyond anything practical, but say
the word if you'd rather have it typed differently.
AI assistance
Parts of this change were drafted with AI assistance. The relevant blocks are marked as such
in the code. I have gone through the result line by line, verified the behaviour on hardware
as described above, and left the surrounding existing comments untouched.
Summary by CodeRabbit
New Features
Bug Fixes