wled-screen-controller-mixed/custom_components/wled_screen_controller/README.md

# WLED Screen Controller - Home Assistant Integration

Native Home Assistant integration for WLED Screen Controller with full HACS support.

## Overview

This integration connects Home Assistant to the WLED Screen Controller server, providing:

- 🎛️ **Switch Entities** - Turn processing on/off per device
- 📊 **Sensor Entities** - Monitor FPS, status, and frame count
- 🖥️ **Select Entities** - Choose which display to capture
- 🔄 **Auto-Discovery** - Devices appear automatically
- 📦 **HACS Compatible** - Install directly from HACS
- ⚙️ **Config Flow** - Easy setup through UI

## Installation

### Method 1: HACS (Recommended)

1. **Install HACS** if you haven't already:
   - Visit https://hacs.xyz/docs/setup/download

2. **Add Custom Repository:**
   - Open HACS in Home Assistant
   - Click the menu (⋮) → Custom repositories
   - Add URL: `https://github.com/yourusername/wled-screen-controller`
   - Category: **Integration**
   - Click **Add**

3. **Install Integration:**
   - In HACS, search for "WLED Screen Controller"
   - Click **Download**
   - Restart Home Assistant

4. **Configure:**
   - Go to Settings → Devices & Services
   - Click **+ Add Integration**
   - Search for "WLED Screen Controller"
   - Enter your server URL (e.g., `http://192.168.1.100:8080`)
   - Click **Submit**

### Method 2: Manual Installation

1. **Download:**
   ```bash
   cd /config  # Your Home Assistant config directory
   mkdir -p custom_components
   ```

2. **Copy Files:**
   Copy the entire `custom_components/wled_screen_controller` folder to your Home Assistant `custom_components/` directory.

3. **Restart Home Assistant**

4. **Configure:**
   - Settings → Devices & Services → Add Integration
   - Search for "WLED Screen Controller"

## Configuration

### Initial Setup

When adding the integration, you'll be prompted for:

- **Name**: Friendly name for the integration (default: "WLED Screen Controller")
- **Server URL**: URL of your WLED Screen Controller server (e.g., `http://192.168.1.100:8080`)

The integration will automatically:
- Verify connection to the server
- Discover all configured WLED devices
- Create entities for each device

### Entities Created

For each WLED device, the following entities are created:

#### Switch Entities

**`switch.{device_name}_processing`**
- Controls processing on/off for the device
- Attributes:
  - `device_id`: Internal device ID
  - `fps_target`: Target FPS
  - `fps_actual`: Current FPS
  - `display_index`: Active display
  - `frames_processed`: Total frames
  - `errors_count`: Error count
  - `uptime_seconds`: Processing uptime

#### Sensor Entities

**`sensor.{device_name}_fps`**
- Current FPS value
- Unit: FPS
- Attributes:
  - `target_fps`: Target FPS setting

**`sensor.{device_name}_status`**
- Processing status
- States: `processing`, `idle`, `unavailable`, `unknown`

**`sensor.{device_name}_frames_processed`**
- Total frames processed counter
- Continuously increasing while processing

#### Select Entities

**`select.{device_name}_display`**
- Select which display to capture
- Options: `Display 0`, `Display 1`, etc.
- Changes take effect immediately

## Usage Examples

### Basic Automation

Turn on processing when TV turns on:

```yaml
automation:
  - alias: "Auto Start WLED with TV"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
        to: "on"
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.living_room_wled_processing

  - alias: "Auto Stop WLED with TV"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
        to: "off"
    action:
      - service: switch.turn_off
        target:
          entity_id: switch.living_room_wled_processing
```

### Lovelace UI Examples

#### Simple Card

```yaml
type: entities
title: WLED Screen Controller
entities:
  - entity: switch.living_room_wled_processing
  - entity: sensor.living_room_wled_fps
  - entity: sensor.living_room_wled_status
  - entity: select.living_room_wled_display
```

#### Advanced Card

```yaml
type: vertical-stack
cards:
  - type: entity
    entity: switch.living_room_wled_processing
    name: Ambient Lighting
    icon: mdi:television-ambient-light

  - type: conditional
    conditions:
      - entity: switch.living_room_wled_processing
        state: "on"
    card:
      type: entities
      entities:
        - entity: sensor.living_room_wled_fps
          name: Current FPS
        - entity: sensor.living_room_wled_frames_processed
          name: Frames Processed
        - entity: select.living_room_wled_display
          name: Display Selection
```

## Troubleshooting

### Integration Not Appearing

1. Check HACS installation
2. Clear browser cache
3. Restart Home Assistant
4. Check logs: Settings → System → Logs

### Connection Errors

1. Verify server is running:
   ```bash
   curl http://YOUR_SERVER_IP:8080/health
   ```

2. Check firewall settings
3. Ensure Home Assistant can reach server
4. Try http:// not https://

### Entities Not Updating

1. Check coordinator logs
2. Verify server has devices
3. Restart integration

## Support

- 📖 [Full Documentation](../../INSTALLATION.md)
- 🐛 [Report Issues](https://github.com/yourusername/wled-screen-controller/issues)

## License

MIT License - see [../../LICENSE](../../LICENSE)