Add iBeacon presence tracking instructions (#1069)

components/binary_sensor/ble_presence.rst

@@ -26,6 +26,10 @@ Bluetooth Low Energy device.
       - platform: ble_presence
         service_uuid: '11aa'
         name: "ESP32 BLE Tracker Test Service 16 bit"
+      # Presence based on iBeacon UUID
+      - platform: ble_presence
+        ibeacon_uuid: '68586f1e-89c2-11eb-8dcd-0242ac130003'
+        name: "ESP32 BLE Tracker Test Service iBeacon"
 
 .. note::
 
@@ -39,10 +43,19 @@ Configuration variables:
 
 -  **name** (**Required**, string): The name of the binary sensor.
 -  **mac_address** (*Optional*, MAC Address): The MAC address to track for this
-   binary sensor. Either this or ``service_uuid`` has to be present.
+   binary sensor. Note that exactly one of ``mac_address``, ``service_uuid`` or ``ibeacon_uuid``
+   must be present.
 -  **service_uuid** (*Optional*, string): 16 bit, 32 bit, or 128 bit BLE Service UUID
-   which can be tracked if the device randomizes the MAC address. Either
-   this or ``mac_address`` has to be present.
+   which can be tracked if the device randomizes the MAC address. Note that exactly one of
+   ``mac_address``, ``service_uuid`` or ``ibeacon_uuid`` must be present.
+-  **ibeacon_uuid** (*Optional*, string): The `universally unique identifier <https://en.wikipedia.org/wiki/Universally_unique_identifier>`__
+   to identify the beacon that needs to be tracked. Note that exactly one of ``mac_address``,
+   ``service_uuid`` or ``ibeacon_uuid`` must be present.
+-  **ibeacon_major** (*Optional*, integer): The iBeacon major identifier of the beacon that needs
+   to be tracked. Usually used to group beacons, for example for grouping all beacons in the
+   same building.
+-  **ibeacon_minor** (*Optional*, integer): The iBeacon minor identifier of the beacon that needs
+   to be tracked. Usually used to identify beacons within an iBeacon group.
 -  **id** (*Optional*, :ref:`config-id`): Manually specify
    the ID used for code generation.
 -  All other options from :ref:`Binary Sensor <config-binary_sensor>`.
@@ -68,17 +81,41 @@ boot-up. Then, when a BLE device is discovered, you should see messages like
 address type and advertised name. If you don't see these messages, your device is unfortunately
 currently not supported.
 
+.. code-block:: yaml
+
+    # Example configuration entry for finding
+    # Service UUIDs and iBeacon UUIDs and identifiers
+    esp32_ble_tracker:
+
+    logger:
+      level: VERY_VERBOSE
+
+You can increase the :ref:`log level <logger-log_levels>` to ``VERY_VERBOSE`` to review detailed
+data for each discovered BLE device. This will make ESPHome print Service UUIDs, iBeacon UUIDs,
+iBeacon major and minor identifiers, BLE manufacturer data, RSSI and other data useful for
+debugging purposes. Note that this is useful only during set-up and a less verbose log level
+should be specified afterwards.
+
 Please note that devices that show a ``RANDOM`` address type in the logs cannot be used for
-MAC address based tracking, since their MAC-address periodically changes. Instead you can create
-a BLE beacon, set a unique 16 bit, 32 bit or 128 bit Service UUID and track your device based on that.
-Make sure you don't pick a `GATT Service UUID <https://www.bluetooth.com/specifications/gatt/services/>`__,
-otherwise generic services might give you incorrect tracking results.
+MAC address based tracking, since their MAC-address periodically changes. Instead you can:
+
+-  Create a BLE beacon, set a unique 16 bit, 32 bit or 128 bit Service UUID and track your device
+   based on that. Make sure you don't pick a `GATT Service UUID
+   <https://www.bluetooth.com/specifications/gatt/services/>`__, otherwise generic services
+   might give you incorrect tracking results.
+
+-  Create an iBeacon and track it based on its iBeacon UUID. You can also optionally specify
+   major and minor numbers to match if additional filtering is required. ESPHome offers this
+   functionality via the :doc:`ESP32 Bluetooth Low Energy Beacon </components/esp32_ble_beacon>`
+   component. Several iOS and Android applications, including the open source Home Assistant
+   mobile application also provide means to create iBeacons.
 
 
 See Also
 --------
 
 - :doc:`/components/esp32_ble_tracker`
+- :doc:`/components/esp32_ble_beacon`
 - :doc:`/components/binary_sensor/index`
 - :apiref:`ble_presence/ble_presence.h`
 - `ESP32 BLE for Arduino <https://github.com/nkolban/ESP32_BLE_Arduino>`__ by `Neil Kolban <https://github.com/nkolban>`__.

components/esp32_ble_beacon.rst

@@ -74,6 +74,7 @@ See Also
 --------
 
 - :doc:`esp32_ble_tracker`
+- :doc:`binary_sensor/ble_presence`
 - :apiref:`esp32_ble_beacon/esp32_ble_beacon.h`
 - `ESP32 BLE for Arduino <https://github.com/nkolban/ESP32_BLE_Arduino>`__ by `Neil Kolban <https://github.com/nkolban>`__.
 - :ghedit:`Edit`