64bcc0091a
Architecture changes: - Created VM 100 "docker-services" (Debian 12 Cloud Image) - 10GB RAM, 6 Cores, 50GB system disk - Separate 100GB LVM data volume for service data - WireGuard moved from host to VM (10.0.0.2) - All containers migrated and running Updated documentation to reflect new architecture 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
185 lines
4.3 KiB
Markdown
185 lines
4.3 KiB
Markdown
# 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
|
|
```
|