git.zerfleddert.de Git - fnordlicht-mini/blob - firmware/doc/PROTOCOL

   1 SERIAL PROTOCOL FOR FNORDLICHT-NG FIRMWARE
   2 ==========================================
   3
   4 Physical bus description
   5 ------------------------
   6
   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.
  13
  14 Diagram:
  15
  16                 +----------------+         +----------------+
  17                 |    device N    |         |   device N+1   |
  18 UART: ... --> >-|RX            TX|-> --> >-|RX            TX|-> ...
  19                 |      INT       |         |      INT       |
  20                 +-------+--------+         +-------+--------+
  21                         |                          |
  22 INT: -------------------+--------------------------+----------> ...
  23
  24
  25 Bootloader startup procedure
  26 ----------------------------
  27
  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.
  37
  38 Initial sync sequence
  39 ---------------------
  40
  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!
  46
  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.
  51
  52 Example:
  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
  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).
  64
  65 Flow:
  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
  72 Result: Each device on the bus knows it's own address (=position).
  73
  74
  75 Commands
  76 --------
  77
  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.
  85
  86
  87 List of commands:
  88 -----------------
  89
  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)
 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
 486 Static Programs
 487 ---------------
 488
 489 This section describes the programs which are (in the default version)
 490 compiled 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   |