- Getting Started
- Home Assistant Configuration
- Trackable Devices
- Release Notes
You’re going to need the following items:
- An ESP32 development board
- A running instance of Home Assistant
- The Atom IDE with the PlatformIO package installed.
- A Bluetooth Low Energy beacon (either iBeacon or EddyStone), or
- An Android phone with a beacon app installed.
Flashing the Hardware
You can get started by cloning this repository to your local machine using git. Alternatively, you can download the zip. To get the code onto your device, thanks to some great work by kylegordon, you can now build and upload using PlatformIO.
Define your settings
Create a copy of the
Settings.h file, and rename it to
Settings_local.h or something similar. Any variation of the name
Settings followed by an underscore will be ignored by git. This will allow you to set your own configuration without the risk of any commits to the repository of sensitive information. It can also be helpful to keep a settings file for each device you will run, as they will differ.
Flashing the device via USB
Open the project folder in Atom, using the
open project option in the PlatformIO Home screen. Modify the settings in the
Settings_local.h file to match your environment. Set the correct port in the
platformio.ini file (or remove the line to use auto-detection), and upload to the board. Open the serial monitor after successful upload to check for success.
Flashing via OTA
It is possible to update the device using “Over the Air” (OTA) updates from the command line interface of PlatformIO. You will need to know the IP address of the device itself (check your router). From the command line, enter the command
platformio run -t upload --upload-port . During the update process, you will see the on-board LED blinking slowly. Once the update has completed, you should see the device reconnect and update its telemetry.
Home Assistant Configuration
See the section on configuring Home Assistant.
See the section on tracking beacons
Generic BLE Devices
Some other devices that advertise as BLE (such as the Mi Flora plant sensors or the Mi Band fitness tracker) can also be tracked, as long as you can scan the device and see its hardware ID. See the section on tracking generic BLE devices.
Tracking Android Phone
Read more here about getting your Android phone configured and tracked.
Unfortunately, Apple does not allow devices to advertise iBeacon data in the background. As I do not own an iPhone, I will not attempt to implement scanning and reporting by device name, but I welcome pull requests.
This depends heavily on the hard work done by a number of people.
- pcbreflux (GitHub) (YouTube) - this code takes heavy inspiration from ESP32_BLE_beaconscan
- Neil Kolban (GitHub) (YouTube) - provided the Bluetooth low enery libraries used
- Marvin Roger (GitHub) - provided the Async MQTT library
- Benoit Blanchon (GitHub) (YouTube) - provided the Arduino JSON library
- Me No Dev (GitHub) - provided the Async TCP library
- Kyle Gordon (GitHub) - wrote the necessary code for PlatformIO support
If you’re having difficulty getting things set up and work properly, check out the troubleshooting section before you open an issue. It will help you determine what information you need to provide to identify and fix what’s gone wrong.
If you’re having difficulty updating your device to the newest version, or you’re just curious, check out the release notes.