Add own functionality

This page is intended for those wishing to modify the WLED code to add their own functionality.

Basics

Programming is done in the Arduino IDE. There is a special file, wled06_usermod.ino, to write your own code. (however, if you think your code may be relevant to many users, feel free to code it in directly and open a pull request)

This file has three empty methods:

• userSetup() is called after loading settings but before connecting to WiFi. Use it to start own interfaces if it does not depend on WiFi (IR, Sensors, GPIOs,...). Also you can use it to load custom settings or to specify own server pages with the server.on() method.
• userConnected() is called once WiFi is connected. Use it to connect to external servers or init interfaces using wiFi.
• userLoop() is called by the main loop() function.

Modify WLED values

If you know what you're doing, you may choose to change the value of any global variable declared in wled00.ino. However, for basic color and brightness changes, these are the most important:

Variable Name	Type	Purpose
bri	byte (0-255)	Master Brightness (0 is off, 255 is maximum)
col[0]	byte (0-255)	Red color value
col[1]	byte (0-255)	Green color value
col[2]	byte (0-255)	Blue color value
col[3]	byte (0-255)	White color value

After updating the color, you must call the colorUpdated(int) method. If you want to send a notification with the new color to other ESPs, use colorUpdated(1), otherwise colorUpdated(5).

Timing

If you'd just like a simple modification that requires timing (like sending a request every 2 seconds), please never use the delay() function in your userLoop()! It will block everything else and WLED will become unresponsive and effects won't work! Instead, try this instead:

long lastTime = 0;
int delayMs = 2000; //we want to do something every 2 seconds

void userLoop()
{
  if (millis()-lastTime > delayMs)
  {
    lastTime = millis();
    //do something you want to do every 2 seconds
  }
}

Internal Segments API

You can use Segments from your code to set different parts of the strip to different colors or effects.
This can be very useful for highly customized installations, clocks, ...

To set a segment, use strip.setSegment(id, start, stop);, where id is the segment ID, start is the first LED of the segment and stop is the LED after the last one in the segment.

To edit the configuration of a segment, use:

WS2812FX::Segment& seg = strip.getSegment(id);
//set color (i=0 is primary, i=1 secondary i=2 tertiary)
seg.colors[i] = ((myWhite << 24) | ((myRed&0xFF) << 16) | ((myGreen&0xFF) << 8) | ((myBlue&0xFF)));
//set effect config
seg.mode = myFxI;
seg.speed = mySpeed;
seg.intensity = myIntensity;
seg.palette = myPaletteId;

Keep in mind that this will not cause interface updates as of 0.8.6. For that, you still need to use 'colorUpdated(1)'

Create custom effects

It is possible to create your own effects and add them to the FX library. The relevant files for that are FX.cpp and FX.h.

Here is a step-by-step guide on how to make your effect:

1. Take a look at some of the effects in FX.cpp to see how they are implemented!

2. TBD

If you programmed a nice effect you want to share, submit a pull request!

Web UI

Changes to the embedded web user interface are not convenient. The reason is that the HTML is gzipped and added to the code as a binary array in html_ui.h to boost speed and lower flash usage.

If you want to test changes to the UI, it is easiest to work with the local /wled00/data/index.htm file. You just need to change a single line to have the local file interface to an ESP with WLED installed. Preview

Change url = command ? '/json/state':'/json'; (0.9.1 line 1048, subject to change) to url = command ? 'http://[Your ESP IP address]/json/state':'http://[Your ESP IP address]/json';

Important: Do not forget to change it back before gzipping the UI file! Otherwise it will not work on any other WLED installation with a different IP address.

To serve your changes by the internal webserver, you will need to follow these or similar steps to gzip compress the index.html file:

• Gzip compress the file. I use this online converter, use setting Compress this file, output – gz

• Rename file to xxx.gz.png (change file type to image)

• Convert it to a C-style byte/char array. I use this converter, intended for image sprites. Therefore, the previous step of changing the file format was neccessary. Select Raw as Color format.

• Open the downloaded .c file in a text editor, e. g. Notepad++. Select the contents of the array and replace the array contents in html_ui.h with them.

• Update PAGE_index_L to the binary size stated in the bottom of the downloaded .c file

• Recompile and flash WLED!