wled-screen-controller-mixed/INSTALLATION.md

# Installation Guide

Complete installation guide for LED Grab (WLED Screen Controller) server and Home Assistant integration.

## Table of Contents

1. [Docker Installation (recommended)](#docker-installation)
2. [Manual Installation](#manual-installation)
3. [First-Time Setup](#first-time-setup)
4. [Home Assistant Integration](#home-assistant-integration)
5. [Configuration Reference](#configuration-reference)
6. [Troubleshooting](#troubleshooting)

---

## Docker Installation

The fastest way to get running. Requires [Docker](https://docs.docker.com/get-docker/) with Compose.

1. **Clone and start:**

   ```bash
   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
   cd wled-screen-controller/server
   docker compose up -d
   ```

2. **Verify:**

   ```bash
   curl http://localhost:8080/health
   # → {"status":"healthy", ...}
   ```

3. **Open the dashboard:** <http://localhost:8080>

4. **View logs:**

   ```bash
   docker compose logs -f
   ```

5. **Stop / restart:**

   ```bash
   docker compose down          # stop
   docker compose up -d         # start again (data is persisted)
   ```

### Docker manual build (without Compose)

```bash
cd server
docker build -t ledgrab .

docker run -d \
  --name wled-screen-controller \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/config:/app/config:ro \
  ledgrab
```

### Linux screen capture in Docker

Screen capture from inside a container requires X11 access. Uncomment `network_mode: host` in `docker-compose.yml` and ensure the `DISPLAY` variable is set. Wayland is not currently supported for in-container capture.

---

## Manual Installation

### Requirements

| Dependency | Version | Purpose |
| ---------- | ------- | ------- |
| Python | 3.11+ | Backend server |
| Node.js | 18+ | Frontend build (esbuild) |
| pip | latest | Python package installer |
| npm | latest | Node package manager |

### Steps

1. **Clone the repository:**

   ```bash
   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
   cd wled-screen-controller/server
   ```

2. **Build the frontend bundle:**

   ```bash
   npm ci
   npm run build
   ```

   This compiles TypeScript and bundles JS/CSS into `src/wled_controller/static/dist/`.

3. **Create a virtual environment:**

   ```bash
   python -m venv venv

   # Linux / macOS
   source venv/bin/activate

   # Windows (cmd)
   venv\Scripts\activate

   # Windows (PowerShell)
   venv\Scripts\Activate.ps1
   ```

4. **Install Python dependencies:**

   ```bash
   pip install .
   ```

   Optional extras:

   ```bash
   pip install ".[camera]"          # Webcam capture via OpenCV
   pip install ".[perf]"            # DXCam, BetterCam, WGC (Windows only)
   pip install ".[notifications]"   # OS notification capture
   pip install ".[dev]"             # pytest, black, ruff (development)
   ```

5. **Set PYTHONPATH and start the server:**

   ```bash
   # Linux / macOS
   export PYTHONPATH=$(pwd)/src
   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080

   # Windows (cmd)
   set PYTHONPATH=%CD%\src
   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
   ```

6. **Verify:** open <http://localhost:8080> in your browser.

---

## First-Time Setup

### Change the default API key

The server ships with a development API key (`development-key-change-in-production`). **Change it before exposing the server on your network.**

Option A -- edit the config file:

```yaml
# server/config/default_config.yaml
auth:
  api_keys:
    main: "your-secure-key-here"   # replace the dev key
```

Option B -- set an environment variable:

```bash
export WLED_AUTH__API_KEYS__main="your-secure-key-here"
```

Generate a random key:

```bash
openssl rand -hex 32
```

### Configure CORS for LAN access

By default the server only allows requests from `http://localhost:8080`. To access the dashboard from another machine on your LAN, add its origin:

```yaml
# server/config/default_config.yaml
server:
  cors_origins:
    - "http://localhost:8080"
    - "http://192.168.1.100:8080"   # your server's LAN IP
```

Or via environment variable:

```bash
WLED_SERVER__CORS_ORIGINS='["http://localhost:8080","http://192.168.1.100:8080"]'
```

### Discover devices

Open the dashboard and go to the **Devices** tab. Click **Discover** to find WLED devices on your network via mDNS. You can also add devices manually by IP address.

---

## Home Assistant Integration

### Option 1: HACS (recommended)

1. Install [HACS](https://hacs.xyz/docs/setup/download) 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/wled-screen-controller-mixed`
5. Set category to **Integration** and click **Add**.
6. Search for "WLED Screen Controller" in HACS and click **Download**.
7. Restart Home Assistant.
8. Go to **Settings > Devices & Services > Add Integration** and search for "WLED Screen Controller".
9. Enter your server URL (e.g., `http://192.168.1.100:8080`) and API key.

### Option 2: Manual

Copy the `custom_components/wled_screen_controller/` folder from this repository into your Home Assistant `config/custom_components/` directory, then restart Home Assistant and add the integration as above.

### Automation example

```yaml
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
```

---

## Configuration Reference

The server reads configuration from three sources (in order of priority):

1. **Environment variables** -- prefix `WLED_`, double underscore as nesting delimiter (e.g., `WLED_SERVER__PORT=9090`)
2. **YAML config file** -- `server/config/default_config.yaml` (or set `WLED_CONFIG_PATH` to override)
3. **Built-in defaults**

See [`server/.env.example`](server/.env.example) for every available variable with descriptions.

### Key settings

| Variable | Default | Description |
| -------- | ------- | ----------- |
| `WLED_SERVER__PORT` | `8080` | HTTP listen port |
| `WLED_SERVER__LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
| `WLED_SERVER__CORS_ORIGINS` | `["http://localhost:8080"]` | Allowed CORS origins (JSON array) |
| `WLED_AUTH__API_KEYS` | `{"dev":"development-key..."}` | API keys (JSON object) |
| `WLED_MQTT__ENABLED` | `false` | Enable MQTT for HA auto-discovery |
| `WLED_MQTT__BROKER_HOST` | `localhost` | MQTT broker address |
| `WLED_DEMO` | `false` | Enable demo mode (sandbox with virtual devices) |

---

## Troubleshooting

### Server will not start

**Check Python version:**

```bash
python --version  # must be 3.11+
```

**Check the frontend bundle exists:**

```bash
ls server/src/wled_controller/static/dist/app.bundle.js
```

If missing, run `cd server && npm ci && npm run build`.

**Check logs:**

```bash
# Docker
docker compose logs -f

# Manual install
tail -f logs/wled_controller.log
```

### Cannot access the dashboard from another machine

1. Verify the server is reachable: `curl http://SERVER_IP:8080/health`
2. Check your firewall allows inbound traffic on port 8080.
3. Add your server's LAN IP to `cors_origins` (see [Configure CORS](#configure-cors-for-lan-access) above).

### Home Assistant integration not appearing

1. Verify HACS installed the component: check that `config/custom_components/wled_screen_controller/` exists.
2. Clear your browser cache.
3. Restart Home Assistant.
4. Check logs at **Settings > System > Logs** and search for `wled_screen_controller`.

### WLED device not responding

1. Confirm the device is powered on and connected to Wi-Fi.
2. Test it directly: `curl http://DEVICE_IP/json/info`
3. Check that the server and the device are on the same subnet.
4. Try restarting the WLED device.

### Low FPS or high latency

1. Lower the target FPS in the stream settings.
2. Reduce `border_width` to decrease the number of sampled pixels.
3. Check CPU usage on the server (`htop` or Task Manager).
4. On Windows, install the `perf` extra for GPU-accelerated capture: `pip install ".[perf]"`

---

## Next Steps

- [API Documentation](docs/API.md)
- [Calibration Guide](docs/CALIBRATION.md)
- [Repository Issues](https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed/issues)