Bluetooth Hacking?
Blinkenlights WDIM

From OpenBeacon

Jump to: navigation, search



A WDIM in action
The WDIM software stacks
A naked WDIM

At each lamp of the Blinkenlights installation in Toronto, a wireless dimmer was installed. Its purpose is to receive wireless 2.4GHz information and switch the lamp by using a phase control technique.

This design is based on a Atmel ARM SAM7S. For RF communication, the NRF24L01 HF frontentend was used.

In huge setups, phase control can be difficult to handle as many lamps cutting the phase at the very same time can have influence back on the electricity network. This is especially hard to control as long as all dimmers are controlled by crystal osciallators and really run in sync tightly. For relaxation of this issue, a jitter method was implemented which modifies the ignition time slightly with a random offset. This jitter defaults to 0 and can be set by an RF command.

Gamma table

In order to be able to fine-tune the dim steps, each of the 16 values are configurable. Each half sine-wave is divided in 10000 steps, so an entry in the gamma table can have a value from 0 to 10000. As these values are all configurable over the RF channel, the whole setup can be configured remotely once set up.

The RF packet size is limited to 32 bytes in total, hence the setup of all 16 gamma values is split in two commands.

RF commands

Here is a list of commands that can a WDIM device responds to.

  • SET_LAMP_ID causes the WDIM to set its internal ID and the WMCU ID so it can extract the right value from broadcastet dimmer packets. This also configures the RF frontend to a special channel for broadcasts from the configured WMCU.
  • SET_GAMMA configures the gamma table for this dimmer. This information is volatile but can be written by the WRITE_CONFIG command.
  • WRITE_CONFIG makes a WDIM write its config to flash.
  • SET_JITTER sets the jitter of a dimmer. This setting controls the jitter of the ignition time for each half wave. This information is volatile but can be written by the WRITE_CONFIG command.
  • SEND_WDIM_STATS make a dimmer to send back information about its condition to the corresponding WMCU.
  • SET_DIMMER_DELAY configures a delay in ms for a dimmer. This was indended to compensate WMCU delays but is in fact unused for now.
  • SET_DIMMER_CONTROL switches a dimmer off completely. Normally, even the lowest dim step will still let back a little glow on the filament to reduce problems caused by inrush current.
  • RESET_WDIM resets a dimmer
  • ENTER_UPDATE_MODE sends a 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.

USB command shell

Once connected to a USB host, the WMCU offers a command shell to query and configure settings of a WMCU. As the USB CDC AMC class is implemented, there should be no hazzle accessing this feature from any computer without any special driver. The following commands are available.

  • debug lets the user set a debug level. The default is 0, other possible values are 1 and 2. With debug devel 2, each received RF packet is dumped to the console.
  • dim manually sets the dimmer circuitry to a certain dim step. Useful for testing only.
  • help outputs a list of available commands.
  • id manually sets the WMCU ID and lamp ID the lamp listens to. Normally, this information is set with a RF command, but being able to input it this way helps debugging and makes setup faster.
  • reset does a reset of the internal non-volatile flash memory. Useful in case a device entered a bogus state.
  • mac sets the mac address of a device. It's mandatory to do this once, but might be done more often in case of major firmware updates.
  • nrf_dump, nrf_init and nrf_reset directly deal with the RF chip in the circuit. For debugging purpose mainly.
  • status outputs a number of internal settings and runtime variables.
  • update sends the device to an update mode. Atmel's SAMBA bootloader will come up on USB, making it easy to flash a new firmware instantaneously.

MAC address and setup procedure

MAC sticker on a WDIM

To tell each dimmer its MAC address initially, we put a sticker with a barcode of the unique MAC address on each dimmer, read it with a scanner and fed it right into the USB shell. The command resulting from the read barcode is interpreted by the firmware to set the ID internally.

Another reason for this sticker is that all dimmers were rolled out over a period of around one week. They were just grabbed out of a huge container and distributed in an arbitrary manner, so we needed to figured out which dimmer was in which position eventually. To make this acquisition easy, the barcode was read again in the correct order. The emerging text files reflect the position of each dimmer precisely so each WMCU can be told which dimmers are in its range.

See the Blinkenlights website for source code of the tools and scripts we used.

Firmware source and design documents

Firmware sources for the WDIM can be found in the OpenBeacon git tree. In the sources, the WDIM is called openbeacon-blinkenlights-dimmer. You can find more information on our OpenBeacon git repository page.

Schematics are released as PDF under a Creative Commons share-alike licence.