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

# 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

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

curl -X POST http://192.168.178.111:5050/tv/power/off

Lautstärke erhöhen

curl -X POST http://192.168.178.111:5050/tv/volume \
  -H "Content-Type: application/json" \
  -d '{"action": "up"}'

Taste senden

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

Netflix starten

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

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:

   {
     "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:

  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

docker logs -f samsung-tv-api