wled-screen-controller-mixed/INSTALLATION.md

Installation Guide

Complete installation guide for WLED Screen Controller server and Home Assistant integration.

Table of Contents

1. Server Installation
2. Home Assistant Integration
3. Quick Start

---

Server Installation

Option 1: Python (Development/Testing)

Requirements:

• Python 3.11 or higher
• Windows, Linux, or macOS

Steps:

1. Clone the repository:

   git clone https://github.com/yourusername/wled-screen-controller.git
   cd wled-screen-controller/server
   

2. Create virtual environment:

   python -m venv venv
   
   # Windows
   venv\Scripts\activate
   
   # Linux/Mac
   source venv/bin/activate
   

3. Install dependencies:

   pip install .
   

4. Configure (optional): Edit config/default_config.yaml to customize settings.

5. Run the server:

   # Set PYTHONPATH
   export PYTHONPATH=$(pwd)/src  # Linux/Mac
   set PYTHONPATH=%CD%\src        # Windows
   
   # Start server
   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
   

6. Verify: Open http://localhost:8080/docs in your browser.

Option 2: Docker (Recommended for Production)

Requirements:

• Docker
• Docker Compose

Steps:

1. Clone the repository:

   git clone https://github.com/yourusername/wled-screen-controller.git
   cd wled-screen-controller/server
   

2. Start with Docker Compose:

   docker-compose up -d
   

3. View logs:

   docker-compose logs -f
   

4. Verify: Open http://localhost:8080/docs in your browser.

Option 3: Docker (Manual Build)

cd server
docker build -t wled-screen-controller .

docker run -d \
  --name wled-controller \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  --network host \
  wled-screen-controller

---

Home Assistant Integration

Option 1: HACS (Recommended)

1. Install HACS if not already installed:

   • Follow instructions at https://hacs.xyz/docs/setup/download

2. Add Custom Repository:

   • Open HACS in Home Assistant
   • Click the three dots 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 Integration:

   • 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

Option 2: Manual Installation

1. Download Integration:

   cd /config  # Your Home Assistant config directory
   mkdir -p custom_components
   

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

3. Restart Home Assistant

4. Configure Integration:

   • Go to Settings → Devices & Services
   • Click "+ Add Integration"
   • Search for "WLED Screen Controller"
   • Enter your server URL
   • Click Submit

---

Quick Start

1. Start the Server

cd wled-screen-controller/server
docker-compose up -d

2. Attach Your WLED Device

curl -X POST http://localhost:8080/api/v1/devices \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Living Room TV",
    "url": "http://192.168.1.100",
    "led_count": 150
  }'

3. Configure in Home Assistant

1. Add the integration (see above)
2. Your WLED devices will appear automatically
3. Use the switch to turn processing on/off
4. Use the select to choose display
5. Monitor FPS and status via sensors

4. Start Processing

Either via API:

curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start

Or via Home Assistant:

• Turn on the "{Device Name} Processing" switch

5. Enjoy Ambient Lighting!

Your WLED strip should now sync with your screen content!

---

Troubleshooting

Server Won't Start

Check Python version:

python --version  # Should be 3.11+

Check dependencies:

pip list | grep fastapi

Check logs:

# Docker
docker-compose logs -f

# Python
tail -f logs/wled_controller.log

Home Assistant Integration Not Appearing

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

Can't Connect to Server from Home Assistant

1. Verify server is running:

   curl http://YOUR_SERVER_IP:8080/health
   

2. Check firewall rules

3. Ensure Home Assistant can reach server IP

4. Try http:// not https://

WLED Device Not Responding

1. Check WLED device is powered on

2. Verify IP address is correct

3. Test WLED directly:

   curl http://YOUR_WLED_IP/json/info
   

4. Check network connectivity

Low FPS / Performance Issues

1. Reduce target FPS (Settings → Devices)
2. Reduce border_width in settings
3. Check CPU usage on server
4. Consider reducing LED count

---

Configuration Examples

Server Environment Variables

# Docker .env file
WLED_SERVER__HOST=0.0.0.0
WLED_SERVER__PORT=8080
WLED_SERVER__LOG_LEVEL=INFO
WLED_PROCESSING__DEFAULT_FPS=30
WLED_PROCESSING__BORDER_WIDTH=10

Home Assistant Automation Example

automation:
  - alias: "Auto Start WLED on TV 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: "Auto Stop WLED on TV 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

---

Next Steps

• API Documentation
• Calibration Guide
• GitHub Issues