mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-01-26 22:21:38 +01:00
Add support for BLE passkey authentication (#2607)
This commit is contained in:
Mat931
GitHub
parent
3032493225
commit
4d8e238f20
@ -21,8 +21,8 @@ but merely manages connections to them for use by other components.
|
||||
ESP32 BLE stack. If you wish to connect more devices, use additional
|
||||
ESP32 boards.
|
||||
|
||||
This component does not (yet) support devices that require
|
||||
security settings (eg connecting with a PIN).
|
||||
This component supports devices that require a 6 digit PIN code
|
||||
for authentication.
|
||||
|
||||
Currently, devices connected with the client cannot be
|
||||
supported by other components based on :doc:`/components/esp32_ble_tracker`
|
||||
@ -53,6 +53,12 @@ Automations:
|
||||
when the client connects to a device. See :ref:`ble_client-on_connect`.
|
||||
- **on_disconnect** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
||||
when the client disconnects from a device. See :ref:`ble_client-on_disconnect`.
|
||||
- **on_passkey_request** (*Optional*, :ref:`Automation <automation>`): An automation to enter
|
||||
the passkey required by the other BLE device. See :ref:`ble_client-on_passkey_request`.
|
||||
- **on_passkey_notification** (*Optional*, :ref:`Automation <automation>`): An automation to
|
||||
display the passkey to the user. See :ref:`ble_client-on_passkey_notification`.
|
||||
- **on_numeric_comparison_request** (*Optional*, :ref:`Automation <automation>`): An automation to
|
||||
compare the passkeys shown on the two BLE devices. See :ref:`ble_client-on_numeric_comparison_request`.
|
||||
|
||||
BLE Client Automation
|
||||
---------------------
|
||||
@ -91,6 +97,64 @@ This automation is triggered when the client disconnects from a BLE device.
|
||||
- lambda: |-
|
||||
ESP_LOGD("ble_client_lambda", "Disconnected from BLE device");
|
||||
|
||||
|
||||
.. _ble_client-on_passkey_request:
|
||||
|
||||
``on_passkey_request``
|
||||
**********************
|
||||
|
||||
This automation is triggered when the BLE device requests a passkey for authentication.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
ble_client:
|
||||
- mac_address: 11:22:33:44:55:66
|
||||
id: ble_itag
|
||||
on_passkey_request:
|
||||
then:
|
||||
- ble_client.passkey_reply:
|
||||
id: ble_itag
|
||||
passkey: 123456
|
||||
|
||||
.. _ble_client-on_passkey_notification:
|
||||
|
||||
``on_passkey_notification``
|
||||
***************************
|
||||
|
||||
This automation is triggered when a passkey is received from the BLE device.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
ble_client:
|
||||
- mac_address: 11:22:33:44:55:66
|
||||
id: ble_itag
|
||||
on_passkey_notification:
|
||||
then:
|
||||
- logger.log:
|
||||
format: "Enter this passkey on your BLE device: %06d"
|
||||
args: [ passkey ]
|
||||
|
||||
.. _ble_client-on_numeric_comparison_request:
|
||||
|
||||
``on_numeric_comparison_request``
|
||||
*********************************
|
||||
|
||||
This automation is triggered when a numeric comparison is requested by the BLE device.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
ble_client:
|
||||
- mac_address: 11:22:33:44:55:66
|
||||
id: ble_itag
|
||||
on_numeric_comparison_request:
|
||||
then:
|
||||
- logger.log:
|
||||
format: "Compare this passkey with the one on your BLE device: %06d"
|
||||
args: [ passkey ]
|
||||
- ble_client.numeric_comparison_reply:
|
||||
id: ble_itag
|
||||
accept: True
|
||||
|
||||
.. _ble_client-ble_write_action:
|
||||
|
||||
``ble_client.ble_write`` Action
|
||||
@ -133,6 +197,75 @@ Configuration variables:
|
||||
- **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to write to.
|
||||
- **value** (**Required**, Array of bytes or :ref:`lambda <config-lambda>`): The value to be written.
|
||||
|
||||
.. _ble_client-passkey_reply_action:
|
||||
|
||||
``ble_client.passkey_reply`` Action
|
||||
-----------------------------------
|
||||
|
||||
This action triggers an authentication attempt using the specified ``passkey``.
|
||||
|
||||
Example usage:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
then:
|
||||
- ble_client.passkey_reply:
|
||||
id: my_ble_client
|
||||
passkey: 123456
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
|
||||
- **passkey** (**Required**, int): The 6-digit passkey.
|
||||
|
||||
.. _ble_client-numeric_comparison_reply_action:
|
||||
|
||||
``ble_client.numeric_comparison_reply`` Action
|
||||
----------------------------------------------
|
||||
|
||||
This action triggers an authentication attempt after a numeric comparison.
|
||||
|
||||
Example usage:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
then:
|
||||
- ble_client.numeric_comparison_reply:
|
||||
id: my_ble_client
|
||||
accept: True
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
|
||||
- **accept** (**Required**, boolean): Should be ``true`` if the passkeys
|
||||
displayed on both BLE devices are matching.
|
||||
|
||||
.. _ble_client-remove_bond_action:
|
||||
|
||||
``ble_client.remove_bond`` Action
|
||||
----------------------------------------------
|
||||
|
||||
This action removes a device from the security database and manages
|
||||
unpairing.
|
||||
|
||||
Example usage:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
ble_client:
|
||||
- mac_address: 11:22:33:44:55:66
|
||||
id: my_ble_client
|
||||
on_connect:
|
||||
then:
|
||||
- ble_client.remove_bond:
|
||||
id: my_ble_client
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
|
||||
|
||||
BLE Overview
|
||||
------------
|
||||
This section gives a brief overview of the Bluetooth LE architecture
|
||||
@ -186,9 +319,8 @@ characteristics and descriptors also provide a small 2-byte
|
||||
Setting Up Devices
|
||||
------------------
|
||||
|
||||
Whilst the component can connect to most BLE devices (that do not
|
||||
require authentication/pin), useful functionality is only obtained
|
||||
through dependent components, such as :doc:`/components/sensor/ble_client`.
|
||||
Whilst the component can connect to most BLE devices, useful functionality
|
||||
is only obtained through dependent components, such as :doc:`/components/sensor/ble_client`.
|
||||
See the documentation for these components for details on setting up
|
||||
specific devices.
|
||||
|
||||
@ -247,6 +379,78 @@ The discovered services can then be used to enable and configure other
|
||||
ESPHome components, for example Service UUID 0xFFE0 is used for iTag style
|
||||
keychain button events, used by the :doc:`/components/sensor/ble_client` component.
|
||||
|
||||
Passkey examples
|
||||
----------------
|
||||
|
||||
Secure connection with a fixed passkey:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
esp32_ble:
|
||||
io_capability: keyboard_only
|
||||
|
||||
esp32_ble_tracker:
|
||||
|
||||
ble_client:
|
||||
- mac_address: A4:C1:38:B1:CD:7F
|
||||
id: pvvx_ble_display
|
||||
on_passkey_request:
|
||||
then:
|
||||
- logger.log: "Authenticating with passkey"
|
||||
- ble_client.passkey_reply:
|
||||
id: pvvx_ble_display
|
||||
passkey: 123456
|
||||
|
||||
Secure connection with a dynamically generated passkey:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
api:
|
||||
services:
|
||||
- service: passkey_reply
|
||||
variables:
|
||||
passkey: int
|
||||
then:
|
||||
- logger.log: "Authenticating with passkey"
|
||||
- ble_client.passkey_reply:
|
||||
id: my_ble_client
|
||||
passkey: !lambda return passkey;
|
||||
- service: numeric_comparison_reply
|
||||
variables:
|
||||
accept: bool
|
||||
then:
|
||||
- logger.log: "Authenticating with numeric comparison"
|
||||
- ble_client.numeric_comparison_reply:
|
||||
id: my_ble_client
|
||||
accept: !lambda return accept;
|
||||
|
||||
esp32_ble:
|
||||
io_capability: keyboard_display
|
||||
|
||||
esp32_ble_tracker:
|
||||
|
||||
ble_client:
|
||||
- mac_address: AA:BB:CC:DD:EE:FF
|
||||
id: my_ble_client
|
||||
on_passkey_request:
|
||||
then:
|
||||
- logger.log: "Enter the passkey displayed on your BLE device"
|
||||
- logger.log: " Go to https://my.home-assistant.io/redirect/developer_services/ and select passkey_reply"
|
||||
on_passkey_notification:
|
||||
then:
|
||||
- logger.log:
|
||||
format: "Enter this passkey on your BLE device: %06d"
|
||||
args: [ passkey ]
|
||||
on_numeric_comparison_request:
|
||||
then:
|
||||
- logger.log:
|
||||
format: "Compare this passkey with the one on your BLE device: %06d"
|
||||
args: [ passkey ]
|
||||
- logger.log: " Go to https://my.home-assistant.io/redirect/developer_services/ and select numeric_comparison_reply"
|
||||
on_connect:
|
||||
then:
|
||||
- logger.log: "Connected"
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
|
||||
@ -13,9 +13,18 @@ can run.
|
||||
# Example configuration
|
||||
|
||||
esp32_ble:
|
||||
io_capability: keyboard_only
|
||||
|
||||
Configuration variables:
|
||||
------------------------
|
||||
|
||||
No configuration variables.
|
||||
- **io_capability** (*Optional*, enum): The IO capability of this ESP32, used for securely connecting to other BLE devices. Defaults to ``none``.
|
||||
|
||||
- ``none`` - No IO capability (Connections that require PIN code authentication will fail)
|
||||
- ``keyboard_only`` - Only a keyboard to enter PIN codes (or a fixed PIN code)
|
||||
- ``display_only`` - Only a display to show PIN codes
|
||||
- ``keyboard_display`` - A keyboard and a display
|
||||
- ``display_yes_no`` - A display to show PIN codes and buttons to confirm or deny the connection
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user