junior/LEDController
junior/LEDController
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add information about UDP messaging protocol.

Browse Source
This commit is contained in:
Junior 2026-01-08 18:01:01 -05:00
parent 31462c5683
commit 92aad927e1
1 changed files with 90 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
README.md
View File

@ -1,3 +1,93 @@
# LEDController
This project should load onto just about any ESP8266 based microcontroller or dev board. It has been tested on the Adafruit ESP8266 Huzzah, and the NodeMCUv2/v3 development boards.
## UDP Messages
**Note!** As of Firmware v3.x+ there are some breaking API changes:
* Any message with color set data now includes RGBWW capability instead of just RGB.
* Target IDs are now parsed as a bitmask instead of a 32bit integer value comparison. This makes sending messages that target specific, multiple IDs possible, but limits the network to 31 unique zones (but unlimited number of controllers in those zones).
Each message consists of two four byte (32 bits) unique numbers used as a basic packet filter, four bytes (32 bits) for the message ID, a one byte (8 bits) command, four bytes (32 bits) for the target ID, followed by the appropriate data for the message type. Multiple targets can have the same ID. A target ID of 0 means "all targets".
The first and second four byte integers values are 4039196302 and 3194769291 respectively. The packet filter values are used to do a simple check that the incoming packet is meant for the device receiving it. Slow speed receivers may crash or hang if over-flooded with UDP packets. Since the receiver must listen for broadcast UDP there is a decent liklihood that other traffic may show up. Having a specific 64 bits of data at the very start of the packet drastically reduces the chance of thinking the packet needs to be processed which saves major clock cycles on slow receivers. If there is a better/simpler/more efficient way of doing this I'm open to suggestions.
| Name | Value | Description |
| :--- | ----: | :---------- |
| CMD_OFF | 0x00 | Turn off all colors (i.e. terminate auto patterns and set values to zero) |
| CMD_SETLEVELS | 0x01 | Message contains data to set one full color triplet (R,G,B) and rest value |
| CMD_AUTOPATTERN | 0x02 | Message contains data containing a ramp time along with NumColors number of color triplets to cycle between. |
| CMD_AUTODISABLE | 0x03 | Message contains only the command (no extra data) and stops any current auto-cycling pattern. |
| CMD_UPDATESTATUS | 0x04 | Message contains only the command (no extra data) triggers a board metadata status update to the server as well as receiving the current/updated target ID. |
### CMD_OFF
| Name | Description | Type | Bits |
| :--- | :---------- | :--- | ---: |
| Filter_1 | Value: 4039196302 | Unsigned Int | 32 |
| Filter_2 | Value: 3194769291 | Unsigned Int | 32 |
| MessageID | This is used to identify and ignore duplicate messages. Due to the unreliable nature of UDP, and the slow embedded processors, sending multiple duplicate messages some few milliseconds (10) apart can help ensure the devices get all their messages | Unsigned Int | 32 |
| CMD | Value: 0 | Unsigned Char | 8 |
| TargetID | This is the target ID mask for the broadcast message. | Unsigned Int | 32 |
### CMD_SETLEVELS
**Caution!** Any color set which includes a non-zero value for cool or warm white will have its RGB values forced to zero regardless of the provided values. RGB and Whites shall not be used simultaneously and Whites take precedence.
| Name | Description | Type | Bits |
| :--- | :---------- | :--- | ---: |
| Filter_1 | Value: 4039196302 | Unsigned Int | 32 |
| Filter_2 | Value: 3194769291 | Unsigned Int | 32 |
| MessageID | This is used to identify and ignore duplicate messages. Due to the unreliable nature of UDP, and the slow embedded processors, sending multiple duplicate messages some few milliseconds (10) apart can help ensure the devices get all their messages | Unsigned Int | 32 |
| CMD | Value: 1 | Unsigned Char | 8 |
| TargetID | This is the target ID mask for the broadcast message. | Unsigned Int | 32 |
| RampTime | This is the time in milliseconds over which the color will be changed | Unsigned Int | 32 |
| Red | This is the level for the "red" GPIO pin. Values from 0 to 255 | Unsigned Char | 8 |
| Green | This is the level for the "green" GPIO pin. Values from 0 to 255 | Unsigned Char | 8 |
| Blue | This is the level for the "blue" GPIO pin. Values from 0 to 255 | Unsigned Char | 8 |
| WarmWhite | This is the level for the "warm white" GPIO pin. Values from 0 to 255 | Unsigned Char | 8 |
| CoolWhite | This is the level for the "cool white" GPIO pin. Values from 0 to 255 | Unsigned Char | 8 |
### CMD_AUTOPATTERN
**Caution!** Any color set which includes a non-zero value for cool or warm white will have its RGB values forced to zero regardless of the provided values. RGB and Whites shall not be used simultaneously and Whites take precedence.
The CMD, RampTime and NumColors value/bits are at the head of the message. The number of color sets (R, G, B, CW, WW, RestTime) passed must be equal to NumColors.
| Name | Description | Type | Bits |
| :--- | :---------- | :--- | ---: |
| Filter_1 | Value: 4039196302 | Unsigned Int | 32 |
| Filter_2 | Value: 3194769291 | Unsigned Int | 32 |
| MessageID | This is used to identify and ignore duplicate messages. Due to the unreliable nature of UDP, and the slow embedded processors, sending multiple duplicate messages some few milliseconds (10) apart can help ensure the devices get all their messages | Unsigned Int | 32 |
| CMD | Value: 2 | Unsigned Char | 8 |
| TargetID | This is the target ID mask for the broadcast message. | Unsigned Int | 32 |
| RampTime | This is the time in milliseconds over which the color will be changed | Unsigned Int | 32 |
| NumColors | This is the number of color triplets in the message | Unsigned Char | 8 |
| Red | This is the level for the "red" GPIO pin. Values from 0.0 to 1.0 | Unsigned Char | 8 |
| Green | This is the level for the "green" GPIO pin. Values from 0.0 to 1.0 | Unsigned Char | 8 |
| Blue | This is the level for the "blue" GPIO pin. Values from 0.0 to 1.0 | Unsigned Char | 8 |
| WarmWhite | This is the level for the "warm white" GPIO pin. Values from 0 to 255 | Unsigned Char | 8 |
| CoolWhite | This is the level for the "cool white" GPIO pin. Values from 0 to 255 | Unsigned Char | 8 |
| RestTime | This is the time in milliseconds to hold on this color after ramping | Unsigned Int | 32 |
### CMD_AUTODISABLE
| Name | Description | Type | Bits |
| :--- | :---------- | :--- | ---: |
| Filter_1 | Value: 4039196302 | Unsigned Int | 32 |
| Filter_2 | Value: 3194769291 | Unsigned Int | 32 |
| MessageID | This is used to identify and ignore duplicate messages. Due to the unreliable nature of UDP, and the slow embedded processors, sending multiple duplicate messages some few milliseconds (10) apart can help ensure the devices get all their messages | Unsigned Int | 32 |
| CMD | Value: 3 | Unsigned Char | 8 |
| TargetID | This is the target ID mask for the broadcast message. | Unsigned Int | 32 |
### CMD_UPDATESTATUS
From the controller's perspective this command triggers the updateBoardStatus() function which sends board metadata to the server and receives the current/updated controller ID value.
| Name | Description | Type | Bits |
| :--- | :---------- | :--- | ---: |
| Filter_1 | Value: 4039196302 | Unsigned Int | 32 |
| Filter_2 | Value: 3194769291 | Unsigned Int | 32 |
| MessageID | This is used to identify and ignore duplicate messages. Due to the unreliable nature of UDP, and the slow embedded processors, sending multiple duplicate messages some few milliseconds (10) apart can help ensure the devices get all their messages | Unsigned Int | 32 |
| CMD | Value: 4 | Unsigned Char | 8 |
| TargetID | This is the target ID mask for the broadcast message. | Unsigned Int | 32 |