Bluetooth low energy (BLE) tracker for ESP32

Overview

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

  1. Using VSCode and PlatformIO
  1. 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
  • 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.

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.

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

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
Comments
  • Online/offline status string customization

    Online/offline status string customization

    Would be nice if we could set custom string for online/offline status. Most of mqtt services I use are having online/offline string as status message, which looks unified in home assistant entities card for quick overview.

    enhancement question 
    opened by Goodwillson 13
  • automatic discovery

    automatic discovery

    How about, as the title says, automatic discovery? This would enable the end-user to simply skip the manual configuration of device trackers in HA. Documentation: https://www.home-assistant.io/integrations/device_tracker.mqtt/#discovery-schema

    enhancement 
    opened by leonardpitzu 13
  • [FR:] JSON out  & MQTT /status

    [FR:] JSON out & MQTT /status

    the detailed status is send as JSON over MQTT, but the message "present/away" is not.

    i request all JSON, because its more likely . and better for node-red.

    also

    would like another topic to simply filter on in node red would let me easily filter for all rssi

    💚 /blecker/status/1234id...

    🟥 (instead of /blecker/1234id.../status)

    image

    enhancement 
    opened by ozett 12
  • Some settings form fields are not pre-populated by saved settings values

    Some settings form fields are not pre-populated by saved settings values

    Its quite annoying thing when you fiddle with settings and still have to enter over again many values. Namely mqtt password, both presence strings, observed devices list, autodiscovery prefix, reboot after hours...from what I have used so far.

    bug 
    opened by Goodwillson 7
  • Upload binary from the browser

    Upload binary from the browser

    To make the installation easier create a website that helps to flash your ESP32 device More information: https://esphome.github.io/esp-web-tools/

    This feature won't change any code in the repository here.

    enhancement 
    opened by redakker 7
  • Send MQTT message just about the observed devices

    Send MQTT message just about the observed devices

    Currently, all device presence is sent in MQTT. Send present status just about devices which are mentioned in the Observed devices in the web interface.

    enhancement 
    opened by redakker 7
  • Improvement idea

    Improvement idea

    Hello

    After a week of use I realize that it would be interesting to have in the advanced menu of the graphical interface the possibility of changing

    • the duration of the scan
    • interval scan time
    • the timeout (when the device is no longer there)

    This allows each user to be able to adjust as they wish without having to compile the project each time, so it would allow to have a very open project :)

    Do you think this and feasible?

    enhancement 
    opened by Hydci 5
  • Only send stats mac save

    Only send stats mac save

    Hello to start super job works perfectly :) I have a little question it would be interesting to have an option to send the status that for the devices to record by watching it sends to mqtt all the devices present not only those including the Mac and record

    question 
    opened by Hydci 5
  • Observed devices

    Observed devices

    I noticed that "home" status message for observed device is not sent after reboot (message is sent just for "not home" devices). I guess it should be updated on each reboot also, as retained message could be flushed from broker cache after broker reboot when database is not set as persistent (saved to disk).

    enhancement 
    opened by Goodwillson 4
  • Compile the version into the binary

    Compile the version into the binary

    Currently, the web frontend displays v-orig for version if you upload the firmware directly. It displays the version if it was uploaded by OTA. Compile the version for each binary then it will display the current version always

    bug enhancement 
    opened by redakker 4
  • create some logs

    create some logs

    I really like the idea to have a BLE-Tracker for presence within HomeAssistant. But I didn't get it to work. I think everything is configured correctly. I do not get any MQTT message. I track it with MQTT Explorer. Does the system itselves also send messages? Or only the presence status? It would be nice to get some log information.

    question 
    opened by kabakakao 4
  • Observed devices status update on reconnect

    Observed devices status update on reconnect

    Shouldnt be sent message about observed devices status on each reconnect to reflect changes which happend during wifi/mqtt server connection downtime? Lets say the wifi/mqtt server downtime takes 10 minutes and some bluetooth devices appear/disappear during this time, we wont know current status untill periodic update which is every hour. At least make this behaviour optional.

    enhancement 
    opened by Goodwillson 0
  • Missing retain flag for online message in subscribeForBaseTopic() function

    Missing retain flag for online message in subscribeForBaseTopic() function

    Online message should have same retain status as last will message, but the flag lastWillRetain is not in the message query on connection (sendMqttMessage(baseTopic, "{"status": "" + statusOn + "", "ip":"" + this -> deviceIPAddress + ""}");)

    When we have working last will, then all should work properly and both online and offline statuses should be retained.

    bug 
    opened by Goodwillson 0
  • subscribeFroBaseTopic not called on reconnect

    subscribeFroBaseTopic not called on reconnect

    After restarting mosquitto, blecker status is set to OFF after reconnect to mqtt server again. Some delay between reconnection tries would be beneficial also, now it hits mosquitto server in loop.

    bug 
    opened by Goodwillson 10
  • Code refactor

    Code refactor

    Bluetooth solution use now a double message (signal message inside). Refactor needs to eliminate the unnecessary double process

    Details: https://github.com/redakker/blecker/blob/f251a02fb7202b85aba9e6c3d802401fd6df3b52/src/bluetooth.cpp#L264

    enhancement 
    opened by redakker 0
Releases(1.08)
Owner
Vörös Ákos
http://www.redphoto.hu/bemutatkozas.html
Vörös Ákos
Allows for multiple SwitchBot buttons and curtains to be controlled via MQTT sent to ESP32. ESP32 will send BLE commands to switchbots and return MQTT responses to the broker. Also supports Meter/Temp Sensor

SwitchBot-MQTT-BLE-ESP32 Switchbot local control using ESP32. no switchbot hub used/required. works with any smarthub that supports MQTT https://githu

null 343 Dec 27, 2022
Arduino Sketch and a Web Bluetooth API for loading models and running inference on the Nano Sense 33 BLE device.

TF4Micro Motion Kit This repo contains the Arduino Sketch and a Web Bluetooth API for loading models and running inference on the device. Install and

Google Creative Lab 52 Nov 24, 2022
ControllaBLE - A retro-controllers to Bluetooth BLE adapter

ControllaBLE - A retro-controllers to Bluetooth BLE adapter This is an ESP32 based controller adapter that outputs as a dual joypad through Bluetooth

null 14 Oct 16, 2022
Exploits the Wii U's bluetooth stack to gain IOSU kernel access via bluetooth.

BluuBomb Exploits the Wii U's bluetooth stack to gain IOSU kernel access via bluetooth. For a more detailed write-up see WRITEUP.md. Not to be confuse

null 99 Dec 17, 2022
Bluetooth Joystick : A wireless joystick with ESP-32 microcontroller and Dual Axis Joystick Module using the Bluetooth connectivity.

BluetoothJoystick Bluetooth Joystick : A wireless joystick with ESP-32 microcontroller and Dual Axis Joystick Module using the Bluetooth connectivity.

null 9 Feb 24, 2022
Control Heidelberg Wallbox Energy Control over WiFi using ESP8266 and configure your own local load management

< scroll down for English version and additional information > wbec WLAN-Anbindung der Heidelberg WallBox Energy Control über ESP8266 Die Heidelberg W

null 95 Jan 3, 2023
ESP32-Skid-Steer - Bruder Catepillar Skid Steer model converted to RC, controlled by an ESP32 with 2 analog joysticks and a receiver that is an ESP32 on the model.

ESP32-Skid-Steer Bruder Catepillar Skid Steer model converted to RC, controlled by an ESP32 with 2 analog joysticks and a receiver that is an ESP32 on

null 6 Oct 27, 2022
A handy little system information monitor using and ESP32 + ILI9488 TFT. Receives data over Serial Bluetooth.

Bluetooth-System-Monitor A handy little system information monitor using and ESP32 + ILI9488 TFT. Receives data over Serial Bluetooth and thus giving

Dustin Watts 32 Dec 22, 2022
Bluetooth Monitor port for the ESP32

ESP32 BT Monitor What is it? This is a (at the moment partial) port of andrewjfreyer/monitor for the popular and super cheap ESP32 boards. For a more

null 38 Dec 28, 2022
Bluetooth Gateway for Phantom Remote Control based on ESP32

Phantom remote control Bluetooth gateway An ESP3232 firmware for the gateway of Phantom remote control, which can push the temperature and humidity data of Phantom remote control through LAN, and also support to control Phantom remote control to send and receive IR data through LAN.

George Zhao 14 Nov 3, 2022
Gesture-Detecting-Macro-Keyboard - Glorified Bluetooth macro keyboard with machine learning (TensorFlow Lite for Microcontrollers) running on an ESP32.

Gesture detection tldr; Glorified Bluetooth macro keyboard with machine learning (TensorFlow Lite for Microcontrollers) running on an ESP32. Main feat

Jakob Krantz 68 Dec 1, 2022
Bluetooth LE Keyboard library for the ESP32 (Arduino IDE compatible)

ESP32 BLE Keyboard library This library allows you to make the ESP32 act as a Bluetooth Keyboard and control what it does. You might also be intereste

null 1.5k Jan 8, 2023
CC2500 Low-Cost Low-Power 2.4 GHz RF Transceiver driver for esp-idf

esp-idf-cc2500 CC2500 Low-Cost Low-Power 2.4 GHz RF Transceiver driver for esp-idf. I ported from this. 2.00mm pitch External Antena 1.27mm pitch PCB

null 3 May 29, 2022
Minimalistic text-based 1-bit music tracker

1bitr 1bitr ("One Bitter" or "The Bitter One") is a minimalistic text-based music tracker. It only supports 1-bit audio playback and encourages users

Serge Zaitsev 58 Dec 25, 2022
Arduino based bicycle movement sensor and GPS tracker

Bike Tracker Background There are actually plenty of bicycle trackers around, so why make your own? Well, so that it works the way you want it… And it

null 22 Aug 21, 2022
Blazingly fast multi-object tracker. Works on 1 (x, y) point per object.

Norfair++ This is a C++ implementation of Techainer's Norfair, which originates from Norfair, a library for real-time 2D object tracking. Its function

Tô Đức (Watson) 6 Jan 26, 2022
A decompilation of the Nintendo Switch version of Captain Toad: Treasure Tracker [v1.3.0].

cttt-decomp A decompilation of the Nintendo Switch version of Captain Toad: Treasure Tracker [v1.3.0]. Build Instructions Obtain a clean copy of a mai

shibbs 14 Aug 17, 2022
Aims to be an accurate C port of Impulse Tracker 2.15's IT replayer (with selectable IT2 sound drivers)

it2play Aims to be an accurate C port of Impulse Tracker 2.15's IT replayer (with selectable IT2 sound drivers). This is a direct port of the original

Olav Sørensen 18 Sep 27, 2022
CC1312R1 Sub-G Solar power asset tracker

Sub-G Solar Power Asset Tracker TOP BOTTOM Sub-G Solar Power Asset Tracker 은 AxDen 의 Aggregator Platform 를 이용하여 온도, 가속도, GPS 위치와 같은 Asset tracking 에 필

AXDEN 6 Dec 6, 2022