Add gateway discovery via USB for EnOcean integration (#162756)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Joost Lekkerkerker <joostlek@outlook.com>

homeassistant/components/enocean/config_flow.py

@@ -4,17 +4,23 @@ from typing import Any
 
 import voluptuous as vol
 
+from homeassistant.components import usb
+from homeassistant.components.usb import (
+    human_readable_device_name,
+    usb_unique_id_from_service_info,
+)
 from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
-from homeassistant.const import CONF_DEVICE
+from homeassistant.const import ATTR_MANUFACTURER, CONF_DEVICE, CONF_NAME
 from homeassistant.helpers import config_validation as cv
 from homeassistant.helpers.selector import (
     SelectSelector,
     SelectSelectorConfig,
     SelectSelectorMode,
 )
+from homeassistant.helpers.service_info.usb import UsbServiceInfo
 
 from . import dongle
-from .const import DOMAIN, ERROR_INVALID_DONGLE_PATH, LOGGER
+from .const import DOMAIN, ERROR_INVALID_DONGLE_PATH, LOGGER, MANUFACTURER
 
 MANUAL_SCHEMA = vol.Schema(
     {
@@ -31,8 +37,48 @@ class EnOceanFlowHandler(ConfigFlow, domain=DOMAIN):
 
     def __init__(self) -> None:
         """Initialize the EnOcean config flow."""
-        self.dongle_path = None
-        self.discovery_info = None
+        self.data: dict[str, Any] = {}
+
+    async def async_step_usb(self, discovery_info: UsbServiceInfo) -> ConfigFlowResult:
+        """Handle usb discovery."""
+        unique_id = usb_unique_id_from_service_info(discovery_info)
+
+        await self.async_set_unique_id(unique_id)
+        self._abort_if_unique_id_configured(
+            updates={CONF_DEVICE: discovery_info.device}
+        )
+
+        discovery_info.device = await self.hass.async_add_executor_job(
+            usb.get_serial_by_id, discovery_info.device
+        )
+
+        self.data[CONF_DEVICE] = discovery_info.device
+        self.context["title_placeholders"] = {
+            CONF_NAME: human_readable_device_name(
+                discovery_info.device,
+                discovery_info.serial_number,
+                discovery_info.manufacturer,
+                discovery_info.description,
+                discovery_info.vid,
+                discovery_info.pid,
+            )
+        }
+        return await self.async_step_usb_confirm()
+
+    async def async_step_usb_confirm(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle USB Discovery confirmation."""
+        if user_input is not None:
+            return await self.async_step_manual({CONF_DEVICE: self.data[CONF_DEVICE]})
+        self._set_confirm_only()
+        return self.async_show_form(
+            step_id="usb_confirm",
+            description_placeholders={
+                ATTR_MANUFACTURER: MANUFACTURER,
+                CONF_DEVICE: self.data.get(CONF_DEVICE, ""),
+            },
+        )
 
     async def async_step_import(self, import_data: dict[str, Any]) -> ConfigFlowResult:
         """Import a yaml configuration."""
@@ -104,4 +150,4 @@ class EnOceanFlowHandler(ConfigFlow, domain=DOMAIN):
 
     def create_enocean_entry(self, user_input):
         """Create an entry for the provided configuration."""
-        return self.async_create_entry(title="EnOcean", data=user_input)
+        return self.async_create_entry(title=MANUFACTURER, data=user_input)

homeassistant/components/enocean/const.py

@@ -6,6 +6,8 @@ from homeassistant.const import Platform
 
 DOMAIN = "enocean"
 
+MANUFACTURER = "EnOcean"
+
 ERROR_INVALID_DONGLE_PATH = "invalid_dongle_path"
 
 SIGNAL_RECEIVE_MESSAGE = "enocean.receive_message"

homeassistant/components/enocean/manifest.json

@@ -3,10 +3,19 @@
   "name": "EnOcean",
   "codeowners": [],
   "config_flow": true,
+  "dependencies": ["usb"],
   "documentation": "https://www.home-assistant.io/integrations/enocean",
   "integration_type": "hub",
   "iot_class": "local_push",
   "loggers": ["enocean"],
   "requirements": ["enocean==0.50"],
-  "single_config_entry": true
+  "single_config_entry": true,
+  "usb": [
+    {
+      "description": "*usb 300*",
+      "manufacturer": "*enocean*",
+      "pid": "6001",
+      "vid": "0403"
+    }
+  ]
 }

homeassistant/components/enocean/strings.json

@@ -25,6 +25,9 @@
           "device": "[%key:component::enocean::config::step::detect::data_description::device%]"
         },
         "description": "Enter the path to your EnOcean USB dongle."
+      },
+      "usb_confirm": {
+        "description": "{manufacturer} USB dongle detected at {device}. Do you want to set up this device?"
       }
     }
   },

homeassistant/generated/usb.py

@@ -4,6 +4,13 @@ To update, run python3 -m script.hassfest
 """
 
 USB = [
+    {
+        "description": "*usb 300*",
+        "domain": "enocean",
+        "manufacturer": "*enocean*",
+        "pid": "6001",
+        "vid": "0403",
+    },
     {
         "description": "*zbt-2*",
         "domain": "homeassistant_connect_zbt2",

tests/components/enocean/test_config_flow.py

@@ -1,18 +1,25 @@
 """Tests for EnOcean config flow."""
 
-from unittest.mock import Mock, patch
+from unittest.mock import AsyncMock, Mock, patch
 
-from homeassistant import config_entries
 from homeassistant.components.enocean.config_flow import EnOceanFlowHandler
-from homeassistant.components.enocean.const import DOMAIN
+from homeassistant.components.enocean.const import DOMAIN, MANUFACTURER
+from homeassistant.config_entries import (
+    SOURCE_IMPORT,
+    SOURCE_USB,
+    SOURCE_USER,
+    ConfigEntryState,
+)
 from homeassistant.const import CONF_DEVICE
 from homeassistant.core import HomeAssistant
 from homeassistant.data_entry_flow import FlowResultType
+from homeassistant.helpers.service_info.usb import UsbServiceInfo
 
 from tests.common import MockConfigEntry
 
 DONGLE_VALIDATE_PATH_METHOD = "homeassistant.components.enocean.dongle.validate_path"
 DONGLE_DETECT_METHOD = "homeassistant.components.enocean.dongle.detect"
+SETUP_ENTRY_METHOD = "homeassistant.components.enocean.async_setup_entry"
 
 
 async def test_user_flow_cannot_create_multiple_instances(hass: HomeAssistant) -> None:
@@ -24,7 +31,7 @@ async def test_user_flow_cannot_create_multiple_instances(hass: HomeAssistant) -
 
     with patch(DONGLE_VALIDATE_PATH_METHOD, Mock(return_value=True)):
         result = await hass.config_entries.flow.async_init(
-            DOMAIN, context={"source": config_entries.SOURCE_USER}
+            DOMAIN, context={"source": SOURCE_USER}
         )
 
     assert result["type"] is FlowResultType.ABORT
@@ -37,7 +44,7 @@ async def test_user_flow_with_detected_dongle(hass: HomeAssistant) -> None:
 
     with patch(DONGLE_DETECT_METHOD, Mock(return_value=[FAKE_DONGLE_PATH])):
         result = await hass.config_entries.flow.async_init(
-            DOMAIN, context={"source": config_entries.SOURCE_USER}
+            DOMAIN, context={"source": SOURCE_USER}
         )
 
     assert result["type"] is FlowResultType.FORM
@@ -51,7 +58,7 @@ async def test_user_flow_with_no_detected_dongle(hass: HomeAssistant) -> None:
     """Test the user flow with a detected EnOcean dongle."""
     with patch(DONGLE_DETECT_METHOD, Mock(return_value=[])):
         result = await hass.config_entries.flow.async_init(
-            DOMAIN, context={"source": config_entries.SOURCE_USER}
+            DOMAIN, context={"source": SOURCE_USER}
         )
 
     assert result["type"] is FlowResultType.FORM
@@ -147,7 +154,7 @@ async def test_import_flow_with_valid_path(hass: HomeAssistant) -> None:
     with patch(DONGLE_VALIDATE_PATH_METHOD, Mock(return_value=True)):
         result = await hass.config_entries.flow.async_init(
             DOMAIN,
-            context={"source": config_entries.SOURCE_IMPORT},
+            context={"source": SOURCE_IMPORT},
             data=DATA_TO_IMPORT,
         )
 
@@ -165,9 +172,86 @@ async def test_import_flow_with_invalid_path(hass: HomeAssistant) -> None:
     ):
         result = await hass.config_entries.flow.async_init(
             DOMAIN,
-            context={"source": config_entries.SOURCE_IMPORT},
+            context={"source": SOURCE_IMPORT},
             data=DATA_TO_IMPORT,
         )
 
     assert result["type"] is FlowResultType.ABORT
     assert result["reason"] == "invalid_dongle_path"
+
+
+async def test_usb_discovery(
+    hass: HomeAssistant,
+) -> None:
+    """Test usb discovery success path."""
+    usb_discovery_info = UsbServiceInfo(
+        device="/dev/enocean0",
+        pid="6001",
+        vid="0403",
+        serial_number="1234",
+        description="USB 300",
+        manufacturer="EnOcean GmbH",
+    )
+    device = "/dev/enocean0"
+    # test discovery step
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN,
+        context={"source": SOURCE_USB},
+        data=usb_discovery_info,
+    )
+
+    assert result["type"] is FlowResultType.FORM
+    assert result["step_id"] == "usb_confirm"
+    assert result["errors"] is None
+
+    # test device path
+    with (
+        patch(DONGLE_VALIDATE_PATH_METHOD, Mock(return_value=True)),
+        patch(SETUP_ENTRY_METHOD, AsyncMock(return_value=True)),
+        patch(
+            "homeassistant.components.usb.get_serial_by_id",
+            side_effect=lambda x: x,
+        ),
+    ):
+        result = await hass.config_entries.flow.async_configure(result["flow_id"], {})
+
+    assert result["type"] is FlowResultType.CREATE_ENTRY
+    assert result["title"] == MANUFACTURER
+    assert result["data"] == {"device": device}
+    assert result["context"]["unique_id"] == "0403:6001_1234_EnOcean GmbH_USB 300"
+    assert result["context"]["title_placeholders"] == {
+        "name": "USB 300 - /dev/enocean0, s/n: 1234 - EnOcean GmbH - 0403:6001"
+    }
+    assert result["result"].state is ConfigEntryState.LOADED
+
+
+async def test_usb_discovery_already_configured_updates_path(
+    hass: HomeAssistant,
+) -> None:
+    """Test usb discovery aborts when already configured and updates device path."""
+    # Existing entry with the same unique_id but an old device path
+    existing_entry = MockConfigEntry(
+        domain=DOMAIN,
+        data={CONF_DEVICE: "/dev/enocean-old"},
+        unique_id="0403:6001_1234_EnOcean GmbH_USB 300",
+    )
+    existing_entry.add_to_hass(hass)
+
+    # New USB discovery for the same dongle but with an updated device path
+    usb_discovery_info = UsbServiceInfo(
+        device="/dev/enocean-new",
+        pid="6001",
+        vid="0403",
+        serial_number="1234",
+        description="USB 300",
+        manufacturer="EnOcean GmbH",
+    )
+
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN,
+        context={"source": SOURCE_USB},
+        data=usb_discovery_info,
+    )
+
+    assert result["type"] is FlowResultType.ABORT
+    assert result["reason"] == "single_instance_allowed"