Blinkenlights WMCU

Abstract


The Blinkenlights Wireless Matrix Control Unit is a Atmel ARM SAM7X based microcontroller design for the Blinkenlights installation which has Ethernet at one end and the OpenBeacon RF frontend on the other side. For RF communication, the NRF24L01 HF frontentend was used.



The WMCU has an internal list of up to 32 lamps it can control and holds the row, column and dimmer MAC address for each of them. Whenever a Blinkenlights UDP packet is received by the firmware, it is parsed by the firmware and the individual pixel information for each relevant lamp is extracted and sent out as a broadcast packet to all listening dimmers.



There are also control commands received by the WMCU to setup internal parameters, control the Lamp map, send packets to single dimmers individually and to query status information.

A packet sent over the wireless channel is described by the Blinkenlights RF packet format, the wired Ethernet packets are defined by the Blinkenlights Ethernet packet format.

Ethernet commands affecting the WMCU
As of version 1.0, the WMCU can handle the following commands received via Ethernet.

These are the commands that affect the WMCU directly:


 * Multiframe packets are sent to the WMCU in order to set the actual dim values for the pixels. For each entry in the lampmap, the according information in the multiframe packet is parsed and a broadcast packet is prepared for all the connected dimmers. As each dimmer has its own ID, it can then extract its information from the broadcast packet again. See also Blinkenlights WDIM.
 * SET_MCU_ID sets the internal ID of a WMCU. This information is used to configure a special RF pipe used for addressing the dimmers so collisions between different RF domains are kept to a minimum.
 * SET_ASSIGNED_LAMPS configures the lamp map of WMCU. This is mandatory in order to let the WMCU know which parts of a multiframe is has to extract. Once this command is received, each WDIM is also configured to its lamp and WMCU id.
 * SET_RF_POWER sets the RF power used by the WMCU to drive it RF output channel. The default is set to 3 which is the maximum. Lower strength can be used to avoid crosstalk between different domains.
 * SET_JAM_DENSITY configures the density of the RF channel jamming. Each packet is sent out multiple times to compensate possible packet loss. The value of this command sets the delay between two consecutive packets in milliseconds.
 * SEND_WMCU_STATS make the WMCU to send back information about its condition via UDP. See the protocol specs for more detailed information of how the packet is up.
 * RESET_MCU makes the WMCU to vector to its reset code. For paranoia reasons only.
 * OUTPUT_RAW directly sends out information using the wireless channel, bypassing other procotol layers. This is used for debugging purposes only.

Ethernet commands affecting the WDIMs
These commands are sent to the WMCU in order to configure or query a dimmer connected to the RF channel. By addressing a dimmer, a MAC address is given in each packet. This can either be a usual MAC address a dimmer is configured to or 0xFFFF which addresses them all.


 * SET_LAMP_ID causes a packet to be sent to an individual lamp in order to set its ID.
 * SET_GAMMA configures the gamma table for a specific lamps or all lamps connected
 * WRITE_CONFIG makes a specific dimmer write its config to flash. See Blinkenlights WDIM
 * SET_JITTER sets the jitter of a dimmer
 * SEND_WDIM_STATS make a dimmer to send back information about its condition
 * SET_DIMMER_DELAY configures a delay in ms for a dimmer
 * SET_DIMMER_CONTROL switches a dimmer off completely
 * RESET_WDIM resets a dimmer
 * ENTER_UPDATE_MODE sends a Blinkenlights WDIM to update mode. This is highly dangerous as it destroys the firmware on a WDIM device permanently. This command is hence protected by some magic numbers. Check the sources.

For more information about how the other ends parse this information, please see the Blinkenlights WDIM page.

USB command shell
Once connected to a USB host, the WMCU offers a command shell to query and configure settings of a WMCU. The following commands are available.


 * help outputs a list of available commands.
 * mac or wmcu-mac sets the last two bytes of the Ethernet MAC of this WMCU. The MAC is actually prefixed by 00:bd:33:06 and the IP address is also made up from that information and prefixed by 192.168. So for example, if the MAC is set to 1122, the Ethernet MAC will be 00:bd:33:06:11:22 and the IP 192.168.17.34.
 * id or wmcu-id sets the WMCU ID
 * status dumps many status informations such as the IP address, the MAC address, a packet count for both the Ethernet and the RF channel, the number of assigned lamps and so on.
 * lampmap dumps the lampmap configured for this WMCU.

Encryption and sequence numbers
In order to make a system unattackable, a XXTEA block cipher algorithm is used to protect the data on air. As this does still not make the system immune against simple replay attacks, a 32bit sequence number is embedded in each RF packet. This number has to be constantly growing, otherwise packets will be dropped on by the WDIM.

Also, the system must be able to handle reboots on both the WMCU and the WDIM side - recovery must always be possible.

As the WMCU has no RTC, the sequence must be seeded externally from another host which keeps timing information up and running. For this, the timestamp information in multiframe packets are used. Hence, before any control packet can be passed to a WDIM, a multiframe packet must have been received by the WMCU.

Return packets
Return packets containing status information about WDIMs and WMCUs are sent to the IP address which sent out the last configuration packet.

Firmware sources
Firmware sources can be found in the OpenBeacon GIT tree - see our OpenBeacon git repository page for more information. In the sources, the WMCU is called openbeacon-blinkenlights-wmcu.