{"id":23430151,"url":"https://github.com/softplus/ble_proxy_esphome","last_synced_at":"2025-04-12T21:36:10.874Z","repository":{"id":155417259,"uuid":"440642858","full_name":"softplus/ble_proxy_esphome","owner":"softplus","description":"Bluetooth Low-Energy Xiaomi-specific ESPHome proxy for ESP32 devices. Proxies multiple BTLE devices to MQTT.","archived":false,"fork":false,"pushed_at":"2024-12-20T23:07:39.000Z","size":39,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T15:48:07.631Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softplus.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":"2021-12-21T20:30:56.000Z","updated_at":"2024-12-20T23:07:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"d675ec91-cd36-40aa-9fb8-c2e6d2c71426","html_url":"https://github.com/softplus/ble_proxy_esphome","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softplus%2Fble_proxy_esphome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softplus%2Fble_proxy_esphome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softplus%2Fble_proxy_esphome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softplus%2Fble_proxy_esphome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softplus","download_url":"https://codeload.github.com/softplus/ble_proxy_esphome/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637221,"owners_count":21137531,"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":[],"created_at":"2024-12-23T08:15:59.117Z","updated_at":"2025-04-12T21:36:10.855Z","avatar_url":"https://github.com/softplus.png","language":"C++","readme":"# ble_proxy_esphome\n\nBluetooth Low-Energy Xiaomi-specific ESPHome proxy for ESP32 devices. Proxies multiple BTLE devices to MQTT.\n\nTested with LYWSD03MMC thermometers - they're super-cheap.\n\nLast update 2023-07-02. \nWritten by John Mueller (johnmu.com)\n\n## Goals\n\nBTLE thermometers are cheap, and last a long time on battery. However, they use BTLE to communicate, which doesn't go far (10-15m? YMMV). ESP32 devices are also cheap, they support both BTLE as well as Wifi. This project proxies BTLE to MQTT via Wifi, supporting multiple devices that don't need to be configured individually. Using MQTT also enables basic fault tolerance. \n\nAdd BTLE devices where you need them, add proxies nearby as needed. \n\n## Setup (super-rough)\n\n1. Set up ESPhome \n2. Clone this repo\n3. Flash the ATC firmware on your Xiaomi devices (removes bind keys)\n4. Set up a MQTT server (eg, Home Assistant)\n5. Compile \u0026 run this code on an ESP32\n6. Repeat to place proxy devices in strategic locations\n\nNote that when using the proxy, don't also read the BTLE values directly with Home Assistant (you'll just get duplicated sensors). Don't use the BTLE module there, only use MQTT.\n\n## BTLE Device firmware\n\nI used [pvvx's ATC firmware](https://github.com/pvvx/ATC_MiThermometer). This seems to work well on the Xiaomi Mi / LYWSD03MMC devices I have. \n\nThe simplest way is to navigate to the [flasher page](https://pvvx.github.io/ATC_MiThermometer/TelinkMiFlasher.html) on a smartphone, connect to the BTLE device, flash the firmware, and then configure the firmware to use \"Mi\" connections (this is compatible with all Xiaomi-like software).\n\nDevice lifetime seems to be 12-18 months on a CR2032 battery. Use the default settings with 2.5 seconds interval since ESP32 BTLE isn't that great.\n\n## Proxy setup\n\nI recommend using the default config file to start. Use unique device names for each ESP32 that you use, since these need to use the device name to communicate and for over-the-air updates. \n\nBefore compiling, make a copy of \"secrets-example.yaml\" and call it \"secrets.yaml\". In this file, update the wifi SSID, password, and the MQTT hostname, username, password. \n\nNote: the MQTT communications are over HTTP and not encrypted. We're just sending temperature/humidity, so probably no big deal.\n\n```\nesphome -s name yourdevicename run ble_proxy_default.yaml\n```\n\nThis will compile ESPhome based on the YAML-config file specified, using the device name 'yourdevicename'. I like to number my devices, but call them whatever you want.\n\nThe initial setup must be done with the device connected with a USB cable, afterwards you can update with OTA. \n\nI use a variety of ESP32 dev-boards, they're cheap, use USB, and are pretty small. I hang them from a USB charger with a short cable in out-of-the-way places, or from USB ports of routers, Raspberry-Pi's, etc. \n\n## MQTT\n\nThe proxies publish MQTT data in three places. \n\nA good way to understand the data is to use a MQTT explorer like [MQTT explorer](http://mqtt-explorer.com/). Connect to your MQTT server, and you'll see what's happening.\n\nAll data is published using the name of the ESP32 proxy as well as the MAC address of the BTLE device. You can rename MAC addresses as needed. \n\n### Device measurements\n\nMeasurements are published as:\n\n/ble_proxy/[MAC Addr]/[measurement]/state\n\nFor example:\n\n```\n/ble_proxy/A4:C1:38:AA:BB:CC/battery_level/state\n/ble_proxy/A4:C1:38:AA:BB:CC/temperature/state\n```\n\nRead these values to get the current measurement for each device. \n\n### Proxy status\n\nProxy status information is published under:\n\n/[Proxyname]/seen/[MAC Addr]/\n... in there, it includes:\nname = BTLE device name\nrssi = BTLE RSSI measurement\ntype = PUBLIC\nviewcount = Number times device sent data in last hour\n\nExample:\n\n```\n/btproxy05/seen/A4:C1:38:AA:BB:CC/name\n/btproxy05/seen/A4:C1:38:AA:BB:CC/rssi\n/btproxy05/seen/A4:C1:38:AA:BB:CC/viewcount\n```\n\n### Autodiscover for Home Assistant\n\nFor Home Assistant, the autodiscovery config information is published:\n\n/homeassistant/sensor/ble_proxy/[MAC Addr]__[measurement]\n\nThis looks a bit messy in MQTT but makes sure that all measurements are automatically found in Home Assistant. \n\nExamples:\n\n```\n/homeassistant/sensor/ble_proxy/a4_c1_38_aa_bb_cc__temperature/config\n/homeassistant/sensor/ble_proxy/a4_c1_38_aa_bb_cc__humidity/config\n/homeassistant/sensor/ble_proxy/a4_c1_38_aa_bb_cc__temperature/config\n```\n\n## Advanced configuration\n\nRequirements:\n* mqtt (hostname, username, password)\n* esp32_ble_tracker (no settings)\n\nCommon setup in a YAML file:\n\n```\nsensor:\n  - platform: ble_proxy\n    hostname: ${name}\n    mqtt_client_id: mqtt_client\n```\n\nRequired settings:\n\n* hostname - name of this ESP32 device, used for MQTT connections\n* mqtt_client_id - ID of the MQTT client that you set up\n\nOptional settings:\n\n* auto_reboot_interval\n  Time to automatically reboot the ESP32. Since we track seen BTLE devices, this encourages us not to run out of memory over time. \n\n  Example:\n\n  ```auto_reboot_interval: 6h```\n\n* mac_addresses_renamed\n  MAC addresses are great until you have to swap out a device. With this setting, you can rename devices to us a different name. You can also use this to give BTLE devices an understandable name.\n  Uses YAML lists with strings.\n\n  Examples:\n\n  ```mac_addresses_renamed: \"A4:C1:38:00:11:22=A4:C1:38:AA:BB:CC\"```\n\n  ```\n  mac_addresses_renamed:\n   - \"A4:C1:38:00:11:22=A4:C1:38:AA:BB:CC\"\n   - \"A4:C1:38:00:22:44=GUESTROOM\"\n  ```\n\n* mac_addresses_allowed\n  If you have a lot of BTLE devices and *only* want to proxy a portion of them, specify them like this. Allowed MACs are processed before renames.\n\n  Examples:\n\n  ```mac_addresses_allowed: [\"A4:C1:38:00:11:22\", \"A4:C1:38:00:22:44\"]```\n\n  ```\n  mac_addresses_allowed:\n   - \"A4:C1:38:00:11:22\"\n   - \"A4:C1:38:00:22:44\"\n  ```\n\n* mac_addresses_blocked\n  If you have a lot of BTLE devices and *don't* want to proxy a portion of them, specify them like this. All other devices are proxied. Blocked MACs are processed before renames.\n\n  Examples:\n\n  ```mac_addresses_blocked: [\"A4:C1:38:00:11:22\", \"A4:C1:38:00:22:44\"]```\n\n  ```\n  mac_addresses_blocked:\n   - \"A4:C1:38:00:11:22\"\n   - \"A4:C1:38:00:22:44\"\n  ```\n\n* notify_interval\n  Collects sensor values over this period of time and sends the average value over this time.\n\n  Example:\n  ```notify_interval: 15min```\n\n\n## Supported BTLE devices\n\nTheoretically this supports various Xiaomi BTLE devices. I only have the thermometers. Aliexpress or a local electronics shop is your friend.\n\nYou must remove the bind-keys for this to work (with the previously-mentioned firmware). The device will continue to work as previously without bind-keys, you can use any Xiaomi-supported app to also read the devices.\n\nThis code proxies measurements for:\n\n* temperature\n* humidity\n* battery-level\n* conductivity\n* illuminance\n* moisture\n* tablet\n* \"is active\" (a switch?)\n* \"has motion\" (another switch?)\n* \"is light\" (yet another switch?)\n\n## Updates\n\n* 2021-12-21 - initial commit (has been running for \u003e1 year now)\n* 2023-07-02 - Support ble_enable() and ble_disable()\n* 2023-07-02 - Support notify_interval setting to reduce MQTT spam\n* 2023-07-02 - Send autodiscovery MQTT once per boot\n\n## Done\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftplus%2Fble_proxy_esphome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftplus%2Fble_proxy_esphome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftplus%2Fble_proxy_esphome/lists"}