esphome-docs/components/esp32_ble_beacon.rst

81 lines
3.3 KiB
ReStructuredText
Raw Normal View History

2018-06-13 22:38:49 +02:00
ESP32 Bluetooth Low Energy Beacon
=================================
2018-11-14 22:12:27 +01:00
.. seo::
:description: Instructions for setting up Bluetooth Low Energy iBeacons using the BLE feature on ESP32s.
:image: bluetooth.svg
2018-11-14 22:12:27 +01:00
2018-06-13 22:38:49 +02:00
The ``esp32_ble_beacon`` component creates a Bluetooth Low Energy Beacon with your ESP32 device.
Beacons are BLE devices that repeatedly just send out a pre-defined packet of data. This packet
can then be received by devices like smartphones and can then be used to track a phone's location.
.. code-block:: yaml
2018-06-13 22:38:49 +02:00
# Example configuration entry
esp32_ble_beacon:
type: iBeacon
uuid: 'c29ce823-e67a-4e71-bff2-abaa32e77a98'
Configuration variables:
------------------------
- **type** (**Required**): The type of beacon to create, currently only supports ``iBeacon``.
- **uuid** (**Required**): The `universally unique identifier <https://en.wikipedia.org/wiki/Universally_unique_identifier>`__
to identify the beacon.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for code generation.
Advanced options:
- **major** (*Optional*, int): The iBeacon major identifier of this beacon. Usually used to
2018-06-13 22:38:49 +02:00
group beacons, for example for grouping all beacons in the same building, but has no effect if
the BLE receiver doesn't use it. Defaults to ``10167``.
- **minor** (*Optional*, int): The iBeacon minor identifier of this beacon. Usually used to
2018-06-13 22:38:49 +02:00
identify beacons within an iBeacon group. Defaults to ``61958``.
Setting Up
----------
2019-02-16 23:25:23 +01:00
First, you'll need to set up the configuration for ESPHome. Just copy the configuration above and
change the UUID to something unique. For example, you can copy this randomly generated UUID:
2018-06-13 22:38:49 +02:00
.. raw:: html
2019-01-06 18:56:14 +01:00
<input type="text" id="ble-uuid" onclick="this.focus();this.select()" style="width: 240px;" readonly="readonly">
2018-06-13 22:38:49 +02:00
<script>
// https://stackoverflow.com/a/105074/8924614
function guid() {
function s4() {
return Math.floor((1 + Math.random()) * 0x10000)
.toString(16)
.substring(1);
}
return s4() + s4() + '-' + s4() + '-' + s4() + '-' + s4() + '-' + s4() + s4() + s4();
}
document.getElementById("ble-uuid").value = guid();
</script>
2019-02-16 23:25:23 +01:00
Then, just compile and flash the ESP32.
2018-06-13 22:38:49 +02:00
When everything is set up correctly, you should see a show up using your iBeacon scanner of choice. On iPhones,
2020-05-10 21:27:59 +02:00
this should already work from the Bluetooth screen (not tested), on Android, you will need to use an app like
2018-06-13 22:38:49 +02:00
`"Beacon Scanner" <https://play.google.com/store/apps/details?id=com.bridou_n.beaconscanner>`__ by Nicolas Bridoux.
For using these beacons to track the location of your phone, you will need to use another app. For example, I used
`this guide by the owntracks <https://owntracks.org/booklet/features/beacons/>`__ app to let my Home Automation system
2019-11-20 13:49:15 +01:00
know when I'm home or away. Another nice Android app is `Beacon MQTT <https://turbo-lab.github.io/android-beacon-mqtt/>`__.
It can work with multiple beacons simultaneously.
2018-06-13 22:38:49 +02:00
.. figure:: images/esp32_ble_beacon-ibeacon.png
:align: center
:width: 75.0%
See Also
--------
2019-05-12 22:44:59 +02:00
- :doc:`esp32_ble_tracker`
- :doc:`binary_sensor/ble_presence`
2019-05-12 22:44:59 +02:00
- :apiref:`esp32_ble_beacon/esp32_ble_beacon.h`
2018-08-24 22:44:01 +02:00
- `ESP32 BLE for Arduino <https://github.com/nkolban/ESP32_BLE_Arduino>`__ by `Neil Kolban <https://github.com/nkolban>`__.
- :ghedit:`Edit`