Hacking Kuando Busylight for your own good
Kuando Busylight Omega interfaced with Raspberry pi running Busylight REST interface
How Kuando Busylight actually works(-ish)…
Kuando Busylight Omega is a wonderful product as a status indicator whether in a personal space or in a work environment. For the uninitiated, Busylight is a small status “blub” that shows different status indicators depending on your presence status whether “in-call” or “busy” or simply “do-not” disturb me.
Here’s how it works from their promo:
Busylight in-general, is targeted more towards the “corporate” crowd, meaning it has fantastic integration to enterprise applications like Microsoft Lync, Skype for Business, 3CX etc., but not much for the public.
The mood of the light, ringtones etc can not be used outside the boundaries these applications. Although in theory you can use it to pretty much any application, if you “crack the code”.
To their defense, they did release desktop application and an “SDK”, (which is available only on request). BUT a huge complaint on my side is that there are no SDKs available for either Java or related. Working with JavaScript and/or any non-open source languages is a big no-no for me. There were some projects available here and here that tried a way to access Busylight programmatically. There were fine, but almost all of them riddled with this “magic” initial value that has no explanation. The one I hate the most is working with “magic” values that preassumbly has no reasons behind it.
But, a great resource along with these project is this unappreciated communication protocol document.
Bingo! 🎇🌟 this was a gold mine for me, this means I can communicate with Busylight pure and unadulterated, without any middle man. This idea was very much appealing to me. It didn’t take too long for analyzing the protocol, after few days of trial and errors, I disentangled this magic code that everyone seems to be using without any logic what so-ever.
The Communication Protocol
The “protocol” is nothing but a series of bytes that are sent across to Kaundo Busylight via the underlying USB comm layer. For sake of explanation lets call this a Protocol Specification (ProtocolSpec). This article or any future articles does not cover the actual transfer of this signal. Instead we will focus on the structure of this payload, how to construct it, manipulate it to get different light settings and assume that the transfer actually works from the underlying driver.
The Protocol Specification
As per rev2.2 the following spec works for the following Plenom devices –
| Serial | Device Model |
|---|---|
| 0x3BCA | Busylight Alpha |
| 0x3BCB | Busylight UC |
| 0x3BCC | Kuando Box |
| 0x3BCD | Busylight Omega |
The specification is just 64 byte payload arranged in 8x8 byte grid. Each 8 byte order is a ProcotolStep. Every StepByte represents an unsigned integer with values 0 - 255.
An 8x8 byte grid overview of the Communication protocol specification for all Kuando Busylight devices
There can be 7 protocol steps (7x8 bytes) that constitutes the actual data payload and the last 8x8 bytes are the so-called Meta payload; of which the last two bytes 63, 64 bytes are the checksum of the data payload (ordered as MSB, LSB). The checksum itself is just the sum of the all values in the data payload. This can be calculated as follows:
// checksum formula here
The Charecteristics of each step is defined by this so-called Command Byte and Kuando Busylight can technically run 7 steps at a time on a single ProtocolSpec until the signal timeout. So, for Busylight to run the same spec continuously one must send this KeepAlive command periodically before the timeout.
StepBytes
A ProtocolStep starts with a commandbyte which defines what kind of protocolspec that is being sent to the device. A detailed explanation of each stepbyte is available as follows -
| CommandByte | byte format | notes |
|---|---|---|
| RESET_DEVICE | 00100000 | resets the device |
| START_BOOT_LOADER | 01000000 | starts the boot loader |
| KEEP_ALIVE | 1000XXXX | XXXX 4 bits for timeout |
| NEXT_STEP | 00010XXX | XX 3 bits (0-7) defines the step to execute next |
| RepeatByte | byte format | notes |
|---|---|---|
| **** | XXXXXXXX | 8 bits (0-255) defines how many times the current step should execute |
| ColorByte | byte format | notes |
|---|---|---|
| RED | XXXXXXXX | 8 bits (0-255) defines the _intensity_ (not pixel) value of red LED in the device |
| GREEN | XXXXXXXX | 8 bits (0-255) defines the _intensity_ (not pixel) value of green LED in the device |
| BLUE | XXXXXXXX | 8 bits (0-255) defines the _intensity_ (not pixel) value of blue LED in the device |
| TimeByte | byte format | notes |
|---|---|---|
| TIME_ON | XXXXXXXX | 8 bits (0-255) defines the time duration in seconds (value/10, max 25.5 seconds) where the lights (red, green, blue) leds are switched on. |
| TIME_OFF | XXXXXXXX | 8 bits (0-255) defines the time duration in seconds (value/10, max 25.5 seconds) where the lights (red, green, blue) leds are switched off. |
| ToneByte | byte format | notes |
|---|---|---|
| **** | CTTTTVVVV | ** |
| T [ToneId] | TTTT | 4 bits (0-15) 1 = OPENOFFICE, 2 = QUIET, 3 = FUNKY, 4 = FAIRY_TALE, 5 = KUANDO_TRAIN, 6 = TELEPHONIC_NORDIC, 7 = TELEPHONIC_ORIGINAL, 8 = TELEPHONIC_PICKMEUP 9 = IM_1, 10 = IM_2, 13 = IM_3 |
| V [ToneVolume] | VVV | 3 bits (0-7) 0 - no volume, mute 7 - max volume |
| MetaStep | ||
|---|---|---|
| SensitivityByte | XXXXXXXX | 8 bits (0-31) configure sensitivity (only for Kuando Box) |
| TimeoutByte | XXXXXXXX | 8 bits (1-30) seconds before the current spec times out (only for Kuando Box) |
| TriggerByte | XXXXXXXX | 8 bits (1-250) milliseconds trigger time (only of Kuando Box) |
| ChecksumMSBByte | XXXXXXXX | Most significant byte of 2-byte-Checksum |
| ChecksumLSBByte | XXXXXXXX | Least significant byte of 2-byte-Checksum |
On first glance, this is sounds quite intimidating, in-fact this is but on the other hand it gives a lot of opportunity to explore more and gives us more control over what is possible with the device. After digging a little bit more, I wrote Java driver for communicating with Busylight device.
So, Now what? What is possible with learning about this Spec
Here’s what is possibly possible by learning about this spec. I wrote a nice REST interface which uses this driver.
The rest server can now run on a raspberry pi and then the uses are limitless :)
Raspberry Pi running Kuando Bustlight REST interface
for example, you can use your beloved Apple Shortcuts for setting your status, may be sprinkle-in a voice action perhaps?
putting your apple shortcuts to good use #RaspberryPi #busylight #shortcuts pic.twitter.com/N8hEyB9kKS
— tckb (@this_is_tckb) September 10, 2019
What would you use it for?