Quelltext der Seite DMXControl

== Einleitung ==
Diese Seite zeigt, wie man die Integration von DMX-Geräten über die Windows-Software DMXControl in FHEM realisieren kann.

'''Hinweis: wer statt dem Erklärungstext die reine Konfiguration sucht, kann sie im [http://www.fhemwiki.de/wiki/DMXControl#Konfig-Zusammenfassung vorletzten Abschnitt] einsehen.'''

Funktionalität:
* Steuerung der DMX-Geräte via FHEMWEB oder der Android-App andFHEM mit Live-Colorpicker
* Abrufen von Effekten (z.B. Farbverläufe)

Benötigte Software & Module:
* FHEM
** [http://fhem.de/commandref.html#ECMD ECMD]
** [http://fhem.de/commandref.html#readingsProxy readingsProxy]
** [http://www.fhemwiki.de/wiki/Color Colorpicker]
** [http://fhem.de/commandref.html#LightScene Lightscene] (optional)
** [http://andfhem.klass.li andFHEM] (optional)

* [http://www.dmxcontrol.org DMXControl]
** [http://www.dmxcontrol.de/wiki/Terminal_Schnittstelle Terminal-Schnittstelle]

== Funktionsbeschreibung ==
In DMXControl werden die DMX-Geräte definiert und entsprechende Effekte wie Farbverläufe generiert.

FHEM stellt über das Modul ECMD eine Verbindung zur Terminal-Schnittstelle von DMXControl her.

Da im ECMD-Modul einige Befehle fehlen, werden diese über das readingsProxy-Modul simuliert. Dieses gibt die Befehle dann über das ECMD-Modul an DMXControl weiter.

Zur Bedienung von Farb-LEDs bietet sich der FHEMWEB-Colorpicker an, der auch über eine Live-Farbänderungsfunktion verfügt.

== DMXControl ==
[[Datei:DMXControl_Kanaele.png|thumb|DMXControl Kanalübersicht]]
[[Datei:DMXControl_Terminal.png|thumb|DMXControl Terminal]]
In meiner Konfiguration hat jede RGB-LED 5 DMX-Kanäle:
* 1 = Rot
* 2 = Grün
* 3 = Blau
* 4 = Master (Helligkeit)
* 5 = Strobe (Blinken)

Das Modul "PDA-Fernsteuerung" aka "[http://www.dmxcontrol.de/wiki/Terminal_Schnittstelle Terminal-Schnittstelle]" muss aktiviert sein. Ich benutze die Standard-Konfiguration auf COM1, 115200 kbps und Port 2145.

== ECMD-Modul ==
Damit die Farben im Format RRGGBB gesendet werden können, müssen für jede Farbe und die sonst  noch benötigten DMX-Kanäle eigene globale Userattribute erstellt werden. In alphabetischer Reihenfolge sieht das dann so aus:
 attr global userattr DMX_B DMX_G DMX_M DMX_R DMX_S

Jedes ECMDDevice benötigt eine eigene Konfigurationsdatei, eine sog. classdef.
In ihr wird beschrieben, welche Attribute konfiguriert werden können sollen.
Für die DMX-Geräte heisst sie bei mir DMXControl_Devices.classdef und liegt im FHEM\ECMD-Verzeichnis.

Sie fängt so an:
 params DMX_R DMX_G DMX_B DMX_M DMX_S

Dann kommt die Übersetzung der Befehle, die an die Terminal-Schnittstelle von DMXControl gesendet werden, jeweils für ein set und ein get.
ein set (ECMDDevice) rgb (Farbe RRGGBB) soll folgende Aktionen ausführen:

* Senden der Farbe Rot an den 1. Kanal der RGB-LED [in DMXControl: "sc (DMX-Kanal 1) (Rot-Wert)"]
* Senden der Farbe Grün an den 2. Kanal der RGB-LED
* Senden der Farbe Blau an den 3. Kanal der RGB-LED
* Einstellen auf maximale Helligkeit (da im Format RRGGBB die Helligkeitsinformation schon enthalten ist. Der Colorpicker funktioniert z.B. so.)

Die zu sendende Farbe wird vorher über den Colorpicker als oben beschriebene Attribute des jeweiligen Geräts eingestellt. Siehe unten.


 # SET
 set rgb cmd {"sc %DMX_R " . AttrVal("%NAME","DMX_R","") . "\nsc %DMX_G " . AttrVal("%NAME","DMX_G","") . "\nsc %DMX_B " . AttrVal("%NAME","DMX_B","") . "\nsc %DMX_M 255"}
 set rgb postproc {sprintf("%%02x%%02x%%02x", (split(" ", "$_"))[2],(split(" ", "$_"))[5],(split(" ", "$_"))[8])}

 # GET
 get rgb cmd {"gc %DMX_R " . "\ngc %DMX_G " . "\ngc %DMX_B "}
 get rgb postproc {sprintf("%%02x%%02x%%02x", (split(" ", "$_"))[2],(split(" ", "$_"))[5],(split(" ", "$_"))[8])}

Nun kann das ECMD-Modul zum Definieren von ECMD-Devices in der fhem.cfg definiert werden:
Hinweis: bei mir laufen DMXControl und FHEM auf einem Server, deswegen ist die IP "localhost".

 define DMXControl ECMD telnet localhost:2145
 attr DMXControl classdefs DMXControl_Devices=ECMD\DMXControl_Devices.classdef

Nun kann die erste RGB-LED in der fhem.cfg definiert werden:
 define RGB1 ECMDDevice DMXControl_Devices 1 2 3 4 5
 attr RGB1 DMX_B 0
 attr RGB1 DMX_G 0
 attr RGB1 DMX_M 0
 attr RGB1 DMX_R 0
 attr RGB1 DMX_S 0
 attr RGB1 room hidden

Die zweite RGB-LED wäre bei mir:
 define RGB2 ECMDDevice DMXControl_Devices 6 7 8 9 10
 attr RGB2 DMX_B 0
 attr RGB2 DMX_G 0
 attr RGB2 DMX_M 0
 attr RGB2 DMX_R 0
 attr RGB2 DMX_S 0
 attr RGB2 room hidden

== Colorpicker & readingsProxy ==
[[Datei:FHEMWEB_Colorpicker.png|thumb|FHEMWEB-Colorpicker]]
[[Datei:andFHEM_Colorpicker.png|thumb|andFHEM-Colorpicker]]
Eigentlich kann man jetzt schon die LEDs ansteuern. Man muss nur die Attribute des jeweiligen RGB-Geräts verändern und ein "set RGB1 rgb" ausführen.
Da man so aber keine Möglichkeit hat, die Farbe direkt in einem Farbfeld auszuwählen, fügen wir diese Funktionalität nun mit dem [http://www.fhemwiki.de/wiki/Color Colorpicker] hinzu.
Damit dem ECMD-Device die dafür erforderlichen Befehle "beigebracht" werden, muss das Modul [http://fhem.de/commandref.html#readingsProxy readingsProxy] zwischen das [http://fhem.de/commandref.html#ECMD ECMD-Modul] und den Colorpicker geschaltet werden.

Das Standard-Format für die Farbeinstellung im Colorpicker ist RRGGBB. Da DMXControl jede Farbe einzeln benötigt und das auch noch im Dezimal-Format, wird der readingsProxy so eingestellt, dass er bei einem "set (Readingsproxy) rgb RRGGBB" die Farben extrahiert, ins Dezimalformat umwandelt und sie als einzelne Attribute in das ECMD-Device (RGB1) schreibt.
Zum Schluss wird der Befehl gegeben, die jetzt als Attribut vorhandenen Farben über das ECMD-Modul an DMXControl zu senden.
Die darauffolgenden setreadings werden für die Iconfarbe benötigt, siehe unten.

Damit der Colorpicker überhaupt aktiviert wird, muss in der 99_myUtils.pm initialisiert werden, siehe [http://www.fhemwiki.de/wiki/DMXControl#Konfig-Zusammenfassung hier].

 define LED1 readingsProxy RGB1:state
 attr LED1 setFn {fhem ("attr RGB1 DMX_R ".hex(substr($ARGS,0,2)));;fhem ("attr RGB1 DMX_G ".hex(substr($ARGS,2,2)));;fhem ("attr RGB1 DMX_B ".hex(substr($ARGS,4,2)));;fhem ("set RGB1 rgb");;fhem ("setreading $name RGB $ARGS");;fhem ("setreading $name rgb $ARGS");;return undef}
 attr LED1 setList rgb:colorpicker,RGB on off
 attr LED1 webCmd rgb:rgb FF0000:rgb C8FF12:rgb 0000FF:rgb 000000

=== Iconfarbe in LED-Farbe ===

Damit die Icon-Farbe automatisch die jeweils eingestellte LED-Farbe einnimmt, fügen wir folgende Attribute hinzu:
 attr LED1 getList rgb
 attr LED1 getFn {fhem ("get RGB1 rgb");;fhem ("setreading LED1a RGB ".ReadingsVal("RGB1","rgb","000000"));;(ReadingsVal($name,"RGB","000000"),1) }
 attr LED1 devStateIcon {Color_devStateIcon (ReadingsVal($name,"RGB","000000"))}

Anmerkung: dies funktioniert nur mit den SVG-Icons!

=== Live-Colorpicker ===

Das i-Tüpfelchen ist jetzt der Live-Colorpicker, mit dem man über das Farbfeld fahren kann und die Farbe, die das Fadenkreuz markiert, sofort eingestellt wird.
Dazu benötigen wir ein globales Attribut:
 attr global userattr realtimePicker

und schalten dieses auf den readingsProxy scharf:
 attr LED1 realtimePicker 1

Die Android-App [http://andfhem.klass.li andFHEM] verfügt ebenfalls über einen Live-Colorpicker, der automatisch erscheint, wenn man den Colorpicker in der fhem.cfg definiert hat.

== Lightscene ==
Damit die eingestellte Farbe auch mit dem [http://fhem.de/commandref.html#LightScene Lightscene-Modul] funktioniert, muss folgendes Attribut gesetzt werden:

Global:
 attr global userattr lightSceneParamsToSave 
Gerät: 
 attr LED1 lightSceneParamsToSave RGB -> rgb

== Konfig-Zusammenfassung ==
Zusammenfassung der Konfiguration mit allen oben beschriebenen Funktionen:
* fhem.cfg
 attr global userattr DMX_B DMX_G DMX_M DMX_R DMX_S realtimePicker lightSceneParamsToSave
 
 define DMXControl ECMD telnet localhost:2145
 attr DMXControl classdefs DMXControl_Devices=ECMD\DMXControl_Devices.classdef:DMXControl_Effects=ECMD\DMXControl_Effects.classdef
 
 define RGB1 ECMDDevice DMXControl_Devices 1 2 3 4 5
 attr RGB1 DMX_B 0
 attr RGB1 DMX_G 0
 attr RGB1 DMX_M 0
 attr RGB1 DMX_R 0
 attr RGB1 DMX_S 0
 attr RGB1 room hidden
 
 define LED1 readingsProxy RGB1:state
 attr LED1 setFn {fhem ("attr RGB1 DMX_R ".hex(substr($ARGS,0,2)));;fhem ("attr RGB1 DMX_G ".hex(substr($ARGS,2,2)));;fhem ("attr RGB1 DMX_B ".hex(substr($ARGS,4,2)));;fhem ("set RGB1 rgb");;fhem ("setreading $name RGB $ARGS");;fhem ("setreading $name rgb $ARGS");;return undef}
 attr LED1 setList rgb:colorpicker,RGB on off
 attr LED1 getFn {fhem ("get RGB1 rgb");;fhem ("setreading LED1a RGB ".ReadingsVal("RGB1","rgb","000000"));;(ReadingsVal($name,"RGB","000000"),1) }
 attr LED1 getList rgb
 attr LED1 webCmd rgb:rgb FF0000:rgb C8FF12:rgb 0000FF:rgb 000000
 attr LED1 devStateIcon {Color_devStateIcon (ReadingsVal($name,"RGB","000000"))}
 attr LED1 realtimePicker 1
 attr LED1 lightSceneParamsToSave RGB -> rgb


* FHEM\ECMD\DMXControl_Devices.classdef
 params DMX_R DMX_G DMX_B DMX_M DMX_S
 
 # SET
 set rgb cmd {"sc %DMX_R " . AttrVal("%NAME","DMX_R","") . "\nsc %DMX_G " . AttrVal("%NAME","DMX_G","") . "\nsc %DMX_B " . AttrVal("%NAME","DMX_B","") . "\nsc %DMX_M 255"}
 set rgb postproc {sprintf("%%02x%%02x%%02x", (split(" ", "$_"))[2],(split(" ", "$_"))[5],(split(" ", "$_"))[8])}
 
 # GET
 get rgb cmd {"gc %DMX_R " . "\ngc %DMX_G " . "\ngc %DMX_B "}
 get rgb postproc {sprintf("%%02x%%02x%%02x", (split(" ", "$_"))[2],(split(" ", "$_"))[5],(split(" ", "$_"))[8])}


* FHEM\ECMD\DMXControl_Effects.classdef ''(oben noch nicht beschrieben)''
 # Notifcations
 set Klingel cmd {"runcommand 7 17 3"}
 set Tueroeffner cmd {"runcommand 7 18 3"}
 set Nachricht cmd {"runcommand 7 19 3"}
 
 #statische Beleuchtungs-Presets
 set Licht_0 cmd {"runcommand 7 7 3"}
 set Licht_1 cmd {"runcommand 7 8 3"}
 set Licht_2 cmd {"runcommand 7 9 3"}
 set Licht_3 cmd {"runcommand 7 10 3"}
 set Licht_4 cmd {"runcommand 7 11 3"}
 set Licht_5 cmd {"runcommand 7 12 3"}
 set Licht_6 cmd {"runcommand 7 13 3"}
 set Licht_7 cmd {"runcommand 7 14 3"}
 set Licht_8 cmd {"runcommand 7 15 3"}
 set Licht_9 cmd {"runcommand 7 16 3"}


* 99_myUtils.pm (in '''fett''' die notwendigen Änderungen zum Initialisieren des Colorpickers)
 # start-of-template
 package main;
 
 use strict;
 use warnings;
 use POSIX;
 ##### wichtig, da die in Color; verwendete Variable $FW_ME sonst noch nicht definiert ist #####
 '''use vars qw($FW_ME);''' 
 '''use Color;'''
 
 sub
 myUtils_Initialize($$)
 {
 	my ($hash) = @_;
 '''FHEM_colorpickerInit();'''	
 }
 
 # start with your own functions below this line
 
 
 # behind your last function, we need the following
 1;
 # end-of-template

== Danksagung ==
Ich bedanke mich für die Bereitstellung der Software und die Hilfe bei:
* FHEM: Rudolf König stellvertretend für alle anderen Mitentwickler
* ECMD: Dr. Boris Neubert
* readingsProxy, Lightscene, Colorpicker: Andre (justme1968), ganz besonders, weil er viele meiner Wünsche nachträglich implementiert hat
* andFHEM: Matthias Klass, auch für meinen Wunsch des Live-Colorpickers in Verbindung mit ECMD-Devices
* DMXControl: Stefan Krupop stellvertretend für alle anderen Mitentwickler
* Windows: Bill... ach ne, doch nicht. :)