Update mapping.md - improve description of how LEDMAPs work, and how to use them

[gunjambi]

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

Summary by CodeRabbit

• Documentation
  • Enhanced ledmap configuration documentation with optional width and height fields for default matrix dimensions
  • Added "Mapping Requirements" section detailing validation rules for LED assignments
  • Added example illustrating serpentine 5x3 mapping setup with sacrificial LEDs

[blazoncek]

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

[blazoncek]

It is defined, the last set value.

[gunjambi]

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]

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.

[gunjambi]

Changed must -> should.

Partial mapping is nothing but trouble.

[blazoncek]

Partial mapping is nothing but trouble.

However, it is historical feature.

[blazoncek]

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

[gunjambi]

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]

This needs rewording.

[blazoncek]

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.

[gunjambi]

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.

[softhack007]

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.

[softhack007]

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.

[softhack007]

• 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]

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":[

[DedeHai]

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.

[softhack007]

@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.

[DedeHai]

only saw this now. it pretty prints in the editor but always saves as minified.

[softhack007]

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.

[gunjambi]

My intention here was exactly that you cannot cannot map many-to-one. And the explanation is tries to explain that any logical led 1,2,3 all changes the physical led 0.

One problem I suffered here is the lack of terminology. We all know what physical leds are, they are the physical leds on a strip. But what are the leds on the wled "canvas" the ones I can peek in UI? I avoided using "logical" as that is only used in code, and "virtual" is used for led grouping thing which is a separate feature.

I feel I should draw a figure of the how the rendering pipelien works here, but I don't know the system well enough for it to be correct. My current understanding is:

Would this make it easier to understand and is this correct? This would have helped me, but I'm partial since I've already done the unhappy source code spelunking trying to fix my lights. The above pic is a draw.io diagram so feel free to edit it.

[softhack007]

@gunjambi I like your idea with the figure 👍

a few ideas:

• the grouping & spacing box actually should have some additions: mirroring & reverse, transpose, 1D2D Mapping, offset (1D). Or just call it "segment transformations" and keep grouping/spacing as examples
• if you want to be complete, there is actually a box "segment blending" missing - before "logical canvas"
• The "mapping" box could look like a real table (2 columns) where column 1 is fixed (0.... n) and column 2 is the numbers from the ledmap (like 0,1,4,5,2,3)

not sure all this extra info will make the drawing clearer - if this just add clutter, better to "keep it simple"

Good point about terminology - I don't have a good solution for this, but maybe that's a good question to ask in our Discord sub-channel for documentation.

Thanks for your effort 🥇

[coderabbitai]

Walkthrough

Documentation for LED mapping configuration is updated to clarify the ledmap structure, adding optional width and height fields for setting default matrix dimensions. A new "Mapping Requirements" section details validation rules and introduces a serpentine layout example with sacrificial LEDs.

Changes

Cohort / File(s)	Summary
Documentation Updates docs/advanced/mapping.md	Removes "now" from opening sentence; documents optional width and height fields for ledmap; adds "Mapping Requirements" section specifying uniqueness validation (no repeated non--1 values) and coverage rules; adds serpentine 5×3 example with sacrificial LEDs and full-length map array.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A hop, skip, and blink—
The map now shines bright and clear,
With width, height, and rules so fine,
Each LED finds its rightful line,
No more guessing—just serpentine shine! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately describes the main change: updating mapping.md documentation to improve descriptions of how LEDMAPs work and how to use them, which aligns with the PR's objectives to clarify mapping requirements and add examples.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[softhack007]

@coderabbitai please review, and summarize open ends and suggested improvements in a prioritized list.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Get PR details and diff
gh pr view 293 --repo wled/WLED-Docs --json title,body,files,additions,deletions
echo "---DIFF---"
gh pr diff 293 --repo wled/WLED-Docs

Length of output: 3902

---

@softhack007 Here is a prioritized review of the PR changes in docs/advanced/mapping.md:

---

🔴 Priority 1 — Typos & Grammar (affects correctness/readability)

1. "sacrifical" → "sacrificial" — misspelled consistently throughout the diff (3 occurrences in the file, and also in the PR title/description).

2. Missing word "be" — in the duplicate-value bullet:

   "the resulting color of the LED[0] will the be the last value set to it."

3. Article error — "the effect sets colors of a LEDs" → "the effect sets colors of the LEDs" (or just "sets LED colors").

4. Inconsistent capitalisation — "physical LEDS" should be "physical LEDs" (appears once in the requirements section).

5. Double space — "reordering the  physical LEDs" has two spaces after "the".

6. Determiner — "A same value must not appear" → "The same value must not appear".

7. Lowercase LED — "every physical led" → "every physical LED"; "a sacrifical led between each row" → "a sacrificial LED".

---

🟠 Priority 2 — Content Clarity

8. Tautological sentence — The following sentence says nothing useful and is circular:

   "Note that the total number of LEDs in the system is the number of LEDs in the system."

   It should instead explain why the count may be larger than width × height — e.g.: "Note that the total LED count includes any sacrificial/gap LEDs that are wired into the strip but excluded from the visible matrix."

9. Fate of sacrificial LEDs not explained — The example describes sacrificial LEDs at physical positions 5 and 11 but never explains what happens to them at runtime (e.g., they remain off/unaddressed). A one-sentence clarification would help.

10. No visual layout for the serpentine example — The sacrificial-LED example is the most complex in the document. An ASCII diagram of the physical wiring (showing positions 0–16 with the two sacrificial positions marked) would significantly aid comprehension, comparable to the existing mapping_infinity_shape.png diagram used elsewhere.

---

🟡 Priority 3 — Structure & Consistency

11. Missing subsection heading for the 2D-matrix paragraph — The new paragraph about width/height fields is inserted without a heading (e.g., #### 2D Matrix Dimensions), making it inconsistent with the rest of the document which uses headings for each topic. The "Mapping Requirements" section directly below it does have a heading.

12. Abrupt transition — The 2D-matrix paragraph flows directly into the "Mapping Requirements" section with no bridging sentence, making the document feel disjointed at that point.

13. No example for the duplicate-values requirement — The first requirement (no duplicate values except -1) is explained in prose but has no small illustrative JSON snippet. A brief bad/good example (like [0, 0, 0] vs [2, 1, 0]) would reinforce the concept at a glance, consistent with the style used for the second requirement.

---

Summary table

#	Issue	Priority
1–7	Typos/grammar (sacrificial, missing "be", "a LEDs", LEDS, double space, "A same", led)	🔴 High
8	Tautological sentence about LED count	🟠 Medium
9	No explanation of sacrificial LED runtime behaviour	🟠 Medium
10	No visual/ASCII diagram for serpentine+sacrificial example	🟠 Medium
11	Missing heading for 2D matrix paragraph	🟡 Low
12	Abrupt transition between paragraphs	🟡 Low
13	No illustrative JSON snippet for duplicate-values requirement	🟡 Low

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/advanced/mapping.md`:
- Around line 117-129: Replace the fenced triple-backtick JSON example in the
docs/advanced/mapping.md with an indented code block to satisfy markdownlint
MD046; locate the JSON example (the "map"/"width"/"height" snippet) and convert
it from a fenced block to a four-space indented block (preserving the JSON
content exactly) so the example is rendered as an indented code block instead of
a fenced one.
- Line 113: Fix the spelling typo in the example sentence that currently reads
"sacrifical" — change the word "sacrifical" to "sacrificial" in the markdown
content (search for the phrase "sacrifical led" in docs/advanced/mapping.md and
replace it with "sacrificial led") so the example reads "sacrificial led between
each row".
- Around line 35-45: Rewrite the paragraph for grammar and capitalization:
change "A same value" to "The same value", fix "a LEDs" to "the LEDs", change
"LEDS" to "LEDs", and add the missing word so the sentence reads "the resulting
color of the `LED[0]` will be the last value set to it"; keep references to
`map`, `LED[0]`, `LED[1]`, `LED[2]` and the example mapping `[2, 1, 0]` intact
and ensure consistent capitalization of "LED" throughout.

🪄 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

Run ID: 363a274c-e8ca-44c6-98d6-2ea92c38861c

📥 Commits

Reviewing files that changed from the base of the PR and between b702911 and a7979b6.

📒 Files selected for processing (1)

• docs/advanced/mapping.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix grammar/capitalization errors in the core rule explanation.

Several wording issues reduce clarity in a key section (e.g., Line 35 “A same value”, Line 38 “a LEDs”, Line 40 “LEDS”, Line 44 missing “be”).

Suggested edit

-* A same value must not appear multiple times in the mapping, except for -1.
+* The same value must not appear multiple times in the mapping, except for -1.

-  Mapping works by reordering the  physical LEDs.
-  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 the 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]`.
+  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]` will the last value set to it.
+  In this case, the resulting color of `LED[0]` will be the last value set to it.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/advanced/mapping.md` around lines 35 - 45, Rewrite the paragraph for
grammar and capitalization: change "A same value" to "The same value", fix "a
LEDs" to "the LEDs", change "LEDS" to "LEDs", and add the missing word so the
sentence reads "the resulting color of the `LED[0]` will be the last value set
to it"; keep references to `map`, `LED[0]`, `LED[1]`, `LED[2]` and the example
mapping `[2, 1, 0]` intact and ensure consistent capitalization of "LED"
throughout.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Align with markdownlint MD046 code block style.

Static analysis flags this new JSON example as fenced while MD046 expects indented style for this doc.

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 117-117: Code block style
Expected: indented; Actual: fenced

(MD046, code-block-style)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/advanced/mapping.md` around lines 117 - 129, Replace the fenced
triple-backtick JSON example in the docs/advanced/mapping.md with an indented
code block to satisfy markdownlint MD046; locate the JSON example (the
"map"/"width"/"height" snippet) and convert it from a fenced block to a
four-space indented block (preserving the JSON content exactly) so the example
is rendered as an indented code block instead of a fenced one.

[softhack007]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win
Align with markdownlint MD046 code block style.

@coderabbitai Please explain what needs to be changed - the example should still be shown in a "code example" style.

[coderabbitai]

@softhack007 — happy to clarify. The rendered output would not change either way; it's purely a Markdown syntax question.

What MD046 is flagging

MD046 enforces a consistent code-block style across the whole document — either all blocks use fenced style (triple backticks) or all blocks use indented style (four leading spaces). The document currently starts with indented blocks for the simple examples:

    {"map":[0,2,1,3]}

…which causes the linter to expect the "indented" style everywhere. The new JSON snippet uses fenced style (```json), triggering the warning.

What the "fix" would look like

Converting to indented style means replacing:

```json
{
  "map": [
     0,  1,  2,  3,  4,
    ...
  ],
  "width":  5,
  "height": 3
}
```

with four-space-indented lines:

    {
      "map": [
         0,  1,  2,  3,  4,
        ...
      ],
      "width":  5,
      "height": 3
    }

Both render as a code block in the browser — the example would still look like a code example.

However — this is a pre-existing inconsistency

The document already has multiple fenced blocks (the serpentine example, the 4×3 grid, the ∞ shape — all use ```json), so the mixed style is not introduced by this PR. Fixing only the new block while leaving the others fenced would actually make things more inconsistent.

The most sensible resolution is one of:

1. Configure MD046 to expect fenced style (preferred, since fenced blocks support json syntax-hint while indented ones do not).
2. Suppress MD046 for this file (e.g. via a .markdownlint.json or .markdownlint.yaml rule override).
3. Leave as-is and treat this as a pre-existing lint issue out of scope for this PR.

Option 1 is the cleanest long-term fix and doesn't require touching any content.

---

🧠 Learnings used

Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:327-337
Timestamp: 2026-05-01T12:08:39.081Z
Learning: In WLED-Docs (wled/WLED-Docs), the FAQ under "Bundling WLED with custom hardware" is intentionally written as plain-language guidance for integrators, not as a legally precise document. Avoid suggesting overly exact legal language (e.g., "commit hash", "exact release tag") in this section; simple readable phrasing like "in the exact version you're shipping" is preferred by the maintainers.

---

Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:304-310
Timestamp: 2026-05-01T12:15:59.568Z
Learning: In wled/WLED-Docs FAQ (docs/basics/faq.md), when softening definitive legal statements (e.g., "is not considered a derivative work"), prefer minimal hedge words like "generally" or "typically" rather than adding extra paragraphs or repeated legal disclaimers. The existing "Consult a Lawyer" admonition block at the top of the licensing section already covers the legal-advice caveat; do not duplicate it in-line.

---

Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:321-326
Timestamp: 2026-05-01T12:10:43.108Z
Learning: When documenting or advising about WLED licensing/distribution under EUPL-1.2, treat WLED build environment files such as platformio.ini and platformio_override.ini as part of the firmware source code: they are required to rebuild the firmware and must be shared with recipients when distributing a modified WLED build. In contrast, treat LittleFS runtime user data/config files (e.g., presets.json, cfg.json, ledmap.json, etc.) as runtime user data that are not subject to this source-code disclosure requirement. Ensure your documentation reflects this distinction consistently.

[softhack007]

@coderabbitai please suggest a possibly better wording instead of "programmatically"

[coderabbitai]

@softhack007, here are a few alternatives, roughly from simplest to most descriptive:

Option	Resulting sentence
"in software"	WLED has the ability to remap your LED strip in software.
"via configuration"	WLED has the ability to remap your LED strip via configuration.
"using a mapping file"	WLED has the ability to remap your LED strip using a mapping file.
"without physical rewiring"	WLED has the ability to remap your LED strip without physical rewiring.
"through software, without rewiring"	WLED has the ability to remap your LED strip through software, without rewiring.

My personal recommendation would be "without physical rewiring" — it immediately conveys the practical benefit to a hardware-oriented audience (no need to resolder or rearrange wires), and it doesn't assume any coding background. Alternatively, "using a mapping file" ties naturally to the very next paragraph that introduces ledmap.json.

---

🧠 Learnings used

Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:327-337
Timestamp: 2026-05-01T12:08:39.081Z
Learning: In WLED-Docs (wled/WLED-Docs), the FAQ under "Bundling WLED with custom hardware" is intentionally written as plain-language guidance for integrators, not as a legally precise document. Avoid suggesting overly exact legal language (e.g., "commit hash", "exact release tag") in this section; simple readable phrasing like "in the exact version you're shipping" is preferred by the maintainers.

---

Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:304-310
Timestamp: 2026-05-01T12:15:59.568Z
Learning: In wled/WLED-Docs FAQ (docs/basics/faq.md), when softening definitive legal statements (e.g., "is not considered a derivative work"), prefer minimal hedge words like "generally" or "typically" rather than adding extra paragraphs or repeated legal disclaimers. The existing "Consult a Lawyer" admonition block at the top of the licensing section already covers the legal-advice caveat; do not duplicate it in-line.

---

Learnt from: softhack007
Repo: wled/WLED-Docs PR: 310
File: docs/basics/faq.md:321-326
Timestamp: 2026-05-01T12:10:43.108Z
Learning: When documenting or advising about WLED licensing/distribution under EUPL-1.2, treat WLED build environment files such as platformio.ini and platformio_override.ini as part of the firmware source code: they are required to rebuild the firmware and must be shared with recipients when distributing a modified WLED build. In contrast, treat LittleFS runtime user data/config files (e.g., presets.json, cfg.json, ledmap.json, etc.) as runtime user data that are not subject to this source-code disclosure requirement. Ensure your documentation reflects this distinction consistently.