]> git.zerfleddert.de Git - fnordlicht-mini/blame - firmware/doc/PROTOCOL
projects / fnordlicht-mini / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
fix config.mk file header comment
[fnordlicht-mini] / firmware / doc / PROTOCOL
CommitLineData
ec1bef8e 1SERIAL PROTOCOL FOR FNORDLICHT-NG FIRMWARE
2==========================================
3
4Physical bus description
5------------------------
6
7The serial bus consists of up to 254 devices, each device having the uart rx
8pin connected to the uart tx pin of the predecessor, the uart tx pin connected
9to the tx successor. The uart is used with a baud rate of 19200. A device
10will retransmit each received byte immediately and unaltered, the only
11exception is the address byte in the sync sequence (which is incremented by one
12before retransmission). An interrupt line is connected to each device.
13
14Diagram:
15
16 +----------------+ +----------------+
17 | device N | | device N+1 |
18UART: ... --> >-|RX TX|-> --> >-|RX TX|-> ...
19 | INT | | INT |
20 +-------+--------+ +-------+--------+
21 | |
22INT: -------------------+--------------------------+----------> ...
23
24
25Bootloader startup procedure
26----------------------------
27
28For updating the firmware installed on the devices of a bus, each device should
29be equipped with a bootloader program. At power-on, the bootloader should be
30started, 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
32start the main firmware. Otherwise it should not attempt to start the main
33firmware, but wait for commands received over the bus. This procedure allows a
34recovery from a broken firmware which does not process commands received over
35the bus (such as the BOOTLOADER command). To enter the bootloader via the
36BOOTLOADER command, first pull down the INT line, then issue the command.
37
38Initial sync sequence
39---------------------
40
41For the purpose of (automatic) address discovery and resetting the bus, a
42sync sequence consisting of 15x ESC (0x1b) followed by an address byte is used.
43The controller sends 15x ESC, followed by a null byte. Please note that the
44length of the sync sequence (16 byte) is different from the length of a
45command packet, which is 15 byte!
46
47A device MUST be able to detect this sequence asynchronously, i.e. even if it is
48in the middle of receiving a command packet. The device does not need to
49withhold the execution of the received command packet until it is clear if a
50sequence of ESC bytes constitutes a sync sequence.
51
52Example:
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
55
56 A B C D ESC ESC ... ESC
57
58 but the sync sequence must be detected, too.
59
60Asynchronous detection of the sync sequence can be done by just counting the
61number of consecutive ESC bytes, as 15 consecutive ESC bytes can only occur
62in a sync sequence, never in a command packet (ESC cannot occur as a command in
63the second byte of a command packet).
64
65Flow:
66* controller sends 15x ESC, followed by the address of the first device
67 (usually a null)
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
71
72Result: Each device on the bus knows it's own address (=position).
73
74
75Commands
76--------
77
78Commands are sent in packets, 15 bytes in length, and are passed from device
79to device unmodified. The first byte is the destination address (0-254, 255
80is broadcast), the second byte contains the command. The meaning of the
81following 13 bytes depends on the value of the second byte (command). A
82device ignores non-broadcast packets for which the address byte does not
83match it's own address. Bytes which are declared as "don't care" bytes SHOULD
84be set to zero, this makes future extensions easier.
85
86
87List of commands:
88-----------------
89
90command | 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)
105
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
114
115
116 Command: FADE_RGB - set color/fade to color (RGB) (0x01)
117 --------------------------------------------------------
118
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.
123
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.
127
128 byte offset | name | description
129 ---------------------------------
130 2 | step | increment step for fading
131 3 | delay | delay between steps when fading (in 10ms)
132 4 | red | red value
133 5 | green | green value
134 6 | blue | blue value
135 7-14 | - | don't care
136
137
138 Command: FADE_HSV - set color/fade to color (HSV) (0x02)
139 --------------------------------------------------------
140
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).
145
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.
150
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
159
160
161 Command: SAVE_RGB - save color to EEPROM (RGB) (0x03)
162 -----------------------------------------------------
163
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.
168
169 All values are unsigned 8 bit integers, except pause, which is a little
170 endian 16 bit integer.
171
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)
178 7 | red | red value
179 8 | green | green value
180 9 | blue | blue value
181 10-14 | - | don't care
182
183
184 Command: SAVE_HSV - save color to EEPROM (HSV) (0x04)
185 -----------------------------------------------------
186
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.
191
192 All values are unsigned 8 bit integers, except pause and hue, which are
193 little endian 16 bit integers.
194
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
201 | | (in 100ms)
202 7-8 | hue | hue, 0-360, little endian
203 9 | saturation | saturation
204 10 | value | value (brightness)
205 11-14 | - | don't care
206
207
208 Command: SAVE_CURRENT - save current color to EEPROM (0x05)
209 -----------------------------------------------------------
210
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
213 pulled down.
214
215 All values are unsigned 8 bit integers, except pause, which is a little
216 endian 16 bit integers.
217
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
224 | | (in 100ms)
225 7-14 | - | don't care
226
227
228 Command: CONFIG_OFFSETS - set global offset values (0x06)
229 ---------------------------------------------------------
230
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.
236
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
246
247
248 Command: START_PROGRAM - start program (0x07)
249 ---------------------------------------------
250
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
254 "Static Programs".
255
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
261
262
263 Command: STOP - stop color changing (0x08)
264 ------------------------------------------
265
266 Stop all processes modifying the current color. Optionally, also stop
267 the current fading process.
268
269 byte offset | name | description
270 ---------------------------------
271 2 | fade | stop fading if set (1)
272 3-14 | - | don't care
273
274
275 Command: MODIFY_CURRENT - modify current color (0x09)
276 -----------------------------------------------------
277
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.
284
285 Step and delay are unsigned 8 bit integers, all other values are signed 8
286 (or 16) bit integers.
287
288 byte offset | name | description
289 -------------------------------------
290 2 | step | increment step for fading
291 3 | delay | delay between steps when fading (in 10ms)
292 4 | red | red offset
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
299
300
301 Command: PULL_INT - pull down INT line (0x0A)
302 ---------------------------------------------
303
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).
308
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
314
315
316 Command: CONFIG_STARTUP - configure startup (0x0B)
317 --------------------------------------------------
318
319 Configure what a device should perform after power-up. Mode is an
320 unsigned 8 bit integer, selecting the desired startup mode.
321
322 Two different modes can be configured:
323
324 * NOTHING (mode == 0):
325 Do nothing after startup (ie do not show any color, stay black)
326
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").
331
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"):
335
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
341
342
343 Command: POWERDOWN - power down device (0x0C)
344 ---------------------------------------------
345
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.
351
352 byte offset | name | description
353 ------------------------------------
354 2-14 | don't care |
355
356
357 Command: BOOTLOADER - start bootloader (0x80)
358 ---------------------------------------------
359
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.
365
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
373
374
375 Command: BOOT_CONFIG - configure bootloader (0x81)
376 --------------------------------------------------
377
378 Set configuration options of the bootloader. Currently the only
379 options is the start address.
380
381 Start address is an unsigned 16-bit integer automatically incremented
382 by the configured packet size upon each flash command.
383
384 byte offset | name | description
385 ---------------------------------
386 2-3 | start | address to flash to
387 4-14 | - | don't care
388
389
390 Command: BOOT_INIT - initialize bootloader data buffer (0x82)
391 -------------------------------------------------------------
392
393 This resets and clears the internal bootloader data buffer.
394
395 byte offset | name | description
396 ---------------------------------
397 2-14 | data | payload
398
399
400 Command: BOOT_DATA - store data in the bootloader data buffer (0x83)
401 --------------------------------------------------------------------
402
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.
405
406 byte offset | name | description
407 ---------------------------------
408 2-14 | data | payload
409
410
411 Command: BOOT_CRC_CHECK - compare check-sum (0x84)
412 --------------------------------------------------
413
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
419 integer.
420
421 The CRC calculation uses the polynomial x^16 + x^15 + x^2 + 1 (0xa001)
422 and 0xffff as initial value.
423
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
431
432
433 Command: BOOT_CRC_FLASH - compare check-sum with flash (0x85)
434 -------------------------------------------------------------
435
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
441 integers.
442
443 The CRC calculation uses the polynomial x^16 + x^15 + x^2 + 1 (0xa001)
444 and 0xffff as initial value.
445
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
454
455
456 Command: BOOT_FLASH - write provided data to flash (0x86)
457 ---------------------------------------------------------
458
459 Write the data provided earlier to the flash memory of the device.
460
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.
465
466 After completion of this command the address where to flash to is
467 incremented by the configured chunk data size.
468
469
470 byte offset | name | description
471 ---------------------------------
472 2-14 | - | don't care
473
474
475 Command: BOOT_ENTER_APP - start application (0x87)
476 --------------------------------------------------
477
478 Leave bootloader and launch application code.
479
480
481 byte offset | name | description
482 ------------------------------------
483 2-14 | - | don't care
484
485
486Static Programs
487---------------
488
489This section describes the programs which are (in the default version)
490compiled into the firmware.
491
492 program "colorwheel", program index 0
493 -------------------------------------
494
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.
499
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).
502
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.
506
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)
523 9 | value | value
524 | | (unsigned 8 bit integer)
525
526
527 program "random", program index 1
528 ---------------------------------
529
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
534 the device.
535
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).
543
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.
547
548 flags (1 byte)
549 --------------
550
551 Bits:
552 MSB LSB
553 7 6 5 4 3 2 1 0
554 | | | |
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
560
561 byte offset | name | description
562 ----------------------------------------------------------------------
563 0-1 | seed | used for initializing the random generator
564 | | (unsigned 16 bit integer)
565 2 | flags | flags
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)
575 8 | value | value
576 | | (unsigned 8 bit integer)
577 9 | min_distance | minimal distance for new hue value
578 | | (unsigned 8 bit integer)
579
580
581 program "replay", program index 2
582 ---------------------------------
583
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.
590
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.
594
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)
603 4-9 | don't care |
fnordlicht-mini verpeilung
Impressum, Datenschutz