Kick Wireless Communication Protocol

Version 1.1

Terms:
Master: A controller, e.g an iPhone running the app.
Unit, Device, Slave: The Kick.
MCU: microcontroller
AP: WiFi Access Point
System: A working combination of master and slave units

The IP address of the RiftNet is 169.254.255.255, port 8080. It is the responsibility of the first live slave unit to set up an access point for the network. The first slave unit will have IP address 167.254.1.1. Any subsequent slave units will join this network and make themselves known.

Heartbeat

All slave units broadcasts a heartbeat every 8 seconds.

Data format

Any slave unit may initiate communication, but the slave initiated communication is kept to a minimum. When not transmitting, all slave units are in listening mode.
Data is sent as UDP datagrams.
The high byte is always sent first for floating point or 16/32 bit integers. All bytes are unsigned integers unless otherwise noted.
Version 1 denotes commands for the initial firmware and app version. Ver 2 and up is for future versions.

Establishing a WiFi connection

When the user presses the Connect button, the Kick sets up an ad-hoc AP called “RiftNet”. The user connects the iPhone to “RiftNet”.
The slave broadcasts a hello message every 2 seconds until queried by the master or it times out.
The master listen for slaves and queries them as necessary to indicate to the slave that a connection has been established.

Soft AP

This feature requires firmware 1.04 or newer and WiFi firmware version 4.00 or newer
Kicks shipped since May 2012 uses Soft AP instead of ad-hoc AP. The difference is that the Kick now uses dhcp, so connections to the host is much faster. With Soft AP the first Kick acts as a dhcp server for up to 7 devices.

Alternative AP

This feature requires firmware 1.04 or newer.
It is possible to store an alternative network in the Kick via the 0x94, 0x95 and 0x97 commands. If an alternative access point (AP) is stored, the Kick will scan for the AP and connect to it if found. If the alternative AP is not found, the Kick will set up or connect to “RiftNet”.
The slavet broadcasts a hello message every 2 seconds until queried by the master or it times out.
The master listen for slaves and queries them as necessary to indicate to the slave that a connection has been established.

Master to slave transfer

The format is <marker><address><length><command><data>

Marker

(2 bytes)
The marker is “RL”. This signals a transfer from the master is in progress.

Slave UID and group

(4 bytes)
The first byte indicates group. The default is 0×00. There is no grouping in ver 1.
The remaining 24 bits are the lower part of the 48 bit MAC address for the WiFi radio. These 24 bits ensures a unique ID for each device. Using a UID for the slaves alleviates the need to assign and maintain a session ID for the network communication.
0xFF000000 is the broadcast address. All slave units will respond to messages on this address.

Length

(2 bytes)
16 bit length split into high byte and low byte, indicating the total length in bytes of command and data.

Command

(1 byte)
See below for a list of master commands.

Data

(n bytes)
The format of the data bytes is determined by the command. See below.

Master commands

 

Cmd Desc Data

Ver

0×00 N/A
0×01 Set raw RGB data 3 bytes: <red>, <green> and <blue>. For each color a value between 0 and 255.This color format is device dependent and should only be used for testing purposes.

1

0×02 Set Lab color 3 bytes: <L>, <a> and <b>. For each byte a value between 0 and 255.This format is compact and device independent, but requires color domain transformation on the slave. Color domain transformation is computational intensive and may require a few milliseconds to perform.

1

0×03 Set CIEXYZ 12 bytes consisting of 3 x 32 bit (decimal32) floating point values, <X>, <Y> and <Z>.This color format is device independent and is the internal color representation of the slave.

1

0×04 Set EV Deprecated
A 32 bit value (4 bytes).Sets the exposure value.0 is full intensity. Each full Int is one stop down. Eg. 3 is three stops down. 1.5 is one and a half stop down.This is a int-converted float (ev * 100 000). So 2.8 stops down from full intensity is sent as 280 000. 1.5 stops is sent as 150 000.Any values beyond the lowest value the device can emit is interpreted as off. The Kick has a 5 stop range, so any value larger than 500000 will turn off the light.

1

0×05 Set CCT A 16 bit value (2 bytes).Sets the color temperature in Kelvin. Typical values are between 2500 and 10000.

1

0×06 Set EV2 Prefer in place of 0×04 Set EV. An 8 bit value. Brightness from full (255) to off (0) on a linear scale(127 is half power, 63 is quarter power etc.).

1

0×07 Set CHROMA 8 bytes consisting of 8 x 32 bit (decimal32) floating point values, <x>, <y>. The color space is CIE xyY. Only the x,y color coordinates are sent.This color format is device independent.

1

0×08 Set PR 1 byte. Adjust the clock speed of the PWM engine. Use any value between 1 and 50. Default is 25. Low values improves flicker but affects color linearity.Refresh = 25000/PR+1. Examples: PR 49 = 500Hz, PR 24 = 1kHz, 4 = 5kHz.

2

0×09 Set Refresh Rate A 16 bit value (2 bytes).  Set the refresh rate of the PWM engine directly in Hz. Minimum value is 10Hz, maximum value is 5000Hz.Not every single frequency can be generated. The PWM engine will use the closest match.

2

0x0A Select Alternate Button Function 1 byte.
A value of 0 (zero) is default.
0 = Default(Brightness buttons control brightness, CCT buttons controls color temperature)
1 = Refresh Rate (Brightness buttons control brightness, CCT buttons controls refresh rate)
2 = Demo Mode (Each button triggers a different light effect)
4 = WB + Color. The WB[+] and WB[-] buttons will cycle through both Color temperature presets and the color circle.This value is currently not stored across sessions. Each time the device is turned on, the alternate button functions reverts to default.
0×0B Flash 3 16 bit values (6 bytes):  Duration in ms (2 bytes), CCT in Kelvin (2 bytes), Power (2 bytes)

1

0×0C RAW Three 8bit values (3 bytes): <red>, <green> and <blue>. For each color a value between 0 and 255. This command offers direct unfiltered control over the emitters. Do not run all emitters at full power. Utilization over 70% may cause a temperature cutoff.

1

0×0D Set RGB (Color Managed) Four 8bit values (4 bytes):  The first byte is the working space
0 = RGB (no working space)
1 = sRGB (Reference White D65)
2 = AdobeRGB 1998 (Reference White D65)
3 = ProPhoto RGB (Reference White D50)
The next three bytes are the RGB values: <red>, <green> and <blue>. For each color a value between 0 and 255.

1

0×0E Reserved Reserved for future use

1

0×0F Reserved Reserved for future use

1

0×10 Run preset effect Starts a preset light effect. The bytes to follow are the settings for the particular effect:

Strobe. 10 bytes:
0×01
<Effect UID> (one byte)
<cycle length in ms> (16bit, two bytes)
<duration in ms> (16bit, two bytes)
<LCH(uv) Lightness> (one byte, 50-100)
<LCH(uv) Hue> (16bit, two bytes, 0-360)
<loop> (one byte, the number of loops, 0×00 is loop forever)

Rainbow. 10 bytes:
0×02
<Effect UID> (one byte)
<LCH(uv) Lightness start> (one byte, 50-100)
<LCH(uv) Hue start> (16bit, two bytes, 0-360)
<LCH(uv) Lightness end> (one byte, 50-100)
<LCH(uv) Hue end> (16bit, two bytes, 0-360)
<direction> (one byte)
<cycle length in ms> (16bit, two bytes)
<loop> (one byte, the number of loops, 0×00 is loop forever)

Boom. 9 bytes:
0×03
<Effect UID> (one byte)
<cycle length in ms> (16bit, two bytes)
<duration in ms> (16bit, two bytes)
<LCH(uv) Lightness> (one byte, 50-100)
<LCH(uv) Hue> (16bit, two bytes, 0-360)
<loop> (one byte, the number of loops, 0×00 is loop forever)

LightningStorm. 2 bytes:
0×04
<Effect UID> (one byte)
<intensity> (one byte, 0-255)

Sine. 9 bytes:
0×05
<Effect UID> (one byte)
<cycle length in ms5 (16bit, two bytes)
<min amplitude> (one byte, 0-255)
<max amplitude> (one byte, 0-255)
<LCH(uv) Lightness> (one byte, 50-100)
<LCH(uv) Hue> (16bit, two bytes, 0-360)
<loop> (one byte, the number of loops, 0×00 is loop forever)

Fire. 3 bytes:
0×06
<Effect UID> (one byte)
<wind> (one byte, 0-255)
<size> (one byte, 0-255)

TwoColorSine. 12 bytes:
0×07
<Effect UID> (one byte)
<cycle length in ms> (16bit, two bytes)
<min amplitude> (one byte, 0-255)
<max amplitude> (one byte, 0-255)
<LCH(uv) Lightness 1> (one byte, 50-100)
<LCH(uv) Hue 1> (16bit, two bytes, 0-360)
<LCH(uv) Lightness 2> (one byte, 50-100)
<LCH(uv) Hue 2> (16bit, two bytes, 0-360)
<loop> (one byte, the number of loops, 0×00 is loop forever)

Disco. 10 bytes:
0×08
<Effect UID> (one byte)
<LCH(uv) Lightness start> (one byte, 50-100)
<LCH(uv) Hue start> (16bit, two bytes, 0-360)
<LCH(uv) Lightness end> (one byte, 50-100)
<LCH(uv) Hue end> (16bit, two bytes, 0-360)
<step> (one byte, 1-10)
<direction> (one byte)
<loop> (one byte, the number of loops, 0×00 is loop forever)

1

0×11 Stop effect Effect UID (8bit, one byte) Stop a light effect.

1

0×12 Load effect Effect UID (16bit, two bytes) plus dataThis will typically transmit a relatively large amount of data describing a light effect. The slave will store the effect for future execution. Probably requires an ACK from the slave.Data format TBD.

2

0×80 Hello Typically broadcast when the master does not have any slaves registered. No data is sent with this command.Slaves will respond with their UID.

1

0×81 Query slave name Ask for the user name and ID color of the slave unit. After receiving this command, the slave will wait 1 ms before sending back data. No data is sent with this command.

1

0×82 Set slave name Assign a user defined name and a ID color to the slave.The first 3 bytes are RGB values for the ID color <red>, <green> and <blue>, followed by the user defined name (16 ascii characters).The slave unit will store its assigned user name and ID color in non-volatile memory.The slave is the primary storage for names and IDs. The master acts as a cache, and til update itself if the data in the slave changes.Do not send less than 16 ascii characters for the name. Pad with NUL (0×00) if name is shorter.

1

0×83 Query slave status Ask for status from the slave. After receiving this command, the slave will wait 1 ms before sending back data. No data is sent with this command.See slave command 0×83 for return values.

1

0×84 Set clock The master can use either network time or is own RTC for synchronizing. If there is no network time available the master can set the slave Real Time Clock with this command.Data format TBD

2

0×85 Query custom effects Ask the slave to list custom effects and the remaining space in non-volatile storage. After receiving this command, the slave will wait 1 ms before sending back data. No data is sent with this command.

2

0×86 Signal 2 bytes (16bit) duration in ms. Upon receiving this command, the slave will emit a full power (EV=0) light pulse for <duration> milliseconds. The color of the light will be the user defined ID color for the slave unit.

1

0×87 Query version Ask for the hardware version, firmware version and serial number of the slave. After receiving this command, the slave will wait 1 ms before sending back data. No data is sent with this command.

1

0×88 Master disconnect Indicates to the slave that the master is disconnecting and the slave should change mode to standalone. No data is sent with this command.

1

0×91 Query slave summary Ask for EV2, Chroma, ID color, firmware version, hardware version, and user name of the slave unit. After receiving this command, the slave will wait 1 ms before sending back data. No data is sent with this command.

1

0×92 Query session debug info Ask for debug info. No data is sent with this command.

1

Firmware data TBC

2

0x94 Set alternative AP SSID Set the SSID for the alternative AP. A string of max 31 ASCII characters.

1

0x95 Set alternative AP password Set the password for the alternative AP. Max 64 characters.

1

0x96 Query alternative SSID After receiving this command, the slave will wait 1 ms before sending back data. Slave will return the stored alternative net SSID, max 32 characters (31 characters plus terminating null).

1

0x97 Set alternative AP authentication 1 byte. Sets the authentication method for the alternative network AP.
0 = none
1 = WEP
2 = WPA

1

0×98 Sleep Ask the device to enter sleep mode. No data is sent with this command.

1

0×99 Query capabilities Ask the device about its capabilities. After receiving this command, the slave will wait 1 ms before sending back data. No data is sent with this command.

1

0×FF Not allowed (internal use)

 

Slave to master transfer

The format is <marker><address><length><command><data>
The first 7 bytes is the header, the rest is command and data.

Marker

(2 bytes)
The marker is “R$”. This signals a transfer from a slave unit is in progress.

Address

(3 bytes)
The 3 low octets of the slave MAC address. Identifies the slave unit to the master.

Length

(2 bytes)
16 bit length split into high byte and low byte, indicating the length in bytes of command and data. (The length does not include the size of the header)

Command

(1 byte)
See below for a list of slave commands

Data

(n bytes)
The format of the data bytes is determined by the command. See below.

Slave commands

 

 

Cmd Desc Data

Ver

0×00 ACK 1 byte CRC-8.Sent after those commands from the master that expects an ACK. The data is an 8-bit CRC value for the entire received message including marker.If the CRC does not match, the master can decide to resend the command.Note: currently just returns True (0×01)

?

0×01 Hello Sent when the slave wants to attach to the master. No data is sent with this command.
0×04 Set EV A 32 bit value (4 bytes).Sent from the slave when the exposure value has been changed on the slave (using the adjustment buttons).0 is full intensity. Each full Int is one stop down. Eg. 3 is three stops down. 1.5 is one and a half stop down.This is a int-converted float (ev * 100 000). So 2.8 stops down from full intensity is sent as 280 000. 1.5 stops is sent as 150 000.Any values beyond the lowest value the device can emit is interpreted as off. The Kick has a 5 stop range, so any value larger than 500000 will turn off the light.

1

0×05 Set CCT A 16 bit value (2 bytes).Sent from the slave when the kelvin value has been changed on the slave (using the adjustment buttons).Typical values are between 2500 and 10000.

1

0×06 Set EV2 Relative scale, use instead of 0×04 Set EV.An 8 bit value (1 byte).Brightness from full (255) to off (0) on a linear scale(128 is half power, 64 is quarter power etc.).

1

0×07 Set CHROMA 8 bytes consisting of two floating point values, <x> and <y>.The color space is CIE xyY. Only the x,y color coordinates are sent.This color format is device independent.

1

0×81 Slave name The first 3 bytes are RGB values for the color ID <red>, <green> and <blue>, followed by the user defined name (n ascii characters).The slave stores its assigned user name and ID color in non-volatile memory.

1

0×82 N/A
0×83 Slave status 1 byte emitter temperature in Celsius. This byte is a signed integer.1 byte battery level. 0 to 255 where 0 is empty, 254 is full and 255 is charging.4 bytes current EV value (one 32 bit value)12 bytes current CIEXYZ color value (3 floating point values)

1

0×84 Clock TBD

2

0×85 Custom effects TBD

2

0×84 N/A
0×87 Slave Version 2 bytes major and minor firmware version
2 bytes major and minor hardware version
16 bytes serial number (display as hex in 4 groups)

1

0×88 Slave disconnect Indicates to the master that the slave is disconnecting. No data is sent with this command.

1

0×89 Temperature alert Sent when temperature changes. 1 byte emitter temperature in Celsius. This byte is a signed integer.

1

0×90 Battery alert Sent when battery charge level changes. 1 byte, 0 to 255 where 0 is empty, 254 is full and 255 is charging. A value of 51 of less is low battery
0×91 Slave summary Slave sends:
EV2 (1 byte), see cmd 0×06
Chroma, (8 bytes), see cmd 0×07
ID color (3 bytes), see cmd 0×81
Firmware version (two bytes), see cmd 0×87
Hardware version (2 bytes), see cmd 0×87
User Name (0 to 16 bytes), see cmd 0×81
0×92 Session debug info A 32 bit value (4 bytes).Details TBC
0×98 Sleep A single byte. Sent when the device enters or leaves low power standby.
1 = Device is sleeping (power save mode)
0 = Normal operation
0×99 Slave Capabilities The slave sends 12 bytes:
2 bytes Minimum CCT in Kelvin
2 bytes Maximum CCT in Kelvin
1 Byte Color support (1 = TRUE)
1 Byte Light modes (1=flash, 2=continuous, 3=flash+continuous)
6 bytes reserved to future use
Firmware data TBC
0×FF Not allowed (internal use)

 

Example:

The master sends the 0×87 version command.

After a delay of 1 ms, the slave respond with this message:

byte

value

comment

0

0×52

“R”

1

0×24

“$”

2

0×72

First (highest) of the three low octets of the MAC address

3

0x3e

Second low octet of MAC address

4

0×22

Third low octet of MAC address. The device UID is 723E22 (0x00723E22)

5

0×00

Data length HIGH byte

6

0×15

Data length LOW byte. The size of the data + command is 0×0015 = 21 bytes

7

0×87

Command

8

0×00

Software major version

9

0×09

Software minor version. In this case the sw version is 0.9

10

0×01

Hardware major version

11

0×02

Hardware major version. I this case the hw version is 1.2

12

0×12

First byte of serial number

13

0×12

Second byte of serial number

14

0×10

etc…

15

0×08

16

0×53

17

0x4d

18

0x1f

19

0x7f

20

0x4e

21

0xdb

22

0xe4

23

0×71

24

0xf5

25

0×00

26

0×00

27

0×02

(in this case serial num is: 12121008-534D1F7F-4EDBE471-F5000002)

 

Commands from slave to master

The slave independently sends commands to the master in these cases:

Event: Command: Comment
User change Brightness 0×06  SetEV2 (previously 0×04  Set EV)
User change Color Temp 0×05 Set CCT
Battery level changes 0×90 Battery alert
Temperature level changes 0×89 Temperature alert
User connects 0×01  Hello Keeps sending every 2 seconds until master responds
Sleep 0×98  Sleep state Sent when slave enters or leaves low power state

The slave replies to these commands from the master

Command: Response: Comment
0×01  Hello 0×81  Slave Name
0×81  Query Slave Name 0×81  Slave Name
0×83  Query Slave Status 0×83  Slave Status
0×87  Query Slave Version 0×87  Slave Version
0×91  Query Slave Summary 0×91  Slave Summary
0×98  Sleep 0×98  Sleep state
0×99  Query Slave Capabilities 0×99  Slave Capabilities

 

There is no response from the slave for other commands from master like setting brightness, color, or starting and stopping effects

*** END ***