From f101ca4c73488fb05d9ac96c0bfae005502d6b81 Mon Sep 17 00:00:00 2001 From: "alexei.dolgolyov" Date: Tue, 23 Jun 2026 00:50:38 +0300 Subject: [PATCH] feat: expose scene presets as voice-controllable scene.* entities (0.5.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a SCENE platform (scene.py) so each scene preset becomes a scene.* entity. Alexa / Google Assistant / HomeKit expose the scene, light, and switch domains — but NOT button — so the existing button.* scene entities are invisible to voice assistants. Scenes use a distinct unique_id so both coexist (buttons for dashboards, scenes for voice). - Register Platform.SCENE; bump manifest 0.4.0 -> 0.5.0 - README: "Voice Control (Alexa / Google / Siri)" guide (Nabu Casa cloud, manual skill linking, HomeKit bridge, voice-friendly naming) --- README.md | 36 ++++++++++- custom_components/ledgrab/__init__.py | 1 + custom_components/ledgrab/manifest.json | 2 +- custom_components/ledgrab/scene.py | 81 +++++++++++++++++++++++++ 4 files changed, 118 insertions(+), 2 deletions(-) create mode 100644 custom_components/ledgrab/scene.py diff --git a/README.md b/README.md index c7d4142..70428d1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Custom Home Assistant integration for [LedGrab](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab) — ambient lighting system that captures screen content and drives LED strips in real time. -Creates light, switch, sensor, number, and select entities for each configured device, allowing full control and automation from Home Assistant. +Creates light, switch, scene, sensor, number, and select entities for each configured device, allowing full control and automation from Home Assistant — including hands-free voice control via Alexa, Google Assistant, and Siri. ## Installation @@ -47,6 +47,40 @@ automation: entity_id: switch.living_room_tv_processing ``` +## Voice Control (Alexa / Google / Siri) + +Scene presets are exposed both as **`scene.*`** entities (new in 0.5.0) and as `button.*` entities. **For voice control, use the `scene.*` entities** — Alexa, Google Assistant, and HomeKit/Siri expose `scene`, `light`, and `switch` domains, but **not** `button`. Capture targets are `switch.*_processing` entities and `api_input` color sources are `light.*` entities, both of which are also voice-controllable. + +### Prerequisites + +Install the LedGrab integration (above) and create the entities you want to control. Confirm you have: + +- `scene.*` entities for your scene presets (e.g. `scene.movie_night`) +- `switch.*_processing` for your capture targets +- `light.*` for any `api_input` color sources + +### Alexa & Google Assistant — easy path (Nabu Casa) + +1. Subscribe to **Home Assistant Cloud** (Nabu Casa). +2. **Settings → Home Assistant Cloud → Alexa / Google Assistant** → enable. +3. **Settings → Voice assistants → Expose** → tick the LedGrab `scene`, `switch`, and `light` entities. +4. Discover devices: *"Alexa, discover devices"* (or open the Google Home app). +5. Say *"Alexa, turn on Movie Night"* or *"Hey Google, turn off the TV ambient light."* + +### Alexa & Google Assistant — manual path (no subscription) + +Link the official **Home Assistant** Alexa skill / Google Assistant action against an externally reachable HA URL with a long-lived access token, then expose the same domains. See HA's [`cloud`](https://www.home-assistant.io/integrations/cloud/), [`google_assistant`](https://www.home-assistant.io/integrations/google_assistant/), and [`alexa`](https://www.home-assistant.io/integrations/alexa/) component docs. + +### Siri — HomeKit Bridge + +Add the **HomeKit Bridge** integration (`homekit:`), include the LedGrab `scene` / `light` / `switch` entities in its `filter`, then scan the pairing QR code in the iOS Home app. Say *"Hey Siri, turn on Movie Night."* + +### Voice-friendly naming tips + +- Rename entities in HA so the friendly name is what you'll say (e.g. `scene.movie_night` → "Movie Night"). +- Add **Aliases** in the Expose dialog so multiple phrasings work. +- Avoid the generic auto-names ("Light", "Processing"). + ## Requirements - Home Assistant 2023.1.0 or later diff --git a/custom_components/ledgrab/__init__.py b/custom_components/ledgrab/__init__.py index 08a65e9..5855e27 100644 --- a/custom_components/ledgrab/__init__.py +++ b/custom_components/ledgrab/__init__.py @@ -31,6 +31,7 @@ _LOGGER = logging.getLogger(__name__) PLATFORMS: list[Platform] = [ Platform.BUTTON, Platform.LIGHT, + Platform.SCENE, Platform.SWITCH, Platform.SENSOR, Platform.NUMBER, diff --git a/custom_components/ledgrab/manifest.json b/custom_components/ledgrab/manifest.json index be23128..731cf15 100644 --- a/custom_components/ledgrab/manifest.json +++ b/custom_components/ledgrab/manifest.json @@ -8,5 +8,5 @@ "iot_class": "local_push", "issue_tracker": "https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab-haos-integration/issues", "requirements": ["aiohttp>=3.9.0"], - "version": "0.4.0" + "version": "0.5.0" } diff --git a/custom_components/ledgrab/scene.py b/custom_components/ledgrab/scene.py new file mode 100644 index 0000000..6006c38 --- /dev/null +++ b/custom_components/ledgrab/scene.py @@ -0,0 +1,81 @@ +"""Scene platform for LedGrab — scene presets as voice-activatable scenes. + +Scene presets are also exposed as ``button.*`` entities (see button.py) for +dashboard use. Buttons, however, are NOT in the set of entity domains that +Alexa / Google Assistant / HomeKit expose to voice assistants — ``scene.*`` is. +This platform adds a ``scene.*`` entity per preset so "Alexa, turn on Movie +Night" works, while leaving the buttons in place for existing dashboards. +""" +from __future__ import annotations + +import logging +from typing import Any + +from homeassistant.components.scene import Scene +from homeassistant.config_entries import ConfigEntry +from homeassistant.core import HomeAssistant +from homeassistant.helpers.entity_platform import AddEntitiesCallback +from homeassistant.helpers.update_coordinator import CoordinatorEntity + +from .const import DOMAIN, DATA_COORDINATOR +from .coordinator import LedGrabCoordinator + +_LOGGER = logging.getLogger(__name__) + + +async def async_setup_entry( + hass: HomeAssistant, + entry: ConfigEntry, + async_add_entities: AddEntitiesCallback, +) -> None: + """Set up a scene entity per scene preset.""" + data = hass.data[DOMAIN][entry.entry_id] + coordinator: LedGrabCoordinator = data[DATA_COORDINATOR] + + entities: list[Scene] = [] + if coordinator.data: + for preset in coordinator.data.get("scene_presets", []): + entities.append(LedGrabScene(coordinator, preset, entry.entry_id)) + + async_add_entities(entities) + + +class LedGrabScene(CoordinatorEntity, Scene): + """A scene preset exposed as a HA scene (voice-friendly).""" + + # Full standalone name so utterances like "turn on Movie Night" match, + # instead of the " " composite that has_entity_name gives. + _attr_has_entity_name = False + _attr_icon = "mdi:palette" + + def __init__( + self, + coordinator: LedGrabCoordinator, + preset: dict[str, Any], + entry_id: str, + ) -> None: + """Initialize the scene.""" + super().__init__(coordinator) + self._preset_id = preset["id"] + self._entry_id = entry_id + # Distinct from the button's unique_id so both can coexist. + self._attr_unique_id = f"{entry_id}_scene_entity_{preset['id']}" + self._attr_name = preset["name"] + + @property + def device_info(self) -> dict[str, Any]: + """All scene entities belong to the same Scenes device as the buttons.""" + return {"identifiers": {(DOMAIN, f"{self._entry_id}_scenes")}} + + @property + def available(self) -> bool: + """Return if the underlying preset still exists.""" + if not self.coordinator.data: + return False + return self._preset_id in { + p["id"] for p in self.coordinator.data.get("scene_presets", []) + } + + async def async_activate(self, **kwargs: Any) -> None: + """Activate the scene preset.""" + await self.coordinator.activate_scene(self._preset_id)