BLEcker

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. 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.

What does it exactly

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

Example

Device MAC is: 12:34:56:ab:cd:ef Send an MQTT message if available:

topic: /blecker/123456abcdef
payload: present

Send an MQTT message if NOT available:

topic: /blecker/123456abcdef
payload: not_present

The 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.

Explanation

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.

Status messages

System sends a detailed status message about the BLE device in every minute: /blecker/[device-mac]/status
The payload is a JSON object structure which contains detailed data like name, rssi, observed, etc. for more possibilities. This function is off by default. It can be changed on a web administration UI.

Upload to ESP32

Using VSCode and PlatformIO

download the source and put it into a folder
install VSCode (https://code.visualstudio.com/download) and PlatformIO inside (https://platformio.org/install/ide?install=vscode)
open the folder of the source code in VSCode
connect your ESP32 to your computer using the USB cable
on the bottom of the window there should be a PlatformIO tool: Platform IO upload
wait while the code is being built and uploaded

Use the ESPtool to upload the prebuilt binary

download the binary here
read how to install and use esptool: https://github.com/espressif/esptool
upload the binary with something like this: esptool.py --chip esp32 image_info blecker.bin

First steps

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

connect to this access point with your smartphone and call the IP address 192.168.4.1 for web administration. You can set your WiFi and MQTT credentials on that administration page. See the details below.

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.

Web configuration

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:

WiFi name: your WiFi network name where the board should connect
Password: password of your WiFi network
MQTT server: your MQTT server address
MQTT port: port of the MQTT connection
Base topic: you can define a prefix for your messages. Example: /home/presence -> /home/presence/blecker/[device-mac] topic will be used
Username: MQTT server username
Password: MQTT server password
Observed devices: you can define your own devices for more accuracy, see the reason above (explanation). Use the mac address without ":" and separate them with ";" Please do not use space characters
Home Assistant Auto discovery: set to "Send" to enable this function
Auto discovery prefix: should be the same what is configured in HA. Default is: homeassistant
Reboot after (hours): device reboot this amount of hours (Value should be integer and greater than 0)
Detailed report: default off. See the details in section Status messages

If you click to the advanced text, you can find more options

Presence string (available): a custom payload to send an available state
Presence string (not available) a custom payload to send a not available state

Update

There are two ways to update your board:

build and upload a new code like the first time (Upload to ESP32)
use web OTA. Web administration interface offers you an update mechanism. You can update your board with a new .bin update file. Browse the update file from your PC and press the upload button. Some minutes later the new firmware will run on your ESP32.

Devices for usage

Tested boards:

ESP32-S (dev board)
ESP32-S2 (dev board)

Possible suitable boards (not tested):

All ESP32 (BLE capable) board

Tested BLE beacons:

Nut Bluetooth Beacon https://www.amazon.com/Nut-F6-world-Smallest-Trackers/dp/B01B0WRC4I/
Long Range (500m) Bluetooth Beacon https://www.amazon.com/programmable-Battery-Bluetooth-eddystone-Technology/dp/B07PT9758D

Possible suitable beacons:

any BLE beacon which can provide a mac address

Please if you tested with any kind of boards/beacons and the test was successful, contact me and I'll update the list

For developers

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.

Build the project

Download the project from github
unzip to a folder
install VS Code
install PlatformIO IDE extension in it
reload VSCode
Open Platform IO
Click to the Platforms tab
Inside the Patforms tab click to Embedded tab
search for "Espressif 32"
install it
open the code folder (File -> Open folder)

open a terminal window in VScode and install "htmlmin", "jsmin" and "cssmin" python package

commands:

             - pip install htmlmin
             
             - pip install cssmin
             
             - pip install jsmin

build the project

Example for Home Assistant

Let's say you have a BLE beacon with this device id (mac address): 12:34:56:ab:cd:ef

Settings on ESP32

Upload the code to your ESP32 and let it run.
Call the ESP32 web interface its IP address (Web frontend should appear)
Set the credentials of your WiFi and MQTT, let the base topic field empty for now
Click to the 'advenced' text and set the presence strings to the following -> home | not_home
put your BLE device address into the Observed devices input field without ":". In tis case: 123456abcdef
Press the submit button (device will reboot)

Settings in Home Assistant

open your configuration file of Home Assistant instance to configure the device tracker module. It is usually in the configuration.yaml file
complete your device tracker configuration with the MQTT presence option. Details: https://www.home-assistant.io/integrations/device_tracker.mqtt/
reboot/reload the HA
At the end of the day you should have something like this

device_tracker:
     - platform: mqtt
       devices:
         redakker: '/blecker/123456abcdef'

after restar HA you will find among states the presence of your BLE device with this name: device_tracker.redakker

Home Assistant MQTT autodiscovery (MQTT Discovery)

Autodiscovery for Home Assistant is implemented with version 1.03. Idea was coming from @leonardpitzu. Thanks! 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.

Release notes

1.01

#2 has been solved: if you define observed devices in the web frontend then just that devices will be monitored and sent messages about their presence
reboot timer introduced: it is actually a workaround. I experienced the ESP32 stuck after some days (network ping is okay, but web frontend and message sending are dead). The administrator can define a reboot time in hours (web frontend). After defined hours the ESP will reboot. It has no effect on presence detection. The format is a single number (integer): "1" or "2". You cannot use float numbers

1.02

#4 has been solved: hostname is propagated for the routers. Easier to determine the IP address in the router using the hostname "blecker"
typo fixes

1.03

#7 feature is implemented: Home assistant auto discovery
typo fixes

Buy me a coffee: https://www.buymeacoffee.com/redakker

Robinsir/blecker