Update mapping.md #293

gunjambi · 2025-12-30T17:28:49Z

Spell out the requirements for the mapping values
Add example for sacrifical leds.

* Spell out the requirements for the mapping values * Add example for sacrifical leds.

blazoncek

This text confuses me and does not make understanding ledmaps any easier IMO. It also contains mistakes.

blazoncek · 2025-12-30T17:39:17Z

docs/advanced/mapping.md

+  Mapping changes these indices to `LED[map[0]]`, `LED[map[1]]` and `LED[map[2]]`, and by setting a map of `[2, 1, 0]` we can reverse the order.
+  But if the mapping contained the same value multiple times, for example `map=[0, 0, 0]`, then the effect would set the
+  colors of the LEDs `LED[map[0]] = LED[0]`, `LED[map[1]] = LED[0]` and `LED[map[2]] = LED[0]`, i.e. we would be setting the value of `LED[0]` multiple times.
+  In this case, the resulting color of the `LED[0]` is undefined.


It is defined, the last set value.

okay, updated. I based this on the comment here wled/WLED#5237 (comment)
I thought they were the last but didn't check all bus implementations.

blazoncek · 2025-12-30T17:40:47Z

docs/advanced/mapping.md

+  colors of the LEDs `LED[map[0]] = LED[0]`, `LED[map[1]] = LED[0]` and `LED[map[2]] = LED[0]`, i.e. we would be setting the value of `LED[0]` multiple times.
+  In this case, the resulting color of the `LED[0]` is undefined.
+
+* The ledmap must include a mapping for every physical led, that is to say, the length of the `map` array must be as long as the number of total LEDs in the system.


No, it does not need to include values for all LEDs. Ledmap can be shorter than total number of LEDs. Making it longer has no effect, trailing values are ignored.

Changed must -> should.

Partial mapping is nothing but trouble.

Partial mapping is nothing but trouble.

However, it is historical feature.

blazoncek · 2025-12-30T17:42:31Z

docs/advanced/mapping.md

+* The ledmap must include a mapping for every physical led, that is to say, the length of the `map` array must be as long as the number of total LEDs in the system.
+
+  As described above, the mapping works by changing the LEDs from `LED[0], LED[1], LED[2]...` to `LED[map[0]], LED[map[1]], LED[map[2]]...`.
+  If the `map` array is shorter than the number of LEDs, the mapping is assumed to be `map[N] = N` for the missing elements.


Now you contradict your previous (and incorrect) statement. This is the behaviour if ledmap is shorter than actual LEDs.

It was intentional to first start with a strong statement. Every new user should set the whole mapping.
Only if you fail to do that, this happens.

blazoncek · 2025-12-30T17:43:40Z

docs/advanced/mapping.md

+
+  As described above, the mapping works by changing the LEDs from `LED[0], LED[1], LED[2]...` to `LED[map[0]], LED[map[1]], LED[map[2]]...`.
+  If the `map` array is shorter than the number of LEDs, the mapping is assumed to be `map[N] = N` for the missing elements.
+  Note that the total number of LEDs in the system is the number of LEDs in the system, which may be larger than the product of the `width` and `height` fields.


This needs rewording.

blazoncek · 2025-12-30T17:45:28Z

docs/advanced/mapping.md

+  As described above, the mapping works by changing the LEDs from `LED[0], LED[1], LED[2]...` to `LED[map[0]], LED[map[1]], LED[map[2]]...`.
+  If the `map` array is shorter than the number of LEDs, the mapping is assumed to be `map[N] = N` for the missing elements.
+  Note that the total number of LEDs in the system is the number of LEDs in the system, which may be larger than the product of the `width` and `height` fields.
+  Specifically if you use sacrificial leds, i.e. LEDs, that are not present in the mapping, you may need to add trailing `-1` elements to your `map`.


Sacrificial LEDs are not part of the ledmap.

Sacrificial LEDs are part of a bus while ledmap belongs to a strip (WS2812FX class). Buses can overlap!!! See custom start indices.

I know sacrificial leds are not part of the ledmap. That's why I wrote "sacrificial leds are not present in the mapping".

Or is this a terminology question where sacrifical leds that are not in the beginning of a bus are called something else? Gaps?

The thing is that I have a serpentine grid, and there is a special led between every column that is not part of the grid. What do I call it? If I had 48 separate busses, they would be sacrifical leds. But if I use ledmap they are something else?

Buses can overlap!!! See custom start indices.

Please expand on this? I'm missing how it's related to the mapping.

I know sacrificial leds are not part of the ledmap. That's why I wrote "sacrificial leds are not present in the mapping".

@gunjambi the point is, "sacrificial leds" should be part of the ledmap.json; you need to add them as a kind of "trailing strip" otherwise WLED cannot control them properly. So the ledmap should not end with "-1" for the sacrificial leds, but its better to append them.

In your example, after the matrix map that skips sacrificial LEDs 5 and 11, append ",5, 11" as the last two positions. This allows to create an additional segment only for the sacrificial leds, and bring them to "black" in a controlled way.

Edit: I did not test if you can create segments when a ledmap.json is active. In case it does not work (ledmap dimensions might force-override segment dimensions), then indeed you must set the trailing leds to -1 to ensure they stay black and don't interfere with already-mapped leds. Please make a short experiment to verify if you can create a "sacrificial segment" when the ledmap is active.

there is a special led between every column that is not part of the grid. What do I call it?

I think "sacrificial LEDs" is OK, because this term is already known to users.

docs/advanced/mapping.md

softhack007 · 2025-12-30T21:29:51Z

docs/advanced/mapping.md

+    10,  9,  8,  7,  6,
+    12, 13, 14, 15, 16,
+
+    -1, -1


better to use "5, 11" instead of "-1, -1" (see my previous comment)

for best compatibility with older versions and other forks: don't use a blank line, and put "width" and "height" before "map")

softhack007 · 2025-12-31T01:24:12Z

docs/advanced/mapping.md

+
+```json
+{
+  "map": [


Sorry for nitpicking, but this example won't work with WLED 0.16, because the whitespace after "map": will cause the parser to ignore the complete map content. See

https://github.com/wled/WLED/blob/787d8a7342a45d957eff0493d87c93fce247b46d/wled00/FX_fcn.cpp#L2012

To make it work, change "map": [ to "map":[

FYI: the new editor auto-formats ledmaps (and any other json file for that matter) when saving but not if a file is just uploaded.

@DedeHai side-topic: does it mean that editing cfg.json or presets.json will automatically "pretty-format" the file? I think we can handle it in case of ledmap.json (did some tests in MM, found a simple solution), but pretty-printed cfg.json or presets.json might cause new problems with the parser.

Also pretty-formatting will blow up the file size, and it might be too much for boards with small littleFS partitions.

softhack007 · 2025-12-31T01:39:53Z

docs/advanced/mapping.md

+  Let's denote these physical LEDS as `LED[0]`, `LED[1]` and `LED[2]`.
+  Mapping changes these indices to `LED[map[0]]`, `LED[map[1]]` and `LED[map[2]]`, and by setting a map of `[2, 1, 0]` we can reverse the order.
+  But if the mapping contained the same value multiple times, for example `map=[0, 0, 0]`, then the effect would set the
+  colors of the LEDs `LED[map[0]] = LED[0]`, `LED[map[1]] = LED[0]` and `LED[map[2]] = LED[0]`, i.e. we would be setting the value of `LED[0]` multiple times.


This would be nice, but unfortunately it does not work. Reason: ledmaps are many-to-1, so you can map 3 logical leds to the same physical led, or map 256 logical leds to a randomly picked 256 of 1024 physical leds . But you cannot send the same "logical" led pixel to multiple output pixels, if this is what you wanted to say.

Your example "map":[0,0,0] does the opposite: when an effect changes pixel 0, 1 or 2, then this will always change physical led 0. So its effectively the same as "map":[-1,-1,0] because the value of pixel 2 will "win" in wled 0.16, while in wled 0.15 and earlier the result would be random.

Update mapping.md

1fcd34b

* Spell out the requirements for the mapping values * Add example for sacrifical leds.

gunjambi mentioned this pull request Dec 30, 2025

2D matrix mapping regression in Nightly wled/WLED#5237

Open

1 task

blazoncek suggested changes Dec 30, 2025

View reviewed changes

Update mapping.md

cdcb9f3

softhack007 reviewed Dec 30, 2025

View reviewed changes

softhack007 reviewed Dec 31, 2025

View reviewed changes

softhack007 mentioned this pull request Dec 31, 2025

Rewrite of mapping.md to make it easier to follow and more complete #291

Open

Update mapping.md #293

Are you sure you want to change the base?

Update mapping.md #293

Uh oh!

Conversation

gunjambi commented Dec 30, 2025

Uh oh!

blazoncek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

softhack007 Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

softhack007 Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

softhack007 Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

softhack007 Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

softhack007 Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

softhack007 Dec 30, 2025 •

edited

Loading

softhack007 Dec 30, 2025 •

edited

Loading

softhack007 Dec 31, 2025 •

edited

Loading

softhack007 Dec 31, 2025 •

edited

Loading

softhack007 Dec 31, 2025 •

edited

Loading