LightBus/Protokoll

LightBus protocol documentation (WIP)
=====================================

The LightBus (lbus) is a bus designed for communicating with lighting actors. It might work as a
generic control bus for other actors/sensors, too. The protocol is designed as a master/slave
system. There should be one single master in a lbus segment and 1-n slaves.

Physical layer
--------------

RS485 transceivers are used for communication. The lbus is designed for half-duplex communication,
where the master is in control by default. Slaves can send, too, but only when asked for it by the
master.

Data link layer
---------------

Communication is designed for UARTs. It uses 921600 Baud communication, 8 data bits, 1 stop bit,
no parity information.

Slaves default to receiving data, the master by default transmits data. Direction can be switched
if mandated by the protocol.

Network layer
-------------

On the bus, information is sent in packet entities. A packet is a series of bytes. The first two
bytes specify the overall length of the packet. A packet is always started by the master, it might,
however, be continued at a protocol defined point by a slave.

When there is no transmission for a given timeout (TODO: specify it here) after a packet has been
started but not yet completed, the packet is considered to be done. It is undefined if the
information transmitted so far is to be considered valid.

General packet format:

packet byte offset: 0    | 1    | 2    | 3...
                    length      | addr | data

All multi-byte values, like the 16bit length field, are sent in lower endian format.

length:
  the packet length, including potential answer from slaves

addr:
  the packet's destination address. The source is always the lbus master, the address specifies
  the slave's address or an address of a group of slaves
  For now, the addresses 128-255 are reserved. They might be used if the protocol at some point
  gets extended to allow for more addresses or similar use cases.
  Also, address 0 is reserved and should not be used.
  Address 127 is reserved to be a group ID assigned implicitly to all slaves.

Transport layer
---------------

All packets' data sections start with a 1-byte command ID (cmd). ID values 128-255 are reserved
for future extension.

packet byte offset: 0    | 1    | 2    | 3    | ...
                    length      | addr | cmd  | cmd_data


Application layer
-----------------

The following commands are defined:

0:
  reserved

1: PING
  This command sends a ping to a slave controller and expects an answer from the controller.

  addr must not be a group address.

  packet byte offset: 0    | 1    | 2    | 3    | 4
  sender:             M           | M    | M    | S
                      5           | addr | 1    | response

2: GET_DATA
  This command reads data from a slave. The data to return is determined by the 16bit "type"
  ID. Depending on the ID, the master might send additional information (like a sub-ID).
  The master has to specify the length of data the slave must send when answering using
  the overall packet length.

  addr must not be a group address.

  packet byte offset: 0    | 1    | 2    | 3    | 4    | 5    | 6...
  sender:             M           | M    | M    | M           | S
                      5+n         | addr | 2    | type        | response

  At this point, the following types and corresponding response lengths (n) are defined:

  id    | n    | description of response
  ------|------|------------------------------------------------------------------------
  1     | 1    | operational status
  2     | 4    | firmware version
  3     | 4    | bootloader version
  4     | 1    | number of assigned groups
  5     | 1..m | group IDs:
        |      | slave will send up to <n> group IDs assigned to it
        |      | when there are no more IDs assigned, but still IDs to send, it will
        |      | send an ID of 0 for each such ID.

3: SET_GROUPS
  This command sets the group addresses assigned to a slave.
  It will overwrite existing assigned group addresses.
  Note: group ID 127 is always implicitly assigned.

  packet byte offset: 0    | 1    | 2    | 3    | (4...)
  sender:             M           | M    | M    | (M)
                      4+n         | addr | 124  | (group id...)

10: LED_SET_16BIT
  This command sets the 16bit PWM duty cycle for n (one or more) LEDs. After receiving,
  it will not be effective immediately (see LED_COMMIT).
  Each LED - and this means physical LED, so an RGB LED consists of 3 LEDs - is
  identified by a 16bit ID. The packet specifies the first LED ID for which a value
  is set. All following values apply for the following LED IDs.

  packet byte offset: 0    | 1    | 2    | 3    | 4    | 5    | 6    | 7    | ...
  sender:             M           | M    | M    | M           | M           | (M)
                      6+2*n       | addr | 10   | LED ID      | value       | (value...)

11: LED_COMMIT
  This command will latch the programmed duty cycles to the LED's PWM, making them
  effective 

  packet byte offset: 0    | 1    | 2    | 3
  sender:             M           | M    | M
                      4           | addr | 11

124: SET_ADDRESS
  This command sets the (new) address (naddr) of a slave.
  The slave confirms a successful operation by replying with the new address.
  It is only handled in bootloader mode.

  packet byte offset: 0    | 1    | 2    | 3    | 4     | 5
  sender:             M           | M    | M    | M     | S
                      6           | addr | 124  | naddr | naddr

125: READ_MEMORY
  This command requests memory contents from a device.
  It can be used e.g. to verify a successful firmware flash.

  packet byte offset: 0    | 1    | 2    | 3    | 4    | 5    | 6    | 7    | 7+1...7+n | 8+n  | 9+n  | 10+n | 11+n
  sender:             M    | M    | M    | M    | M                         | S         | S
                      12+length   | addr | 125  | address                   | data      | CRC32 for data

126: FLASH_FIRMWARE
  This command sends data to be put into a device's flash.
  When in bootloader mode, the firmware flash pages can be written to.
  When in default firmware mode, the bootloader flash pages can be written to.

  packet byte offset: 0    | 1    | 2    | 3    | 4    | 5    | 6    | 7    | 8    | 9    | 10...
  sender:             M    | M    | M    | M    | M           | M                         | M
                      10+length   | addr | 126  | Page ID     | CRC32 for data            | data

127: RESET_TO_BOOTLOADER
  This command will make the slave go into bootloader mode

  packet byte offset: 0    | 1    | 2    | 3
  sender:             M    | M    | M    | M
                      4           | addr | 127