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:

   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:

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

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

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:

   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
• 🐛 Report Issues

License

MIT License - see ../../LICENSE