Add documentation for 16.0 usermod system#312
Conversation
Also clean up other small details in the Custom Features page. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adding new fx by usermod is the best way forward -- we don't want to confuse people by suggesting two different approaches. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add a place for showing off external usermod contributions! Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
WalkthroughAdds and restructures documentation for WLED usermods: a rewritten custom-features guide describing v2 class-based usermods, a compiling-wled subsection for ChangesUsermod docs, compilation, and site navigation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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 the current code and only fix it if needed.
Inline comments:
In `@docs/advanced/community-usermods.md`:
- Around line 15-17: The fenced code block containing the example table is
missing a language identifier which triggers MD040; update the opening fence for
that snippet (the triple backticks before the table row that includes
"[Name](https://github.com/you/your-usermod) | Short description | `@yourname` |
esp32 | |") to use a language tag (e.g., ```markdown) so the block is correctly
recognized as Markdown.
In `@docs/advanced/custom-features.md`:
- Around line 58-64: Add a language identifier to the fenced code block
containing the directory tree (the triple-backtick block showing "~/projects/
WLED/ my-wled-usermod/ ...") by changing the opening fence from ``` to ```text
(or ```plaintext) so the markdownlint MD040 rule is satisfied and the snippet is
treated as plain text.
🪄 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: 61c1db3a-0fb2-430f-88bb-87f7e4ae61f5
📒 Files selected for processing (4)
docs/advanced/community-usermods.mddocs/advanced/compiling-wled.mddocs/advanced/custom-features.mdmkdocs.yml
| ```cpp | ||
| long lastTime = 0; | ||
| int delayMs = 2000; //we want to do something every 2 seconds | ||
| Each line is a usermod name corresponding to a folder under `usermods/` (or a short alias — see the folder for exact names). Restart the PlatformIO build and the usermods are automatically included, no other file edits needed. |
There was a problem hiding this comment.
should mention the actual name is defined in the json file
There was a problem hiding this comment.
Hm. Maybe I should update load_usermods.py to scan library names for in-tree usermods instead of just accepting folder names. It'd be a little more work to index the folder, but it'd get rid of all the usermod_v2 handling crap.
| Writing effects as usermods is the recommended way to add new LED effects to a WLED build — no core source files need changing, and the effect can live in its own repository and be shared like any other usermod. | ||
|
|
||
| Here is a step-by-step guide on how to make your effect: | ||
| The `user_fx` usermod (`usermods/user_fx`) is the mainline example of this pattern and a convenient starting point. It bundles multiple effects in a single usermod and can be enabled with `custom_usermods = user_fx`. Fork it or use it as a template for your own effects usermod. |
There was a problem hiding this comment.
also mention it has a readme explaining in detail how to write WLED effects
There was a problem hiding this comment.
Will do.
Should we pull user_fx out to a separate example repo?
Pro - easy to fork for people who just want to add a new effect
Con - harder to keep in sync with core code, should the API change. Could play games with git submodules but that creates its own frictions
There was a problem hiding this comment.
I would keep it as it is, if a user wants to invest the time to write user FX, deleting the existing ones and renaming a few things is the least of the work. I personally do not like "examples" that only give you one single easy case, using the existing user effects as a look-up on how to do things is a good thing.
You could mention the other example we have: PS meteor or something, a UM with a single FX.
There was a problem hiding this comment.
Oh, I wasn't suggesting changing the code in user_fx - I agree that having many examples is good. The question is where is the best place to keep that code, either in-tree or out-of-tree.
There was a problem hiding this comment.
ah I get it now, I would keep it in the WLED repo, at least for the time being: it is a collection of FX that others may find useful to have compiled in. Having an example repo to fork for OOT is a good idea though.
|
good writeup |
| To include one or more usermods in your build, add a `custom_usermods` line to your environment in `platformio_override.ini`: | ||
|
|
||
| ```ini | ||
| [env:esp32dev] |
There was a problem hiding this comment.
Surely you need a new name if you are trying to extend env:esp32dev rather than override?
|
|
||
| ### Timing | ||
| ```ini | ||
| [env:esp32dev] |
| The forked example file contains a fully annotated version of this covering persistent settings (`addToConfig` / `readFromConfig`), JSON state, MQTT, and more. | ||
|
|
||
|
|
||
| #### Useful lifecycle methods |
There was a problem hiding this comment.
What about the new UDP reception?
There was a problem hiding this comment.
good point about the palettes, I will add that after this is merged in
|
About the muddy waters of licenses - I think we should add a statement somewhere about what EUPL-1.2 expects. The case for in-tree seems clear: EUPL-1.2. |
EUPL-1.2 and Library Licensing
|
That was my understanding as well: copyleft license clauses add requirements to distributing the binaries (or products containing the binaries), but as long as you don't share anything containing the build products with anyone else, you haven't broken any terms of the license -- even if your usermod is proprietary. Library components such as usermods are usually themselves individual works and can have their own licenses, it's only the linked binary that constitutes a derivative work. |
|
@willmmiles @netmindz good points, thanks. I'm not sure if we should just keep the new docs strictly technical (nothing about open source or not), or maybe add a minimal statement "for orientation"? Need to sleep over it 😴. What's your preference? |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
I'd say "that's out of scope for this PR" ;) Licensing of user customizations isn't a new issue to the 16.0 usermod system. There's no legal difference between linking an out-of-tree repo vs. forking the base and adding your own in-tree folders. In both cases you can license the new code you wrote however you want; our license applies only to our code and the build products. That said, a PR on top of this one that adds some encouragement for open source licensing is a good idea. |
4 participants
Update the documentation to provide details on the 16.0 usermod system, and add a new page to collect links to available external usermods.
Includes a number of small correctness fixes to the "custom features" page to bring the documentation in line with the current sources.
Summary by CodeRabbit