[bk72xx_ble] Fail early with a clear error on non BLE 5.x SoCs (#18406)

esphome/components/bk72xx_ble/__init__.py

@@ -5,11 +5,11 @@ bring-up and the controller BLE address. Consumers (bk72xx_ble_tracker) build
 on this component and contain no SDK calls of their own.
 
 Supported SoCs (BLE 5.x): BK7231N/BK7236 (BLE 5.1), BK7238/BK7252N/BK7253
-(BLE 5.2), and any future BLE-5.x SoC. Capability is detected at compile time,
-not by a chip list: the C++ guards on `__has_include("ble_api.h")` — the Beken
-BLE 5.x public API header, which the LibreTiny beken-72xx builder ships only
-for BLE-5.x SoCs. BK7231T/BK7251/BK7271 (BLE 4.2) and BK7231Q (no BLE) fail
-with a clear #error.
+(BLE 5.2), and any future BLE-5.x SoC. Known non-5.x families are rejected in
+to_code; unknown families are capability-checked at compile time via
+`__has_include("app_ble.h")`, a header only on the BLE 5.x include path
+(ble_api.h ships for every SoC, so it cannot be the probe). A non-5.x build
+fails with a clear #error.
 
 No framework patch is needed: the LibreTiny beken-72xx builder already compiles
 and links the BLE 5.x stack (CFG_SUPPORT_BLE=1 + CFG_BLE_VERSION=BLE_VERSION_5_x;
@@ -21,9 +21,16 @@ import logging
 
 import esphome.codegen as cg
 from esphome.components import libretiny
-from esphome.components.libretiny.const import FAMILY_BK7231N, FAMILY_BK7238
+from esphome.components.libretiny.const import (
+    FAMILY_BK7231N,
+    FAMILY_BK7231Q,
+    FAMILY_BK7231T,
+    FAMILY_BK7238,
+    FAMILY_BK7251,
+)
 import esphome.config_validation as cv
 from esphome.const import CONF_ENABLE_ON_BOOT, CONF_ID
+from esphome.core import EsphomeError
 from esphome.types import ConfigType
 
 DEPENDENCIES = ["bk72xx"]
@@ -50,7 +57,32 @@ CONFIG_SCHEMA = cv.Schema(
 request_scan_listener_slot = cg.slot_counter("BK72XX_BLE_SCAN_LISTENER_COUNT")
 
 
+def _unsupported_family_message(family: str) -> str | None:
+    if family in (FAMILY_BK7231T, FAMILY_BK7251):
+        return (
+            f"bk72xx_ble does not support {family}: this SoC has the Beken BLE 4.2 "
+            "stack; a BLE 5.x SoC such as BK7231N or BK7238 is required"
+        )
+    if family == FAMILY_BK7231Q:
+        return "bk72xx_ble does not support BK7231Q: this SoC has no BLE"
+    return None
+
+
+def _final_validate(config: ConfigType) -> ConfigType:
+    # Warn only: a hard error here would break the validate-only CI fixtures,
+    # which run on a BLE 4.2 board. The hard error is raised at codegen.
+    if msg := _unsupported_family_message(libretiny.get_libretiny_family()):
+        _LOGGER.warning("%s (this configuration cannot compile)", msg)
+    return config
+
+
+FINAL_VALIDATE_SCHEMA = _final_validate
+
+
 async def to_code(config: ConfigType) -> None:
+    if msg := _unsupported_family_message(libretiny.get_libretiny_family()):
+        raise EsphomeError(msg)
+
     var = cg.new_Pvariable(config[CONF_ID])
     await cg.register_component(var, config)
 

esphome/components/bk72xx_ble/bdk_scan.cpp

@@ -10,7 +10,7 @@
 #ifdef USE_BK72XX_BLE
 
 // Same SDK gate as bk72xx_ble.cpp (which carries the explanatory #error).
-#if !defined(CLANG_TIDY) && __has_include("ble_api.h")
+#if !defined(CLANG_TIDY) && __has_include("ble_api.h") && __has_include("app_ble.h")
 
 extern "C" {
 #include "app_ble.h"     // app_ble_env, app_ble_run, app_ble_reset, actv_state_t,
@@ -115,5 +115,5 @@ BdkOpResult bdk_scan_release(uint8_t activity_idx, bool created, int *err_out) {
 
 }  // namespace esphome::bk72xx_ble
 
-#endif  // !CLANG_TIDY && ble_api.h
+#endif  // !CLANG_TIDY && ble_api.h && app_ble.h
 #endif  // USE_BK72XX_BLE

esphome/components/bk72xx_ble/bk72xx_ble.cpp

@@ -34,22 +34,26 @@
 
 // ---------------------------------------------------------------------------
 // SDK-capability gate (not a chip allowlist).
-// This component drives the Beken BLE *5.x* controller via its public API,
-// `ble_api.h`, which the LibreTiny beken-72xx builder ships only for the
-// BLE-5.x SoCs (it selects the `ble_pub` 5.x stack from CFG_BLE_VERSION; the
-// 4.2 SoCs build a different, older API with no ble_api.h). Gate on the header
-// itself so any BLE-5.x Beken chip — present or future — is supported without a
-// hard-coded list, and a non-5.x build fails here with a clear message instead
-// of a cryptic "ble_api.h: No such file or directory".
+// This component drives the Beken BLE *5.x* controller. `ble_api.h` cannot be
+// the probe: it ships for every SoC (driver/include) and merely switches on
+// CFG_BLE_VERSION internally. `app_ble.h` is on the include path only when the
+// LibreTiny beken-72xx builder selects a 5.x stack, so gating on it supports
+// any BLE-5.x chip — present or future — without a hard-coded list, and a
+// non-5.x build fails here with a clear message instead of a cryptic
+// "app_ble.h: No such file or directory".
 // ---------------------------------------------------------------------------
 #if defined(CLANG_TIDY)
 // The clang-tidy environment does not carry the full Beken BDK BLE 5.x API
 // (its ble_api.h variant lacks parts of the 5.x surface), so there is nothing
 // accurate to analyze the SDK calls against — skip the file under analysis.
 #define BK72XX_BLE_NO_SDK
-#elif !__has_include("ble_api.h")
+#elif !__has_include("ble_api.h") || !__has_include("app_ble.h")
+// Also skip the SDK body: #error does not stop the preprocessor, and on a 4.2
+// SoC ble_api.h exists, so without the guard the 5.x symbols would fail one by
+// one and bury this message.
+#define BK72XX_BLE_NO_SDK
 #error \
-    "bk72xx_ble requires a BLE 5.x Beken SDK (ble_api.h). Supported SoCs: BK7231N/BK7236 (BLE 5.1) and BK7238/BK7252N/BK7253 (BLE 5.2). BK7231T/BK7251/BK7271 (BLE 4.2) and BK7231Q (no BLE) are not supported."
+    "bk72xx_ble requires a BLE 5.x Beken SDK (app_ble.h). Supported SoCs: BK7231N/BK7236 (BLE 5.1) and BK7238/BK7252N/BK7253 (BLE 5.2). BK7231T/BK7251/BK7271 (BLE 4.2) and BK7231Q (no BLE) are not supported."
 #endif
 
 #ifndef BK72XX_BLE_NO_SDK

tests/component_tests/bk72xx_ble/config/test_bk7231n.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: bk-family-gate-n
+
+bk72xx:
+  board: cb2s
+
+bk72xx_ble:

tests/component_tests/bk72xx_ble/config/test_bk7231q.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: bk-family-gate-q
+
+bk72xx:
+  board: wa2
+
+bk72xx_ble:

tests/component_tests/bk72xx_ble/config/test_bk7231t.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: bk-family-gate-t
+
+bk72xx:
+  board: generic-bk7231t-qfn32-tuya
+
+bk72xx_ble:

tests/component_tests/bk72xx_ble/config/test_bk7252.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: bk-family-gate-7252
+
+bk72xx:
+  board: generic-bk7252
+
+bk72xx_ble:

tests/component_tests/bk72xx_ble/test_family_gate.py

@@ -0,0 +1,40 @@
+"""The non-5.x family rejection lives in to_code (config validation must stay
+family-agnostic for the validate-only CI fixtures), so codegen is the only
+place it can be pinned."""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+from esphome.core import EsphomeError
+
+
+@pytest.mark.parametrize(
+    ("config_file", "match"),
+    [
+        ("test_bk7231t.yaml", "BK7231T.*BLE 4.2"),
+        ("test_bk7252.yaml", "BK7251.*BLE 4.2"),
+        ("test_bk7231q.yaml", "BK7231Q.*no BLE"),
+    ],
+)
+def test_unsupported_family_rejected(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+    config_file: str,
+    match: str,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    with pytest.raises(EsphomeError, match=match):
+        generate_main(component_config_path(config_file))
+    # Validation itself must not fail (CI validate fixtures run on a BLE 4.2
+    # board), but it warns before codegen raises.
+    assert "cannot compile" in caplog.text
+
+
+def test_ble5_family_generates(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    main_cpp = generate_main(component_config_path("test_bk7231n.yaml"))
+    assert "bk72xx_ble::BK72xxBLE" in main_cpp

tests/component_tests/ble_device_base/config/bk72xx_controller_only.yaml

@@ -2,6 +2,6 @@ esphome:
   name: slotcount-controller
 
 bk72xx:
-  board: generic-bk7252
+  board: cb2s
 
 bk72xx_ble:

tests/component_tests/ble_device_base/config/bk72xx_tracker.yaml

@@ -2,6 +2,6 @@ esphome:
   name: slotcount-tracker
 
 bk72xx:
-  board: generic-bk7252
+  board: cb2s
 
 bk72xx_ble_tracker: