LEDController

This project should load onto just about any ESP8266 or ESP32 based microcontroller or dev board. It has been tested on the Adafruit ESP8266 Huzzah, the NodeMCUv2/v3 development boards, and the ESP32 (using APIv3).

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: 0x00	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: 0x01	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: 0x02	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: 0x03	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: 0x04	Unsigned Char	8
TargetID	This is the target ID mask for the broadcast message.	Unsigned Int	32