ledgrab-haos-integration/README.md

LedGrab Home Assistant Integration

Custom Home Assistant integration for 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 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

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