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.
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.
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
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
4 | 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
4 | 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