Remotecontrol

remotecontrol
Zweck / Funktion
Grafische Darstellung einer Fernbedienung
Allgemein
Typ	Hilfsmodul
Details
Dokumentation	EN / DE
Modulname	95_remotecontrol.pm
Ersteller	ulimaass
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Grafische Darstellung einer Fernbedienung

Das Modul remotecontrol stellt einen Weblink bereit, der eine grafische Abbildung einer physischen Fernbedienung anzeigt, siehe Beispiel rechts. Dieser Weblink kann in FHEM-Frontends wie FHEMWEB oder FLOORPLAN verwendet werden.

Die Tastenbelegung (das Layout) ist frei wählbar. Standard-Layouts sind für unterschiedliche Geräte verfügbar. Das remotecontrol-device wird per notify an das FHEM-device gekoppelt, das nach einem Tastendruck den Befehl an das physische Gerät sendet.

Einrichtung

Define

Das define erfolgt nach der üblichen FHEM-Syntax:

# Syntax:
define <name> remotecontrol
# Beispiel:
define rc1 remotecontrol

Damit ist eine leere Fernbedienung (zunächst noch ohne Tasten) angelegt.

Zu Testzwecken kann man sein Device zunächst einem Testraum zuordnen, z. B.

attr rc1 room TestRemote

Standard-Tastaturlayouts nutzen

Jedes FHEM-Modul kann Tastaturlayouts für das Modul remotecontrol bereitstellen.

Die Liste der vorhandenen Tastaturlayouts wird angezeigt mit

# Syntax:
get <name> layout
# Beispiel:
get rc1 layout 

Die Liste der vordefinierten Tastaturlayouts wird nun angezeigt.

Ein Tastatur-Layout kann zugeordnet (geladen) werden mit

# Syntax:
set <name< layout <layoutname<
# Beispiel:
set rc1 layout itunes  

Hinweis: Das Laden von Standard-Layouts ändert die Werte der Attribute row00 - row19. Diese werden erst durch den Befehl save nach fhem.cfg geschrieben. Soll der Befehl save nicht verwendet werden, kann die Konfiguration auch manuell in fhem.cfg eingetragen werden. Ein Beispiel befindet sich am Ende dieses Wiki-Artikels.

Hinweis: Ein Standard-Tastaturlayout wird erst nach dem Laden eines Moduls bereitgestellt. Wenn Sie also erst zu einem späteren Zeitpunkt ein weiteres Modul (z.B. VIERA für Panasonic-TV) in Ihre Konfiguration aufnehmen, wird ein ggf. vorhandenes remotecontrol-Standard-Layout erst dann angezeigt. Man sollte also auch später ab und zu mit dem o.g. Befehl prüfen, ob für weitere Geräte Standardlayouts vorhanden/hinzugekommen sind.

Im Modul remotecontrol selbst sind die Beispiel-Layouts "itunes" und "samsung" vorhanden.

Eigene Tastaturlayouts einrichten

Die Tastatur der Fernbedienung ist aufgeteilt in bis zu 20 Zeilen. Je Zeile können beliebig viele Tasten definiert werden.

Jede Taste auf der Fernbedienung wird definiert durch

• den Befehl, der nach einem Tastendruck ausgeführt werden soll
• das icon, das als Taste erscheinen soll

Man muss also je Taste diese beiden Werte festlegen. Mehrere Tasten in einer Zeile werden jeweils durch ein Komma voneinander getrennt.

Icon-Pfad festlegen

Einmalig ermitteln, in welchem Ordner die Icons liegen, die für die Tastatur verwendet werden sollen. Die Standard-icons liegen im Ordner www/images/default/remotecontrol. Um das nicht bei jeder Taste angeben zu müssen, setzt man

attr <name> rc_iconpath icons/remotecontrol

Icon-Prefix festlegen

Ggf. einmalig einen prefix für Dateinamen festlegen. Die Standard-icons folgen der Namenskonvention black_btn_<Beschreibung>. Um den Teil vor der Beschreibung nicht bei jeder Taste mit angeben zu müssen, setzt man

attr <name> rc_iconprefix black_btn_

Tasten definieren

1. ermitteln, welcher Befehl an das ausführende FHEM-Gerät gesendet werden soll. Als Beispiel soll der Befehl "play" dienen. Groß-/Kleinschreibung ist zu beachten.
2. ermitteln, welches Icon zur Darstellung der Taste verwendet werden soll. Unter den Standardicons gibt es ein icon mit dem Dateinamen black_btn_PLAY.png. Der vordere Teil ist bereits als prefix hinterlegt, die Datei-Endung muss nicht angegeben werden. Als icon für die Tastaturdefinition kann man also einfach PLAY angeben. Groß-/Kleinschreibung ist zu beachten.

Nachdem nun der Befehl (play) und der Icon-Name (PLAY) ermittelt sind, können diese - durch einen Doppelpunkt getrennt - als Definition einer Taste hinterlegt werden.

# Syntax: 
attr <name> rowXX <command>:<icon>
# Beispiel:
attr rc1 row00 play:PLAY         # als Befehl wird play gesendet, als icon wird PLAY verwendet

Sollen weitere Tasten definiert werden, hängt man sie durch Komma getrennt an.

# Syntax: 
attr <name> rowXX <command>:<icon>[,<command>:<icon>][,....]
# Beipiel:
attr rc1 row01 play:PLAY,anhalten:STOP

Sollen auf der Tastatur Leer-Räume abgebildet werden, gibt man als Tastendefinition :blank an (also kein Befehl, Icon blank). Das Icon mit dem Namen 'blank' ist vorhanden, hat ein Drittel der regulären Tastenhöhe und ist 100% transparent.

attr rc1 row02 play:PLAY,:blank,anhalten:STOP

Eine "Trennzeile" lässt sich einfügen durch

attr rc1 row03 :blank,:blank,:blank

Hinweis: Manche Browser stellen in einer Zeile, in der die letzte Taste nicht definiert ist, den Rahmen nicht dar. Füllen Sie in diesem Fall die Tastaturzeile mit :blank soweit auf, dass sie dieselbe Anzahl Tasten aufweist wie die längste Tastaturzeile auf Ihrer Fernbedienung.

Für den Fall, dass der Befehl und der Icon-Name identisch sind (incl. Groß-/Kleinschreibung) besteht zur Vereinfachung die Möglichkeit, nur das Kommando anzugeben. Dieses wird dann auch als icon-Name verwendet.

# Syntax: 
attr <name> rowXX [<command>:<icon>|<command_icon>][,[<command>:<icon>|<command_icon>]]...
# Beispiele:
attr rc1 row04 PLAY                           # als Befehl wird PLAY gesendet, als icon wird PLAY verwendet
attr rc1 row05 PLAY,:blank,anhalten:STOP      # auch Mischformen sind möglich

Verwenden von .svg-icons

Endet der Dateiname nicht auf .svg, verhält sich die die img-Generierung wie oben beschrieben unter Beachtung von rc_iconpath und rc_iconprefix.

Enthält der angegebene Dateiname ".svg" , so wird der svg-Lesemechanismus aus FHEMWEB verwendet. Dabei werden die Attribute rc_iconpath und rc_iconprefix ignoriert, es wird die "ganz normale" Zugriffsfolge verwendet wie im FHEMWEB-Attribut iconPath gesetzt (z. B. fhemSVG:openautomation:default)

Attributes:
   rc_iconpath icons
   row00       play:audio_play.svg                    # svg-icon ohne Farbangabe
   row01       oldplay:remotecontrol/black_btn_PLAY   # nicht-svg-icon, Pfadangabe bei iconpath "icons"
   row02       redplay:audio_play.svg@red             # svg-icon mit Farbangabe

Neue Icons für Tasten erstellen und verwenden

Im Ordner www/images/default/remotecontrol liegt das Template für weitere Tasten. Die Datei heisst _black_btn_template.pdn und kann z. B. mit paint.net bearbeitet werden.

Neue Dateien bitte als png analog der vorhandenen Namenskonvention erstellen: Prefix black_btn_, Beschreibung in Grossbuchstaben.

Zur Erweiterung des icon-Vorrats neue Dateien bitte zum Einchecken an den Modulautor mailen.

Hinweis: Neue Dateien werden in FHEM erst angezeigt, nachdem das interne Icon-Listing aktualisiert wurde. Dies geschieht nach jedem FHEM-(re)start oder mit dem Befehl

set WEB rereadicons

Kopplung an das ausführende Gerät

Bei jedem Tastendruck wird der Befehl (command), der der Taste zugeordnet ist, als STATE des remotecontrol-device angezeigt.

Ausserdem wird ein entsprechendes System-Event erzeugt. Dieses kann mit notify geprüft und an das ausführende Gerät weitergegeben werden.

Als Beispiel soll wie oben gezeigt eine Fernbedienung mit dem Namen rc1 bereits erstellt worden sein. Tastendrucke sollen zur Ausführung an das bereits vorhandene FHEM-device myTV weitergegeben werden.

Das entsprechende notify kann "manuell" oder per set-Befehl erzeugt werden:

# Syntax: 
set <name> makenotify <executingDevice>
# Beispiel:
set rc1 makenotify myTV               #erzeugt: define notify_rc1 notify rc1 set myTV $EVENT

Bei jedem Tastendruck löst die Fernbedienung rc1 ein event aus. Darauf reagiert das notify und sendet den entsprechenden set-Befehl an das Gerät myTV zur Ausführung.

Hinweis: Der Befehl makenotify erzeugt ein neues notify-device. Dieses wird erst durch den Befehl save in die fhem.cfg geschrieben. Möchten Sie den Befehl save nicht verwenden, tragen Sie das notify manuell in fhem.cfg ein. Ein weiteres Beispiel befindet sich am Ende dieses Wiki-Artikels.

Es können auch eigene Scripte (z. B. in 99_myUtils.pm) aufgerufen werden. Wenn es z. B. dort eine Routine MeineRoutine($) gibt, kann diese mit der Fernbedienung gesteuert werden durch

define n_rc1 notify rc1 {MeineRoutine("$EVENT")}

Optional: Weblink erzeugen und einbinden

Zusätzlich zum remotecontrol-device selbst kann auch ein weblink zum Anzeigen der grafischen Fernbedienung verwendet werden. Beim Erzeugen des Weblinks kann man einen Namen angeben. Wird kein Name angegeben, wird der default-Name "weblink_<name>" verwendet.

set rc1 makeweblink             # erzeugt Weblink mit dem Namen weblink_rc1
set rc1 makeweblink w_rc1       # erzeugt Weblink mit dem Namen w_rc1

Zu Testzwecken kann man auch den Weblink einem Testraum zuordnen, z. B.

attr weblink_rc1 room TestRemote
attr weblink_rc1 group rc

Durch die Zuordnung zu einer Gruppe wird der Name des Weblinks ebenfalls angezeigt, was zum Testen sehr praktisch ist. Während der Einrichtungsphase ist zu empfehlen, in einem Fenster den Detailscreen des remotecontrol-device anzuzeigen, während man in einem zweiten Fenster den Weblink anzeigt. So kann man durch einfaches Refresh die Auswirkungen der Konfigurationsänderungen sofort sehen.

Hinweis: Der erzeugte weblink wird erst durch den Befehl save nach fhem.cfg geschrieben. Möchten Sie den Befehl save nicht verwenden, tragen Sie die Konfiguration manuell in fhem.cfg ein. Ein Beispiel befindet sich am Ende dieses Wiki-Artikels.

Troubleshooting

Eine Taste wird nicht angezeigt

• Groß/Kleinschreibung icon-Namens prüfen
• Nach dem Anlegen neuer icons muss ausgeführt werden

set WEB rereadicons

• Mit dem Befehl

get <name> htmlcode
den html-Code der grafischen Fernbedienung anzeigen. Darin suchen nach "<img src" und dann Link und Dateiname prüfen. Erwarteter Wert: <img src="/fhem/icons/remotecontrol/black_btn_PLAY">

Der rechte Rahmen wird mit Lücken dargestellt

Manche Browser stellen in einer Zeile, in der die letzte Taste gar nicht definiert ist, den Rahmen nicht dar. Füllen Sie in diesem Fall die Tastaturzeile mit :blank soweit auf, dass sie dieselbe Anzahl Tasten aufweist wie die längste Tastaturzeile auf Ihrer Fernbedienung.

Für Entwickler

Entwickler können aus ihren Modulen heraus Tastatur-Standardlayouts hinterlegen. Auch eine eigene Routine für makenotify ist möglich.

Neue Standard-Layouts hinterlegen

Standard-Layouts werden im eigenen Modul in Arrays abgelegt. Die Umwandung von Arrays in rowXX-Attribute sowie das Rendern zu html übernimmt das Modul remotecontrol.

Vorgehensweise im eigenen Modul:

1. Eine Funktion implementieren, die ein Array mit dem Standard-Tastaturlayout zurückgibt. Als Vorlage dient aus dem Quelltext von 95_remotecontrol.pm eine der Routinen RC_layout_samsung() oder RC_layout_itunes().
2. Im eigenen Modul in der Initialize-Funktion (nicht erst in der Define-Funktion!) einen Eintrag für $data{RC_layout}{<Layoutname>} vornehmen. Als Inhalt ist der Funktionsname der im ersten Schritt hinterlegten eigenen Layout-Funktion als Zeichenkette zu setzen.
   • Beispiel: Das Layout soll für den Nutzer MeinLayout heißen, die eigene Array-Routine heißt Mein_Modul_Layout(). Dafür ist in der eigenen Initialize-Funktion zu hinterlegen:

     $data{RC_layout}{MeinLayout} = "Mein_Modul_Layout";

     Als Vorlage kann wiederum das Modul 95_remotecontrol.pm dienen, siehe dort am Ende der Initialize-Funktion.
   • In einer definierten remotecontrol den Befehl

     get <name> layout

     absetzen. Das eigene Layout sollte nun in der Liste erscheinen.
   • Das eigene Layout kann dann mit

     set <name> layout <MeinLayout>

     geladen werden.

Eigene makenotify-Routine hinterlegen

Beim Aufruf von set <Device> makenotify wird ein notify erzeugt der Form

define <Name> notify <RC-Name> set <ausführendes Gerät> $EVENT

Das sollte in 90% der Fälle passen. Wenn für das eigene Modul jedoch ein abweichendes Kommando erforderlich ist, z. B.

set <ausführendes Gerät> command <Befehl>

dann passt das standardmäßig durch makenotify erzeugte notify nicht. In diesem Fall kann das notify durch eine eigene Routine angelegt werden. Dazu wird im eigenen Modul eine Routine zur Erzeugung des notify hinterlegt. Der Name der Routine wird wiederum in %data hinterlegt mit:

$data{RC_makenotify}{<Modulname>} = "Mein_Modul_Makenotify";

# Beispiel:
$data{RC_makenotify}{VIERA}  = "VIERA_makenotify";

Beim Aufruf von

set <rc> makenotify <ausführendes Gerät>

wird nun der TYPE von <ausführendes Gerät> ermittelt und gesucht, ob es einen passenden Eintrag in $data{RC_makenotify} gibt. Ist dieser vorhanden, wird die dort angegebene Routine aufgerufen. Als Beispiel kann das Modul VIERA dienen.

Beispiel-Layouts mit screenshots

iTunes

define rc_itunes remotecontrol

attr rc_itunes rc_iconpath icons/remotecontrol
attr rc_itunes rc_iconprefix black_btn_
attr rc_itunes row00      play:PLAY,pause:PAUSE,prev:REWIND,next:FF,louder:VOLUP,quieter:VOLDOWN

define weblink_itunes weblink htmlCode {fhem("get rc_itunes htmlcode", 1)}
define notify_itunes rc_itunes {doiTunes("$EVENT");}

Samsung

define rc_samsung remotecontrol

attr rc_samsung rc_iconpath   icons/remotecontrol
attr rc_samsung rc_iconprefix black_btn_
attr rc_samsung row00         POWEROFF,TV,HDMI
attr rc_samsung row01         :blank,:blank,:blank
attr rc_samsung row02         1,2,3
attr rc_samsung row03         4,5,6
attr rc_samsung row04         7,8,9
attr rc_samsung row05         :blank,0,PRECH
attr rc_samsung row06         :blank,:blank,:blank
attr rc_samsung row07         VOLUP,MUTE,CHUP
attr rc_samsung row08         VOLDOWN,CH_LIST,CHDOWN
attr rc_samsung row09         MENU,:blank,GUIDE
attr rc_samsung row10         :blank,:blank,:blank
attr rc_samsung row11         TOOLS,UP,INFO
attr rc_samsung row12         LEFT,ENTER,RIGHT
attr rc_samsung row13         RETURN,DOWN,EXIT

define weblink_rc_samsung weblink htmlCode {fhem("get rc_samsung htmlcode", 1)}
define notify_rc_samsung notify rc_samsung set myTV $EVENT