Bluetooth low energy (BLE) tracker for ESP32
This software is written for ESP32 boards to track BLE devices. It can be used for your smart home, scan BLE devices and send their presence to your smart home hub over MQTT. From version 1.04 webhook call is also possible. This is a ready-to-use program, you don't need to modify the code (add your wifi, mqtt credentials whatever). Settings can be done on a nice web interface.
This is a very simple tracker software which creates an MQTT topic for each scanned device mac address (without ":" ) under the base topic and sends the availability as payload. I personally use it for presence detection of family members. Every family member has a BLE device on her/his keyring and smart home can do automations depends on the members' availability. For example: turn on the alarm system if nobody at home.
The default topic is /blecker\ The default payload for available device: present\ The default payload for not available device: not_present
Device MAC is: 12:34:56:ab:cd:ef
Send an MQTT message if available:
topic: /blecker/123456abcdef
payload: presentSend an MQTT message if NOT available:
topic: /blecker/123456abcdef
payload: not_presentThe scan is running in every 2 seconds for 5 seconds and collects the devices into a list. In case of an available device, it sends an MQTT message as available. If the device is gone or can't be scanned after 120 seconds then a "not available" message will be sent out.
The administrator can define an observable device list in a web frontend. These devices will be uploaded to the inside device list. With this mechanism, the "not available" message can be sent out even if the device was not available right after the reboot.
If the device is not available after the system start, "not available" message will be never sent out just in case the BLE device becomes available and will be gone again.
-- System sends a detailed status message about the BLE device periodically: /blecker/[device-mac]/status\ --
BREAKING CHANGE from 1.06
-- System sends a detailed status message about the BLE device: /blecker/status/[device-mac]\ --
{"name":"", "rssi":"", "mac":"123456abcdef", "presence":"present", "observed":"true", "lastSeenMs":"18023"}This message is coming together with the normal availability message. The payload is a JSON object structure which contains detailed data like name, rssi, observed, lastSeenMs, etc. for more possibilities. This function is off by default. It can be changed on a web administration UI.
This feature is available in and over version 1.04. It was implemented under ticket #10.
In every device state change (available -> not available and not available -> available) ESP32 calls the configured webhook url. Configuration field is available on the web administration of the software.
Webhook can be configured for dinamic usage. Wildcards in the URL will be replaced.
Currently available wildcards in the URL:
Example URL:
Autodiscovery for Home Assistant is implemented with version 1.03. Idea was coming from @leonardpitzu. Thanks! Details: https://www.home-assistant.io/integrations/device_tracker.mqtt/#discovery-schema On the web administration page autodiscovery can be set. (See the details in Web Configuration section) In this case Home Assistant automatically can set up the observed deivces. To use this function "Observed devices" field must be set at least with one observed device. Observed devices appears in the state page (Developer tools / States)
Home Assistant and the BLEcker should connected to the same MQTT broker.
Discovery message is sent out every 60 seconds.
Using VSCode and PlatformIO
Use the ESPtool to upload the prebuilt binary
Use the web tool on https://redakker.github.io/blecker/
Be aware the third solution works currently with chrome/chromium engine browsers (Chrome/Edge)
With https://redakker.github.io/blecker/ you can check the device logs too for debugging. Connect your device and in the modal click to "Logs & Console". You might click the "Reset device" to see the logs.
Upload and start the code on ESP32. If there is no configuration yet then it offers an access point. The name of the accesspoint can be found in this file: definitions.h It is "blecker" now.
Later you can find the web administration tool on the IP address which was set to the ESP32. Check it in your own router or WiFi manager tool.
Thanks for the mDNS support, you can find your board in the local area network if you call the URL: http://blecker
or chek the IP address of it with the following command in the commmand line: nslookup blecker
Web configuration UI is available to change some parameters in the system. It can be reached in a browser. Call the IP address of the board. (See the network settings in your router or WiFi manager) The following settings are available:
If you click to the advanced text, you can find more options
There are two ways to update your board:
Tested boards:
Possible suitable boards (not tested):
Tested BLE beacons:
Possible suitable beacons:
Please if you tested with any kind of boards/beacons and the test was successful, contact me and I'll update the list
Under #55 a Github action has been implemented. This action creates a build after each commit to the master branch. With this, you can try the latest and the greatest version of BLEcker. Go the the Actions tab and find the latest successful build with Blecker build (PlatformIO CI). Open it and you can find the build artifact which can be used for updating your ESP32 board.
${{\color{red}\Huge{\textsf{ !!!\ Important\ !!!\ }}}}\$
Be aware these builds could contain not stable solutions.
After some investigation, the project descriptors are made to make the development environment ready automatically in VSCode. All you need to do is wait till VSCode reads the settings files with recommended plugins and then install them. Before the build you need to have inside VSCode:
Prebuild script(s) should install the dependecies automaticaly.
HTML code in /html folder is built to the source code. It is done by PlatformIO build mechanism. (pre_build.py, pre_build_web.py) Python removes the trailing spaces and compile into a PROGMEM variable. To live edit the web UI make a symlink from /html to your webserver folder. If you modify the code then refresh your browser by F5. You should not change the HTML code in a webcontent.h file.
You can use the live server to edit the HTML on-the-fly. Install this plugin: https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer
./vscode/settings.json contains the configuration data for that.
The code contains a lot of logs which send messages over the serial connection (for example in VS Code) and Bluetooth as well. Bluetooth Serial for Android is one of the apps which was tried in this way. Each part of the code has a related log prefix, so it is easy to see which part of the code sends logs.
With https://redakker.github.io/blecker/ you can check the device logs too for debugging. Connect your device and in the modal click to "Logs & Console". You might click the "Reset device" to see the logs.
Let's say you have a BLE beacon with this device id (mac address): 12:34:56:ab:cd:ef
!!! deprecated in the newest HA !!!
device_tracker:
- platform: mqtt
devices:
redakker: '/blecker/123456abcdef'
!!! deprecated in the newest HA !!!
mqtt:
device_tracker:
- name: "redakker"
state_topic: "/blecker/123456abcdef"
- name: "otheruser"
state_topic: "/blecker/987654fedcba"And a big thanks and thumbs up to @Seinuh for beta tests!
Status message now is coming with the normal presence message (availability change). MQTT message topic is also changed
Status message topic from this version is /blecker/status/[device-mac]
Not product logic-related
Buy me a coffee: https://www.buymeacoffee.com/redakker