Rewrite of mapping.md to make it easier to follow and more complete#291
Rewrite of mapping.md to make it easier to follow and more complete#291azariah001 wants to merge 4 commits intowled:mainfrom
Conversation
Adjusted and added more section headings to aid in finding specific information. Expanded most sections with additional examples and specific callouts for config breaking issues, like not including a number in the filename and common file formatting issues. Also added a new section about the previously undocumented custom naming key "n".
blazoncek
left a comment
blazoncek
left a comment
There was a problem hiding this comment.
Thank you for contribution.
Unfortunately there are several incorrect and misleading bits. Please revise.
| Use this edit page to create a file called `ledmap.json`. | ||
| Use this edit page to create a file called `ledmap1.json`, where `1` is incremented for each map you load on your controller. | ||
|
|
||
| **Note:** If the filename is `ledmap.json`, the config file ***will not load***; the filename must end in a number even if there's only one config file. |
There was a problem hiding this comment.
That is untrue. ledmap.json is a default ledmap, loaded at boot or when "Default" is selected.
| The ArduinoJSON library is *****extremely***** white-space sensitive. | ||
| If your `ledmap.json` file is not working, check for white-spaces where they should not be. The LED positions are zero-indexed. | ||
| The ArduinoJSON library is *****extremely***** whitespace sensitive. | ||
| If your `ledmap1.json` file is not working, check for white-spaces where they should not be. |
There was a problem hiding this comment.
The best way is to minimize ledmap file and pass it through JSON parser 1st.
| ## Complicated maps | ||
|
|
||
| Use -1 in the map for gaps/blank/null LEDs. | ||
| LEDs can be mapped in the "map" array in any order, including out-of-order, allowing you to map custom and complex shapes using `-1` in the map for gaps/blank/null LEDs. In addition, not all LEDs in a segment need to be mapped in the map; you can leave out extra LEDs if they're not required. |
There was a problem hiding this comment.
-1 translates to 65535 but any number above actual LED count will provide similar result - placeholder for skipped LED.
There was a problem hiding this comment.
for sake of "keep it simple", I think we can still tell users that "-1" is the best way.
| ``` | ||
|
|
||
|
|
||
| ### Multi-line array, helpful in visualising 2D matrices |
There was a problem hiding this comment.
2D ledmap requires "width" and "height" keys. If omitted, the resulting ledmap is 1D and WLED will refuse to provide 2D support. Please include that info if you are suggesting to split lines for 2D.
| {"n": "Double infinity map.", | ||
| "map": | ||
| [ | ||
| -1, -1, 14, -1, 12, -1, 10, -1, -1, |
There was a problem hiding this comment.
In the preceding lines there was a warning about spaces and in this example, there are plenty of spaces present. Please avoid contradicting information.
|
|
||
| The ArduinoJSON library is *****extremely***** white-space sensitive. | ||
| If your `ledmap.json` file is not working, check for white-spaces where they should not be. The LED positions are zero-indexed. | ||
| The ArduinoJSON library is *****extremely***** whitespace sensitive. |
There was a problem hiding this comment.
Please substitute "ArduinoJSON" with "JSON parsing". Things have changed and ArduinoJSON is no longer responsible for ledmap handling.
|
Is this PR complementary to PR #293 ? Or is it about the same documentation parts? |
softhack007
added
the
in progress
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughThis pull request updates documentation for the LED mapping feature, restructuring section headings and reorganizing the mapping workflow to use numbered map configuration files ( Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ 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. Review rate limit: 0/1 reviews remaining, refill in 43 minutes and 37 seconds.Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (3)
docs/advanced/mapping.md (3)
25-25:⚠️ Potential issue | 🟠 Major | ⚡ Quick winCorrect
ledmap.jsonload behavior statement.Line 25 currently says
ledmap.jsonwill not load, which conflicts with existing behavior and will mislead users about defaults. Please correct this section to distinguish default-map loading vs numbered map selection.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/advanced/mapping.md` at line 25, The sentence claiming "If the filename is `ledmap.json`, the config file will not load" is incorrect; update the text to explain that `ledmap.json` is treated as the default map and will load by default, whereas numbered filenames (e.g., `ledmap1.json`, `ledmap2.json`) are used for explicit map selection: rewrite the line to state that `ledmap.json` loads as the default map and only use numbered filenames when choosing a specific map index.
32-36:⚠️ Potential issue | 🟠 Major | ⚡ Quick winReplace outdated parser attribution and whitespace warning.
This section appears inaccurate: it attributes handling to ArduinoJSON and warns about extreme whitespace sensitivity. Please reword to generic JSON validity/minification guidance and remove parser-specific claims unless they’re currently true.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/advanced/mapping.md` around lines 32 - 36, Replace the ArduinoJSON-specific claim and whitespace warning in the paragraph that currently reads about "The ArduinoJSON library" and the note about added whitespace: remove any parser-specific attribution and instead state a generic JSON validity/minification guidance (e.g., "JSON parsers require valid JSON; extra or misplaced whitespace/formatting can break some parsers or examples—use a JSON validator or minifier before use"), update the note about examples to warn that added whitespace for readability may need removal or validation before copying, and ensure the wording no longer names ArduinoJSON unless you can verify that library is definitely required by the project.
94-94:⚠️ Potential issue | 🟠 Major | ⚡ Quick winCorrect 2D requirement wording for
width/height.Line 94 says
widthandheightaren’t required, but for actual 2D behavior they are required. Please update wording to prevent users from ending up with a 1D map unexpectedly.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/advanced/mapping.md` at line 94, The sentence currently says `width` and `height` aren’t required but should be changed to state that while those keys are optional for simple 1D maps, they are required for true 2D behavior; update the paragraph around the `ledmap1.json` example (mentioning `width`, `height`, and the map array) to clearly say that to interpret the array as a two-dimensional grid you must include `width` and `height`, and that omitting them will result in the map being treated as a 1D string.
🤖 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`:
- Line 81: Fix the user-facing heading typo by changing the heading text "1D
redordering example" to "1D reordering example" in the docs/advanced/mapping.md
file (update the heading string used for the section title "1D redordering
example").
- Line 42: The cfg.json example is malformed; replace the partial snippet
{"ledmap":x,...} with a valid JSON example or mark it clearly as partial. Update
the docs text to show a complete valid entry such as a JSON object containing a
numeric ledmap property (e.g., "ledmap": 1) within cfg.json and mention that x
corresponds to the number in ledmapx.json, or explicitly prefix the snippet with
"partial:" to prevent copy/paste errors; ensure references to ledmapx.json and
the ledmap setting in cfg.json remain intact.
---
Duplicate comments:
In `@docs/advanced/mapping.md`:
- Line 25: The sentence claiming "If the filename is `ledmap.json`, the config
file will not load" is incorrect; update the text to explain that `ledmap.json`
is treated as the default map and will load by default, whereas numbered
filenames (e.g., `ledmap1.json`, `ledmap2.json`) are used for explicit map
selection: rewrite the line to state that `ledmap.json` loads as the default map
and only use numbered filenames when choosing a specific map index.
- Around line 32-36: Replace the ArduinoJSON-specific claim and whitespace
warning in the paragraph that currently reads about "The ArduinoJSON library"
and the note about added whitespace: remove any parser-specific attribution and
instead state a generic JSON validity/minification guidance (e.g., "JSON parsers
require valid JSON; extra or misplaced whitespace/formatting can break some
parsers or examples—use a JSON validator or minifier before use"), update the
note about examples to warn that added whitespace for readability may need
removal or validation before copying, and ensure the wording no longer names
ArduinoJSON unless you can verify that library is definitely required by the
project.
- Line 94: The sentence currently says `width` and `height` aren’t required but
should be changed to state that while those keys are optional for simple 1D
maps, they are required for true 2D behavior; update the paragraph around the
`ledmap1.json` example (mentioning `width`, `height`, and the map array) to
clearly say that to interpret the array as a two-dimensional grid you must
include `width` and `height`, and that omitting them will result in the map
being treated as a 1D string.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 1f3bd3de-341a-4c7c-b3fa-3a1873d90808
📒 Files selected for processing (1)
docs/advanced/mapping.md
| 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. | ||
|
|
||
| ### How do we do it? | ||
| LED Maps replace and over-ride the older Gap system. **Note:** that if a `ledmap.json` file exists, the `2d-gaps.json` file will be ignored. |
There was a problem hiding this comment.
over-ride => override (@coderabbitai please confirm)
There was a problem hiding this comment.
@softhack007, confirmed. "Override" is the standard dictionary spelling — the hyphenated form "over-ride" is non-standard/archaic. The correction to override is appropriate here.
🧠 Learnings used
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.
There was a problem hiding this comment.
@coderabbitai please trace through the related source code https://github.com/wled/WLED/blob/49f653c621a859d1f0567d02d143b2e1a8eefab2/wled00/FX_2Dfcn.cpp#L21 and https://github.com/wled/WLED/blob/49f653c621a859d1f0567d02d143b2e1a8eefab2/wled00/FX_fcn.cpp#L2058, and check if the statement "LED Maps preplace and override ..." is correct.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Fetch FX_2Dfcn.cpp around line 21
curl -s "https://raw.githubusercontent.com/wled/WLED/49f653c621a859d1f0567d02d143b2e1a8eefab2/wled00/FX_2Dfcn.cpp" | head -60
echo "---SEPARATOR---"
# Fetch FX_fcn.cpp around line 2058
curl -s "https://raw.githubusercontent.com/wled/WLED/49f653c621a859d1f0567d02d143b2e1a8eefab2/wled00/FX_fcn.cpp" | awk 'NR>=2040 && NR<=2100'
Length of output: 5683
Let me also search for any references to 2d-gaps.json in the WLED codebase to verify if that file name is accurate.
🏁 Script executed:
#!/bin/bash
# Search for 2d-gaps.json in the WLED codebase via GitHub API
curl -s "https://api.github.com/search/code?q=2d-gaps+repo:wled/WLED" \
-H "Accept: application/vnd.github.v3+json" | jq '.total_count, (.items[]? | {path: .path, name: .name})'
echo "---SEPARATOR---"
# Also check for any "gaps" related file loading logic
curl -s "https://raw.githubusercontent.com/wled/WLED/49f653c621a859d1f0567d02d143b2e1a8eefab2/wled00/FX_fcn.cpp" | grep -n -i "gap\|2d-gap" | head -30
Length of output: 90
@softhack007, after tracing through both source files, the statement is partially incorrect — specifically, the reference to 2d-gaps.json.
Findings
From FX_fcn.cpp (deserializeMap()):
The relevant logic is:
if (!isFile && n==0 && isMatrix) {
// 2D panel support creates its own ledmap (on the fly) if a ledmap.json does not exist
setUpMatrix();
return false;
}
if (!isFile || ...) return false;So the actual behavior is:
- If
ledmap.json(index 0, no suffix) does not exist and the device is in matrix mode →setUpMatrix()is called (panel-based mapping from UI/cfg.json) - If
ledmap.jsondoes exist → the file is loaded, andsetUpMatrix()is skipped
From FX_2Dfcn.cpp (setUpMatrix()):
This function builds customMappingTable from the panel[] array (populated from UI configuration stored in cfg.json). There is no reference to any 2d-gaps.json file here or anywhere else.
GitHub code search for 2d-gaps in wled/WLED: returned zero results. The file 2d-gaps.json does not exist in the WLED codebase at all.
Summary of issues in the doc statement
| Claim | Verdict |
|---|---|
| "LED Maps replace and override the older Gap system" | ✅ Directionally correct — ledmap.json takes precedence over setUpMatrix() (UI panel config) |
"if a ledmap.json file exists, the 2d-gaps.json file will be ignored" |
❌ 2d-gaps.json is a non-existent file name; the "Gap system" is actually the UI panel/matrix configuration (setUpMatrix()) stored in cfg.json |
Suggested correction
The sentence should reference the actual "Gap" system — which is the 2D panel configuration set up via the UI (stored in cfg.json):
LED Maps replace and override the older Gap system. Note: If a
ledmap.jsonfile exists, any 2D panel/matrix configuration set up via the UI will be ignored and the LED map file will be used instead.
🧠 Learnings used
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.
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: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.
There was a problem hiding this comment.
agreed with one correction: the file 2d-gaps.json is used when exiting in LittleFS. However it is applied together with the 2D panel configuration (order top/bottom or left/light, linear or serpentine).
If a ledmap.json (or ledmapx.json) is selected by the user, the complete 2D panel configuration is replaced by the layout described in the ledmap file.
There was a problem hiding this comment.
@softhack007, thank you for the correction! I apologize for the confusion — my GitHub code search only scanned the C++ source files and didn't account for 2d-gaps.json being a runtime LittleFS file rather than a hardcoded source filename.
So to summarize the corrected understanding:
2d-gaps.jsondoes exist in LittleFS and is applied alongside the 2D panel configuration (top/bottom, left/right, linear/serpentine order)- Selecting a
ledmap.jsonorledmapX.jsonreplaces the entire 2D panel configuration (including2d-gaps.json) with the layout from the ledmap file
With that in mind, the original doc sentence is directionally correct. A slightly more precise revision might be:
LED Maps replace and override the older Gap system. Note: If a
ledmap.json(orledmapX.json) is selected, the complete 2D panel configuration — including any2d-gaps.json— will be ignored and replaced by the layout described in the LED map file.
🧠 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.
There was a problem hiding this comment.
@coderabbitai please add a learning: WLED has an on-device filesystem (LittleFS). This filesystem stores user configuration files (cfg.json, presets.json), and optional user files in JSON format like 2d-gaps.json, ledmap.json, ledmapX.json - these files are not stored in the main WLED repo. The filesystem can also be used for small additional files like .gif animations (image effect), or for extra files served by the embedded webserver (like pixelforge.htm.gz).
There was a problem hiding this comment.
@softhack007, noted and added to long-term memory!
🧠 Learnings used
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.
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.
3 participants
Adjusted and added more section headings to aid in finding specific information.
Expanded most sections with additional examples and specific callouts for config breaking issues, like not including a number in the filename and common file formatting issues.
Also added a new section about the previously undocumented custom naming key "n".
Summary by CodeRabbit