From 035da429bf56fd9d1d4f84c8b575d8ba00fcb26a Mon Sep 17 00:00:00 2001 From: Borys Pierov Date: Sat, 19 Feb 2022 03:49:25 -0500 Subject: [PATCH] text_sensor for ble_client - docs (#1823) Co-authored-by: Otto Winter --- components/text_sensor/ble_client.rst | 68 +++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 components/text_sensor/ble_client.rst diff --git a/components/text_sensor/ble_client.rst b/components/text_sensor/ble_client.rst new file mode 100644 index 000000000..f3ba0cd37 --- /dev/null +++ b/components/text_sensor/ble_client.rst @@ -0,0 +1,68 @@ +BLE Client Text Sensor +====================== + +.. seo:: + :description: Fetch string values from BLE devices. + :image: bluetooth.svg + +The ``ble_client`` component is a text sensor platform that can +query BLE devices for specific values of service characteristics. + +For more information on BLE services and characteristics, see +:doc:`/components/ble_client`. + +.. code-block:: yaml + + esp32_ble_tracker: + + ble_client: + - mac_address: FF:FF:20:00:0F:15 + id: itag_black + + text_sensor: + - platform: ble_client + ble_client_id: itag_black + name: "Sensor Location" + service_uuid: '180d' + characteristic_uuid: '2a38' + +Configuration variables: +------------------------ + +- **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client. +- **service_uuid** (**Required**, UUID): UUID of the service on the device. +- **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to query. +- **descriptor_uuid** (*Optional*, UUID): UUID of the characteristic's descriptor to query. +- **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components. +- **notify** (*Optional*, boolean): Instruct the server to send notifications for this + characteristic. Defaults to ``false``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device. Defaults to ``60s``. +- All other options from :ref:`Text Sensor `. + +Automations: + +- **on_notify** (*Optional*, :ref:`Automation `): An automation to + perform when a notify message is received from the device. See :ref:`ble_text_sensor-on_notify`. + + +BLE Sensor Automation +--------------------- + +.. _ble_text_sensor-on_notify: + +``on_notify`` +************* + +This automation is triggered when the device/server sends a notify message for +a characteristic. The config variable *notify* must be true or this will have +no effect. +A variable ``x`` of type ``std::string`` is passed to the automation for use in lambdas. + +See Also +-------- + +- :doc:`/components/ble_client` +- :doc:`/components/sensor/ble_client` +- :ref:`sensor-filters` +- :apiref:`ble_text_sensor/ble_text_sensor.h` +- :ghedit:`Edit`