From af9abec4f4ba1219abac6af69aaf754e07192006 Mon Sep 17 00:00:00 2001
From: RoboMagus <68224306+RoboMagus@users.noreply.github.com>
Date: Wed, 12 Oct 2022 04:24:00 +0200
Subject: [PATCH] Update docs for ble_client RSSI sensor (#2339)

---
 components/sensor/ble_client.rst | 40 ++++++++++++++++++++++----------
 cookbook/ble_itag.rst            |  7 ++++++
 2 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/components/sensor/ble_client.rst b/components/sensor/ble_client.rst
index d859dcf76..db0683786 100644
--- a/components/sensor/ble_client.rst
+++ b/components/sensor/ble_client.rst
@@ -6,7 +6,7 @@ BLE Client Sensor
     :image: bluetooth.svg
 
 The ``ble_client`` component is a sensor platform that can
-query BLE devices for specific values of service characteristics.
+query BLE devices for RSSI or specific values of service characteristics.
 
 For more information on BLE services and characteristics, see
 :doc:`/components/ble_client`.
@@ -21,6 +21,7 @@ For more information on BLE services and characteristics, see
 
     sensor:
       - platform: ble_client
+        type: characteristic
         ble_client_id: itag_black
         name: "iTag battery level"
         service_uuid: '180f'
@@ -28,20 +29,34 @@ For more information on BLE services and characteristics, see
         icon: 'mdi:battery'
         unit_of_measurement: '%'
 
+      - platform: ble_client
+        type: rssi
+        ble_client_id: itag_black
+        name: "iTag RSSI"
+
 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.
-- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for converting a raw data
-  reading to a sensor value. See :ref:`ble-sensor-lambda` for more information.
-- **notify** (*Optional*, boolean): Instruct the server to send notifications for this
-  characteristic.
-- **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device.
-- All other options from :ref:`Sensor <config-sensor>`.
+- **type** (**Required**): One of ``rssi``, ``characteristic``.
+
+  rssi options:
+
+  - **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+  characteristic options:
+
+  - **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.
+  - **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for converting a raw data
+    reading to a sensor value. See :ref:`ble-sensor-lambda` for more information.
+  - **notify** (*Optional*, boolean): Instruct the server to send notifications for this
+    characteristic.
+  - **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device.
+  - All other options from :ref:`Sensor <config-sensor>`.
 
 Automations:
 
@@ -64,6 +79,7 @@ variable ``x`` of type ``std::vector<uint8_t>``. The function must return a sing
 
     sensor:
       - platform: ble_client
+        type: characteristic
         ble_client_id: t_sensor
         name: "Temperature Sensor 32bit float"
         ...
diff --git a/cookbook/ble_itag.rst b/cookbook/ble_itag.rst
index cbffa953c..a797ad550 100644
--- a/cookbook/ble_itag.rst
+++ b/cookbook/ble_itag.rst
@@ -55,6 +55,7 @@ Configuration example:
     # a notification is received, the corresponding binary_sensor
     # is briefly toggled.
       - platform: ble_client
+        type: characteristic
         ble_client_id: itag_black
         name: "Black iTag btn"
         service_uuid: 'ffe0'
@@ -73,12 +74,18 @@ Configuration example:
     # support this characteristic, you will see 'Unknown' in the
     # HA frontend.
       - platform: ble_client
+        type: characteristic
         ble_client_id: itag_black
         name: "Black iTag Battery"
         service_uuid: '180f'
         characteristic_uuid: '2a19'
         icon: 'mdi:battery'
         unit_of_measurement: '%'
+    # This entry queries polls the RSSI when the tag is connected.
+      - platform: ble_client
+        type: rssi
+        ble_client_id: itag_black
+        name: "Black iTag RSSI"
 
 Explanation
 -----------