1 SERIAL PROTOCOL FOR FNORDLICHT-NG FIRMWARE
2 ==========================================
4 Physical bus description
5 ------------------------
7 The serial bus consists of up to 254 devices, each device having the uart rx
8 pin connected to the uart tx pin of the predecessor, the uart tx pin connected
9 to the tx successor. The uart is used with a baud rate of 19200. A device
10 will retransmit each received byte immediately and unaltered, the only
11 exception is the address byte in the sync sequence (which is incremented by one
12 before retransmission). An interrupt line is connected to each device.
16 +----------------+ +----------------+
17 | device N | | device N+1 |
18 UART: ... --> >-|RX TX|-> --> >-|RX TX|-> ...
20 +-------+--------+ +-------+--------+
22 INT: -------------------+--------------------------+----------> ...
25 Bootloader startup procedure
26 ----------------------------
28 For updating the firmware installed on the devices of a bus, each device should
29 be equipped with a bootloader program. At power-on, the bootloader should be
30 started, sleep for 100ms and check afterwards, if the INT line is pulled down
31 (by a bus-master). If INT is not pulled down, the bootloader is allowed to
32 start the main firmware. Otherwise it should not attempt to start the main
33 firmware, but wait for commands received over the bus. This procedure allows a
34 recovery from a broken firmware which does not process commands received over
35 the bus (such as the BOOTLOADER command). To enter the bootloader via the
36 BOOTLOADER command, first pull down the INT line, then issue the command.
41 For the purpose of (automatic) address discovery and resetting the bus, a
42 sync sequence consisting of 15x ESC (0x1b) followed by an address byte is used.
43 The controller sends 15x ESC, followed by a null byte. Please note that the
44 length of the sync sequence (16 byte) is different from the length of a
45 command packet, which is 15 byte!
47 A device MUST be able to detect this sequence asynchronously, i.e. even if it is
48 in the middle of receiving a command packet. The device does not need to
49 withhold the execution of the received command packet until it is clear if a
50 sequence of ESC bytes constitutes a sync sequence.
53 A device received 4 bytes, say A B C D, of a packet, then a sync sequence.
54 It may (or may not) execute the packet
56 A B C D ESC ESC ... ESC
58 but the sync sequence must be detected, too.
60 Asynchronous detection of the sync sequence can be done by just counting the
61 number of consecutive ESC bytes, as 15 consecutive ESC bytes can only occur
62 in a sync sequence, never in a command packet (ESC cannot occur as a command in
63 the second byte of a command packet).
66 * controller sends 15x ESC, followed by the address of the first device
68 * first device on the bus receives and retransmits 15x ESC, receives address
69 byte, stores own address in ram, increments address byte and transmits new
70 address to next device on the bus
72 Result: Each device on the bus knows it's own address (=position).
78 Commands are sent in packets, 15 bytes in length, and are passed from device
79 to device unmodified. The first byte is the destination address (0-254, 255
80 is broadcast), the second byte contains the command. The meaning of the
81 following 13 bytes depends on the value of the second byte (command). A
82 device ignores non-broadcast packets for which the address byte does not
83 match it's own address. Bytes which are declared as "don't care" bytes SHOULD
84 be set to zero, this makes future extensions easier.
90 command | function | description
91 --------------------------------------------------------
92 0x01 | FADE_RGB | set color/fade to color (RGB)
93 0x02 | FADE_HSV | set color/fade to color (HSV)
94 0x03 | SAVE_RGB | save color to EEPROM (RGB)
95 0x04 | SAVE_HSV | save color to EEPROM (HSV)
96 0x05 | SAVE_CURRENT | save current color to EEPROM
97 0x06 | CONFIG_OFFSETS | set global offset values
98 0x07 | START_PROGRAM | start program
99 0x08 | STOP | stop color changing
100 0x09 | MODIFY_CURRENT | modify current color
101 0x0A | PULL_INT | pull down INT line
102 0x0B | CONFIG_STARTUP | configure startup
103 0x0C | POWERDOWN | power down the device
104 0x1B | | RESERVED (sync-sequence)
106 0x80 | BOOTLOADER | start bootloader
107 0x81 | BOOT_CONFIG | configure bootloader
108 0x82 | BOOT_INIT | initialize bootloader data buffer
109 0x83 | BOOT_DATA | store data in bootloader data buffer
110 0x84 | BOOT_CRC_CHECK | compare check-sum
111 0x85 | BOOT_CRC_FLASH | compare check-sum with flash
112 0x86 | BOOT_FLASH | write provided data to flash
113 0x87 | BOOT_ENTER_APP | start application
116 Command: FADE_RGB - set color/fade to color (RGB) (0x01)
117 --------------------------------------------------------
119 Instruct the device to fade to the specified absolute color, given as a
120 RGB value, with a specific speed. Step and delay might be modified by
121 application of the global offsets (see CONFIG_OFFSETS), color values
122 (red, green, blue) are used unmodified.
124 All values are unsigned 8 bit integers. If step is set to 255, the target
125 color is set without fading. If delay is 0, the target color is set
126 directly after receiving the command packet.
128 byte offset | name | description
129 ---------------------------------
130 2 | step | increment step for fading
131 3 | delay | delay between steps when fading (in 10ms)
133 5 | green | green value
134 6 | blue | blue value
135 7-14 | - | don't care
138 Command: FADE_HSV - set color/fade to color (HSV) (0x02)
139 --------------------------------------------------------
141 Instruct the device to fade to the specified absolute color, given as a
142 HSV value, with a specific speed. Step, delay and hue might be modified
143 by application of the global offsets, saturation and value might be scaled
144 by global scales (see CONFIG_OFFSETS).
146 All values are unsigned 8 bit integers, except hue, which is a 16 bit
147 little endian integer. If step is set to 255, the target color is set
148 without fading. If delay is 0, the target color is set directly after
149 receiving the command packet.
151 byte offset | name | description
152 ------------------------------------
153 2 | step | increment step for fading
154 3 | delay | delay between steps when fading (in 10ms)
155 4-5 | hue | hue, 0-360, little endian
156 6 | saturation | saturation
157 7 | value | value (brightness)
158 8-14 | - | don't care
161 Command: SAVE_RGB - save color to EEPROM (RGB) (0x03)
162 -----------------------------------------------------
164 Save a color in RGB format, a fade speed (step and delay) and a pause
165 length to the EEPROM. The EEPROM can store 60 color and speed/delay
166 values (see section "EEPROM color storage" below). While writing the
167 data to the EEPROM, the INT line is pulled down.
169 All values are unsigned 8 bit integers, except pause, which is a little
170 endian 16 bit integer.
172 byte offset | name | description
173 ------------------------------
174 2 | slot | slot in the EEPROM (0-59)
175 3 | step | increment step for fading
176 4 | delay | delay between steps when fading (in 10ms)
177 5-6 | pause | time to wait before fading to next color (in 100ms)
179 8 | green | green value
180 9 | blue | blue value
181 10-14 | - | don't care
184 Command: SAVE_HSV - save color to EEPROM (HSV) (0x04)
185 -----------------------------------------------------
187 Save a color in HSV format, a fade speed (step and delay) and a pause
188 length to the EEPROM. The EEPROM can store 60 color and speed/delay
189 values (see section "EEPROM color storage" below). While writing the
190 data to the EEPROM, the INT line is pulled down.
192 All values are unsigned 8 bit integers, except pause and hue, which are
193 little endian 16 bit integers.
195 byte offset | name | description
196 -----------------------------------
197 2 | slot | slot in the EEPROM (0-59)
198 3 | step | increment step for fading
199 4 | delay | delay between steps when fading (in 10ms)
200 5-6 | pause | time to wait before fading to next color
202 7-8 | hue | hue, 0-360, little endian
203 9 | saturation | saturation
204 10 | value | value (brightness)
205 11-14 | - | don't care
208 Command: SAVE_CURRENT - save current color to EEPROM (0x05)
209 -----------------------------------------------------------
211 Save the current color to EEPROM (RGB), together with a fade speed and a
212 pause length. While writing the data to the EEPROM, the INT line is
215 All values are unsigned 8 bit integers, except pause, which is a little
216 endian 16 bit integers.
218 byte offset | name | description
219 ----------------------------------------
220 2 | slot | slot in the EEPROM (0-59)
221 3 | step | increment step for fading
222 4 | delay | delay between steps when fading (in 10ms)
223 5-6 | pause | time to wait before fading to next color
225 7-14 | - | don't care
228 Command: CONFIG_OFFSETS - set global offset values (0x06)
229 ---------------------------------------------------------
231 Set global values which influence how fast and what colors are when using
232 FADE_RGB or FADE_HSV or the static programs documented below. All bytes are
233 signed 8 bit integers, except hue, which is a little endian signed 16 bit
234 integer. Saturation and value are scales. This means, the final saturation
235 and value will be scaled with saturation/255 and value/255, respectively.
237 byte offset | name | description
238 -------------------------------------------
239 2 | step | increment step for fading (offset)
240 3 | delay | delay between steps when fading
241 | | (in 10ms, offset)
242 4-5 | hue | hue offset, signed, little endian
243 6 | saturation | saturation scale, unsigned, 0-255
244 7 | value | value scale, unsigned, 0-255
245 8-14 | - | don't care
248 Command: START_PROGRAM - start program (0x07)
249 ---------------------------------------------
251 Start a program (a function compiled into the firmware) with given
252 parameters. This command stops all other programs (and EEPROM fade
253 sequences). For a list of programs and parameters see section
256 byte offset | name | description
257 ---------------------------------
258 2 | program | program id, 0-255
259 3-11 | params | 10 byte parameters passed to program
260 12-13 | - | don't care
263 Command: STOP - stop color changing (0x08)
264 ------------------------------------------
266 Stop all processes modifying the current color. Optionally, also stop
267 the current fading process.
269 byte offset | name | description
270 ---------------------------------
271 2 | fade | stop fading if set (1)
272 3-14 | - | don't care
275 Command: MODIFY_CURRENT - modify current color (0x09)
276 -----------------------------------------------------
278 Instruct the device to fade to a new target color, which is determined
279 relatively to the one currently visible. This works only if no
280 program (or EEPROM fade sequence) is running. The current color is
281 faded to the target color with the given step and delay values. The
282 RGB offsets are applied before the HSV offsets. Setting either one to
283 zero will not modify the color in that color space.
285 Step and delay are unsigned 8 bit integers, all other values are signed 8
286 (or 16) bit integers.
288 byte offset | name | description
289 -------------------------------------
290 2 | step | increment step for fading
291 3 | delay | delay between steps when fading (in 10ms)
293 5 | green | green offset
294 6 | blue | blue offset
295 4-5 | hue | hue offset
296 6 | saturation | saturation offset
297 7 | value | value offset
298 8-14 | - | don't care
301 Command: PULL_INT - pull down INT line (0x0A)
302 ---------------------------------------------
304 Instruct the adressed device to immediately pull down the INT line
305 (connected to all devices in parallel) for a given amount of time. This
306 can be efficiently used to determine the number of devices listening to
307 the bus (eg. by binary search).
309 byte offset | name | description
310 ---------------------------------
311 2 | delay | time to wait before releasing the INT line
312 | (in 50ms, maximum 2550ms, jitter +-10ms)
313 3-14 | - | don't care
316 Command: CONFIG_STARTUP - configure startup (0x0B)
317 --------------------------------------------------
319 Configure what a device should perform after power-up. Mode is an
320 unsigned 8 bit integer, selecting the desired startup mode.
322 Two different modes can be configured:
324 * NOTHING (mode == 0):
325 Do nothing after startup (ie do not show any color, stay black)
327 * PROGRAM (mode == 1):
328 Start a static program compiled into the firmware, using the
329 following 10 bytes as parameters for the program (for details
330 see section "Static Programs").
332 If startup mode is PROGRAM, the CONFIGURE_STARTUP packet is constructed in
333 this way (for the program indexes and meaning of the parameters see
334 section "Static Programs"):
336 byte offset | name | description
337 ------------------------------------
338 2 | mode | desired startup mode (1 in this case)
339 3 | program | static program index
340 4-14 | parameters | parameters to configured program
343 Command: POWERDOWN - power down device (0x0C)
344 ---------------------------------------------
346 Power down the device. After receiving this command, the device should
347 power down all light outputs and suspend itself to reduce the power
348 consumption to a minimum. A device must resume operation after a falling
349 edge on the INT pin. It is allowed to activate a pull-up resistor on
350 that pin, to pull the pin to a defined level.
352 byte offset | name | description
353 ------------------------------------
357 Command: BOOTLOADER - start bootloader (0x80)
358 ---------------------------------------------
360 If a bootloader is installed, jump to the bootloader, otherwise just
361 restart the device. A magic byte sequence of 0xfc27566b (little endian)
362 must follow the command byte. Pull down the INT line BEFORE sending this
363 command, otherwise the bootloader might not be able to detect wether to
364 start the main firmware or remain within the bootloader code.
366 byte offset | name | description
367 ---------------------------------
368 2 | byte1 | magic byte 1 (0x6b)
369 3 | byte2 | magic byte 2 (0x56)
370 4 | byte3 | magic byte 3 (0x27)
371 5 | byte4 | magic byte 4 (0xfc)
372 6-14 | - | don't care
375 Command: BOOT_CONFIG - configure bootloader (0x81)
376 --------------------------------------------------
378 Set configuration options of the bootloader. Currently the only
379 options is the start address.
381 Start address is an unsigned 16-bit integer automatically incremented
382 by the configured packet size upon each flash command.
384 byte offset | name | description
385 ---------------------------------
386 2-3 | start | address to flash to
387 4-14 | - | don't care
390 Command: BOOT_INIT - initialize bootloader data buffer (0x82)
391 -------------------------------------------------------------
393 This resets and clears the internal bootloader data buffer.
395 byte offset | name | description
396 ---------------------------------
397 2-14 | data | payload
400 Command: BOOT_DATA - store data in the bootloader data buffer (0x83)
401 --------------------------------------------------------------------
403 Store data (up to 13 data bytes) at the end of the bootloader data
404 buffer. If the buffer is full, additional bytes will be ignored.
406 byte offset | name | description
407 ---------------------------------
408 2-14 | data | payload
411 Command: BOOT_CRC_CHECK - compare check-sum (0x84)
412 --------------------------------------------------
414 Compare provided CRC-16 checksum against calculated checksum over the
415 first len bytes of previously received data in the data buffer. If both
416 checksums do not match, the boot loader MUST immediately pull down the
417 INT line. The INT line must be held down for the time specified in delay
418 and be released afterwards. chksum is a little endian unsigned 16 bit
421 The CRC calculation uses the polynomial x^16 + x^15 + x^2 + 1 (0xa001)
422 and 0xffff as initial value.
424 byte offset | name | description
425 ---------------------------------
426 2-3 | len | checksum over the first len buffer bytes in the buffer
427 4-5 | chksum | CRC-16 checksum over the data chunk
428 6 | delay | time to wait before releasing the INT line
429 | (in 50ms, maximum 2550ms, jitter +-10ms)
430 7-14 | - | don't care
433 Command: BOOT_CRC_FLASH - compare check-sum with flash (0x85)
434 -------------------------------------------------------------
436 Compare provided CRC-16 checksum against calculated checksum over
437 len bytes from flash starting at addr. If both checksums do not match,
438 the boot loader MUST immediately pull down the INT line. The INT line
439 must be held down for the time specified in delay and be released
440 afterwards. Chksum, start and len are unsigned 16 bit little endian
443 The CRC calculation uses the polynomial x^16 + x^15 + x^2 + 1 (0xa001)
444 and 0xffff as initial value.
446 byte offset | name | description
447 ---------------------------------
448 2-3 | addr | checksum len bytes starting at this address
449 4-6 | len | checksum over the first len buffer bytes in the buffer
450 6-8 | chksum | CRC-16 checksum over the data chunk
451 9 | delay | time to wait before releasing the INT line
452 | (in 50ms, maximum 2550ms, jitter +-10ms)
453 10-14 | - | don't care
456 Command: BOOT_FLASH - write provided data to flash (0x86)
457 ---------------------------------------------------------
459 Write the data provided earlier to the flash memory of the device.
461 The device pulls the interrupt line down upon reception of the command
462 and releases it on successful completion of the command. This way the
463 master node is capable of detecting when the successing initial data
464 packet may be provided by continuously sensing the interrupt line.
466 After completion of this command the address where to flash to is
467 incremented by the configured chunk data size.
470 byte offset | name | description
471 ---------------------------------
472 2-14 | - | don't care
475 Command: BOOT_ENTER_APP - start application (0x87)
476 --------------------------------------------------
478 Leave bootloader and launch application code.
481 byte offset | name | description
482 ------------------------------------
483 2-14 | - | don't care
489 This section describes the programs which are (in the default version)
490 compiled into the firmware.
492 program "colorwheel", program index 0
493 -------------------------------------
495 This program fades throught the HSV color space, with fixed saturation and
496 value, starting at hue_start. In each step, hue_step is added to the
497 current hue value, afterwards the device fades to the resulting color (using
498 fade_step and fade_delay) and waits for the time specified by fade_sleep.
500 If add_addr is nonzero (attention: signed integer!), the fade ist not
501 started at hue_start but (hue_start + addr_add * device_address * hue_step).
503 This program honors the globally defined offsets set with the CONFIG_OFFSETS
504 command in each step. If a global offset is reconfigured, the new value
505 will be applied in the next color calculation of this program.
507 byte offset | name | description
508 ---------------------------------------------------------
509 0 | fade_step | used for fading to new color
510 | | (unsigned 8 bit integer)
511 1 | fade_delay | used for fading to now color
512 | | (unsigned 8 bit integer)
513 2 | fade_sleep | sleep between steps (in seconds)
514 | | (unsigned 8 bit integer)
515 3-4 | hue_start | start at this hue value
516 | | (unsigned 16 bit integer
517 5-6 | hue_step | add this to the hue in each step
518 | | (signed 16 bit integer)
519 7 | add_addr | add hue_step address-times before start
520 | | (signed 8 bit integer)
521 8 | saturation | saturation
522 | | (unsigned 8 bit integer)
524 | | (unsigned 8 bit integer)
527 program "random", program index 1
528 ---------------------------------
530 When this program is started, the pseudo-random generator is initialized
531 with the seed value. If the use_address-bit within the flags byte is set,
532 the address of a device is XORed with the seed before initializing the
533 pseudo-random generator, so the random values also depend on the address of
536 In each step, this program generates a new random hue value which is at
537 least min_distance away from the current hue value. Afterwards the device
538 fades to the new color (using the generated hue and the configured
539 saturation and value from the parameters). The parameters fade_step and
540 fade_delay are used in each fade. If the wait_for_fade-bit within the
541 flags byte is set, the device waits until the target color is reached.
542 Afterwards the device sleeps for a configurable amount of time (fade_sleep).
544 This program honors the globally defined offsets set with the CONFIG_OFFSETS
545 command in each step. If a global offset is reconfigured, the new value
546 will be applied in the next color calculation of this program.
555 | | | \- use_address -- XOR device address and seed before
556 | | | initializing the pseudo random generator
557 | | \--- wait_for_fade -- wait until the (newly generated)
558 | | target color is reached before sleeping
559 \---------+----- reserved
561 byte offset | name | description
562 ----------------------------------------------------------------------
563 0-1 | seed | used for initializing the random generator
564 | | (unsigned 16 bit integer)
566 | | (unsigned 8 bit integer)
567 3 | fade_step | used for fading to new color
568 | | (unsigned 8 bit integer)
569 4 | fade_delay | used for fading to now color
570 | | (unsigned 8 bit integer)
571 5-6 | fade_sleep | sleep between steps (in 100ms)
572 | | (unsigned 16 bit integer)
573 7 | saturation | saturation
574 | | (unsigned 8 bit integer)
576 | | (unsigned 8 bit integer)
577 9 | min_distance | minimal distance for new hue value
578 | | (unsigned 8 bit integer)
581 program "replay", program index 2
582 ---------------------------------
584 The commands SAVE_RGB, SAVE_HSV and SAVE_CURRENT stores a color,
585 fade_step, fade_delay and fade_sleep to the EEPROM. This program replays
586 the stored colors, from start to end. If repeat is 0, the sequence stops
587 when end is reached, if repeat is 1, the sequence is restarted from the
588 beginning and if repeat is 2, the color sequence is played in reverse
589 order, from end to beginning.
591 This program honors the globally defined offsets set with the CONFIG_OFFSETS
592 command for hsv colors in each step. If a global offset is reconfigured,
593 the new value will be applied in the next color calculation of this program.
595 byte offset | name | description
596 ----------------------------------------------------------------------
597 0 | start | index of the first color
598 | | (unsigned 8 bit integer)
599 1 | end | index of the last color (included)
600 | | (unsigned 8 bit integer)
601 3 | repeat | configure repetition
602 | | (unsigned 8 bit integer)