[ble_client] Reject descriptor_uuid combined with notify at validation time (#18109)

esphome/components/ble_client/__init__.py

@@ -9,6 +9,7 @@ from esphome.const import (
     CONF_ID,
     CONF_MAC_ADDRESS,
     CONF_NAME,
+    CONF_NOTIFY,
     CONF_ON_CONNECT,
     CONF_ON_DISCONNECT,
     CONF_SERVICE_UUID,
@@ -16,11 +17,46 @@ from esphome.const import (
     CONF_VALUE,
 )
 from esphome.core import ID
+from esphome.types import ConfigType
 
 AUTO_LOAD = ["esp32_ble_client"]
 CODEOWNERS = ["@buxtronix", "@clydebarrow"]
 DEPENDENCIES = ["esp32_ble_tracker"]
 
+CONF_DESCRIPTOR_UUID = "descriptor_uuid"
+CONF_ON_NOTIFY = "on_notify"
+
+
+def validate_descriptor_not_notify(config: ConfigType) -> ConfigType:
+    """Reject descriptor_uuid combined with notify or on_notify.
+
+    BLE descriptors cannot send notifications; only characteristics can, and
+    ESP-IDF has no descriptor variant of esp_ble_gattc_register_for_notify.
+    """
+    if CONF_DESCRIPTOR_UUID in config and (
+        config.get(CONF_NOTIFY) or CONF_ON_NOTIFY in config
+    ):
+        raise cv.Invalid(
+            f"'{CONF_DESCRIPTOR_UUID}' cannot be used with '{CONF_NOTIFY}' or "
+            f"'{CONF_ON_NOTIFY}': BLE descriptors cannot send notifications; remove "
+            f"'{CONF_DESCRIPTOR_UUID}' to receive characteristic notifications, or "
+            f"remove '{CONF_NOTIFY}' and '{CONF_ON_NOTIFY}' to poll the descriptor"
+        )
+    return config
+
+
+def notify_from_on_notify(config: ConfigType) -> ConfigType:
+    """Enable notifications when an on_notify automation is configured.
+
+    The triggers have no registration path of their own; without notify the
+    automation would validate but never fire.
+    """
+    if CONF_ON_NOTIFY in config and not config[CONF_NOTIFY]:
+        config = config.copy()
+        config[CONF_NOTIFY] = True
+    return config
+
+
 ble_client_ns = cg.esphome_ns.namespace("ble_client")
 BLEClient = ble_client_ns.class_("BLEClient", esp32_ble_client.BLEClientBase)
 BLEClientNode = ble_client_ns.class_("BLEClientNode")

esphome/components/ble_client/sensor/__init__.py

@@ -14,13 +14,16 @@ from esphome.const import (
     UNIT_DECIBEL_MILLIWATT,
 )
 
-from .. import ble_client_ns
+from .. import (
+    CONF_DESCRIPTOR_UUID,
+    CONF_ON_NOTIFY,
+    ble_client_ns,
+    notify_from_on_notify,
+    validate_descriptor_not_notify,
+)
 
 DEPENDENCIES = ["ble_client"]
 
-CONF_DESCRIPTOR_UUID = "descriptor_uuid"
-
-CONF_ON_NOTIFY = "on_notify"
 TYPE_CHARACTERISTIC = "characteristic"
 TYPE_RSSI = "rssi"
 
@@ -85,6 +88,8 @@ CONFIG_SCHEMA = cv.All(
         },
         lower=True,
     ),
+    validate_descriptor_not_notify,
+    notify_from_on_notify,
 )
 
 

esphome/components/ble_client/text_sensor/__init__.py

@@ -9,13 +9,16 @@ from esphome.const import (
     CONF_TRIGGER_ID,
 )
 
-from .. import ble_client_ns
+from .. import (
+    CONF_DESCRIPTOR_UUID,
+    CONF_ON_NOTIFY,
+    ble_client_ns,
+    notify_from_on_notify,
+    validate_descriptor_not_notify,
+)
 
 DEPENDENCIES = ["ble_client"]
 
-CONF_DESCRIPTOR_UUID = "descriptor_uuid"
-
-CONF_ON_NOTIFY = "on_notify"
 
 adv_data_t = cg.std_vector.template(cg.uint8)
 adv_data_t_const_ref = adv_data_t.operator("ref").operator("const")
@@ -48,7 +51,9 @@ CONFIG_SCHEMA = cv.All(
         }
     )
     .extend(cv.polling_component_schema("60s"))
-    .extend(ble_client.BLE_CLIENT_SCHEMA)
+    .extend(ble_client.BLE_CLIENT_SCHEMA),
+    validate_descriptor_not_notify,
+    notify_from_on_notify,
 )