|====================================| | ArtUDP Protocol Version 2.02 | | Written by: Michel van Osenbruggen | | CopyRight 2024 ArtiLED B.V. | |====================================| Minimum Slave Firmware version : 0.122 beta Latest change : 23-01-2024 ======================= | Protocol Definition | ======================= Protocol : UDP unicast or broadcast Port : 1093 |========================| | TCP Protocol Structure | |========================| Start byte : Always 0x7e Command byte : See command structure Status byte : See status structure Channel byte : 0 for all 1-4 for individual led strips MSB Amount byte : MSB Number of bytes to follow LSB Amount byte : LSB Number of bytes to follow Data byte(s) : 0 or Multiples bytes as defined before Stop byte : Always 0x7e |=================== | Status Structure | |=================== RealTime (bit 1) : Realtime Mode 0=Off, 1=On (with Realtime on no answer is returned) Commit (bit 2) : Commit Mode 0=Off, 1=On (with no commit led actions are not shown until commit is given) |============================| | Protocol Answer Formatting | |============================| -1 = TimeOut : No Answer -> Check Realtime Mode 0 = Error : Error is just 0 -> See debug for Error 1 = Success : Success is just 1 |=============| | Definitions | |=============| Strip : Whole led strip -> All leds (Number of leds) Multi Strip : Multiple led strips with channel -> All leds Segment : Part of a led strip -> Start, End -> Start and End are two bytes (msb, lsb) Multi Segment : Multiple Parts of a led strip -> Array of n x (Start, End) -> Start and End are two bytes (msb, lsb) Multi Channel Segment : Multiple Parts of multiple led strip with channel -> Array of n x (Channel, Start, End) -> Start and End are two bytes (msb, lsb) Pixel : Single pixel of a led strip -> Pixel number -> Pixel numbers are two bytes (msb, lsb) Multi Pixel : Multiple pixels of a led strip -> Array of Pixel Numbers -> Pixel numbers are two bytes (msb, lsb) Multi Channel Pixel : Multiple pixels of multiple led strip with channels -> Array of channel and Pixel Numbers -> Pixel numbers are two bytes (msb, lsb) Pixel String : Multiple pixels of a led strip with a start (msb, lsb) then followed by an Array of Pixel Numbers (msb, lsb) Palette : Collection of Colors -> Max 16 colors Msb : Most Significant Byte (0x01,0x00) 0x01 = 256 Lsb : Least Significant Byte (0x00, 0x01) 0x01 = 1 |===================| | Command Structure | |===================| 0x?? : Command *0x?? : Sub Commands, Values, Effects, Palettes etc. |================| | Data Structure | |================| Channel : Byte 0x00-0x04, 0x00=All Channels, > 0x04 Channel Combinations (see List) Data : Byte 0x00-0xff (0-255) or No Data |==================== | Channel Structure | ===================== 0x00 : 0 = All Channels 0x01 : 1 = Channel 1 0x02 : 2 = Channel 2 0x03 : 3 = Channel 3 0x04 : 4 = Channel 4 0x0c : 12 = Channel 1 + 2 0x0d : 13 = Channel 1 + 3 0x0e : 14 = Channel 1 + 4 0x17 : 23 = Channel 2 + 3 0x18 : 24 = Channel 2 + 4 0x22 : 34 = Channel 3 + 4 0x7b : 123 = Channel 1 + 2 + 3 0x7c : 124 = Channel 1 + 2 + 4 0x86 : 134 = Channel 1 + 3 + 4 0xea : 234 = Channel 2 + 3 + 4 |===================| | Command Structure | |===================| 0x00 Command : Command + Data * Sub Command : Sub Command, Values, Effects, Palettes etc. ! Future Command : Command not done yet, coming soon ----------------------------------- | Led Controller Control commands | ----------------------------------- 0x10 Clear : No Data, Realtime,Commit,Channel -> Clear all leds on channel (Set to black) (0=All channels) 0x11 Brightness : Data 1 byte, Realtime,Commit -> Sets Global brightness for Dimming Leds -> Always All channels 0x12 Saturation : Data 1 byte, Realtime,Channel -> Sets Global Saturation (if only Hue) (Channel has no function yet -> Always All channels) 0x13 Hue : Data 1 byte, Realtime,Channel -> Sets Global Hue (if only Sat) (Channel has no function yet -> Always All channels) 0x14 Value : Data 1 byte, Realtime,Channel -> Sets Global Value (if only Hue or Sat) (Channel has no function yet -> Always All channels) 0x15 Brighten : Data 1 byte, Realtime,Commit -> Reads current Global Brightness and adds value (0-255) 0x16 Dim : Data 1 byte, Realtime,Commit -> Reads current Global Brightness and subtracts value (0-255) 0x17 Scale : Data 1 byte, Realtime,Commit,Channel -> Reads led values and scales them with value (0-255) Percent 0x18 Calc : Data 2 bytes, Realtime,Commit,Channel -> Reads led values and does calculations. Option (0x00=Add, 0x01=Subtract, 0x02=Multiply, 0x03=Divide), value (0-255) 0x19 Save : No Data, Realtime,Channel -> Saves current led values for Channel in memory array for restore. (RAM, lost when power down) 0x1a Restore : No Data, Realtime,Commit,Channel -> Restores saved led values from memory array for restore. (RAM, lost when power down) 0x1b Default : No Data, Realtime,Commit,Channel -> Sets leds to default color and brightness for channel based on Default Startup Mode (0xfd) 0x1e Commit : No Data, Realtime -> Commits non commmited Led Actions 0x1f Set Power : Data 1 byte, Realtime -> Set PSU Power -> 0x00=Power PSU Off, 0x01=Power PSU On ------------------------ | Strip Color Commands | ------------------------ 0x30 Strip RGBW : Data 4 bytes, Realtime,Commit,Channel -> Colors whole strip (Red, Green, Blue, White) 0x31 Strip RGB : Data 3 bytes, Realtime,Commit,Channel -> Colors whole strip (Red, Green, Blue) 0x32 Strip HSV : Data 3 bytes, Realtime,Commit,Channel -> Colors whole strip (Hue, Sat, Brightness) 0x35 Strip W : Data 2 bytes, Realtime,Commit,Channel -> Colors whole Strip (Temperature, Intensity) 0=Cold, 127=Normal,255=Warm ------------------------------ | Multi Strip Color Commands | ------------------------------ 0x33 Multi Strip RGBW : Data n x 5 bytes, Realtime,Commit,Channel -> Colors Multiple Strips (n x (Channel, Red, Green, Blue, White) ) 0x34 Multi Strip RGB : Data n x 4 bytes, Realtime,Commit,Channel -> Colors Multiple Strips (n x (Channel, Red, Green, Blue) ) 0x43 Multi Strip HSV : Data n x 4 bytes, Realtime,Commit,Channel -> Colors Multiple Strips (n x (Channel, Hue, Sat, Value) ) 0x44 Multi Strip W : Data n x 3 bytes, Realtime,Commit,Channel -> Colors Multiple Strips (n x (Channel, Temperature, Intensity)) 0=Cold, 127=Normal,255=Warm ------------------------- | Strip Modify Commands | ------------------------- 0x36 Strip Scale RGBW : Data 4 bytes, Realtime,Commit,Channel -> Reads led values and scales them 0-255 Percent (Red, Green, Blue, White) 0x37 Strip Calc RGBW : Data 5 bytes, Realtime,Commit,Channel -> Reads led values and does calculations. (Option, Red, Green, Blue, White) -> 0x00 add, 0x01 subtract, 0x02 multiply, 0x03 divide 0x38 Strip Shift : Data 3 bytes, Realtime,Commit,Channel -> Reads led values and shift them (Step, Mode, Option) -> Mode 0x00=Left, 0x01=Right, 0x02=Outward, 0x03=Inward -> Option 0x00=Insert Blank, 0x01=Recycle 0x39 Strip Copy : Data 1 byte, Realtime,Commit,Channel -> Reads leds values for Channel (Origin) and copies them to Channel (Channel 0 copies to all Channels) 0x3a Strip Swap : Data 1 byte, Realtime,Commit,Channel -> Reads led values for Channel (Origin) with Channel (Channel 0 doesn't work) 0x3b Strip Rotate : Data 1 byte, Realtime,Commit -> Reads led values and Rotates Strips in Direction (0x00=Right, 0x01=Left) 0x3c Strip Feed RGBW : Data 6 bytes, Realtime,Commit,Channel -> Insert Led Value (R,G,B,W) and Shift (Step, Mode) -> Mode 0x00=Left, 0x01=Right, 0x02=Outward, 0x03=Inward) 0x3d Strip Feed HSV : Data 5 bytes, Realtime,Commit,Channel -> Insert Led Value (H,S,V) and Shift (Step, Mode) -> Mode 0x00=Left, 0x01=Right, 0x02=Outward, 0x03=Inward) 0x3e Strip Feed Palette : Data 3 bytes, Realtime,Commit,Channel -> Insert Color from Palette and Shift (Index, Step, Mode) -> Mode 0x00=Left, 0x01=Right, 0x02=Outward, 0x03=Inward) 0x3f Strip Blur : Data 2 bytes, Realtime,Commit,Channel -> Blurs Leds (Count, Amount) -> Count=Number of Blurs (0-255), Blur Amount 0=No Spread, 64=Moderate Spread, 172=Max Smooth, 173-255=Wider Spreading -------------------------- | Segment Color Commands | -------------------------- 0x40 Segment RGBW : Data 8 bytes, Realtime,Commit,Channel -> Colors Segment (start_msb, start_lsb, end_msb, end_lsb, Red, Green, Blue, White) 0x41 Segment RGB : Data 7 bytes, Realtime,Commit,Channel -> Colors Segment (start_msb, start_lsb, end_msb, end_lsb, Red, Green, Blue) 0x42 Segment HSV : Data 7 bytes, Realtime,Commit,Channel -> Colors Segment (start_msb, start_lsb, end_msb, end_lsb, Hue, Sat, Brightness) 0x45 Segment W : Data 6 bytes, Realtime,Commit,Channel -> Colors Segment (start_msb, start_lsb, end_msb, end_lsb, Temperature, Intensity) 0=Cold, 127=Normal, 255=Warm --------------------------- | Segment Modify Commands | --------------------------- 0x4f Segment Blur : Data 6 bytes, Realtime,Commit,Channel -> Blurs Leds (start_mdb, start_lsb, end_msb, end_lsb, Count, Amount) -> Count=Number of Blurs (0-255), Blur Amount 0=No Spread, 64=Moderate Spread, 172=Max Smooth, 173…255=Wider Spreading -------------------------------- | Multi Segment Color Commands | -------------------------------- 0x50 Multi Segment RGBW : Data n x 8 bytes, Realtime,Commit,Channel -> Colors Segment (n x (start_msb, start_lsb, end_msb, end_lsb, Red, Green, Blue, White) ) 0x51 Multi Segment RGB : Data n x 7 bytes, Realtime,Commit,Channel -> Colors Segment (n x (start_msb, start_lsb, end_msb, end_lsb, Red, Green, Blue) ) 0x52 Multi Segment HSV : Data n x 7 bytes, Realtime,Commit,Channel -> Colors Segment (n x (start_msb, start_lsb, end_msb, end_lsb, Hue, Sat, Brightness) ) 0x55 Multi Segment W : Data n x 6 bytes, Realtime,Commit,Channel -> Colors Segment (n x (start_msb, start_lsb, end_msb, end_lsb, Temperature, Intensity) ) 0=Cold, 127=Normal, 255=Warm ---------------------------------------- | Multi Channel Segment Color Commands | ---------------------------------------- 0x53 Multi Channel Segment RGBW : Data n x 9 bytes, Realtime,Commit,Channel -> Colors Segment (n x (channel, start_msb, start_lsb, end_msb, end_lsb, Red, Green, Blue, White) ) 0x54 Multi Channel Segment RGB : Data n x 8 bytes, Realtime,Commit,Channel -> Colors Segment (n x (channel, start_msb, start_lsb, end_msb, end_lsb, Red, Green, Blue) ) 0x63 Multi Channel Segment HSV : Data n x 8 bytes, Realtime,Commit,Channel -> Colors Segment (n x (channel, start_msb, start_lsb, end_msb, end_lsb, Hue, Sat, Brightness) ) 0x64 Multi Channel Segment W : Data n x 7 bytes, Realtime,Commit,Channel -> Colors Segment (n x (channel, start_msb, start_lsb, end_msb, end_lsb, Temperature, Intensity) ) 0=Cold, 127=Normal, 255=Warm ------------------------ | Pixel Color Commands | ------------------------ 0x60 Pixel RGBW : Data 6 bytes, Realtime,Commit,Channel -> Colors Pixels (Pixel_msb, Pixel_lsb, Red, Green, Blue, White) 0x61 Pixel RGB : Data 5 bytes, Realtime,Commit,Channel -> Colors Pixels (Pixel_msb, Pixel_lsb, Red, Green, Blue) 0x62 Pixel HSV : Data 5 bytes, Realtime,Commit,Channel -> Colors Pixels (Pixel_msb, Pixel_lsb, Hue, Sat, Brightness) 0x65 Pixel W : Data 4 bytes, Realtime,Commit,Channel -> Colors Pixels (Pixel_msb, Pixel_lsb, Temperature, Intensity) 0=Cold, 127=Normal, 255=Warm ------------------------------ | Multi Pixel Color Commands | ------------------------------ 0x70 Multi Pixel RGBW : Data n x 6 bytes, Realtime,Commit,Channel -> Colors Pixels (n x (Pixel_msb, Pixel_lsb, Red, Green, Blue, White) ) 0x71 Multi Pixel RGB : Data n x 5 bytes, Realtime,Commit,Channel -> Colors Pixels (n x (Pixel_msb, Pixel_lsb, Red, Green, Blue) ) 0x72 Multi Pixel HSV : Data n x 5 bytes, Realtime,Commit,Channel -> Colors Pixels (n x (Pixel_msb, Pixel_lsb, Hue, Sat, Brightness) ) 0x75 Multi Pixel W : Data n x 4 bytes, Realtime,Commit,Channel -> Colors Pixels (n x (Pixel_msb, Pixel_lsb, Temperature, Intensity) ) 0=Cold, 127=Normal, 255=Warm !0x7e Reserved! Don't use : Same as Start and Stop Byte. Not in use to avoid problems -------------------------------------- | Multi Channel Pixel Color Commands | -------------------------------------- 0x73 Multi Channel Pixel RGBW : Data n x 7 bytes, Realtime,Commit,Channel -> Colors Pixels (n x (Channel, Pixel_msb, Pixel_lsb, Red, Green, Blue, White) ) 0x74 Multi Channel Pixel RGB : Data n x 6 bytes, Realtime,Commit,Channel -> Colors Pixels (n x (Channel, Pixel_msb, Pixel_lsb, Red, Green, Blue) ) 0x83 Multi Channel Pixel HSV : Data n x 6 bytes, Realtime,Commit,Channel -> Colors Pixels (n x (Channel, Pixel_msb, Pixel_lsb, Hue, Sat, Brightness) ) 0x84 Multi Channnel Pixel W : Data n x 5 bytes, Realtime,Commit,Channel -> Colors Pixels (n x (Channel, Pixel_msb, Pixel_lsb, Temperature, Intensity) ) 0=Cold, 127=Normal, 255=Warm ------------------------------- | Pixel String Color Commands | ------------------------------- 0x80 Pixel String RGBW : Data start_msb, start_lsb, n x 4 bytes, Realtime,Commit,Channel -> Colors Pixels Start, (n x ( Red, Green, Blue, White) ) 0x81 Pixel String RGB : Data start_msb, start_lsb, n x 3 bytes, Realtime,Commit,Channel -> Colors Pixels Start, (n x ( Red, Green, Blue) ) 0x82 Pixel String HSV : Data start_msb, start_lsb, n x 3 bytes, Realtime,Commit,Channel -> Colors Pixels Start, (n x ( Hue, Sat, Brightness) ) 0x85 Pixel String W : Data start_msb, start_lsb, n x 2 bytes, Realtime,Commit,Channel -> Colors Pixels Start, (n x ( Temperature, Intensity) ) 0=Cold, 127=Normal, 255=Warm --------------------- | Palette commands | --------------------- 0xb0 Get Palette : No Data -> Returns Palette (see ArtiPALETTE.txt) 255=Custom Palette 0xb1 Set Palette : Data 1 byte, Realtime -> Sets Palette (see ArtiPALETTE.txt) Always all channels! 0xb2 Set Simple Custom Palette : Data 6 bytes, Realtime -> Set Custom Palette with 2 Colors 2 x (R,G,B) on Default Position 0 and 255 0xb3 Set Advanced Custom Palette : Data n x 4 bytes, Realtime -> Set Custom Palette with (2-16) Colors n x (Position,R,G,B) 0xb4 Set Target Palette : Data 1 byte, Realtime -> Sets Target Palette for Blending (see ArtiPALETTE.txt) Always all channels! 0xb5 Set Simple Target Palette : Data 6 bytes, Realtime -> Set Custom Target Palette for Blending with 2 Colors 2 x (R,G,B) on Default Position 0 and 255 0xb6 Set Advanced Target Palette : Data n x 4 bytes, Realtime -> Set Custom Target Palette for Blending with (2-16) Colors n x (Position,R,G,B) 0xb7 Strip Palette : Data 5 bytes, Realtime,Commit,Channel -> Colors whole strip with Palette (Blend, Scale, Alternate, Start Index, End Index) -> 0x00 = No Blend 0x01 = Circular Blend 0x02 = Linear Blend, 0x00=No Scale or (1-255), 0x00=No Alternate 0x01 = Alternate 0xb8 Strip Part Palette : Data 9 bytes, Realtime,Commit,Channel -> Colors Part of strip with Palette Preserving Strip Scale (start_msb, start_lsb, end_msb, end_lsb, Blend, Scale, Alternate, Start Index, End Index) -> 0x00 = No Blend 0x01 = Circular Blend 0x02=Linear Blend 0x00=No Scale or (1-255), 0x00=No Alternate 0x01 = Alternate 0xb9 Segment Palette : Data 9 bytes, Realtime,Commit,Channel -> Colors Segment of Strip with Palette with own Scale (start_msb, start_lsb, end_msb, end_lsb, Blend, Scale, Alternate, Start Index, End Index) -> 0x00 = No Blend 0x01 = Circular Blend 0x02 = Linear Blend, 0x00=No Scale or (1-255), 0x00=No Alternate 0x01 = Alternate 0xba Multi Channel Strip Part Palette : Data n x 11 bytes, Realtime,Commit,Channel -> Colors Multiple Parts of Strip with own Strip Scale (n x (channel, start_msb, start_lsb, end_msb, end_lsb, Clear, Blend, Scale, Alternate, Start Index, End Index) ) -> 0x00 = No Blend 0x01 = Circular Blend 0x02=Linear Blend 0x00=No Scale or (1-255), 0x00=No Alternate 0x01 = Alternate 0xbb Multi Channel Segment Palette : Data n x 11 bytes, Realtime,Commit,Channel -> Colors Multiple Parts of Strip preserving Strip Scale (n x (channel, start_msb, start_lsb, end_msb, end_lsb, Clear, Blend, Scale, Alternate, Start Index, End Index) ) -> 0x00 = No Blend 0x01 = Circular Blend 0x02=Linear Blend 0x00=No Scale or (1-255), 0x00=No Alternate 0x01 = Alternate 0xbf Blend Palette : Data 3 byte, Realtime -> Blends from Current Pallette to Target Pallete (Speed, Steps, Delay) Speed->0x00=No Blend,0x01=Very Slow, 0x40=Fast, Steps (0x00-0xff), Delay ms (0x00-0xff) ----------------------------------------------------------------------------------------------------------------- | Led Controller Additional Commands (Default Color Correct Values and RGB order will be saved in Flash memory) | ----------------------------------------------------------------------------------------------------------------- 0xc0 On : No Data -> Turns PSU On and all channels On depending on Startup Mode it will go to Default or Saved State 0xc1 Off : No Data -> Turns Leds Off and PSU off 0xc2 Sleep : No Data -> Activates Power Save immediately depending on Power Save Mode 0xc3 Awake : No Data -> Awaken if Asleep or Keep Awake. Turns Power Saver off or Resets Power Saver Timer. (After Power Save Leds will remain off. Use 'On' or 'Restore' to turn leds on).