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
Issues
  • 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
  • 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
  • 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
  • [FR:] Send RSSI with MQTT

    [FR:] Send RSSI with MQTT

    simple is beautiful, but i want to measure distance. so a feature-request to send not only "on/off) but (configurable?) also the RSSI). simple simple, and still beautiful.

    question 
    opened by ozett 2
  • iOS / Android

    iOS / Android

    Hello,

    im looking for a ESP Solution for tracking iOS and Android Devices. For security reasons its not that easy to detect them. Can your code used for that?

    https://www.room-assistant.io/integrations/bluetooth-low-energy.html#settings

    question 
    opened by corgan2222 2
  • MQTT does not work without authentication

    MQTT does not work without authentication

    I had more quqtions about that. Somebody uses the MQTT server without authentication (username, password) Currently the code prevents it. Change that behaviour and allow to connect MQTT without username and password.

    Workaround: Recompile the code with this change: mqtt.cpp reconnect() function (line 107) remove this statement: if (!String("").equals(server) && !String("").equals(user)) {

    enhancement 
    opened by redakker 1
  • Compilation error. Cannot find WIFI library v1.0.0

    Compilation error. Cannot find WIFI library v1.0.0

    Got error while compiling:

    Library Manager: Installing arduino-libraries/WiFi @ 1.0.0
    Error: Could not find the package with 'arduino-libraries/WiFi @ 1.0.0' requirements for your system 'windows_amd64'
    

    The last version and only one is 1.2.7 https://github.com/arduino-libraries/WiFi/releases

    Changing WiFi lib version to 1.2.7 occurs the error:

    Compiling .pio\build\esp32dev\src\wifi.cpp.o
    In file included from .pio/libdeps/esp32dev/ESP32 BLE Arduino/src/BLEAdvertising.h:15,
                     from .pio/libdeps/esp32dev/ESP32 BLE Arduino/src/BLEServer.h:19,
                     from .pio/libdeps/esp32dev/ESP32 BLE Arduino/src/BLEDevice.h:18,
                     from src/bluetooth.cpp:12:
    .pio/libdeps/esp32dev/ESP32 BLE Arduino/src/FreeRTOS.h:61:28: error: 'ringbuf_type_t' has not been declared
    
    opened by VadimIzmalkov 0
  • 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.07)
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 244 Jun 29, 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 46 Jun 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 13 Dec 1, 2021
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 94 Jun 30, 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 69 Jun 21, 2022
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 5 Feb 4, 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 24 May 28, 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 33 Jun 11, 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 13 Jan 23, 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 63 Jun 19, 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.2k Jul 5, 2022
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 54 Jun 6, 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 20 May 7, 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 13 May 22, 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 17 May 21, 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 3 Feb 22, 2022