Citizen Engineer
Controlling MagicLight Bluetooth Bulbs
by ladyada@alum.mit.edu and fill@2600.com
Internet of Things (IoT) devices are inexpensive, popular, and incredibly fun to hack!
If you shop for IoT devices, there's about a 50/50 split between Wi-Fi and Bluetooth LE (BLE).
In this article, we'll take you through the process of "hacking" a low-cost, off-the-shelf BLE light bulb - all you need is an Android phone.
If you must, you can also use an iOS device or even a desktop with Linux (using BlueZ) or Windows (using Microsoft's Bluetooth LE Explorer).
The BLE bulb we'll be exploring today screws into a common socket and can display any color when controlled with the app.
But how does it all work?
What if you do not trust their app? And what if we want to control the bulb ourselves?
Say have the light act as an ambient indicator for our CI build status, network ping time, or when our favorite streamer comes online!
We will be using the MagicLight Bluetooth bulbs: www.magiclightbulbs.com/collections/bluetooth-bulbs (about $20 just about everywhere)
Bluetooth LE has many terms that need to be understood so you can know what is talking to what, and how.
Let's start with some BLE basics. The two modes of BLE devices are:
- Broadcasting ("Advertising") Mode (also called GAP for Generic Access Profile)
- Connected Device Mode (also called GATT for Generic ATTribute Profile)
GAP Mode deals with broadcasting peripheral advertisements, such as "I'm a device named LEDBlue-19592CBC" as well as advertising information necessary to establish a dedicated device connection if desired. This mode has two device roles involved:
Peripheral - The low-power device that broadcasts advertisements. Examples of peripherals include heart rate monitor, smartwatch, fitness tracker, iBeacon, and a smart bulb.
Central - The host "computer" that listens to advertisements broadcast by peripherals. Central is often a mobile device such as a phone, tablet, desktop, or laptop.
Advertising is information sent by the peripheral before a dedicated connection is established.
All nearby centrals can observe these advertisements. When a peripheral device advertises, it may be transmitting the name of the device, describing its capabilities, and/or some other piece of data. Central can look for advertising peripherals to connect to, and use that information to determine each peripheral's capabilities (or services offered - more on that below).
GATT Mode deals with communications between two devices once they are connected, such as between a heart monitor and a phone, or between your phone and a smart bulb. GATT mode also has two device roles:
Server - In connected mode, a device may take on a new role as a server, providing a service available to clients. It can now send and receive data packets as requested by the client device to which it now has a connection.
Client - In connected mode, a device may also take on a new role as client that can send requests to one or more of a server's available services to send and receive data packets.
A device in GATT mode can take on the role of both server and client while connected to another device.
There are a few terms to be familiar with to get the information out and usable:
Profile - A predefined collection of services that a BLE device can provide. For example, the heart rate profile, or the cycling sensor (bike computer) profile. These profiles are defined by the Bluetooth Special Interest Group (SIG). For devices that don't fit into one of the predefined profiles, the manufacturer creates its profile. For example, there is not an official "smartbulb" profile, so the Magic Light manufacturer has created its unique one.
Service - A function the server provides. For example, a heart rate monitor armband may have separate services for device information, battery service, and heart rate itself. Each service comprises collections of information called characteristics. In the case of the heart rate service, the two characteristics are "heart rate measurement" and "body sensor location." The peripheral advertises its services in GAP mode.
Characteristic - A characteristic is a container for the value, or attribute, of a piece of data along with any associated metadata, such as a human-readable name. A characteristic may be readable, writable, or both. For example, the heart rate measurement characteristic can be served up to the client device and reports the heart rate measurement as a number, as well as the unit string "bpm" for beats-per-minute. The Magic Light server has a characteristic for the RGB value of the bulb, which can be written to by the central to change the color. Characteristics each have an Universal Unique Identifier (UUID), which is a 16-bit or 128-bit ID.
Packet - Data transmitted by a device. BLE devices and host computers transmit and receive data in small bursts called packets, much like other radio or networking protocols!
O.K., now that we know the terminology, it's time for reading and writing data to characteristics to Magic Light.
An excellent way to get familiar with BLE is to read and write to individual characteristics using the Nordic nRF Connect app for Android and iOS: play.google.com/store/apps/details?id=no.nordicsemi.android.mcp
The Android version is much more feature-rich than the iOS version.
That's what we are using. Again, you can use different tools on desktop devices, such as Bluetooth LE Explorer (Windows 10) or BlueZ (Mac). Once you launch the app or scan within your program, you'll see a list of BLE peripheral devices that are broadcasting their advertisements.
Screw the bulb into a standard lamp socket and turn it on, then re-scan/refresh until you see the LEDBlue device and click on the "Connect" or "Pair" button. (Make sure it's not connected on your phone - only one central at a time can connect to the bulb peripheral!)
Once connected, look at the services available.
There are three mysterious services, with codes: 0xFFF0, 0xFFE5, and 0xFFE0
There isn't much helpful info here about what these services are, so we'll need to dig deeper into the characteristics to find what we need.
Click to explore the service with UUID of: 0xFFE5
You'll see that it contains five characteristics called red, green, blue, white, and RGBW.
Bingo!
Try writing values from 0x00 - 0xFF to each of the first four characteristics using the Write Value dialog box.
You should see the bulb immediately change color. Hacker voice: "I'm in."
In addition to a characteristic each for red, green, blue, and white, there is a combined characteristic for RGBW (although the white element is not enabled in this characteristic for some reason).
To write to the RGB combined attribute, use the characteristic UUID: 0xFFE9
The byte array looks like this: 56 FF FF FF 00 F0 AA
The first and last bytes are required (we figured these out by packet-sniffing the BLE connection from the app).
You can set the red, green, and blue values in bytes 2-4 and the range is 0x00 - 0xFF (or 0-255 in decimal).
Now that you know how it works and how to control it, you can use open-source BLE tools to connect to and control the light bulb with your computer acting as the central.
JavaScript fans can use Web Bluetooth (available in Chrome). Python folks can try Bleak. Linux fans can use BlueZ.
Now that you know the basics of BLE, try scanning, connecting, and controlling other IoT devices you own to uncover their secrets!
Good night and good luck.