LightBus/Protokoll
Zur Navigation springen
Zur Suche springen
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 500000 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 little 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