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](#server-installation)
2. [Home Assistant Integration](#home-assistant-integration)
3. [Quick Start](#quick-start)

---

## Server Installation

### Option 1: Python (Development/Testing)

**Requirements:**
- Python 3.11 or higher
- Windows, Linux, or macOS

**Steps:**

1. **Clone the repository:**
   ```bash
   git clone https://github.com/yourusername/wled-screen-controller.git
   cd wled-screen-controller/server
   ```

2. **Create virtual environment:**
   ```bash
   python -m venv venv

   # Windows
   venv\Scripts\activate

   # Linux/Mac
   source venv/bin/activate
   ```

3. **Install dependencies:**
   ```bash
   pip install .
   ```

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

5. **Run the server:**
   ```bash
   # 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:**
   ```bash
   git clone https://github.com/yourusername/wled-screen-controller.git
   cd wled-screen-controller/server
   ```

2. **Start with Docker Compose:**
   ```bash
   docker-compose up -d
   ```

3. **View logs:**
   ```bash
   docker-compose logs -f
   ```

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

### Option 3: Docker (Manual Build)

```bash
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:**
   ```bash
   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

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

### 2. Attach Your WLED Device

```bash
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:
```bash
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:**
```bash
python --version  # Should be 3.11+
```

**Check dependencies:**
```bash
pip list | grep fastapi
```

**Check logs:**
```bash
# 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:
   ```bash
   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:
   ```bash
   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

```bash
# 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

```yaml
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](docs/API.md)
- [Calibration Guide](docs/CALIBRATION.md)
- [GitHub Issues](https://github.com/yourusername/wled-screen-controller/issues)