Serial
WLED 0.13.0 supports multiple protocols over Serial. Serial is available via USB, and on most boards, GPIO1 for TX and GPIO3 for RX.
Pin usage limitation
If GPIO3 is allocated (e.g. for LED output), all Serial functionality except debug output is unavailable.
If GPIO1 is allocated, all Serial output is disabled, including the JSON API response, Improv, and tpm2 output.
Adalight and tpm2
Both these protocols are supported and can be used to stream realtime LED data to WLED for direct display, e.g. from an bias lighting program. For tpm2, only data packets are supported and data in 24-bit RGB format is expected.
If you want to drive a large amount of LEDs, you may need to increase the Baud rate in WLED Sync settings, as the default baud rate of 115200 is only sufficient for about 50-100 LEDs depending on the refresh rate.
Adalight is supported since WLED 0.6.3, tpm2 since version 0.10.2.
JSON over Serial
You can send commands to the WLED instance via Serial using the JSON API.
To request a JSON response containing the state and info objects, send {"v":true}.
Improv
Improv Serial is supported and can be used to check the installed software version as well as connect your device to WiFi without needing to connect to the WLED access point.
Improv is used by the WLED web installer for an easy installation and setup process.
Note that the baud rate must remain at the default 115200 setting for the device to be detected as Improv-capable.
Other
Version query
Send a lowercase 'v' character (byte 0x76) to obtain the ID of the installed WLED version.
LED data query
To get the colors currently displayed by LEDs:
-
Send an uppercase
'L'(byte0x4C) to request the current LED data as a tpm2 data packet in 24-bit RGB format. -
Send a lowercase
'l'(byte0x6C) to request the current LED data in JSON format. This returns the LED colors as 32-bit integers, of which the lowest byte is the Blue value, then Green, then Red, and the highest byte is the White channel value.
For both of these methods, you may need to increase the baud rate if you have a large amount of LEDs.
However, tpm2 requires on average 2-4x less bandwidth than JSON, and should therefore be preferred if your application can parse binary data.
Changing Baud Rate
There are 2 main method for changing Baud Rate for the serial connection - Persistant: Configure in App under Sync Interfaces. This setting will persist, and WLED will use specified Baud Rate from this point forward. - Temporary: Utilizing the serial connection at the existing Baud Rate, send the specific command byte to have WLED temporarily change to new Baud Rate. This Baud Rate is temporary and will be reset to default or peristant setting on reboot.
| Byte | Baud Rate |
|---|---|
0xB0 |
115200 |
0xB1 |
230400 |
0xB2 |
460800 |
0xB3 |
500000 |
0xB4 |
576000 |
0xB5 |
921600 |
0xB6 |
1000000 |
0xB7 |
1500000 |
| - Note: Keep at 115200 to use Improv. Some boards may not support high rates. |
Debugging
Compile with the -D WLED_DEBUG build flag to enable serial debugging using DEBUG_PRINTLN(x) macros.
This will reserve pin GPIO1, therefore it cannot be used for other purposes when debugging.