feat: Add HDMI source selection for AI Sync Box (H6604)

Adds support for devices with devices.capabilities.mode/hdmiSource capability:
- New select entity for HDMI input selection (1-4)
- ModeCommand class for mode-type capabilities
- State tracking for hdmi_source
- Updated README with debug logging instructions

Closes #3

Author: Tom Lasswell

README.md

@@ -60,6 +60,7 @@ Enter your API key. Want instant updates? Add your Govee email/password for MQTT
 | **LED Lights & Strips** | On/off, brightness, RGB, color temp |
 | **RGBIC Strips** | All the above + per-segment colors |
 | **Fans** | On/off, speed (Low/Medium/High), oscillation, preset modes |
+| **HDMI Sync Boxes** | On/off, HDMI input selection (1-4) |
 
 > **Note:** Cloud-enabled devices only. Bluetooth-only devices need a different integration.
 
@@ -81,7 +82,65 @@ No credentials? Polling works fine (every 60 seconds by default).
 | Slow updates | Enable MQTT or reduce poll interval in options |
 | Rate limit errors | Increase poll interval (Govee allows 100 req/min) |
 
-Need debug logs? Add `custom_components.govee: debug` to your logger config.
+---
+
+## Debug Logging
+
+When troubleshooting issues, enable debug logging to capture detailed information about what the integration is doing.
+
+### Enable Debug Logging
+
+**Option 1: From the Integration (Recommended)**
+1. Go to **Settings** → **Devices & Services**
+2. Find the **Govee** integration card
+3. Click the **three dots menu** (⋮) on the integration card
+4. Select **Enable debug logging**
+5. Reproduce the issue (turn on a light, trigger the error, etc.)
+6. Return to the integration card, click the three dots menu again
+7. Select **Disable debug logging**
+8. Your browser will download a log file automatically
+
+**Option 2: Via configuration.yaml**
+
+For issues during startup or if you need persistent debug logging, add to your `configuration.yaml` and restart:
+
+```yaml
+logger:
+  default: info
+  logs:
+    custom_components.govee: debug
+```
+
+### Viewing Logs
+
+- Go to **Settings** → **System** → **Logs**
+- Click **Load Full Logs** to see everything
+- Use the search box to filter for "govee"
+
+See [Home Assistant Logger docs](https://www.home-assistant.io/integrations/logger/) for more details.
+
+### Gathering Logs for Issues
+
+When opening an issue, include relevant log entries. Here's what to capture:
+
+1. **Enable debug logging** (see above)
+2. **Reproduce the issue** (turn on/off a device, change a scene, etc.)
+3. **Copy the relevant log entries**
+
+**What to include:**
+- Logs from when Home Assistant starts (shows device discovery)
+- Logs from when the issue occurs
+- Any error messages or tracebacks
+
+**Example log snippet to include:**
+```
+2024-01-15 10:30:45 DEBUG (MainThread) [custom_components.govee.coordinator] Device: Living Room Light (AA:BB:CC:DD:EE:FF:00:11) type=devices.types.light
+2024-01-15 10:30:45 DEBUG (MainThread) [custom_components.govee.coordinator]   Capability: type=devices.capabilities.on_off instance=powerSwitch
+```
+
+**Before posting**, redact sensitive information:
+- Replace device IDs with `XX:XX:XX:XX:XX:XX:XX:XX`
+- Remove any email addresses or account IDs
 
 ---
 

custom_components/govee/__init__.py

@@ -244,6 +244,7 @@ async def _async_cleanup_orphaned_entities(
         "_scene_select",
         "_diy_scene_select",
         "_diy_style_select",
+        "_hdmi_source_select",
         "_refresh_scenes",
         "_night_light",
         "_music_mode",

custom_components/govee/coordinator.py

@@ -667,9 +667,11 @@ def _apply_optimistic_update(
             BrightnessCommand,
             ColorCommand,
             ColorTempCommand,
+            ModeCommand,
             PowerCommand,
             SceneCommand,
         )
+        from .models.device import INSTANCE_HDMI_SOURCE
 
         if isinstance(command, PowerCommand):
             state.apply_optimistic_power(command.power_on)
@@ -681,6 +683,9 @@ def _apply_optimistic_update(
             state.apply_optimistic_color_temp(command.kelvin)
         elif isinstance(command, SceneCommand):
             state.apply_optimistic_scene(str(command.scene_id))
+        elif isinstance(command, ModeCommand):
+            if command.mode_instance == INSTANCE_HDMI_SOURCE:
+                state.apply_optimistic_hdmi_source(command.value)
 
     async def async_get_scenes(
         self,

custom_components/govee/manifest.json

@@ -9,13 +9,13 @@
   "integration_type": "hub",
   "iot_class": "cloud_push",
   "issue_tracker": "https://github.com/lasswellt/govee-homeassistant/issues",
-  "loggers": ["aiohttp", "aiomqtt"],
+  "loggers": ["custom_components.govee", "aiohttp", "aiomqtt"],
   "requirements": [
     "aiohttp-retry>=2.8.3",
     "aiomqtt>=2.0.0",
     "cryptography>=41.0.0"
   ],
   "ssdp": [],
-  "version": "2026.1.51",
+  "version": "2026.1.52",
   "zeroconf": []
 }

custom_components/govee/models/__init__.py

@@ -9,6 +9,7 @@
     ColorTempCommand,
     DeviceCommand,
     DIYSceneCommand,
+    ModeCommand,
     OscillationCommand,
     PowerCommand,
     SceneCommand,
@@ -47,5 +48,6 @@
     "ToggleCommand",
     "OscillationCommand",
     "WorkModeCommand",
+    "ModeCommand",
     "create_night_light_command",
 ]

custom_components/govee/models/commands.py

@@ -13,6 +13,7 @@
 from .device import (
     CAPABILITY_COLOR_SETTING,
     CAPABILITY_DYNAMIC_SCENE,
+    CAPABILITY_MODE,
     CAPABILITY_ON_OFF,
     CAPABILITY_RANGE,
     CAPABILITY_SEGMENT_COLOR,
@@ -276,3 +277,27 @@ def instance(self) -> str:
 
     def get_value(self) -> dict[str, int]:
         return {"workMode": self.work_mode, "modeValue": self.mode_value}
+
+
+@dataclass(frozen=True)
+class ModeCommand(DeviceCommand):
+    """Command to set a mode value (e.g., HDMI source).
+
+    This is a generic command for mode-type capabilities that take
+    an integer value. Used for HDMI source selection on devices
+    like the Govee AI Sync Box (H6604).
+    """
+
+    mode_instance: str  # e.g., "hdmiSource"
+    value: int  # e.g., 1, 2, 3, 4 for HDMI ports
+
+    @property
+    def capability_type(self) -> str:
+        return CAPABILITY_MODE
+
+    @property
+    def instance(self) -> str:
+        return self.mode_instance
+
+    def get_value(self) -> int:
+        return self.value

custom_components/govee/models/device.py

@@ -21,6 +21,7 @@
 CAPABILITY_TOGGLE = "devices.capabilities.toggle"
 CAPABILITY_WORK_MODE = "devices.capabilities.work_mode"
 CAPABILITY_PROPERTY = "devices.capabilities.property"
+CAPABILITY_MODE = "devices.capabilities.mode"
 
 # Device type constants
 DEVICE_TYPE_LIGHT = "devices.types.light"
@@ -42,6 +43,7 @@
 INSTANCE_TIMER = "timer"
 INSTANCE_OSCILLATION = "oscillationToggle"
 INSTANCE_WORK_MODE = "workMode"
+INSTANCE_HDMI_SOURCE = "hdmiSource"
 
 
 @dataclass(frozen=True)
@@ -195,6 +197,11 @@ def is_work_mode(self) -> bool:
         """Check if this is a work mode capability (for fans)."""
         return self.type == CAPABILITY_WORK_MODE and self.instance == INSTANCE_WORK_MODE
 
+    @property
+    def is_hdmi_source(self) -> bool:
+        """Check if this is an HDMI source mode capability."""
+        return self.type == CAPABILITY_MODE and self.instance == INSTANCE_HDMI_SOURCE
+
     @property
     def brightness_range(self) -> tuple[int, int]:
         """Get brightness min/max range. Default (0, 100)."""
@@ -291,6 +298,18 @@ def supports_work_mode(self) -> bool:
         """Check if device supports work mode (fans)."""
         return any(cap.is_work_mode for cap in self.capabilities)
 
+    @property
+    def supports_hdmi_source(self) -> bool:
+        """Check if device supports HDMI source selection."""
+        return any(cap.is_hdmi_source for cap in self.capabilities)
+
+    def get_hdmi_source_options(self) -> list[dict[str, Any]]:
+        """Get available HDMI source options from capability parameters."""
+        for cap in self.capabilities:
+            if cap.is_hdmi_source:
+                return cap.parameters.get("options", [])
+        return []
+
     @property
     def is_light_device(self) -> bool:
         """Check if device is a light (not a plug, fan, or other appliance)."""

custom_components/govee/models/state.py

@@ -93,6 +93,9 @@ class GoveeDeviceState:
     work_mode: int | None = None  # Fan work mode: 1=gearMode, 3=Auto, 9=Fan
     mode_value: int | None = None  # Fan speed for gearMode: 1=Low, 2=Medium, 3=High
 
+    # HDMI source state (for devices like AI Sync Box H6604)
+    hdmi_source: int | None = None  # HDMI port: 1, 2, 3, 4
+
     # Source tracking for state management
     # "api" = from REST poll, "mqtt" = from push, "optimistic" = from command
     source: str = "api"
@@ -142,6 +145,10 @@ def update_from_api(self, data: dict[str, Any]) -> None:
                     self.work_mode = value.get("workMode")
                     self.mode_value = value.get("modeValue")
 
+            elif cap_type == "devices.capabilities.mode":
+                if instance == "hdmiSource":
+                    self.hdmi_source = int(value) if value is not None else None
+
     def update_from_mqtt(self, data: dict[str, Any]) -> None:
         """Update state from MQTT push message.
 
@@ -220,6 +227,11 @@ def apply_optimistic_work_mode(self, work_mode: int, mode_value: int) -> None:
         self.mode_value = mode_value
         self.source = "optimistic"
 
+    def apply_optimistic_hdmi_source(self, source: int) -> None:
+        """Apply optimistic HDMI source update."""
+        self.hdmi_source = source
+        self.source = "optimistic"
+
     @classmethod
     def create_empty(cls, device_id: str) -> GoveeDeviceState:
         """Create empty state for a device."""

custom_components/govee/select.py

@@ -25,7 +25,8 @@
     DOMAIN,
 )
 from .coordinator import GoveeCoordinator
-from .models import DIYSceneCommand, GoveeDevice, SceneCommand
+from .models import DIYSceneCommand, GoveeDevice, ModeCommand, SceneCommand
+from .models.device import INSTANCE_HDMI_SOURCE
 
 # DIY Style options for select entity
 DIY_STYLE_OPTIONS = list(DIY_STYLE_NAMES.keys())
@@ -103,6 +104,19 @@ async def async_setup_entry(
                 )
                 _LOGGER.debug("Created DIY style select entity for %s", device.name)
 
+        # HDMI source selector (for devices like AI Sync Box H6604)
+        if device.supports_hdmi_source:
+            hdmi_options = device.get_hdmi_source_options()
+            if hdmi_options:
+                entities.append(
+                    GoveeHdmiSourceSelectEntity(
+                        coordinator=coordinator,
+                        device=device,
+                        options=hdmi_options,
+                    )
+                )
+                _LOGGER.debug("Created HDMI source select entity for %s", device.name)
+
     async_add_entities(entities)
     _LOGGER.debug("Set up %d Govee scene select entities", len(entities))
 
@@ -436,3 +450,114 @@ async def async_select_option(self, option: str) -> None:
                 option,
                 self._device.name,
             )
+
+
+class GoveeHdmiSourceSelectEntity(CoordinatorEntity["GoveeCoordinator"], SelectEntity):
+    """Govee HDMI source select entity.
+
+    Provides a dropdown to select HDMI input source on devices like
+    the Govee AI Sync Box (H6604).
+    """
+
+    _attr_has_entity_name = True
+    _attr_translation_key = "govee_hdmi_source_select"
+    _attr_icon = "mdi:hdmi-port"
+
+    def __init__(
+        self,
+        coordinator: GoveeCoordinator,
+        device: GoveeDevice,
+        options: list[dict[str, Any]],
+    ) -> None:
+        """Initialize the HDMI source select entity.
+
+        Args:
+            coordinator: Govee data coordinator.
+            device: Device this select belongs to.
+            options: List of HDMI source options from capability parameters.
+        """
+        super().__init__(coordinator)
+
+        self._device = device
+        self._device_id = device.device_id
+
+        # Build option mapping: display name -> value
+        self._option_map: dict[str, int] = {}
+        option_names: list[str] = []
+
+        for opt in options:
+            name = opt.get("name", "")
+            value = opt.get("value")
+            if name and value is not None:
+                self._option_map[name] = value
+                option_names.append(name)
+
+        self._attr_options = option_names
+
+        # Unique ID
+        self._attr_unique_id = f"{device.device_id}_hdmi_source_select"
+
+        # Entity name
+        self._attr_name = "HDMI Source"
+
+    @property
+    def device_info(self) -> DeviceInfo:
+        """Return device information."""
+        return DeviceInfo(
+            identifiers={(DOMAIN, self._device.device_id)},
+            name=self._device.name,
+            manufacturer="Govee",
+            model=self._device.sku,
+        )
+
+    @property
+    def available(self) -> bool:
+        """Return True if entity is available."""
+        state = self.coordinator.get_state(self._device_id)
+        if state is None:
+            return False
+        return state.online or self._device.is_group
+
+    @property
+    def current_option(self) -> str | None:
+        """Return current selected option from state."""
+        state = self.coordinator.get_state(self._device_id)
+        if state and state.hdmi_source is not None:
+            # Find option name matching the current value
+            for name, value in self._option_map.items():
+                if value == state.hdmi_source:
+                    return name
+        # Return first option as default if available
+        return self._attr_options[0] if self._attr_options else None
+
+    async def async_select_option(self, option: str) -> None:
+        """Handle HDMI source selection."""
+        value = self._option_map.get(option)
+        if value is None:
+            _LOGGER.warning("Unknown HDMI source option: %s", option)
+            return
+
+        command = ModeCommand(
+            mode_instance=INSTANCE_HDMI_SOURCE,
+            value=value,
+        )
+
+        success = await self.coordinator.async_control_device(
+            self._device_id,
+            command,
+        )
+
+        if success:
+            self.async_write_ha_state()
+            _LOGGER.debug(
+                "Set HDMI source '%s' (value=%d) on %s",
+                option,
+                value,
+                self._device.name,
+            )
+        else:
+            _LOGGER.warning(
+                "Failed to set HDMI source '%s' on %s",
+                option,
+                self._device.name,
+            )