WLED usermod example

This repository is a template for building your own WLED usermod as a standalone project. Fork it, add your code, and reference it from a WLED build — no changes to the WLED source tree needed.

Getting started

1. Fork and rename

Fork this repository on GitHub, then:

• Rename usermod_example.cpp to something descriptive (e.g. my_sensor.cpp)
• Rename the class inside from MyExampleUsermod to match
• Update "name" in library.json to match your repository name

2. Wire it into your WLED build

Clone your fork alongside your WLED checkout:

~/projects/
  WLED/
  my-wled-usermod/
    library.json
    my_sensor.cpp

In platformio_override.ini inside the WLED folder, add a file:// reference to your local clone:

[env:esp32dev]
extends = env:esp32dev
custom_usermods =
  ${env:esp32dev.custom_usermods}
  file:///home/you/projects/my-wled-usermod

Both projects are now open in the same VS Code session. PlatformIO picks up your changes on each build.

3. Share it

Once ready, others can reference your usermod directly by URL — no local clone needed:

custom_usermods =
  ${env:esp32dev.custom_usermods}
  https://github.com/you/my-wled-usermod.git#main

What's in this repo

library.json — PlatformIO library manifest. The "libArchive": false setting is required; without it the build will fail. Add any library dependencies here.

usermod_example.cpp — A fully annotated example covering all available lifecycle hooks:

Method	When called
setup()	Once at boot, after config is loaded, before WiFi
connected()	Each time WiFi (re)connects
loop()	Every main loop iteration
addToJsonInfo()	When /json/info is requested
addToJsonState() / readFromJsonState()	On /json/state get/post
addToConfig() / readFromConfig()	Persistent settings in cfg.json
appendConfigData()	When the Usermod Settings page renders
handleOverlayDraw()	Just before each LED strip update
handleButton()	On button events
onMqttMessage() / onMqttConnect()	MQTT events
onStateChange()	When WLED state changes

REGISTER_USERMOD(instance) at the bottom of the file handles self-registration — there is no usermods_list.cpp to edit.

For full documentation see the WLED Custom Features page.