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-254 are reserved. They might be used if the protocol at some point
  gets extended to allow for more addresses or similar use cases. They must not be used until
  their use is specified.
  Also, address 0 is reserved and should not be used.
  Address 255 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     | 1    | device's LBUS address
  3     | 4    | firmware version
  4     | 4    | bootloader version
  5     | 1    | length of the stored name of the current firmware
  6     | 1..m | name of the current firmware

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

122: RESET_TO_BOOTLOADER
  This command requests to restart the slave device in bootloader mode. When in
  bootloader mode already, all running timeouts are stopped, so the device will
  stay in bootloader mode until explicitly put back into normal mode.

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

123: ERASE_CONFIG
  This command requests to erase the configuration store area of the flash
  memory. This can be used when resetting a device to factory mode or in order
  to defragment the configuration store.

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

124: SET_ADDRESS
  This command sets the (new) address (naddr) of a slave.
  The slave confirms a successful operation by replying with 0.
  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 | <result>

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.
  Slave sends a result byte 0 when operation was successful.

  packet byte offset: 0    | 1    | 2    | 3    | 4    | 5    | 6..1029    | 1030 | 1032 | 1033 | 1034 | 1035
  sender:             M    | M    | M    | M    | M           | M          | M                         | S
                      1036        | addr | 126  | Page ID     | data       | CRC32 for data            | result

127: RESET_TO_FIRMWARE
  This command will make a slave in bootloader mode reset and boot into firmware

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