Add WiiM media player integration (#148948)

Co-authored-by: Tao Jiang <tao.jiang@linkplay.com>
Co-authored-by: Erik Montnemery <erik@montnemery.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Paulus Schoutsen <balloob@gmail.com>
Co-authored-by: Joostlek <joostlek@outlook.com>

Author: 6 people

CODEOWNERS

@@ -0,0 +1,128 @@
+"""The WiiM integration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import urlparse
+
+from wiim.controller import WiimController
+from wiim.discovery import async_create_wiim_device
+from wiim.exceptions import WiimDeviceException, WiimRequestException
+
+from homeassistant.const import CONF_HOST, EVENT_HOMEASSISTANT_STOP
+from homeassistant.core import Event, HomeAssistant
+from homeassistant.exceptions import ConfigEntryNotReady
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+from homeassistant.helpers.network import NoURLAvailableError, get_url
+
+from .const import DATA_WIIM, DOMAIN, LOGGER, PLATFORMS, UPNP_PORT, WiimConfigEntry
+from .models import WiimData
+
+DEFAULT_AVAILABILITY_POLLING_INTERVAL = 60
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: WiimConfigEntry) -> bool:
+    """Set up WiiM from a config entry.
+
+    This method owns the device connect/disconnect lifecycle.
+    """
+    LOGGER.debug(
+        "Setting up WiiM entry: %s (UDN: %s, Source: %s)",
+        entry.title,
+        entry.unique_id,
+        entry.source,
+    )
+
+    # This integration maintains shared domain-level state because:
+    # - Multiple config entries can be loaded simultaneously.
+    # - All WiiM devices share a single WiimController instance
+    #   to coordinate network communication and event handling.
+    # - We also maintain a global entity_id -> UDN mapping
+    #   used for cross-entity event routing.
+    #
+    # The domain data must therefore be initialized once and reused
+    # across all config entries.
+    session = async_get_clientsession(hass)
+
+    if DATA_WIIM not in hass.data:
+        hass.data[DATA_WIIM] = WiimData(controller=WiimController(session))
+
+    wiim_domain_data = hass.data[DATA_WIIM]
+    controller = wiim_domain_data.controller
+
+    host = entry.data[CONF_HOST]
+    upnp_location = f"http://{host}:{UPNP_PORT}/description.xml"
+
+    try:
+        base_url = get_url(hass, prefer_external=False)
+    except NoURLAvailableError as err:
+        raise ConfigEntryNotReady("Failed to determine Home Assistant URL") from err
+
+    local_host = urlparse(base_url).hostname
+    if TYPE_CHECKING:
+        assert local_host is not None
+
+    try:
+        wiim_device = await async_create_wiim_device(
+            upnp_location,
+            session,
+            host=host,
+            local_host=local_host,
+            polling_interval=DEFAULT_AVAILABILITY_POLLING_INTERVAL,
+        )
+    except WiimRequestException as err:
+        raise ConfigEntryNotReady(f"HTTP API request failed for {host}: {err}") from err
+    except WiimDeviceException as err:
+        raise ConfigEntryNotReady(f"Device setup failed for {host}: {err}") from err
+
+    await controller.add_device(wiim_device)
+
+    entry.runtime_data = wiim_device
+    LOGGER.info(
+        "WiiM device %s (UDN: %s) linked to HASS. Name: '%s', HTTP: %s, UPnP Location: %s",
+        entry.entry_id,
+        wiim_device.udn,
+        wiim_device.name,
+        host,
+        upnp_location or "N/A",
+    )
+
+    async def _async_shutdown_event_handler(event: Event) -> None:
+        LOGGER.info(
+            "Home Assistant stopping, disconnecting WiiM device: %s",
+            wiim_device.name,
+        )
+        await wiim_device.disconnect()
+
+    entry.async_on_unload(
+        hass.bus.async_listen_once(
+            EVENT_HOMEASSISTANT_STOP, _async_shutdown_event_handler
+        )
+    )
+
+    async def _unload_entry_cleanup():
+        """Cleanup when unloading the config entry.
+
+        Removes the device from the controller and disconnects it.
+        """
+        LOGGER.debug("Running unload cleanup for %s", wiim_device.name)
+        await controller.remove_device(wiim_device.udn)
+        await wiim_device.disconnect()
+
+    entry.async_on_unload(_unload_entry_cleanup)
+
+    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+    return True
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: WiimConfigEntry) -> bool:
+    """Unload a config entry."""
+    LOGGER.info("Unloading WiiM entry: %s (UDN: %s)", entry.title, entry.unique_id)
+
+    if not await hass.config_entries.async_unload_platforms(entry, PLATFORMS):
+        return False
+
+    if not hass.config_entries.async_loaded_entries(DOMAIN):
+        hass.data.pop(DATA_WIIM)
+        LOGGER.info("Last WiiM entry unloaded, cleaning up domain data")
+    return True

homeassistant/components/wiim/__init__.py

@@ -0,0 +1,132 @@
+"""Config flow for WiiM integration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import voluptuous as vol
+from wiim.discovery import async_probe_wiim_device
+from wiim.models import WiimProbeResult
+
+from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
+from homeassistant.const import CONF_HOST
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import HomeAssistantError
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+from homeassistant.helpers.service_info.zeroconf import ZeroconfServiceInfo
+
+from .const import DOMAIN, LOGGER, UPNP_PORT
+
+STEP_USER_DATA_SCHEMA = vol.Schema({vol.Required(CONF_HOST): str})
+
+
+async def _async_probe_wiim_host(hass: HomeAssistant, host: str) -> WiimProbeResult:
+    """Probe the given host and return WiiM device information."""
+    session = async_get_clientsession(hass)
+    location = f"http://{host}:{UPNP_PORT}/description.xml"
+    LOGGER.debug("Validating UPnP device at location: %s", location)
+    try:
+        probe_result = await async_probe_wiim_device(
+            location,
+            session,
+            host=host,
+        )
+    except TimeoutError as err:
+        raise CannotConnect from err
+
+    if probe_result is None:
+        raise CannotConnect
+    return probe_result
+
+
+class WiimConfigFlow(ConfigFlow, domain=DOMAIN):
+    """Handle a config flow for WiiM."""
+
+    _discovered_info: WiimProbeResult | None = None
+
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle the initial step when user adds integration manually."""
+        errors: dict[str, str] = {}
+        if user_input is not None:
+            host = user_input[CONF_HOST]
+            try:
+                device_info = await _async_probe_wiim_host(self.hass, host)
+            except CannotConnect:
+                errors["base"] = "cannot_connect"
+            else:
+                await self.async_set_unique_id(device_info.udn)
+                self._abort_if_unique_id_configured()
+                return self.async_create_entry(
+                    title=device_info.name,
+                    data={
+                        CONF_HOST: device_info.host,
+                    },
+                )
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=self.add_suggested_values_to_schema(
+                STEP_USER_DATA_SCHEMA, user_input
+            ),
+            errors=errors,
+        )
+
+    async def async_step_zeroconf(
+        self, discovery_info: ZeroconfServiceInfo
+    ) -> ConfigFlowResult:
+        """Handle Zeroconf discovery."""
+        LOGGER.debug(
+            "Zeroconf discovery received: Name: %s, Host: %s, Port: %s, Properties: %s",
+            discovery_info.name,
+            discovery_info.host,
+            discovery_info.port,
+            discovery_info.properties,
+        )
+
+        host = discovery_info.host
+        udn_from_txt = discovery_info.properties.get("uuid")
+        if udn_from_txt:
+            await self.async_set_unique_id(udn_from_txt)
+            self._abort_if_unique_id_configured(updates={CONF_HOST: host})
+
+        try:
+            device_info = await _async_probe_wiim_host(self.hass, host)
+        except CannotConnect:
+            return self.async_abort(reason="cannot_connect")
+
+        await self.async_set_unique_id(device_info.udn)
+        self._abort_if_unique_id_configured(updates={CONF_HOST: device_info.host})
+
+        self._discovered_info = device_info
+        self.context["title_placeholders"] = {"name": device_info.name}
+        return await self.async_step_discovery_confirm()
+
+    async def async_step_discovery_confirm(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle user confirmation of discovered device."""
+        discovered_info = self._discovered_info
+        if user_input is not None and discovered_info is not None:
+            return self.async_create_entry(
+                title=discovered_info.name,
+                data={
+                    CONF_HOST: discovered_info.host,
+                },
+            )
+
+        return self.async_show_form(
+            step_id="discovery_confirm",
+            description_placeholders={
+                "name": (
+                    discovered_info.name
+                    if discovered_info is not None
+                    else "Discovered WiiM Device"
+                )
+            },
+        )
+
+
+class CannotConnect(HomeAssistantError):
+    """Error to indicate we cannot connect."""

homeassistant/components/wiim/config_flow.py

@@ -0,0 +1,27 @@
+"""Constants for the WiiM integration."""
+
+import logging
+from typing import TYPE_CHECKING, Final
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import Platform
+from homeassistant.util.hass_dict import HassKey
+
+if TYPE_CHECKING:
+    from wiim import WiimDevice
+
+    from .models import WiimData
+
+type WiimConfigEntry = ConfigEntry[WiimDevice]
+
+DOMAIN: Final = "wiim"
+LOGGER = logging.getLogger(__package__)
+DATA_WIIM: HassKey[WiimData] = HassKey(DOMAIN)
+
+PLATFORMS: Final[list[Platform]] = [
+    Platform.MEDIA_PLAYER,
+]
+
+UPNP_PORT = 49152
+
+ZEROCONF_TYPE_LINKPLAY: Final = "_linkplay._tcp.local."

homeassistant/components/wiim/const.py

@@ -0,0 +1,36 @@
+"""Base entity for the WiiM integration."""
+
+from __future__ import annotations
+
+from wiim.wiim_device import WiimDevice
+
+from homeassistant.helpers import device_registry as dr
+from homeassistant.helpers.entity import Entity
+
+from .const import DOMAIN
+
+
+class WiimBaseEntity(Entity):
+    """Base representation of a WiiM entity."""
+
+    _attr_has_entity_name = True
+
+    def __init__(self, wiim_device: WiimDevice) -> None:
+        """Initialize the WiiM base entity."""
+        self._device = wiim_device
+        self._attr_device_info = dr.DeviceInfo(
+            identifiers={(DOMAIN, self._device.udn)},
+            name=self._device.name,
+            manufacturer=self._device.manufacturer,
+            model=self._device.model_name,
+            sw_version=self._device.firmware_version,
+        )
+        if self._device.presentation_url:
+            self._attr_device_info["configuration_url"] = self._device.presentation_url
+        elif self._device.http_api_url:
+            self._attr_device_info["configuration_url"] = self._device.http_api_url
+
+    @property
+    def available(self) -> bool:
+        """Return True if entity is available."""
+        return self._device.available

homeassistant/components/wiim/entity.py

@@ -0,0 +1,13 @@
+{
+  "domain": "wiim",
+  "name": "WiiM",
+  "codeowners": ["@Linkplay2020"],
+  "config_flow": true,
+  "documentation": "https://www.home-assistant.io/integrations/wiim",
+  "integration_type": "hub",
+  "iot_class": "local_push",
+  "loggers": ["wiim.sdk", "async_upnp_client"],
+  "quality_scale": "bronze",
+  "requirements": ["wiim==0.1.0"],
+  "zeroconf": ["_linkplay._tcp.local."]
+}