MagicBlue - Cheap bluetooth bulbs
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.
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-engineering
information and pull requests are more than welcome
MagicBlue is not compatible with Windows.
You must use python 3+ and have a proper Bluetooth 4.0 interface installed on your machine.
sudo apt-get install libglib2.0-dev
sudo dnf install glib2-devel
sudo pip3 install magicblue
Library needs elevated permissions to use Bluetooth features. You can either run as root (required for magicblueshell), or give
hcitoolspecial capabilities (see this link)
- Bluepy not compiled (very common)
If you get an error like
No such file or directory: '/usr/local/lib/python3.4/dist-packages/bluepy/bluepy-helper'
ERROR:magicblue.magicblueshell:Unexpected error with command "ls": Helper exited:
this is a known bug in bluepy that sometimes doesn't get compiled when installed from Pypi.
You can fix it by compiling the helper yourself :
Go to the lib folder (usually
but could be different, especially if you're using a virtual env) and
sudo make (
make should be enought for a virtual env).
- Other errors
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
Check the API documentation
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.
Using the interactive shell
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 !
Passing command as an option
Script can also be used by command line (for example to include it in custom shell scripts):
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
The protocol isn't fully retro-engineered 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).