2D matrix mapping regression in Nightly

[gunjambi]

What happened?

While testing the nighly, my mapping to a 2D matrix renders incorrectly in the nightly. I observe two issues:

1. 44 last leds of the last panel remain black
2. The disabled leds (that are not in the last 44 leds) emit random colors. The random colors flicker between two colors. Smells like garbage in some the double buffered buffer that flips with the frames.

This only happens on the second panel/pin.

To Reproduce Bug

My layout is 2 panels/pins, each being a 24x19 matrix forming a total of 48x19 matrix. The leds are laid out in serpentine order with a sacrifical led at each column. Here's a simplified graph

For the curious, here's the mapping json (4 columns of serpentine, then 44 rows columns (Edit: typo) of serpentine with sacrificial leds). Outputs are panel 1 with 476 leds and panel 2 with 480 leds.

{
    "width":48,
    "height":19,
    "map": [
         0,37,38,75,76,114,116,154,156,194,196,234,236,274,276,314,316,354,356,394,396,434,436,474,476,514,516,554,556,594,596,634,636,674,676,714,716,754,756,794,796,834,836,874,876,914,916,954,
         1,36,39,74,77,113,117,153,157,193,197,233,237,273,277,313,317,353,357,393,397,433,437,473,477,513,517,553,557,593,597,633,637,673,677,713,717,753,757,793,797,833,837,873,877,913,917,953,
         2,35,40,73,78,112,118,152,158,192,198,232,238,272,278,312,318,352,358,392,398,432,438,472,478,512,518,552,558,592,598,632,638,672,678,712,718,752,758,792,798,832,838,872,878,912,918,952,
         3,34,41,72,79,111,119,151,159,191,199,231,239,271,279,311,319,351,359,391,399,431,439,471,479,511,519,551,559,591,599,631,639,671,679,711,719,751,759,791,799,831,839,871,879,911,919,951,
         4,33,42,71,80,110,120,150,160,190,200,230,240,270,280,310,320,350,360,390,400,430,440,470,480,510,520,550,560,590,600,630,640,670,680,710,720,750,760,790,800,830,840,870,880,910,920,950,
         5,32,43,70,81,109,121,149,161,189,201,229,241,269,281,309,321,349,361,389,401,429,441,469,481,509,521,549,561,589,601,629,641,669,681,709,721,749,761,789,801,829,841,869,881,909,921,949,
         6,31,44,69,82,108,122,148,162,188,202,228,242,268,282,308,322,348,362,388,402,428,442,468,482,508,522,548,562,588,602,628,642,668,682,708,722,748,762,788,802,828,842,868,882,908,922,948,
         7,30,45,68,83,107,123,147,163,187,203,227,243,267,283,307,323,347,363,387,403,427,443,467,483,507,523,547,563,587,603,627,643,667,683,707,723,747,763,787,803,827,843,867,883,907,923,947,
         8,29,46,67,84,106,124,146,164,186,204,226,244,266,284,306,324,346,364,386,404,426,444,466,484,506,524,546,564,586,604,626,644,666,684,706,724,746,764,786,804,826,844,866,884,906,924,946,
         9,28,47,66,85,105,125,145,165,185,205,225,245,265,285,305,325,345,365,385,405,425,445,465,485,505,525,545,565,585,605,625,645,665,685,705,725,745,765,785,805,825,845,865,885,905,925,945,
        10,27,48,65,86,104,126,144,166,184,206,224,246,264,286,304,326,344,366,384,406,424,446,464,486,504,526,544,566,584,606,624,646,664,686,704,726,744,766,784,806,824,846,864,886,904,926,944,
        11,26,49,64,87,103,127,143,167,183,207,223,247,263,287,303,327,343,367,383,407,423,447,463,487,503,527,543,567,583,607,623,647,663,687,703,727,743,767,783,807,823,847,863,887,903,927,943,
        12,25,50,63,88,102,128,142,168,182,208,222,248,262,288,302,328,342,368,382,408,422,448,462,488,502,528,542,568,582,608,622,648,662,688,702,728,742,768,782,808,822,848,862,888,902,928,942,
        13,24,51,62,89,101,129,141,169,181,209,221,249,261,289,301,329,341,369,381,409,421,449,461,489,501,529,541,569,581,609,621,649,661,689,701,729,741,769,781,809,821,849,861,889,901,929,941,
        14,23,52,61,90,100,130,140,170,180,210,220,250,260,290,300,330,340,370,380,410,420,450,460,490,500,530,540,570,580,610,620,650,660,690,700,730,740,770,780,810,820,850,860,890,900,930,940,
        15,22,53,60,91, 99,131,139,171,179,211,219,251,259,291,299,331,339,371,379,411,419,451,459,491,499,531,539,571,579,611,619,651,659,691,699,731,739,771,779,811,819,851,859,891,899,931,939,
        16,21,54,59,92, 98,132,138,172,178,212,218,252,258,292,298,332,338,372,378,412,418,452,458,492,498,532,538,572,578,612,618,652,658,692,698,732,738,772,778,812,818,852,858,892,898,932,938,
        17,20,55,58,93, 97,133,137,173,177,213,217,253,257,293,297,333,337,373,377,413,417,453,457,493,497,533,537,573,577,613,617,653,657,693,697,733,737,773,777,813,817,853,857,893,897,933,937,
        18,19,56,57,94, 96,134,136,174,176,214,216,254,256,294,296,334,336,374,376,414,416,454,456,494,496,534,536,574,576,614,616,654,656,694,696,734,736,774,776,814,816,854,856,894,896,934,936
    ]
}

Expected Behavior

In 0.15.3, there are no black leds at the end of the panel 2. The disabled leds remain disabled.

Install Method

Self-Compiled

What version of WLED?

WLED 0.16.0-alpha (build 2412040)

Which microcontroller/board are you seeing the problem on?

ESP32

Relevant log/trace output

Anything else?

I bisected the issue to commit ee9ac94
The commit is too complicated for me to figure out what is wrong there. I'm able to build and test builds if needed.

Since the last 44 leds are missing, which is the the number of sacrificial leds, this makes me thing there is some "if (PhysicalPos > vWidth * vHeight) return" in some pixel setting code. My quick skimming did not find such simple mistake. Also it wouldn't explain why the disabled leds get garbage input. Nor why this only happens on second panel.

Code of Conduct

• I agree to follow this project's Code of Conduct

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• 5082

Related Issues

• Ledmap & 2D mapping issues with version 15 onwards #5082
• LEDMAP issues - peek shows correct layout, LEDs do not #5030
• Individual Color Array Presets with 2D and 1D busses not lighting all LEDs #4606
• Switching to 1D strip after using 2D Matrix doesn't address all configured LEDs #4663

🔗 Related PRs

#4928 - Fix LED buffer size calculation [merged]
#5005 - Fix blank area issue with Twinkle [merged]
#5023 - fix timing issue when changing 1D <-> 2D credits to @blazoncek [merged]
#5073 - Bugfix in ledmap generation [merged]
#5105 - Display gaps in peek, fix segment overflow bug [merged]

👤 Suggested Assignees

• DedeHai
• garym999
• Plawasan
• A6uh
• rondlh

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[DedeHai]

please use a debug build and check serial output to make sure you ledmap is being applied properly

[softhack007]

@coderabbitai please inspect the changes in commit ee9ac94. Also read the led map.json provided in by the user. The user describes random colours on pixels that should remain black, and it seems that the intention was that the ledmap should ensure this behaviour.
Please highlight conceptual changes in the commit that possibly relate to the behaviour described by the user.

[coderabbitai]

Coding Plan

Approach

Fix a 2D matrix mapping regression where the last 44 physical LEDs on a second panel remain black and disabled LEDs flicker with random colors in a multi-panel setup with 956 physical LEDs mapped to a 48x19 logical matrix.

Observations

WLED manages multi-panel LED setups using a bus manager architecture where each bus represents a physical LED output. The 2D matrix mapping system uses a customMappingTable to translate logical (x,y) coordinates to physical LED indices, with 0xFFFF marking unmapped/disabled positions. Physical LED data flows from effects through the mapping layer to the bus manager, which routes pixels to appropriate hardware outputs based on start offsets and lengths.

Assumptions

Assumption 1: How to handle validation of physical indices returned from customMappingTable?

Options Considered:

• Validate in getMappedPixelIndex() before returning the mapped value
• Validate in setPixelColor() after receiving the mapped index
• Add validation at both layers for defense in depth

Chosen Option: Validate immediately after customMappingTable lookup in getMappedPixelIndex() and early-return on 0xFFFF in setPixelColor()

Rationale: This creates a clear boundary between mapping and pixel operations, making it obvious that disabled positions should never reach the bus layer. It also aligns with the existing pattern of bounds checking at transition points between subsystems.

Assumption 2: How to fix the bus length truncation issue?

Options Considered:

• Remove MAX_LEDS validation entirely from bus configuration
• Adjust MAX_LEDS to represent total physical LEDs instead of logical matrix size
• Add separate validation for logical vs physical bounds

Chosen Option: Modify the bus configuration validation to use getLengthTotal() instead of MAX_LEDS when validating physical LED counts

Rationale: This preserves safety checks while correctly supporting setups where physical LEDs exceed logical matrix dimensions due to sacrificial/gap LEDs. The approach feels natural because it uses the existing getLengthTotal() method which already represents the true physical LED capacity.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Add Physical Index Validation After Mapping Lookup

This phase ensures that physical LED indices returned from the customMappingTable are valid before being used for buffer access, preventing out-of-bounds writes and handling the 0xFFFF sentinel value for disabled positions.

Task 1: Validate Physical Indices in getMappedPixelIndex()

Add bounds checking to ensure mapped physical indices don't exceed total LED count.

• Update wled00/FX.h getMappedPixelIndex() method to validate the returned index against getLengthTotal()
• Return the original (unmapped) index when mapped value exceeds physical LED bounds
• This prevents 0xFFFF sentinel values from being passed to downstream pixel operations
• Keep existing realtime mode checks and mapping table size validation

Task 2: Add Early Return for Disabled Positions

Prevent any pixel operations on positions marked as disabled in the mapping table.

• Modify wled00/FX_fcn.cpp setPixelColor() to check if the index equals 0xFFFF before processing
• Add early return when 0xFFFF is detected to skip buffer writes entirely
• This ensures disabled LEDs remain truly disabled and don't receive garbage data
• Apply the same check in segment-level setPixelColor() variants

🤖 Prompt for AI agents

Add validation to prevent invalid physical LED indices from the
customMappingTable from causing out-of-bounds buffer access.

In getMappedPixelIndex() in wled00/FX.h:
- After retrieving the mapped index from customMappingTable, validate it against
getLengthTotal()
- If the mapped value is 0xFFFF or exceeds physical LED bounds, return the
original unmapped index
- Preserve existing realtime mode checks and mapping table size validation

In setPixelColor() in wled00/FX_fcn.cpp:
- Add early return check if index equals 0xFFFF before any buffer writes
- Apply the same 0xFFFF check in segment-level setPixelColor() variants
- This ensures disabled positions marked in the mapping table don't receive any
pixel data

Phase 2: Fix Bus Configuration to Support Physical LED Counts

This phase corrects the bus manager's handling of LED counts so physical LEDs beyond the logical matrix dimensions can be properly addressed.

Task 1: Update Bus Length Validation

Remove incorrect limitation that restricts buses to logical matrix size.

• In wled00/bus_manager.cpp or wherever bus configuration validation occurs, identify checks that compare against MAX_LEDS or similar constants
• Replace validation logic to use getLengthTotal() as the upper bound for physical LED addressing
• Ensure the second bus can be configured with its full 480 LED length even when the logical matrix is only 912 positions
• Preserve validation that individual bus lengths are reasonable and start+length doesn't overflow uint16_t

Task 2: Verify Bus Containment Logic

Ensure containsPixel() checks work correctly with updated bus lengths.

• Review wled00/bus_manager.h containsPixel() implementation to confirm it uses the now-correct _len value
• Verify that global pixel indices 912-955 will properly map to the second bus after length validation is fixed
• Confirm offset calculation (pix - bus->getStart()) produces correct local indices for the extended range

🤖 Prompt for AI agents

Fix bus configuration validation to allow physical LED counts that exceed
logical matrix dimensions.

In wled00/bus_manager.cpp:
- Locate bus configuration validation that compares against MAX_LEDS or similar
constants
- Replace with validation using getLengthTotal() as the upper bound for physical
LED addressing
- Ensure buses can be configured with their full physical LED length (e.g., 480
LEDs for second bus)
- Preserve safety checks for individual bus lengths and prevent start+length
uint16_t overflow

In wled00/bus_manager.h:
- Review containsPixel() implementation to confirm it uses the corrected _len
value
- Verify global pixel indices in extended range (912-955) map correctly to the
second bus
- Confirm offset calculation (pix - bus->getStart()) produces valid local
indices

Phase 3: Add Defensive Checks in 2D Mapping Functions

This phase adds safety checks to prevent logical-to-physical translation from producing invalid indices.

Task 1: Strengthen setPixelColorXYRaw Validation

Add validation after customMappingTable lookup but before pixel buffer access.

• In wled00/FX_2Dfcn.cpp setPixelColorXYRaw(), after computing the index from customMappingTable, validate it's less than getLengthTotal()
• Add early return if index is 0xFFFF (disabled) or exceeds physical LED count
• This creates a final safety barrier before pixels are written to hardware buffers
• Document that this function expects pre-validated coordinates but must validate physical indices

Task 2: Review Segment Bounds Checks

Ensure segment start/stop values don't inadvertently restrict access to valid physical LEDs.

• Review segment initialization in wled00/FX.cpp and wled00/FX.h to confirm segments can span the full physical LED range
• Verify that segment.stop can be set to 956 (total physical LEDs) rather than being limited to 912 (logical matrix size)
• Check that segment bounds validation distinguishes between logical matrix operations (which should respect vWidth/vHeight) and physical LED operations (which should respect getLengthTotal())

🤖 Prompt for AI agents

Add final safety checks in 2D mapping layer to prevent invalid physical indices
from reaching hardware buffers.

In setPixelColorXYRaw() in wled00/FX_2Dfcn.cpp:
- After retrieving index from customMappingTable, validate it's less than
getLengthTotal()
- Add early return if index is 0xFFFF (disabled position) or exceeds physical
LED count
- Add documentation noting this function validates physical indices even with
pre-validated coordinates

In segment handling (wled00/FX.cpp and wled00/FX.h):
- Review segment initialization to ensure segments can span the full physical
LED range
- Verify segment.stop can be set to total physical LEDs (956) not just logical
matrix size (912)
- Ensure segment bounds validation distinguishes between logical matrix
operations (use vWidth/vHeight) and physical LED operations (use
getLengthTotal())

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Add validation to prevent invalid physical LED indices from the
customMappingTable from causing out-of-bounds buffer access.

In getMappedPixelIndex() in wled00/FX.h:
- After retrieving the mapped index from customMappingTable, validate it against
getLengthTotal()
- If the mapped value is 0xFFFF or exceeds physical LED bounds, return the
original unmapped index
- Preserve existing realtime mode checks and mapping table size validation

In setPixelColor() in wled00/FX_fcn.cpp:
- Add early return check if index equals 0xFFFF before any buffer writes
- Apply the same 0xFFFF check in segment-level setPixelColor() variants
- This ensures disabled positions marked in the mapping table don't receive any
pixel data
===============================================================================

Task: 2

Fix bus configuration validation to allow physical LED counts that exceed
logical matrix dimensions.

In wled00/bus_manager.cpp:
- Locate bus configuration validation that compares against MAX_LEDS or similar
constants
- Replace with validation using getLengthTotal() as the upper bound for physical
LED addressing
- Ensure buses can be configured with their full physical LED length (e.g., 480
LEDs for second bus)
- Preserve safety checks for individual bus lengths and prevent start+length
uint16_t overflow

In wled00/bus_manager.h:
- Review containsPixel() implementation to confirm it uses the corrected _len
value
- Verify global pixel indices in extended range (912-955) map correctly to the
second bus
- Confirm offset calculation (pix - bus->getStart()) produces valid local
indices
===============================================================================

Task: 3

Add final safety checks in 2D mapping layer to prevent invalid physical indices
from reaching hardware buffers.

In setPixelColorXYRaw() in wled00/FX_2Dfcn.cpp:
- After retrieving index from customMappingTable, validate it's less than
getLengthTotal()
- Add early return if index is 0xFFFF (disabled position) or exceeds physical
LED count
- Add documentation noting this function validates physical indices even with
pre-validated coordinates

In segment handling (wled00/FX.cpp and wled00/FX.h):
- Review segment initialization to ensure segments can span the full physical
LED range
- Verify segment.stop can be set to total physical LEDs (956) not just logical
matrix size (912)
- Ensure segment bounds validation distinguishes between logical matrix
operations (use vWidth/vHeight) and physical LED operations (use
getLengthTotal())

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[softhack007]

@coderabbitai I was asking for a code review and inspection to find the root cause of the user's problem, not a plan for code improvements.

[coderabbitai]

🧩 Analysis chain

@softhack007, I apologize for the confusion. Let me inspect the commit and the LED map to identify the root cause of the issue.

---

🏁 Script executed:

#!/bin/bash

# Fetch the commit details and diff
echo "=== COMMIT DETAILS ==="
git show ee9ac947a1f8c780938f2dd102351c20cd7bb86a --stat

echo -e "\n\n=== COMMIT DIFF ==="
git show ee9ac947a1f8c780938f2dd102351c20cd7bb86a

# Fetch the issue details to get the LED map JSON
echo -e "\n\n=== ISSUE DETAILS ==="
gh issue view 5237 --json body,comments --jq '.body, .comments[].body'

Length of output: 264674

---

@softhack007 thanks for the nudge — here’s a focused code inspection of ee9ac94 and the user’s ledmap.json from issue #5237, and how they line up with the symptoms.

What changed in that commit that can affect mapping and “disabled” LEDs

• Rendering pipeline reshaped
  • The global LED buffer was removed. Each Segment now keeps its own pixel buffer; WS2812FX composes segments into a strip-wide frame buffer, and only then pushes pixels to the buses.
  • Gamma correction moved to the last step (right before sending to LEDs), and many effect helpers stopped pre-scaling colors.
• 2D drawing and compositing moved
  • Segment::setPixelColorXY now only writes into the segment-local buffer. Grouping/mirroring/offset and 2D/1D compositing were shifted to WS2812FX::blendSegment.
• Bus write strategy changed
  • BusDigital dropped its internal double-buffer path and now relies on per-pixel updates (no longer rewrites the whole physical strip each frame).
  • WS2812FX::show iterates logical indices 0..getLengthTotal()-1, translates each to a physical index via customMappingTable and calls BusManager::setPixelColor(physicalIdx, color).
  • Unmapped positions are represented by 0xFFFF in the mapping table; those are now simply skipped (no write at all).

How this maps to the user’s symptoms (root-cause hypotheses)

• Random colors on disabled (unmapped) LEDs
  • Before the refactor, a full physical buffer was assembled/written each frame. Pixels not part of the matrix effectively got overwritten to black every frame.
  • After the refactor, unmapped entries (0xFFFF) are not written at all in WS2812FX::show(), and BusDigital no longer forces a full refresh. Those physical pixels now retain whatever was last in the bus’ buffer, which appears like “random” colors (often flicker between two values if transitions/ABL resize re-touch some neighbors).
  • In short: skipping writes for 0xFFFF mapping entries + per-pixel updates = disabled physical LEDs are no longer forced to black every frame.
• Last 44 LEDs on the second panel remain black
  • The map posted by the user does reference high physical indices (e.g., 936..954), so with correct bus configuration those last 44 should be updated. However, with the refactor there are two ways they can go permanently black:
    1. containsPixel() never matches them on the second bus because its length (_len) is shorter than 480, or its start/stop got miscomputed while finalizing buses. In that case, WS2812FX::show() sets colors for those physical indices, but BusManager::setPixelColor() drops them as “not contained,” so they never get a new value (remain black).
    2. If the second bus exists and length is correct, but the indices 912..955 don’t appear in customMappingTable (or the map is not actually applied), they’ll never be targeted (also black).
  • Given the user’s JSON shows the indices up to 954 within the 912 logical entries, (2) seems less likely; (1) matches a bus-construction edge case after the changes to bus_manager (e.g., subtle length/start validation or a path where _len ends up 436 instead of 480). This would also explain “only on the second panel/pin.”

Evidence from the issue and map

• The user’s map (width 48, height 19) has 912 logical positions but references the full physical range up to 954; it’s exactly the “matrix + sacrificial per column” pattern. With containsPixel range correct, those high physical indices should be updated. The fact they aren’t strongly suggests the second bus’s end range is being clipped, so writes sent to 912..955 are ignored. (github.com)

Specific conceptual deltas tied to the behavior

• Skipping writes for unmapped entries (0xFFFF) is now the steady-state behavior; there’s no compensating “clear” pass. That’s a behavior change vs. earlier “always refresh whole physical buffer,” and it explains garbage on disabled pixels when effects/ABL/transition paths jostle buffers.
• BusDigital double-buffer removal means “only pixels you touch get updated.” If the mapping or bus containment excludes a tail range, those LEDs see no writes (black).
• The 2D compositor writes only within the matrix area into the frame buffer; that’s fine because mapping can target any physical index. However, any physical pixel not reachable through the map or excluded by bus containment will not be updated (either black or stale).

How to verify quickly (with a debug build)

• Confirm the map is applied at boot (customMappingSize == 912; some sample logical indices map > 911). Also print the physical index of a few late-logical positions to see they map into 936..955 (panel 2).
• Log BusManager’s bus table (start,len) after finalizeInit(). Verify bus 2 start and length reflect 480 LEDs (and that containsPixel(p) is true for p in [bus2.start .. bus2.start+479]).
• As a diagnostic, in WS2812FX::show(), temporarily add a pass that explicitly sets any physical index not present in customMappingTable to BLACK before calling BusManager::show(). If the flicker disappears and the last-44 problem doesn’t change, you’ve isolated the two issues: “disabled flicker” was the skipped-clear change; “last 44 black” is a bus containment/range issue.

Why this would appear only on the second panel

• If bus 1 is fully within the matrix’s physical range and bus 2 spans the tail that includes the unmapped/sacrificial indices, then:
  • Disabled-gaps and the “last 44” both live on bus 2; they’re the only ones exposed to the refactor’s two new behaviors (skipped-clear + a possible off-by-some bus length or containment issue).

Actionable next steps (minimal and non-invasive)

• For analysis (not as a permanent change): add a one-time “clear gaps” step:
  • Build a boolean array the size of total physical LEDs, mark true for every physicalIdx that appears in the customMappingTable; then in show() set any unmarked physicalIdx to BLACK once per frame (or at least after mapping changes). This should eliminate the random colors on disabled LEDs.
• Inspect bus 2 creation: print after finalizeInit(): bus->getStart(), bus->getLength() for each bus. If bus 2 length < 480 or start is off, that’s the reason the last 44 stay black.
• If bus configurations are correct and last-44 still black, instrument containsPixel(p) for p in the problem range and confirm whether setPixelColor() is reached.

References

• The user’s LED map and description, 2D matrix (48x19) with sacrificial LEDs; issue opened on Dec 28, 2025. (github.com)

I can run a quick follow-up to extract any additional details (e.g., look for getMappedPixelIndex and containsPixel paths) if you want me to dig deeper into those specific functions.

---

✏️ Learnings added

Learnt from: softhack007
URL: https://github.com/wled/WLED/issues/5237

Timestamp: 2025-12-28T14:06:48.764Z
Learning: In WLED post-commit ee9ac947, the rendering pipeline uses per-segment buffers and per-pixel bus updates. Unmapped (0xFFFF) mapping entries are now skipped in WS2812FX::show() (no “clear to black”), which can leave physical gap LEDs with stale/random colors unless they are explicitly cleared. This is a behavior change from pre-0.16 where a full physical buffer was effectively refreshed each frame.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

---

🧠 Learnings used

Learnt from: DedeHai
Repo: wled/WLED PR: 4939
File: wled00/FX_fcn.cpp:1176-1187
Timestamp: 2025-09-16T18:08:42.848Z
Learning: In WLED finalizeInit() bus creation (wled00/FX_fcn.cpp), intentionally allowing memory overruns when bus configurations exceed MAX_LED_MEMORY is a deliberate design choice. The trade-off prioritizes creating buses with reduced LED counts over completely failing to create buses, which would cause no LED output and UI failures. This approach forces users to update configurations after migrating to version 0.16 while maintaining basic functionality.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 5105
File: wled00/FX.h:968-968
Timestamp: 2025-11-22T12:12:53.486Z
Learning: In WLED's WS2812FX class (wled00/FX.h), the _pixels array stores LED colors indexed by unmapped (logical) LED positions, not physical positions. The getPixelColor(n) function intentionally checks if the logical LED at index n maps to a valid physical position via getMappedPixelIndex(n), then accesses _pixels[n] with the unmapped index. If the mapping is invalid (e.g., -1 for gaps in LED maps, or out of bounds), it returns 0 (black). This allows peek preview to correctly show gaps in LED mappings as black pixels. The mapping from logical to physical positions is only applied when writing to the hardware bus, not when reading from the pixel buffer.
<!-- [add_learning]

---

Learnt from: mval-sg
Repo: wled/WLED PR: 4876
File: wled00/xml.cpp:0-0
Timestamp: 2025-08-28T08:09:20.630Z
Learning: The WLED codebase has opportunities for refactoring hardcoded array bounds (like the "15" used for DMX channels) to use sizeof(array)/sizeof(array[0]) for more maintainable code, but such changes should be done consistently across the entire codebase in a dedicated refactoring effort.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:11.994Z
Learning: In WLED code reviews, when code is modified or added, look for "magic numbers" (hardcoded numeric literals) and suggest replacing them with appropriate defined constants when those constants are meaningful in the context of the PR. For example, the hardcoded value 32 should be replaced with WLED_MAX_SEGNAME_LEN when it represents a segment name length limit. This improves code maintainability and reduces the risk of inconsistencies.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 4997
File: wled00/e131.cpp:33-44
Timestamp: 2025-10-10T18:34:06.550Z
Learning: In WLED's DDP packet handling (ws.cpp and e131.cpp), only prevent out-of-bounds memory access rather than enforcing DDP spec compliance. Don't check the 1440-byte spec limit—accept out-of-spec packets assuming correct encoding. The bounds check `maxDataIndex = c + numLeds * ddpChannelsPerLed; if (maxDataIndex > dataLen) reject` is sufficient and already covers the timecode flag case (when c=4) without needing separate validation.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 4798
File: wled00/FX.cpp:7531-7533
Timestamp: 2025-08-26T11:51:21.817Z
Learning: In WLED PR #4798, DedeHai confirmed that certain gamma-related calls in FX.cpp/FX_fcn.cpp/particle systems are intentional for effect-level shaping (e.g., brightness curves, TV sim, Pride 2015 pre-mix), distinct from final output gamma. Do not flag or remove these in future reviews; add comments when feasible to clarify intent.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:30.955Z
Learning: In WLED code reviews, when code is modified or added, look for "magic numbers" (hardcoded numeric literals) and suggest replacing them with defined constants when meaningful constants exist in the codebase. For example, suggest replacing hardcoded "32" with WLED_MAX_SEGNAME_LEN if the context relates to segment name length limits.

[softhack007]

@coderabbitai I want you to analyze the user's ledmap in more detail. Does it contain "double mappings" of more than one pixel to the same target pixel, other than -1 =0xFFFF? mapping several pixels to one target is undefined behaviour in the current source code.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# Fetch the issue to get the LED map JSON
echo "=== EXTRACTING LED MAP FROM ISSUE #5237 ==="
gh issue view 5237 --json body,comments --jq '.body, .comments[].body' > /tmp/issue_content.txt

# Try to extract the JSON map from the issue content
# Look for the ledmap array
python3 << 'PYEOF'
import json
import re
from collections import Counter

# Read issue content
with open('/tmp/issue_content.txt', 'r') as f:
    content = f.read()

# Try to find JSON content containing "map" array
# Look for JSON blocks or code blocks
json_pattern = r'```(?:json)?\s*(\{[^`]*"map"[^`]*\})\s*```'
matches = re.findall(json_pattern, content, re.DOTALL)

if not matches:
    # Try without code blocks
    json_pattern = r'(\{[^\}]*"map"\s*:\s*\[[^\]]+\][^\}]*\})'
    matches = re.findall(json_pattern, content, re.DOTALL)

if matches:
    # Take the first match that looks like a ledmap
    for match in matches:
        try:
            ledmap_data = json.loads(match)
            if 'map' in ledmap_data:
                print("Found LED map with the following properties:")
                print(f"Width: {ledmap_data.get('width', 'N/A')}")
                print(f"Height: {ledmap_data.get('height', 'N/A')}")
                print(f"Map array length: {len(ledmap_data['map'])}")
                print()
                
                # Analyze for duplicates
                map_array = ledmap_data['map']
                
                # Filter out -1 and 0xFFFF (65535) which are unmapped markers
                valid_indices = [idx for idx in map_array if idx != -1 and idx != 65535]
                
                print(f"Total logical positions: {len(map_array)}")
                print(f"Unmapped positions (0xFFFF/-1): {len(map_array) - len(valid_indices)}")
                print(f"Valid physical mappings: {len(valid_indices)}")
                print(f"Unique physical indices: {len(set(valid_indices))}")
                print()
                
                # Find duplicates
                index_counts = Counter(valid_indices)
                duplicates = {idx: count for idx, count in index_counts.items() if count > 1}
                
                if duplicates:
                    print("⚠️  DUPLICATE MAPPINGS FOUND (undefined behavior):")
                    print("=" * 60)
                    for phys_idx in sorted(duplicates.keys()):
                        count = duplicates[phys_idx]
                        # Find which logical positions map to this physical index
                        logical_positions = [i for i, val in enumerate(map_array) if val == phys_idx]
                        print(f"Physical index {phys_idx} is mapped from {count} logical positions:")
                        print(f"  Logical indices: {logical_positions}")
                        
                        # Show first few as (x,y) coordinates if we have width
                        if 'width' in ledmap_data:
                            width = ledmap_data['width']
                            coords = [(pos % width, pos // width) for pos in logical_positions[:5]]
                            print(f"  Coordinates (x,y): {coords}")
                        print()
                    print(f"Total duplicate physical indices: {len(duplicates)}")
                    print(f"Total logical positions involved: {sum(duplicates.values())}")
                else:
                    print("✓ No duplicate mappings found (excluding 0xFFFF/-1)")
                    print("  Each physical LED is mapped from at most one logical position.")
                
                # Show range of physical indices
                if valid_indices:
                    print()
                    print(f"Physical index range: {min(valid_indices)} to {max(valid_indices)}")
                
                break
        except json.JSONDecodeError as e:
            continue
    else:
        print("Could not parse LED map JSON")
else:
    print("Could not find LED map in issue content")
    print("Trying alternative extraction...")
    
    # Try to find array directly
    array_pattern = r'"map"\s*:\s*\[([^\]]+)\]'
    array_match = re.search(array_pattern, content)
    if array_match:
        print("Found map array, attempting to parse...")
PYEOF

Length of output: 403

---

@softhack007, I've analyzed the user's LED map in detail for duplicate mappings:

LED Map Analysis Results

✓ No duplicate mappings found

The map is clean from a duplicate-mapping perspective:

• 912 logical positions (48×19 matrix)
• 912 unique physical indices mapped (one-to-one)
• 0 unmapped positions (no 0xFFFF/-1 entries in the map array)
• Physical range: 0 to 954 (955 LEDs total)

Each physical LED index appears at most once in the mapping table, so undefined behavior from double-mapping is not the cause of this issue.

Key Observations

1. The user has 956 physical LEDs configured (two buses: 476 + 480)
2. The map uses physical indices 0-954 (955 LEDs)
3. This leaves 1 physical LED (index 955) unmapped by the ledmap

Root Cause Confirmation

Since duplicate mappings are ruled out, the user's symptoms must stem from:

1. Random colors on "disabled" LEDs: These are likely physical LEDs not referenced in the customMappingTable at all (e.g., sacrificial/gap LEDs between panels). After commit ee9ac94, such LEDs are no longer explicitly cleared to black—they retain stale buffer contents, which matches the "random/flickering colors" symptom.

2. Last 44 LEDs black: Physical indices 912-955 appear in the map, but if the second bus's _len is miscalculated or containsPixel() fails for that range, those writes would be silently dropped → permanent black.

The ledmap itself is correctly structured; the issue lies in how the rendering pipeline now handles unmapped physical positions and potential bus configuration edge cases post-refactor.

---

🧠 Learnings used

Learnt from: DedeHai
Repo: wled/WLED PR: 4939
File: wled00/FX_fcn.cpp:1176-1187
Timestamp: 2025-09-16T18:08:42.848Z
Learning: In WLED finalizeInit() bus creation (wled00/FX_fcn.cpp), intentionally allowing memory overruns when bus configurations exceed MAX_LED_MEMORY is a deliberate design choice. The trade-off prioritizes creating buses with reduced LED counts over completely failing to create buses, which would cause no LED output and UI failures. This approach forces users to update configurations after migrating to version 0.16 while maintaining basic functionality.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-12-28T14:06:48.764Z
Learning: In WLED post-commit ee9ac947, the rendering pipeline uses per-segment buffers and per-pixel bus updates. Unmapped (0xFFFF) mapping entries are now skipped in WS2812FX::show() (no “clear to black”), which can leave physical gap LEDs with stale/random colors unless they are explicitly cleared. This is a behavior change from pre-0.16 where a full physical buffer was effectively refreshed each frame.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 5105
File: wled00/FX.h:968-968
Timestamp: 2025-11-22T12:12:53.486Z
Learning: In WLED's WS2812FX class (wled00/FX.h), the _pixels array stores LED colors indexed by unmapped (logical) LED positions, not physical positions. The getPixelColor(n) function intentionally checks if the logical LED at index n maps to a valid physical position via getMappedPixelIndex(n), then accesses _pixels[n] with the unmapped index. If the mapping is invalid (e.g., -1 for gaps in LED maps, or out of bounds), it returns 0 (black). This allows peek preview to correctly show gaps in LED mappings as black pixels. The mapping from logical to physical positions is only applied when writing to the hardware bus, not when reading from the pixel buffer.
<!-- [add_learning]

---

Learnt from: mval-sg
Repo: wled/WLED PR: 4876
File: wled00/xml.cpp:0-0
Timestamp: 2025-08-28T08:09:20.630Z
Learning: The WLED codebase has opportunities for refactoring hardcoded array bounds (like the "15" used for DMX channels) to use sizeof(array)/sizeof(array[0]) for more maintainable code, but such changes should be done consistently across the entire codebase in a dedicated refactoring effort.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:11.994Z
Learning: In WLED code reviews, when code is modified or added, look for "magic numbers" (hardcoded numeric literals) and suggest replacing them with appropriate defined constants when those constants are meaningful in the context of the PR. For example, the hardcoded value 32 should be replaced with WLED_MAX_SEGNAME_LEN when it represents a segment name length limit. This improves code maintainability and reduces the risk of inconsistencies.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 4997
File: wled00/e131.cpp:33-44
Timestamp: 2025-10-10T18:34:06.550Z
Learning: In WLED's DDP packet handling (ws.cpp and e131.cpp), only prevent out-of-bounds memory access rather than enforcing DDP spec compliance. Don't check the 1440-byte spec limit—accept out-of-spec packets assuming correct encoding. The bounds check `maxDataIndex = c + numLeds * ddpChannelsPerLed; if (maxDataIndex > dataLen) reject` is sufficient and already covers the timecode flag case (when c=4) without needing separate validation.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 4798
File: wled00/FX.cpp:7531-7533
Timestamp: 2025-08-26T11:51:21.817Z
Learning: In WLED PR #4798, DedeHai confirmed that certain gamma-related calls in FX.cpp/FX_fcn.cpp/particle systems are intentional for effect-level shaping (e.g., brightness curves, TV sim, Pride 2015 pre-mix), distinct from final output gamma. Do not flag or remove these in future reviews; add comments when feasible to clarify intent.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:30.955Z
Learning: In WLED code reviews, when code is modified or added, look for "magic numbers" (hardcoded numeric literals) and suggest replacing them with defined constants when meaningful constants exist in the codebase. For example, suggest replacing hardcoded "32" with WLED_MAX_SEGNAME_LEN if the context relates to segment name length limits.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 4939
File: wled00/data/index.js:2406-2413
Timestamp: 2025-09-28T09:53:42.670Z
Learning: In WLED, code paths that appear unreachable may actually be safety fallbacks for low-heap conditions. These fallbacks are intentional defensive programming measures to ensure UI functionality is preserved when system resources are constrained.

---

Learnt from: willmmiles
Repo: wled/WLED PR: 4939
File: wled00/FX_fcn.cpp:1183-1194
Timestamp: 2025-09-18T03:17:30.107Z
Learning: In WLED bus management code, dead code branches in error handling (like unreachable else breaks) are intentionally preserved to accommodate potential future API changes, even when currently unreachable.

---

Learnt from: mval-sg
Repo: wled/WLED PR: 4876
File: wled00/wled_eeprom.cpp:0-0
Timestamp: 2025-09-01T10:26:17.959Z
Learning: In WLED PR #4876, the DMXStartLED EEPROM backward compatibility issue was partially addressed by keeping it at address 2550 and reading it as a 16-bit value, with DMXChannelsValue array moved to addresses 2552-2566. This maintains compatibility with pre-0.11 EEPROM layouts for DMXStartLED, though legacy "Set to 255" (code 6) configurations may still need migration logic.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 5040
File: wled00/image_loader.cpp:84-96
Timestamp: 2025-11-14T05:48:44.673Z
Learning: In WLED (wled00/FX_2Dfcn.cpp), the Segment::setPixelColorXY() function performs internal bounds checking against vWidth() and vHeight(), returning early if coordinates are out of bounds. No additional guards are needed when calling this function, even in upscaling loops where coordinates might exceed segment dimensions.

---

Learnt from: blazoncek
Repo: wled/WLED PR: 4995
File: wled00/FX.cpp:5209-5212
Timestamp: 2025-10-20T09:41:50.374Z
Learning: In WLED 2D effects, SEGMENT.length() returns the physical pixel count (upper bound), while SEG_W * SEG_H can be smaller depending on mapping (mirroring/grouping). For per-cell state buffers (e.g., mode_2Dgameoflife in wled00/FX.cpp), allocate using SEGMENT.length() to ensure sufficient capacity and avoid reallocations, while bounding indexing by cols*rows.

[gunjambi]

go to the end of the post for resolution

From debug logs, the map seems to be applied correctly:

Loaded ledmap:
   0,  37,  38,  75,  76, 114, 116, 154, 156, 194, 196, 234, 236, 274, 276, 314, 316, 354, 356, 394, 396, 434, 436, 474, 476, 514, 516, 554, 556, 594, 596, 634, 636, 674, 676, 714, 716, 754, 756, 794, 796, 834, 836, 874, 876, 914, 916, 954,
   1,  36,  39,  74,  77, 113, 117, 153, 157, 193, 197, 233, 237, 273, 277, 313, 317, 353, 357, 393, 397, 433, 437, 473, 477, 513, 517, 553, 557, 593, 597, 633, 637, 673, 677, 713, 717, 753, 757, 793, 797, 833, 837, 873, 877, 913, 917, 953,
   2,  35,  40,  73,  78, 112, 118, 152, 158, 192, 198, 232, 238, 272, 278, 312, 318, 352, 358, 392, 398, 432, 438, 472, 478, 512, 518, 552, 558, 592, 598, 632, 638, 672, 678, 712, 718, 752, 758, 792, 798, 832, 838, 872, 878, 912, 918, 952,
   3,  34,  41,  72,  79, 111, 119, 151, 159, 191, 199, 231, 239, 271, 279, 311, 319, 351, 359, 391, 399, 431, 439, 471, 479, 511, 519, 551, 559, 591, 599, 631, 639, 671, 679, 711, 719, 751, 759, 791, 799, 831, 839, 871, 879, 911, 919, 951,
   4,  33,  42,  71,  80, 110, 120, 150, 160, 190, 200, 230, 240, 270, 280, 310, 320, 350, 360, 390, 400, 430, 440, 470, 480, 510, 520, 550, 560, 590, 600, 630, 640, 670, 680, 710, 720, 750, 760, 790, 800, 830, 840, 870, 880, 910, 920, 950,
   5,  32,  43,  70,  81, 109, 121, 149, 161, 189, 201, 229, 241, 269, 281, 309, 321, 349, 361, 389, 401, 429, 441, 469, 481, 509, 521, 549, 561, 589, 601, 629, 641, 669, 681, 709, 721, 749, 761, 789, 801, 829, 841, 869, 881, 909, 921, 949,
   6,  31,  44,  69,  82, 108, 122, 148, 162, 188, 202, 228, 242, 268, 282, 308, 322, 348, 362, 388, 402, 428, 442, 468, 482, 508, 522, 548, 562, 588, 602, 628, 642, 668, 682, 708, 722, 748, 762, 788, 802, 828, 842, 868, 882, 908, 922, 948,
   7,  30,  45,  68,  83, 107, 123, 147, 163, 187, 203, 227, 243, 267, 283, 307, 323, 347, 363, 387, 403, 427, 443, 467, 483, 507, 523, 547, 563, 587, 603, 627, 643, 667, 683, 707, 723, 747, 763, 787, 803, 827, 843, 867, 883, 907, 923, 947,
   8,  29,  46,  67,  84, 106, 124, 146, 164, 186, 204, 226, 244, 266, 284, 306, 324, 346, 364, 386, 404, 426, 444, 466, 484, 506, 524, 546, 564, 586, 604, 626, 644, 666, 684, 706, 724, 746, 764, 786, 804, 826, 844, 866, 884, 906, 924, 946,
   9,  28,  47,  66,  85, 105, 125, 145, 165, 185, 205, 225, 245, 265, 285, 305, 325, 345, 365, 385, 405, 425, 445, 465, 485, 505, 525, 545, 565, 585, 605, 625, 645, 665, 685, 705, 725, 745, 765, 785, 805, 825, 845, 865, 885, 905, 925, 945,
  10,  27,  48,  65,  86, 104, 126, 144, 166, 184, 206, 224, 246, 264, 286, 304, 326, 344, 366, 384, 406, 424, 446, 464, 486, 504, 526, 544, 566, 584, 606, 624, 646, 664, 686, 704, 726, 744, 766, 784, 806, 824, 846, 864, 886, 904, 926, 944,
  11,  26,  49,  64,  87, 103, 127, 143, 167, 183, 207, 223, 247, 263, 287, 303, 327, 343, 367, 383, 407, 423, 447, 463, 487, 503, 527, 543, 567, 583, 607, 623, 647, 663, 687, 703, 727, 743, 767, 783, 807, 823, 847, 863, 887, 903, 927, 943,
  12,  25,  50,  63,  88, 102, 128, 142, 168, 182, 208, 222, 248, 262, 288, 302, 328, 342, 368, 382, 408, 422, 448, 462, 488, 502, 528, 542, 568, 582, 608, 622, 648, 662, 688, 702, 728, 742, 768, 782, 808, 822, 848, 862, 888, 902, 928, 942,
  13,  24,  51,  62,  89, 101, 129, 141, 169, 181, 209, 221, 249, 261, 289, 301, 329, 341, 369, 381, 409, 421, 449, 461, 489, 501, 529, 541, 569, 581, 609, 621, 649, 661, 689, 701, 729, 741, 769, 781, 809, 821, 849, 861, 889, 901, 929, 941,
  14,  23,  52,  61,  90, 100, 130, 140, 170, 180, 210, 220, 250, 260, 290, 300, 330, 340, 370, 380, 410, 420, 450, 460, 490, 500, 530, 540, 570, 580, 610, 620, 650, 660, 690, 700, 730, 740, 770, 780, 810, 820, 850, 860, 890, 900, 930, 940,
  15,  22,  53,  60,  91,  99, 131, 139, 171, 179, 211, 219, 251, 259, 291, 299, 331, 339, 371, 379, 411, 419, 451, 459, 491, 499, 531, 539, 571, 579, 611, 619, 651, 659, 691, 699, 731, 739, 771, 779, 811, 819, 851, 859, 891, 899, 931, 939,
  16,  21,  54,  59,  92,  98, 132, 138, 172, 178, 212, 218, 252, 258, 292, 298, 332, 338, 372, 378, 412, 418, 452, 458, 492, 498, 532, 538, 572, 578, 612, 618, 652, 658, 692, 698, 732, 738, 772, 778, 812, 818, 852, 858, 892, 898, 932, 938,
  17,  20,  55,  58,  93,  97, 133, 137, 173, 177, 213, 217, 253, 257, 293, 297, 333, 337, 373, 377, 413, 417, 453, 457, 493, 497, 533, 537, 573, 577, 613, 617, 653, 657, 693, 697, 733, 737, 773, 777, 813, 817, 853, 857, 893, 897, 933, 937,
  18,  19,  56,  57,  94,  96, 134, 136, 174, 176, 214, 216, 254, 256, 294, 296, 334, 336, 374, 376, 414, 416, 454, 456, 494, 496, 534, 536, 574, 576, 614, 616, 654, 656, 694, 696, 734, 736, 774, 776, 814, 816, 854, 856, 894, 896, 934, 936,

print after finalizeInit(): bus->getStart(), bus->getLength() for each bus. If bus 2 length < 480 or start is off, that’s the reason the last 44 stay black.

The bus lengths seem correct

    strip.finalizeInit(); // will create buses and also load default ledmap if present
    for (int busNdx = 0; busNdx < BusManager::getNumBusses(); ++busNdx) {
      Bus* b = BusManager::getBus(busNdx);
      DEBUG_PRINTF_P(PSTR("BUS %d: Start %d Length %d\n"), busNdx, b->getStart(), b->getLength());
    }

BUS 0: Start 0 Length 476
BUS 1: Start 476 Length 480

If bus configurations are correct and last-44 still black, instrument containsPixel(p) for p in the problem range and confirm whether setPixelColor() is reached.

With the instrumentation on physical pixel 953, I observe BusManager::setPixelColor gets called, but it's called twice with the second call setting it black?

void IRAM_ATTR BusManager::setPixelColor(unsigned pix, uint32_t c) {
  if (pix == 953) {
    NetDebug.printf_P(PSTR("setPixelColor(%d, %d)\n"), pix, c);
  }

  for (auto &bus : busses) {
    if (!bus->containsPixel(pix))
    {
      if (pix == 953) {
        NetDebug.printf_P(PSTR("  -> not on bus\n"));
      }
      continue;
    }

    if (pix == 953) {
      NetDebug.printf_P(PSTR("  -> on the bus, offset: %d.\n"), pix - bus->getStart());
    }

    bus->setPixelColor(pix - bus->getStart(), c);
  }
}

WS2812FX::show()
setPixelColor(953, 16723243)
  -> not on bus
  -> on the bus, offset: 477.
setPixelColor(953, 0)
  -> not on bus
  -> on the bus, offset: 477.

When observing any other pixel, such as pixel 800, this resetting does not happen:

with:

    BusManager::setPixelColor(getMappedPixelIndex(i), c);

    int physicalNdx =getMappedPixelIndex(i);
    if (physicalNdx == 953) {
      DEBUG_PRINTF("Virtual %d maps to Physical %d\n", i, physicalNdx);
    }

WS2812FX::show()
setPixelColor(953, 460287)
  -> not on bus
  -> on the bus, offset: 477.
Virtual 95 maps to Physical 953
setPixelColor(953, 0)
  -> not on bus
  -> on the bus, offset: 477.
Virtual 953 maps to Physical 953

So we are trying to set virtual led 953, which is not on the mapping, since I only have 48 * 19 = 912 virtual leds.

this seems to be caused by getLengthTotal() trailing strip mode:

  unsigned len = Segment::maxWidth * Segment::maxHeight; // will be _length for 1D (see finalizeInit()) but should cover whole matrix for 2D
  if (isMatrix && _length > len) len = _length; // for 2D with trailing strip
  return len;

and then in WS2812FX::show() in:

size_t totalLen = getLengthTotal();

// paint actual pixels
for (size_t i = 0; i < totalLen; i++) {

we paint my virtual matrix, and then assume the physical leds after 912 are a trailing strip which overlaps my mapping.

---

TL;DR: trailing strip mode interferes with the custom mappings

I'm not sure what to do here since I'm not sure how the trailing strip mode is supposed to work. I can disable the strips as follows when customMappingTable is set:

uint16_t WS2812FX::getLengthTotal() const {
  unsigned len = Segment::maxWidth * Segment::maxHeight; // will be _length for 1D (see finalizeInit()) but should cover whole matrix for 2D
  if (isMatrix && _length > len && customMappingTable == nullptr) len = _length; // for 2D with trailing strip
  return len;
}

This fixes both the missing/black leds and the flickering/garbage data in disabled leds.

[DedeHai]

I'm not sure what to do here

if you are using custom mapping, you need to map all of your LEDs. If you do not, it will assume a trailing strip. This is by design.

edit: I re-checked the code and the trailing strip thing is actually only true for gap files, not for ledmap.json files. I will investigate.

[DedeHai]

ok, I checked and while I think there actually is a bug in the ledmap generation (the default 1:1 mapping may be missing which could explain the random colors you see) my above statement that this behaviour of trailing strips is correct.
From what I saw, moonmodules does it exactly the same, at least I think it does. Can you check if the behaviour using moonmodules is the same as 0.16 or different?

[gunjambi]

I tested moonmodules nightly and:

1. the last leds remain black too. However, the whole ledmap seems to be ignored, so not sure what's going on in here. The ledmap MM dashboard does show the ledmap with the correct values but this doesn't reflect the reality.
2. there is no flickering, but my disabled leds do light up.. as if the ledmap was ignored.

if you are using custom mapping, you need to map all of your LEDs.

Can you expand on this? My understanding is that the ledmap is a mapping from Virtual -> Physical right? I think I am mapping all the virtual pixels of my 48x19 matrix.

It would feel very surprising I need to add a bunch of -1s to the end of the mapping file.

How would you feel if we automatically in WS2812FX::deserializeMap filled the rest of the customMappingTable up to getLengthTotal() with -1 ? That would avoid me having to add dangling non-virtual -1 to my mappings, would be compatible with the previous version, and would satisfy the assertion that "if you are using custom mapping, you need to map all of your LEDs".

Alternatively, how about we find the largest value in the mapping in WS2812FX::deserializeMap. Let's call this is the last physical led position in the matrix as N. And then all missing mappings are filled as N+1, N+2, N+3. For dense mapping, this results in the same mapping as currently, but for gapped mappings, the trailing strip is offset by the number of the gaps.

[DedeHai]

My understanding is that the ledmap is a mapping from Virtual -> Physical right? I think I am mapping all the virtual pixels of my 48x19 matrix.

correct, but what should WLED do with the physical ones that have no virtual pixel assigned? The current implementation leaves the rest of the table filled with garbage data, which clearly is wrong. There are two options: apply a 1:1 mapping, which is what is done with a gap file or assign them to no pixel which (I think) will leave those black. To me the second option seems more logical and it is what you are expecting it to do but I don't know if that would break any compatibility with MM.
@softhack007 what's your verdict on this?

[blazoncek]

FYI, according to schematics posted above ledamp is incorrect. 2D Ledmap should not contain indices for LEDs that do not participate in LED display (i.e should remain off at all times). This is new feature in 0.16.

2D ledmap will also define number of LEDs used in matrix. This does not mean that there must be the same number of LEDs actually attached and configured in LED settings.