From 1fcd34ba11260b8db6f2a325874a9f5414f34e2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jarkko=20P=C3=B6yry?= Date: Tue, 30 Dec 2025 19:27:41 +0200 Subject: [PATCH 1/2] Update mapping.md * Spell out the requirements for the mapping values * Add example for sacrifical leds. --- docs/advanced/mapping.md | 46 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/advanced/mapping.md b/docs/advanced/mapping.md index 9ca3c7e8a..c6ccf5a14 100644 --- a/docs/advanced/mapping.md +++ b/docs/advanced/mapping.md @@ -5,7 +5,7 @@ hide: # - toc --- -WLED now has the ability to remap your LED strip programmatically. +WLED has the ability to remap your LED strip programmatically. ### What is it? This allows us to treat the WLED strip as if it is wired in any way - we can then use the mapping feature to address the strip in any order. This allows for matrix support, serpentine runs and such. @@ -24,6 +24,30 @@ Multiple maps are supported in the latest versions by using `ledmapx.json` where Use -1 in the map for gaps/blank/null LEDs. +The ledmap also allows defining the dimensions of a 2D matrix. +By specifying the `width` and `height` fields, these dimensions are used when the ledmap is applied. + +#### Mapping Requirements + +Mapping is an advanced feature, and for the correct results the following requirements must be fulfilled: + +* A same value must not appear multiple times in the mapping, except for -1. + + Mapping works by changing the target LED of each color update. When an effect is rendered, the effect sets colors of a LEDs. + For example, a rainbow effect might set first LED of the strip as Red, the second LED as Yellow and the third LED as Blue. + 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. + 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. + + 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`. + ### Examples In the below example (formatted multiple ways), we remap a strip of four LEDs from a physical order of 0 1 2 3 into a new order of 0 2 1 3. @@ -81,3 +105,23 @@ Note that if a `ledmap.json` file exists, the `2d-gaps.json` file will be ignore ``` ![wiring diagram of the double ∞ shape mapping](mapping/mapping_infinity_shape.png) + +The following example demonstrates that when using sacrificial leds, you must include a mapping for all LEDs. + +Here, we have a serpentine of LEDs in 5 columns and 3 rows, and a sacrifical led between each row (in positions 5 and 11). +Since the total number of LEDs in this system is 15 + 2 = 17, the `map` must also be 17 elements long. +We fill those elements with -1. + +```json +{ + "map": [ + 0, 1, 2, 3, 4, + 10, 9, 8, 7, 6, + 12, 13, 14, 15, 16, + + -1, -1 + ], + "width": 5, + "height": 3 +} +``` From cdcb9f3f8ea08679b82b691dc3a85c5a4aca8980 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jarkko=20P=C3=B6yry?= Date: Tue, 30 Dec 2025 22:15:55 +0200 Subject: [PATCH 2/2] Update mapping.md --- docs/advanced/mapping.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/advanced/mapping.md b/docs/advanced/mapping.md index c6ccf5a14..9ab155143 100644 --- a/docs/advanced/mapping.md +++ b/docs/advanced/mapping.md @@ -25,7 +25,8 @@ Multiple maps are supported in the latest versions by using `ledmapx.json` where Use -1 in the map for gaps/blank/null LEDs. The ledmap also allows defining the dimensions of a 2D matrix. -By specifying the `width` and `height` fields, these dimensions are used when the ledmap is applied. +In such case you do not need to set up 2D in settings. +By specifying the `width` and `height` fields, these dimensions are used as default matrix size when the ledmap is applied. #### Mapping Requirements @@ -33,15 +34,16 @@ Mapping is an advanced feature, and for the correct results the following requir * A same value must not appear multiple times in the mapping, except for -1. - Mapping works by changing the target LED of each color update. When an effect is rendered, the effect sets colors of a LEDs. + Mapping works by reordering the physical LEDs. + When an effect is rendered, the effect sets colors of a LEDs. For example, a rainbow effect might set first LED of the strip as Red, the second LED as Yellow and the third LED as Blue. 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. - In this case, the resulting color of the `LED[0]` is undefined. + In this case, the resulting color of the `LED[0]` will the last value set to it. -* 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. +* The ledmap should 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.