{"id":19217463,"url":"https://github.com/devbis/ble2mqtt","last_synced_at":"2025-04-06T11:07:48.985Z","repository":{"id":38461043,"uuid":"309096896","full_name":"devbis/ble2mqtt","owner":"devbis","description":"Bluetooth to MQTT bridge, add your bluetooth-capable (including controllable) devices to your smart home","archived":false,"fork":false,"pushed_at":"2024-04-11T09:50:30.000Z","size":1366,"stargazers_count":115,"open_issues_count":12,"forks_count":26,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-04-27T17:02:13.956Z","etag":null,"topics":["ble","bluetooth","ensto","home-assistant","lifecontrol","mqtt","redmond","smarthome","wp6003","xiaomi"],"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/devbis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-01T13:01:48.000Z","updated_at":"2024-04-22T10:31:16.000Z","dependencies_parsed_at":"2023-01-28T17:00:52.589Z","dependency_job_id":"7d1e7265-f9c1-4b83-935f-53f116122ecf","html_url":"https://github.com/devbis/ble2mqtt","commit_stats":{"total_commits":249,"total_committers":7,"mean_commits":35.57142857142857,"dds":"0.048192771084337394","last_synced_commit":"c2f493192f4ed5b8f4266fe36e8e2f1ef87a6e53"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbis%2Fble2mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbis%2Fble2mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbis%2Fble2mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbis%2Fble2mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devbis","download_url":"https://codeload.github.com/devbis/ble2mqtt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247471518,"owners_count":20944158,"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","ensto","home-assistant","lifecontrol","mqtt","redmond","smarthome","wp6003","xiaomi"],"created_at":"2024-11-09T14:22:12.366Z","updated_at":"2025-04-06T11:07:48.970Z","avatar_url":"https://github.com/devbis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BLE2MQTT\n### Control your Bluetooth devices with smart home\n\n![ble2mqtt devices](./ble2mqtt.png)\n\n## Supported devices:\n\n### Any device\n- Any bluetooth device can work as a presence tracker \n  You can provide `\"threshold\"` parameter to the device to set the limit in \n  second when the device is considered away. The default value is 180 seconds.\n\n### Kettles\n- **Redmond RK-G2xxS series (type: redmond_rk_g200)**\n\n  The default key that is used is `\"ffffffffffffffff\"`\n  and can be omitted in the config.\n  In some cases kettles don't accept it. Just use another \n  key in the config file for the device: \n  `\"key\": \"16 random hex numbers\"`\n\n- **Mi Kettle (type: mikettle)**\n\n  Use correct `product_id` for your kettle:\n  - yunmi.kettle.v1: `131`\n  - yunmi.kettle.v2: `275` (default)\n  - yunmi.kettle.v7: `1116`\n\n### Multi-Cookers\n- **Redmond RMC-M225S, RMC-M227S (type: redmond_rmc_m200)**\n\n  Notes about the key parameter you can read above for the \n  Redmond kettles. \n  *Other RMC multi-cookers may need \n  adjustments for the list of available programs, it depends\n  on the device panel.*\n\n### Humidity sensors\n- **Xiaomi MJ_HT_V1 (type: xiaomihtv1)**\n- **Xiaomi LYWSD02MMC (type: xiaomihtv1)**\n- **Xiaomi LYWSD03MMC (type: xiaomilywsd)** (due to the connection to the device on \n  every data fetch, it consumes more battery power. Flashing to the custom\n  firmware is recommended)\n- **Xiaomi LYWSD03MMC with custom ATC firmware (xiaomilywsd_atc)**\n  - supported both atc1441 and pvvx formats\n- **Qingping CGDK2 (type: qingpingCGDK2)**\n- **RuuviTag (type: ruuvitag)**\n- **RuuviTag Pro 2in1 (type: ruuvitag_pro_2in1)**\n- **RuuviTag Pro 3in1 (type: ruuvitag_pro_3in1)**\n- **RuuviTag Pro 4in1 (type: ruuvitag)**\n- **Govee H5074, H5075 (type: govee_ht)**\n\n### Air sensors\n- **Vson WP6003 (type: wp6003)**\n\n### Shades and Blinds\n- **Generic AM43 (type: am43)**\n\n  Manufacturer can be A-OK, Zemismart, etc.\n- **Soma Shades (type: soma_shades)**\n\n### Bulbs\n- **Avea RGBW bulbs (type: avea_rgbw)**\n\n### Dosimeters\n- **Atom Fast (type: atomfast)**\n\n### Heaters\n- **Ensto EPHBEBT10PR, EPHBEBT15PR (type: ensto_thermostat)**\n\n  These devices require [manual pairing](#manual-pairing-in-linux).\n  After the device is paired on the host device, see the logs for the `key` and \n  put it to the config.\n\n  The adapter uses holiday mode to control temperature as thermostat. You cannot \n  use this feature in the official app while ble2mqtt is working.\n\n### Vacuum cleaners\n\n- **Roidmi NEX2 Pro (type: roidmi_cleaner)**\n\n### Battery voltage meters\n\n- **BM2 car battery voltage meter (type: voltage_bm2)**\n\n\n### Plant sensors:\n\n- **LifeControl MCLH-09 (type: mclh09)**\n\n  optionally, polling interval can be configured with `interval` parameter in seconds\n- **Xiaomi Mi Flora (type: miflora)**\n\n  optionally, polling interval can be configured with `interval` parameter in seconds\n\nBy default, a device works in the passive mode without connection by \nlistening to advertisement packets from a device.\nTo use connection to the device provide `\"passive\": false` parameter.\n\n**Supported devices in passive mode:**\n- Xiaomi MJ_HT_V1 (xiaomihtv1)\n- Xiaomi LYWSD03MMC with custom ATC firmware (xiaomilywsd_atc)\n- RuuviTag (ruuvitag/ruuvitag_pro_2in1/ruuvitag_pro_3in1)\n- Govee temperature/humidity sensors (govee_ht)\n- Any device as presence tracker\n\n## Manual pairing in Linux\n\nSome devices (e.g. Ensto heaters) require paired connection to work with it. \nYou need to pair the device with linux machine before using it. \n\nFind out MAC addresses of your devices. Put the device in pairing mode if it is supported.\n\nOpen console and run `bluetoothctl` command. It is a command line tool to work with BLE devices.\nWait for the prompt \n\n```\n[bluetooth]#\n```\n\nPrint a command to enable scanning. Linux must know the device is present before pairing.\n\n```\n[bluetooth]# scan on\n```\n\nWait for MAC address of the device appears in the list of found devices.\nPrint a pairing command (replace MAC address to the one from your device)\n\n```\n[bluetooth]# pair 90:fd:00:00:00:01\n```\n\nOn successful pairing you'll see a message:\n\n```\n[CHG] Device 90:FD:00:00:00:01 Paired: yes\nPairing successful\n```\nYou can proceed with the next configuration steps now.\n\n\n## Selinux issues\n\nIf using SELinux and you are experience issues, see [README.md](selinux/README.md).\n\n### Known issues:\n- *High cpu usage due to underlying library to work with bluetooth*\n\n**Use this software at your own risk.**\n\n## Configuration\n\nDefault config should be located in `/etc/ble2mqtt.json` or \ncan be overridden with `BLE2MQTT_CONFIG` environment variable.\n\nExample run command:\n\n```sh \nBLE2MQTT_CONFIG=./ble2mqtt.json ble2mqtt\n```\n\nThe configuration file is a JSON with the following content:\n\n```json\n{\n    \"mqtt_host\": \"localhost\",\n    \"mqtt_port\": 1883,\n    \"mqtt_user\": \"\",\n    \"mqtt_password\": \"\",\n    \"log_level\": \"INFO\",\n  \n    \"// remove this comment. Set next line to true if you have HA \u003c2024.4\": \"\",\n    \"legacy_color_mode\": false, \n    \"devices\": [\n        {\n            \"address\": \"11:22:33:aa:cc:aa\",\n            \"type\": \"presence\"\n        },\n        {\n            \"address\": \"11:22:33:aa:bb:cc\",\n            \"type\": \"redmond_rk_g200\",\n            \"key\": \"ffffffffffffffff\"\n        },\n        {\n            \"address\": \"11:22:33:aa:bb:c0\",\n            \"type\": \"redmond_rmc_m200\",\n            \"key\": \"ffffffffffffffff\"\n        },\n        {\n            \"address\": \"11:22:33:aa:bb:c1\",\n            \"type\": \"ensto_thermostat\",\n            \"# see logs after pairing and put the key to config\": \"\",\n            \"key\": \"00112233\"\n        },\n        {\n            \"address\": \"11:22:33:aa:bb:cd\",\n            \"type\": \"mikettle\",\n            \"product_id\": 275\n        },\n        {\n            \"address\": \"11:22:33:aa:bb:de\",\n            \"type\": \"am43\"\n        },\n        {\n            \"address\": \"11:22:33:aa:bb:dd\",\n            \"type\": \"xiaomihtv1\",\n            \"interval\": 60\n        },\n        {\n            \"address\": \"11:22:34:aa:bb:dd\",\n            \"type\": \"xiaomihtv1\",\n            \"passive\": false\n        },\n        {\n            \"address\": \"11:22:33:aa:bb:ee\",\n            \"type\": \"xiaomilywsd\"\n        },\n        {\n            \"address\": \"11:22:33:aa:bb:ff\",\n            \"type\": \"xiaomilywsd_atc\",\n            \"interval\": 60\n        },\n        {\n            \"address\": \"11:22:33:aa:aa:aa\",\n            \"type\": \"atomfast\"\n        },\n        {\n            \"address\": \"11:22:33:aa:aa:bb\",\n            \"type\": \"voltage_bm2\"\n        },\n        {\n            \"address\": \"11:22:33:aa:aa:bc\",\n            \"type\": \"mclh09\",\n            \"interval\": 600\n        },\n        {\n            \"address\": \"11:22:33:aa:aa:bd\",\n            \"type\": \"miflora\",\n            \"interval\": 500\n        },\n        {\n            \"address\": \"11:22:33:aa:aa:be\",\n            \"type\": \"ruuvitag\",\n            \"interval\": 60\n        },\n        {\n            \"address\": \"11:22:33:aa:aa:0a\",\n            \"type\": \"roidmi_cleaner\"\n        }\n    ]\n}\n```\n\nYou can omit a line, then default value will be used.\n\nExtra configuration parameters:\n- `\"base_topic\"`- the default value is 'ble2mqtt'\n- `\"mqtt_prefix\"`- a prefix to distinguish ble devices from other instances and\n  programs. The default value is 'b2m_'.\n- `\"hci_adapter\"` - an adapter to use. The default value is \"hci0\"\n- `\"legacy_color_mode\"` - set to true if you have Home Assistant version \u003c 2024.4. For example, if you use HomeAssistant on OpenWrt script.\n\nDevices accept `friendly_name` parameter to replace mac address in device\nnames for Home Assistant.\n\n\n## Systemd unit file to start on boot\n\nPut the following content to the unit file `/etc/systemd/system/ble2mqtt.service`\n\n```\n[Unit]\nDescription=ble2mqtt bridge\n\n[Service]\nType=Simple\nExecStart=/usr/local/bin/ble2mqtt\nUser=ble2mqtt\nGroup=ble2mqtt\nWants=bluetooth.target\n\n[Install]\nWantedBy=multi-user.target\n```\n\nThe user and group should match the owner and group of the configuration file /etc/ble2mqtt.json.\n\nAfterwards you simply have to enable and start the service:\n\n```sh\nsudo systemctl daemon-reload\nsudo systemctl enable ble2mqtt\nsudo systemctl start ble2mqtt\n```\n\n## Installation on OpenWRT\n\n### OpenWRT 23.05 and later\n\nCreate the configuration file in /etc/ble2mqtt.json and\nappend your devices.\n\nExecute the following commands in the terminal:\n\n```sh\nopkg update\nopkg install python3-ble2mqtt\n/etc/init.d/ble2mqtt enable\n/etc/init.d/ble2mqtt start\n```\n\n### OpenWRT 22.03 and earlier\n\nExecute the following commands in the terminal:\n\n```sh\nopkg update\nopkg install python3-pip python3-asyncio\npip3 install \"bleak\u003e=0.11.0\"\npip3 install -U ble2mqtt\n```\n\nCreate the configuration file in /etc/ble2mqtt.json and\nappend your devices.\n\nBluetooth must be turned on.\n\n```sh\nhciconfig hci0 up\n```\n\nRun the service in background\n\n```sh\nble2mqtt 2\u003e /tmp/ble2mqtt.log \u0026\n```\n\nAdd a service script to start:\n\n```sh\ncat \u003c\u003cEOF \u003e /etc/init.d/ble2mqtt\n#!/bin/sh /etc/rc.common\n\nSTART=98\nUSE_PROCD=1\n\nstart_service()\n{\n    procd_open_instance\n\n    procd_set_param env BLE2MQTT_CONFIG=/etc/ble2mqtt.json\n    procd_set_param command /usr/bin/ble2mqtt\n    procd_set_param stdout 1\n    procd_set_param stderr 1\n    procd_close_instance\n}\nEOF\nchmod +x /etc/init.d/ble2mqtt\n/etc/init.d/ble2mqtt enable\n/etc/init.d/ble2mqtt start\n```\n\n## Running on Xiaomi Zigbee Gateway\n\nDue to small CPU power and increasing number of messages from bluetoothd\nit is recommended to do several workarounds:\n\n1. Use passive mode for those sensors for which this is possible. E.g. use\n   custom ATC firmware for lywsd03mmc sensors\n1. Restart `bluetoothd` daily and restart ble2mqtt several times a day to \n   reduce increasing CPU usage. \n   Put the following lines to the `/etc/crontabs/root`\n\n ```\n10 0,7,17 * * * /etc/init.d/ble2mqtt restart\n1 4,14 * * * /etc/init.d/bluetoothd restart\n```\n\n## Running in Container\n\nBuild the image as:\n\n```sh\npodman build -t ble2mqtt:dev .\n```\n\nStart the container and share the config file and DBus for Bluetooth connectivity:\n```sh\npodman run \\\n-d \\\n--net=host \\\n-v $PWD/ble2mqtt.json.sample:/etc/ble2mqtt.json:z \\\n-v /var/run/dbus:/var/run/dbus:z \\\nble2mqtt:dev\n```\n\nInstead of sharing `/var/run/dbus`, you can export `DBUS_SYSTEM_BUS_ADDRESS`.\n\nNOTE: `--net=host` is required as it needs to use the bluetooth interface\n\nNOTE: `podman` is the same as `docker`\n\n\n## Running in Container FULLy\n\n\u003e **ATTENTION:** Make sure `bluez` is not running (or not intalled) on your host. \n\nBuild the image as:\n\n```sh\ndocker build -t ble2mqtt:dev .\n```\n\nStart the container and share the config file:\n```sh\ndocker run \\\n-d \\\n--net=host \\\n--cap-add=NET_ADMIN \\\n-v $PWD/ble2mqtt.json.sample:/etc/ble2mqtt.json:ro \\\nble2mqtt:dev\n```\n\nDocker compose:\n```yaml\nversion: '3.7'\nservices:\n\n  ble2mqtt:\n    image: ble2mqtt:dev\n    build: ./ble2mqtt\n    hostname: ble2mqtt\n    restart: always\n    environment:\n      - TZ=Asia/Yekaterinburg\n    volumes:\n      - ./ble2mqtt/ble2mqtt.json:/etc/ble2mqtt.json:ro\n    network_mode: host\n    cap_add:\n      - NET_ADMIN\n\n```\n\nYou do not need to share `/var/run/dbus`, because `dbus` will start in the container.\n\nNOTE: `--net=host` and `--cap-add=NET_ADMIN` is required as it needs to use and control the bluetooth interface\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevbis%2Fble2mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevbis%2Fble2mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevbis%2Fble2mqtt/lists"}