proxmox-infrastruktur/docker/samsung-tv-api/README.md

# Samsung TV API Service

REST API zur Steuerung von Samsung Smart TVs (2016+, Tizen OS) via WebSocket.
Entwickelt für die Integration mit n8n auf Proxmox.

## Unterstützte Geräte

- Samsung Smart TVs ab 2016 (Tizen OS)
- Getestet mit: UE50RU7409 (2019)

## Setup

### 1. TV IP-Adresse ermitteln

Am TV: **Einstellungen → Allgemein → Netzwerk → Netzwerkstatus**

Oder im Router nachschauen (Fritz!Box: Heimnetz → Netzwerk)

### 2. .env Datei anpassen

```bash
# In /opt/docker/.env auf dem Proxmox Host
SAMSUNG_TV_IP=192.168.178.XXX
SAMSUNG_TV_MAC=AA:BB:CC:DD:EE:FF  # Optional für Wake-on-LAN
```

### 3. Container starten

```bash
cd /opt/docker
docker-compose up -d samsung-tv-api
```

### 4. Erste Verbindung - TV Autorisierung

Beim ersten API-Aufruf erscheint auf dem TV ein Dialog:
**"n8n-proxmox möchte sich verbinden - Zulassen?"**

→ Mit der TV-Fernbedienung **Zulassen** wählen

Der Token wird dann in `/opt/docker/samsung-tv-api/tv-token.txt` gespeichert.

**Tipp:** In TV-Einstellungen → Externe Geräteverwaltung → Geräteverbindungsmanager →
Zugriffsbenachrichtigung auf **"Nur beim ersten Mal"** stellen.

## API Endpoints

| Endpoint | Method | Beschreibung |
|----------|--------|--------------|
| `/` | GET | API Dokumentation |
| `/health` | GET | Health-Check |
| `/tv/status` | GET | TV Status prüfen |
| `/tv/power/on` | POST | TV einschalten (Wake-on-LAN) |
| `/tv/power/off` | POST | TV ausschalten |
| `/tv/key` | POST | Taste senden |
| `/tv/volume` | POST | Lautstärke steuern |
| `/tv/channel` | POST | Kanal wechseln |
| `/tv/source` | POST | Eingangsquelle wechseln |
| `/tv/apps` | GET | Installierte Apps auflisten |
| `/tv/app/open` | POST | App starten |
| `/tv/browser` | POST | URL im Browser öffnen |

## Beispiel-Aufrufe

### TV ausschalten
```bash
curl -X POST http://192.168.178.111:5050/tv/power/off
```

### Lautstärke erhöhen
```bash
curl -X POST http://192.168.178.111:5050/tv/volume \
  -H "Content-Type: application/json" \
  -d '{"action": "up"}'
```

### Taste senden
```bash
curl -X POST http://192.168.178.111:5050/tv/key \
  -H "Content-Type: application/json" \
  -d '{"key": "KEY_MUTE"}'
```

### Netflix starten
```bash
curl -X POST http://192.168.178.111:5050/tv/app/open \
  -H "Content-Type: application/json" \
  -d '{"app_id": "Netflix"}'
```

### HDMI 1 auswählen
```bash
curl -X POST http://192.168.178.111:5050/tv/source \
  -H "Content-Type: application/json" \
  -d '{"source": "hdmi1"}'
```

## Verfügbare Tasten (Keys)

### Navigation
- `KEY_UP`, `KEY_DOWN`, `KEY_LEFT`, `KEY_RIGHT`
- `KEY_ENTER`, `KEY_RETURN`, `KEY_EXIT`
- `KEY_HOME`, `KEY_MENU`, `KEY_INFO`

### Power
- `KEY_POWER`, `KEY_POWEROFF`

### Lautstärke
- `KEY_VOLUP`, `KEY_VOLDOWN`, `KEY_MUTE`

### Kanal
- `KEY_CHUP`, `KEY_CHDOWN`
- `KEY_0` bis `KEY_9`

### Quellen
- `KEY_SOURCE`
- `KEY_HDMI1`, `KEY_HDMI2`, `KEY_HDMI3`, `KEY_HDMI4`
- `KEY_TV`

### Wiedergabe
- `KEY_PLAY`, `KEY_PAUSE`, `KEY_STOP`
- `KEY_REWIND`, `KEY_FF` (Fast Forward)
- `KEY_RECORD`

### Farbtasten
- `KEY_RED`, `KEY_GREEN`, `KEY_YELLOW`, `KEY_BLUE`

## n8n Integration

### Von n8n aus aufrufen (im gleichen Docker-Netzwerk)

Da beide Container im `n8n-net` Netzwerk sind, kann n8n den Service
direkt über den Container-Namen erreichen:

```
URL: http://samsung-tv-api:5000/tv/power/off
```

### HTTP Request Node Konfiguration

1. **Method:** POST
2. **URL:** `http://samsung-tv-api:5000/tv/key`
3. **Body Content Type:** JSON
4. **Body:**
   ```json
   {
     "key": "KEY_VOLUP"
   }
   ```

### Beispiel-Workflow importieren

Die Datei `n8n-workflow-example.json` enthält einen Beispiel-Workflow
zum Importieren in n8n.

## Troubleshooting

### TV nicht erreichbar

1. Prüfe ob TV eingeschaltet ist (im Standby funktioniert nur Wake-on-LAN)
2. Prüfe IP-Adresse: `ping 192.168.178.XXX`
3. Prüfe ob Port 8002 offen ist: `nc -zv 192.168.178.XXX 8002`

### "Verbindung abgelehnt"

- Wurde die Verbindung am TV erlaubt?
- Token-Datei löschen und neu verbinden:
  ```bash
  rm /opt/docker/samsung-tv-api/tv-token.txt
  docker-compose restart samsung-tv-api
  ```

### Wake-on-LAN funktioniert nicht

1. Am TV: Einstellungen → Allgemein → Netzwerk → Experteneinstellungen →
   **Einschalten mit Mobilgerät** aktivieren
2. MAC-Adresse in `.env` korrekt eingetragen?
3. Broadcast funktioniert nur im gleichen Subnetz

### Container-Logs prüfen

```bash
docker logs -f samsung-tv-api
```