More usermod doc tweaks#331
Conversation
GitHub doesn't support multiple forks of the same repo, so instead the example usermod should be used as a template.
Symlink instructs PlatformIO to track changes.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
WalkthroughThis PR updates usermod documentation to improve community transparency and developer workflows. It adds a prominent safety warning and license tracking to the community usermods index, while simultaneously updating the usermod development guide to recommend template-based repository creation and symlink-based local development instead of forking and file-based paths. ChangesUsermod Documentation Improvements
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches✨ Simplify code
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. 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
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/advanced/community-usermods.md`:
- Around line 9-31: The warning blanket currently states all listed usermods are
community-maintained but the table includes an official module (`user_fx` by
`@wled`) and the example template (`wled-usermod-example`), so update the text to
scope the warning to third-party usermods only: either change the heading/body
to say "third-party usermods" and ensure official entries like `user_fx` are
exempt, or move official entries (`user_fx`, `wled-usermod-example`) into a
separate "Official/Included modules" section and keep the warning box above the
third-party list; update any wording that implies the project doesn't maintain
those specific official modules accordingly.
In `@docs/advanced/custom-features.md`:
- Around line 66-76: Update the Windows symlink URI example in the docs to use
the correct PlatformIO format with two slashes
(symlink://C:/Users/you/projects/my-wled-usermod) instead of the triple-slash
form; leave the POSIX example (`symlink:///home/you/projects/my-wled-usermod`)
unchanged so the `platformio_override.ini` snippet and the explanatory sentence
reflect the proper `symlink://<path>` syntax.
🪄 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: 96a562c9-73e3-4219-a960-47cbe84633ce
📒 Files selected for processing (2)
docs/advanced/community-usermods.mddocs/advanced/custom-features.md
| !!! warning "Community content — use at your own risk" | ||
| The usermods listed below are created and maintained by community members, **not** the WLED development team. | ||
| **The WLED project does not review, test, endorse, or provide support for any of these modules.** | ||
|
|
||
| Open a pull request to [WLED-Docs](https://github.com/wled/WLED-Docs) adding a row to the table below. One row, one PR. | ||
| Usermods are native C++ code compiled directly into your WLED firmware. A usermod runs with | ||
| **full, unrestricted access** to your device's hardware, network, and memory — there is no | ||
| sandbox or permission system to limit what it can do. Before installing a third-party build: | ||
|
|
||
| - **Read the source code** (or have someone you trust read it) before flashing. | ||
| - Be aware that a malicious or poorly written usermod could expose your network, **brick your | ||
| device**, or behave in ways its description does not mention. | ||
| - Only flash firmware from sources you trust. Prefer builds you compile yourself from | ||
| reviewed source code over pre-compiled binaries distributed by strangers. | ||
|
|
||
| The WLED project cannot verify the safety or quality of community usermods. | ||
| **You are solely responsible for any third-party code you choose to run on your devices.** | ||
|
|
||
| ## Index | ||
|
|
||
| | Name | Description | Author | Platforms | License | Notes | | ||
| |---|---|---|---|---|---| | ||
| | [wled-usermod-example](https://github.com/wled/wled-usermod-example) | Annotated template — use as template to start your own usermod | @wled | both | EUPL | Official starting point | | ||
| | [user_fx](https://github.com/wled/WLED/tree/main/usermods/user_fx) | Community effects usermod — add your own effects here or use as a template | @wled | both | EUPL | Ships with WLED; enable with `custom_usermods = user_fx` | |
There was a problem hiding this comment.
Scope the warning to third-party usermods.
The box says every usermod below is community-maintained, but Line 31 also lists user_fx, which is marked as shipping with WLED and authored by @wled. Narrow the warning or split the official example out so the statement stays accurate.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/advanced/community-usermods.md` around lines 9 - 31, The warning blanket
currently states all listed usermods are community-maintained but the table
includes an official module (`user_fx` by `@wled`) and the example template
(`wled-usermod-example`), so update the text to scope the warning to third-party
usermods only: either change the heading/body to say "third-party usermods" and
ensure official entries like `user_fx` are exempt, or move official entries
(`user_fx`, `wled-usermod-example`) into a separate "Official/Included modules"
section and keep the warning box above the third-party list; update any wording
that implies the project doesn't maintain those specific official modules
accordingly.
| In `platformio_override.ini`, point `custom_usermods` at the local clone using a `symlink://` URL: | ||
|
|
||
| ```ini | ||
| [env:esp32dev_my_usermod] | ||
| extends = env:esp32dev | ||
| custom_usermods = | ||
| ${env:esp32dev.custom_usermods} | ||
| file:///home/you/projects/my-wled-usermod | ||
| symlink:///home/you/projects/my-wled-usermod | ||
| ``` | ||
|
|
||
| On Windows, use the `file:///C:/Users/you/...` form with forward slashes: `file:///C:/Users/you/projects/my-wled-usermod`. | ||
| On Windows, use the `symlink:///C:/Users/you/...` form with forward slashes: `symlink:///C:/Users/you/projects/my-wled-usermod`. |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
PlatformIO symlink:// URI syntax local path example Windows vs POSIX custom_usermods
💡 Result:
PlatformIO supports the symlink:// URI syntax to include local directories as dependencies while allowing changes in the source folder to affect the installed package, as opposed to file:// which typically performs a hard copy [1][2]. Syntax and Examples The URI structure is symlink://<path_to_directory> [1]. POSIX (Linux/macOS) Example: lib_deps = symlink:///home/user/projects/my_library Windows Example: lib_deps = symlink://C:/Users/User/Projects/my_library PlatformIO also supports relative paths, which are resolved against the project directory [3]. For example: lib_deps = symlink://../my_local_library Windows vs. POSIX Considerations While the symlink:// syntax is cross-platform, users have reported that symlinked libraries on Windows can occasionally experience issues with dependency resolution or build failures, particularly when using specific Library Dependency Finder (LDF) modes like lib_ldf_mode = off [4]. Clearing the.pio/libdeps directory is a common troubleshooting step if the build fails to recognize changes or locate the symlinked files [4]. Recent core updates have improved the robustness of symlink path resolution, including canonicalizing absolute paths and ensuring relative paths are correctly anchored to the project root [3]. Usage with Custom Usermods (e.g., WLED) In projects like WLED that utilize custom_usermods, the symlink approach is a powerful way to develop and test modules externally [5]. The custom_usermods property in platformio.ini allows referencing these external modules [6]. When integrating external usermods via symlink: 1. Ensure the referenced folder contains a valid manifest (e.g., library.json) [1][5]. 2. If the library name in library.json does not match the folder name, you can specify it using the alias syntax: =symlink:// [1]. 3. For WLED-specific usermods, ensure "libArchive": false is set in the module's library.json to ensure the code is linked directly into the firmware [5]. Automation scripts (like those used in WLED) often handle the parsing of these entries and inject them into the lib_deps list to ensure PlatformIO correctly manages them as dependencies [7][6]. If an external module is not being detected, check that the automation logic is correctly parsing your URI format and adding it to the project's dependency list [7].
Citations:
- 1: https://docs.platformio.org/en/latest/core/userguide/pkg/cmd_install.html
- 2: https://github.com/platformio/platformio-docs/blob/develop/core/userguide/pkg/cmd_install.rst
- 3: bind symlink:// relative paths to project dir (fix #5201) platformio/platformio-core#5238
- 4:
lib_ldf_mode = offfails to resolve symlinked dependencies on Windows (works on WSL) platformio/platformio-core#5421 - 5: https://kno.wled.ge/advanced/custom-features/
- 6: Convert usermods to static libraries WLED#4480
- 7: custom_usermod improvements WLED#5403
Fix the Windows symlink:// URI example (keep POSIX as-is).
symlink:///home/... matches PlatformIO’s documented symlink://<path> format, but Windows should be symlink://C:/Users/you/projects/my-wled-usermod (double slash) rather than symlink:///C:/Users/....
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/advanced/custom-features.md` around lines 66 - 76, Update the Windows
symlink URI example in the docs to use the correct PlatformIO format with two
slashes (symlink://C:/Users/you/projects/my-wled-usermod) instead of the
triple-slash form; leave the POSIX example
(`symlink:///home/you/projects/my-wled-usermod`) unchanged so the
`platformio_override.ini` snippet and the explanatory sentence reflect the
proper `symlink://<path>` syntax.
1 participant
Summary by CodeRabbit