KATHREIN UFScontrol-API Dokumentation

Version: 0.9

Autor: KATHREIN-Team

Datum: 06.08.2013

E-Mail:

ufscontrol.api @kathrein.de

KATHREIN-Werke KGAnton-Kathrein-Str. 1-3

P.O. Box 10 04 4483004 Rosenheim, Germany

www.kathrein.de

Disclaimer

Haftung für Inhalte

Die Beschreibung unserer UFScontrol-API wurden mit größter Sorgfalt erstellt. Für die Richtigkeit, Vollständigkeit und Aktualität der UFScontrol-API können wir jedoch keine Gewähr übernehmen.

Urheberrecht

Die erstellten Inhalte und Werke auf dieser UFScontrol-API unterliegen dem deutschen Urheberrecht. Die Vervielfältigung, Bearbeitung, Verbreitung und jede Art der Verwertung außerhalb der Grenzen des Urheberrechtes bedürfen der schriftlichen Zustimmung der Firma KATHREIN.

Die UFScontrol-API ist nur für den privaten, nicht kommerziellen Gebrauch gestattet.

Sollten Sie trotzdem auf eine Urheberrechtsverletzung aufmerksam werden, bitten wir um einen entsprechenden Hinweis. Bei Bekanntwerden von Rechtsverletzungen werden wir die UFScontrol-API umgehend ändern.

Wir behalten uns vor, die UFScontrol-API jederzeit ohne Angaben von Gründen zu verändern und optimieren.

UFScontrol-API www.kathrein.de Seite 2

Inhaltsverzeichnis1. Einleitung................................................................................................................52. Interfaces................................................................................................................7

2.1. RCU-Interface...................................................................................................72.2. XML-Interface...................................................................................................7

2.2.1. Device Info................................................................................................82.2.2. Channel Table...........................................................................................92.2.3. Favorite Table.........................................................................................102.2.4. Current EPG Table...................................................................................102.2.5. Schedule EPG Table...............................................................................112.2.6. Timer Table.............................................................................................132.2.7. Series Timer Table..................................................................................132.2.8. Archive Table..........................................................................................142.2.9. Detailed Info............................................................................................15

2.3. Command Interface.......................................................................................162.3.1. Change Channel......................................................................................162.3.2. Set Timer.................................................................................................172.3.3. Set External Timer..................................................................................172.3.4. Delete Timer...........................................................................................182.3.5. Delete Recording.....................................................................................192.3.6. Set Series Timer......................................................................................192.3.7. Delete Series Timer.................................................................................19

2.4. Text Interface ................................................................................................202.4.1. Text Input................................................................................................202.4.2. Get Text..................................................................................................20

3. Streaming.............................................................................................................213.1. Live-Streaming...............................................................................................213.2. Streaming von Aufnahmen............................................................................21

4. Revisions..............................................................................................................22

UFScontrol-API www.kathrein.de Seite 3

UFScontrol-API www.kathrein.de Seite 4

1 Einleitung

Die UFScontrol-API wurde speziell mit Hinblick auf die Kommunikation bzw. Steuerung des Receivers über mobile Endgeräte (Smartphones, Tablets) entwickelt. Durch die Notwendigkeit mehrere Platformen (Android, iOS, etc.) zu unsterstützen werden als Basis für diese API grundlegende Webtechnologien verwendet, die von allen gängigen Betriebssystemen unterstützt werden.

Die Kommunikation mit dem Receiver findet über das HTTP-Protokoll statt. Alle Kommandos werden mittels HTTP-GET gesendet. Manche Befehle können durch spezifische Variablen in der URL parametrisiert werden, um beispielsweise die Anzahl der Elemente die zurückgeliefert werden einzugrenzen.

Alle Daten werden vom Receiver in eine XML-Struktur verpackt und im HTTP-Body zurückgeliefert.

Beispiel:

Eine typischer http-Request zum Abruf der EPG-Daten:

http://192.168.178.20:9000/xmlfeeds/currentEpgTable?start-index=1&max-results=50?start-time=1287512100

Dieser Aufruf liefert maximal 50 Einträge aus der Epg-Tabelle ab 20:15. Eine genaue Aufstellung und Beschreibung der einzelnen Befehle und Parameter findet sich in Abschnitt 2.

<?xml version="1.0" encoding="utf-8"?>

<channelTable>

<channel>

<channelName>Das Erste HD</channelName>

<channelNumber>1</channelNumber>

<sdChannelNumber>98</sdChannelNumber>

<hd>1</hd>

<tvtvId>4162</tvtvId>

<dvb>1.1019.10301</dvb>

<channelIcon>/tvtv/4162</channelIcon>

<title>Sturm der Liebe (1812)</title>

<progress>22</progress>

<catIcon>/icon/2</catIcon>

<startTime>1375343700</startTime>

<endTime>1375346700</endTime>

<progId>813805201</progId>

</channel>

....

</channelTable>

UFScontrol-API www.kathrein.de Seite 5

Unterstützte Receiver :

Modell *

UFS 912

UFS 913

UFS 922

UFS 923

UFS 924

UFS 925

UFS 935

* Nicht alle UFScontrol-API-Funktionen werden von allen Geräten unterstützt

UFScontrol-API www.kathrein.de Seite 6

UFScontrol-API www.kathrein.de Seite 7

2 Interfaces

Für alle URLs gilt, dass nur ASCII-Zeichen enthalten sein dürfen. Zeichen außerhalb des ASCII-Zeichensatzes müssen escaped werden (siehe RFC 1738).

Zeitangaben sind, falls nicht explizit anders angegeben, als Sekunden ab dem 01.01.1970 0:00 Uhr UTC zu verstehen.

Legende:

Grüner Text = Platzhalter

2.1 RCU-InterfaceDas Fernbedienungsinterface bildet die Möglichkeiten der Bedienung via RCU ab, d.h. fast alle Tasten der RCU können an den Receiver gesendet werden.

Url: http://IP-ADRESSE:9000/HandleKey/ KEY

KEY bezeichnet die entsprechende Taste, siehe unten.

tvr standby

0, 1, 2, 3, 4 ... , 9 text

menu vol+ / vol

p+ / p- info

mute fav / pip / opt / tvr

epg archiv

up / down / right / left media

back fback / play / fforward

pause / rec / stop

UFScontrol-API www.kathrein.de Seite 8

2.2 XML-InterfaceDas XML-Interface ermöglicht den lesenden Zugriff auf Kanallisten, EPG-Daten und Aufnahmetimer.

Im folgenden Abschnitt wird jedes Kommando mit seinen Parametern aufgelistet und die möglichen Rückgabewerte aufgeschlüsselt.

2.2.1 Device InfoLiefert Informationen über den aktuellen Zustand des Receivers.

Url:

http://IP-ADRESSE:9000/xmlfeeds/deviceInfo

Aufbau der Antwort:

<?xml version="1.0" encoding="utf-8"?>

<deviceInfoTable>

<deviceInfo> ... </deviceInfo>

<deviceInfo> ... </deviceInfo>

...

</deviceInfoTable>

Elemente von < deviceInfo > :

Tag Typ / Werte Beschreibung

xmlInterfaceVersion alphanumerisch Die Versionsnummer dieses Interfaces. Nicht alle Daten oder Funktionen sindfür alle Versionen des Interfaces verfügbar.

ipAdress alphanumerisch Netzwerkadresse des Gerätes.

productType alphanumerisch Modellbezeichnung

VirtualStandBy 'FALSE', 'TRUE' 'TRUE' wenn eine Aufnahme läuft und alle Ausgänge abgeschalten sind

textInput '0', '1' Falls der Focus des Receivers auf einem Texteingabefeld liegt ist dieser Wert 1 (Siehe Abschnitt 2.3.6).

TVGenial numerisch Wenn vorhanden wird TVGenial unterstützt

liveChannel alphanumerisch Das Programm welches aktuell wiedergegeben wird. Format: TYPE.CHANNELNUMBER. Mögliche Typen: TV, RADIO. Beispiel: TV.3

redBull 'YES' Zeigt an ob dieser Receiver RedBull-Features unterstützt (aktuell nur UFS-924)

wol 'YES' Receiver unterstützt Wake-on-Lan und ist eingeschalten

mac alphanumerisch Die Mac-Adresse der Netzwerkschnittstelle

UFScontrol-API www.kathrein.de Seite 9

2.2.2 Channel TableAbrufen der Gesamtliste im XML-Format.

Url:

http://IP-ADRESSE:9000/xmlfeeds/channelTable

Parameter:

Parameter Typ / Werte Beschreibung

start-index numerisch Index des ersten Eintrags der geladen werden soll

max-results numerisch Maximal Anzahl an Einträgen die zurückgeliefert werden dürfen

favorite-nr numerisch [ '1' ... '8' ] Liefert nur die Einträge der entsprechenden Favoritenliste (siehe 2.2.3)

channel-type 'tv', 'radio' Default: 'tv'. Wählt zwischen der Liste für TV bzw. Radio aus.

Aufbau der Antwort:

<?xml version="1.0" encoding="utf-8"?>

<channelTable>

<channel> ... </channel>

<channel> ... </channel>

...

</channelTable>

Elemente von < channel > :

Tag Typ / Werte Beschreibung

channelName alphanumersich Der Bezeichner des Programms

channelNumber numerisch Die Programmnummer nach der Sortierreihenfolge in der Gesamtliste.

streamable 'NO', 'YES' Gibt an ob das Streaming (siehe Kapitel 3) dieses Programms möglich ist.

tuneable 'NO', 'YES' Zeigt ob das Programm in der aktuellen Antennenkonfiguration empfangbar ist.

sdChannelNumber numerisch Für HD-Programme, falls bekannt und vorhanden, die Programmnummer des entsprechenden SD-Programms.

sdStreamable 'NO', 'YES' Gibt an ob das Streaming des SD-Programms möglich ist.

hd '0', '1' '1' falls dieses Programm in HD-Qualität ausgestrahlt wird.

tvtvId numerisch Bezeichnet dieses Programm für den Service von tvtv.

dvb alphanumerisch DVB-URI (ETSI TS 102 851)

channelIcon alphanumerisch Über die http://IP-ADRESSE:9000/tvtv/ channelIcon kann das Sernderlogo geladen werden, falls vorhanden.

UFScontrol-API www.kathrein.de Seite 10

2.2.3 Favorite TableUrl:

http://IP-ADRESSE:9000/xmlfeeds/favoriteTable

Parameter:

-

Aufbau der Antwort:

<?xml version="1.0" encoding="utf-8"?>

<favoriteTable>

<favorite> ... </favorite>

<favorite> ... </favorite>

...

</favoriteTable>

Elemente von <favorite>:

Tag Typ / Werte Beschreibung

name alphanumerisch Name der Favoritenliste

favoriteNr numerisch Nummer der Favoritenliste

UFScontrol-API www.kathrein.de Seite 11

2.2.4 Current EPG TableZeigt die EPG-Daten aller Programme zu einem bestimmten Zeitpunkt an.

Url:

http://IP-ADRESSE:9000/xml feeds/cur rentEpgTable

Parameter:

Parameter Typ / Werte Beschreibung

start-index numerisch Nummer des ersten Programms das zurückgeliefert werden soll

max-results numerisch Maximal Anzahl an Einträgen die zurückgeliefert werden dürfen

start-time numerisch [UTC in s] Nur Events die zu dieser Zeit oder danach beginnen werden zurückgeliefert. Wird keine start-time übergeben, wird die aktuelle Uhrzeit verwendet.

favorite-nr numerisch [ '1' ... '8' ] Liefert nur die Einträge der entsprechenden Favoritenliste (siehe 2.2.3)

Aufbau der Antwort:

<?xml version="1.0" encoding="utf-8"?>

<channelTable>

<channel> ... </channel>

...

</channelTable>

Elemente von < channel > :

Tag Typ / Werte Beschreibung

channelName alphanumerisch Siehe 2.2.2

channelNumber numerisch Siehe 2.2.2

tvtvId numerisch Siehe 2.2.2

channelIcon alphanumerisch Siehe 2.2.2

dvb alphanumerisch Siehe 2.2.2

title alphanumerisch Die Bezeichnung des Events

progress numerisch [ '0', ..., '100' ]

Die aktuelle Spieldauer im Verhältnis zur Gesamtlänge

catIcon alphanumerisch Über die http://IP-ADRESSE:9000/ icon / catIcon kann das Icon für Kategorien(z.B. Live, Film, Serien) geladen werden.

startTime numerisch Zeitpunkt des Beginns des Events.

endTime numerisch Endzeitpunkt des Events

progId numerisch ID eines Events. Wird nicht verwendet.

UFScontrol-API www.kathrein.de Seite 12

2.2.5 Schedule EPG TableLiefert die EPG-Daten eines bestimmten Programms.

Url:

http://IP-ADRESSE:9000/xmlfeeds/scheduleEpgTable

Parameter:

Parameter Typ / Werte Beschreibung

start-index numerisch channelNumber des gewünschten Programms

max-results numerisch maximale Anzahl der Einträge die zurückgeliefert werden

start-time numerisch [UTC in s] Nur Events die mit diesem Zeitpunkt, oder später beginnen werden zurückgeliefert. (Default: aktuelle Zeit)

Aufbau der Antwort:

<?xml version="1.0" encoding="utf-8"?>

<scheduleEpgTable>

<event> ... </event>

<event> ... </event>

...

</scheduleEpgTable>

Elemente von < event > :

Tag Typ / Werte Beschreibung

title alphanumerisch Die Bezeichnung des Events

progress numerisch [ '0', ..., '100' ]

Die aktuelle Spieldauer im Verhältnis zur Gesamtlänge

catIcon alphanumerisch Siehe 2.2.4

startTime numerisch Zeitpunkt des Beginns des Events.

endTime numerisch Endzeitpunkt des Events

progId numerisch Siehe 2.2.4

UFScontrol-API www.kathrein.de Seite 13

2.2.6 Timer TableInformation über geplante Aufnahmen und Serientimer.

Url:

http://IP-ADRESSE:9000/xmlfeeds/timerTable

Parameter:

Parameter Typ / Werte Beschreibung

once-only 'true', 'false' Wenn 'true' werden keine Serientimer geliefert

Aufbau der Antwort:

<?xml version="1.0" encoding="utf-8"?>

<timerTable>

<timerevent> ... </timerevent>

<timerevent> ... </timerevent>

...

</timerTable>

Elemente von < timerevent > :

Tag Typ / Werte Beschreibung

title alphanumerisch Die Bezeichnung des Events

timerNo numerisch ID des Timers

seriesTimerNo numerisch ID des Serientimers

channelName alphanumerisch Name des Programms

tvtvId numerisch Siehe 2.2.2

startTime numerisch Zeitpunkt des Beginns des Events.

endTime numerisch Endzeitpunkt des Events

channelIcon alphanumerisch Siehe 2.2.2

catIcon alphanumerisch Siehe 2.2.4

UFScontrol-API www.kathrein.de Seite 14

2.2.7 Series Timer TableListet wiederkehrende Aufnahmetimer auf.

Url:

http://IP-ADRESSE:9000/xmlfeeds/seriesTimerTable

Parameter:

-

Aufbau der Antwort:

<?xml version="1.0" encoding="utf-8"?>

<seriesTimerTable>

<seriesTimerEvent> ... </seriesTimerEvent>

<seriesTimerEvent> ... </seriesTimerEvent>

...

</seriesTimerTable>

Elemente von <seriesTimerEvent>:

Tag Typ / Werte Beschreibung

title alphanumerisch Bezeichnung der Serienaufnahme

seriesTimerNo numerisch ID der Serienaufnahme

channelNumber numerisch Siehe 2.2.2

channelName alphanumerisch Siehe 2.2.2

catIcon alphanumerisch Siehe 2.2.4

channelIcon alphanumerisch Siehe 2.2.2

seasonId numerisch ID der Staffel. Stimmt mit der echten Staffelnummer überein.

UFScontrol-API www.kathrein.de Seite 15

2.2.8 Archive TableListe der Aufnahmen.

Url:

http://IP-ADRESSE:9000/xmlfeeds/archiveTable

Parameter:

Parameter Typ / Werte Beschreibung

folder-nr numerisch Nur Einträge zu bestimmten Verzeichnissen

rootcontainer-id numerisch ID des physikalischen Mediums

Aufbau der Antwort:

<?xml version="1.0" encoding="utf-8"?>

<archiveTable>

<recordingevent> ... </recordingevent>

<recordingevent> ... </recordingevent>

...

</archiveTable>

Elemente von <recordingEvent>:

Tag Typ / Werte Beschreibung

title alphanumerisch Die Bezeichnung des Events

catIcon alphanumerisch Siehe 2.2.4

archiveNo numerisch ID des Events

parentFolder numerisch ID des übergeordneten Verzeichnisses

rootContainer numerisch Identifiziert das physikalische Medium (z.B. Festplatte) auf dem die Aufnahme gespeichert ist.

isFolder '0', '1' Event beschreibt ein Verzeichnis wenn isFolder = 1

startTime numerisch [UTC in s] Das Datum an dem die Aufnahme gestartet wurde

duration numerisch [min] Die Dauer des Events

UFScontrol-API www.kathrein.de Seite 16

2.2.9 Detailed InfoDetailiertere Informationen zu einem EPG-Event.

Url:

http://IP-ADRESSE:9000/xmlfeeds/detailedInfo

Parameter:

Parameter Typ / Werte Beschreibung

start-index numerisch channelNumber des Events

start-time numerisch [UTC in s] Die Startzeit des gewünschten Eintrags (muss genau mit der Startzeit des Eintrags übereinstimmen!)

Aufbau der Antwort:

<?xml version="1.0" encoding="utf-8"?>

<detailedInfoTable>

<channel> ... </channel>

<event> ... </event>

</detailedInfoTable>

Elemente von <channel>:

Tag Typ / Werte Beschreibung

channelName alphanumerisch Siehe 2.2.2

channelNumber numerisch Siehe 2.2.2

channelIcon alphanumerisch Siehe 2.2.2

Elemente von <event>:

Tag Typ / Werte Beschreibung

title alphanumerisch Die Bezeichnung des Events

longInfo alphanumerisch Detailierter Infotext

startTime numerisch [UTC in s] Begin des Events

endTime numerisch [UTC in s] Ende des Events

progId numerisch Siehe 2.2.4

UFScontrol-API www.kathrein.de Seite 17

2.3 Command InterfaceÜber das Command-Interface werden einfache Kommandos an den Receiver gesendet, welche mit Ausnahme der Texteingabe unabhängig vom Zustand des Receivers (im laufenden Betrieb) sind.

Alle Kommandos werden Erfolgsunabhängig mit einem HTTP-Response 200 (OK) quittiert. Ob ein Kommando erfolgreich ausgeführt wurde, muss durch Abruf der entsprechenden Liste (siehe Kapitel 2.2) kontrolliert werden.

2.3.1 Change ChannelWechselt den Sender.

Url:

http://IP-ADRESSE:9000/cmds/changeChannel

Parameter:

Parameter Typ / Werte Beschreibung

channel-no numerisch Sendernummer des gewünschten Programms (referenziert die Gesamtliste)

2.3.2 Set TimerProgrammieren eines Timers auf ein Event des EPGs.

Url:

http://IP-ADRESSE:9000/cmds/setTimer

Parameter:

Parameter Typ / Werte Beschreibung

channel-no numerisch Sendernummer des gewünschten Programms (referenziert die Gesamtliste)

start-time numerisch [UTC in s] Die Startzeit des gewünschten Eintrags (muss genau mit der Startzeit des Eintrags übereinstimmen!)

tvtv-Id numerisch Siehe 2.2.2

UFScontrol-API www.kathrein.de Seite 18

2.3.3 Set External TimerProgrammieren eines Aufnahmetimers unter Angabe von Start- und Endzeit (tvtv-id nicht erforderlich).

Url:

http://IP-ADRESSE:9000/cmds/set External Timer

Parameter:

Parameter Typ / Werte Beschreibung

channel-no numerisch Sendernummer des gewünschten Programms (referenziert die Gesamtliste)

start-time numerisch [UTC in s] Die Startzeit

end-time numerisch [UTC in s] Die Endzeit der Aufnahme

channel-type 'tv', 'radio' Default: 'tv'. Wählt zwischen der Liste für TV bzw. Radio aus.

repeated-days numerisch Wochentage an denen sich die Aufnahme wöchentlich wiederholen soll, binär codiert.

Bit 0: Montag … Bit 7: Sonntag

Bsp.: Wert: 66, bedeutet wiederholende Aufnahme Dienstags und Sonntags

66 = 1000010b

2.3.4 Delete TimerLöschen eines Aufnahmetimers.

Url:

http://IP-ADRESSE:9000/cmds/ deleteTimer

Parameter:

Parameter Typ / Werte Beschreibung

timer-no numerisch ID des timers (siehe 2.2.5)

UFScontrol-API www.kathrein.de Seite 19

2.3.5 Delete RecordingLöschen einer Aufnahme aus dem Archiv und vom physikalischen Medium.

Url:

http://IP-ADRESSE:9000/cmds/ deleteRecording

Parameter:

Parameter Typ / Werte Beschreibung

recorderkey-id numerisch ID der Aufnahme (siehe 2.2.6)

rootcontainer-id numerisch ID des Mediums (siehe 2.2.6)

2.3.6 Set Series TimerDieses Kommando ermöglicht das programmieren neuer Serienaufnahmen. Die Start- und Endzeiten beziehen sich auf die erste Aufnahme der Serie.

Url:

http://IP-ADRESSE:9000/cmds/ setSeriesTimer

Parameter:

Parameter Typ / Werte Beschreibung

start-time numerisch [UTC in s] Beginn der ersten Serienaufnahme

end-time numerisch [UTC in s] Ende der ersten Aufnahme

channel-no numerisch Sendernummer des gewünschten Programms (referenziert die Gesamtliste)

tvtv-Id numerisch Siehe 2.2.2

2.3.7 Delete Series TimerLöschen von Serienaufnahmen.

Url:

http://IP-ADRESSE:9000/cmds/deleteSeriesTimer

Parameter:

Parameter Typ / Werte Beschreibung

timer-no numerisch ID des Aufnahmetimers (siehe 2.2.5)

UFScontrol-API www.kathrein.de Seite 20

2.4 Text Interface

2.4.1 Text InputErmöglicht die Texteingabe in diversen Textfeldern (Suche, Einstellungen etc.). Hat ein Textfeld auf dem Receiver den aktivenFocus (siehe 2.2.1) werden Eingaben dieses Kommandos direkt an das entsprechende Feld weitergeleitet.

Url:

http://IP-ADRESSE:9000/newTextInput/ TEXT

Escaping:

Da in URLs nur Zeichen des ASCII-character-set erlaubt sind müssen alle Zeichen außerhalb dieses Zeichensatzes escaped werden (siehe RFC 1738).

2.4.2 Get TextZurücklesen des Textes im aktuell aktiven Textfeld (siehe 2.2.1)

Url:

http://IP-ADRESSE:9000/getTextInput

Escaping:

siehe 2.4.1

UFScontrol-API www.kathrein.de Seite 21

3 Streaming

Das Container-Format der Streams ist MPEG-TS.

Mögliche Videocodecs Mögliche Audiocodecs

MPEG-2 MPEG-1 Layer 2 Audio

H.264/MPEG-4 AVC AAC

3.1 Live-StreamingUrl:

http://IP-ADRESSE:49152/content/live-streaming/liveStream-http- channelNumber -1.ts

Parameter:

channelNumber ist die Nummer des Programms in der Gesamtliste.

3.2 Streaming von AufnahmenUrl:

http://IP-ADRESSE:49152/content/ internal-recording / rootContainer /record/ archiveId / record.ts

Parameter:

rootContainer bezeichnet das physikalische Medium (siehe 2.2.8)

archiveId siehe 2.2.8

UFScontrol-API www.kathrein.de Seite 22

4 Revisions

Version Autoren Änderung Datum

0.8 KATHREIN-Team Erstellung dieses Dokuments 06.08.2013

0.9 KATHREIN-Team Bugfixes 30.09.2013

UFScontrol-API www.kathrein.de Seite 23