[bridge] New component and cdc_acm_uart platform (#11689)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: J. Nick Koston <nick@koston.org>

tests/component_tests/cdc_acm_uart/test_init.py

@@ -0,0 +1,154 @@
+"""Tests for the bridge cdc_acm_uart platform's final validation."""
+
+import pytest
+
+from esphome import config_validation as cv
+from esphome.components.cdc_acm_uart import bridge
+from esphome.components.cdc_acm_uart.bridge import CONF_USB_CDC_ACM_ID
+from esphome.config import Config
+from esphome.const import CONF_DEBUG, CONF_ID, CONF_UART_ID, PlatformFramework
+from esphome.core import ID
+from esphome.types import ConfigType
+from tests.component_tests.types import SetCoreConfigCallable
+
+_final_validate = bridge._final_validate
+
+
+def _set_esp32_s3(set_core_config: SetCoreConfigCallable, **kwargs) -> None:
+    from esphome.components.esp32 import KEY_VARIANT, VARIANT_ESP32S3
+
+    set_core_config(
+        PlatformFramework.ESP32_IDF,
+        platform_data={KEY_VARIANT: VARIANT_ESP32S3},
+        **kwargs,
+    )
+
+
+def _full_config(uarts: list[ConfigType] | None = None, **domains) -> Config:
+    """A full config declaring uart_0 and uart_1 (plus any extra entries), as the ID
+    pass leaves it, so the debug check can resolve a uart_id to its declaration."""
+    uarts = uarts or [{CONF_ID: ID("uart_0")}, {CONF_ID: ID("uart_1")}]
+    full = Config()
+    full["uart"] = uarts
+    for index, uart_conf in enumerate(uarts):
+        full.declare_ids.append((uart_conf[CONF_ID], ["uart", index, CONF_ID]))
+    full.update(domains)
+    return full
+
+
+def _bridge_config(uart_id: str, cdc_id: str) -> dict:
+    return {CONF_UART_ID: ID(uart_id), CONF_USB_CDC_ACM_ID: ID(cdc_id)}
+
+
+def test_accepts_distinct_uart_and_cdc_interfaces(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    _set_esp32_s3(set_core_config, full_config=_full_config())
+    _final_validate(_bridge_config("uart_0", "cdc_acm_1"))
+    _final_validate(_bridge_config("uart_1", "cdc_acm_2"))
+
+
+def test_rejects_two_bridges_sharing_a_uart(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    _set_esp32_s3(set_core_config, full_config=_full_config())
+    _final_validate(_bridge_config("uart_0", "cdc_acm_1"))
+    with pytest.raises(cv.Invalid, match="already bridged"):
+        _final_validate(_bridge_config("uart_0", "cdc_acm_2"))
+
+
+def test_rejects_two_bridges_sharing_a_cdc_interface(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    _set_esp32_s3(set_core_config, full_config=_full_config())
+    _final_validate(_bridge_config("uart_0", "cdc_acm_1"))
+    with pytest.raises(cv.Invalid, match="already bridged"):
+        _final_validate(_bridge_config("uart_1", "cdc_acm_1"))
+
+
+def test_rejects_uart_shared_with_another_component(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    _set_esp32_s3(
+        set_core_config,
+        full_config=_full_config(
+            sensor=[{"platform": "pzemac", CONF_UART_ID: ID("uart_0")}],
+        ),
+    )
+    with pytest.raises(cv.Invalid, match="exclusive"):
+        _final_validate(_bridge_config("uart_0", "cdc_acm_1"))
+
+
+def test_rejects_cdc_interface_shared_with_another_component(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    # The CDC instance is itself a uart::UARTComponent, so other components can bind
+    # it as a plain UART via uart_id -- that must be rejected just like UART sharing.
+    _set_esp32_s3(
+        set_core_config,
+        full_config=_full_config(
+            sensor=[{"platform": "pzemac", CONF_UART_ID: ID("cdc_acm_1")}],
+        ),
+    )
+    with pytest.raises(cv.Invalid, match="exclusive"):
+        _final_validate(_bridge_config("uart_0", "cdc_acm_1"))
+
+
+def test_rejects_uart_referenced_from_nested_config(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    # References can sit arbitrarily deep, e.g. inside an automation's action list.
+    _set_esp32_s3(
+        set_core_config,
+        full_config=_full_config(
+            binary_sensor=[
+                {
+                    "platform": "gpio",
+                    "on_press": [{"then": [{CONF_UART_ID: ID("uart_0")}]}],
+                }
+            ],
+        ),
+    )
+    with pytest.raises(cv.Invalid, match="exclusive"):
+        _final_validate(_bridge_config("uart_0", "cdc_acm_1"))
+
+
+def test_ignores_other_components_on_other_uarts(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    _set_esp32_s3(
+        set_core_config,
+        full_config=_full_config(
+            sensor=[{"platform": "pzemac", CONF_UART_ID: ID("uart_1")}],
+            # The bridge domain itself is skipped: this bridge's own entry (and any
+            # bridge-vs-bridge sharing, which the seen-set already rejects) must not
+            # trip the exclusivity scan.
+            bridge=[_bridge_config("uart_0", "cdc_acm_1")],
+        ),
+    )
+    _final_validate(_bridge_config("uart_0", "cdc_acm_1"))
+
+
+def test_rejects_debug_on_bridged_uart(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    # The bridge talks to the IDF driver directly, so the uart debugger would see
+    # nothing and its dummy_receiver would steal RX bytes.
+    _set_esp32_s3(
+        set_core_config,
+        full_config=_full_config(uarts=[{CONF_ID: ID("uart_0"), CONF_DEBUG: {}}]),
+    )
+    with pytest.raises(cv.Invalid, match="debug"):
+        _final_validate(_bridge_config("uart_0", "cdc_acm_1"))
+
+
+def test_allows_debug_on_other_uart(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    _set_esp32_s3(
+        set_core_config,
+        full_config=_full_config(
+            uarts=[{CONF_ID: ID("uart_0")}, {CONF_ID: ID("uart_1"), CONF_DEBUG: {}}]
+        ),
+    )
+    _final_validate(_bridge_config("uart_0", "cdc_acm_1"))

tests/component_tests/conftest.py

@@ -60,7 +60,7 @@ def reset_core() -> Generator[None]:
 @pytest.fixture(autouse=True)
 def reset_full_config() -> Generator[None]:
     """Give each test a clean final-validate config and restore it after."""
-    token = final_validate.full_config.set({})
+    token = final_validate.full_config.set(Config())
     yield
     final_validate.full_config.reset(token)
 
@@ -75,7 +75,7 @@ def set_core_config() -> Generator[SetCoreConfigCallable]:
         *,
         core_data: ConfigType | None = None,
         platform_data: ConfigType | None = None,
-        full_config: dict[str, ConfigType] | None = None,
+        full_config: dict[str, ConfigType] | Config | None = None,
     ) -> None:
         platform, framework = platform_framework.value
 
@@ -94,7 +94,12 @@ def set_core_config() -> Generator[SetCoreConfigCallable]:
             CORE.data[platform.value] = platform_data
 
         config.path_context.set([])
-        final_validate.full_config.set(full_config or Config())
+        # Production always installs a Config (a FinalValidateConfig), never a plain dict.
+        if not isinstance(full_config, Config):
+            full = Config()
+            full.update(full_config or {})
+            full_config = full
+        final_validate.full_config.set(full_config)
 
     yield setter
 

tests/component_tests/types.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from typing import Protocol
 
+from esphome.config import Config
 from esphome.const import PlatformFramework
 from esphome.types import ConfigType
 
@@ -18,5 +19,5 @@ class SetCoreConfigCallable(Protocol):
         *,
         core_data: ConfigType | None = None,
         platform_data: ConfigType | None = None,
-        full_config: dict[str, ConfigType] | None = None,
+        full_config: dict[str, ConfigType] | Config | None = None,
     ) -> None: ...

tests/components/cdc_acm_uart/common.yaml

@@ -0,0 +1,18 @@
+tinyusb:
+  id: tinyusb_test
+  usb_lang_id: 0x0123
+  usb_manufacturer_str: ESPHomeTestManufacturer
+  usb_product_id: 0x1234
+  usb_product_str: ESPHomeTestProduct
+  usb_serial_str: ESPHomeTestSerialNumber
+  usb_vendor_id: 0x2345
+
+uart:
+  - id: uart_0
+    tx_pin: 14
+    rx_pin: 13
+    baud_rate: 115200
+
+usb_cdc_acm:
+  interfaces:
+    - id: cdc_acm_1

tests/components/cdc_acm_uart/common_dual.yaml

@@ -0,0 +1,12 @@
+# Second UART/CDC pair for a two-bridge setup. Kept out of common.yaml because the
+# ESP32-S2 has only two UART controllers and the logger occupies one, so a second
+# uart there would fail at runtime.
+uart:
+  - id: uart_1
+    tx_pin: 15
+    rx_pin: 16
+    baud_rate: 115200
+
+usb_cdc_acm:
+  interfaces:
+    - id: cdc_acm_2

tests/components/cdc_acm_uart/test.esp32-p4-idf.yaml

@@ -0,0 +1,15 @@
+packages:
+  cdc_acm_uart: !include common.yaml
+  cdc_acm_uart_dual: !include common_dual.yaml
+
+bridge:
+  - platform: cdc_acm_uart
+    uart_id: uart_0
+    usb_cdc_acm_id: cdc_acm_1
+    dtr_pin: 40
+    rts_pin: 41
+  - platform: cdc_acm_uart
+    uart_id: uart_1
+    usb_cdc_acm_id: cdc_acm_2
+    dtr_pin: 20
+    rts_pin: 21

tests/components/cdc_acm_uart/test.esp32-s2-idf.yaml

@@ -0,0 +1,14 @@
+# ESP32-S2 has no USB_SERIAL_JTAG, so the logger defaults to USB_CDC, which shares
+# the USB OTG peripheral with tinyusb. Use a hardware UART for logging instead.
+logger:
+  hardware_uart: UART0
+
+packages:
+  cdc_acm_uart: !include common.yaml
+
+bridge:
+  - platform: cdc_acm_uart
+    uart_id: uart_0
+    usb_cdc_acm_id: cdc_acm_1
+    dtr_pin: 40
+    rts_pin: 41

tests/components/cdc_acm_uart/test.esp32-s3-idf.yaml

@@ -0,0 +1,17 @@
+packages:
+  cdc_acm_uart: !include common.yaml
+  cdc_acm_uart_dual: !include common_dual.yaml
+
+bridge:
+  - platform: cdc_acm_uart
+    uart_id: uart_0
+    usb_cdc_acm_id: cdc_acm_1
+    dtr_pin: 40
+    rts_pin: 41
+  - platform: cdc_acm_uart
+    uart_id: uart_1
+    usb_cdc_acm_id: cdc_acm_2
+    # GPIO19/20 are USB D-/D+ on the S3 (which the CDC side itself uses); use
+    # unrelated free pins here.
+    dtr_pin: 17
+    rts_pin: 18