The Magic Bulb is, as far as I know, the cheapest bluetooth RGB light bulb on the market : you can get it for as low as ~8€/9$ on sites like Gearbest. It works pretty good and comes with mobile apps.
Unfortunately I haven't found any API or documentation for it, which is why I started this project.
I haven't fully retro-engineered the protocol yet so it's not complete but Characteristics list page and How to use manually with Gatttool page should give you enough details to start working on your own implementation if you need to port this for another language / platform. On the research/bluetooth branch you'll also find capture of bluetooth packets exchanged between Android and the bulb (open hci_capture.log with Wireshark).
Tested on Linux and Raspberry Pi. I'll be happy to get your feedback on other platforms !
There are multiple versions of the bulb, some of them may need development to be compatible with this project. If you have a different bulb version you can try to sniff bluetooth communications. Reverse-engeeniring information and pull requests are more than welcome 😺
| Bulb Version |
v7 | v8 | v9 | v10 |
|---|---|---|---|---|
| Status | ☑️ | ☑️ |
☑️ | ☑️ |
If you want to use this project with HomeAssistant you'll need to install magicblue as described below then use the component available here : https://github.com/xiaohuim/homeassistant-magicblue
You must use python 3+ and have a proper Bluetooth 4.0 interface installed on your machine.
-
Prerequisite
- Debian:
sudo apt-get install libglib2.0-dev - Fedora:
sudo dnf install glib2-devel
- Debian:
-
Install
sudo pip3 install magicblue
⚠️ If you get the errorNo such file or directory: '/usr/local/lib/python3.4/dist-packages/bluepy/bluepy-helper'orERROR:magicblue.magicblueshell:Unexpected error with command "ls": [Errno 8] Exec format error: This is a known bug in bluepy that sometimes doesn't get compiled when installed from Pypi on Raspberry Pi. You can fix it by compiling the helper yourself : Go to the lib folder (usually/usr/local/lib/python3.4/dist-packages/bluepy-1.1.0-py3.5.egg/bluepy/but could be different, especially if you're using a virtual env) and runsudo make(makeshould be enought for a virtual env) -
Raspberry Pi specifics
Follow the Debian procedure. If it doesn't work (unstable devices listing, commands have no effect) but you're sure that your bulb has a correct version (check the official app for that) then try updating bluez to the latest version. You can follow this post for more info.
Library needs elevated permissions to use Bluetooth features. You can either run as root (required for magicblueshell), or give hcitool special capabilities (see next section.)
If you run into problems during devices listing or connect, try to follow this procedure to ensure your Bluetooth interface works correctly : How to use manually with Gatttool page
You can give hcitool capabilities by installing and using the libcap library/commands.
- On most Debian systems, including Raspbian/Raspberry Pi
sudo apt-get install libcap2-bin
sudo setcap 'cap_net_raw,cap_net_admin+eip' `which hcitool`
- Fedora
sudo dnf install libcap
sudo setcap 'cap_net_raw,cap_net_admin+eip' `which hcitool`
>>> from magicblue import MagicBlue
>>> bulb_mac_address = 'XX:XX:XX:XX:XX:XX'
>>> bulb = MagicBlue(bulb_mac_address)
>>> bulb.connect()
>>> bulb.set_color([255, 0, 0]) # Set red
>>> bulb.set_random_color() # Set random
>>> bulb.turn_off() # Turn off the light
>>> bulb.turn_on() # Set white light
Script must be run as root.
You can always specify which bluetooth adapter (default: hci0) you want to use by specifying it with the -a option.
Also don't forget to specify your bulb version with -b if it's something else than 7. Example :
sudo magicblueshell -b 10 to run with version 10
Just launch magicblueshell as root user :
$ sudo magicblueshell
Magic Blue interactive shell v0.3.0
Type "help" for a list of available commands
> help
----------------------------
| List of available commands |
----------------------------
COMMAND PARAMETERS DETAILS
------- ---------- -------
help Show this help
list_devices List Bluetooth LE devices in range
ls // //
list_effects List available effects
connect mac_address or ID Connect to light bulb
disconnect Disconnect from current light bulb
set_color name or hexadecimal value Change bulb's color
set_warm_light intensity[0.0-1.0] Set warm light
set_effect effect_name speed[1-20] Set an effect
turn on|off Turn on / off the bulb
read name|device_info|date_time Read device_info/datetime from the bulb
exit Exit the script
> ls
Listing Bluetooth LE devices in range for 5 minutes.Press CTRL+C to stop searching.
ID Name Mac address
-- ---- -----------
1 LEDBLE-1D433903 c7:17:1d:43:39:03
^C
> connect 1
INFO:magicblue.magicblueshell:Connected
> set_color red
> exit
Bye !
Script can also be used by command line (for example to include it in custom shell scripts) Usage is defined as follow :
usage: magicblueshell [-h] [-l LIST_COMMANDS] [-c COMMAND] [-m MAC_ADDRESS]
[-a BLUETOOTH_ADAPTER] [-b BULB_VERSION]
Python tool to control MagicBlue bulbs over Bluetooth
optional arguments:
-h, --help show this help message and exit
-l LIST_COMMANDS, --list_commands LIST_COMMANDS
List available commands
-c COMMAND, --command COMMAND
Command to execute
-m MAC_ADDRESS, --mac_address MAC_ADDRESS
Device mac address. Must be set if command given in -c
needs you to be connected
-a BLUETOOTH_ADAPTER, --bluetooth_adapter BLUETOOTH_ADAPTER
Bluetooth adapter name as listed by hciconfig
-b BULB_VERSION, --bulb-version BULB_VERSION
Bulb version as displayed in the official app
So if you want to change the color of bulb with mac address "C7:17:1D:43:39:03", just run :
sudo magicblueshell -c 'set_color red' -m C7:17:1D:43:39:03
- Use the wiki info as a reference to implement turn_on / turn_off in a cleaner way (this may means being able to get the state from the bulb directly)
- Create a proper documentation