{"id":15043644,"url":"https://github.com/betree/magicblue","last_synced_at":"2025-04-14T03:15:17.633Z","repository":{"id":49270519,"uuid":"46747497","full_name":"Betree/magicblue","owner":"Betree","description":"💡 Unofficial Python API to control Magic Blue bulbs over Bluetooth","archived":false,"fork":false,"pushed_at":"2022-12-08T00:52:57.000Z","size":113,"stargazers_count":101,"open_issues_count":23,"forks_count":22,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-14T03:15:10.799Z","etag":null,"topics":["ble","bluetooth","bulb","iot","magic-blue-bulbs","python","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Betree.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-23T20:56:28.000Z","updated_at":"2024-10-21T05:26:53.000Z","dependencies_parsed_at":"2023-01-24T01:30:29.325Z","dependency_job_id":null,"html_url":"https://github.com/Betree/magicblue","commit_stats":null,"previous_names":["betree/pymagicblue"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Betree%2Fmagicblue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Betree%2Fmagicblue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Betree%2Fmagicblue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Betree%2Fmagicblue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Betree","download_url":"https://codeload.github.com/Betree/magicblue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248813803,"owners_count":21165634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","bluetooth","bulb","iot","magic-blue-bulbs","python","raspberry-pi"],"created_at":"2024-09-24T20:49:22.662Z","updated_at":"2025-04-14T03:15:17.613Z","avatar_url":"https://github.com/Betree.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![MagicBlue Bulb](https://lut.im/xpaCaUNTaU/k6WRbc71KMMSFIln.jpg)\n\n# MagicBlue - Cheap bluetooth bulbs\n\n[![Documentation Status](https://readthedocs.org/projects/magicblue/badge/?version=latest)](http://magicblue.readthedocs.io/en/latest/?badge=latest)\n\nThe Magic Bulb is, as far as I know, the cheapest bluetooth RGB light bulb\non the market : you can get it for as low as ~8€/9$ on sites like\n[Gearbest](http://www.gearbest.com/smart-light-bulb/pp_230349.html).\nIt works pretty good and comes with mobile apps.\n\nUnfortunately I haven't found any API or documentation for it, which is\nwhy I started this project.\n\n\nThere are multiple versions of the bulb, some of them may need development\nto be compatible with this project. If you have a different bulb version\nyou can try to sniff bluetooth communications. Reverse-engineering\ninformation and pull requests are more than welcome 😺\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eBulb Version\u003cbr\u003e\u003c/th\u003e\n    \u003cth\u003ev6\u003c/th\u003e\n    \u003cth\u003ev7\u003c/th\u003e\n    \u003cth\u003ev8\u003c/th\u003e\n    \u003cth\u003ev9\u003c/th\u003e\n    \u003cth\u003ev10\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eStatus\u003c/td\u003e\n    \u003ctd\u003e☑️\u003c/td\u003e\n    \u003ctd\u003e☑️\u003c/td\u003e\n    \u003ctd\u003e☑️\u003cbr\u003e\u003c/td\u003e\n    \u003ctd\u003e☑️\u003c/td\u003e\n    \u003ctd\u003e☑️\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Installation\n### HomeAssistant\nIf you want to use this project with [HomeAssistant](https://home-assistant.io/)\nyou'll need to install `magicblue` as described below then use the\ncomponent available here: https://github.com/Betree/homeassistant-magicblue\n\nMagicBlue is not compatible with Windows.\n\n### Linux\nYou must use python 3+ and have a proper Bluetooth 4.0 interface\ninstalled on your machine.\n\n* Prerequisite\n\n  - Debian: `sudo apt-get install libglib2.0-dev`\n  - Fedora: `sudo dnf install glib2-devel`\n\n* Install\n\n  \u003e sudo pip3 install magicblue\n\n  Library needs elevated permissions to use Bluetooth features. You can either\n  run as root (required for magicblueshell), or give `hcitool` special capabilities\n  (see [this link](https://github.com/Betree/magicblue/wiki/Giving-hcitool-capabilities))\n\n### Known errors\n\n  * Bluepy not compiled (very common)\n  \n  If you get an error like `No such file or directory: '/usr/local/lib/python3.4/dist-packages/bluepy/bluepy-helper'`\n\tor `ERROR:magicblue.magicblueshell:Unexpected error with command \"ls\": Helper exited`:\n\tthis is a known bug in bluepy that sometimes doesn't get compiled when installed from Pypi.\n\tYou can fix it by compiling the helper yourself :\n\tGo to the lib folder (usually `/usr/local/lib/python3.5/dist-packages/bluepy-1.1.2-py3.5.egg/bluepy/`\n\tbut could be different, especially if you're using a virtual env) and\n\trun `sudo make` (`make` should be enought for a virtual env).\n\t\n  More info: https://github.com/IanHarvey/bluepy/issues/158\n  \n  * Other errors\n  \n  If you run into problems during devices listing or connect, try to follow\n  this procedure to ensure your Bluetooth interface works correctly :\n  [How to use manually with Gatttool page](https://github.com/Betree/pyMagicBlue/wiki/How-to-use-manually-with-Gatttool)\n\n## Usage\n\n### Python API\n\nCheck the [API documentation](http://magicblue.readthedocs.io/en/latest/)\n\n### From shell\nScript must be run as root.\n\nYou can always specify which bluetooth adapter (default: hci0) you want to use by specifying it with the -a option.\n\n#### Using the interactive shell\nJust launch magicblueshell as root user :\n\n```bash\n$ sudo magicblueshell\nMagic Blue interactive shell v0.3.0\nType \"help\" for a list of available commands\n\u003e help\n ----------------------------\n| List of available commands |\n ----------------------------\nCOMMAND         PARAMETERS                    DETAILS\n-------         ----------                    -------\nhelp                                          Show this help\nlist_devices                                  List Bluetooth LE devices in range\nls              //                            //\nlist_effects                                  List available effects\nconnect         mac_address or ID             Connect to light bulb\ndisconnect                                    Disconnect from current light bulb\nset_color       name or hexadecimal value     Change bulb's color\nset_warm_light  intensity[0.0-1.0]            Set warm light\nset_effect      effect_name speed[1-20]       Set an effect\nturn            on|off                        Turn on / off the bulb\nread            name|device_info|date_time    Read device_info/datetime from the bulb\nexit                                          Exit the script\n\u003e ls\nListing Bluetooth LE devices in range for 5 minutes.Press CTRL+C to stop searching.\nID    Name                           Mac address \n--    ----                           ----------- \n1     LEDBLE-1D433903                c7:17:1d:43:39:03\n^C\n\n\u003e connect 1\nINFO:magicblue.magicblueshell:Connected\n\u003e set_color red\n\u003e exit\nBye !\n```\n\n#### Passing command as an option\nScript can also be used by command line (for example to include it in custom shell scripts):\n\n```\nusage: magicblueshell [-h] [-l LIST_COMMANDS] [-c COMMAND] [-m MAC_ADDRESS]\n                      [-a BLUETOOTH_ADAPTER] [-b BULB_VERSION]\n\nPython tool to control MagicBlue bulbs over Bluetooth\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -l LIST_COMMANDS, --list_commands LIST_COMMANDS\n                        List available commands\n  -c COMMAND, --command COMMAND\n                        Command to execute\n  -m MAC_ADDRESS, --mac_address MAC_ADDRESS\n                        Device mac address. Must be set if command given in -c\n                        needs you to be connected\n  -a BLUETOOTH_ADAPTER, --bluetooth_adapter BLUETOOTH_ADAPTER\n                        Bluetooth adapter name as listed by hciconfig\n  -b BULB_VERSION, --bulb-version BULB_VERSION\n                        Bulb version as displayed in the official app\n\n```\n                     \nSo if you want to change the color of bulb with mac address \"C7:17:1D:43:39:03\", just run :\n    \n\u003e sudo magicblueshell -c 'set_color red' -m C7:17:1D:43:39:03\n\n\n## Contributing\n\nTo contribute to this repo, start with [CONTRIBUTING.md](https://github.com/Betree/magicblue/blob/staging/CONTRIBUTING.md)\nthen check [open issues](https://github.com/Betree/magicblue/issues)\n\nThe protocol isn't fully retro-engineered but\n[Characteristics list page](https://github.com/Betree/pyMagicBlue/wiki/Characteristics-list) and\n[How to use manually with Gatttool page](https://github.com/Betree/pyMagicBlue/wiki/How-to-use-manually-with-Gatttool)\nshould give you enough details to start working on your own implementation if you need to port this for another\nlanguage / platform.\nOn the [research/bluetooth branch](https://github.com/Betree/pyMagicBlue/tree/research/bluetooth)\nyou'll also find capture of bluetooth packets exchanged between Android and the bulb (open hci_capture.log with Wireshark).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetree%2Fmagicblue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbetree%2Fmagicblue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetree%2Fmagicblue/lists"}