# LedGrab Home Assistant Integration

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, 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

### Option 1: HACS (recommended)

1. Install [HACS](https://hacs.xyz/docs/setup/download) if you have not already.
2. Open HACS in Home Assistant.
3. Click the three-dot menu, then **Custom repositories**.
4. Add URL: `https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab-haos-integration`
5. Set category to **Integration** and click **Add**.
6. Search for "LedGrab" in HACS and click **Download**.
7. Restart Home Assistant.
8. Go to **Settings > Devices & Services > Add Integration** and search for "LedGrab".
9. Enter your server URL (e.g., `http://192.168.1.100:8080`) and API key.

### Option 2: Manual

Copy the `custom_components/ledgrab/` folder from this repository into your Home Assistant `config/custom_components/` directory, then restart Home Assistant and add the integration as above.

## Automation Example

```yaml
automation:
  - alias: "Start ambient lighting when TV turns on"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
        to: "on"
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.living_room_tv_processing

  - alias: "Stop ambient lighting when TV turns off"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
        to: "off"
    action:
      - service: switch.turn_off
        target:
          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
- A running [LedGrab](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab) server accessible on your network

## Troubleshooting

1. Verify the component exists: check that `config/custom_components/ledgrab/` is present.
2. Clear the browser cache and hard-refresh the HA UI.
3. Restart Home Assistant.
4. Check logs at **Settings > System > Logs** and search for `ledgrab`.

## License

MIT