http://wiki.fhem.de/w/api.php?action=feedcontributions&feedformat=atom&user=EislerFHEMWiki - Benutzerbeiträge [de]2026-04-30T15:38:13ZBenutzerbeiträgeMediaWiki 1.43.6http://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=31976Proteus EcoMeter2019-12-14T17:35:03Z<p>Eisler: Links korrigiert</p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zur Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=platzHalter.png<br />
|Bildbeschreibung=EcoMeter Ultraschall Füllstandsanzeige für Heizöltank<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 433,92MHz, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Tekelek<br />
}}<br />
== Features ==<br />
EcoMeter für Heizöl liefert alle 60 Minuten einen Messwert<br />
<br />
EcoMeter S für Zisterne, Wassertank liefert alle 30 Minuten einen Messwert <br />
<br />
Wenn der Sensor eine Füllstandänderung von 3cm pro Minute erkennt, geht der Sensor in den FastModus, d.h. es werden alle 2 - 3 Sekunden neue Werte an den Ecomonitor kommuniziert. Dies ist hilfreich bei einem Leck oder beim Nachtanken. Der FastModus, vergleichbar mit dem Modus nach dem Koppeln, dauert dann ca. 10 Minuten an, so dass die Batterie nicht leer gesaugt wird.<br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== Identifikation ===<br />
Das Proteus EcoMeter verwendet für die Anbindung der seriellen Kommunikation an die USB-Schnittstelle einen sehr weit verbreiteten Chip der Familie <code>CP210x UART Bridges</code>. Dieser Baustein hat die USB <code>ID 10c4:ea60</code> über die auch der Name in <code>/dev/serial/by-id</code> abgeleitet wird. Hat man mehrere Geräte die mit diesem Chip arbeiten (z.B. den optischen Adapter von Viessmann für [[Vitotronic_200_(Viessmann_Heizungssteuerung)|VCONTROL]]) am gleichen Rechner, so werden diese unter <code>lsusb</code> mit identischer ID gelistet, aber nur einer erhält den passenden Namen unter <code>/dev/serial/by-id</code>. Sie sind also auf diese Weise nicht unterscheidbar. Die kurzen Gerätenamen <code>/dev/ttyUSBx</code> werden willkürlich zugeordnet. Damit sind die Geräte auch nicht unterscheidbar.<br />
<br />
{{Hinweis|Eventuell können die Identifizierungsangaben ggf. im EEPROM der CP2102 abgeändert werden. Details hierzu sind im Artikel [[CP2102]] zu finden.}}<br />
<br />
Bleibt noch der Pfad wenn man die Geräte immer in die gleiche Buchse steckt. Diese Pfade werden unter Linux in <code>/dev/serial/by-path</code> angelegt. Hier kann man einzelne Buchsen (auch von Hubs) identifizieren. Die Namen enthalten jedoch Doppelpunkte und FHEM verkraftet keine Gerätenamen mit Doppelpunkten. <small>''Wer weiß warum bitte hier Lösung eintragen.''</small> Um diese ohnehin unhandlichen Namen kürzer und verträglicher zu bekommen, kann man Symbolische Links anlegen. Dazu erzeugt man am besten in <code>/opt/fhem</code> ein Verzeichnis <code>dev</code> und verlinkt alle für FHEM relevanten Geräte dort hin. Also in meinem Beispiel TEK603 und VCONTROL:<br />
<syntaxhighlight lang=bash><br />
cd /opt/fhem<br />
mkdir dev<br />
cd dev<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.3:1.0-port0 heizung<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.2:1.0-port0 oelpegel<br />
</syntaxhighlight><br />
Solange man die beiden Geräte immer in die gleiche Buchse steckt, werden sie ab jetzt immer korrekt zugeordnet:<br />
<syntaxhighlight lang=text><br />
defmod Oelpegel TEK603 /opt/fhem/dev/oelpegel<br />
defmod Heizung VCONTROL /opt/fhem/dev/heizung /opt/fhem/mycfg/vitoladens_300-C_J3Ra-24.cfg 120<br />
</syntaxhighlight><br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
<syntaxhighlight lang=text><br />
2017-03-03_13:07:11 Oelpegel CONNECTED<br />
2017-03-03_13:08:27 Oelpegel Time: 13:05:21<br />
2017-03-03_13:08:27 Oelpegel Temperature: 18.33<br />
2017-03-03_13:08:27 Oelpegel Ullage: 100<br />
2017-03-03_13:08:27 Oelpegel RemainingUsableLevel: 3227<br />
2017-03-03_13:08:27 Oelpegel RemainingUsablePercent: 31.0<br />
2017-03-03_13:08:27 Oelpegel TotalUsableCapacity: 10414<br />
</syntaxhighlight><br />
In den ersten 10 Minuten nach dem Anlernen, befindet sich das Gerät im Echtzeit-Modus. Das bedeutet es werden mehrere Messungen pro Sekunde übertragen. Das würde die Batterie sehr schnell lehren. Daher schaltet das Gerät nach 10 Minuten in den Normalbetrieb, in dem nur noch ganz grob alle 30 Minuten Werte übertragen werden. Die Übertragung zu FHEM findet auch nur statt, wenn über die Funkstrecke Daten vom Sensor kommen. Das führt zu der Situation, dass nach diesen 10 Minuten ein neu eingerichtetes <code>TEK603</code> Modul sehr lange (Stunden ?) keine Daten anzeigt, obwohl das Display der Proteus Daten anzeigt. Das liegt einfach daran, dass dieses Display den zuletzt gespeicherten Messwert anzeigt egal wie lange der her ist. Übertragen wird bis zum nächsten Wert auf der Funkstrecke nichts.<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
Füllstandsanzeige für Zisterne, Wassertank]<br />
* Hersteller: [https://tekelek.ie/wp-content/uploads/2019/04/InstallationGuide-TEK-603-Eco-Oil-Monitor-Tekelek-Installation-Guide-A4.pdf Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=AutoShuttersControl&diff=28567AutoShuttersControl2018-11-26T20:54:45Z<p>Eisler: fix</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Steuerung von Rollläden<br />
|ModCategory=Automatisierung<br />
|ModType=x<br />
<!-- |ModCmdRef= ---- noch nicht Teil von FHEM --><br />
|ModForumArea=Automatisierung<br />
|ModTechName=73_AutoShuttersControl.pm<br />
|ModOwner=CoolTux}}<br />
Mit [[AutoShuttersControl]] oder kurz ASC können typische Aufgabenstellungen im Zusammenhang mit Rollläden u.ä. automatisiert werden, wie zum Beispiel das Öffnen bei Sonnenaufgang, Schließen bei Sonnenuntergang oder das Anfahren von Lüftungspositionen beim Öffnen des zugehörigen Fensters. <br />
<br />
{{Hinweis|Das Modul befindet sich derzeit noch in der Entwicklung; der jeweils aktuelle Stand ist diesem {{Link2Forum|Topic=90751|LinkText="Thread im Forum"}} zu entnehmen.}}<br />
<br />
== Basics ==<br />
Zur Nutzung des Moduls sollten folgende andere FHEM-Devices vorhanden sein:<br />
* Rollläden<br />
* Fensterkontakte und <br />
* Bewohnerstatus auf Basis von Residents/Roomates in englisch. Ersatzweise andere Devices, z.B. Dummys, welche als ''state'' ''home'', ''asleep'', ''gotosleep'' und ''awoken'' setzen sowie ein Reading ''lastState''.<br />
<br />
Die Einrichtung des Moduls bzw. dessen Funktionalität erfolgt in mehreren Schritten:<br />
* Definition des ASC-Devices<br />
* Einstellung zentraler Vorgaben am ASC-Device<br />
* Markieren der zukünftig zu steuernden Rollladen-Devices<br />
* Einbinden der Rollladen-Devices in das ASC-Device<br />
* Einstellen der individuellen Vorgaben je Rollladen (am Rollladen-Device)<br />
<br />
== Einrichtung ==<br />
<br />
=== Vorbereitung ===<br />
<br />
{{Hinweis|Ihr benötigt ein aktuelles FHEM. Update ab dem 04.09.2018 Voraussetzung!}}<br />
<br />
=== Define des ASC-Devices ===<br />
Es genügt ein einfaches define ohne weitere Parameter.<br />
<code>define <name> AutoShuttersControl</code><br />
Dies bewirkt neben der Anlage des Devices selbst auch, dass als weiteres globales Attribut ''ASC'' verfügbar wird.<br />
<br />
=== Einstellung zentraler Vorgaben ===<br />
Es stehen am ASC-Device einige Attribute zur Verfügung, über die sich das Verhalten des ASC-Devices insgesamt steuern lässt, z.B. zur Vermeidung von morgendlichen oder abendlichen Fahrten sowie bei Gefahr von Schäden an den Rollläden durch Frost oder zur Reaktion auf Fensterkontakte. Details sind der Commandref zu entnehmen.<br />
Diese Attribute können auch nachträglich noch geändert werden.<br />
<br />
=== Markieren zu steuernder Rollladen-Devices ===<br />
Um einen oder mehrere Rollläden durch das ASC-Device zu steuern, wird für jeden Rollladen jeweils das neue globale Attribut ''ASC'' gesetzt. Der Wert ist mit 1 oder 2 festzulegen, wobei '''1''' bedeutet, dass <br />
* die Offen-Position kleiner ist als die Geschlossen-Position, also typischerweise 0 ''offen'' bedeutet und 100 für ''geschlossen'' steht<br />
* eine bestimmte Position mit '''position''' angefahren wird, also z.B. <code>set <name> position 70</code>.<br />
Dies ist z.B. die passende Wahl für ROLLO-Devices<br />
<br />
Die '''2''' steht für ein umgekehrtes Verhalten und den Befehlsteil ''pct'', also ''offen'' für <code>set <name> pct 100</code>. Typischer Vertreter dieses Typs sind HomeMatic (CUL_HM-) Geräte oder die Shelly2-Aktoren.<br />
<br />
=== Einbinden in das ASC-Device ===<br />
Nachdem man das obige Attribut bei einem oder mehreren Rollladen-Devices gesetzt hat, kann mit <br />
<code>set <name> scanForShutters</code> ein Suchlauf gestartet werden, mit dem dann diese Rollläden durch das Modul gefunden und in die Steuerungslogik eingebunden werden.<br />
<br />
=== Einstellen der individuellen Vorgaben ===<br />
Nach der Einbindung sind an den Rollladen-Devices weitere Attribute verfügbar, mit denen die für den jeweiligen Rollladen geltenden Einstellungen vorgenommen werden können. <br />
Die Beschreibung der Attribute ist in der commandref enthalten.<br />
<br />
== Readings ==<br />
<br />
===Readings im ASC-Device selbst.===<br />
<br />
{|class="wikitable"<br />
|-<br />
! Name !! Datentyp/<BR/>Wertebereich !! Bedeutung <br />
|-<br />
|..._nextAstroTimeEvent || ||Uhrzeit des nächsten Astro Events, Sonnenauf- oder Sonnenuntergang oder feste Zeit pro Rollonamen <br />
|-<br />
|..._lastPosValue || ||letzter abgesetzter Fahrbefehl pro Rollonamen<br />
|-<br />
|..._lastDelayPosValue || ||letzter abgesetzter Fahrbefehl welcher beim nächsten zulässigen Event ausgeführt wird.<br />
|-<br />
|partyMode ||on, off || aktiviert den globalen Partymodus. Alle Rollläden, welche das Attribut AutoShuttersControl_Partymode bei sich auf on gestellt haben, werden nicht mehr gesteuert. Der letzte Schaltbefehl, welcher durch ein Fensterevent oder Bewohnerstatus an die Rollläden gesendet wurde, wird beim off setzen durch set ASC-Device partyMode off ausgeführt<br />
|-<br />
|lockOut || on, off ||für das Aktivieren des Aussperrschutzes gemäß des entsprechenden Attributs AutoShuttersControl_lock-out im jeweiligen Rolladen. (siehe Beschreibung bei den Attributen für die Rolladendevices)<br />
|-<br />
|room_... || ||Auflistung aller Rollläden welche in den jeweiligen Rämen gefunden wurde, Bsp.: room_Schlafzimmer,Terrasse<br />
|-<br />
|state || ||Status des Devices active, enabled, disabled<br />
|-<br />
|sunriseTimeWeHoliday|| on,off ||wird das Rolladen Device Attribut Attributes AutoShuttersControl_Time_Up_WE_Holiday beachtet oder nicht<br />
|-<br />
|userAttrList || rolled out ||Status der UserAttribute, welche an die Rollläden gesendet werden<br />
|}<br />
<br />
===Readings in den Rolllädendevices===<br />
<br />
{|class="wikitable"<br />
|-<br />
! Name !! Bedeutung <br />
|-<br />
|ASC_Time_DriveUp ||Sonnenaufgangszeit für das Rollo<br />
|-<br />
|ASC_Time_DriveDown ||Sonnenuntergangszeit für das Rollo<br />
|-<br />
|ASC_ShuttersLastDrive ||Grund des letzten fahrens vom Rolladen<br />
|}<br />
<br />
== Settings ==<br />
<br />
===Set Befehle für ASC-Device===<br />
<br />
{|class="wikitable"<br />
|-<br />
! Name !! Datentyp/<BR/>Wertebereich !! Beschreibung <br />
|-<br />
|partyMode ||on, off ||aktiviert den globalen Partymodus. Siehe Reading partyMode<br />
|-<br />
|lockOut ||on, off ||aktiviert den globalen Aussperrschutz. Siehe Reading partyMode<br />
|-<br />
|renewSetSunriseSunsetTimer || || erneuert bei allen Rollläden die Zeiten für Sunset und Sunrise und setzt die internen Timer neu.<br />
|-<br />
|scanForShutters || ||sucht alle FHEM Devices mit dem Attribut "AutoShuttersControl" 1, 2<br />
|-<br />
|sunriseTimeWeHoliday || on,off ||aktiviert/deaktiviert die Beachtung des Attributes AutoShuttersControl_Time_Up_WE_Holiday für Rollladen-Devices<br />
|-<br />
|createNewNotifyDev || ||Legt die interne Struktur für NOTIFYDEV neu an<br />
|-<br />
|selfDefence ||on, off||aktiviert/deaktiviert den Selbstschutz, wenn das Residents Device absent meldet und selfDefence aktiv ist und ein Fenster im Haus steht noch offen, wird an diesem Fenster das Rollo runtergefahren<br />
|-<br />
|wiggle ||||Bewegt einen Rollladen oder alle Rollläden (für Abschreckungszwecke bei der Alarmierung) um 5%, und nach 1 Minute wieder zurück zur Ursprungsposition<br />
|-<br />
|||||<br />
|}<br />
<br />
== Get ==<br />
<br />
{|class="wikitable"<br />
|-<br />
! Name !! Beschreibung<br />
|-<br />
| showShuttersInformations ||zeigt eine Übersicht der Autofahrzeiten<br />
|-<br />
| showNotifyDevsInformations ||zeigt eine Übersicht der abgelegten NOTIFYDEV Struktur. Dient zur Kontrolle<br />
|}<br />
== Attribute ==<br />
<br />
===Attribute im AutoShuttersControl Device selbst.===<br />
<br />
{|class="wikitable"<br />
|-<br />
! Name !! Datentyp/<BR/>Wertebereich !! Default-Wert !! Beschreibung<br />
|-<br />
|ASC_antifreezeTemp || || ||Temperatur ab welcher der Frostschutz greifen soll und das Rollo nicht mehr fährt. Der letzte Fahrbefehl wird gespeichert.<br />
|-<br />
|ASC_autoAstroModeEvening ||aktuell REAL, CIVIL, NAUTIC, ASTRONOMIC || || (in genau dieser Schreibweise)<br />
|-<br />
|ASC_autoAstroModeEveningHorizon || || || Höhe über Horizont, wenn beim Attribut AutoShuttersControl_autoAstroModeEvening HORIZON ausgewählt<br />
|-<br />
|ASC_autoAstroModeMorning ||aktuell REAL, CIVIL, NAUTIC, ASTRONOMIC || ||(in genau dieser Schreibweise)<br />
|-<br />
|ASC_autoAstroModeMorningHorizon || || ||Höhe über Horizont, wenn beim Attribut AutoShuttersControl_autoAstroModeMorning HORIZON ausgewählt<br />
|-<br />
|ASC_autoShuttersControlComfort ||on, off || ||schaltet die Komfortfunktion an. Bedeutet, dass ein Rollladen mit einem threestate Sensor am Fenster beim Öffnen in eine weit offen Position fährt. Die Offenposition wird beim Rollladen über das Attribut AutoShuttersControl_Pos_after_ComfortOpen eingestellt.<br />
|- <br />
|ASC_autoShuttersControlEvening ||on, off || ||ob Abends die Rollläden automatisch nach Zeit gesteuert werden sollen<br />
|-<br />
|ASC_autoShuttersControlMorning ||on, off || ||ob Morgens die Rollläden automatisch nach Zeit gesteuert werden sollen<br />
|-<br />
|ASC_temperatureReading || || ||Reading für die Außentemperatur<br />
|-<br />
|ASC_temperatureSensor || || ||Device für die Außentemperatur<br />
|-<br />
|ASC_timeUpHolidayDevice || || ||Device zur Urlaubserkennung oder Sonstiges / muss 0 oder 1 im Reading state beinhalten.<br />
|-<br />
|ASC_residentsDevice|| || ||Devicenamen des Residents-Device der obersten Ebene<br />
|-<br />
|ASC_residentsDeviceReading|| || ||Status Reading des Residents-Device der obersten Ebene<br />
|-<br />
|ASC_brightnessMinVal|| || ||minimaler Lichtwert, bei dem Schaltbedingungen noch geprüft werden sollen<br />
|-<br />
|ASC_brightnessMaxVal || || ||maximaler Lichtwert, bei dem Schaltbedingungen noch geprüft werden sollen<br />
|-<br />
|ASC_rainSensorDevice || || ||Device, welches bei Regen getriggert werden soll<br />
|-<br />
|ASC_rainSensorReading || || ||das ensprechende Reading zum Regendevice<br />
|-<br />
|ASC_rainSensorShuttersClosedPos || || ||Position in pct, welche der Rollladen bei Regen anfahren soll <br />
|-<br />
|ASC_shuttersDriveOffset || || ||maximale zufällige Verzögerung in Sekunden bei der Berechnung der Fahrzeiten, 0 bedeutet keine Verzögerung<br />
|-<br />
|ASC_twilightDevice || || ||Device welches Informationen zum Sonnenstand liefert, wird unter anderem für die Beschattung verwendet.<br />
|-<br />
|ASC_expert || || ||ist der Wert 1 werden erweiterte Informationen bezüglich des NotifyDevs unter set und get angezeigt<br />
|-<br />
| || || ||<br />
|-<br />
| || || ||<br />
|}<br />
<br />
===Attribute in den Rolllädendevices===<br />
<br />
{|class="wikitable"<br />
|-<br />
! Name !! Datentyp/<BR/>Wertebereich !! Default-Wert !! Beschreibung<br />
|-<br />
|ASC || 0, 1, 2|| ||1 = "Inverse oder Rollo Bsp.: Rollo Oben 0,Rollo Unten 100 und der Befehl zum Prozentualen fahren ist position",2 = "Homematic Style Bsp.: Rollo Oben 100,Rollo Unten 0 und der Befehl zum Prozentualen fahren ist pct<br />
|-<br />
|ASC_Antifreeze || on, off|| ||Frostschutz an oder aus<br />
|-<br />
|ASC_AutoAstroModeEvening ||REAL, CIVIL, NAUTIC, ASTRONOMIC|| ||aktuell REAL,CIVIL,NAUTIC,ASTRONOMIC<br />
|-<br />
|ASC_AutoAstroModeEveningHorizon || || ||Höhe über Horizont wenn beim Attribut ASC_autoAstroModeEvening HORIZON ausgewählt<br />
|-<br />
|ASC_AutoAstroModeMorning ||REAL, CIVIL, NAUTIC, ASTRONOMIC|| ||aktuell REAL,CIVIL,NAUTIC,ASTRONOMIC<br />
|-<br />
|ASC_AutoAstroModeMorningHorizon || || ||Höhe über Horizont wenn beim Attribut ASC_autoAstroModeMorning HORIZON ausgewählt<br />
|-<br />
|ASC_Closed_Pos || || ||in 10 Schritten von 0 bis 100,default Vorgabe ist abhängig vom Attribut ASC<br />
|-<br />
|ASC_Down || astro, time, brightness || ||bei Astro wird Sonnenuntergang berechnet, bei time wird der Wert aus ASC_Time_Down_Early als Fahrzeit verwendet und bei brightness muss ASC_Time_Down_Early und ASC_Time_Down_Late korrekt gesetzt werden. Der Timer läuft dann nach ASC_Time_Down_Late Zeit,es wird aber in der Zeit zwischen ASC_Time_Down_Early und ASC_Time_Down_Late geschaut ob die als Attribut im Moduldevice hinterlegte ASC_brightnessMinVal erreicht wurde, wenn ja wird der Rolladen runter gefahren<br />
|-<br />
|ASC_Mode_Down ||always, home, absent, off || ||wann darf die Automatik steuern. immer,niemals,bei abwesenheit des Roommate (ist kein Roommate und absent eingestellt wird gar nicht gesteuert)<br />
|-<br />
|ASC_Mode_Up ||always, home, absent, off || ||wann darf die Automatik steuern. immer,niemals,bei abwesenheit des Roommate (ist kein Roommate und absent eingestellt wird gar nicht gesteuert)<br />
|-<br />
|ASC_Drive_Offset || || ||maximale zufällige Verzögerung in Sekunden bei der Berechnung der Fahrzeiten, 0 bedeutet sofort, -1 bedeutet das das gleichwertige Attribut aus dem ASC-Device ausgewertet werden soll.<br />
|-<br />
|ASC_Open_Pos || || ||in 10 Schritten von 0 bis 100,default Vorgabe ist abhängig vom Attribut ASC<br />
|-<br />
|ASC_Partymode || on, off || ||schaltet den Partymodus an oder aus. Wird dann am ASC Device set ASC-DEVICE partyMode on geschalten, werden alle Fahrbefehle an den Rollläden, welche das Attribut auf on haben, zwischengespeichert und erst später ausgeführt<br />
|-<br />
|ASC_Pos_Reading || || ||Name des Readings, welches die Position des Rollladen in Prozent an gibt. Wird bei unbekannten Device -ypen auch als set Befehl zum Fahren verwendet<br />
|-<br />
|ASC_Pos_after_ComfortOpen || || ||in 10 Schritten von 0 bis 100, default Vorgabe ist abhängig vom Attribut ASC<br />
|-<br />
|ASC_Roommate_Reading || || ||das Reading zum Roommate-Device, welches den Status wieder gibt<br />
|-<br />
|ASC_Roommate_Device || || ||mit Komma getrennte Namen des/der Roommate-Device/s welche den/die Bewohner des Raumes vom Rollladen wieder gibt. Es macht nur Sinn in Schlaf- oder Kinderzimmern<br />
|-<br />
|ASC_Time_Down_Early || || ||Sunset frühste Zeit zum Runterfahren<br />
|-<br />
|ASC_Time_Down_Late || || ||Sunset späteste Zeit zum Runterfahren<br />
|-<br />
|ASC_Time_Up_Early || || ||Sunrise frühste Zeit zum Hochfahren<br />
|-<br />
|ASC_Time_Up_Late || || ||Sunrise späteste Zeit zum Hochfahren<br />
|-<br />
|ASC_Time_Up_WE_Holiday || || ||Sunrise frühste Zeit zum Hochfahren am Wochenende und/oder Urlaub (we2holiday wird beachtet). Achtung! Sollte nicht größer sein als ASC_Time_Up_Late, sonst wird ASC_Time_Up_Late verwendet<br />
|-<br />
|ASC_Up || astro, time, brightness || ||bei astro wird Sonnenaufgang berechnet, bei time wird der Wert aus ASC_Time_Up_Early als Fahrzeit verwendet und bei brightness müssen ASC_Time_Up_Early und ASC_Time_Up_Late korrekt gesetzt werden. Der Timer läuft dann nach ASC_Time_Up_Late Zeit, es wird aber in der Zeit zwischen ASC_Time_Up_Early und ASC_Time_Up_Late geschaut, ob die als Attribut im Moduldevice hinterlegte ASC_brightnessMinVal erreicht wurde. Wenn ja, wird der Rolladen runter gefahren<br />
|-<br />
|ASC_Ventilate_Pos || || ||in 10 Schritten von 0 bis 100, default Vorgabe ist abhängig vom Attribut ASC<br />
|-<br />
|ASC_Ventilate_Window_Open || || ||auf lüften, wenn das Fenster gekippt/geöffnet wird und aktuelle Position unterhalb der Lüften-Position ist<br />
|-<br />
|ASC_WindowRec || || ||Name des Fensterkontakts an welchen Fenster der Rollladen angebracht ist<br />
|-<br />
|ASC_WindowRec_subType || || ||Typ des verwendeten Fensterkontakts: twostate (optisch oder magnetisch) oder threestate (Drehgriffkontakt)<br />
|-<br />
|ASC_lock-out || soft, hard || ||stellt entsprechend den Aussperrschutz ein. Bei global aktiven Aussperrschutz (set ASC-Device lockOut soft) und einem Fensterkontakt open bleibt dann der Rolladen oben. Dies gilt nur bei Steuerbefehle über das ASC Modul. Stellt man global auf hard, wird bei entsprechender Möglichkeit versucht, den Rollladen hardwareseitig zu blockieren. Dann ist auch ein Fahren über die Taster nicht mehr möglich.<br />
|-<br />
|ASC_lock-outCmd || inhibit, blocked || ||set Befehl für das Rolladen-Device zum Hardware sperren. Der Befehl wird verwendet, wenn man "ASC_lock-out" auf hard setzt<br />
|-<br />
|ASC_Self_Defense_Exclude || on, off || ||bei on Wert wird dieser Rolladen bei aktiven Self Defense und offenen Fenster nicht runter gefahren, wenn Residents absent ist.<br />
|-<br />
|ASC_Shading_Brightness_Sensor || || ||Sensor-Device, welches für die Lichtwerte verwendet wird. ACHTUNG! Findet auch Verwendung bei ASC_Down - brightness<br />
|-<br />
|ASC_BrightnessMinVal || || ||minimaler Lichtwert, bei dem Schaltbedingungen noch geprüft werden sollen / wird der Wert von -1 nicht geändert, so wird automatisch der Wert aus dem Moduldevice genommen<br />
|-<br />
|ASC_BrightnessMaxVal || || ||maximaler Lichtwert, bei dem Schaltbedingungen noch geprüft werden sollen / wird der Wert von -1 nicht geändert, so wird automatisch der Wert aus dem Moduldevice genommen<br />
|-<br />
|ASC_ShuttersPlace || window, terrace || ||wenn dieses Attribut auf terrace gesetzt ist und das Residence Device in den Status "done" geht und SelfDefence aktiv ist wird das Rollo geschlossen<br />
|- <br />
|ASC_WiggleValue || || ||Wert um welchen sich die Position des Rollladens ändern soll <br />
|-<br />
| || || ||<br />
|- <br />
| || || ||<br />
|-<br />
| || || || <br />
|- <br />
| || || ||<br />
|-<br />
| || || || <br />
|- <br />
| || || ||<br />
|-<br />
| || || || <br />
|}<br />
<br />
== Hilfsmittel ==<br />
tbd<br />
<br />
readingsGroup, um die diversen Level einzustellen: <br />
<br />
define rg_ASC_Rollaeden_Level readingsGroup <Gerät>,<Closed_Pos>,<Open_Pos>,<Shading_Pos>,<Ventilate_Pos> (Rolladen_.*|Jalousie_.*)..:?ASC_Closed_Pos,?ASC_Open_Pos,?ASC_Shading_Pos,?ASC_Ventilate_Pos<br />
attr rg_ASC_Rollaeden_Level commands { ASC_Closed_Pos => 'ASC_Closed_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100',\<br />
ASC_Open_Pos => 'ASC_Open_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100',\<br />
ASC_Shading_Pos => 'ASC_Shading_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100',\<br />
ASC_Ventilate_Pos => 'ASC_Ventilate_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100'}<br />
[[Datei:ReadingsGroup ASC Level.png|600px|]]<br />
readingsGroup, um die diversen Zeiten einzustellen:<br />
<br />
define rg_ASC_Rollaeden_Times readingsGroup <Gerät>,<Stand>,<Time_Up_Early>,<Time_Up_WE>,<Time_Up_Late>,<Time_Down_Early>,<Time_Down_Late>,<Mode_Down>,<Mode_Up> (Rolladen_.*|Jalousie_.*)..:level,?ASC_Time_Up_Early,?ASC_Time_Up_WE_Holiday,?ASC_Time_Up_Late,?ASC_Time_Down_Early,?ASC_Time_Down_Late,?ASC_Mode_Down,?ASC_Mode_Up<br />
attr rg_ASC_Rollaeden_Times commands {level => 'pct:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100', \<br />
ASC_Mode_Down => 'ASC_Mode_Down:always,absent,off',\<br />
ASC_Mode_Up => 'ASC_Mode_Up:always,absent,off',\<br />
ASC_Time_Down_Early => 'ASC_Time_Down_Early:15:00,15:15,15:30,15:45,16:00,16:15,16:30,16:45,17:00,17:15,17:30,17:45,18:00,18:15,18:30,18:45,19:00,19:15,19:30,19:45,20:00,20:15,20:30,20:45,21:00,21:15,21:30,21:45,22:00', \<br />
ASC_Time_Down_Late => 'ASC_Time_Down_Late:20:15,20:30,20:45,21:00,21:15,21:30,21:45,22:00,22:15,22:30,22:45,23:00,23:15,23:30',\<br />
ASC_Time_Up_Early => 'ASC_Time_Up_Early:05:00,05:05,05:30,05:45,06:00,06:15,06:30,06:45,07:00,07:15,07:30,07:45,08:00,08:15,08:30,08:45,09:00,09:15,09:30,09:45,10:00', \<br />
ASC_Time_Up_Late =>'ASC_Time_Up_Late:06:00,06:15,06:30,06:45,07:00,07:15,07:30,07:45,08:00,08:15,08:30,08:45,09:00,09:15,09:30,09:45,10:00',ASC_Time_Up_WE_Holiday => 'ASC_Time_Up_WE_Holiday:06:00,06:15,06:30,06:45,07:00,07:15,07:30,07:45,08:00,08:15,08:30,08:45,09:00,09:15,09:30,09:45,10:00'}<br />
[[Datei:ReadingsGroup ASC Times.png|600px|]]<br />
<br />
== Weblinks ==<br />
* {{Link2Forum|Topic=92628|LinkText="Thread zum Modul im Forum"}}<br />
* {{Link2Forum|Topic=90751|LinkText="Thread zur Entwicklung im Forum"}} <br />
* {{Link2Forum|Topic=73964|LinkText="Thread zu den Scripten von user cluni"}}, die der Entwicklung des Moduls zugrunde liegen<br />
<br />
<br />
[[Kategorie:Code Snippets]]<br />
[[Kategorie:Rollladensteuerung]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=DevIo&diff=27364DevIo2018-07-10T10:19:02Z<p>Eisler: </p>
<hr />
<div>{{Infobox Modul<br />
|ModPurpose=Dienstfunktionen für die Kommunikation per serieller Schnittstelle (USB/RS232), TCP/IP-Verbindung oder UNIX-Socket<br />
|ModType=u<br />
|ModForumArea=FHEM Development<br />
|ModTechName=DevIo.pm<br />
|ModOwner=rudolfkoenig ({{Link2FU|8|Forum}} / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])<br />
}}<br />
<br />
Das Modul [[DevIo]](.pm) ist für Modulentwickler gedacht, um Daten zwischen einem FHEM-Modul und bspw. einer seriellen Schnittstelle, einer TCP/IP-Verbindung oder einem UNIX-Socket auszutauschen. Es übernimmt dabei die gesamte Verbindungsverwaltung und Aufrechterhaltung innerhalb von FHEM und nimmt dem Modulentwickler daher die gesamte Verbindungsverwaltung (Aufbau, Initialisierung, Neu-Verbindung bei Abbruch, etc.) ab. Es berücksichtigt dabei Besonderheiten zwischen Unix-basierten Betriebssystemen und Windows.<br />
<br />
Es dient dabei lediglich dem Zweck einen Kommunikationskanal für eine Definition in FHEM zu etablieren und Daten darüber auszutauschen. Die Interpretation der empfangenen Daten obliegt dem Modul, welches die Verbindung via DevIo geöffnet hat. Die ausgetauschten Daten werden durch DevIo nicht verändert.<br />
<br />
= Allgemeine Funktionsweise =<br />
DevIo hat das Ziel eine besonders einfache Möglichkeit für Modulentwickler zu schaffen, um einen dauerhaften Kommunikationskanal mit einem Hardware- oder Netzwerk-Gerät bzw. Service zu etablieren. Um eine Verbindung aufzubauen muss zunächst die Gegenstelle bekannt sein. Dazu muss vor dem Verbindungsaufbau in dem Internal <code>$hash->{DeviceName}</code> der jeweiligen Definition das Ziel hinterlegt werden. Dies kann bspw. eine serielle Schnittstelle sein (z.B. "/dev/ttyUSB0" oder "COM1" unter Windows) oder eine TCP/IP-Gegenstelle (z.B. "192.168.1.100:1012") sein. Eine detaillierte Aufstellung der möglichen Verbindungsarten und deren Angabe in <code>$hash->{DeviceName}</code> gibt es im folgenden Kapitel [[#Unterstützte Verbindungsarten|Unterstützte Verbindungsarten]].<br />
<br />
Die Funktion [[#DevIo_OpenDev()|DevIo_OpenDev()]] baut dabei die entsprechende Verbindung für eine einzelne Definition in Form eines Filedeskriptors auf und registriert diesen in dem globalen Hash <code>%selectlist</code><ref name="selectlist">[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|Development Module Introduction]] - Wichtige globale Variablen aus fhem.pl</ref>. Sobald die Verbindung erfolgreich aufgebaut wurde, kann eine, durch den Modulautor mitgelieferte, Initialisierungs-Funktion ausgeführt werden, um die Kommunikation zu initialiseren (bspw. das Senden einer Authentifizierungs-/Loginsequenz oder aktivieren der Hardware, etc.).<br />
<br />
FHEM (respektive fhem.pl) prüft nun regelmäßig, ob Daten zum Lesen bereitstehen (also Daten empfangen wurden). Ist dies der Fall, so wird die [[DevelopmentModuleIntro#X_Read|X_Read()]]-Funktion des zugehörigen Moduls für die hinterlegte Definition aufgerufen. Hier können die Daten durch den Aufruf von [[#DevIo_SimpleRead()|DevIo_SimpleRead()]] nun eingelesen und verarbeitet werden. Das Senden von Daten ist durch den Aufruf von [[#DevIo_SimpleWrite()|DevIo_SimpleWrite()]] sehr einfach möglich.<br />
<br />
Sollte die Verbindung zusammenbrechen (USB-Gerät abgezogen, Gerät per Netzwerk nicht mehr erreichbar, etc.), so erkennt dies DevIo und registriert die Definition in <code>%readyfnlist</code><ref name="selectlist" />. FHEM führt nun regelmäßig die [[DevelopmentModuleIntro#X_Ready|X_Ready()]]-Funktion des zugehörigen Moduls<br />
aus um zu prüfen, ob die Verbindung wieder aufgebaut werden kann. Hier wird nun durch die Ausführung von [[#DevIo_OpenDev()|DevIo_OpenDev()]] versucht die Verbindung wieder herzustellen.<br />
<br />
Sobald die Verbindung nicht mehr benötigt wird, oder FHEM bspw. beendet wird, kann die Verbindung via [[#DevIo_CloseDev()|DevIo_CloseDev()]] sauber geschlossen werden.<br />
<br />
= Unterstützte Verbindungsarten = <br />
<br />
Die folgenden Verbindungsarten können via DevIo realisiert werden.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Verbindungsart !! Beispielangabe in<br><code>$hash->{DeviceName}</code> !! Beschreibung<br />
|-<br />
| style="vertical-align:top" | '''Serielle Schnittstelle'''<br />
| style="vertical-align:top" |<br />
* <code>/dev/ttyUSB0</code> <br />
* <code>/dev/ttyUSB0@9600</code><br />
* <code>/dev/ttyUSB0@9600,7,E,2</code><br />
* <code>/dev/ttyUSB0@directio</code><br />
* <code>COM1@9600</code><br />
|| <br />
Durch Angabe eines Geräts in Form eines Gerätepfad (UNIX-basierte Betriebssysteme) oder der Schnittstellenbezeichnung aus Windows kann eine serielle Verbindung geöffnet werden. Der Gerätename kann zusätzliche Angaben zu Baudrate, Datenbits, Parität und Stoppbits enthalten um die Verbindung entsprechend zu konfiguieren. Diese Angaben sind durch ein "@" getrennt an die Gerätebezeichnung angehangen:<br />
<br />
Schematische Syntax: <code>''<font color="grey"><Gerät></font>'''''@'''''<Baudrate>''''','''''<Datenbits>''''','''''<Parität>''''','''''<Stopbits></code><br />
<br />
* <code><Baudrate></code> - Eine gültige Taktfrequenz (Symbole pro Sekunde) mit der die Schnittstelle geöffnet werden soll (Beispiel: <code>9600</code>, <code>14400</code>, <code>115200</code>, ...)<br />
* <code><Datenbits></code> - Die Anzahl an Datenbits (7 oder 8 Datenbits). Standardwert sofern nicht angegeben sind 8 Datenbits.<br />
* <code><Parität></code> - Die zu verwendende Parität, sofern benötigt. Dabei bedeutet der Wert <code>N</code> keine Parität, <code>O</code> bedeutet ungleiche Parität (odd) und <code>E</code> bedeutet gleiche Parität (even) Standardwert sofern nicht angegeben ist <code>N</code> (keine Parität).<br />
* <code><Stopbits></code> - Die Anzahl an zu verwendenden Stopbits (0, 1 oder 2 Stopbits). Standardwert sofern nicht angegeben sind 0 Stopbits.<br />
<br />
Wenn man unter Unix-basierten Betriebssystemen die Schnittstelle nicht explizit konfiguriert öffnen möchte, sondern das Gerät direkt öffnen möchte (und damit die OS-Einstellungen verwendet), kann man durch Angabe von <code>@directio</code> die Konfiguration der Schnittstelle umgehen und das Gerät direkt öffnen:<br />
<br />
Bsp: <code><font color="grey">/dev/ttyUSB0</font>@directio</code><br />
<br />
Unter Windows verwendet man als Gerätename die entsprechende Schnittstellenbezeichung wie bspw. <code>COM1</code>, <code>COM2</code>, usw.<br />
|-<br />
| style="vertical-align:top" | '''TCP/IP-Verbindung'''<br />
| style="vertical-align:top" | <br />
* <code>192.168.1.2:1012</code> <br />
* <code>raspberry:5000</code><br />
||<br />
Durch Angabe eines Hostnamen oder IP-Adresse und einem Port, kann eine TCP-Verbindung aufgebaut werden. Dazu muss Hostname/IP-Adresse und Port in folgendem Schema angegeben werden:<br />
<br />
Schematische Syntax: <code>''<Hostname/IP-Adresse>''''':'''''<Port>''</code><br />
<br />
* <code><Hostname/IP-Adresse></code> - Der Hostname oder die IP-Adresse des zu verbindenden Gerätes/Server.<br />
* <code><Port></code> - Der Zielport zu dem sich verbunden werden soll (0-65535).<br />
<br />
Die Verbindung kann optional verschlüsselt via SSL/TLS aufgebaut werden. Dazu muss das Internal <code>$hash->{SSL}</code> auf 1 gesetzt werden.<br />
|-<br />
| style="vertical-align:top" | '''UNIX-Socket'''<br />
| style="vertical-align:top"|<br />
* <code>UNIX:SEQPACKET:/var/tmp/me_avm_home_external.ctl</code> <br />
* <code>UNIX:STREAM:/var/socket/con</code><br />
|| <br />
Durch Angabe eines Pfads zu einem UNIX-Domain-Socket kann eine Kommunikation mit einem anderen Prozess aufgebaut werden (Inter-Prozess-Kommunikation). Man kann den Socket dabei paketorientiert ("SEQPACKET") oder als Stream ("STREAM") öffnen. <br />
<br />
Schematische Syntax: <code>UNIX:''<Typ>'':''<Pfad>''</code><br />
<br />
* <code><Typ></code> - Der Typ des Sockets. Für einen paketorientierten Socket ist hier <code>SEQPACKET</code> zu verwenden, für einen streamorientierten Socket <code>STREAM</code>. Der Typ muss immer mit angegeben werden.<br />
* <code><Pfad></code> - Der Pfad im Dateisystem zu dem gewünschten UNIX-Socket<br />
|-<br />
| style="vertical-align:top" | '''FHEM IO-Modul'''<br />
| style="vertical-align:top" |<br />
* <code>FHEM:DEVIO:Firmata_SerielleSchnittstelle@9600</code> <br />
|| <br />
Beschreibung siehe {{Link2Forum|Topic=46276}}<br />
|}<br />
<br />
= Wichtige Internals zur Konfiguration =<br />
<br />
Da DevIo ausschließlich definitionsbezogen arbeitet, erfolgt eine Konfiguration von DevIo über Internals, die im übergebenen <code>$hash</code> gesetzt werden müssen (oder können). Hiermit lässt sich das Verhalten von DevIo entsprechend beeinflussen. <br />
<br />
Hier eine Auflistung von allen Internals, die DevIo beeinflussen:<br />
<br />
{| class="wikitable"<br />
|-<br />
! style="min-width: 13em;" | Internal !! Beschreibung<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{DeviceName}</code> <br />
<br />
''mandatory''<br />
| style="vertical-align:top" | Die Gegenstelle zu der eine Verbindung aufgebaut werden soll. Die möglichen Werte und deren Syntax ist im Kapitel [[#Unterstützte Verbindungsarten|Unterstützte Verbindungsarten]] genauer beschrieben.<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{nextOpenDelay}</code> <br />
<br />
''optional''<br />
|| Die Zeit in Sekunden, welche im Falle eines Verbindungsabbruchs gewartet werden soll, bevor ein erneuter Verbindungsversuch stattfindet. <br />
<br />
Standardwert: 60 Sekunden<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{TIMEOUT}</code> <br />
<br />
''optional''<br />
|| Die maximale Zeit in Sekunden für den Aufbau einer TCP/IP-Verbindung. Sollte diese Zeit überschritten werden, bricht der Verbindungsaufbau mit einer Fehlermeldung ab.<br />
<br />
'''WICHTIG:''' Sollte beim Aufruf von [[#DevIo_OpenDev|DevIo_OpenDev()]] keine Callback-Funktion parametrisiert sein und die Gegenstelle antwortet beim Verbindungsaufbau nicht, so wird FHEM für die Dauer von <code>$hash->{TIMEOUT}</code> blockiert.<br />
<br />
Standardwert: 3 Sekunden<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{SSL}</code> <br />
<br />
''optional''<br />
|| Flag (0 oder 1), ob eine TCP/IP-Verbindung verschlüsselt (via SSL/TLS) aufgebaut werden soll. Wenn dieses Flag auf 1 gesetzt ist, wird nach erfolgtem Verbindungsaufbau eine SSL-Session initiiert.<br />
<br />
Standardwert: 0 (keine Verschlüsselung)<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{devioLoglevel}</code> <br />
<br />
''optional''<br />
|| Das Loglevel in dem <code>disconnected</code>/<code>reappeared</code> Meldungen geloggt werden sollen. Standardmäßig werden solche Verbindungsabbrüche (<code>disconnected</code>/<code>reappeared</code>) im Loglevel 1 geloggt. Die erfolgreiche Erstverbindung wird standardmäßig im Loglevel 3 geloggt. Durch das Setzen von <code>$hash->{devioLoglevel}</code> werden diese Meldungen allesamt in dem gesetzten Loglevel ausgegeben. Details dazu siehe {{Link2Forum|Topic=61970}}.<br />
<br />
Standardwert: ''[leer]''<br />
|}<br />
<br />
= Die Funktionen =<br />
== DevIo_OpenDev() ==<br />
:<syntaxhighlight lang="perl">$error = DevIo_OpenDev($hash, $reopen, $initfn);<br />
$error = DevIo_OpenDev($hash, $reopen, $initfn, $callback);</syntaxhighlight><br />
<br />
Die Funktion DevIo_OpenDev() öffnet eine Verbindung zu dem Endpunkt der in <code>$hash->{DeviceName}</code> hinterlegt ist. Sobald die Verbindung erfolgreich hergestellt wurde, wird die Funktion <code>$initfn</code> ausgeführt, sofern gesetzt, um die Verbindung zu initialisieren. Sofern eine TCP/IP-Verbindung hergestellt wird, kann eine optionale Callback-Funktion <code>$callback</code> übergeben werden um den Verbindungsaufbau non-blocking durchzuführen.<br />
<br />
Der Rückgabewert enthält im Fehlerfall eine entsprechende Fehlermeldung. Im Erfolgsfall wird <code>undef</code> zurückgegeben. Sofern eine TCP/IP-Verbindung hergestellt wird und eine Callback-Funktion <code>$callback</code> übergeben wurde, wird immer <code>undef</code> zurückgegeben, da ein evtl. Fehler an diese Callback-Funktion nach dem erfolgten Verbindungsversuch mitgeteilt wird.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
| style="vertical-align:top" | Die Hash-Referenz der Definition, für die eine Verbindung geöffnet werden soll<br />
|-<br />
| style="vertical-align:top" | '''<code>$reopen</code>''' <br />
<br />
''mandatory<br>can be <code>undef</code>''<br />
| style="vertical-align:top" | Flag (0 oder 1), ob es sich um einen erneuten Verbindungsversuch handelt (im Rahmen der [[DevelopmentModuleIntro#X_Ready|X_Ready()]]-Funktion). Sollte es der erste Verbindungsversuch sein, so muss dieser Parameter den Wert 0 besitzen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$initfn</code>''' <br />
<br />
''mandatory<br>can be <code>undef</code>''<br />
|| Der Name (als Zeichenkette) oder die Referenz auf eine Modulfunktion, welche optional nach dem erfolgreichen Aufbau/Wiederaufbau der Verbindung ausgeführt werden soll. Im Rahmen dieser Funktion kann weiterführende Kommunikation über die aufgebaute Verbindung erfolgen um zum Beispiel eine Loginsequenz oder eine Konfiguration der Gegenseite vorzunehmen, bevor die Verbindung allgemein benutzt werden kann. <br />
<br />
Die Funktion welche in <code>$initfn</code> angegeben wurde, wird mit folgenden Parametern aufgerufen:<br />
<br />
<syntaxhighlight lang="perl">$ret = MYMODULE_InitFn($hash)</syntaxhighlight><br />
<br />
Wenn der Rückgabewert <code>$ret</code> einen Inhalt zurückliefert, wird die Initialisierung als fehlgeschlagen bewertet und die Verbindung wieder geschlossen um einen neuen Verbindungsversuch zu einem späteren Zeitpunkt zu versuchen. Der genaue Inhalt von <code>$ret</code> ist dabei unerheblich, da er nicht weiterverwendet wird. Die Rückgabewerte <code>0</code> oder <code>undef</code> signalisieren dabei eine erfolgreiche Initialisierung.<br />
<br />
Beispiel: <br />
* <code>"MYMODULE_InitFn"</code><br />
* <code>\&MYMODULE_InitFn</code><br />
|-<br />
| style="vertical-align:top" | '''<code>$callback</code>''' <br />
<br />
''optional''<br />
|| Der Name (als Zeichenkette) oder die Referenz auf eine Modulfunktion, welche aufgerufen werden soll um evtl. Fehlermeldungen beim Verbindungsaufbau einer TCP/IP-Verbindung an das Modul zurückzuliefern. Wenn eine Callback-Funktion gesetzt ist, erfolgt der Verbindungsaufbau non-blocking. Andernfalls wartet DevIo_OpenDev() bis die Verbindung steht bzw. ein Fehler auftritt (z.B. Timeout).<br />
<br />
Die Funktion welche in <code>$callback</code> angegeben wurde, wird mit folgenden Parametern aufgerufen:<br />
<br />
<syntaxhighlight lang="perl">MYMODULE_ConnectCallbackFn($hash, $error)</syntaxhighlight><br />
<br />
Das Argument <code>$error</code> enthält dabei eine Fehlermeldung als Zeichenkette welche die aufgetretene Fehlermeldung enthält. Der Rückgabewert der Callback-Funktion wird nicht ausgewertet und ist daher irrelevant.<br />
<br />
Beispiel: <br />
* <code>"MYMODULE_ConnectCallbackFn"</code><br />
* <code>\&MYMODULE_ConnectCallbackFn</code><br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$error </code>''' || Eine Fehlermeldung als Zeichenkette, sollte der Verbindungsaufbau fehlschlagen. Im Erfolgsfall wird <code>undef</code> zurückgegeben.<br />
<br />
Wenn es sich um eine TCP/IP-Verbindung handelt und eine Callback-Funktion als Parameter <code>$callback</code> angegeben wurde, wird immer <code>undef</code> zurückgegeben, andernfalls erfolgt der Verbindungsaufbau blocking und eine evtl. Fehlermeldung wird als Rückgabewert zurückgegeben. Im Erfolgsfall wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_IsOpen() ==<br />
:<syntaxhighlight lang="perl">$status = DevIo_IsOpen($hash);</syntaxhighlight><br />
<br />
Die Funktion DevIo_IsOpen() prüft, ob eine Verbindung für <code>$hash</code> geöffnet ist. Falls ja, wird das zugehörige IO-Objekt zurückgegeben, andernfalls <code>undef</code>.<br />
<br />
Diese Funktion kann dabei direkt in typischen if-Konstrukten verwendet werden um zu prüfen, ob eine Verbindung für die jeweilige Definition geöffnet oder geschlossen ist.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, deren Verbindung geprüft werden soll.<br />
|}<br />
<br />
Rückgabewerte:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabewert !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Verbindung. Wenn eine Verbindung besteht, wird das zugehörige IO-Objekt zurückgegeben. Falls keine Verbindung besteht, wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_SimpleRead() ==<br />
:<syntaxhighlight lang="perl">$buf = DevIo_SimpleRead($hash);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleRead() liest anstehende Daten für die Verbindung von <code>$hash</code> ein und gibt diese zurück.<br />
<br />
Sollte beim Versuch Daten zu lesen eine geschlossene Verbindung erkannt werden, so wird <code>undef</code> zurückgegeben und die Verbindung geschlossen. Es erfolgt zu einem späteren Zeitpunkt (siehe Internal <code>$hash->{nextOpenDelay}</code> aus Kapitel [[#Wichtige Internals zur Konfiguration|Wichtige Internals zur Konfiguration]]) ein neuer Verbindungsversuch.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung aktuell anstehende Daten gelesen werden sollen.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die zu lesenden Daten als Zeichenkette. Im Falle eines Verbindungsabruchs wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_SimpleReadWithTimeout() ==<br />
{{Randnotiz|RNTyp=Warn|RNText=<u>'''ACHTUNG:'''</u><br />
<br />
Bei der Benutzung von DevIo_SimpleReadWithTimeout() wird FHEM für die Dauer von bis zu <code>$timeout</code> Sekunden blockiert, sollten keine Daten bis dahin zum Lesen bereitstehen.}}<br />
:<syntaxhighlight lang="perl">$buf = DevIo_SimpleReadWithTimeout($hash, $timeout);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleReadWithTimeout() wartet maximal <code>$timeout</code> Sekunden bis die Verbindung von <code>$hash</code> Daten zum einlesen bereitstellt und gibt diese zurück. Sollte nach dem Warten von <code>$timeout</code> noch immer keine Daten zum Lesen bereitstehen, so wird ein Leerstring zurückgegeben.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung aktuell anstehende Daten gelesen werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$timeout</code>''' <br />
<br />
''mandatory''<br />
|| Die maximale Wartezeit in Sekunden.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die zu lesenden Daten als Zeichenkette.<br />
|}<br />
<br />
== DevIo_TimeoutRead() ==<br />
{{Randnotiz|RNTyp=Warn|RNText=<u>'''ACHTUNG:'''</u><br />
<br />
Bei der Benutzung von DevIo_TimeoutRead() wird FHEM für die Dauer von <code>$timeout</code> Sekunden blockiert.}}<br />
:<syntaxhighlight lang="perl">$buf = DevIo_TimeoutRead($hash, $timeout);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleReadWithTimeout() wartet <code>$timeout</code> Sekunden und liest sämtliche Daten für die Verbindung von <code>$hash</code> ein, die in dieser Zeit eintreffen. Sollten keinerlei Daten während der Wartezeit eintreffen, so wird ein Leerstring zurückgegeben.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung Daten eingelesen werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$timeout</code>''' <br />
<br />
''mandatory''<br />
|| Die Wartezeit in Sekunden.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die eingelesenen Daten als Zeichenkette.<br />
|}<br />
<br />
== DevIo_SimpleWrite() ==<br />
:<syntaxhighlight lang="perl">DevIo_SimpleWrite($hash, $msg, $type);<br />
DevIo_SimpleWrite($hash, $msg, $type, $addnl);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleWrite() sendet den Inhalt von <code>$msg</code> über die Verbindung von <code>$hash</code>. Mit den beiden Argumenten <code>$type</code> und <code>$addnl</code> kann die Formatierung von <code>$msg</code> beeinflusst werden bevor die Daten tatsächlich gesendet werden.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, über deren Verbindung die Daten gesendet werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$msg</code>''' <br />
<br />
''mandatory''<br />
|| Die zu schreibenden Daten als Zeichenkette. Abhängig von <code>$type</code> kann <code>$msg</code> Byte-Characters, HEX-Darstellungen oder normale ASCII-Zeichen enthalten.<br />
|-<br />
| style="vertical-align:top" | '''<code>$type</code>''' <br />
<br />
''mandatory''<br />
|| Die Art des Inhalts von <code>$msg</code>. Abhängig von dem Inhalt von <code>$type</code> wird <code>$msg</code> entsprechend geändert oder nicht. Desweiteren werden die Daten für Logausgaben evtl. leserlich gemacht.<br />
<br />
Folgende Werte sind möglich:<br />
<br />
* <code>0</code> - <code>$msg</code> enthält Daten in Byteform. Der Inhalt von <code>$msg</code> wird 1:1 gesendet. Zur besseren Lesbarkeit werden die Daten bei Logausgaben in HEX-Darstellung umgewandelt.<br />
* <code>1</code> - <code>$msg</code> enthält Binärdaten in HEX-Darstellung (0-9/A-F). Der Inhalt von <code>$msg</code> wird vorher in Byteform umgewandelt und anschließend gesendet. In Logausgaben wird die HEX-Darstellung wie übergeben verwendet.<br />
* <code>2</code> - <code>$msg</code> enthält normale ASCII-Textzeichen. Der Inhalt von <code>$msg</code> wird 1:1 gesendet. In Logausgaben wird <code>$msg</code> wie übergeben ausgegeben.<br />
|-<br />
| style="vertical-align:top" | '''<code>$addnl</code>''' <br />
<br />
''optional''<br />
|| Ein Flag (0/1) welches, sofern aktiviert, einen Zeilenumbruch (<code>\n</code>) an <code>$msg</code> anfügt, bevor es gesendet wird.<br />
<br />
Standardwert: 0<br />
|}<br />
<br />
== DevIo_Expect() ==<br />
{{Randnotiz|RNTyp=Warn|RNText=<u>'''ACHTUNG:'''</u><br />
<br />
# Bei der Benutzung von DevIo_Expect() wird FHEM für die Dauer von bis zu <code>$timeout</code> Sekunden blockiert.<br />
# Sollte im ersten Versuch keine Antwort auf die zuvor gesendeten Daten innerhalb von <code>$timeout</code> Sekunden eintreffen, wird die Verbindung geschlossen und neu aufgebaut. Es erfolgt dabei '''KEINE INITIALISIERUNG''' durch <code>$initfn</code> aus [[#DevIo_OpenDev()|DevIo_OpenDev()]].<br />
}}<br />
:<syntaxhighlight lang="perl">$buf = DevIo_Expect($hash, $msg, $timeout);</syntaxhighlight><br />
<br />
Die Funktion DevIo_Expect() sendet den Inhalt von <code>$msg</code> und wartet bis zu <code>$timeout</code> Sekunden auf eine Antwort. Sollte in dieser Zeit keine Antwort eintreffen, so wird die Verbindung einmalig geschlossen, erneut geöffnet (ohne Aufruf einer Initialisierungs-Funktion) und der Vorgang wiederholt. Die empfangene Antwort wird anschließend als Funktionsergebnis zurückgegeben.<br />
<br />
Wenn beim ersten Versuch keine Antwort innerhalb von <code>$timeout</code> Sekunden eintrifft, wird das Event <code>FAILED</code> generiert (siehe [[#Generierte Events|Generierte Events]]). Anschließend wird die Verbindung geschlossen, neu geöffnet (ohne Initialisierung) und <code>$msg</code> erneut gesendet. Sollte nun eine Antwort eintreffen, so wird das Event <code>CONNECTED</code> generiert und die empfangene Antwort zurückgegeben. Sollte dennoch keine Antwort eintreffen, so wird das Event <code>DISCONNECTED</code> getriggert.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung Daten gesendet und anschließen gelesen werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$msg</code>''' <br />
<br />
''mandatory''<br />
|| Die zu sendenden Daten auf die eine Antwort erwartet wird. Die Daten werden ohne Konvertierung direkt gesendet (entspricht <code>$type</code> gleich <code>0</code> bei [[#DevIo_SimpleWrite()|DevIo_SimpleWrite]]).<br />
|-<br />
| style="vertical-align:top" | '''<code>$timeout</code>''' <br />
<br />
''mandatory''<br />
|| Die maximale Wartezeit in Sekunden bis zum Eintreffen einer Antwort.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die empfangene Antwort. Sollte es zu einem Fehler gekommen sein (Senden von <code>$msg</code> fehlgeschlagen, keine Antwort innerhalb von <code>$timeout</code> Sekunden erhalten, etc.), so wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_CloseDev() ==<br />
:<syntaxhighlight lang="perl">DevIo_CloseDev($hash);<br />
DevIo_CloseDev($hash, $isFork);</syntaxhighlight><br />
<br />
Die Funktion DevIo_CloseDev() schließt eine evtl. geöffnete Verbindung für die Definition <code>$hash</code>. <br />
<br />
Optional kann man mit dem Flag <code>$isFork</code> angeben, dass man sich aktuell in einem Fork vom Hauptprozess befindet. Dadurch wird beim Schließen von seriellen Verbindungen die Kommunikationsparameter nicht zurückgesetzt. Dies verhindert einen Ausfall der nachwievor bestehenden Verbindung im Hauptprozess.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, deren Verbindung geschlossen werden soll.<br />
|-<br />
| style="vertical-align:top" | '''<code>$isFork</code>''' <br />
<br />
''optional''<br />
|| Ein Flag (0 oder 1), welches angibt, dass DevIo_CloseDev() innerhalb eines geforkten Kindprozess ausgeführt wird. Dadurch werden serielle Verbindung so geschlossen, dass dabei die Kommunikationsparameter (Baudrate, Datenbits, Parität, etc.) nicht zurückgesetzt werden. Dieses Flag wird primär von dem Modul [[Blocking_Call|Blocking.pm]] verwendet um Verbindungen in einem geforkten Kindprozess zu schließen, ohne die Verbindung im Hauptprozess zu beeinträchtigen.<br />
<br />
Standardwert: 0 (Verbindung wird im Hauptprozess geschlossen)<br />
|}<br />
<br />
= Generierte Events =<br />
Die Funktionen von DevIo generieren verschiedene Events für die entsprechende Definition (parametrisiert durch <code>$hash</code>). Diese können bspw. in der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion des entsprechenden Moduls verarbeitet werden.<br />
<br />
Hier eine Übersicht der generierten Events:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Event !! Bedeutung<br />
|-<br />
| '''<code>CONNECTED</code>''' || Die Verbindung wurde nach einem Verbindungsabbruch erfolgreich wieder aufgebaut. Dieses Event wird nur nach einem erfolgreichen Reconnect von einer zuvor verlorenen Verbindung generiert. Es wird '''nicht''' nach der erfolgreichen Initialverbindung generiert.<br />
|-<br />
| '''<code>DISCONNECTED</code>''' || Die Verbindung ist zusammengebrochen. Es wird ein neuer Verbindungsversuch nach <code>$hash->{nextOpenDelay}</code> Sekunden erfolgen (siehe [[#Wichtige Internals zur Konfiguration|Wichtige Internals zur Konfiguration]]).<br />
|-<br />
| '''<code>FAILED</code>''' || Dieses Event wird nur bei der Nutzung der Funktion [[#DevIo_Expect|DevIo_Expect()]] generiert, sofern es keine Antwort auf die zuvor gesendeten Daten gibt. Dies bedeutet konkret, dass Gerät hat nicht auf die eigene Anfrage geantwortet und die Verbindung wird daher neu aufgebaut. Details dazu, siehe [[#DevIo_Expect()|DevIo_Expect()]].<br />
|}<br />
<br />
= Hinweis bei der Datenverarbeitung (Buffering) =<br />
DevIo beschränkt sich ausschließlich auf die Verbindungsverwaltung. Sobald die Verbindung etabliert wurde, übernimmt FHEM (fhem.pl) die Verarbeitung von eingehenden Daten und informiert das entsprechende Modul durch Aufruf der [[DevelopmentModuleIntro#X_Read|Read]]-Funktion. Dabei hat weder DevIo, noch FHEM selber Kenntnis von der Struktur der Daten. Sowohl DevIo, als auch FHEM selber können nicht erkennen, ob die empfangenen Daten weder vollständig, noch valide in ihrem Aufbau sind. Dies alles obliegt dem Modul, welches die Verbindung initiiert hat. Man sollte daher immer davon ausgehen, dass beim Lesen von Daten (in [[DevelopmentModuleIntro#X_Read|X_Read()]]) diese unvollständig sein können, oder sogar mehrere Datagramme enthalten sein können. <br />
<br />
Dazu stellt DevIo dem Modulentwickler das Internal <code>$hash->{PARTIAL}</code> in der jeweiligen Definition zur Verfügung um dort Daten zwischenzuspeichern, bis ein vollständiges Datagramm daraus verarbeitet werden kann. Alle eingelesenen Daten werden dazu in der [[DevelopmentModuleIntro#X_Read|Read]]-Funktion immer an <code>$hash->{PARTIAL}</code> hinten angehangen. Sobald ein vollständiges Datagramm in <code>$hash->{PARTIAL}</code> erkannt wurde, wird dieses herausgenommen und verarbeitet, solange bis kein vollständiges Datagramm in <code>$hash->{PARTIAL}</code> erkennbar ist. Hierbei ist jedoch entscheidend, woran man ein abgeschlossenes Datagramm erkennen kann. Dies kann je nach Protokoll sehr unterschiedlich sein (bspw. Zeilenumbruch <code>\r\n</code> oder ein Semikolon <code>;</code>, etc.). <br />
<br />
DevIo initialisiert <code>$hash->{PARTIAL}</code> nach dem erfolgreichen Verbindungsaufbau mit einem Leerstring (<code>""</code>). Sobald eine Verbindung mit [[#DevIo_CloseDev()|DevIo_CloseDev()]] geschlossen wird, wird <code>$hash->{PARTIAL}</code> gelöscht.<br />
<br />
Hier ein Beispiel, wie man ein solches Buffering verwendet für ein Protokoll, welches Datagramme durch einen Zeilenumbruch <code>\n</code> (Newline) abtrennt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub MY_MODULE_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
my $data = DevIo_SimpleRead($hash);<br />
return if(!defined($data)); # connection lost<br />
<br />
my $buffer = $hash->{PARTIAL};<br />
<br />
Log3 $name, 5, "MY_MODULE ($name) - received $data (buffer contains: $buffer)";<br />
<br />
# concat received data to $buffer<br />
$buffer .= $data;<br />
<br />
# as long as the buffer contains newlines (complete datagramm)<br />
while($buffer =~ m/\n/)<br />
{<br />
my $msg;<br />
<br />
# extract the complete message ($msg), everything else is assigned to $buffer<br />
($msg, $buffer) = split("\n", $buffer, 2);<br />
<br />
# remove trailing whitespaces<br />
chomp $msg;<br />
<br />
# update $hash->{PARTIAL} with the current buffer content<br />
$hash->{PARTIAL} = $buffer; <br />
<br />
# parse the extracted message<br />
MY_MODULE_ParseMessage($hash, $msg);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
= Beispielimplementierung in einem Modul =<br />
== serielle Verbindung ==<br />
<syntaxhighlight lang="perl"><br />
package main;<br />
<br />
use strict;<br />
use warnings;<br />
use DevIo; # load DevIo.pm if not already loaded<br />
<br />
# called upon loading the module MY_MODULE<br />
sub MY_MODULE_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
$hash->{DefFn} = "MY_MODULE_Define";<br />
$hash->{UndefFn} = "MY_MODULE_Undef";<br />
$hash->{SetFn} = "MY_MODULE_Set";<br />
$hash->{ReadFn} = "MY_MODULE_Read";<br />
$hash->{ReadyFn} = "MY_MODULE_Ready";<br />
}<br />
<br />
# called when a new definition is created (by hand or from configuration read on FHEM startup)<br />
sub MY_MODULE_Define($$)<br />
{<br />
my ($hash, $def) = @_;<br />
my @a = split("[ \t]+", $def);<br />
<br />
my $name = $a[0];<br />
<br />
# $a[1] is always equals the module name "MY_MODULE"<br />
<br />
# first argument is a serial device (e.g. "/dev/ttyUSB0@9600")<br />
my $dev = $a[2]; <br />
<br />
return "no device given" unless($dev);<br />
<br />
# add a default baud rate (9600), if not given by user<br />
$dev .= '@9600' if(not $dev =~ m/\@\d+$/);<br />
<br />
$hash->{DeviceName} = $dev;<br />
<br />
# close connection if maybe open (on definition modify)<br />
DevIo_CloseDev($hash) if(DevIo_IsOpen($hash)); <br />
<br />
# open connection with custom init function<br />
my $ret = DevIo_OpenDev($hash, 0, "MY_MODULE_Init"); <br />
<br />
return undef;<br />
}<br />
<br />
# called when definition is undefined <br />
# (config reload, shutdown or delete of definition)<br />
sub MY_MODULE_Undef($$)<br />
{<br />
my ($hash, $name) = @_;<br />
<br />
# close the connection <br />
DevIo_CloseDev($hash);<br />
<br />
return undef;<br />
}<br />
<br />
# called repeatedly if device disappeared<br />
sub MY_MODULE_Ready($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# try to reopen the connection in case the connection is lost<br />
return DevIo_OpenDev($hash, 1, "MY_MODULE_Init"); <br />
}<br />
<br />
# called when data was received<br />
sub MY_MODULE_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# read the available data<br />
my $buf = DevIo_SimpleRead($hash);<br />
<br />
# stop processing if no data is available (device disconnected)<br />
return if(!defined($buf));<br />
<br />
Log3 $name, 5, "MY_MODULE ($name) - received: $buf"; <br />
<br />
#<br />
# do something with $buf, e.g. generate readings, send answers via DevIo_SimpleWrite(), ...<br />
#<br />
<br />
}<br />
<br />
# called if set command is executed<br />
sub MY_MODULE_Set($$@)<br />
{<br />
my ($hash, $name, $cmd) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
my $usage = "unknown argument $cmd, choose one of statusRequest:noArg on:noArg off:noArg";<br />
<br />
if($cmd eq "statusRequest")<br />
{<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
}<br />
elsif($cmd eq "on")<br />
{<br />
DevIo_SimpleWrite($hash, "on\r\n", 2);<br />
}<br />
elsif($cmd eq "off")<br />
{<br />
DevIo_SimpleWrite($hash, "off\r\n", 2);<br />
}<br />
else<br />
{<br />
return $usage;<br />
}<br />
}<br />
<br />
# will be executed upon successful connection establishment (see DevIo_OpenDev())<br />
sub MY_MODULE_Init($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# send a status request to the device<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
<br />
return undef; <br />
}<br />
</syntaxhighlight><br />
<br />
== TCP/IP-Verbindung == <br />
<syntaxhighlight lang="perl"><br />
package main;<br />
<br />
use strict;<br />
use warnings;<br />
use DevIo; # load DevIo.pm if not already loaded<br />
<br />
# called upon loading the module MY_MODULE<br />
sub MY_MODULE_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
$hash->{DefFn} = "MY_MODULE_Define";<br />
$hash->{UndefFn} = "MY_MODULE_Undef";<br />
$hash->{SetFn} = "MY_MODULE_Set";<br />
$hash->{ReadFn} = "MY_MODULE_Read";<br />
$hash->{ReadyFn} = "MY_MODULE_Ready";<br />
}<br />
<br />
# called when a new definition is created (by hand or from configuration read on FHEM startup)<br />
sub MY_MODULE_Define($$)<br />
{<br />
my ($hash, $def) = @_;<br />
my @a = split("[ \t]+", $def);<br />
<br />
my $name = $a[0];<br />
<br />
# $a[1] is always equals the module name "MY_MODULE"<br />
<br />
# first argument is the hostname or IP address of the device (e.g. "192.168.1.120")<br />
my $dev = $a[2]; <br />
<br />
return "no device given" unless($dev);<br />
<br />
# add a default port (1012), if not explicitly given by user<br />
$dev .= ':1012' if(not $dev =~ m/:\d+$/);<br />
<br />
$hash->{DeviceName} = $dev;<br />
<br />
# close connection if maybe open (on definition modify)<br />
DevIo_CloseDev($hash) if(DevIo_IsOpen($hash)); <br />
<br />
# open connection with custom init and error callback function (non-blocking connection establishment)<br />
DevIo_OpenDev($hash, 0, "MY_MODULE_Init", "MY_MODULE_Callback"); <br />
<br />
return undef;<br />
}<br />
<br />
# called when definition is undefined <br />
# (config reload, shutdown or delete of definition)<br />
sub MY_MODULE_Undef($$)<br />
{<br />
my ($hash, $name) = @_;<br />
<br />
# close the connection <br />
DevIo_CloseDev($hash);<br />
<br />
return undef;<br />
}<br />
<br />
# called repeatedly if device disappeared<br />
sub MY_MODULE_Ready($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# try to reopen the connection in case the connection is lost<br />
return DevIo_OpenDev($hash, 1, "MY_MODULE_Init", "MY_MODULE_Callback"); <br />
}<br />
<br />
# called when data was received<br />
sub MY_MODULE_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# read the available data<br />
my $buf = DevIo_SimpleRead($hash);<br />
<br />
# stop processing if no data is available (device disconnected)<br />
return if(!defined($buf));<br />
<br />
Log3 $name, 5, "MY_MODULE ($name) - received: $buf"; <br />
<br />
#<br />
# do something with $buf, e.g. generate readings, send answers via DevIo_SimpleWrite(), ...<br />
#<br />
<br />
}<br />
<br />
# called if set command is executed<br />
sub MY_MODULE_Set($$@)<br />
{<br />
my ($hash, $name, $cmd) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
my $usage = "unknown argument $cmd, choose one of statusRequest:noArg on:noArg off:noArg";<br />
<br />
if($cmd eq "statusRequest")<br />
{<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
}<br />
elsif($cmd eq "on")<br />
{<br />
DevIo_SimpleWrite($hash, "on\r\n", 2);<br />
}<br />
elsif($cmd eq "off")<br />
{<br />
DevIo_SimpleWrite($hash, "off\r\n", 2);<br />
}<br />
else<br />
{<br />
return $usage;<br />
}<br />
}<br />
<br />
# will be executed upon successful connection establishment (see DevIo_OpenDev())<br />
sub MY_MODULE_Init($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# send a status request to the device<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
<br />
return undef; <br />
}<br />
<br />
# will be executed if connection establishment fails (see DevIo_OpenDev())<br />
sub MY_MODULE_Callback($)<br />
{<br />
my ($hash, $error) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# create a log emtry with the error message<br />
Log3 $name, 5, "MY_MODULE ($name) - error while connecting: $error"; <br />
<br />
return undef; <br />
}<br />
</syntaxhighlight><br />
<br />
= Referenzen = <br />
<references /><br />
<br />
<br />
[[Kategorie:Development]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=DevIo&diff=27363DevIo2018-07-10T10:15:49Z<p>Eisler: </p>
<hr />
<div>{{Infobox Modul<br />
|ModPurpose=Dienstfunktionen für die Kommunikation per serieller Schnittstelle (USB/RS232), TCP/IP-Verbindung oder UNIX-Socket<br />
|ModType=u<br />
|ModForumArea=FHEM Development<br />
|ModTechName=DevIo.pm<br />
|ModOwner=rudolfkoenig ({{Link2FU|8|Forum}} / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])<br />
}}<br />
<br />
Das Modul [[DevIo]](.pm) ist für Modulentwickler gedacht, um Daten zwischen einem FHEM-Modul und bspw. einer seriellen Schnittstelle, einer TCP/IP-Verbindung oder einem UNIX-Socket auszutauschen. Es übernimmt dabei die gesamte Verbindungsverwaltung und Aufrechterhaltung innerhalb von FHEM und nimmt dem Modulentwickler daher die gesamte Verbindungsverwaltung (Aufbau, Initialisierung, Neu-Verbindung bei Abbruch, etc.) ab. Es berücksichtigt dabei Besonderheiten zwischen Unix-basierten Betriebssystemen und Windows.<br />
<br />
Es dient dabei lediglich dem Zweck einen Kommunikationskanal für eine Definition in FHEM zu etablieren und Daten darüber auszutauschen. Die Interpretation der empfangenen Daten obliegt dem Modul, welches die Verbindung via DevIo geöffnet hat. Die ausgetauschten Daten werden durch DevIo nicht verändert.<br />
<br />
= Allgemeine Funktionsweise =<br />
DevIo hat das Ziel eine besonders einfache Möglichkeit für Modulentwickler zu schaffen, um einen dauerhaften Kommunikationskanal mit einem Hardware- oder Netzwerk-Gerät bzw. Service zu etablieren. Um eine Verbindung aufzubauen muss zunächst die Gegenstelle bekannt sein. Dazu muss vor dem Verbindungsaufbau in dem Internal <code>$hash->{DeviceName}</code> der jeweiligen Definition das Ziel hinterlegt werden. Dies kann bspw. eine serielle Schnittstelle sein (z.B. "/dev/ttyUSB0" oder "COM1" unter Windows) oder eine TCP/IP-Gegenstelle (z.B. "192.168.1.100:1012") sein. Eine detaillierte Aufstellung der möglichen Verbindungsarten und deren Angabe in <code>$hash->{DeviceName}</code> gibt es im folgenden Kapitel [[#Unterstützte Verbindungsarten|Unterstützte Verbindungsarten]].<br />
<br />
Die Funktion [[#DevIo_OpenDev()|DevIo_OpenDev()]] baut dabei die entsprechende Verbindung für eine einzelne Definition in Form eines Filedeskriptors auf und registriert diesen in dem globalen Hash <code>%selectlist</code><ref name="selectlist">[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|Development Module Introduction]] - Wichtige globale Variablen aus fhem.pl</ref>. Sobald die Verbindung erfolgreich aufgebaut wurde, kann eine, durch den Modulautor mitgelieferte, Initialisierungs-Funktion ausgeführt werden, um die Kommunikation zu initialiseren (bspw. das Senden einer Authentifizierungs-/Loginsequenz oder aktivieren der Hardware, etc.).<br />
<br />
FHEM (respektive fhem.pl) prüft nun regelmäßig, ob Daten zum Lesen bereitstehen (also Daten empfangen wurden). Ist dies der Fall, so wird die [[DevelopmentModuleIntro#X_Read|X_Read()]]-Funktion des zugehörigen Moduls für die hinterlegte Definition aufgerufen. Hier können die Daten durch den Aufruf von [[#DevIo_SimpleRead()|DevIo_SimpleRead()]] nun eingelesen und verarbeitet werden. Das Senden von Daten ist durch den Aufruf von [[#DevIo_SimpleWrite()|DevIo_SimpleWrite()]] sehr einfach möglich.<br />
<br />
Sollte die Verbindung zusammenbrechen (USB-Gerät abgezogen, Gerät per Netzwerk nicht mehr erreichbar, etc.), so erkennt dies DevIo und registriert die Definition in <code>%readyfnlist</code><ref name="selectlist" />. FHEM führt nun regelmäßig die [[DevelopmentModuleIntro#X_Ready|X_Ready()]]-Funktion des zugehörigen Moduls<br />
aus um zu prüfen, ob die Verbindung wieder aufgebaut werden kann. Hier wird nun durch die Ausführung von [[#DevIo_OpenDev()|DevIo_OpenDev()]] versucht die Verbindung wieder herzustellen.<br />
<br />
Sobald die Verbindung nicht mehr benötigt wird, oder FHEM bspw. beendet wird, kann die Verbindung via [[#DevIo_CloseDev()|DevIo_CloseDev()]] sauber geschlossen werden.<br />
<br />
= Unterstützte Verbindungsarten = <br />
<br />
Die folgenden Verbindungsarten können via DevIo realisiert werden.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Verbindungsart !! Beispielangabe in<br><code>$hash->{DeviceName}</code> !! Beschreibung<br />
|-<br />
| style="vertical-align:top" | '''Serielle Schnittstelle'''<br />
| style="vertical-align:top" |<br />
* <code>/dev/ttyUSB0</code> <br />
* <code>/dev/ttyUSB0@9600</code><br />
* <code>/dev/ttyUSB0@9600,7,E,2</code><br />
* <code>/dev/ttyUSB0@directio</code><br />
* <code>COM1@9600</code><br />
|| <br />
Durch Angabe eines Geräts in Form eines Gerätepfad (UNIX-basierte Betriebssysteme) oder der Schnittstellenbezeichnung aus Windows kann eine serielle Verbindung geöffnet werden. Der Gerätename kann zusätzliche Angaben zu Baudrate, Datenbits, Parität und Stoppbits enthalten um die Verbindung entsprechend zu konfiguieren. Diese Angaben sind durch ein "@" getrennt an die Gerätebezeichnung angehangen:<br />
<br />
Schematische Syntax: <code>''<font color="grey"><Gerät></font>'''''@'''''<Baudrate>''''','''''<Datenbits>''''','''''<Parität>''''','''''<Stopbits></code><br />
<br />
* <code><Baudrate></code> - Eine gültige Taktfrequenz (Symbole pro Sekunde) mit der die Schnittstelle geöffnet werden soll (Beispiel: <code>9600</code>, <code>14400</code>, <code>115200</code>, ...)<br />
* <code><Datenbits></code> - Die Anzahl an Datenbits (7 oder 8 Datenbits). Standardwert sofern nicht angegeben sind 8 Datenbits.<br />
* <code><Parität></code> - Die zu verwendende Parität, sofern benötigt. Dabei bedeutet der Wert <code>N</code> keine Parität, <code>O</code> bedeutet ungleiche Parität (odd) und <code>E</code> bedeutet gleiche Parität (even) Standardwert sofern nicht angegeben ist <code>N</code> (keine Parität).<br />
* <code><Stopbits></code> - Die Anzahl an zu verwendenden Stopbits (0, 1 oder 2 Stopbits). Standardwert sofern nicht angegeben sind 0 Stopbits.<br />
<br />
Wenn man unter Unix-basierten Betriebssystemen die Schnittstelle nicht explizit konfiguriert öffnen möchte, sondern das Gerät direkt öffnen möchte (und damit die OS-Einstellungen verwendet), kann man durch Angabe von <code>@directio</code> die Konfiguration der Schnittstelle umgehen und das Gerät direkt öffnen:<br />
<br />
Bsp: <code><font color="grey">/dev/ttyUSB0</font>@directio</code><br />
<br />
Unter Windows verwendet man als Gerätename die entsprechende Schnittstellenbezeichung wie bspw. <code>COM1</code>, <code>COM2</code>, usw.<br />
|-<br />
| style="vertical-align:top" | '''TCP/IP-Verbindung'''<br />
| style="vertical-align:top" | <br />
* <code>192.168.1.2:1012</code> <br />
* <code>raspberry:5000</code><br />
||<br />
Durch Angabe eines Hostnamen oder IP-Adresse und einem Port, kann eine TCP-Verbindung aufgebaut werden. Dazu muss Hostname/IP-Adresse und Port in folgendem Schema angegeben werden:<br />
<br />
Schematische Syntax: <code>''<Hostname/IP-Adresse>''''':'''''<Port>''</code><br />
<br />
* <code><Hostname/IP-Adresse></code> - Der Hostname oder die IP-Adresse des zu verbindenden Gerätes/Server.<br />
* <code><Port></code> - Der Zielport zu dem sich verbunden werden soll (0-65535).<br />
<br />
Die Verbindung kann optional verschlüsselt via SSL/TLS aufgebaut werden. Dazu muss das Internal <code>$hash->{SSL}</code> auf 1 gesetzt werden.<br />
|-<br />
| style="vertical-align:top" | '''UNIX-Socket'''<br />
| style="vertical-align:top"|<br />
* <code>UNIX:SEQPACKET:/var/tmp/me_avm_home_external.ctl</code> <br />
* <code>UNIX:STREAM:/var/socket/con</code><br />
|| <br />
Durch Angabe eines Pfads zu einem UNIX-Domain-Socket kann eine Kommunikation mit einem anderen Prozess aufgebaut werden (Inter-Prozess-Kommunikation). Man kann den Socket dabei paketorientiert ("SEQPACKET") oder als Stream ("STREAM") öffnen. <br />
<br />
Schematische Syntax: <code>UNIX:''<Typ>'':''<Pfad>''</code><br />
<br />
* <code><Typ></code> - Der Typ des Sockets. Für einen paketorientierten Socket ist hier <code>SEQPACKET</code> zu verwenden, für einen streamorientierten Socket <code>STREAM</code>. Der Typ muss immer mit angegeben werden.<br />
* <code><Pfad></code> - Der Pfad im Dateisystem zu dem gewünschten UNIX-Socket<br />
|-<br />
| style="vertical-align:top" | '''FHEM IO-Modul'''<br />
| style="vertical-align:top" |<br />
* <code>FHEM:DEVIO:Firmata_SerielleSchnittstelle@9600</code> <br />
|| <br />
Beschreibung siehe {{Link2Forum|Topic=46276}}<br />
|}<br />
<br />
= Wichtige Internals zur Konfiguration =<br />
<br />
Da DevIo ausschließlich definitionsbezogen arbeitet, erfolgt eine Konfiguration von DevIo über Internals, die im übergebenen <code>$hash</code> gesetzt werden müssen (oder können). Hiermit lässt sich das Verhalten von DevIo entsprechend beeinflussen. <br />
<br />
Hier eine Auflistung von allen Internals, die DevIo beeinflussen:<br />
<br />
{| class="wikitable"<br />
|-<br />
! style="min-width: 13em;" | Internal !! Beschreibung<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{DeviceName}</code> <br />
<br />
''mandatory''<br />
| style="vertical-align:top" | Die Gegenstelle zu der eine Verbindung aufgebaut werden soll. Die möglichen Werte und deren Syntax ist im Kapitel [[#Unterstützte Verbindungsarten|Unterstützte Verbindungsarten]] genauer beschrieben.<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{nextOpenDelay}</code> <br />
<br />
''optional''<br />
|| Die Zeit in Sekunden, welche im Falle eines Verbindungsabbruchs gewartet werden soll, bevor ein erneuter Verbindungsversuch stattfindet. <br />
<br />
Standardwert: 60 Sekunden<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{TIMEOUT}</code> <br />
<br />
''optional''<br />
|| Die maximale Zeit in Sekunden für den Aufbau einer TCP/IP-Verbindung. Sollte diese Zeit überschritten werden, bricht der Verbindungsaufbau mit einer Fehlermeldung ab.<br />
<br />
'''WICHTIG:''' Sollte beim Aufruf von [[#DevIo_OpenDev|DevIo_OpenDev()]] keine Callback-Funktion parametrisiert sein und die Gegenstelle antwortet beim Verbindungsaufbau nicht, so wird FHEM für die Dauer von <code>$hash->{TIMEOUT}</code> blockiert.<br />
<br />
Standardwert: 3 Sekunden<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{SSL}</code> <br />
<br />
''optional''<br />
|| Flag (0 oder 1), ob eine TCP/IP-Verbindung verschlüsselt (via SSL/TLS) aufgebaut werden soll. Wenn dieses Flag auf 1 gesetzt ist, wird nach erfolgtem Verbindungsaufbau eine SSL-Session initiiert.<br />
<br />
Standardwert: 0 (keine Verschlüsselung)<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{devioLoglevel}</code> <br />
<br />
''optional''<br />
|| Das Loglevel in dem <code>disconnected</code>/<code>reappeared</code> Meldungen geloggt werden sollen. Standardmäßig werden solche Verbindungsabbrüche (<code>disconnected</code>/<code>reappeared</code>) im Loglevel 1 geloggt. Die erfolgreiche Erstverbindung wird standardmäßig im Loglevel 3 geloggt. Durch das Setzen von <code>$hash->{devioLoglevel}</code> werden diese Meldungen allesamt in dem gesetzten Loglevel ausgegeben. Details dazu siehe {{Link2Forum|Topic=61970}}.<br />
<br />
Standardwert: ''[leer]''<br />
|}<br />
<br />
= Die Funktionen =<br />
== DevIo_OpenDev() ==<br />
:<syntaxhighlight lang="perl">$error = DevIo_OpenDev($hash, $reopen, $initfn);<br />
$error = DevIo_OpenDev($hash, $reopen, $initfn, $callback);</syntaxhighlight><br />
<br />
Die Funktion DevIo_OpenDev() öffnet eine Verbindung zu dem Endpunkt der in <code>$hash->{DeviceName}</code> hinterlegt ist. Sobald die Verbindung erfolgreich hergestellt wurde, wird die Funktion <code>$initfn</code> ausgeführt, sofern gesetzt, um die Verbindung zu initialisieren. Sofern eine TCP/IP-Verbindung hergestellt wird, kann eine optionale Callback-Funktion <code>$callback</code> übergeben werden um den Verbindungsaufbau non-blocking durchzuführen.<br />
<br />
Der Rückgabewert enthält im Fehlerfall eine entsprechende Fehlermeldung. Im Erfolgsfall wird <code>undef</code> zurückgegeben. Sofern eine TCP/IP-Verbindung hergestellt wird und eine Callback-Funktion <code>$callback</code> übergeben wurde, wird immer <code>undef</code> zurückgegeben, da ein evtl. Fehler an diese Callback-Funktion nach dem erfolgten Verbindungsversuch mitgeteilt wird.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
| style="vertical-align:top" | Die Hash-Referenz der Definition, für die eine Verbindung geöffnet werden soll<br />
|-<br />
| style="vertical-align:top" | '''<code>$reopen</code>''' <br />
<br />
''mandatory<br>can be <code>undef</code>''<br />
| style="vertical-align:top" | Flag (0 oder 1), ob es sich um einen erneuten Verbindungsversuch handelt (im Rahmen der [[DevelopmentModuleIntro#X_Ready|X_Ready()]]-Funktion). Sollte es der erste Verbindungsversuch sein, so muss dieser Parameter den Wert 0 besitzen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$initfn</code>''' <br />
<br />
''mandatory<br>can be <code>undef</code>''<br />
|| Der Name (als Zeichenkette) oder die Referenz auf eine Modulfunktion, welche optional nach dem erfolgreichen Aufbau/Wiederaufbau der Verbindung ausgeführt werden soll. Im Rahmen dieser Funktion kann weiterführende Kommunikation über die aufgebaute Verbindung erfolgen um zum Beispiel eine Loginsequenz oder eine Konfiguration der Gegenseite vorzunehmen, bevor die Verbindung allgemein benutzt werden kann. <br />
<br />
Die Funktion welche in <code>$initfn</code> angegeben wurde, wird mit folgenden Parametern aufgerufen:<br />
<br />
<syntaxhighlight lang="perl">$ret = MYMODULE_InitFn($hash)</syntaxhighlight><br />
<br />
Wenn der Rückgabewert <code>$ret</code> einen Inhalt zurückliefert, wird die Initialisierung als fehlgeschlagen bewertet und die Verbindung wieder geschlossen um einen neuen Verbindungsversuch zu einem späteren Zeitpunkt zu versuchen. Der genaue Inhalt von <code>$ret</code> ist dabei unerheblich, da er nicht weiterverwendet wird. Die Rückgabewerte <code>0</code> oder <code>undef</code> signalisieren dabei eine erfolgreiche Initialisierung.<br />
<br />
Beispiel: <br />
* <code>"MYMODULE_InitFn"</code><br />
* <code>\&MYMODULE_InitFn</code><br />
|-<br />
| style="vertical-align:top" | '''<code>$callback</code>''' <br />
<br />
''optional''<br />
|| Der Name (als Zeichenkette) oder die Referenz auf eine Modulfunktion, welche aufgerufen werden soll um evtl. Fehlermeldungen beim Verbindungsaufbau einer TCP/IP-Verbindung an das Modul zurückzuliefern. Wenn eine Callback-Funktion gesetzt ist, erfolgt der Verbindungsaufbau non-blocking. Andernfalls wartet DevIo_OpenDev() bis die Verbindung steht bzw. ein Fehler auftritt (z.B. Timeout).<br />
<br />
Die Funktion welche in <code>$callback</code> angegeben wurde, wird mit folgenden Parametern aufgerufen:<br />
<br />
<syntaxhighlight lang="perl">MYMODULE_ConnectCallbackFn($hash, $error)</syntaxhighlight><br />
<br />
Das Argument <code>$error</code> enthält dabei eine Fehlermeldung als Zeichenkette welche die aufgetretene Fehlermeldung enthält. Der Rückgabewert der Callback-Funktion wird nicht ausgewertet und ist daher irrelevant.<br />
<br />
Beispiel: <br />
* <code>"MYMODULE_ConnectCallbackFn"</code><br />
* <code>\&MYMODULE_ConnectCallbackFn</code><br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$error </code>''' || Eine Fehlermeldung als Zeichenkette, sollte der Verbindungsaufbau fehlschlagen. Im Erfolgsfall wird <code>undef</code> zurückgegeben.<br />
<br />
Wenn es sich um eine TCP/IP-Verbindung handelt und eine Callback-Funktion als Parameter <code>$callback</code> angegeben wurde, wird immer <code>undef</code> zurückgegeben, andernfalls erfolgt der Verbindungsaufbau blocking und eine evtl. Fehlermeldung wird als Rückgabewert zurückgegeben. Im Erfolgsfall wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_IsOpen() ==<br />
:<syntaxhighlight lang="perl">$status = DevIo_IsOpen($hash);</syntaxhighlight><br />
<br />
Die Funktion DevIo_IsOpen() prüft, ob eine Verbindung für <code>$hash</code> geöffnet ist. Falls ja, wird das zugehörige IO-Objekt zurückgegeben, andernfalls <code>undef</code>.<br />
<br />
Diese Funktion kann dabei direkt in typischen if-Konstrukten verwendet werden um zu prüfen, ob eine Verbindung für die jeweilige Definition geöffnet oder geschlossen ist.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, deren Verbindung geprüft werden soll.<br />
|}<br />
<br />
Rückgabewerte:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabewert !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Verbindung. Wenn eine Verbindung besteht, wird das zugehörige IO-Objekt zurückgegeben. Falls keine Verbindung besteht, wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_SimpleRead() ==<br />
:<syntaxhighlight lang="perl">$buf = DevIo_SimpleRead($hash);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleRead() liest anstehende Daten für die Verbindung von <code>$hash</code> ein und gibt diese zurück.<br />
<br />
Sollte beim Versuch Daten zu lesen eine geschlossene Verbindung erkannt werden, so wird <code>undef</code> zurückgegeben und die Verbindung geschlossen. Es erfolgt zu einem späteren Zeitpunkt (siehe Internal <code>$hash->{nextOpenDelay}</code> aus Kapitel [[#Wichtige Internals zur Konfiguration|Wichtige Internals zur Konfiguration]]) ein neuer Verbindungsversuch.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung aktuell anstehende Daten gelesen werden sollen.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die zu lesenden Daten als Zeichenkette. Im Falle eines Verbindungsabruchs wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_SimpleReadWithTimeout() ==<br />
{{Randnotiz|RNTyp=Warn|RNText=<u>'''ACHTUNG:'''</u><br />
<br />
Bei der Benutzung von DevIo_SimpleReadWithTimeout() wird FHEM für die Dauer von bis zu <code>$timeout</code> Sekunden blockiert, sollten keine Daten bis dahin zum Lesen bereitstehen.}}<br />
:<syntaxhighlight lang="perl">$buf = DevIo_SimpleReadWithTimeout($hash, $timeout);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleReadWithTimeout() wartet maximal <code>$timeout</code> Sekunden bis die Verbindung von <code>$hash</code> Daten zum einlesen bereitstellt und gibt diese zurück. Sollte nach dem Warten von <code>$timeout</code> noch immer keine Daten zum Lesen bereitstehen, so wird ein Leerstring zurückgegeben.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung aktuell anstehende Daten gelesen werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$timeout</code>''' <br />
<br />
''mandatory''<br />
|| Die maximale Wartezeit in Sekunden.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die zu lesenden Daten als Zeichenkette.<br />
|}<br />
<br />
== DevIo_TimeoutRead() ==<br />
{{Randnotiz|RNTyp=Warn|RNText=<u>'''ACHTUNG:'''</u><br />
<br />
Bei der Benutzung von DevIo_TimeoutRead() wird FHEM für die Dauer von <code>$timeout</code> Sekunden blockiert.}}<br />
:<syntaxhighlight lang="perl">$buf = DevIo_TimeoutRead($hash, $timeout);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleReadWithTimeout() wartet <code>$timeout</code> Sekunden und liest sämtliche Daten für die Verbindung von <code>$hash</code> ein, die in dieser Zeit eintreffen. Sollten keinerlei Daten während der Wartezeit eintreffen, so wird ein Leerstring zurückgegeben.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung Daten eingelesen werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$timeout</code>''' <br />
<br />
''mandatory''<br />
|| Die Wartezeit in Sekunden.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die eingelesenen Daten als Zeichenkette.<br />
|}<br />
<br />
== DevIo_SimpleWrite() ==<br />
:<syntaxhighlight lang="perl">DevIo_SimpleWrite($hash, $msg, $type);<br />
DevIo_SimpleWrite($hash, $msg, $type, $addnl);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleWrite() sendet den Inhalt von <code>$msg</code> über die Verbindung von <code>$hash</code>. Mit den beiden Argumenten <code>$type</code> und <code>$addnl</code> kann die Formatierung von <code>$msg</code> beeinflusst werden bevor die Daten tatsächlich gesendet werden.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, über deren Verbindung die Daten gesendet werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$msg</code>''' <br />
<br />
''mandatory''<br />
|| Die zu schreibenden Daten als Zeichenkette. Abhängig von <code>$type</code> kann <code>$msg</code> Byte-Characters, HEX-Darstellungen oder normale ASCII-Zeichen enthalten.<br />
|-<br />
| style="vertical-align:top" | '''<code>$type</code>''' <br />
<br />
''mandatory''<br />
|| Die Art des Inhalts von <code>$msg</code>. Abhängig von dem Inhalt von <code>$type</code> wird <code>$msg</code> entsprechend geändert oder nicht. Desweiteren werden die Daten für Logausgaben evtl. leserlich gemacht.<br />
<br />
Folgende Werte sind möglich:<br />
<br />
* <code>0</code> - <code>$msg</code> enthält Daten in Byteform. Der Inhalt von <code>$msg</code> wird 1:1 gesendet. Zur besseren Lesbarkeit werden die Daten bei Logausgaben in HEX-Darstellung umgewandelt.<br />
* <code>1</code> - <code>$msg</code> enthält Binärdaten in HEX-Darstellung (0-9/A-F). Der Inhalt von <code>$msg</code> wird vorher in Byteform umgewandelt und anschließend gesendet. In Logausgaben wird die HEX-Darstellung wie übergeben verwendet.<br />
* <code>2</code> - <code>$msg</code> enthält normale ASCII-Textzeichen. Der Inhalt von <code>$msg</code> wird 1:1 gesendet. In Logausgaben wird <code>$msg</code> wie übergeben ausgegeben.<br />
|-<br />
| style="vertical-align:top" | '''<code>$addnl</code>''' <br />
<br />
''optional''<br />
|| Ein Flag (0/1) welches, sofern aktiviert, einen Zeilenumbruch (<code>\n</code>) an <code>$msg</code> anfügt, bevor es gesendet wird.<br />
<br />
Standardwert: 0<br />
|}<br />
<br />
== DevIo_Expect() ==<br />
{{Randnotiz|RNTyp=Warn|RNText=<u>'''ACHTUNG:'''</u><br />
<br />
# Bei der Benutzung von DevIo_Expect() wird FHEM für die Dauer von bis zu <code>$timeout</code> Sekunden blockiert.<br />
# Sollte im ersten Versuch keine Antwort auf die zuvor gesendeten Daten innerhalb von <code>$timeout</code> Sekunden eintreffen, wird die Verbindung geschlossen und neu aufgebaut. Es erfolgt dabei '''KEINE INITIALISIERUNG''' durch <code>$initfn</code> aus [[#DevIo_OpenDev()|DevIo_OpenDev()]].<br />
}}<br />
:<syntaxhighlight lang="perl">$buf = DevIo_Expect($hash, $msg, $timeout);</syntaxhighlight><br />
<br />
Die Funktion DevIo_Expect() sendet den Inhalt von <code>$msg</code> und wartet bis zu <code>$timeout</code> Sekunden auf eine Antwort. Sollte in dieser Zeit keine Antwort eintreffen, so wird die Verbindung einmalig geschlossen, erneut geöffnet (ohne Aufruf einer Initialisierungs-Funktion) und der Vorgang wiederholt. Die empfangene Antwort wird anschließend als Funktionsergebnis zurückgegeben.<br />
<br />
Wenn beim ersten Versuch keine Antwort innerhalb von <code>$timeout</code> Sekunden eintrifft, wird das Event <code>FAILED</code> generiert (siehe [[#Generierte Events|Generierte Events]]). Anschließend wird die Verbindung geschlossen, neu geöffnet (ohne Initialisierung) und <code>$msg</code> erneut gesendet. Sollte nun eine Antwort eintreffen, so wird das Event <code>CONNECTED</code> generiert und die empfangene Antwort zurückgegeben. Sollte dennoch keine Antwort eintreffen, so wird das Event <code>DISCONNECTED</code> getriggert.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung Daten gesendet und anschließen gelesen werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$msg</code>''' <br />
<br />
''mandatory''<br />
|| Die zu sendenden Daten auf die eine Antwort erwartet wird. Die Daten werden ohne Konvertierung direkt gesendet (entspricht <code>$type</code> gleich <code>0</code> bei [[#DevIo_SimpleWrite()|DevIo_SimpleWrite]]).<br />
|-<br />
| style="vertical-align:top" | '''<code>$timeout</code>''' <br />
<br />
''mandatory''<br />
|| Die maximale Wartezeit in Sekunden bis zum Eintreffen einer Antwort.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die empfangene Antwort. Sollte es zu einem Fehler gekommen sein (Senden von <code>$msg</code> fehlgeschlagen, keine Antwort innerhalb von <code>$timeout</code> Sekunden erhalten, etc.), so wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_CloseDev() ==<br />
:<syntaxhighlight lang="perl">DevIo_CloseDev($hash);<br />
DevIo_CloseDev($hash, $isFork);</syntaxhighlight><br />
<br />
Die Funktion DevIo_CloseDev() schließt eine evtl. geöffnete Verbindung für die Definition <code>$hash</code>. <br />
<br />
Optional kann man mit dem Flag <code>$isFork</code> angeben, dass man sich aktuell in einem Fork vom Hauptprozess befindet. Dadurch wird beim Schließen von seriellen Verbindungen die Kommunikationsparameter nicht zurückgesetzt. Dies verhindert einen Ausfall der nachwievor bestehenden Verbindung im Hauptprozess.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, deren Verbindung geschlossen werden soll.<br />
|-<br />
| style="vertical-align:top" | '''<code>$isFork</code>''' <br />
<br />
''optional''<br />
|| Ein Flag (0 oder 1), welches angibt, dass DevIo_CloseDev() innerhalb eines geforkten Kindprozess ausgeführt wird. Dadurch werden serielle Verbindung so geschlossen, dass dabei die Kommunikationsparameter (Baudrate, Datenbits, Parität, etc.) nicht zurückgesetzt werden. Dieses Flag wird primär von dem Modul [[Blocking_Call|Blocking.pm]] verwendet um Verbindungen in einem geforkten Kindprozess zu schließen, ohne die Verbindung im Hauptprozess zu beeinträchtigen.<br />
<br />
Standardwert: 0 (Verbindung wird im Hauptprozess geschlossen)<br />
|}<br />
<br />
= Generierte Events =<br />
Die Funktionen von DevIo generieren verschiedene Events für die entsprechende Definition (parametrisiert durch <code>$hash</code>). Diese können bspw. in der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion des entsprechenden Moduls verarbeitet werden.<br />
<br />
Hier eine Übersicht der generierten Events:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Event !! Bedeutung<br />
|-<br />
| '''<code>CONNECTED</code>''' || Die Verbindung wurde nach einem Verbindungsabbruch erfolgreich wieder aufgebaut. Dieses Event wird nur nach einem erfolgreichen Reconnect von einer zuvor verlorenen Verbindung generiert. Es wird '''nicht''' nach der erfolgreichen Initialverbindung generiert.<br />
|-<br />
| '''<code>DISCONNECTED</code>''' || Die Verbindung ist zusammengebrochen. Es wird ein neuer Verbindungsversuch nach <code>$hash->{nextOpenDelay}</code> Sekunden erfolgen (siehe [[#Wichtige Internals zur Konfiguration|Wichtige Internals zur Konfiguration]]).<br />
|-<br />
| '''<code>FAILED</code>''' || Dieses Event wird nur bei der Nutzung der Funktion [[#DevIo_Expect|DevIo_Expect()]] generiert, sofern es keine Antwort auf die zuvor gesendeten Daten gibt. Dies bedeutet konkret, dass Gerät hat nicht auf die eigene Anfrage geantwortet und die Verbindung wird daher neu aufgebaut. Details dazu, siehe [[#DevIo_Expect()|DevIo_Expect()]].<br />
|}<br />
<br />
= Hinweis bei der Datenverarbeitung (Buffering) =<br />
DevIo beschränkt sich ausschließlich auf die Verbindungsverwaltung. Sobald die Verbindung etabliert wurde, übernimmt FHEM (fhem.pl) die Verarbeitung von eingehenden Daten und informiert das entsprechende Modul durch Aufruf der [[DevelopmentModuleIntro#X_Read|Read]]-Funktion. Dabei hat weder DevIo, noch FHEM selber Kenntnis von der Struktur der Daten. Sowohl DevIo, als auch FHEM selber können nicht erkennen, ob die empfangenen Daten weder vollständig, noch valide in ihrem Aufbau sind. Dies alles obliegt dem Modul, welches die Verbindung initiiert hat. Man sollte daher immer davon ausgehen, dass beim Lesen von Daten (in [[DevelopmentModuleIntro#X_Read|X_Read()]]) diese unvollständig sein können, oder sogar mehrere Datagramme enthalten sein können. <br />
<br />
Dazu stellt DevIo dem Modulentwickler das Internal <code>$hash->{PARTIAL}</code> in der jeweiligen Definition zur Verfügung um dort Daten zwischenzuspeichern, bis ein vollständiges Datagramm daraus verarbeitet werden kann. Alle eingelesenen Daten werden dazu in der [[DevelopmentModuleIntro#X_Read|Read]]-Funktion immer an <code>$hash->{PARTIAL}</code> hinten angehangen. Sobald ein vollständiges Datagramm in <code>$hash->{PARTIAL}</code> erkannt wurde, wird dieses herausgenommen und verarbeitet, solange bis kein vollständiges Datagramm in <code>$hash->{PARTIAL}</code> erkennbar ist. Hierbei ist jedoch entscheidend, woran man ein abgeschlossenes Datagramm erkennen kann. Dies kann je nach Protokoll sehr unterschiedlich sein (bspw. Zeilenumbruch <code>\r\n</code> oder ein Semikolon <code>;</code>, etc.). <br />
<br />
DevIo initialisiert <code>$hash->{PARTIAL}</code> nach dem erfolgreichen Verbindungsaufbau mit einem Leerstring (<code>""</code>). Sobald eine Verbindung mit [[#DevIo_CloseDev()|DevIo_CloseDev()]] geschlossen wird, wird <code>$hash->{PARTIAL}</code> gelöscht.<br />
<br />
Hier ein Beispiel, wie man ein solches Buffering verwendet für ein Protokoll, welches Datagramme durch einen Zeilenumbruch <code>\n</code> (Newline) abtrennt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub MY_MODULE_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
my $data = DevIo_SimpleRead($hash);<br />
return if(!defined($data)); # connection lost<br />
<br />
my $buffer = $hash->{PARTIAL};<br />
<br />
Log3 $name, 5, "MY_MODULE ($name) - received $data (buffer contains: $buf)";<br />
<br />
# concat received data to $buffer<br />
$buffer .= $data;<br />
<br />
# as long as the buffer contains newlines (complete datagramm)<br />
while($buffer =~ m/\n/)<br />
{<br />
my $msg;<br />
<br />
# extract the complete message ($msg), everything else is assigned to $buffer<br />
($msg, $buffer) = split("\n", $buffer, 2);<br />
<br />
# remove trailing whitespaces<br />
chomp $msg;<br />
<br />
# update $hash->{PARTIAL} with the current buffer content<br />
$hash->{PARTIAL} = $buffer; <br />
<br />
# parse the extracted message<br />
MY_MODULE_ParseMessage($hash, $msg);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
= Beispielimplementierung in einem Modul =<br />
== serielle Verbindung ==<br />
<syntaxhighlight lang="perl"><br />
package main;<br />
<br />
use strict;<br />
use warnings;<br />
use DevIo; # load DevIo.pm if not already loaded<br />
<br />
# called upon loading the module MY_MODULE<br />
sub MY_MODULE_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
$hash->{DefFn} = "MY_MODULE_Define";<br />
$hash->{UndefFn} = "MY_MODULE_Undef";<br />
$hash->{SetFn} = "MY_MODULE_Set";<br />
$hash->{ReadFn} = "MY_MODULE_Read";<br />
$hash->{ReadyFn} = "MY_MODULE_Ready";<br />
}<br />
<br />
# called when a new definition is created (by hand or from configuration read on FHEM startup)<br />
sub MY_MODULE_Define($$)<br />
{<br />
my ($hash, $def) = @_;<br />
my @a = split("[ \t]+", $def);<br />
<br />
my $name = $a[0];<br />
<br />
# $a[1] is always equals the module name "MY_MODULE"<br />
<br />
# first argument is a serial device (e.g. "/dev/ttyUSB0@9600")<br />
my $dev = $a[2]; <br />
<br />
return "no device given" unless($dev);<br />
<br />
# add a default baud rate (9600), if not given by user<br />
$dev .= '@9600' if(not $dev =~ m/\@\d+$/);<br />
<br />
$hash->{DeviceName} = $dev;<br />
<br />
# close connection if maybe open (on definition modify)<br />
DevIo_CloseDev($hash) if(DevIo_IsOpen($hash)); <br />
<br />
# open connection with custom init function<br />
my $ret = DevIo_OpenDev($hash, 0, "MY_MODULE_Init"); <br />
<br />
return undef;<br />
}<br />
<br />
# called when definition is undefined <br />
# (config reload, shutdown or delete of definition)<br />
sub MY_MODULE_Undef($$)<br />
{<br />
my ($hash, $name) = @_;<br />
<br />
# close the connection <br />
DevIo_CloseDev($hash);<br />
<br />
return undef;<br />
}<br />
<br />
# called repeatedly if device disappeared<br />
sub MY_MODULE_Ready($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# try to reopen the connection in case the connection is lost<br />
return DevIo_OpenDev($hash, 1, "MY_MODULE_Init"); <br />
}<br />
<br />
# called when data was received<br />
sub MY_MODULE_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# read the available data<br />
my $buf = DevIo_SimpleRead($hash);<br />
<br />
# stop processing if no data is available (device disconnected)<br />
return if(!defined($buf));<br />
<br />
Log3 $name, 5, "MY_MODULE ($name) - received: $buf"; <br />
<br />
#<br />
# do something with $buf, e.g. generate readings, send answers via DevIo_SimpleWrite(), ...<br />
#<br />
<br />
}<br />
<br />
# called if set command is executed<br />
sub MY_MODULE_Set($$@)<br />
{<br />
my ($hash, $name, $cmd) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
my $usage = "unknown argument $cmd, choose one of statusRequest:noArg on:noArg off:noArg";<br />
<br />
if($cmd eq "statusRequest")<br />
{<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
}<br />
elsif($cmd eq "on")<br />
{<br />
DevIo_SimpleWrite($hash, "on\r\n", 2);<br />
}<br />
elsif($cmd eq "off")<br />
{<br />
DevIo_SimpleWrite($hash, "off\r\n", 2);<br />
}<br />
else<br />
{<br />
return $usage;<br />
}<br />
}<br />
<br />
# will be executed upon successful connection establishment (see DevIo_OpenDev())<br />
sub MY_MODULE_Init($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# send a status request to the device<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
<br />
return undef; <br />
}<br />
</syntaxhighlight><br />
<br />
== TCP/IP-Verbindung == <br />
<syntaxhighlight lang="perl"><br />
package main;<br />
<br />
use strict;<br />
use warnings;<br />
use DevIo; # load DevIo.pm if not already loaded<br />
<br />
# called upon loading the module MY_MODULE<br />
sub MY_MODULE_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
$hash->{DefFn} = "MY_MODULE_Define";<br />
$hash->{UndefFn} = "MY_MODULE_Undef";<br />
$hash->{SetFn} = "MY_MODULE_Set";<br />
$hash->{ReadFn} = "MY_MODULE_Read";<br />
$hash->{ReadyFn} = "MY_MODULE_Ready";<br />
}<br />
<br />
# called when a new definition is created (by hand or from configuration read on FHEM startup)<br />
sub MY_MODULE_Define($$)<br />
{<br />
my ($hash, $def) = @_;<br />
my @a = split("[ \t]+", $def);<br />
<br />
my $name = $a[0];<br />
<br />
# $a[1] is always equals the module name "MY_MODULE"<br />
<br />
# first argument is the hostname or IP address of the device (e.g. "192.168.1.120")<br />
my $dev = $a[2]; <br />
<br />
return "no device given" unless($dev);<br />
<br />
# add a default port (1012), if not explicitly given by user<br />
$dev .= ':1012' if(not $dev =~ m/:\d+$/);<br />
<br />
$hash->{DeviceName} = $dev;<br />
<br />
# close connection if maybe open (on definition modify)<br />
DevIo_CloseDev($hash) if(DevIo_IsOpen($hash)); <br />
<br />
# open connection with custom init and error callback function (non-blocking connection establishment)<br />
DevIo_OpenDev($hash, 0, "MY_MODULE_Init", "MY_MODULE_Callback"); <br />
<br />
return undef;<br />
}<br />
<br />
# called when definition is undefined <br />
# (config reload, shutdown or delete of definition)<br />
sub MY_MODULE_Undef($$)<br />
{<br />
my ($hash, $name) = @_;<br />
<br />
# close the connection <br />
DevIo_CloseDev($hash);<br />
<br />
return undef;<br />
}<br />
<br />
# called repeatedly if device disappeared<br />
sub MY_MODULE_Ready($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# try to reopen the connection in case the connection is lost<br />
return DevIo_OpenDev($hash, 1, "MY_MODULE_Init", "MY_MODULE_Callback"); <br />
}<br />
<br />
# called when data was received<br />
sub MY_MODULE_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# read the available data<br />
my $buf = DevIo_SimpleRead($hash);<br />
<br />
# stop processing if no data is available (device disconnected)<br />
return if(!defined($buf));<br />
<br />
Log3 $name, 5, "MY_MODULE ($name) - received: $buf"; <br />
<br />
#<br />
# do something with $buf, e.g. generate readings, send answers via DevIo_SimpleWrite(), ...<br />
#<br />
<br />
}<br />
<br />
# called if set command is executed<br />
sub MY_MODULE_Set($$@)<br />
{<br />
my ($hash, $name, $cmd) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
my $usage = "unknown argument $cmd, choose one of statusRequest:noArg on:noArg off:noArg";<br />
<br />
if($cmd eq "statusRequest")<br />
{<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
}<br />
elsif($cmd eq "on")<br />
{<br />
DevIo_SimpleWrite($hash, "on\r\n", 2);<br />
}<br />
elsif($cmd eq "off")<br />
{<br />
DevIo_SimpleWrite($hash, "off\r\n", 2);<br />
}<br />
else<br />
{<br />
return $usage;<br />
}<br />
}<br />
<br />
# will be executed upon successful connection establishment (see DevIo_OpenDev())<br />
sub MY_MODULE_Init($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# send a status request to the device<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
<br />
return undef; <br />
}<br />
<br />
# will be executed if connection establishment fails (see DevIo_OpenDev())<br />
sub MY_MODULE_Callback($)<br />
{<br />
my ($hash, $error) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# create a log emtry with the error message<br />
Log3 $name, 5, "MY_MODULE ($name) - error while connecting: $error"; <br />
<br />
return undef; <br />
}<br />
</syntaxhighlight><br />
<br />
= Referenzen = <br />
<references /><br />
<br />
<br />
[[Kategorie:Development]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=MQTT_(Modul)&diff=26350MQTT (Modul)2018-04-02T07:41:26Z<p>Eisler: </p>
<hr />
<div>{{Infobox Modul<br />
|ModPurpose=Stellt als Gateway die Verbindung zu einem MQTT-Broker her<br />
|ModType=d<br />
|ModForumArea=MQTT<br />
|ModTechName=00_MQTT.pm<br />
|ModOwner=eisler ({{Link2FU|2214|Forum}}) }}<br />
Das Modul [[MQTT]] fungiert als [[Interface|Verbindung]] zwischen FHEM und einem MQTT Broker und repräsentiert ein '''''MQTT Gateway'''''. Die durch die Module [[MQTT_DEVICE]] oder {{Link2CmdRef|Anker=MQTT_BRIDGE|Lang=en|Label=MQTT_BRIDGE}} repräsentierten Client-Geräte sind gesondert anzulegen.<br />
<br />
== Voraussetzungen ==<br />
Es muss für jedes MQTT-Gateway ein Broker eingerichtet und erreichbar sein.<br />
Eine Anleitung zur Einrichtung eines Mosquitto-Brokers finden Sie z.B. im Artikel [[MQTT Einführung]].<br />
<br />
== Begrifflichkeiten in Kürze ==<br />
Ein Broker ist ein zentraler Serverdienst (irgendwo im Netz oder auf derselben Maschine, auf der auch FHEM läuft), an den Geräte ihre Informationen weitergeben (publish), und der dann dafür sorgt, dass diese Information an alle anderen Geräte weitergegeben wird, die sich dafür interessieren (subscribe). [[MQTT]] fungiert dabei als [[Systemübersicht#Interfaces| IO-Modul]] und organisiert die Kommunikation zwischen dem Broker und allen FHEM-Geräten, die MQTT bei diesem Server nutzen wollen.<br />
<br />
== Define ==<br />
Das MQTT Gateway wird angelegt mit<br />
<code>define '''meinMQTTGW''' MQTT <Broker-IP>[:<Broker-Port>]</code><br />
<br />
== Anwendung ==<br />
Danach können entsprechende Client-Devices angelegt werden, <br />
[[MQTT_DEVICE]] wird verwendet, wenn das physikalische Device (Sensor oder Aktor) über mqtt kommuniziert, wie dieses z.B. bei vielen ESP8266-basierten Geräten der Fall ist. <br />
{{Link2CmdRef|Anker=MQTT_BRIDGE|Lang=en|Label=MQTT_BRIDGE}} ist für den Fall, dass ein FHEM-Device<ref>Dies kann z.B. ein beliebiger HM- oder Z-Wave-Aktor sein, der ein Licht einschaltet.</ref> existiert und dieses über MQTT sicht- bzw. steuerbar gemacht werden soll.<br />
<br />
== Ergänzende Funktionen ==<br />
Manche MQTT-Geräte senden Informationen im JSON-Format. Um solche Informationen in FHEM verwenden zu können, müssen sie zunächst in ein anderes Format überführt werden. Hierfür wird das Modul {{Link2CmdRef|Anker=expandJSON|Lang=en|Label=expandJSON}} benötigt.<br />
<br />
== Anwendungsbeispiele ==<br />
<br />
<br />
== Links ==<br />
* {{Link2Forum|Topic=27532|LinkText=Ankündigung}} der MQTT Module<br />
* [[MQTT Einführung]]<br />
<br />
== Anmerkungen ==<br />
<references /><br />
<br />
[[Kategorie:IP Components|IP Komponenten]]<br />
[[Kategorie:Other Components]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=DevelopmentModuleIntro&diff=26267DevelopmentModuleIntro2018-03-25T11:48:38Z<p>Eisler: /* X_Set */</p>
<hr />
<div>{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}<br />
<br />
<br />
== Einleitung ==<br />
<br />
Um neue Geräte, Dienste, o.ä. in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben. Ein Modul wird in FHEM automatisch geladen, wenn ein entsprechendes Device in FHEM definiert wird. Das Modul ermöglicht eine spezifische Kommunikation mit einem physikalischen Gerät, stellt Ergebnisse ("Readings") und Events innerhalb von FHEM zur Verfügung und erlaubt es, das Gerät mit "Set"-/"Get"-Befehlen zu beeinflussen. Dieser Artikel soll den Einstieg in die Entwicklung eigener Module erleichtern.<br />
<br />
Mit dem FHEM-Befehl <code>define</code> werden Devices in FHEM basierend auf einem Modul definiert. Dieser Befehl sorgt dafür, dass ein neues Modul bei Bedarf geladen und initialisiert wird. Ein gutes Beispiel ist hierbei die zentrale Konfigurationsdatei "fhem.cfg" in der sämtliche Devices in Form von <code>define</code>-Statements gespeichert sind.<br />
<br />
Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:<br />
<br />
Ein Jeelink USB-Stick könnte beispielsweise mit dem Befehl <code>define JeeLink1 ''JeeLink'' /dev/ttyUSB0@57600</code> definiert werden.<br />
<br />
In fhem.pl wird der define-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und dann geladen. <br />
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''&lt;Modulname&gt;''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt.<br />
<br />
In der Initialisierungsfunktion des Moduls werden die Namen aller weiteren Perl-Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird für jedes Modul ein eigener Hash (genauer "Modul-Hash") mit entsprechenden Werten gefüllt, der in fhem.pl für jedes Modul entsprechend abgelegt wird. Dadurch weiß FHEM wie dieses Modul anzusprechen ist.<br />
<br />
== Grundlegender Aufbau eines Moduls ==<br />
<br />
=== Dateiname ===<br />
<br />
Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:<br />
<br />
:<code>''['''Schlüsselnummer''']''<font color="grey">_</font>''['''Modulname''']''<font color="grey">.pm</font></code><br />
<br />
* '''Schlüsselnummer''' - Eine zweistellige Zahl zwischen 00 - 99. Die Schlüsselnummer hat aktuell keine technische Relevanz mehr. In früheren FHEM-Versionen ist sie relevant für [[#Zweistufiges_Modell_f.C3.BCr_Module|zweistufige Module]] (Reihenfolge für [[DevelopmentModuleAPI#Dispatch|Dispatch()]] um logische Module zu prüfen). Die allgemeine Empfehlung ist hierbei eine Schlüsselnummer eines Moduls zu verwenden, welches eine ähnliche Funktionalität bietet. Die Schlüsselnummer 99 hat hierbei eine besondere Bedeutung, da alle Module mit dieser Schlüsselnummer beim Start von FHEM automatisch geladen werden, selbst, wenn sie in der Konfiguration nicht verwendet werden. Daher wird für myUtils 99 als Schlüsselnummer verwendet (99_myUtils.pm). Module mit der Schlüsselnummer 99 werden im SVN nicht akzeptiert (siehe [[SVN Nutzungsregeln]])<br />
* '''Modulname''' - Der Name des Moduls wie er in FHEM bei dem Anlegen einer Gerätedefinition zu verwenden ist. Der Modulname sollte nur aus den folgenden möglichen Zeichen bestehen: Groß-/Kleinbuchstaben, Zahlen sowie Unterstrich (_)<br />
<br />
=== Inhaltlicher Aufbau ===<br />
<br />
Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:<br />
<br />
<syntaxhighlight lang="perl"><br />
#<br />
# 72_MYMODULE.pm <br />
#<br />
<br />
package main;<br />
<br />
# Laden evtl. abhängiger Perl- bzw. FHEM-Module<br />
use HttpUtils;<br />
use [...]<br />
<br />
# FHEM Modulfunktionen<br />
<br />
sub MYMODULE_Initialize() {<br />
...<br />
}<br />
<br />
sub MYMODULE_Define() {<br />
...<br />
}<br />
<br />
...<br />
<br />
# Eval-Rückgabewert für erfolgreiches<br />
# Laden des Moduls<br />
1;<br />
<br />
<br />
# Beginn der Commandref<br />
<br />
=pod<br />
=item [helper|device|command]<br />
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt<br />
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt<br />
<br />
=begin html<br />
Englische Commandref in HTML<br />
=end html<br />
<br />
=begin html_DE<br />
Deustche Commandref in HTML<br />
=end html<br />
<br />
# Ende der Commandref<br />
=cut<br />
</syntaxhighlight><br />
<br />
Man kann hierbei von folgender Reihenfolge sprechen:<br />
<br />
# Perl-Code, welcher das Modul implementiert<br />
# Die Zeile <code>1;</code> nachdem der Perl-Code abgeschlossen ist. Dies dient FHEM der Erkennung, dass das Modul erfolgreich und vollständig geladen wurde. Sollte diese Zeile nicht enthalten sein, wird FHEM beim Laden des Moduls die Fehlermeldung <code>Error:Modul 72_MYMODULE deactivated</code> in das Logfile schreiben.<br />
# Commandref zur Dokumentation des Moduls. Diese Dokumentation soll dem User die möglichen Befehle/Attribute/Readings/Events vermitteln. Weitere Informationen und Hinweise findet man in den [[Guidelines zur Dokumentation]].<br />
<br />
== Der Hash einer Geräteinstanz ==<br />
Eine Besonderheit in Perl sind [http://de.wikipedia.org/wiki/Assoziatives_Array#Perl assoziative Arrays], (nicht ganz richtig als "Hash" bezeichnet) in denen die Adressierung nicht über eine Zählvariable erfolgt, sondern über einen beliebigen String. Die internen Abläufe bei der Adressierung führen dazu, dass die Speicherung in und der Abruf aus Hashes relativ langsam ist.<br />
<br />
Der zentrale Speicherort für Informationen einer Geräteinstanz bei FHEM ist ein solcher Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird. <br />
<br />
In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''&lt;Name&gt;''}</code> in fhem.pl verweist dabei auf den Hash der Geräteinstanz in Form einer Hashreferenz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben (i.d.R. als <code>$hash</code> bezeichnet), welche direkt von fhem.pl aufgerufen werden. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im Frontend als "Internals" angezeigt werden, sowie die Readings des Geräts. <br />
<br />
Beispiele:<br />
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz, <br />
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)<br />
<br />
==Ausführung von Modulen==<br />
FHEM arbeitet intern nicht parallel, sondern arbeitet alle Aufgaben seriell nacheinander kontinuierlich ab. Daher wäre es ungünstig, wenn Module Daten von einem physikalischen Gerät abfragen wollen und dabei innerhalb der selben Funktion auf die Antwort des Geräts warten. In dieser Zeit, in der FHEM auf die Antwort des Gerätes warten muss, wäre der Rest von FHEM blockiert. Da immer nur eine Aufgabe zur selben Zeit bearbeitet wird, müssen alle weiteren Aufgaben solange warten. Eine Datenkommunikation innerhalb eines Moduls sollte daher immer ohne Blockierung erfolgen. Dadurch kann FHEM die Wartezeit effizient für andere Aufgaben nutzen um bspw. anstehende Daten für andere Module zu verarbeiten. Es gibt in FHEM entsprechende Mechanismen, welche eine "Non-Blocking"-Kommunikation über verschiedene Wege (z.B. seriell, HTTP, TCP, ...) ermöglichen.<br />
<br />
Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sind. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet um Filedeskriptoren auf lesbare Daten zu überprüfen. In FHEM gibt es dazu eine Liste (<code>%selectlist</code>), in der die Filedeskriptoren sämtlicher Geräte (z.B. serielle Verbindung, TCP-Verbindung, etc.) gespeichert sind. <br />
<br />
In der zentralen Schleife (Main-Loop) von fhem.pl wird mit <code>select()</code> überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion ([[#X_Read|X_Read]]) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und verarbeitet. Anschließend wird die Schleife weiter ausgeführt.<br />
<br />
Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per <code>select()</code> überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion ([[#X_Ready|X_Ready]]) implementieren, welche prüft, ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt, beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.<br />
<br />
Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert um die Daten zu interpretieren und Werte in Readings geschrieben.<br />
<br />
Auch wenn von einem Anwender über einen Get-Befehl Daten aktiv von einem Gerät angefordert werden, sollte nicht blockierend gewartet werden. Eine asynchrone Ausgabe, sobald das Ergebnis vorliegt, ist über [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] möglich. Siehe {{Link2Forum|Topic=43771|Message=357870|LinkText=Beschreibung}} und {{Link2Forum|Topic=43771|Message=360935|LinkText=Beispiel}}. Weitere Anwendungsbeispiele finden sich im {{Link2Forum|Topic=43052|Message=353477|LinkText=PLEX Modul}} und im überarbeiteten und nicht-blockierenden {{Link2Forum|Topic=42771|Message=348498|LinkText=SYSSTAT Modul}}.<br />
<br />
== Wichtige globale Variablen aus fhem.pl ==<br />
<br />
FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Variable !! Beschreibung<br />
|-<br />
| <code>$init_done</code> || Dient der Erkennung für fhem.pl sowie den Modulen, ob FHEM den Initialisierungsvorgang abgeschlossen hat. Beim Starten von FHEM ist <code>$init_done</code> gleich <code>0</code>. Erst, wenn das Einlesen der Konfiguration, sowie des State-Files (Readings) abgeschlossen ist, wird <code>$init_done</code> auf <code>1</code> gesetzt.<br />
Das gleiche Verfahren wird auch bei dem Befehl <code>rereadcfg</code> angewandt. Während <code>rereadcfg</code> ausgeführt wird (Konfiguration löschen, neu einlesen), ist <code>$init_done</code> gleich <code>0</code>.<br />
<br />
Dies ist insbesondere in der [[#X_Define|Define]]-Funktion eines Moduls relevant. Durch eine Prüfung auf <code>$init_done</code> kann man erkennen, ob eine Definition von Hand (<code>$init_done</code> = 1) oder im Rahmen der Initialisierung (FHEM Start / Rereadcfg => <code>$init_done</code> = 0) erfolgte. Während der Initialisierung stehen bspw. die gesetzten Attribute der Definition noch nicht zur Verfügung und können daher nicht ausgewertet werden (siehe . <br />
|-<br />
| <code>%attr</code> || In <code>%attr</code> werden sämtliche gesetzten Attribute aller Geräte gespeichert. Diese Datenstruktur wird generell durch den <code>attr</code>-Befehl verwaltet. Hierbei wird einem Gerätenamen eine Mehrzahl an Attributnamen mit einem Wert zugeordnet. Attribut-Inhalte können über die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] ausgelesen werden.<br />
|-<br />
| <code>%cmds</code> || In <code>%cmds</code> wird jedem in FHEM existierendem Befehl die entsprechende Funktion zugewiesen, welche diesen Befehl umsetzt. Module können durch das Eintragen eines Befehlsnamen samt Funktion in <code>%cmds</code> über die [[#X_Initialize|Initialize]]-Funktion eines Moduls einen (oder mehrere) eigene Befehle in FHEM registrieren.<br />
<br />
Die Struktur ist dabei wiefolgt:<br />
<br />
$cmds{''&lt;Befehlsname&gt;''} = { Fn => "''&lt;Funktionsname&gt;''",<br />
Hlp => "''&lt;Aufrufsyntax&gt;''"};<br />
<br />
|-<br />
| <code>%data</code>|| Der eigentliche Zweck von <code>%data</code> ist dem Nutzer eine Möglichkeit zum Speichern von temporären Daten im globalen Kontext zu ermöglichen. Einige Module verwenden <code>%data</code> jedoch auch um modul- & geräteübergreifend Daten auszutauschen.<br />
|-<br />
| <code>%defs</code>|| In <code>%defs</code> werden sämtliche Gerätedefinitionen, bzw. die Hash-Referenzen auf diese, gespeichert. Hier ist jedem Gerätenamen eine Hash-Referenz zugeordnet.<br />
|-<br />
| <code>%modules</code>|| In <code>%modules</code> sind alle geladenen Module gelistet mit ihren entsprechenden Initialisierungsdaten (Funktionsnamen, Attribut-Listen, spezielle Einstellungen, ...). Hier wird für jeden Modulname der Modul-Hash aus der [[#X_Initialize|Initialize]]-Funktion gespeichert. <br />
Desweiteren legen viele Module, welche nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] hier eine Rückwärtszuordnung von Geräteadressen zu Geräte-Hash an.<br />
|-<br />
| <code>%readyfnlist</code>|| In <code>%readyfnlist</code> sind alle zu prüfenden Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte regelmäßig über eine Aufruf der entsprechenden [[#X_Ready|Ready]]-Funktion.<br />
<br />
Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%readyfnlist</code>.<br />
|-<br />
| <code>%selectlist</code>|| In <code>%selectlist</code> sind alle geöffneten Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte, ob der geöffnete Filedeskriptor unter <code>$hash->{FD}</code> Daten zum Lesen bereitgestellt hat. Ist dass der Fall, wird die entsprechende [[#X_Read|Read]]-Funktion aufgerufen, um anstehende Daten durch das Modul zu verarbeiten.<br />
Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%selectlist</code>.<br />
|}<br />
<br />
Es gibt durchaus viele weitere globale Variablen, die jedoch für sehr spezielle Anwendungsfälle und z.T. nur einzelne Module gedacht sind und daher hier nicht aufgeführt werden.<br />
<br />
== Internals ==<br />
Daten, die ein Modul im Geräte-Hash speichert nennt man Internals. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{NAME}</code> für den Gerätenamen, welcher beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Diese Daten spielen für FHEM eine sehr wichtige Rolle, da sämtliche gerätespezifischen Daten als Internal im Gerätehash gespeichert werden.<br />
<br />
Falls Werte wie z.B. ein Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollten, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen das Interval als Attribut über den Befehl <code>attr</code> gesetzt wird.<br />
<br />
Generell werden alle Werte, welche direkt in der ersten Ebene von <code>$hash</code> (Gerätehash) gespeichert werden auf der Detail-Seite einer Definition in der FHEMWEB Oberfläche angezeigt. Es gibt jedoch Ausnahmen:<br />
<br />
* <code>$hash->{helper}{URL}</code> - Alle Elemente, welche als Unterelement wieder einen Hash besitzen werden nicht in FHEMWEB dargestellt. Typischerweise speichern Module Daten unter <code>$hash->{helper}</code> interne Daten zwischen, die für den User nicht relevant sind, sondern nur der internen Verarbeitung dienen.<br />
* <code>$hash->{'''.'''<font color="grey">ELEMENT</font>}</code> - Alle Knoten, welche mit einem Punkt beginnen werden in der FHEMWEB Oberfläche nicht angezeigt. Man kann diese Daten jedoch beim Aufruf des [[List|list-Kommandos]] einsehen.<br />
<br />
Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:<br />
<br />
{| class="wikitable"<br />
|-<br />
! style="min-width: 13em;" | Internal !! Beschreibung<br />
|-<br />
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde. <br />
|-<br />
| <code>$hash->{READINGS}</code> || Enthält alle aktuell vorhandenen Readings. Daten unterhalb dieses Knotens sollte man nicht direkt manipulieren. Um Readings zu Erzeugen gibt es entsprechende [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]].<br />
|-<br />
| <code>$hash->{NR}</code> || Die Positions-Nr. der Definition innerhalb der Konfiguration. Diese dient dazu die Konfiguration in der gleichen Reihenfolge zu speichern, wie die einzelnen Geräte angelegt wurden.<br />
|-<br />
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.<br />
|-<br />
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.<br />
|-<br />
| <code>$hash->{CFGFN}</code> || Der Dateiname der Konfigurationsdatei in der diese Definition enthalten ist (sofern nicht in fhem.cfg). Dieser Wert ist nur gefüllt, wenn man mit mehreren Konfigurationsdateien arbeitet, welche dann in fhem.cfg via include-Befehl eingebunden werden.<br />
|-<br />
| <code>$hash->{NTFY_ORDER}</code> || Sofern das Modul Events via [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] verarbeitet enthält jede Definition eine Notify-Order als Zeichenkette bestehend aus dem Notify Order Prefix und dem Definitionsnamen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Reihenfolge für den Aufruf der Notify-Funktion beeinflussen".<br />
|-<br />
| <code>$hash->{NOTIFYDEV}</code> || Sofern das Modul Events via NotifyFn verarbeitet kann man damit die Definitionen, von denen man Events erhalten will begrenzen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Begrenzung der Aufrufe auf bestimmte Geräte".<br />
|-<br />
| <code>$hash->{IODev}</code> || Hier wird das zugeordnete IO-Gerät durch [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] gespeichert, welches für den Datentransport und -empfang dieses logischen Gerätes zuständig ist. Dieser Wert existiert nur bei Modulen die nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] arbeiten. <br />
|-<br />
| <code>$hash->{CHANGED}</code> || Hier werden alle Events kurzzeitig gesammelt, welche für die Eventverarbeitung anstehen. Insbesondere die [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] speichern hier alle Events zwischen um sie nach Abschluss via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] zu verarbeiten. <br />
|-<br />
| <code>$hash->{FD}</code> || Wenn die Definition eine Netzwerkverbindung oder serielle Schnittstelle geöffnet hat (z.B. via [[DevIo]]), so wird der entsprechende File-Deskriptor in diesem Internal gespeichert. Damit kann FHEM alle geöffneten Filedeskriptoren der entsprechenden Definition zuordnen um bei ankommenden Daten die Definition via [[DevelopmentModuleIntro#X_Read|Read-Funktion]] damit zu versorgen.<br />
|-<br />
| <code>$hash->{EXCEPT_FD}</code> || Ähnlich wie <code>$hash->{FD}</code>. Sofern die Definition in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> eingetragen ist und ein Fildeskriptor in diesem Internal gesetzt ist, wird bei einer auftretenden Exception bzw. Interrupt die [[DevelopmentModuleIntro#X_Except|Except]]-Funktion des entsprechenden Moduls aufgerufen um darauf zu reagieren.<br />
|}<br />
<br />
Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.<br />
<br />
== Readings ==<br />
Daten, welche von einem Gerät gelesen werden und in FHEM in einer für Menschen verständlichen Form zur Verfügung gestellt werden können, werden Readings genannt. Sie geben den Status des Gerätes wieder und erzeugen Events innerhalb von FHEM auf die andere Geräte reagieren können. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise <br />
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers<br />
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung<br />
<br />
Für den lesenden Zugriff auf Readings steht die Funktion <code>[[DevelopmentModuleAPI#ReadingsVal|ReadingsVal()]]</code> zur Verfügung. Ein direkter Zugriff auf die Datenstruktur sollte nicht vorgenommen werden.<br />
<br />
Readings werden im Statefile von FHEM automatisch auf der Festplatte zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen. Dadurch ist der letzte Status eines Gerätes vor einem Neustart nachvollziehbar.<br />
<br />
Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FHEMWEB nicht angezeigt und können somit als "Permanentspeicher" für kleinere Daten innerhalb des Moduls genutzt werden. Um größere Datenmengen permanent zu speichern sollte man jedoch die Funktion <code>[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]</code> verwenden.<br />
<br />
Zum Setzen von Readings sollen <br />
*bei Gruppen von Readings der Funktionsblock <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code> (mehrfach wiederholt), <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code><br />
*bei einzelnen Updates die Funktion <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> <br />
aufgerufen werden. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen, je nach Hardwareperformance, spürbare Last auf dem System (siehe [[DevelopmentModuleIntro#X_Notify|NotifyFn]]), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.<br />
<br />
Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:<br />
<br />
<syntaxhighlight lang="perl"><br />
readingsBeginUpdate($hash);<br />
readingsBulkUpdate($hash, $readingName1, $wert1 );<br />
readingsBulkUpdate($hash, $readingName2, $wert2 );<br />
readingsEndUpdate($hash, 1);<br />
</syntaxhighlight><br />
<br />
== Events ==<br />
<br />
FHEM verfügt über einen Event-Mechanismus um Änderungen verschiedenster Art an einzelne oder alle Definitionen mitzuteilen. Jedes Modul (und damit alle Definitionen dieses Moduls) können auf Events von FHEM selber (Definition <code>global</code>) oder von anderen Definitionen reagieren und dadurch selber aktiv werden. Ein Event wird innerhalb von FHEM als Zeichenkette behandelt.<br />
<br />
Events sind grundsätzlich immer definitionsbezogen. Das bedeutet, dass ein Event immer in Verbindung mit einem Definitionsnamen erzeugt wird. Jede Definition, welche ein Event verarbeitet, erhält den Definitions-Hash (<code>$hash</code>) der auslösenden Definition.<br />
<br />
Events werden typischerweise bei der Erstellung von Readings implizit für jedes einzelne Reading erzeugt. Es gibt jedoch auch Events die nichts mit Readings zu tun haben um anderweitige Änderungen bekannt zu geben.<br />
<br />
Eigene Events können in FHEM mit der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] erzeugt werden. Um auf Events in einem Modul reagieren zu können, muss eine [[#X_Notify|Notify]]-Funktion implementiert sein. Sobald ein oder mehrere Events für eine Definition getriggert werden, prüft FHEM, welche Definitionen über Events der auslösenden Definition informiert werden möchten. Diese werden dann nacheinander in einer bestimmten Reihenfolge durch Aufruf der [[#X_Notify|Notify]]-Funktion über anstehende Events in Kenntnis gesetzt. Es obliegt dann dem jeweiligen Modul, wie es auf die Events reagiert.<br />
<br />
=== globale Events ===<br />
<br />
Als "globale Events" werden alle Events bezeichnet, die durch die Definition <code>global</code> erzeugt werden. Es handelt sich hierbei um Events die Strukturänderungen in der Konfiguration, als auch systemweite Ereignisse zu FHEM selbst signalisieren.<br />
<br />
Hier eine kurze Zusammenfassung, welche Events durch <code>global</code> getriggert werden können:<br />
<br />
<u>Allgemeine Events:</u><br />
<br />
{| class="wikitable"<br />
|-<br />
! Event-Text !! Beschreibung.<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>INITIALIZED</code>''' || Der Start von FHEM ist abgeschlossen. Sämtliche Definitionen und Attribute wurden aus der Konfiguration (fhem.cfg oder configDB) eingelesen, sowie sämtliche Readings sind aus dem State-File eingelesen und stehen nun voll umfänglich zur Verfügung.<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>REREADCFG</code>''' || Die Konfiguration wurde erneut eingelesen. Dies bedeutet, es wurden alle Definitionen/Attribute/Readings aus FHEM entfernt und durch Einlesen der Konfiguration neu angelegt. (FHEM-Befehl: "rereadcfg")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>SAVE</code>''' || Die laufende Konfiguration soll gespeichert werden (in fhem.cfg oder configDB). Dieses Event wird '''VOR''' dem Speichern der Konfiguration getriggert. Sobald der Trigger verarbeitet wurde, beginnt das Speichern der Konfiguration. (FHEM-Befehl: "save")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>SHUTDOWN</code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>UPDATE</code>''' || Es wurde ein Update erfolgreich installiert. (FHEM-Befehl: "update")<br />
|}<br />
<br />
<u>Definitionsbezogene Events:</u><br />
<br />
{| class="wikitable"<br />
|-<br />
! Event-Text !! Beschreibung.<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>DEFINED ''<Name>''</code>''' || Es wurde eine neue Definition mit Namen <code>''<Name>''</code> angelegt. (FHEM-Befehl: "define")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>DELETED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde gelöscht. (FHEM-Befehl: "delete")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>RENAMED ''<Alt>'' ''<Neu>''</code>''' || Die Definition mit dem Namen <code>''<Alt>''</code> wurde in den Namen <code>''<Neu>''</code> umbenannt. (FHEM-Befehl: "rename")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>MODIFIED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde modifiziert. (FHEM-Befehl: "modify")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>UNDEFINED ''<Name> <Modul> <Define-Parameter>''</code>''' || Es wurde eine Nachricht von einem physikalischen Modul (siehe [[#Zweistufiges Modell für Module|zweistufiges Modulkonzept]]) erhalten, für die keine passende logische Definition in FHEM existiert. Details dazu, siehe dazu Abschnitt [[#Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)|Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)]].<br />
|}<br />
<br />
=== Begrenzung von Events ===<br />
<br />
Ein Modul, welches Events verarbeitet, kann die Eventverarbeitung auf bestimmte Definitionen begrenzen. Dadurch werden nur Events an das Modul gemeldet (via [[#X_Notify|X_Notify()]]), welche von einer oder mehreren bestimmten Definitionen getriggert wurden. Dadurch werden unnötige Events nicht an das Modul gemeldet und schont somit Ressourcen.<br />
<br />
Standardmäßig werden sämtliche Events ohne Begrenzung an ein Modul gemeldet, welches eine [[#X_Notify|Notify]]-Funktion implementiert hat und somit Events verarbeiten kann. Details zur Begrenzung von Events findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].<br />
<br />
=== Reihenfolge der Eventverarbeitung ===<br />
<br />
Ein getriggertes Event wird nacheinander gegen jede Definition geprüft, deren Modul eine [[#X_Notify|Notify]]-Funktion implementiert hat. Dies bedeutet, jede Definition wird nacheinander durch Aufruf der [[#X_Notify|Notify]]-Funktion mit dem Definitionshash der auslösenden Definition aufgerufen.<br />
<br />
Unter bestimmten Umständen kann es erforderlich sein, in diese Reihenfolge einzugreifen. Beispielsweise wenn das eigene Modul und deren Definitionen das Event als letztes oder erstes verarbeiten müssen. Ein Beispiel bietet hierbei das Modul [[dewpoint]], welches Events vor allen anderen Modulen verarbeiten muss.<br />
<br />
Details, wie man die Reihenfolge der Eventverarbeitung steuern kann, findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].<br />
<br />
== Attribute ==<br />
Damit der Nutzer das Verhalten einer einzelnen Gerätedefinition zur Laufzeit individuell anpassen kann, gibt es in FHEM für jede Definition sogenannte Attribute, welche mit dem Befehl <code>attr</code> gesetzt werden können.<br />
Diese stehen dann dem Modul unmittelbar zur Verfügung um das Verhalten während der Ausführung zu beeinflussen. Attribute werden zusammen mit dem <code>define</code>-Befehl der jeweiligen Definition beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben. Beim Neustart werden die entsprechenden Befehle ausgeführt um alle Definition inkl. Attribute wieder anzulegen. Zur Laufzeit werden Attribute in dem globalen Hash <code>%attr</code> mit dem Definitionsnamen als Index (<code>$attr{$name} = $value</code>) gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert. Generell sollte <code>%attr</code> nicht durch direkten Zugriff manipuliert/benutzt werden.<br />
<br />
Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.<br />
<br />
Welche Attribute ein Modul unterstützt muss in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen von <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten).<br />
<br />
Wenn beim Setzen von Attributen in einer Gerätedefinition entsprechende Werte geprüft werden sollen oder zusätzliche Funktionalitäten implementiert werden müssen, dann muss dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> (siehe unten) implementiert werden. Hier kann man bspw. einen Syntaxcheck für Attribut-Werte implementieren um ungültige Werte zurückzuweisen.<br />
<br />
== Modulfunktionen ==<br />
<br />
Damit fhem.pl ein Modul nutzen kann, muss dieses entsprechende Funktionen mit einer vorgegebenen Aufrufsyntax implementieren. Durch die Bekanntgabe dieser modulspezifischen Funktionen können Daten zwischen fhem.pl und einem Modul entsprechend ausgetauscht werden. Es gibt verschiedene Arten von Funktionen die ein Modul anbieten muss bzw. kann, je nach Funktionsumfang.<br />
<br />
=== Die wichtigsten Funktionen in einem Modul ===<br />
<br />
Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:<br />
<br />
{| class="wikitable"<br />
|-<br />
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung<br />
|-<br />
| [[#X_Initialize|X_Initialize]] || Initialisiert das Modul und gibt den Namen zusätzlicher Modulfunktionen bekannt, sowie modulspezifische Einstellungen. Wird direkt nach dem erfolgreichen Laden des Moduls durch fhem.pl aufgerufen.<br />
|}<br />
<br />
Die folgenden Funktionen sind die wichtigsten Funktionen, welche je nach Anwendungsfall zu implementieren sind. Es handelt sich hierbei um die wichtigsten Vertreter, welche in den meisten Modulen Verwendung finden. Nicht alle Funktionen machen jedoch in jedem Modul Sinn. Generell sollte auch hier bei jeder Funktion der Modulname vorangestellt werden um ein einheitliches Namensschema zu gewährleisten. Hier die wichtigsten Modulfunktionen:<br />
<br />
{| class="wikitable sortable"<br />
|-<br />
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable"| Kurzbeschreibung<br />
|-<br />
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.<br />
|-<br />
| [[#X_Undef|X_Undef]] || Wird im Rahmen des <code>delete</code>-Befehls, sowie <code>rereadcfg</code>-Befehl aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.<br />
|-<br />
| [[#X_Delete|X_Delete]] || Wird im Rahmen des beim <code>delete</code>-Befehls aufgerufen wenn das Gerät endgültig gelöscht wird um weiterführende Aktionen vor dem Löschen durchzuführen.<br />
|-<br />
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen<br />
|-<br />
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.<br />
|-<br />
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)<br />
|-<br />
| [[#X_Read|X_Read]] || Wird durch FHEM aufgerufen, wenn ein gelisteter Filedeskriptor in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> Daten zum Lesen bereitstellt.<br />
|-<br />
| [[#X_Ready|X_Ready]] || Wird unter Windows durch FHEM aufgerufen um zyklisch einen seriellen Filedeskriptor auf lesbare Daten zu prüfen. Unter Linux dient diese Funktion dem Wiederaufbau verlorener Verbindungen.<br />
|-<br />
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM<br />
|-<br />
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.<br />
|-<br />
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.<br />
|}<br />
<br />
Diese Funktionen werden in diesem Abschnitt genauer beschrieben.<br />
<br />
==== X_Initialize ====<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von fhem.pl nach dem Laden des Moduls aufgerufen und bekommt eine leere Hashreferenz für den Initialisierungsvorgang übergeben. <br />
<br />
Dieser Hash muss nun von X_Initialize mit allen modulrelevanten Funktionsnamen gefüllt werden. Anschließend wird dieser Hash durch fhem.pl im globalen Hash <code>%modules</code> gespeichert. <code>$modules{ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der für jedes Modul existiert und modulspezifische Daten wie bspw. die implementierten Modulfunktionen enthält. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls wie folgt:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{DefFn} = "X_Define";<br />
$hash->{UndefFn} = "X_Undef";<br />
$hash->{DeleteFn} = "X_Delete";<br />
$hash->{SetFn} = "X_Set";<br />
$hash->{GetFn} = "X_Get";<br />
$hash->{AttrFn} = "X_Attr";<br />
$hash->{ReadFn} = "X_Read";<br />
$hash->{ReadyFn} = "X_Ready";<br />
$hash->{NotifyFn} = "X_Notify";<br />
$hash->{RenameFn} = "X_Rename";<br />
$hash->{ShutdownFn} = "X_Shutdown";<br />
</syntaxhighlight><br />
<br />
Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub &lt;''Funktionsname''&gt;() { ... }</code> definiert ist, als Zeichenkette in <code>$hash</code> gesetzt werden. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden.<br />
Auf diese Weise können sämtliche modulspezifisch implementierten Funktionen wie <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> bzw. <code>$hash->{ParseFn}</code> usw. bekannt gemacht werden.<br />
<br />
Darüber hinaus sollten die vom Modul unterstützten Attribute definiert werden:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{AttrList} =<br />
"do_not_notify:1,0 " . <br />
"header " .<br />
$readingFnAttributes; <br />
</syntaxhighlight><br />
<br />
Die Auflistung aller unterstützten modulspezifischen Attribute erfolgt in Form einer durch Leerzeichen getrennten Liste in <code>$hash->{AttrList}}</code>. Es gibt in FHEM globale Attribute, die in allen Gerätedefinitionen verfügbar sind und nur modulspezifische Attribute die jedes Modul via <code>$hash->{AttrList}</code> über die eigene Initialize-Funktion setzt. In fhem.pl werden dann die entsprechenden Attributwerte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die [[#X_Attr|Attr]]-Funktion implementiert und in der Initialize-Funktion bekannt gemacht werden.<br />
<br />
Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann zusätzlich gemacht werden, wenn das Modul zum Setzen von Readings die Funktionen <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code> oder <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref zu {{Link2CmdRef|Anker=readingFnAttributes|Label=readingFnAttributes}}.<br />
<br />
<br />
<u>Nutzung von parseParams()</u><br />
<br />
Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modulautoren beim Parsen von Übergabeparametern, welche bei <code>define</code>, <code>get</code> und <code>set</code> Kommandos an die entsprechenden Modulfunktionen übergeben werden. Dadurch lassen sich auf einfache Weise insbesondere komplexe Parameter (wie bspw. Perl-Ausdrücke) sehr einfach parsen.<br />
<br />
Diese Zusatzfunktion kann man in der Initialize-Funktion einfach über folgenden Parameter für [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion modulweit aktivieren:<br />
<syntaxhighlight lang="perl">$hash->{parseParams} = 1;</syntaxhighlight><br />
Sobald es gesetzt ist wird automatisch durch fhem.pl <code>[[DevelopmentModuleAPI#parseParams|parseParams()]]</code> aufgerufen und die an die [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion übergebenen Parameter ändern sich wie weiter unten in den jeweiligen Funktionen beschrieben.<br />
<br />
==== X_Define ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ( $hash, $def ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Define-Funktion eines Moduls wird von FHEM aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Funktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.) oder einen [[#Pollen_von_Geräten|Status-Timer]] zu starten.<br />
Sie beginnt typischerweise mit:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ( $hash, $def ) = @_;<br />
my @a = split( "[ \t][ \t]*", $def );<br />
...<br />
</syntaxhighlight><br />
<br />
Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den die im <code>define</code>-Befehl übergebenen Parameter. Welche bzw. wie viele Parameter <br />
akzeptiert werden und welcher Syntax diese entsprechen müssen ist Sache dieser Funktion. Im obigen Beispiel wird die Argumentzeile <code>$def</code> in ein Array aufgeteilt (durch Leerzeichen/Tabulator getrennt) und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:<br />
<br />
<syntaxhighlight lang="perl"><br />
my $name = $a[0];<br />
my $module = $a[1];<br />
my $url = $a[2];<br />
my $inter = 300;<br />
<br />
if(int(@a) == 4) { <br />
$inter = $a[3]; <br />
if ($inter < 5) {<br />
return "interval too small, please use something > 5s, default is 300 seconds";<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerweise als Internals im Hash der Geräteinstanz gespeichert:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{url} = $url;<br />
$hash->{Interval} = $inter;<br />
</syntaxhighlight><br />
<br />
Sobald alle Parameter korrekt verarbeitet wurden, wird in der Regel die erste Verbindung zum Gerät aufgebaut. Je nach Art des Geräts kann das eine permanente Datenverbindung sein (z.B. serielle Schnittstelle oder TCP-Verbindung) oder das Starten eines regelmäßigen Timers, der zyklisch den Status z.B. via [[HttpUtils|HTTP]] ausliest.<br />
<br />
Sollten im Rahmen der Define-Funktion Syntax-Probleme der Übergabeparameter festgestellt werden oder es kann bspw. keine Verbindung aufgebaut werden, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn alle Übergabeparameter akzeptiert werden, darf <code>undef</code> zurückgegeben werden. Sobald eine Define-Funktion eine Fehlermeldung zurückmeldet, wird der define-Befehl durch FHEM zurückgewiesen und der User erhält die Fehlermeldung, welche die Define-Funktion produziert hat, als Ausgabe zurück.<br />
<br />
<br />
<u>Verfügbarkeit von Attributen</u><br />
<br />
Während die Define-Funktion ausgeführt wird, sollte man nicht davon ausgehen, dass alle vom Nutzer konfigurierten Attribute via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verfügbar sind. Attribute stehen in der Define-Funktion nur dann zur Verfügung, wenn FHEM sich nicht in der Initialisierungsphase befindet (globale Variable <code>$init_done</code> ist wahr; der Nutzer hat die Gerätedefinition modifiziert). Daher sollte man weiterführende Funktion, welche auf gesetzte Attribute angewiesen sind, nur dann in der Define-Funktion starten, wenn <code>$init_done</code> zutrifft.<br />
<br />
Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ( $hash, $def ) = @_;<br />
<br />
...<br />
<br />
$hash->{NOTIFYDEV} = "global";<br />
<br />
X_FunctionWhoNeedsAttr($hash) if($init_done);<br />
}<br />
<br />
sub X_Notify($$)<br />
{<br />
my ($own_hash, $dev_hash) = @_;<br />
my $ownName = $own_hash->{NAME}; # own name / hash<br />
<br />
return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled<br />
<br />
my $devName = $dev_hash->{NAME}; # Device that created the events<br />
my $events = deviceEvents($dev_hash, 1);<br />
<br />
if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))<br />
{<br />
X_FunctionWhoNeedsAttr($hash);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.<br />
<br />
<br />
<u>Nutzung von parseParams()</u><br />
<br />
Zum Aufteilen und Parsen von <code>$def</code> lässt sich die Funktion [[DevelopmentModuleAPI#parseParams|parseParams()]] verwenden um die einzelnen Argumente einfach zu parsen. Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird parseParams() automatisch aufgerufen und X_Define() ändert sich wie folgt:<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$$)<br />
{<br />
my ( $hash, $a, $h ) = @_;<br />
...<br />
</syntaxhighlight><br />
<br />
Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.<br />
<br />
==== X_Undef ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Undef ($$)<br />
{<br />
my ( $hash, $name ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
Die Undef-Funktion wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird oder bei der Abarbeitung des Befehls <code>rereadcfg</code>, der ebenfalls alle Geräte löscht und danach das Konfigurationsfile neu einliest. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das Entfernen von internen Timern, sofern diese im Modul zum Pollen verwendet wurden (siehe Abschnitt [[#Pollen_von_Geräten|Pollen von Geräten]]). <br />
<br />
Zugewiesene Variablen im Hash der Geräteinstanz, Internals oder Readings müssen hier nicht gelöscht werden. In fhem.pl werden die entsprechenden Strukturen beim Löschen der Geräteinstanz ohnehin vollständig gelöscht.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Undef($$) <br />
{ <br />
my ( $hash, $name) = @_; <br />
DevIo_CloseDev($hash); <br />
RemoveInternalTimer($hash); <br />
return undef; <br />
}<br />
</syntaxhighlight><br />
<br />
Sollten im Rahmen der Undef-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn die Undef-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht bzw. neu angelegt. Sollte die Undef-Funktion jedoch eine Fehlermeldung zurückgeben, wird der entsprechende Vorgang (<code>delete</code> bzw. <code>rereadcfg</code>) für dieses Gerät abgebrochen. Es bleibt dann unverändert in FHEM bestehen.<br />
<br />
==== X_Delete ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Delete ($$)<br />
{<br />
my ( $hash, $name ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Delete-Funktion ist das Gegenstück zur Funktion [[#X_Define|X_Define]] und wird aufgerufen wenn ein Gerät mit dem Befehl <code>delete</code> gelöscht wird. <br />
<br />
Wenn ein Gerät in FHEM gelöscht wird, wird zuerst die Funktion [[#X_Undef|X_Undef]] aufgerufen um offene Verbindungen zu schließen, anschließend wird die Funktion X_Delete aufgerufen. Diese dient eher zum Aufräumen von dauerhaften Daten, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch dauerhafte Daten bspw. im physikalischen Gerät zu löschen die mit dieser Gerätedefinition zu tun haben.<br />
<br />
Dies kann z.B. folgendes sein:<br />
<br />
* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.<br />
* Lösen von evtl. Pairings mit dem physikalischen Gerät <br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Delete($$) <br />
{ <br />
my ( $hash, $name ) = @_; <br />
<br />
# Löschen von Geräte-assoziiertem Temp-File<br />
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)<br />
<br />
return undef;<br />
} <br />
</syntaxhighlight><br />
<br />
Sollten im Rahmen der Delete-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur die Delete-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht. Sollte die Delete-Funktion eine Fehlermeldung zurückgeben, wird der Löschvorgang abgebrochen und das Gerät bleibt weiter in FHEM bestehen.<br />
<br />
==== X_Get ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Get ($$@)<br />
{<br />
my ( $hash, $name, $opt, @args ) = @_;<br />
<br />
...<br />
<br />
return $result;<br />
}<br />
</syntaxhighlight><br />
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. In vielen Modulen wird auf diese Weise auch der Zugriff auf generierte Readings ermöglicht. Der Get-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des get-Befehls übergeben. Als Rückgabewert wird das Ergebnis des entsprechenden Befehls in Form einer Zeichenkette zurückgegeben. Der Rückgabewert <code>undef</code> hat hierbei keine besondere Bedeutung und wird behandelt wie eine leere Zeichenkette <code>""</code>.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Get($$@)<br />
{<br />
my ( $hash, $name, $opt, @args ) = @_;<br />
<br />
return "\"get $name\" needs at least one argument" unless(defined($opt));<br />
<br />
if($opt eq "status") <br />
{<br />
...<br />
}<br />
elsif($opt eq "power")<br />
{<br />
...<br />
}<br />
...<br />
else<br />
{<br />
return "Unknown argument $opt, choose one of status power [...]";<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax einhalten um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:<br />
<br />
<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code><br />
<br />
Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Get-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen. <br />
<br />
Beispiel:<br />
<ul><br />
<syntaxhighlight lang="perl">return "unknown argument $opt choose one of status temperature humidity";</syntaxhighlight><br />
<br />
Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:<br />
<br />
* <code>status</code><br />
* <code>temperature</code><br />
* <code>humidity</code><br />
<br />
Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:<br />
<br />
* <code>get ''&lt;NAME&gt;'' status</code><br />
* <code>get ''&lt;NAME&gt;'' temperature</code><br />
* <code>get ''&lt;NAME&gt;'' humidity</code><br />
</ul><br />
<br />
Die Ausgabe einer solchen Meldung ist sehr wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>get</code>-Optionen zu ermitteln und als Auswahl anzubieten. Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert direkt abfragen und diesen als Return-Wert der Get-Funktion zurückgeben.<br />
<br />
<br />
<u>Nutzung von parseParams()</u><br />
<br />
Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Get() ändert sich wie folgt:<br />
<syntaxhighlight lang="perl"><br />
sub X_Get($$$)<br />
{<br />
my ( $hash, $a, $h ) = @_;<br />
...<br />
</syntaxhighlight><br />
<br />
Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.<br />
<br />
==== X_Set ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Set ($$@)<br />
{<br />
my ( $hash, $name, $cmd, @args ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
return ($error, $skip_trigger);<br />
}<br />
</syntaxhighlight><br />
<br />
Die Set-Funktion ist das Gegenteil zur [[#X_Get|Get]]-Funktion. Sie ist dafür gedacht, Daten zum physischen Gerät zu schicken, bzw. entsprechende Aktionen im Gerät selber auszulösen. Ein Set-Befehl dient daher der direkten Steuerung des physikalischen Gerätes in dem es bspw. Zustände verändert (wie <code>on</code>/<code>off</code>). Der Set-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des set-Befehls übergeben. Als Rückgabewert kann eine Fehlermeldung in Form Zeichenkette zurückgegeben werden. Der Rückgabewert <code>undef</code> bedeutet hierbei, dass der Set-Befehl erfolgreich durchgeführt wurde. Eine Set-Funktion gibt daher nur im Fehlerfall eine Rückmeldung mit einer entsprechenden Fehlermeldung. Der Wert <code>undef</code> wird als "erfolgreich" interpretiert. <br />
<br />
Standardmäßig wird jeder Set-Befehl, welcher erfolgreich ausgeführt wurde (<code>$error</code> ist <code>undef</code>), als Event getriggert um dies bspw. in einem FileLog festzuhalten. Dieses Verhalten kann optional unterbunden werden indem der zweite Rückgabewert <code>$skip_trigger</code> auf <code>1</code> gesetzt wird. Damit wird das Generieren eines Events für das erfolgreich ausgeführte Set-Kommando unterbunden. Falls nicht gesetzt, wird ein Event erzeugt (<code>$cmd</code> mit sämtlichen <code>@args</code>).<br />
<br />
Rückmeldungen (Fehler) von set-Befehlen sämtlicher Module, die im Rahmen eines ausgeführten [[Notify]] auftreten werden im FHEM Logfile festgehalten.<br />
<br />
Falls nur interne Daten, die ausschließlich für das Modul relevant sind, gesetzt werden müssen, so sollte statt Set die [[#X_Attr|Attr]]-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht, da sie nur zur Steuerungszwecken im laufenden Betrieb von FHEM dienen.<br />
<br />
Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter übergeben um Zustände zu setzen. <br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Set($@)<br />
{<br />
my ( $hash, $name, $cmd, @args ) = @_;<br />
<br />
return "\"set $name\" needs at least one argument" unless(defined($cmd));<br />
<br />
if($cmd eq "status")<br />
{<br />
if($args[0] eq "up")<br />
{<br />
...<br />
}<br />
elsif($args[0] eq "down")<br />
{<br />
...<br />
}<br />
else<br />
{<br />
return "Unknown value $args[0] for $cmd, choose one of status power";<br />
} <br />
}<br />
elsif($cmd eq "power")<br />
{<br />
if($args[0] eq "on")<br />
{<br />
...<br />
}<br />
elsif($args[0] eq "off")<br />
{<br />
...<br />
} <br />
else<br />
{<br />
return "Unknown value $args[0] for $cmd, choose one of status power";<br />
} <br />
}<br />
...<br />
else<br />
{<br />
return "Unknown argument $cmd, choose one of status power";<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Wenn eine unbekannte Option an die Set-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Set-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:<br />
<br />
<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code><br />
<br />
Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Set-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen. <br />
<br />
Beispiel:<br />
<ul><br />
<syntaxhighlight lang="perl">return "unknown argument $cmd choose one of status power";</syntaxhighlight><br />
<br />
Hier werden als mögliche Optionen für einen Set-Befehl folgende Parameter angegeben:<br />
<br />
* <code>status</code><br />
* <code>power</code><br />
<br />
Dies würde in folgenden, mögliche Set-Befehle für einen User resultieren:<br />
<br />
* <code>set ''&lt;NAME&gt;'' status</code><br />
* <code>set ''&lt;NAME&gt;'' power</code><br />
</ul><br />
<br />
Die Ausgabe einer solchen Meldung ist sehr wichtig, da sie im Modul [[FHEMWEB]] verwendet wird um die möglichen <code>set</code>-Optionen zu ermitteln und als Auswahl anzubieten.<br />
<br />
<br />
<u>Nutzung von SetExtensions.pm</u><br />
<br />
Wenn man dem Nutzer zusätzlich zu den Set-Befehlen <code>on</code> und <code>off</code> auch weiterführende Befehle wie <code>on-for-timer</code>, <code>on-till</code>, usw. anbieten möchte, obwohl die zu steuernde Hardware solche Kommandos nicht unterstützt, kann man dies über das Hilfsmodul SetExtensions.pm realisieren.<br />
<br />
Das Hilfsmodul SetExtensions.pm bietet weiterführende Set-Kommandos basierend auf den Befehlen <code>on</code>/<code>off</code> an. Dabei werden durch interne Timer bzw. eigens angelegten [[at]]-Definitionen diese Befehle durch FHEM selber umgesetzt. Je nach ausgeführtem Befehl wird der <code>on</code>- bzw. <code>off</code>-Befehl dann durch FHEM zum richtigen Zeitpunkt ausgeführt. Vorausgesetzt das Modul unterstützt in der Set-Funktion die Befehle <code>on</code> und <code>off</code>, so werden durch den Einsatz von SetExtensions.pm folgende Befehle zusätzlich unterstützt:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Set-Kommando !! Beispiel !! Beschreibung<br />
|-<br />
| style="white-space: nowrap;" | <code>on-for-timer ''&lt;Dauer&gt;''</code> || style="white-space: nowrap;" | <code>on-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und nach der angegebenen Dauer in Sekunden via <code>off</code> wieder aus.<br />
|-<br />
| style="white-space: nowrap;" | <code>off-for-timer ''&lt;Dauer&gt;''</code> || style="white-space: nowrap;" | <code>off-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und nach der angegebenen Dauer in Sekunden via <code>on</code> wieder ein.<br />
|-<br />
| style="white-space: nowrap;" | <code>on-till ''&lt;Zeitpunkt&gt;''</code> || style="white-space: nowrap;" | <code>on-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und zum angegebenen Zeitpunkt via <code>off</code> wieder aus.<br />
|-<br />
| style="white-space: nowrap;" | <code>off-till ''&lt;Zeitpunkt&gt;''</code> || style="white-space: nowrap;" | <code>off-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und zum angegebenen Zeitpunkt via <code>on</code> wieder ein.<br />
|-<br />
| style="white-space: nowrap;" | <code>on-till-overnight ''&lt;Zeitpunkt&gt;''</code> || style="white-space: nowrap;" | <code>on-till-overnight 01:00</code> || Ähnlich wie <code>on-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.<br />
|-<br />
| style="white-space: nowrap;" | <code>off-till-overnight ''&lt;Zeitpunkt&gt;''</code> || style="white-space: nowrap;" | <code>off-till-overnight 01:00</code> || Ähnlich wie <code>off-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.<br />
|-<br />
| style="white-space: nowrap;" | <code>blink ''&lt;Anzahl&gt; &lt;Interval&gt;''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''&lt;Interval&gt;''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''&lt;Interval&gt;''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.<br />
|-<br />
| style="white-space: nowrap;" | <code>intervals ''&lt;Start&gt;-&lt;Ende&gt;'' ''&lt;Start&gt;-&lt;Ende&gt;'' ...</code> || style="white-space: nowrap;" | <code>intervals 07:00-08:00 16:30-18:00</code> || Schaltet das Gerät innerhalb der übergebenen Zeiträumen via <code>on</code> ein. Sobald die aktuelle Zeit ausserhalb dieser Zeiträume liegt, wird das Gerät via <code>off</code> wieder ausgeschaltet. Es können dabei beliebig viele Zeiträume angegeben werden.<br />
|-<br />
| style="white-space: nowrap;" | <code>toggle</code> || style="white-space: nowrap;" | <code>toggle</code> || Sofern der aktuelle Status <code>on</code> ist, wird das Gerät via <code>off</code> ausgeschaltet. Andernfalls wird es via <code>on</code> eingeschaltet.<br />
|}<br />
<br />
Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der commandref zum {{Link2CmdRef|Anker=set|Label=set-Befehl}}.<br />
<br />
Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:<br />
<br />
# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls<br />
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
use SetExtensions;<br />
<br />
...<br />
<br />
sub X_Set($@)<br />
{<br />
my ( $hash, $name, $cmd, @args ) = @_;<br />
my $cmdList = "on off";<br />
<br />
return "\"set $name\" needs at least one argument" unless(defined($cmd));<br />
<br />
if($cmd eq "on")<br />
{<br />
# Gerät einschalten...<br />
}<br />
elsif($cmd eq "off")<br />
{<br />
# Gerät ausschalten...<br />
}<br />
...<br />
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()<br />
{<br />
return SetExtensions($hash, $cmdList, $name, $cmd, @args);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''&lt;Name&gt;'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.<br />
<br />
Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].<br />
<br />
<br />
<br />
<u>Nutzung von parseParams()</u><br />
<br />
Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Set() ändert sich wie folgt:<br />
<syntaxhighlight lang="perl"><br />
sub X_Set($$$)<br />
{<br />
my ( $hash, $a, $h ) = @_;<br />
...<br />
</syntaxhighlight><br />
<br />
Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.<br />
<br />
<br />
<u>Nutzung von FHEMWEB-Widgets</u><br />
<br />
Das GUI-Modul [[FHEMWEB]] kann für die einzelnen Set-Optionen, die das Modul versteht, automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht der GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknown ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt entsprechende Zusatzinformationen anhängen.<br />
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück. Das Modul FHEMWEB ermittelt die Syntax eines Gerätes jedoch immer mit dem Befehl:<br />
set ''&lt;NAME&gt;'' ?<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
return "Unknown argument $cmd, choose one of status:up,down power:on,off on:noArg off:noArg";<br />
</syntaxhighlight><br />
<br />
Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann<br />
<pre>timer:30,120,300<br />
mode:verbose,ultra,relaxed</pre><br />
<br />
Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.<br />
<br />
Man kann jedoch die Eingabe-/Auswahlmöglichkeiten durch Widgets vereinfachen. Dazu gibt man hinter dem Doppelpunkt einen Widgetnamen und widgetspezifische Parameter an. Es existieren mehrere solcher Widgets in FHEMWEB. Die gebräuchlichsten sind:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Zusatz !! Beispiel !! Beschreibung<br />
|-<br />
| '''noArg''' || <code>reset:noArg</code>|| Es werden keine weiteren Argumente mehr benötigt. In so einem Fall wird bei der Auswahl keine Textbox oder ähnliches angezeigt, da keine weiteren Argumente für diesen Befehl notwendig sind.<br />
|-<br />
| '''slider''',<min>,<step>,<max> || <code>dim:slider,0,1,100</code>|| Es wird ein Schieberegler angezeigt um den Parameter auszuwählen. Dabei werden als Zusatzparameter Minimum, Schrittweite und Maximum angegeben.<br />
|-<br />
| '''colorpicker''' || <code>rgb:colorpicker,RGB</code>|| Es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Die genaue Parametersyntax kann man dem Artikel zum [[Color#Colorpicker|Colorpicker]] entnehmen.<br />
|-<br />
| '''multiple''' || <code>group:multiple,Telefon,Multimedia,Licht,Heizung</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte durch klicken auswählen kann. Optional kann man in einem Freitext eigene Werte ergänzen. dieser Dialog wird bspw. bei der Raum-Auswahl (Attribut "room") oder der Gruppen-Auswahl (Attribut "group") in FHEMWEB genutzt. <br />
|-<br />
| '''sortable''' || <code>command:sortable,monday,tuesday,...</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte auswählen und sortieren kann. Man kann dabei Werte durch Klicken auswählen und durch Drag'n'Drop sortieren.<br />
|}<br />
<br />
Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der {{Link2CmdRef|Anker=widgetOverride}} unter widgetOverride zu FHEMWEB.<br />
<br />
'''Hinweise'''<br />
<br />
* Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet. <br />
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.<br />
<br />
==== X_Attr ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Attr ($$$$)<br />
{<br />
my ( $cmd, $name, $attrName, $attrValue ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Attr-Funktion dient der Prüfung von Attributen, welche über den <code>attr</code>-Befehl gesetzt werden können. Sobald versucht wird, ein Attribut für ein Gerät zu setzen, wird vorher die Attr-Funktion des entsprechenden Moduls aufgerufen um zu prüfen, ob das Attribut aus Sicht des Moduls korrekt ist.<br />
Liegt ein Problem mit dem Attribut bzw. dem Wert vor, so muss die Funktion eine aussagekräftige Fehlermeldung zurückgeben, welche dem User angezeigt wird.<br />
Sofern das übergebene Attribut samt Inhalt korrekt ist, gibt die Attr-Funktion den Wert <code>undef</code> zurück. Erst dann wird das Attribut in der globalen Datenstruktur <code>%attr</code> gespeichert und ist somit erst aktiv.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
X_Attr(@)<br />
{<br />
my ( $cmd, $name, $attrName, $attrValue ) = @_;<br />
<br />
# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen<br />
# $name - Gerätename<br />
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert<br />
<br />
if ($cmd eq "set") {<br />
if ($aName eq "Regex") {<br />
eval { qr/$aVal/ };<br />
if ($@) {<br />
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";<br />
return "Invalid Regex $aVal: $@";<br />
}<br />
}<br />
}<br />
return undef;<br />
}<br />
</syntaxhighlight><br />
<br />
Zusätzlich ist es möglich auch übergebene Attributwerte zu verändern bzw. zu korrigieren, indem man im Parameterarray <code>@_</code> den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 (entspricht dem 4. Element) im Parameterarray, also <code>$_[3]</code>.<br />
<br />
Da das Attribut zum Zeitpunkt des Aufrufs der Attr-Funktion noch nicht gespeichert ist, wird der neue Wert zu diesem Zeitpunkt noch nicht via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] zurückgegeben. Erst, wenn die Attr-Funktion mit <code>undef</code> beendet ist, wird der neue Wert in FHEM gespeichert und steht dann via AttrVal() zur Verfügung.<br />
<br />
Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie normalerweise keine Werte dort speichern muss, sondern lediglich das Attribut auf Korrektheit prüfen muss.<br />
Im obigen Beispiel wird für ein Attribut mit Namen "Regex" geprüft ob der reguläre Ausdruck fehlerhaft ist. Sofern dieser OK ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs in <code>%attr</code>.<br />
<br />
<br />
<u>Attributnamen mit Platzhaltern</u><br />
<br />
Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:<br />
<syntaxhighlight lang="perl"><br />
$hash->{AttrList} =<br />
"reading[0-9]*Name " .<br />
# usw.<br />
</syntaxhighlight><br />
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken in der Web-Oberfläche, da FHEMWEB nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muss solche Attribute manuell über den <code>attr</code>-Befehl eingeben.<br />
<br />
Man kann jedoch in der Attr-Funktion neu gesetzte Ausprägungen von Wildcard-Attributen an die gerätespezifische userattr-Variable anfügen. Dann können bereits gesetzte Attribute in FHEMWEB durch Klicken ausgewählt und geändert werden.<br />
Dazu reicht ein Aufruf der Funktion [[DevelopmentModuleAPI#addToDevAttrList|addToDevAttrList()]]: <br />
<br />
<syntaxhighlight lang="perl"><br />
addToDevAttrList($name, $aName);<br />
</syntaxhighlight><br />
<br />
==== X_Read ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Read ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
Die X_Read-Funktion wird aufgerufen, wenn ein dem Gerät zugeordneter Filedeskriptor (serielle Schnittstelle, TCP-Verbindung, ...) Daten zum Lesen bereitgestellt hat. Die Daten müssen nun eingelesen und interpretiert werden.<br />
<br />
Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Serial-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion [[DevIo#DevIo_SimpleRead()|DevIo_SimpleRead()]] gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.<br />
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten in einem eigenen Puffer (idealerweise in <code>$hash</code>) zwischenspeichern (siehe auch [[DevIo#Hinweis bei der Datenverarbeitung (Buffering)|DevIo]]). Im Beispiel ist dies <code>$hash->{helper}{BUFFER}</code> an den die aktuell gelesenen Daten angehängt werden, bis die folgende Prüfung ein für das jeweilige Protokoll vollständige Frame erkennt.<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# einlesen der bereitstehenden Daten<br />
my $buf = DevIo_SimpleRead($hash); <br />
return "" if ( !defined($buf) );<br />
Log3 $name, 5, "X ($name) - received data: ".$buf; <br />
<br />
# Daten in Hex konvertieren und an den Puffer anhängen<br />
$hash->{helper}{BUFFER} .= unpack ('H*', $buf); <br />
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};<br />
<br />
# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.<br />
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {<br />
...<br />
</syntaxhighlight><br />
<br />
Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{helper}{BUFFER}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und via [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] in Readings gespeichert werden (siehe unten).<br />
<br />
Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.<br />
<br />
==== X_Ready ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Ready ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
...<br />
<br />
return $success;<br />
}<br />
</syntaxhighlight><br />
<br />
Wird im Main-Loop aufgerufen falls das Modul in der globalen Liste <code>%readyfnlist</code> existiert. Diese Funktion hat, je nachdem auf welchem OS FHEM ausgeführt wird, unterschiedliche Aufgaben:<br />
<br />
* '''UNIX-artiges Betriebssystem:''' prüfen, ob eine Verbindung nach einem Verbindungsabbruch wieder aufgebaut werden kann. Sobald der Verbindungsaufbau erfolgreich war, muss die Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1") und den eigenen Eintrag entsprechend aus <code>%readyfnlist</code> löschen.<br />
* '''Windows-Betriebssystem:''' prüfen, ob lesbare Daten für ein serielles Device (via COM1, COM2, ...) vorliegen. Sofern lesbare Daten vorliegen, muss Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1"). Zusätzlich dazu muss die Funktion, wie bei UNIX-artigen Betriebssystem, ebenfalls bei einem Verbindungsabbruch einen neuen Verbindungsversuch initiieren. Der Eintrag in <code>%readyfnlist</code> bleibt solange erhalten, bis die Verbindung seitens FHEM beendet wird.<br />
<br />
Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.<br />
<br />
Bei der Nutzung des Moduls [[DevIo]] wird dem Modulentwickler der Umgang mit <code>%readyfnlist</code> abgenommen, da DevIo sich selbst um die entsprechenden Einträge kümmert und diese selbstständig wieder entfernt.<br />
<br />
In der Regel sieht eine Ready-Funktion immer gleich aus.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Ready($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.<br />
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );<br />
<br />
# This is relevant for Windows/USB only<br />
if(defined($hash->{USBDev})) {<br />
my $po = $hash->{USBDev};<br />
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;<br />
return ( $InBytes > 0 );<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Notify ====<br />
<br />
Die X_Notify-Funktion wird aus der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] in fhem.pl heraus aufgerufen sobald ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind dabei das [[FileLog]]-Modul oder das [[notify]]-Modul.<br />
<br />
Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, dass die Events erzeugt hat. <br />
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.<br />
Über den Hash des Gerätes und der [[DevelopmentModuleAPI#deviceEvents|deviceEvents()]]-Funktion kann man auf die generierten Events zugreifen. Über den zweiten Parameter dieser Routine lässt sich bestimmen ob für das Reading <code>state</code> ein 'normales' Event (d.h. in der form <code>state: <wert></code>) erzeugen soll (Wert: 1) oder ob z.b. aus Gründen der Rückwärtskompatibilität ein Event ohne <code>state: </code> erzeugt werden soll. Falls dem Anwender die Wahl des verwendeten Formats überlassen werden soll ist hierzu das {{Link2CmdRef|Anker=addStateEvent|Lang=de|Label=addStateEvent-Attribut}} vorzusehen.<br />
<br />
Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Notify($$)<br />
{<br />
my ($own_hash, $dev_hash) = @_;<br />
my $ownName = $own_hash->{NAME}; # own name / hash<br />
<br />
return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled<br />
<br />
my $devName = $dev_hash->{NAME}; # Device that created the events<br />
<br />
my $events = deviceEvents($dev_hash,1);<br />
return if( !$events );<br />
<br />
foreach my $event (@{$events}) {<br />
$event = "" if(!defined($event));<br />
<br />
# Examples:<br />
# $event = "readingname: value" <br />
# or<br />
# $event = "INITIALIZED" (for $devName equal "global")<br />
#<br />
# processing $event with further code<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
<u>Begrenzung der Aufrufe auf bestimmte Geräte</u><br />
<br />
Da die Notify-Funktion für jedes definierte Gerät mit all seinen Events aufgerufen wird, muss sie in einer Schleife jedesmal prüfen und entscheiden, ob es mit dem jeweiligen Event etwas anfangen kann. Ein Gerät, dass die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.<br />
<br />
Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer {{Link2CmdRef|Lang=de|Anker=devspec|Label=devspec}} in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eine der Definitionen, auf welche die devspec passt, ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":<br />
<br />
<syntaxhighlight lang="perl"><br />
in der Define-Funktion:<br />
<br />
$hash->{NOTIFYDEV} = "global";<br />
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";<br />
$hash->{NOTIFYDEV} = "global,TYPE=CUL_HM";<br />
</syntaxhighlight><br />
<br />
Dies schont insbesondere bei grossen Installationen Ressourcen, da die Notify-Funktion nicht sämtliche Events, sondern nur noch Events der gewünschten Definitionen erhält. Dadurch erfolgen deutlich weniger Aufrufe der Notify-Funktion, was Systemressourcen schont.<br />
<br />
Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code>&lt;Definitionsname&gt;</code> bzw. <code>&lt;Definitionsname&gt;:&lt;Event&gt;</code> reagiert, so sollte man in der Define-Funktion die Funktion [[DevelopmentModuleAPI#notifyRegexpChanged|notifyRegexpChanged()]] verwenden. Diese versucht einen passenden Eintrag für <code>$hash->{NOTIFYDEV}</code> basierend auf der übergebenen Regexp zu setzen, sofern dies möglich ist.<br />
<br />
<u>Reihenfolge für den Aufruf der Notify-Funktion beeinflussen</u><br />
<br />
Sobald ein Event ausgelöst wurde, stellt sich FHEM eine Liste aller relevanten Geräte-Hashes zusammen, welche via Notify-Funktion prüfen müssen, ob das Event relevant ist. Dabei wird die Liste nach <code>$hash->{NTFY_ORDER}</code> sortiert. Diese enthält ein Order-Präfix in Form einer Ganzzahl, sowie den Namen der Definition (Bsp: <code>'''50'''-Lampe_Wohnzimmer</code>). Dadurch kann man jedoch nicht sicherstellen, dass Events von bestimmten Modulen zuerst verarbeitet werden.<br />
<br />
Wenn das eigene Modul bei der Eventverarbeitung gegenüber den anderen Modulen eine bestimmte Reihenfolge einhalten muss, kann man in der [[#X_Initialize|Initialize]]-Funktion durch Setzen von <code>$hash->{NotifyOrderPrefix}</code> diese Reihenfolge beeinflussen. Standardmäßig werden Module immer mit einem Order-Präfix von "50-" in FHEM registriert. Durch die Veränderung dieses Präfixes kann man das eigene Modul in der Reihenfolge gegenüber anderen Modulen bei der Eventverarbeitung beeinflussen. <br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
...<br />
<br />
$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft<br />
<br />
# oder...<br />
<br />
$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft<br />
<br />
</syntaxhighlight> <br />
<br />
Da dieses Präfix bei eventverarbeitenden Definitionen in <code>$hash->{NTFY_ORDER}</code> dem Definitionsnamen vorangestellt wird bewirkt es bei einer normalen aufsteigenden Sortierung nach <code>$hash->{NTFY_ORDER}</code> eine veränderte Reihenfolge. Alle Module die in der Initialize-Funktion nicht <code>$hash->{NotifyOrderPrefix}</code> explizit setzen, werden mit "50-" als Standardwert vorbelegt.<br />
<br />
==== X_Rename ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Rename ($$)<br />
{<br />
my ( $new_name, $old_name) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Die Rename-Funktion wird ausgeführt, nachdem ein Gerät umbenannt wurde. Auf diese Weise kann ein Modul auf eine Namensänderung reagieren, wenn das Gerät <code>$old_name</code> in <code>$new_name</code> umbenannt wurde. Ein typischer Fall ist das Umsetzen der Namensänderungen bei Daten die mittels [[DevelopmentModuleAPI#setKeyValue|setKeyValue()]] gespeichert wurden. Hierbei müssen die Daten, welche unter dem alten Namen gespeichert sind, auf den neuen Namen geändert werden.<br />
<br />
Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Rename ($)<br />
{<br />
my ( $new_name, $old_name ) = @_;<br />
<br />
my $old_index = "Module_X_".$old_name."_data";<br />
my $new_index = "Module_X_".$new_name."_data";<br />
<br />
my ($err, $data) = getKeyValue($old_index);<br />
return undef unless(defined($old_pwd));<br />
<br />
setKeyValue($new_index, $data);<br />
setKeyValue($old_index, undef);<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Shutdown ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Shutdown ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
Mit der X_Shutdown Funktion kann ein Modul Aktionen durchführen bevor FHEM gestoppt wird. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.). Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Shutdown($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# Verbindung schließen<br />
DevIo_CloseDev($hash);<br />
return undef;<br />
}<br />
</syntaxhighlight><br />
<br />
=== Funktionen für zweistufiges Modulkonzept ===<br />
<br />
Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:<br />
<br />
{| class="wikitable sortable"<br />
|-<br />
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung<br />
|-<br />
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.<br />
|-<br />
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.<br />
|-<br />
| [[#X_Fingerprint|X_Fingerprint]] || Rückgabe eines "Fingerabdrucks" einer Nachricht. Dient der Erkennung von Duplikaten im Rahmen von [[DevelopmentModuleAPI#Dispatch|Dispatch()]]. Kann im physischen, als auch logischen Modul benutzt werden.<br />
|}<br />
<br />
Für das zweistufige Modulkonzept muss in einem logischen Modul eine [[#X_Parse|Parse]]-Funktion im Modul-Hash registriert werden. In einem physikalischen Modul muss eine [[#X_Write|Write]]-Funktion registriert sein. Diese dienem dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.<br />
<br />
In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{ParseFn} = "X_Parse";<br />
$hash->{WriteFn} = "X_Write";<br />
$hash->{FingerprintFn} = "X_Fingerprint";<br />
</syntaxhighlight><br />
<br />
Diese Funktionen werden in diesem Abschnitt genauer beschrieben.<br />
<br />
==== X_Parse ====<br />
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font><br />
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''logisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit einem übergeordneten, physikalischen Modul austauscht.}}<br />
<syntaxhighlight lang="perl"><br />
sub X_Parse ($$)<br />
{<br />
my ( $io_hash, $message) = @_;<br />
<br />
...<br />
<br />
return $found;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Funktion X_Parse wird aufgerufen, sobald von dem IO-Gerät <code>$io_hash</code> eine Nachricht <code>$message</code> via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] zur Verarbeitung angefragt wird. Die Parse-Funktion muss dann prüfen, zu welcher Gerätedefinition diese Nachricht gehört und diese entsprechend verarbeiten.<br />
<br />
Üblicherweise enthält eine Nachricht immer eine Komponente durch welche sich die Nachricht einem Gerät zuordnen lässt (z.B. Adresse, ID-Nummer, ...). Eine solche Identifikation sollte man im Rahmen der [[#X_Define|Define]]-Funktion im logischen Modul an geeigneter Stelle speichern, um in der Parse-Funktion eine einfache Zuordnung von Adresse/ID einer Nachricht zur entsprechenden Gerätedefinition zu haben. Dazu wird in der Regel im Modul-Hash im modulspezifischen Berreich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:<br />
<br />
<syntaxhighlight lang="perl"><br />
<br />
sub X_Define ($$)<br />
{<br />
my ( $hash, $def) = @_;<br />
my @a = split("[ \t][ \t]*", $def);<br />
my $name = $a[0];<br />
<br />
...<br />
<br />
# erstes Argument ist die eindeutige Geräteadresse<br />
my $address = $a[1];<br />
<br />
# Adresse rückwärts dem Hash zuordnen (für ParseFn)<br />
$modules{X}{defptr}{$address} = $hash;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Auf Basis dieses Definition Pointers kann die Parse-Funktion nun sehr einfach prüfen, ob für die empfangene Nachricht bereits eine entsprechende Gerätedefinition existiert. Sofern diese existiert, kann die Nachricht entsprechend verarbeitet werden. Sollte jedoch keine passende Gerätedefinition zu der empfangenen Nachricht existieren, so muss die Parse-Funktion den Gerätenamen "UNDEFINED" zusammen mit den Argumenten für einen <code>define</code>-Befehl zurückgeben, welcher ein passendes Gerät in FHEM anlegen würde (durch [[autocreate]]).<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
<br />
sub X_Parse ($$)<br />
{<br />
my ( $io_hash, $message) = @_;<br />
<br />
# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts<br />
my $address = substr($message, 10, 5); <br />
<br />
# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)<br />
if(my $hash = $modules{X}{defptr}{$address}) <br />
{<br />
... # Nachricht für $hash verarbeiten<br />
<br />
# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.<br />
return $hash->{NAME}; <br />
}<br />
else<br />
{<br />
# Keine Gerätedefinition verfügbar<br />
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE><br />
return "UNDEFINED X_".$address." X $address";<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Write ====<br />
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font><br />
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''physisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit untergeordneten logischen Modulen austauscht. }}<br />
<syntaxhighlight lang="perl"><br />
sub X_Write ($$)<br />
{<br />
my ( $hash, @arguments) = @_;<br />
<br />
...<br />
<br />
return $return;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Write-Funktion wird durch die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] aufgerufen, sobald eine logische Gerätedefinition Daten per IO-Gerät an die Hardware übertragen möchte. Dazu kümmert sich die Write-Funktion um die Übertragung der Nachricht in geeigneter Form an die verbundene Hardware. Als Argumente wird der Hash des physischen Gerätes übertragen, sowie alle weiteren Argumente, die das logische Modul beim Aufruf von IOWrite() mitgegeben hat. Im Normalfall ist das ein Skalar mit der zu sendenden Nachricht in Textform. Es kann aber auch sein, dass weitere Daten zum Versand notwendig sind (evtl. Schlüssel, Session-Key, ...). Daher ist die Parametersyntax einer zu schreibenden Nachricht via IOWrite-/Write-Funktion zwischen logischem und physikalischen Modul abzustimmen.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Write ($$)<br />
{<br />
my ( $hash, $message, $address) = @_;<br />
<br />
DevIo_SimpleWrite($hash, $address.$message, 2);<br />
<br />
return undef;<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Fingerprint ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Fingerprint($$)<br />
{<br />
my ( $io_name, $msg ) = @_;<br />
<br />
...<br />
<br />
return ( $io_name, $fingerprint );<br />
}<br />
</syntaxhighlight><br />
<br />
Die Fingerprint-Funktion dient der Erkennung von Duplikaten empfangener Nachrichten. Diese Funktion kann dabei sowohl im physischen, als auch im logischen Modul implementiert sein. Je nachdem auf welcher Ebene man für eine Nachricht einen Fingerprint bilden kann. <br />
<br />
Als Parameter wird der Name des IO-Geräts <code>$io_name</code> übergeben, sowie die Nachricht <code>$msg</code>, welche empfangen wurde. Nun muss aus dieser Nachricht ein eindeutiger Fingerprint gebildet werden. Dies bedeutet, dass alle variablen Inhalte, die aufgrund des Empfangs dieser Nachricht über unterschiedliche IO-Geräte enthalten sein können, entfernt werden müssen. Dies können bspw. Empfangsadressen von IO-Geräten sein oder Session-ID's die in der Nachricht enthalten sind. Alle Fingerprints sämtlicher Nachrichten, die innerhalb der letzten 500 Millisekunden (konfigurierbar via <code>global</code> Attribut <code>dupTimeout</code>) empfangen wurden, werden gegen diesen generierten Fingerprint getestet. Sollte innerhalb dieser Zeit bereits eine Nachricht mit diesem Fingerprint verarbeitet worden sein, so wird sie als Duplikat erkannt und nicht weiter verarbeitet. In diesem Fall gibt [[DevelopmentModuleAPI#Dispatch|Dispatch()]] den Namen der Gerätedefinition zurück, welche eine Nachricht mit dem selben Fingerprint bereits verarbeitet hat. Es erfolgt dann kein Aufruf der [[#X_Parse|Parse]]-Funktion.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Fingerprint($$)<br />
{<br />
my ( $io_name, $msg ) = @_;<br />
<br />
substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse<br />
substr( $msg, 4, 1, "-" ); # entferne Hop-Count<br />
<br />
return ( $io_name, $msg );<br />
}<br />
</syntaxhighlight><br />
<br />
Es wird zuerst, sofern implementiert, die Fingerprint-Funktion des physischen Moduls aufgerufen. Sollte sich hierdurch kein Duplikat erkennen lassen, wird die Fingerprint-Funktion jedes möglichen geladenen logischen Moduls aufgerufen, sofern implementiert. <br />
<br />
Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.<br />
<br />
=== FHEMWEB-spezifische Funktionen ===<br />
<br />
FHEMWEB bietet Modulautoren die Möglichkeit an durch spezielle Funktionsaufrufe in Modulen, eigene HTML-Inhalte zu verwenden. Dadurch können in Verbindung mit zusätzlichem JavaScript komplexe Dialoge/Inhalte/Steuermöglichkeiten dargestellt werden. <br />
<br />
Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]<br />
<br />
=== sonstige Funktionen ===<br />
<br />
In diesem Abschnitt werden weitere Funktionen behandelt die zum Teil aus FHEM, aber auch aus anderen Modulen aufgerufen werden. Sie sind dabei nur in speziellen Anwendungsfällen relevant. Hier eine Auflistung aller sonstigen Modulfunktionen:<br />
<br />
{| class="wikitable sortable"<br />
|-<br />
! Funktionsname !! class="unsortable" | Kurzbeschreibung<br />
|-<br />
| [[#X_DbLog_split|X_DbLog_split]] || Wird durch das Modul 93_DbLog.pm aufgerufen. Dient dem korrekten Split eines moduleigenen Events in Name/Wert/Einheit für die Nutzung einer Datenbank.<br />
|-<br />
| [[#X_Except|X_Except]]|| Wird aufgerufen, sobald ein ein geöffneter Filedescriptor in [[#Wichtige_globale_Variablen_aus_fhem.pl|<code>%selectlist</code>]], der unter <code>$hash->{EXCEPT_FD}</code> im Geräte-Hash gesetzt ist, einen Interrupt bzw. Exception auslöst.<br />
|-<br />
| [[#X_Copy|X_Copy]]|| Wird durch das Modul 98_copy.pm aufgerufen im Rahmen des <code>copy</code>-Befehls sobald ein Gerät kopiert wurde.<br />
|-<br />
| [[#X_State|X_State]]|| Wird aufgerufen im Rahmen des <code>setstate</code>-Befehls bevor der Status einer Gerätedefinition bzw. eines zugehörigen Readings gesetzt wird.<br />
|-<br />
| [[#X_AsyncOutput|X_AsyncOutput]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht die asynchrone Ausgabe von Daten via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an einen einzelnen verbundenen Client.<br />
|-<br />
| [[#X_ActivateInform|X_ActivateInform]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht das aktivieren des inform-Mechanismus zum senden von Events für einen einzelnen verbundenen Client.<br />
|-<br />
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorized|Authorized()]] um eine gewünschte Vorgangs-Art zu autorisieren.<br />
|-<br />
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.<br />
|}<br />
<br />
In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{DbLog_splitFn} = "X_DbLog_split";<br />
$hash->{ExceptFn} = "X_Except";<br />
$hash->{CopyFn} = "X_Copy";<br />
$hash->{AsyncOutputFn} = "X_AsyncOutput";<br />
$hash->{ActivateInformFn} = "X_ActivateInform";<br />
$hash->{StateFn} = "X_State";<br />
$hash->{AuthorizeFn} = "X_Authorize";<br />
$hash->{AuthenticateFn} = "X_Authenticate";<br />
</syntaxhighlight><br />
<br />
<br />
Diese Funktionen werden in diesem Abschnitt genauer beschrieben.<br />
==== X_DbLog_split ====<br />
<syntaxhighlight lang="perl"><br />
sub X_DbLog_split ($$)<br />
{<br />
my ( $event, $device_name ) = @_;<br />
<br />
...<br />
<br />
return ( $reading, $value, $unit );<br />
}<br />
</syntaxhighlight><br />
<br />
Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modulautor das Auftrennen von Events in den Reading-Namen, -Wert und der Einheit selbst steuern. Andernfalls nimmt DbLog diese Auftrennung selber mittels Trennung durch Leerzeichen sowie vordefinierten Regeln zu verschiedenen Modulen vor. Je nachdem, welche Readings man in seinem Modul implementiert, passt diese standardmäßige Trennung jedoch nicht immer.<br />
<br />
Der Funktion werden folgende Eingangsparameter übergeben:<br />
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)<br />
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)<br />
<br />
Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.<br />
<br />
Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:<br />
# Name des Readings (Bsp: <code>temperature</code>)<br />
# Wert des Readings (Bsp: <code>20.5</code>)<br />
# Einheit des Readings (Bsp: <code>°C</code>)<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_DbLog_splitFn($$)<br />
{<br />
my ($event, $device) = @_;<br />
my ($reading, $value, $unit);<br />
my $devhash = $defs{$device}<br />
<br />
if($event =~ m/temperature/) {<br />
$reading = 'temperature';<br />
$value = substr($event,12,4);<br />
$unit = '°C';<br />
} <br />
<br />
return ($reading, $value, $unit);<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Except ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Except ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Die X_Except-Funktion wird durch fhem.pl aufgerufen, wenn die Gerätedefinition <code>$hash</code> in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> aufgeführt ist und der Filedeskriptor in <code>$hash->{EXCEPT_FD}</code> eine Exception bzw. Interrupt auslöst. <br />
<br />
Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
use IO::File;<br />
<br />
...<br />
<br />
sub X_Except ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
# Filehandle aus Filedescriptor erstellen<br />
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');<br />
seek($filehandle,0,0); <br />
<br />
# aktuellen Inhalt auslesen<br />
my $current_value = $filehandle->getline;<br />
<br />
if($current_value eq "1")<br />
{<br />
...<br />
}<br />
else<br />
{<br />
...<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Copy ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Copy ($)<br />
{<br />
my ( $old_name, $new_name ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Die X_Copy-Funktion wird durch das Modul [[copy]] aufgerufen nachdem ein Nutzer eine Gerätedefinition über den Befehl <code>copy</code> kopiert hat. Dazu werden als Funktionsparameter die Definitionsnamen der alten und neuen Gerätedefinition übergeben. Es dient dazu zusätzliche Daten aus der zu kopierenden Gerätedefinition in die neue Definition zu übernehmen. Der Befehl <code>copy</code> überträgt lediglich <code>$hash->{DEF}</code> in die neue Definition sowie sämtliche gesetzte Attribute. Weitere Daten müssen dann durch die X_Copy-Funktion übertragen werden. <br />
<br />
Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.<br />
<br />
Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
<br />
sub X_Copy ($$)<br />
{<br />
my ( $old_name, $new_name ) = @_;<br />
<br />
my $old_hash = $defs{$old_name};<br />
my $new_hash = $defs{$new_name};<br />
<br />
# copy also temporary session key<br />
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_AsyncOutput ====<br />
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}<br />
<syntaxhighlight lang="perl"><br />
sub X_AsyncOutput ($)<br />
{<br />
my ( $client_hash, $text ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Funktion X_AsyncOutput wird durch [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] von anderen Modulen aufgerufen. Es erlaubt diesen anderen Modulen die Ausgabe von asynchronen Befehlsergebnissen <code>$text</code> zuvor ausgeführter set-/get-Befehle an den entsprechenden Client (identifiziert durch den Client-Hash <code>$client_hash</code> der temporären Definition) zurückzugeben. <br />
<br />
Wenn ein Client einen set-/get-Befehl ausführt, wird der Client-Hash bei der Ausführung dieser Befehle an die jeweiligen Module übermittelt. Sobald ein Befehl ausgeführt wird, der seine Ausgabe asynchron ausführen möchte und die Client-Verbindung des Server-Moduls dies unterstützt (<code>$client_hash->{canAsyncOutput}</code> ist gesetzt), merkt sich das befehlsausführende Modul den Client-Hash und gibt das Ergebnis des Befehls zu späterer Zeit via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an den ursprünglichen Client zurück. Die Funktion X_AsyncOutput des Server-Moduls kümmert sich darum das Ergebnis dem entsprechenden Client in der notwendigen Form zuzustellen.<br />
<br />
Der Rückgabewert von X_AsyncOutput() wird als Rückgabewert für asyncOutput() verwendet. Man kann hier im Fehlerfall eine Fehlermeldung angeben und im Erfolgsfall <code>undef</code>. Der Rückgabewert wird aber aktuell nicht ausgewertet.<br />
<br />
==== X_ActivateInform====<br />
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}<br />
<syntaxhighlight lang="perl"><br />
sub X_ActivateInform($$)<br />
{<br />
my ( $client_hash, $arg ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Die Funktion X_ActivateInform wird aktuell nur durch den [[update]]-Befehl aufgerufen, sofern ein Client eines Frontend-Moduls diesen Befehl aufgerufen hat um den Inform-Mechanismus (Senden von Events) zu aktivieren. Dadurch wird im Falle von [[update]] die umgehende Anzeige der Logmeldungen für den ausführenden Client aktiviert. In [[FHEMWEB]] geschieht das über den Event-Monitor, bei telnet mit der direkten Ausgabe.<br />
<br />
Da diese Funktion aktuell nur speziell für den update-Befehl implementiert ist, kann man aktuell keine genaue Angaben zu den möglichen Werten von <code>$arg</code> geben. Dieser Parameter dient dazu genauer zu spezifizieren was exakt an Events an den entsprechenden Client <code>$client_hash</code> zu senden ist. Aktuell wird dazu die Parametersyntax des inform-Befehls verwendet (on|off|log|raw|timer|status).<br />
<br />
==== X_State ====<br />
<syntaxhighlight lang="perl"><br />
sub X_State($$$$)<br />
{<br />
my ( $hash, $time, $readingName, $value ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die X_State-Funktion wird durch fhem.pl aufgerufen, sobald über den Befehl <code>setstate</code> versucht wird ein Wert für ein Reading oder den Status (<code>$hash->{STATE}</code>) einer Gerätedefinition zu setzen. Dieser Befehl wird primär beim Starten von FHEM aufgerufen sobald das State-File eingelesen wird. Je nachdem, ob im gegebenen Fall ein Reading oder der Definitionsstatus gesetzt wird, haben die Übergabeparameter verschiedene Werte:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus<br />
|-<br />
| <code>$hash</code> || colspan=2 align=center | Die Hashreferenz der betreffenden Gerätedefinition<br />
|-<br />
| <code>$time</code>|| Der Zeitstempel auf welchen das Reading <code>$readingName</code> gesetzt werden soll. Das Ergebnis entspricht dem Rückgabewert der Funktion || Der aktuelle Zeitstempel zum jetzigen Zeitpunkt.<br />
|-<br />
| <code>$readingName</code>|| Der Name des Readings, welches auf einen neuen Wert gesetzt werden soll. || Statischer Wert "STATE" um anzuzeigen, dass es sich um den Definitionsstatus handelt, welcher gesetzt werden soll (<code>$hash->{STATE}</code>).<br />
|-<br />
| <code>$value</code> || Den Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Den Wert, welchen die Gerätedefinition als Status annehmen soll.<br />
|}<br />
<br />
Wenn via <code>setstate</code> ein Reading gesetzt wird, kann die X_State-Funktion das Setzen dieses Readings durch die Rückgabe einer aussagekräftigen Fehlermeldung unterbinden. Sofern <code>undef</code> zurückgegeben wird, wird das entsprechende Reading auf den übergebenen Status gesetzt.<br />
<br />
Wenn via <code>setstate</code> der Definitionsstatus gesetzt wird, wird die X_State-Funktion erst nach dem Setzen des Status aufgerufen. Man kann dabei zwar eine Fehlermeldung zurückgeben, der Status wird aber dennoch übernommen. Die Fehlermeldung wird lediglich dem Nutzer angezeigt.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_State($$$$)<br />
{<br />
my ( $hash, $time, $readingName, $value ) = @_;<br />
<br />
return undef if($readingName "STATE" || $value ne "inactive");<br />
readingsSingleUpdate($hash, "state", "inactive", 1);<br />
return undef;<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Authorize ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Authorize($$$$)<br />
{<br />
my ( $hash, $client_hash, $type, $arg ) = @_;<br />
<br />
...<br />
<br />
return $authorized;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Authorize-Funktion wird von fhem.pl aufgerufen um zu erfragen, ob ein bestimmter Client <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf. Auf diese Weise können Module Einfluss nehmen, welcher User welche Funktionen in FHEM nutzen darf. Wenn ein Client eine Aktion ausführen möchte, werden alle Module, die eine Authorize-Funktion implementiert haben, gefragt, ob diese Aktion ausgeführt werden darf. Als Rückgabewert wird das Ergebnis der Überprüfung zurückgegeben, wobei <code>0</code> (unbekannt / nicht zuständig), <code>1</code> (erlaubt) oder <code>2</code> (verboten) zurückgegeben werden können.<br />
<br />
Es gibt aktuell folgende <code>$type</code>/<code>$arg</code> Kombinationen, mit denen die Authorize-Funktion aufgerufen werden:<br />
<br />
{| class="wikitable"<br />
|-<br />
! $type !! $arg !! Überschrift<br />
|- <br />
|rowspan="3" style="white-space: nowrap;" | <code>'''$type''' = "cmd"</code><br />
<br />
<br />
''Befehlsausführung''<br />
| style="white-space: nowrap;" | <code>'''$arg''' = "set Lampe on"</code> || Jeglicher FHEM-Befehl, der ausgeführt werden soll, wird in <code>$arg</code> hinterlegt, sodass innerhalb einer Authorize-Funktion der Befehl genauer geparst werden kann um zu entscheiden, ob dieser Befehl erlaubt ist, oder nicht.<br />
|-<br />
| style="white-space: nowrap;" | <code>'''$arg''' = "perl"</code> || Ausführen von Perl-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.<br />
<br />
Bsp: <code>{ReadingsVal("Lampe", "state", "off"}</code><br />
|-<br />
| style="white-space: nowrap;" | <code>'''$arg''' = "shell"</code> || Ausführen von Shell-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.<br />
<br />
Bsp: <code>"/opt/fhem/myScript.sh"</code><br />
|-<br />
|style="white-space: nowrap;" | <code>'''$type''' = "devicename"</code><br />
<br />
<br />
''Sichtbarkeit von Geräten/Definitionen'' <br />
|style="white-space: nowrap;" | <code>'''$arg''' = "Licht_Wohnzimmer"</code> || Sichtbarkeit des jeweiligen Gerät/Definition in FHEM. Dies bedeutet konkret die Auffindbarkeit im <code>list</code>-Befehl, sowie der Suche via [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wird eine solche Anfrage durch die Authorize-Funktion abgelehnt, ist das entsprechende Gerät bzw. Definition für den jeweiligen Client nicht sichtbar.<br />
|}<br />
<br />
==== X_Authenticate ====<br />
{{Link2Forum|Topic=72757|Message=644098}}<br />
<br />
== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==<br />
<br />
Ein Modul kann primär einen neuen FHEM-Befehl bereitstellen. Man spricht in so einem Fall nicht von einem Gerätemodul, sondern einem Befehlsmodul. Ein solches Befehlsmodul stellt nur einen einzelnen Befehl bereit, der dem Modulnamen entsprechen muss. Nur, wenn der Modulname dem Befehlsname entspricht, kann FHEM das Modul beim ersten Ausführen dieses unbekannten Befehls finden und nachladen.<br />
<br />
Der entsprechende Befehl wird dazu in der [[#X_Initialize|Initialize]]-Funktion im globalen Hash <code>[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|%cmds]]</code> registriert:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($$) {<br />
<br />
$cmds{X} = { Fn => "CommandX",<br />
Hlp => "<argument1> [optional_argument2], print something very useful",<br />
<br />
# optionaler Filter für Clientmodule als regulärer Ausdruck<br />
ClientFilter => "FHEMWEB"<br />
};<br />
}<br />
</syntaxhighlight><br />
<br />
Damit wird der neue Befehl <code>X</code> in FHEM registriert. Die Funktion mit dem Namen <code>CommandX</code> setzt diesen Befehl innerhalb des Moduls um. Desweiteren wird eine kurze Aufrufsyntax mitgegeben, welche beim Aufruf des <code>help</code>-Befehls dem Nutzer angezeigt wird um als Gedankenstütze zu dienen. Optional kann man mittels <code>ClientFilter</code> (regulärer Ausdruck für Modulnamen) die Ausführbarkeit nur auf bestimmte Client-Module (wie FHEMWEB oder telnet) beschränken. <br />
<br />
Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:<br />
<br />
<syntaxhighlight lang="Perl"><br />
sub CommandX($$)<br />
{<br />
my ($client_hash, $arguments) = @_;<br />
<br />
...<br />
<br />
return $output;<br />
}<br />
</syntaxhighlight><br />
<br />
Dabei werden der Befehlsfunktion zwei Parameter übergeben. Zuerst die Hash-Referenz des aufrufenden Clients (sofern manuell ausgeführt, ansonsten <code>undef</code>) zwecks Rechteprüfung via [[allowed|allowed-Definitionen]]. Anschließend folgen die Aufrufparameter als zusammenhängende Zeichenkette. Die Trennung der einzelnen Argumente obligt der Funktion (bspw. via [[DevelopmentModuleAPI#parseParams|parseParams()]]). Als Funktionsrückgabewert wird eine Ausgabemeldung erwartet, die dem Nutzer angezeigt werden soll.<br />
<br />
== Pollen von Geräten ==<br />
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion [[DevelopmentModuleAPI#InternalTimer|InternalTimer()]] verwenden um einen Funktionsaufruf zu einem späteren Zeitpunkt durchführen zu können. Man übergibt dabei den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, sowie den zu übergebenden Parameter. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.<br />
<br />
Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:<br />
<br />
<syntaxhighlight lang="perl"><br />
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash); <br />
</syntaxhighlight><br />
<br />
Alternativ kann man auch in der [[#X_Notify|Notify]]-Funktion auf das Event <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> reagieren und erst dort, den Timer anstoßen, sobald die Konfiguration komplett eingelesen wurde. Dies ist insbesondere notwendig, wenn man sicherstellen will, dass alle Attribute aus der Konfiguration gesetzt sind, sobald man einen Status-Update initiiert.<br />
<br />
In der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_GetUpdate($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
Log3 $name, 4, "X: GetUpdate called ...";<br />
<br />
...<br />
<br />
# neuen Timer starten in einem konfigurierten Interval.<br />
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);<br />
}<br />
</syntaxhighlight><br />
<br />
Innerhalb der Funktion kann man nun das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene [[#X_Read|Read]]-Funktion zu implementieren.<br />
<br />
Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]<br />
<br />
== Logging / Debugging ==<br />
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.<br />
<syntaxhighlight lang="perl"><br />
Log3 $name, 3, "X ($name) - Problem erkannt ...";<br />
</syntaxhighlight><br />
Eine genaue Beschreibung zu der Funktion inkl. Aufrufparameter findet man [[DevelopmentModuleAPI#Log3|hier]]. Es ist generell ratsam in der Logmeldung sowohl den Namen des eigenen Moduls zu schreiben, sowie den Namen des Geräts, welche diese Logmeldung produziert, da die Meldung, so wie sie ist, direkt in das Logfile wandert und es für User ohne diese Informationen schwierig ist, die Meldungen korrekt zuzuordnen.<br />
<br />
Die Funktion Log3() verwendet den Namen der Geräteinstanz um das <code>verbose</code>-Attribut zu prüfen. In der Regel wird bei Modulfunktionen jedoch immer nur der Gerätehash <code>$hash</code> übergeben. Um den Namen der Definition zu ermitteln ist es daher notwendig sich diesen aus dem Hash extrahieren:<br />
<br />
<syntaxhighlight lang="perl"><br />
my $name = $hash->{NAME};<br />
</syntaxhighlight><br />
<br />
Um für eine einzelne Geräteinstanz das Verbose-Level zu erhöhen, ohne gleich für das gesamte FHEM den globalen Verbose-Level zu erhöhen und damit alle Meldungen zu erzeugen, kann man den Befehl <br />
<code>attr <NAME> verbose</code> verwenden. Beispielsweise <code>attr Lichtschalter_Wohnzimmer verbose 5</code><br />
<br />
Logmeldungen sollten je nach Art und Wichtigkeit für den Nutzer in unterschiedlichen Loglevels erzeugt werden. Es gibt insgesamt 5 Stufen in denen geloggt werden kann. Standardmäßig steht der systemweite Loglevel (<code>global</code>-Attribut <code>verbose</code>) auf der Stufe 3. Die Bedeutung der jeweiligen Stufen ist in der {{Link2CmdRef|Lang=de|Anker=verbose}} beschrieben.<br />
<br />
Während der Entwicklung eines Moduls kann man für eigene Debug-Zwecke auch die Funktion [[DevelopmentModuleAPI#Debug|Debug()]] verwenden um schnell und einfach Debug-Ausgaben in das Log zu schreiben. Diese sollten in der endgültigen Fassung jedoch nicht mehr vorhanden sein. Sie dienen ausschließlich zum Debugging während der Entwicklung.<br />
<br />
Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].<br />
<br />
== Zweistufiges Modell für Module ==<br />
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts|Schematische Darstellung am Beispiel CUL]]<br />
Es gibt viele Geräte, welche die Kommunikation mit weiteren Geräten mit tlw. unterschiedlichen Protokollen ermöglichen. Das typischste Beispiel bietet hier der [[CUL]], welcher via Funk mit verschiedenen Protokollen weitere Geräte ansprechen kann (z.B. Aktoren, Sensoren, ...). Hier bildet ein Gerät eine Brücke durch die weitere Geräte in FHEM zugänglich gemacht werden können. Dabei werden über einen Kommunikationsweg (z.B. serielle Schnittstelle, TCP, ...) beliebig viele Geräte gesteuert. Typische Beispiele dazu sind:<br />
<br />
* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)<br />
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit<br />
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit<br />
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit<br />
<br />
Dabei wird die Kommunikation in 2 Stufen unterteilt:<br />
* physisches Modul - z.B. 00_CUL.pm - zuständig für die physikalische Kommunikation mit der Hardware. Empfangene Daten müssen einem logischen Modul zugeordnet werden.<br />
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.<br />
<br />
<u>physisches Modul</u><br />
<br />
Das physische Modul öffnet die Datenverbindung zum Gerät (z.B. CUL) und verarbeitet sämtliche Daten. Es kümmert sich um den Erhalt der Verbindung (bsp. durch Keep-Alives) und konfiguriert das Gerät so, dass eine Kommunikation mit allen weiteren Geräten möglich ist (bsp. Frequenz, Modulation, Kanal, etc.).<br />
<br />
Empfangene Nutzdaten werden als Zeichenkette über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.<br />
<br />
Das Modul stellt eine [[#Die_Match-Liste|Match-Liste]] bereit, anhand FHEM die Nachricht einem Modul zuordnen kann, sofern dieses noch nicht geladen sein sollte. Die Match-Liste enthält eine Liste von regulären Ausdrücken und ordnet diese einem Modul zu. Wenn eine Nachricht auf einen solchen regulären Ausdruck passt und das Modul noch nicht geladen ist, lädt FHEM dieses automatisch nach, zwecks Verarbeitung der Nachricht. <br />
<br />
Anhand einer bereitgestellten [[#Die_Client-Liste|Client-Liste]] (Auflistung von logischen Modulen) kann FHEM feststellen, welche logischen Module mit dem physischen Modul kommunizieren können. Nur die hier aufgelisteten, logischen Module werden beim Aufruf von [[DevelopmentModuleAPI#Dispatch|Dispatch()]] angesprochen.<br />
<br />
Das Modul stellt eine [[#X_Write|Write]]-Funktion zur Verfügung, über die logische Module Daten in beliebiger Form an die Hardware übertragen können. <br />
<br />
<u>logisches Modul</u><br />
<br />
Das logische Modul interpretiert die via Dispatch() übergebene Nachricht (Zeichenkette) durch eine bereitgestellte [[#X_Parse|Parse]]-Funktion und erzeugt entsprechende Readings/Events. Es stellt über <code>set</code>-/<code>get</code>-Kommandos Steuerungsmöglichkeiten dem Nutzer zur Verfügung.<br />
<br />
Es stellt FHEM einen [[#Der_Match-Ausdruck|Match-Ausdruck]] (regulärer Ausdruck) zur Verfügung anhand [[DevelopmentModuleAPI#Dispatch|Dispatch()]] ermitteln kann, ob die Nachricht durch das logische Modul verarbeitet werden kann. Nur Nachrichten, welche auf diesen Ausdruck passen, werden an das logische Modul weitergegeben (Aufruf [[#X_Parse|Parse]]-Funktion).<br />
<br />
=== Die Client-Liste ===<br />
<br />
Die Client-Liste ist eine Auflistung von Modulnamen (genauer: regulären Ausdrücken die auf Modulnamen passen) die in einem physischen Modul gesetzt ist. Damit wird definiert, mit welchen logischen Modulen das physikalische Modul kommunizieren kann. <br />
<br />
Eine Client-Liste ist eine Zeichenkette, welche aus allen logischen Modulnamen besteht. Die einzelnen Namen werden durch einen Doppelpunkt getrennt. Anstatt kompletter Modulnamen können auch reguläre Ausdrücke verwendet werden, die auf mehrere Modulnamen passen (z.B. <code>CUL_.*</code> um die logischen Module CUL_HM, CUL_MAX, etc. zu verwenden).<br />
<br />
Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:<br />
<br />
FS20:FHT.*:KS300:USF1000:BS:HMS:CUL_EM:CUL_WS:CUL_FHTTK:CUL_HOERMANN:ESA2000:CUL_IR:CUL_TX:Revolt:IT:UNIRoll:SOMFY:STACKABLE_CC:CUL_RFR:CUL_TCM97001:CUL_REDIRECT<br />
<br />
Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.<br />
<br />
Die Client-Liste hat generell folgende Funktion:<br />
* Die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur Module, welche in der Client-Liste enthalten sind, ob diese die Nachricht verarbeiten können (Prüfung via [[#Der Match-Ausdruck|Match-Ausdruck]])<br />
* Die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] prüft anhand sämtlicher Client-Listen in FHEM, welches IO-Gerät für ein logisches Gerät nutzbar ist.<br />
<br />
Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
...<br />
$hash->{Clients} = "FS20:KS300:FHT.*";<br />
}<br />
</syntaxhighlight><br />
<br />
Man kann die Client-Liste jedoch auch pro physikalisches Gerät setzen. Eine gesetzte Client-Liste in einem Gerät hat immer Vorrang vor der Liste im Modul-Hash. Eine gerätespezifische Client-Liste wird dann verwendet, wenn bspw. ein Gerät je nach Konfiguration nur bestimmte logische Module bedienen kann. Bspw. kann ein CUL je nach RF-Einstellungen FS20, uvm. oder nur HomeMatic bedienen. In einem solchen Fall wird die Client-Liste im Geräte-Hash gesetzt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ( $hash, $def ) = @_;<br />
...<br />
$hash->{Clients} = "CUL_HM";<br />
}<br />
</syntaxhighlight><br />
<br />
In vielen Modulen, welche nach dem zweistufigem Konzept arbeiten, beginnt und endet die Client-Liste mit einem Doppelpunkt. Dies ist ein historisches Überbleibsel, da der Prüfmechanismus die Client-Liste früher auf das Vorhandensein von <code>'''<u><font color="red">:</font></u>'''&lt;Modulname&gt;'''<u><font color="red">:</font></u>'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.<br />
<br />
=== Die Match-Liste ===<br />
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font><br />
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.<br />
<br />
Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:<br />
<br />
<syntaxhighlight lang="perl"><br />
my %matchListFHEMduino = (<br />
....<br />
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",<br />
....<br />
"13:IT" => "^(?-i)i......\$",<br />
);<br />
</syntaxhighlight><br />
<br />
Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}<br />
}}<br />
Die Match-Liste ordnet eine Nachrichtensyntax (regulärer Ausdruck) einem Modulnamen zu und wird in einem physikalischen Modul gesetzt. Sollte eine Nachricht vom physikalischen Gerät empfangen werden, die durch kein geladenes Modul verarbeitet werden kann ([[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur alle geladenen Module aus der [[#Die Client-Liste|Client-Liste), so wird über die Match-Liste geprüft, welches Modul diese Nachricht verarbeiten kann. Dieses Modul wird anschließend geladen und die Nachricht durch dieses verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.<br />
<br />
Diese Liste wird ausschließlich in der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion verwendet. Sollte keine passendes Modul, welches bereits geladen ist, zur Verarbeitung einer Nachricht gefunden werden, so wird mithilfe der Match-Liste aufgrund der vorliegenden Nachricht das entsprechende Modul ermittelt. Dieses Modul wird dann direkt geladen und die Nachricht wird via [[#X_Parse|Parse]]-Funktion verarbeitet.<br />
<br />
Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:<br />
<br />
<syntaxhighlight lang="perl"><br />
{<br />
"1:FS20" => "^81..(04|0c)..0101a001",<br />
"2:KS300" => "^810d04..4027a001",<br />
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."<br />
}<br />
</syntaxhighlight><br />
<br />
Das Sortierpräfix (<code><u>1:</u><font color="grey">FS20</font></code>) dient als Sortierhilfe um so die Reihenfolge der Prüfung festzulegen. Bei der Prüfung wird die Match-Liste mittels sort() nach dem Schlüssel (Sortierpräfix + Modulname) sortiert und die regulären Ausdrücke werden dann nacheinander getestet. Daher sollten die präzisesten Ausdrücke immer zuerst getestet werden, sofern es weniger präzise Ausdrücke in der Match-Liste gibt. Dabei ist zu beachten, dass der Sortierpräfix nicht nach numerischen Regeln sortiert wird, sondern zeichenbasierend.<br />
<br />
Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
...<br />
<br />
$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",<br />
"2:KS300" => "^810d04..4027a001",<br />
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };<br />
}<br />
</syntaxhighlight><br />
<br />
Man kann die Match-Liste, ähnlich wie bei der Client-Liste, auch pro physikalisches Gerät setzen. Dabei hat auch hier die Match-Liste eines Gerätes immer Vorrang vor der Match-Liste aus dem Modul-Hash:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ($hash, $def) = @_;<br />
<br />
...<br />
<br />
$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };<br />
}<br />
</syntaxhighlight><br />
<br />
=== Der Match-Ausdruck ===<br />
<br />
Ein Match-Ausdruck wird in einem logischen Modul gesetzt und dient der Prüfung, ob eine Nachricht durch das eigene Modul via [[#X_Parse|Parse]]-Funktion verarbeitet werden kann. Es handelt sich hierbei um einen einzelnen regulären Ausdruck, den FHEM innerhalb der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion prüft. Nur wenn eine Nachricht via Dispatch() auf diesen Audruck matcht, wird die Parse-Funktion des eigenen Moduls aufgerufen um die Nachricht zu verarbeiten. <br />
<br />
Der Hintergrund, warum man den Aufruf mit einem solchen Ausdruck vorher abprüft, liegt in der Möglichkeit, dass ein physikalisches Modul mehrere unterschiedliche logische Module ansprechen kann. So kann FHEM jedes geladene Modul durch diesen Match-Ausdruck prüfen, ob es diese Nachricht verarbeiten kann. Erst, wenn alle geladenen Module, aufgrund einer Prüfung des Ausdrucks, die Nachricht nicht verarbeiten können, wird via [[#Die_Match-Liste|Match-Liste]] ermittelt, welches Modul geladen werden muss um die Nachricht zu verarbeiten. <br />
<br />
Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
...<br />
<br />
# Dieses Modul verarbeitet FS20 Nachrichten<br />
$hash->{Match} = "^81..(04|0c)..0101a001"; <br />
}<br />
</syntaxhighlight><br />
=== Die vollständige Implementierung ===<br />
<br />
Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.<br />
<br />
==== physisches Modul ====<br />
<br />
Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:<br />
<br />
* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.<br />
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).<br />
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.<br />
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.<br />
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.<br />
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.<br />
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.<br />
<br />
Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:<br />
<br />
* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können<br />
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.<br />
<br />
==== logisches Modul ====<br />
<br />
Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:<br />
<br />
* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.<br />
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])<br />
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.<br />
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.<br />
<br />
Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:<br />
<br />
* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.<br />
<br />
=== Kommunikation von der Hardware bis zu den logischen Modulen ===<br />
<br />
Die Gerätedefinition des physischen Moduls öffnet eine Verbindung zur Hardware (z.B. via [[DevIo]]). Die [[#X_Read|Read]]-Funktion wird bei anstehenden Daten aus der Hauptschleife von fhem.pl aufgerufen.<br />
<br />
Die Read-Funktion stellt dabei sicher, dass die Daten<br />
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und<br />
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)<br />
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.<br />
<br />
Die Funktion Dispatch() prüft alle geladenen Module aus der [[#Die_Client-Liste|Client-Liste]] des physikalischen Moduls nach möglichen logischen Modulen zur Verarbeitung. Alle zum Zeitpunkt geladenen Module, die in der Client-Liste aufgeführt sind, werden über den [[#Der_Match-Ausdruck|Match-Ausdruck]] geprüft, ob sie mit der Nachricht etwas anfangen können. Sollte bei einem logischen Modul der Match-Ausdruck passen, so wird die entsprechende [[#X_Parse|Parse]]-Funktion des logischen Moduls aufgerufen. Sofern keine passendes Modul gefunden wurde, um die Nachricht zu verarbeiten, wird in der [[#Die_Match-Liste|Match-Liste]] im Geräte- bzw. Modul-Hash der physischen Gerätedefinition nach dem passenden Modul gesucht. Sollte es darin ein Modul geben, was diese Art von Nachricht verarbeiten kann, so wird versucht dieses Modul zu laden um nun die Nachricht via Parse-Funktion zu verarbeiten. Es erfolgt in diesem Fall keine Vorprüfung durch den Match-Ausdruck.<br />
<br />
Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese<br />
* interpretiert die übergebene Nachricht,<br />
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,<br />
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,<br />
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.<br />
<br />
Sollte keine passende Gerätedefinition für die entsprechende Nachricht existieren (Adresse/ID/Kanal/...), wird der Gerätename "UNDEFINED" inkl. einem passenden <code>define</code>-Statement zurückgegeben, um die Definition durch [[autocreate]] erzeugen zu lassen.<br />
<br />
Es findet während der Verarbeitung einer Nachricht durch Dispatch()/Parse-Funktion keine sofortige Eventverarbeitung (via [[DevelopmentModuleAPI#Dispatch|DoTrigger()]]) statt, wenn die [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen verwendet werden.<br />
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )<br />
<br />
Die Funktion Dispatch() triggert das Event-Handling für das von der Parse-Funktion zurückgegebene logische Device selbstständig nach Abschluss der Parse-Funktion.<br />
<br />
Optional führt die Funktion Dispatch() eine Überprüfung auf Nachrichtenduplikate beim Einsatz von mehreren IO-Geräten durch. Dazu wird eine implementierte [[#X_Fingerprint|Fingerprint]]-Funktion im physischen oder logischen Modul benötigt. Sollte der Fingerprint einer Nachricht innerhalb einer bestimmten Zeit (globales Attribut <code>dupTimeout</code>, standardmäßig 500ms) bereits empfangen worden sein, so wird die Nachricht verworfen. Dies ist insbesondere bei funkbasierter Hardware notwendig, wenn mehrere Empfänger die selbe Nachricht empfangen.<br />
<br />
=== Kommunikation von den logischen Modulen bis zur Hardware ===<br />
<br />
Um von einem logischen Modul eine Nachricht an die Hardware senden zu können, muss zunächst im logischen Gerät ein passenden IO-Gerät ausgewählt sein. Dazu muss die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] ein entsprechendes IO-Gerät auswählen und in <code>$hash->{IODev}</code> setzen. Dieser Aufruf wird üblicherweise in der [[#X_Define|Define]]-Funktion des logischen Moduls ausgeführt. Erst, wenn ein IO-Gerät ausgewählt wurde, können Daten über das physikalische Gerät an die Hardware übermittelt werden.<br />
<br />
Zum Senden von Daten ruft das logische Modul die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] samt Daten auf. Diese ruft für das entsprechende IO-Gerät die [[#X_Write|Write]]-Funktion auf und übergibt die Daten zum Schreiben an das physikalische Modul. Die Write-Funktion kümmert sich nun um die Übertragung der Daten an die Hardware. <br />
<br />
Keine direkten Zugriffe zwischen dem logischen und dem physischen Gerät gibt (d.h. keine direkten Aufrufe von Funktionen, kein direktes Überprüfen von <code>$hash</code>-Inhalten, ...), so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie bei der [[RFR_CUL|RFR]]-Funktionalität) oder mittels [[FHEM2FHEM]] im RAW-Modus zwei FHEM-Installationen verbunden werden und die logischen Geräte können dennoch kommunizieren.<br />
<br />
=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===<br />
<br />
Das logische Modul kann im Rahmen der [[#X_Parse|Parse]]-Funktion eine neue Gerätedefinition anlegen, sofern eine passende Definition nicht existieren sollte. Die Parse-Funktion gibt generell den Namen der logischen Gerätedefinition zurück, für welche die Nachricht verarbeitet wurde. Sollte keine passende Definition gefunden werden, so muss die Parse-Funktion folgenden Rückgabewert liefern (zusammenhängende Zeichenkette):<br />
<br />
UNDEFINED ''&lt;Namensvorschlag&gt;'' ''&lt;Modulname&gt;'' ''&lt;Define-Parameter&gt;''<br />
<br />
Sollte also bspw. im Rahmen der Parse-Funktion zu Modul X eine Nachricht nicht einer existierenden Gerätedefinition zugeordnet werden können, so muss ein Namensvorschlag erstellt werden der eine eindeutige Komponente wie bspw. eine Adresse/ID/Kanal-Nr enthält. In der Regel wird hier immer der Modulname zusammen mit der eindeutigen Komponente, durch einen Unterstrich getrennt, verwendet (Bsp: <code>X_4834</code>). Der Modulname ist in der Regel immer der, des eigenen Moduls. In besonderen Fällen kann man hier auch einen abweichenden Modulnamen angeben. Dies wird bspw. bei den [[PanStamp#FHEM-Module.2FDevice_Definition_Files|SWAP-Modulen]] eingesetzt. Als Define-Parameter müssen alle notwendigen Parameter angegeben werden, die beim Aufruf des <code>define</code>-Befehls notwendig sind, damit eine neu angelegte Gerätedefinition Nachrichten zu dieser eindeutigen Adresse Daten verarbeitet. Dazu muss mind. die eindeutige Adresse mitgegeben werden.<br />
<br />
Beispiel für FS20:<br />
<br />
UNDEFINED FS20_0ae42f8 FS20 0ae42 f8<br />
<br />
Sobald [[DevelopmentModuleAPI#Dispatch|Dispatch()]] einen solchen Rückgabewert von einer [[#X_Parse|Parse]]-Funktion erhält, wird diese Zeichenkette so wie sie ist via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] als Event für die Definition <code>global</code> getriggert.<br />
<br />
Sofern der Nutzer das Modul [[autocreate]] verwendet (definiert hat), kümmert sich dieses nun um das Anlegen einer entsprechenden Gerätedefinition. Es lauscht dabei auf generierte Events der Definition <code>global</code> via [[#X_Notify|Notify]]-Funktion. Der Nutzer kann dabei das Verhalten von autocreate durch entsprechende Parameter beeinflussen.<br />
<br />
Das Modul, für welches autocreate eine neue Definition anlegen möchte, kann das Verhalten durch entsprechende Parameter im Modul-Hash beeinflussen. Dabei gilt, dass gesetzte Attribute durch den Nutzer generell Vorrang haben. Die entsprechenden Parameter werden dabei im Rahmen der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
...<br />
<br />
$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",<br />
FILTER => "%NAME",<br />
GPLOT => "temp4hum4:Temp/Hum,",<br />
autocreateThreshold => "2:140"<br />
}<br />
};<br />
<br />
}<br />
</syntaxhighlight><br />
<br />
Hierbei wird unterhalb von <code>$hash->{AutoCreate}</code> eine Liste angelegt, wo einem regulären Ausdruck für einen anzulegenden Definitionsnamen entsprechende Optionen zugeordnet werden. Sobald durch autocreate eine Gerätedefintion angelegt wird, auf den ein hier gelisteter Ausdruck matcht, so werden die zugeordneten Optionen berücksichtigt.<br />
<br />
Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Optionsname !! Beispiel !! Bedeutung<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>ATTR</code>|| style="vertical-align:top; white-space: nowrap;" | <code>"event-on-change-reading:.* event-min-interval:.*:300"</code> || Eine Auflistung von Attributen, die nach dem Anlegen einer Definition zusätzlich gesetzt werden. Es handelt sich hierbei um eine Leerzeichen-separierte Liste von Doppelpunkt-getrennten Tupels mit Attributname und -wert.<br />
<br />
Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:<br />
<br />
attr ''&lt;Name&gt;'' event-on-change-reading .*<br />
attr ''&lt;Name&gt;'' event-min-interval .*:300<br />
<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>FILTER</code> || style="vertical-align:top; white-space: nowrap;" | <code>"%NAME"</code>|| Sofern in der autocreate-Definiton das Attribut <code>filelog</code> entsprechend durch den Nutzer gesetzt ist, wird eine zugehörige FileLog-Definition angelegt. Diese Option setzt den dabei benutzten Filter-Regexp, der beim Anlegen der FileLog-Definition gesetzt wird. <br />
<br />
Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:<br />
<br />
* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen<br />
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>GPLOT</code> || style="vertical-align:top; white-space: nowrap;" | <code>"temp4hum4:Temp/Hum,"</code> || Sofern eine FileLog-Definition angelegt wurde, kann man weiterführend dazu eine passende SVG-Definition erzeugen um Daten aus dem erzeugten FileLog zu visualisieren. Ein typischer Fall sind hierbei Temperatursensoren, wo es sinnvoll sein kann, einen passenden SVG-Plot mit Temperatur/Luftfeuchtigkeit direkt anzulegen.<br />
<br />
Es handelt sich hierbei um eine kommaseparierte Auflistung von gplot-Dateinamen und optionalen Label-Texten durch einen Doppelpunkt getrennt. Im genannten Beispiel entspricht <code>temp4hum4</code> der zu verwendenden GnuPlot-Datei und <code>Temp/Hum</code> dem zu verwendenden Label ([[SVG]] Attribut <code>label</code>). Das Label wird auch durch FileLog verwendet als Link-Text zum entsprechenden SVG Plot. Alternativ kann auch nur die entsprechende GnuPlot-Datei anegeben werden ohne Label. Für jede angegebene GnuPlot-Datei wird anschließend eine entsprechende SVG-Definition erzeugt mit der vorher erzeugten FileLog-Definition als Datenquelle.<br />
<br />
Der gesamte Inhalt der <code>GPLOT</code>-Option wird beim Anlegen einer FileLog-Definition dem Attribut <code>logtype</code> als Wert plus dem Text <code>text</code> zugewiesen. Daher muss der Inhalt der Option <code>GPLOT</code> immer mit einem Komma enden. <br />
<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>autocreateThreshold</code> || style="vertical-align:top; white-space: nowrap;"| <code>"2:10"</code> || Definiert, wie viele Aufrufe (im Bsp: <code>2</code>) von autocreate innerhalb welcher Zeit (im Bsp: <code>10</code> Sek.) stattfinden müssen, bevor die Gerätedefinition tatsächlich durch autocreate angelegt wird. Dadurch kann das ungewollte Anlegen von Geräten verhindert werden die tatsächlich nicht in Echt existieren. Aufgrund von Funkstörungen kann es durchaus zum ungewollten Anlegen einer Definition kommen. Diese Funktion lässt eine Definition erst zu wenn innerhalb einer vorgegeben Zeit eine Mindestzahl an Nachrichten eintrifft.<br />
<br />
Die erste Zahl stellt dabei die Mindestanzahl an Nachrichten dar. Die Zweite Zahl stellt die Zeit in Sekunden dar, in der die Mindestanzahl an Nachrichten erreicht werden muss um eine entsprechende Gerätedefinition anzulegen. <br />
<br />
Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.<br />
<br />
Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>noAutocreatedFilelog</code>|| style="vertical-align:top; white-space: nowrap;" | <code>1</code>|| Flag. Sofern gesetzt, wird keine FileLog- und ggf. SVG-Definition erzeugt. Selbst wenn der Nutzer durch entsprechende Attribute das Anlegen wünscht. Diese Option ist sinnvoll für Module bzw. Geräte die keine Readings erzeugen.<br />
|}<br />
<br />
== Ergänzende Hinweise ==<br />
Die Wahl der vorangestellten Nummer für den Dateinamen eines neuen Moduls hat keine Bedeutung mehr, es sei denn die Nummer ist 99. Module, die mit 99_ beginnen, werden von FHEM automatisch geladen. Module mit einer anderen Nummer nur wenn ein <code>define</code>-Befehl dafür sorgt, dass das Modul geladen wird.<br />
<br />
Wenn ein Modul Initialisierungsdaten benötigt, sollten diese im Modul selbst enthalten sein. Eine zusätzliche Datei oder sogar ein Unterverzeichnis mit mehreren Dateien ist bei FHEM nicht üblich und sollte bei Modulen, die mit FHEM ausgeliefert werden nur in Rücksprache mit Rudolf König angelegt werden, da sie sonst bei einem Update nicht verteilt werden.<br />
<br />
== Weitere Informationen ==<br />
Wenn man weitere Details wissen möchte, ist ein erster sinnvoller Schritt ein Blick in die Datei fhem.pl. Dort sieht man im Perl-Code wie die Module aufgerufen werden, was vorher passiert und was danach. Am Anfang der Datei (ca. ab Zeile 130) findet man beispielsweise eine Liste der globalen Variablen, die den Modulen zur Verfügung stehen sowie Details zu den wichtigen Hashes %modules und %defs. Wer mit Perl noch nicht so gut klar kommt, dem hilft eventuell ein Blick auf die Perldoc Website[http://perldoc.perl.org/] oder in das Perl-Buch seiner Wahl. Auch die FHEM {{Link2CmdRef}} sollte nicht unterschätzt werden. Es stehen oft mehr interessante Details auch für Modulentwickler darin als man zunächst vermuten könnte.<br />
<br />
<br />
== "Hello World" Beispiel ==<br />
<br />
98_Hello.pm<br />
<br />
<syntaxhighlight lang="perl"><br />
package main;<br />
use strict;<br />
use warnings;<br />
<br />
my %Hello_gets = (<br />
"whatyouwant" => "can't",<br />
"whatyouneed" => "try sometimes",<br />
"satisfaction" => "no"<br />
);<br />
<br />
sub Hello_Initialize($) {<br />
my ($hash) = @_;<br />
<br />
$hash->{DefFn} = 'Hello_Define';<br />
$hash->{UndefFn} = 'Hello_Undef';<br />
$hash->{SetFn} = 'Hello_Set';<br />
$hash->{GetFn} = 'Hello_Get';<br />
$hash->{AttrFn} = 'Hello_Attr';<br />
$hash->{ReadFn} = 'Hello_Read';<br />
<br />
$hash->{AttrList} =<br />
"formal:yes,no "<br />
. $readingFnAttributes;<br />
}<br />
<br />
sub Hello_Define($$) {<br />
my ($hash, $def) = @_;<br />
my @param = split('[ \t]+', $def);<br />
<br />
if(int(@param) < 3) {<br />
return "too few parameters: define <name> Hello <greet>";<br />
}<br />
<br />
my $hash->{name} = $param[0];<br />
my $hash->{greet} = $param[2];<br />
<br />
return undef;<br />
}<br />
<br />
sub Hello_Undef($$) {<br />
my ($hash, $arg) = @_; <br />
# nothing to do<br />
return undef;<br />
}<br />
<br />
sub Hello_Get($@) {<br />
my ($hash, @param) = @_;<br />
<br />
return '"get Hello" needs at least one argument' if (int(@param) < 2);<br />
<br />
my $name = shift @param;<br />
my $opt = shift @param;<br />
if(!$Hello_gets{$opt}) {<br />
my @cList = keys %Hello_gets;<br />
return "Unknown argument $opt, choose one of " . join(" ", @cList);<br />
}<br />
<br />
if($attr{$name}{formal} eq 'yes') {<br />
return $Hello_gets{$opt}.', sir';<br />
}<br />
return $Hello_gets{$opt};<br />
}<br />
<br />
sub Hello_Set($@) {<br />
my ($hash, @param) = @_;<br />
<br />
return '"set Hello" needs at least one argument' if (int(@param) < 2);<br />
<br />
my $name = shift @param;<br />
my $opt = shift @param;<br />
my $value = join("", @param);<br />
<br />
if(!defined($Hello_gets{$opt})) {<br />
my @cList = keys %Hello_gets;<br />
return "Unknown argument $opt, choose one of " . join(" ", @cList);<br />
}<br />
$hash->{STATE} = $Hello_gets{$opt} = $value;<br />
<br />
return "$opt set to $value. Try to get it.";<br />
}<br />
<br />
<br />
sub Hello_Attr(@) {<br />
my ($cmd,$name,$attr_name,$attr_value) = @_;<br />
if($cmd eq "set") {<br />
if($attr_name eq "formal") {<br />
if($attr_value !~ /^yes|no$/) {<br />
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";<br />
Log 3, "Hello: ".$err;<br />
return $err;<br />
}<br />
} else {<br />
return "Unknown attr $attr_name";<br />
}<br />
}<br />
return undef;<br />
}<br />
<br />
1;<br />
<br />
=pod<br />
=begin html<br />
<br />
<a name="Hello"></a><br />
<h3>Hello</h3><br />
<ul><br />
<i>Hello</i> implements the classical "Hello World" as a starting point for module development. <br />
You may want to copy 98_Hello.pm to start implementing a module of your very own. See <br />
<a href="http://wiki.fhem.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an <br />
in-depth instruction to your first module.<br />
<br><br><br />
<a name="Hellodefine"></a><br />
<b>Define</b><br />
<ul><br />
<code>define &lt;name&gt; Hello &lt;greet&gt;</code><br />
<br><br><br />
Example: <code>define HELLO Hello TurnUrRadioOn</code><br />
<br><br><br />
The "greet" parameter has no further meaning, it just demonstrates<br />
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a> <br />
for more info about the define command.<br />
</ul><br />
<br><br />
<br />
<a name="Helloset"></a><br />
<b>Set</b><br><br />
<ul><br />
<code>set &lt;name&gt; &lt;option&gt; &lt;value&gt;</code><br />
<br><br><br />
You can <i>set</i> any value to any of the following options. They're just there to <br />
<i>get</i> them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a> <br />
for more info about the set command.<br />
<br><br><br />
Options:<br />
<ul><br />
<li><i>satisfaction</i><br><br />
Defaults to "no"</li><br />
<li><i>whatyouwant</i><br><br />
Defaults to "can't"</li><br />
<li><i>whatyouneed</i><br><br />
Defaults to "try sometimes"</li><br />
</ul><br />
</ul><br />
<br><br />
<br />
<a name="Helloget"></a><br />
<b>Get</b><br><br />
<ul><br />
<code>get &lt;name&gt; &lt;option&gt;</code><br />
<br><br><br />
You can <i>get</i> the value of any of the options described in <br />
<a href="#Helloset">paragraph "Set" above</a>. See <br />
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about <br />
the get command.<br />
</ul><br />
<br><br />
<br />
<a name="Helloattr"></a><br />
<b>Attributes</b><br />
<ul><br />
<code>attr &lt;name&gt; &lt;attribute&gt; &lt;value&gt;</code><br />
<br><br><br />
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about <br />
the attr command.<br />
<br><br><br />
Attributes:<br />
<ul><br />
<li><i>formal</i> no|yes<br><br />
When you set formal to "yes", all output of <i>get</i> will be in a<br />
more formal language. Default is "no".<br />
</li><br />
</ul><br />
</ul><br />
</ul><br />
<br />
=end html<br />
<br />
=cut<br />
</syntaxhighlight><br />
<br />
Der HTML-Code zwischen den Tags <code>=pod</code> und <code>=cut</code> dient zur Generierung der commandref.html. Der HTML-Inhalt wird automatisch beim Verteilen des Moduls im Rahmen des Update-Mechanismus aus jedem Modul extrahiert und daraus die Commandref in verschiedenen Sprachen erstellt. Eine detaillierte Beschreibung wie ein Commandref-Abschnitt in einem Modul definiert wird, siehe: [[Guidelines zur Dokumentation]]<br />
<br />
<br />
[[Kategorie:Development]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=DevelopmentModuleIntro&diff=26266DevelopmentModuleIntro2018-03-25T11:47:54Z<p>Eisler: /* X_Set */</p>
<hr />
<div>{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}<br />
<br />
<br />
== Einleitung ==<br />
<br />
Um neue Geräte, Dienste, o.ä. in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben. Ein Modul wird in FHEM automatisch geladen, wenn ein entsprechendes Device in FHEM definiert wird. Das Modul ermöglicht eine spezifische Kommunikation mit einem physikalischen Gerät, stellt Ergebnisse ("Readings") und Events innerhalb von FHEM zur Verfügung und erlaubt es, das Gerät mit "Set"-/"Get"-Befehlen zu beeinflussen. Dieser Artikel soll den Einstieg in die Entwicklung eigener Module erleichtern.<br />
<br />
Mit dem FHEM-Befehl <code>define</code> werden Devices in FHEM basierend auf einem Modul definiert. Dieser Befehl sorgt dafür, dass ein neues Modul bei Bedarf geladen und initialisiert wird. Ein gutes Beispiel ist hierbei die zentrale Konfigurationsdatei "fhem.cfg" in der sämtliche Devices in Form von <code>define</code>-Statements gespeichert sind.<br />
<br />
Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:<br />
<br />
Ein Jeelink USB-Stick könnte beispielsweise mit dem Befehl <code>define JeeLink1 ''JeeLink'' /dev/ttyUSB0@57600</code> definiert werden.<br />
<br />
In fhem.pl wird der define-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und dann geladen. <br />
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''&lt;Modulname&gt;''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt.<br />
<br />
In der Initialisierungsfunktion des Moduls werden die Namen aller weiteren Perl-Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird für jedes Modul ein eigener Hash (genauer "Modul-Hash") mit entsprechenden Werten gefüllt, der in fhem.pl für jedes Modul entsprechend abgelegt wird. Dadurch weiß FHEM wie dieses Modul anzusprechen ist.<br />
<br />
== Grundlegender Aufbau eines Moduls ==<br />
<br />
=== Dateiname ===<br />
<br />
Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:<br />
<br />
:<code>''['''Schlüsselnummer''']''<font color="grey">_</font>''['''Modulname''']''<font color="grey">.pm</font></code><br />
<br />
* '''Schlüsselnummer''' - Eine zweistellige Zahl zwischen 00 - 99. Die Schlüsselnummer hat aktuell keine technische Relevanz mehr. In früheren FHEM-Versionen ist sie relevant für [[#Zweistufiges_Modell_f.C3.BCr_Module|zweistufige Module]] (Reihenfolge für [[DevelopmentModuleAPI#Dispatch|Dispatch()]] um logische Module zu prüfen). Die allgemeine Empfehlung ist hierbei eine Schlüsselnummer eines Moduls zu verwenden, welches eine ähnliche Funktionalität bietet. Die Schlüsselnummer 99 hat hierbei eine besondere Bedeutung, da alle Module mit dieser Schlüsselnummer beim Start von FHEM automatisch geladen werden, selbst, wenn sie in der Konfiguration nicht verwendet werden. Daher wird für myUtils 99 als Schlüsselnummer verwendet (99_myUtils.pm). Module mit der Schlüsselnummer 99 werden im SVN nicht akzeptiert (siehe [[SVN Nutzungsregeln]])<br />
* '''Modulname''' - Der Name des Moduls wie er in FHEM bei dem Anlegen einer Gerätedefinition zu verwenden ist. Der Modulname sollte nur aus den folgenden möglichen Zeichen bestehen: Groß-/Kleinbuchstaben, Zahlen sowie Unterstrich (_)<br />
<br />
=== Inhaltlicher Aufbau ===<br />
<br />
Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:<br />
<br />
<syntaxhighlight lang="perl"><br />
#<br />
# 72_MYMODULE.pm <br />
#<br />
<br />
package main;<br />
<br />
# Laden evtl. abhängiger Perl- bzw. FHEM-Module<br />
use HttpUtils;<br />
use [...]<br />
<br />
# FHEM Modulfunktionen<br />
<br />
sub MYMODULE_Initialize() {<br />
...<br />
}<br />
<br />
sub MYMODULE_Define() {<br />
...<br />
}<br />
<br />
...<br />
<br />
# Eval-Rückgabewert für erfolgreiches<br />
# Laden des Moduls<br />
1;<br />
<br />
<br />
# Beginn der Commandref<br />
<br />
=pod<br />
=item [helper|device|command]<br />
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt<br />
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt<br />
<br />
=begin html<br />
Englische Commandref in HTML<br />
=end html<br />
<br />
=begin html_DE<br />
Deustche Commandref in HTML<br />
=end html<br />
<br />
# Ende der Commandref<br />
=cut<br />
</syntaxhighlight><br />
<br />
Man kann hierbei von folgender Reihenfolge sprechen:<br />
<br />
# Perl-Code, welcher das Modul implementiert<br />
# Die Zeile <code>1;</code> nachdem der Perl-Code abgeschlossen ist. Dies dient FHEM der Erkennung, dass das Modul erfolgreich und vollständig geladen wurde. Sollte diese Zeile nicht enthalten sein, wird FHEM beim Laden des Moduls die Fehlermeldung <code>Error:Modul 72_MYMODULE deactivated</code> in das Logfile schreiben.<br />
# Commandref zur Dokumentation des Moduls. Diese Dokumentation soll dem User die möglichen Befehle/Attribute/Readings/Events vermitteln. Weitere Informationen und Hinweise findet man in den [[Guidelines zur Dokumentation]].<br />
<br />
== Der Hash einer Geräteinstanz ==<br />
Eine Besonderheit in Perl sind [http://de.wikipedia.org/wiki/Assoziatives_Array#Perl assoziative Arrays], (nicht ganz richtig als "Hash" bezeichnet) in denen die Adressierung nicht über eine Zählvariable erfolgt, sondern über einen beliebigen String. Die internen Abläufe bei der Adressierung führen dazu, dass die Speicherung in und der Abruf aus Hashes relativ langsam ist.<br />
<br />
Der zentrale Speicherort für Informationen einer Geräteinstanz bei FHEM ist ein solcher Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird. <br />
<br />
In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''&lt;Name&gt;''}</code> in fhem.pl verweist dabei auf den Hash der Geräteinstanz in Form einer Hashreferenz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben (i.d.R. als <code>$hash</code> bezeichnet), welche direkt von fhem.pl aufgerufen werden. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im Frontend als "Internals" angezeigt werden, sowie die Readings des Geräts. <br />
<br />
Beispiele:<br />
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz, <br />
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)<br />
<br />
==Ausführung von Modulen==<br />
FHEM arbeitet intern nicht parallel, sondern arbeitet alle Aufgaben seriell nacheinander kontinuierlich ab. Daher wäre es ungünstig, wenn Module Daten von einem physikalischen Gerät abfragen wollen und dabei innerhalb der selben Funktion auf die Antwort des Geräts warten. In dieser Zeit, in der FHEM auf die Antwort des Gerätes warten muss, wäre der Rest von FHEM blockiert. Da immer nur eine Aufgabe zur selben Zeit bearbeitet wird, müssen alle weiteren Aufgaben solange warten. Eine Datenkommunikation innerhalb eines Moduls sollte daher immer ohne Blockierung erfolgen. Dadurch kann FHEM die Wartezeit effizient für andere Aufgaben nutzen um bspw. anstehende Daten für andere Module zu verarbeiten. Es gibt in FHEM entsprechende Mechanismen, welche eine "Non-Blocking"-Kommunikation über verschiedene Wege (z.B. seriell, HTTP, TCP, ...) ermöglichen.<br />
<br />
Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sind. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet um Filedeskriptoren auf lesbare Daten zu überprüfen. In FHEM gibt es dazu eine Liste (<code>%selectlist</code>), in der die Filedeskriptoren sämtlicher Geräte (z.B. serielle Verbindung, TCP-Verbindung, etc.) gespeichert sind. <br />
<br />
In der zentralen Schleife (Main-Loop) von fhem.pl wird mit <code>select()</code> überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion ([[#X_Read|X_Read]]) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und verarbeitet. Anschließend wird die Schleife weiter ausgeführt.<br />
<br />
Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per <code>select()</code> überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion ([[#X_Ready|X_Ready]]) implementieren, welche prüft, ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt, beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.<br />
<br />
Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert um die Daten zu interpretieren und Werte in Readings geschrieben.<br />
<br />
Auch wenn von einem Anwender über einen Get-Befehl Daten aktiv von einem Gerät angefordert werden, sollte nicht blockierend gewartet werden. Eine asynchrone Ausgabe, sobald das Ergebnis vorliegt, ist über [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] möglich. Siehe {{Link2Forum|Topic=43771|Message=357870|LinkText=Beschreibung}} und {{Link2Forum|Topic=43771|Message=360935|LinkText=Beispiel}}. Weitere Anwendungsbeispiele finden sich im {{Link2Forum|Topic=43052|Message=353477|LinkText=PLEX Modul}} und im überarbeiteten und nicht-blockierenden {{Link2Forum|Topic=42771|Message=348498|LinkText=SYSSTAT Modul}}.<br />
<br />
== Wichtige globale Variablen aus fhem.pl ==<br />
<br />
FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Variable !! Beschreibung<br />
|-<br />
| <code>$init_done</code> || Dient der Erkennung für fhem.pl sowie den Modulen, ob FHEM den Initialisierungsvorgang abgeschlossen hat. Beim Starten von FHEM ist <code>$init_done</code> gleich <code>0</code>. Erst, wenn das Einlesen der Konfiguration, sowie des State-Files (Readings) abgeschlossen ist, wird <code>$init_done</code> auf <code>1</code> gesetzt.<br />
Das gleiche Verfahren wird auch bei dem Befehl <code>rereadcfg</code> angewandt. Während <code>rereadcfg</code> ausgeführt wird (Konfiguration löschen, neu einlesen), ist <code>$init_done</code> gleich <code>0</code>.<br />
<br />
Dies ist insbesondere in der [[#X_Define|Define]]-Funktion eines Moduls relevant. Durch eine Prüfung auf <code>$init_done</code> kann man erkennen, ob eine Definition von Hand (<code>$init_done</code> = 1) oder im Rahmen der Initialisierung (FHEM Start / Rereadcfg => <code>$init_done</code> = 0) erfolgte. Während der Initialisierung stehen bspw. die gesetzten Attribute der Definition noch nicht zur Verfügung und können daher nicht ausgewertet werden (siehe . <br />
|-<br />
| <code>%attr</code> || In <code>%attr</code> werden sämtliche gesetzten Attribute aller Geräte gespeichert. Diese Datenstruktur wird generell durch den <code>attr</code>-Befehl verwaltet. Hierbei wird einem Gerätenamen eine Mehrzahl an Attributnamen mit einem Wert zugeordnet. Attribut-Inhalte können über die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] ausgelesen werden.<br />
|-<br />
| <code>%cmds</code> || In <code>%cmds</code> wird jedem in FHEM existierendem Befehl die entsprechende Funktion zugewiesen, welche diesen Befehl umsetzt. Module können durch das Eintragen eines Befehlsnamen samt Funktion in <code>%cmds</code> über die [[#X_Initialize|Initialize]]-Funktion eines Moduls einen (oder mehrere) eigene Befehle in FHEM registrieren.<br />
<br />
Die Struktur ist dabei wiefolgt:<br />
<br />
$cmds{''&lt;Befehlsname&gt;''} = { Fn => "''&lt;Funktionsname&gt;''",<br />
Hlp => "''&lt;Aufrufsyntax&gt;''"};<br />
<br />
|-<br />
| <code>%data</code>|| Der eigentliche Zweck von <code>%data</code> ist dem Nutzer eine Möglichkeit zum Speichern von temporären Daten im globalen Kontext zu ermöglichen. Einige Module verwenden <code>%data</code> jedoch auch um modul- & geräteübergreifend Daten auszutauschen.<br />
|-<br />
| <code>%defs</code>|| In <code>%defs</code> werden sämtliche Gerätedefinitionen, bzw. die Hash-Referenzen auf diese, gespeichert. Hier ist jedem Gerätenamen eine Hash-Referenz zugeordnet.<br />
|-<br />
| <code>%modules</code>|| In <code>%modules</code> sind alle geladenen Module gelistet mit ihren entsprechenden Initialisierungsdaten (Funktionsnamen, Attribut-Listen, spezielle Einstellungen, ...). Hier wird für jeden Modulname der Modul-Hash aus der [[#X_Initialize|Initialize]]-Funktion gespeichert. <br />
Desweiteren legen viele Module, welche nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] hier eine Rückwärtszuordnung von Geräteadressen zu Geräte-Hash an.<br />
|-<br />
| <code>%readyfnlist</code>|| In <code>%readyfnlist</code> sind alle zu prüfenden Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte regelmäßig über eine Aufruf der entsprechenden [[#X_Ready|Ready]]-Funktion.<br />
<br />
Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%readyfnlist</code>.<br />
|-<br />
| <code>%selectlist</code>|| In <code>%selectlist</code> sind alle geöffneten Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte, ob der geöffnete Filedeskriptor unter <code>$hash->{FD}</code> Daten zum Lesen bereitgestellt hat. Ist dass der Fall, wird die entsprechende [[#X_Read|Read]]-Funktion aufgerufen, um anstehende Daten durch das Modul zu verarbeiten.<br />
Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%selectlist</code>.<br />
|}<br />
<br />
Es gibt durchaus viele weitere globale Variablen, die jedoch für sehr spezielle Anwendungsfälle und z.T. nur einzelne Module gedacht sind und daher hier nicht aufgeführt werden.<br />
<br />
== Internals ==<br />
Daten, die ein Modul im Geräte-Hash speichert nennt man Internals. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{NAME}</code> für den Gerätenamen, welcher beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Diese Daten spielen für FHEM eine sehr wichtige Rolle, da sämtliche gerätespezifischen Daten als Internal im Gerätehash gespeichert werden.<br />
<br />
Falls Werte wie z.B. ein Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollten, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen das Interval als Attribut über den Befehl <code>attr</code> gesetzt wird.<br />
<br />
Generell werden alle Werte, welche direkt in der ersten Ebene von <code>$hash</code> (Gerätehash) gespeichert werden auf der Detail-Seite einer Definition in der FHEMWEB Oberfläche angezeigt. Es gibt jedoch Ausnahmen:<br />
<br />
* <code>$hash->{helper}{URL}</code> - Alle Elemente, welche als Unterelement wieder einen Hash besitzen werden nicht in FHEMWEB dargestellt. Typischerweise speichern Module Daten unter <code>$hash->{helper}</code> interne Daten zwischen, die für den User nicht relevant sind, sondern nur der internen Verarbeitung dienen.<br />
* <code>$hash->{'''.'''<font color="grey">ELEMENT</font>}</code> - Alle Knoten, welche mit einem Punkt beginnen werden in der FHEMWEB Oberfläche nicht angezeigt. Man kann diese Daten jedoch beim Aufruf des [[List|list-Kommandos]] einsehen.<br />
<br />
Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:<br />
<br />
{| class="wikitable"<br />
|-<br />
! style="min-width: 13em;" | Internal !! Beschreibung<br />
|-<br />
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde. <br />
|-<br />
| <code>$hash->{READINGS}</code> || Enthält alle aktuell vorhandenen Readings. Daten unterhalb dieses Knotens sollte man nicht direkt manipulieren. Um Readings zu Erzeugen gibt es entsprechende [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]].<br />
|-<br />
| <code>$hash->{NR}</code> || Die Positions-Nr. der Definition innerhalb der Konfiguration. Diese dient dazu die Konfiguration in der gleichen Reihenfolge zu speichern, wie die einzelnen Geräte angelegt wurden.<br />
|-<br />
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.<br />
|-<br />
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.<br />
|-<br />
| <code>$hash->{CFGFN}</code> || Der Dateiname der Konfigurationsdatei in der diese Definition enthalten ist (sofern nicht in fhem.cfg). Dieser Wert ist nur gefüllt, wenn man mit mehreren Konfigurationsdateien arbeitet, welche dann in fhem.cfg via include-Befehl eingebunden werden.<br />
|-<br />
| <code>$hash->{NTFY_ORDER}</code> || Sofern das Modul Events via [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] verarbeitet enthält jede Definition eine Notify-Order als Zeichenkette bestehend aus dem Notify Order Prefix und dem Definitionsnamen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Reihenfolge für den Aufruf der Notify-Funktion beeinflussen".<br />
|-<br />
| <code>$hash->{NOTIFYDEV}</code> || Sofern das Modul Events via NotifyFn verarbeitet kann man damit die Definitionen, von denen man Events erhalten will begrenzen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Begrenzung der Aufrufe auf bestimmte Geräte".<br />
|-<br />
| <code>$hash->{IODev}</code> || Hier wird das zugeordnete IO-Gerät durch [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] gespeichert, welches für den Datentransport und -empfang dieses logischen Gerätes zuständig ist. Dieser Wert existiert nur bei Modulen die nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] arbeiten. <br />
|-<br />
| <code>$hash->{CHANGED}</code> || Hier werden alle Events kurzzeitig gesammelt, welche für die Eventverarbeitung anstehen. Insbesondere die [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] speichern hier alle Events zwischen um sie nach Abschluss via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] zu verarbeiten. <br />
|-<br />
| <code>$hash->{FD}</code> || Wenn die Definition eine Netzwerkverbindung oder serielle Schnittstelle geöffnet hat (z.B. via [[DevIo]]), so wird der entsprechende File-Deskriptor in diesem Internal gespeichert. Damit kann FHEM alle geöffneten Filedeskriptoren der entsprechenden Definition zuordnen um bei ankommenden Daten die Definition via [[DevelopmentModuleIntro#X_Read|Read-Funktion]] damit zu versorgen.<br />
|-<br />
| <code>$hash->{EXCEPT_FD}</code> || Ähnlich wie <code>$hash->{FD}</code>. Sofern die Definition in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> eingetragen ist und ein Fildeskriptor in diesem Internal gesetzt ist, wird bei einer auftretenden Exception bzw. Interrupt die [[DevelopmentModuleIntro#X_Except|Except]]-Funktion des entsprechenden Moduls aufgerufen um darauf zu reagieren.<br />
|}<br />
<br />
Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.<br />
<br />
== Readings ==<br />
Daten, welche von einem Gerät gelesen werden und in FHEM in einer für Menschen verständlichen Form zur Verfügung gestellt werden können, werden Readings genannt. Sie geben den Status des Gerätes wieder und erzeugen Events innerhalb von FHEM auf die andere Geräte reagieren können. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise <br />
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers<br />
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung<br />
<br />
Für den lesenden Zugriff auf Readings steht die Funktion <code>[[DevelopmentModuleAPI#ReadingsVal|ReadingsVal()]]</code> zur Verfügung. Ein direkter Zugriff auf die Datenstruktur sollte nicht vorgenommen werden.<br />
<br />
Readings werden im Statefile von FHEM automatisch auf der Festplatte zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen. Dadurch ist der letzte Status eines Gerätes vor einem Neustart nachvollziehbar.<br />
<br />
Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FHEMWEB nicht angezeigt und können somit als "Permanentspeicher" für kleinere Daten innerhalb des Moduls genutzt werden. Um größere Datenmengen permanent zu speichern sollte man jedoch die Funktion <code>[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]</code> verwenden.<br />
<br />
Zum Setzen von Readings sollen <br />
*bei Gruppen von Readings der Funktionsblock <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code> (mehrfach wiederholt), <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code><br />
*bei einzelnen Updates die Funktion <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> <br />
aufgerufen werden. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen, je nach Hardwareperformance, spürbare Last auf dem System (siehe [[DevelopmentModuleIntro#X_Notify|NotifyFn]]), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.<br />
<br />
Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:<br />
<br />
<syntaxhighlight lang="perl"><br />
readingsBeginUpdate($hash);<br />
readingsBulkUpdate($hash, $readingName1, $wert1 );<br />
readingsBulkUpdate($hash, $readingName2, $wert2 );<br />
readingsEndUpdate($hash, 1);<br />
</syntaxhighlight><br />
<br />
== Events ==<br />
<br />
FHEM verfügt über einen Event-Mechanismus um Änderungen verschiedenster Art an einzelne oder alle Definitionen mitzuteilen. Jedes Modul (und damit alle Definitionen dieses Moduls) können auf Events von FHEM selber (Definition <code>global</code>) oder von anderen Definitionen reagieren und dadurch selber aktiv werden. Ein Event wird innerhalb von FHEM als Zeichenkette behandelt.<br />
<br />
Events sind grundsätzlich immer definitionsbezogen. Das bedeutet, dass ein Event immer in Verbindung mit einem Definitionsnamen erzeugt wird. Jede Definition, welche ein Event verarbeitet, erhält den Definitions-Hash (<code>$hash</code>) der auslösenden Definition.<br />
<br />
Events werden typischerweise bei der Erstellung von Readings implizit für jedes einzelne Reading erzeugt. Es gibt jedoch auch Events die nichts mit Readings zu tun haben um anderweitige Änderungen bekannt zu geben.<br />
<br />
Eigene Events können in FHEM mit der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] erzeugt werden. Um auf Events in einem Modul reagieren zu können, muss eine [[#X_Notify|Notify]]-Funktion implementiert sein. Sobald ein oder mehrere Events für eine Definition getriggert werden, prüft FHEM, welche Definitionen über Events der auslösenden Definition informiert werden möchten. Diese werden dann nacheinander in einer bestimmten Reihenfolge durch Aufruf der [[#X_Notify|Notify]]-Funktion über anstehende Events in Kenntnis gesetzt. Es obliegt dann dem jeweiligen Modul, wie es auf die Events reagiert.<br />
<br />
=== globale Events ===<br />
<br />
Als "globale Events" werden alle Events bezeichnet, die durch die Definition <code>global</code> erzeugt werden. Es handelt sich hierbei um Events die Strukturänderungen in der Konfiguration, als auch systemweite Ereignisse zu FHEM selbst signalisieren.<br />
<br />
Hier eine kurze Zusammenfassung, welche Events durch <code>global</code> getriggert werden können:<br />
<br />
<u>Allgemeine Events:</u><br />
<br />
{| class="wikitable"<br />
|-<br />
! Event-Text !! Beschreibung.<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>INITIALIZED</code>''' || Der Start von FHEM ist abgeschlossen. Sämtliche Definitionen und Attribute wurden aus der Konfiguration (fhem.cfg oder configDB) eingelesen, sowie sämtliche Readings sind aus dem State-File eingelesen und stehen nun voll umfänglich zur Verfügung.<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>REREADCFG</code>''' || Die Konfiguration wurde erneut eingelesen. Dies bedeutet, es wurden alle Definitionen/Attribute/Readings aus FHEM entfernt und durch Einlesen der Konfiguration neu angelegt. (FHEM-Befehl: "rereadcfg")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>SAVE</code>''' || Die laufende Konfiguration soll gespeichert werden (in fhem.cfg oder configDB). Dieses Event wird '''VOR''' dem Speichern der Konfiguration getriggert. Sobald der Trigger verarbeitet wurde, beginnt das Speichern der Konfiguration. (FHEM-Befehl: "save")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>SHUTDOWN</code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>UPDATE</code>''' || Es wurde ein Update erfolgreich installiert. (FHEM-Befehl: "update")<br />
|}<br />
<br />
<u>Definitionsbezogene Events:</u><br />
<br />
{| class="wikitable"<br />
|-<br />
! Event-Text !! Beschreibung.<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>DEFINED ''<Name>''</code>''' || Es wurde eine neue Definition mit Namen <code>''<Name>''</code> angelegt. (FHEM-Befehl: "define")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>DELETED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde gelöscht. (FHEM-Befehl: "delete")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>RENAMED ''<Alt>'' ''<Neu>''</code>''' || Die Definition mit dem Namen <code>''<Alt>''</code> wurde in den Namen <code>''<Neu>''</code> umbenannt. (FHEM-Befehl: "rename")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>MODIFIED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde modifiziert. (FHEM-Befehl: "modify")<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | '''<code>UNDEFINED ''<Name> <Modul> <Define-Parameter>''</code>''' || Es wurde eine Nachricht von einem physikalischen Modul (siehe [[#Zweistufiges Modell für Module|zweistufiges Modulkonzept]]) erhalten, für die keine passende logische Definition in FHEM existiert. Details dazu, siehe dazu Abschnitt [[#Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)|Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)]].<br />
|}<br />
<br />
=== Begrenzung von Events ===<br />
<br />
Ein Modul, welches Events verarbeitet, kann die Eventverarbeitung auf bestimmte Definitionen begrenzen. Dadurch werden nur Events an das Modul gemeldet (via [[#X_Notify|X_Notify()]]), welche von einer oder mehreren bestimmten Definitionen getriggert wurden. Dadurch werden unnötige Events nicht an das Modul gemeldet und schont somit Ressourcen.<br />
<br />
Standardmäßig werden sämtliche Events ohne Begrenzung an ein Modul gemeldet, welches eine [[#X_Notify|Notify]]-Funktion implementiert hat und somit Events verarbeiten kann. Details zur Begrenzung von Events findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].<br />
<br />
=== Reihenfolge der Eventverarbeitung ===<br />
<br />
Ein getriggertes Event wird nacheinander gegen jede Definition geprüft, deren Modul eine [[#X_Notify|Notify]]-Funktion implementiert hat. Dies bedeutet, jede Definition wird nacheinander durch Aufruf der [[#X_Notify|Notify]]-Funktion mit dem Definitionshash der auslösenden Definition aufgerufen.<br />
<br />
Unter bestimmten Umständen kann es erforderlich sein, in diese Reihenfolge einzugreifen. Beispielsweise wenn das eigene Modul und deren Definitionen das Event als letztes oder erstes verarbeiten müssen. Ein Beispiel bietet hierbei das Modul [[dewpoint]], welches Events vor allen anderen Modulen verarbeiten muss.<br />
<br />
Details, wie man die Reihenfolge der Eventverarbeitung steuern kann, findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].<br />
<br />
== Attribute ==<br />
Damit der Nutzer das Verhalten einer einzelnen Gerätedefinition zur Laufzeit individuell anpassen kann, gibt es in FHEM für jede Definition sogenannte Attribute, welche mit dem Befehl <code>attr</code> gesetzt werden können.<br />
Diese stehen dann dem Modul unmittelbar zur Verfügung um das Verhalten während der Ausführung zu beeinflussen. Attribute werden zusammen mit dem <code>define</code>-Befehl der jeweiligen Definition beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben. Beim Neustart werden die entsprechenden Befehle ausgeführt um alle Definition inkl. Attribute wieder anzulegen. Zur Laufzeit werden Attribute in dem globalen Hash <code>%attr</code> mit dem Definitionsnamen als Index (<code>$attr{$name} = $value</code>) gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert. Generell sollte <code>%attr</code> nicht durch direkten Zugriff manipuliert/benutzt werden.<br />
<br />
Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.<br />
<br />
Welche Attribute ein Modul unterstützt muss in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen von <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten).<br />
<br />
Wenn beim Setzen von Attributen in einer Gerätedefinition entsprechende Werte geprüft werden sollen oder zusätzliche Funktionalitäten implementiert werden müssen, dann muss dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> (siehe unten) implementiert werden. Hier kann man bspw. einen Syntaxcheck für Attribut-Werte implementieren um ungültige Werte zurückzuweisen.<br />
<br />
== Modulfunktionen ==<br />
<br />
Damit fhem.pl ein Modul nutzen kann, muss dieses entsprechende Funktionen mit einer vorgegebenen Aufrufsyntax implementieren. Durch die Bekanntgabe dieser modulspezifischen Funktionen können Daten zwischen fhem.pl und einem Modul entsprechend ausgetauscht werden. Es gibt verschiedene Arten von Funktionen die ein Modul anbieten muss bzw. kann, je nach Funktionsumfang.<br />
<br />
=== Die wichtigsten Funktionen in einem Modul ===<br />
<br />
Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:<br />
<br />
{| class="wikitable"<br />
|-<br />
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung<br />
|-<br />
| [[#X_Initialize|X_Initialize]] || Initialisiert das Modul und gibt den Namen zusätzlicher Modulfunktionen bekannt, sowie modulspezifische Einstellungen. Wird direkt nach dem erfolgreichen Laden des Moduls durch fhem.pl aufgerufen.<br />
|}<br />
<br />
Die folgenden Funktionen sind die wichtigsten Funktionen, welche je nach Anwendungsfall zu implementieren sind. Es handelt sich hierbei um die wichtigsten Vertreter, welche in den meisten Modulen Verwendung finden. Nicht alle Funktionen machen jedoch in jedem Modul Sinn. Generell sollte auch hier bei jeder Funktion der Modulname vorangestellt werden um ein einheitliches Namensschema zu gewährleisten. Hier die wichtigsten Modulfunktionen:<br />
<br />
{| class="wikitable sortable"<br />
|-<br />
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable"| Kurzbeschreibung<br />
|-<br />
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.<br />
|-<br />
| [[#X_Undef|X_Undef]] || Wird im Rahmen des <code>delete</code>-Befehls, sowie <code>rereadcfg</code>-Befehl aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.<br />
|-<br />
| [[#X_Delete|X_Delete]] || Wird im Rahmen des beim <code>delete</code>-Befehls aufgerufen wenn das Gerät endgültig gelöscht wird um weiterführende Aktionen vor dem Löschen durchzuführen.<br />
|-<br />
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen<br />
|-<br />
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.<br />
|-<br />
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)<br />
|-<br />
| [[#X_Read|X_Read]] || Wird durch FHEM aufgerufen, wenn ein gelisteter Filedeskriptor in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> Daten zum Lesen bereitstellt.<br />
|-<br />
| [[#X_Ready|X_Ready]] || Wird unter Windows durch FHEM aufgerufen um zyklisch einen seriellen Filedeskriptor auf lesbare Daten zu prüfen. Unter Linux dient diese Funktion dem Wiederaufbau verlorener Verbindungen.<br />
|-<br />
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM<br />
|-<br />
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.<br />
|-<br />
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.<br />
|}<br />
<br />
Diese Funktionen werden in diesem Abschnitt genauer beschrieben.<br />
<br />
==== X_Initialize ====<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von fhem.pl nach dem Laden des Moduls aufgerufen und bekommt eine leere Hashreferenz für den Initialisierungsvorgang übergeben. <br />
<br />
Dieser Hash muss nun von X_Initialize mit allen modulrelevanten Funktionsnamen gefüllt werden. Anschließend wird dieser Hash durch fhem.pl im globalen Hash <code>%modules</code> gespeichert. <code>$modules{ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der für jedes Modul existiert und modulspezifische Daten wie bspw. die implementierten Modulfunktionen enthält. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls wie folgt:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{DefFn} = "X_Define";<br />
$hash->{UndefFn} = "X_Undef";<br />
$hash->{DeleteFn} = "X_Delete";<br />
$hash->{SetFn} = "X_Set";<br />
$hash->{GetFn} = "X_Get";<br />
$hash->{AttrFn} = "X_Attr";<br />
$hash->{ReadFn} = "X_Read";<br />
$hash->{ReadyFn} = "X_Ready";<br />
$hash->{NotifyFn} = "X_Notify";<br />
$hash->{RenameFn} = "X_Rename";<br />
$hash->{ShutdownFn} = "X_Shutdown";<br />
</syntaxhighlight><br />
<br />
Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub &lt;''Funktionsname''&gt;() { ... }</code> definiert ist, als Zeichenkette in <code>$hash</code> gesetzt werden. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden.<br />
Auf diese Weise können sämtliche modulspezifisch implementierten Funktionen wie <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> bzw. <code>$hash->{ParseFn}</code> usw. bekannt gemacht werden.<br />
<br />
Darüber hinaus sollten die vom Modul unterstützten Attribute definiert werden:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{AttrList} =<br />
"do_not_notify:1,0 " . <br />
"header " .<br />
$readingFnAttributes; <br />
</syntaxhighlight><br />
<br />
Die Auflistung aller unterstützten modulspezifischen Attribute erfolgt in Form einer durch Leerzeichen getrennten Liste in <code>$hash->{AttrList}}</code>. Es gibt in FHEM globale Attribute, die in allen Gerätedefinitionen verfügbar sind und nur modulspezifische Attribute die jedes Modul via <code>$hash->{AttrList}</code> über die eigene Initialize-Funktion setzt. In fhem.pl werden dann die entsprechenden Attributwerte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die [[#X_Attr|Attr]]-Funktion implementiert und in der Initialize-Funktion bekannt gemacht werden.<br />
<br />
Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann zusätzlich gemacht werden, wenn das Modul zum Setzen von Readings die Funktionen <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code> oder <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref zu {{Link2CmdRef|Anker=readingFnAttributes|Label=readingFnAttributes}}.<br />
<br />
<br />
<u>Nutzung von parseParams()</u><br />
<br />
Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modulautoren beim Parsen von Übergabeparametern, welche bei <code>define</code>, <code>get</code> und <code>set</code> Kommandos an die entsprechenden Modulfunktionen übergeben werden. Dadurch lassen sich auf einfache Weise insbesondere komplexe Parameter (wie bspw. Perl-Ausdrücke) sehr einfach parsen.<br />
<br />
Diese Zusatzfunktion kann man in der Initialize-Funktion einfach über folgenden Parameter für [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion modulweit aktivieren:<br />
<syntaxhighlight lang="perl">$hash->{parseParams} = 1;</syntaxhighlight><br />
Sobald es gesetzt ist wird automatisch durch fhem.pl <code>[[DevelopmentModuleAPI#parseParams|parseParams()]]</code> aufgerufen und die an die [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion übergebenen Parameter ändern sich wie weiter unten in den jeweiligen Funktionen beschrieben.<br />
<br />
==== X_Define ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ( $hash, $def ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Define-Funktion eines Moduls wird von FHEM aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Funktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.) oder einen [[#Pollen_von_Geräten|Status-Timer]] zu starten.<br />
Sie beginnt typischerweise mit:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ( $hash, $def ) = @_;<br />
my @a = split( "[ \t][ \t]*", $def );<br />
...<br />
</syntaxhighlight><br />
<br />
Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den die im <code>define</code>-Befehl übergebenen Parameter. Welche bzw. wie viele Parameter <br />
akzeptiert werden und welcher Syntax diese entsprechen müssen ist Sache dieser Funktion. Im obigen Beispiel wird die Argumentzeile <code>$def</code> in ein Array aufgeteilt (durch Leerzeichen/Tabulator getrennt) und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:<br />
<br />
<syntaxhighlight lang="perl"><br />
my $name = $a[0];<br />
my $module = $a[1];<br />
my $url = $a[2];<br />
my $inter = 300;<br />
<br />
if(int(@a) == 4) { <br />
$inter = $a[3]; <br />
if ($inter < 5) {<br />
return "interval too small, please use something > 5s, default is 300 seconds";<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerweise als Internals im Hash der Geräteinstanz gespeichert:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{url} = $url;<br />
$hash->{Interval} = $inter;<br />
</syntaxhighlight><br />
<br />
Sobald alle Parameter korrekt verarbeitet wurden, wird in der Regel die erste Verbindung zum Gerät aufgebaut. Je nach Art des Geräts kann das eine permanente Datenverbindung sein (z.B. serielle Schnittstelle oder TCP-Verbindung) oder das Starten eines regelmäßigen Timers, der zyklisch den Status z.B. via [[HttpUtils|HTTP]] ausliest.<br />
<br />
Sollten im Rahmen der Define-Funktion Syntax-Probleme der Übergabeparameter festgestellt werden oder es kann bspw. keine Verbindung aufgebaut werden, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn alle Übergabeparameter akzeptiert werden, darf <code>undef</code> zurückgegeben werden. Sobald eine Define-Funktion eine Fehlermeldung zurückmeldet, wird der define-Befehl durch FHEM zurückgewiesen und der User erhält die Fehlermeldung, welche die Define-Funktion produziert hat, als Ausgabe zurück.<br />
<br />
<br />
<u>Verfügbarkeit von Attributen</u><br />
<br />
Während die Define-Funktion ausgeführt wird, sollte man nicht davon ausgehen, dass alle vom Nutzer konfigurierten Attribute via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verfügbar sind. Attribute stehen in der Define-Funktion nur dann zur Verfügung, wenn FHEM sich nicht in der Initialisierungsphase befindet (globale Variable <code>$init_done</code> ist wahr; der Nutzer hat die Gerätedefinition modifiziert). Daher sollte man weiterführende Funktion, welche auf gesetzte Attribute angewiesen sind, nur dann in der Define-Funktion starten, wenn <code>$init_done</code> zutrifft.<br />
<br />
Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ( $hash, $def ) = @_;<br />
<br />
...<br />
<br />
$hash->{NOTIFYDEV} = "global";<br />
<br />
X_FunctionWhoNeedsAttr($hash) if($init_done);<br />
}<br />
<br />
sub X_Notify($$)<br />
{<br />
my ($own_hash, $dev_hash) = @_;<br />
my $ownName = $own_hash->{NAME}; # own name / hash<br />
<br />
return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled<br />
<br />
my $devName = $dev_hash->{NAME}; # Device that created the events<br />
my $events = deviceEvents($dev_hash, 1);<br />
<br />
if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))<br />
{<br />
X_FunctionWhoNeedsAttr($hash);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.<br />
<br />
<br />
<u>Nutzung von parseParams()</u><br />
<br />
Zum Aufteilen und Parsen von <code>$def</code> lässt sich die Funktion [[DevelopmentModuleAPI#parseParams|parseParams()]] verwenden um die einzelnen Argumente einfach zu parsen. Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird parseParams() automatisch aufgerufen und X_Define() ändert sich wie folgt:<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$$)<br />
{<br />
my ( $hash, $a, $h ) = @_;<br />
...<br />
</syntaxhighlight><br />
<br />
Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.<br />
<br />
==== X_Undef ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Undef ($$)<br />
{<br />
my ( $hash, $name ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
Die Undef-Funktion wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird oder bei der Abarbeitung des Befehls <code>rereadcfg</code>, der ebenfalls alle Geräte löscht und danach das Konfigurationsfile neu einliest. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das Entfernen von internen Timern, sofern diese im Modul zum Pollen verwendet wurden (siehe Abschnitt [[#Pollen_von_Geräten|Pollen von Geräten]]). <br />
<br />
Zugewiesene Variablen im Hash der Geräteinstanz, Internals oder Readings müssen hier nicht gelöscht werden. In fhem.pl werden die entsprechenden Strukturen beim Löschen der Geräteinstanz ohnehin vollständig gelöscht.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Undef($$) <br />
{ <br />
my ( $hash, $name) = @_; <br />
DevIo_CloseDev($hash); <br />
RemoveInternalTimer($hash); <br />
return undef; <br />
}<br />
</syntaxhighlight><br />
<br />
Sollten im Rahmen der Undef-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn die Undef-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht bzw. neu angelegt. Sollte die Undef-Funktion jedoch eine Fehlermeldung zurückgeben, wird der entsprechende Vorgang (<code>delete</code> bzw. <code>rereadcfg</code>) für dieses Gerät abgebrochen. Es bleibt dann unverändert in FHEM bestehen.<br />
<br />
==== X_Delete ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Delete ($$)<br />
{<br />
my ( $hash, $name ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Delete-Funktion ist das Gegenstück zur Funktion [[#X_Define|X_Define]] und wird aufgerufen wenn ein Gerät mit dem Befehl <code>delete</code> gelöscht wird. <br />
<br />
Wenn ein Gerät in FHEM gelöscht wird, wird zuerst die Funktion [[#X_Undef|X_Undef]] aufgerufen um offene Verbindungen zu schließen, anschließend wird die Funktion X_Delete aufgerufen. Diese dient eher zum Aufräumen von dauerhaften Daten, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch dauerhafte Daten bspw. im physikalischen Gerät zu löschen die mit dieser Gerätedefinition zu tun haben.<br />
<br />
Dies kann z.B. folgendes sein:<br />
<br />
* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.<br />
* Lösen von evtl. Pairings mit dem physikalischen Gerät <br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Delete($$) <br />
{ <br />
my ( $hash, $name ) = @_; <br />
<br />
# Löschen von Geräte-assoziiertem Temp-File<br />
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)<br />
<br />
return undef;<br />
} <br />
</syntaxhighlight><br />
<br />
Sollten im Rahmen der Delete-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur die Delete-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht. Sollte die Delete-Funktion eine Fehlermeldung zurückgeben, wird der Löschvorgang abgebrochen und das Gerät bleibt weiter in FHEM bestehen.<br />
<br />
==== X_Get ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Get ($$@)<br />
{<br />
my ( $hash, $name, $opt, @args ) = @_;<br />
<br />
...<br />
<br />
return $result;<br />
}<br />
</syntaxhighlight><br />
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. In vielen Modulen wird auf diese Weise auch der Zugriff auf generierte Readings ermöglicht. Der Get-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des get-Befehls übergeben. Als Rückgabewert wird das Ergebnis des entsprechenden Befehls in Form einer Zeichenkette zurückgegeben. Der Rückgabewert <code>undef</code> hat hierbei keine besondere Bedeutung und wird behandelt wie eine leere Zeichenkette <code>""</code>.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Get($$@)<br />
{<br />
my ( $hash, $name, $opt, @args ) = @_;<br />
<br />
return "\"get $name\" needs at least one argument" unless(defined($opt));<br />
<br />
if($opt eq "status") <br />
{<br />
...<br />
}<br />
elsif($opt eq "power")<br />
{<br />
...<br />
}<br />
...<br />
else<br />
{<br />
return "Unknown argument $opt, choose one of status power [...]";<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax einhalten um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:<br />
<br />
<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code><br />
<br />
Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Get-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen. <br />
<br />
Beispiel:<br />
<ul><br />
<syntaxhighlight lang="perl">return "unknown argument $opt choose one of status temperature humidity";</syntaxhighlight><br />
<br />
Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:<br />
<br />
* <code>status</code><br />
* <code>temperature</code><br />
* <code>humidity</code><br />
<br />
Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:<br />
<br />
* <code>get ''&lt;NAME&gt;'' status</code><br />
* <code>get ''&lt;NAME&gt;'' temperature</code><br />
* <code>get ''&lt;NAME&gt;'' humidity</code><br />
</ul><br />
<br />
Die Ausgabe einer solchen Meldung ist sehr wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>get</code>-Optionen zu ermitteln und als Auswahl anzubieten. Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert direkt abfragen und diesen als Return-Wert der Get-Funktion zurückgeben.<br />
<br />
<br />
<u>Nutzung von parseParams()</u><br />
<br />
Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Get() ändert sich wie folgt:<br />
<syntaxhighlight lang="perl"><br />
sub X_Get($$$)<br />
{<br />
my ( $hash, $a, $h ) = @_;<br />
...<br />
</syntaxhighlight><br />
<br />
Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.<br />
<br />
==== X_Set ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Set ($$@)<br />
{<br />
my ( $hash, $name, $cmd, @args ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
return ($error, $skip_trigger);<br />
}<br />
</syntaxhighlight><br />
<br />
Die Set-Funktion ist das Gegenteil zur [[#X_Get|Get]]-Funktion. Sie ist dafür gedacht, Daten zum physischen Gerät zu schicken, bzw. entsprechende Aktionen im Gerät selber auszulösen. Ein Set-Befehl dient daher der direkten Steuerung des physikalischen Gerätes in dem es bspw. Zustände verändert (wie <code>on</code>/<code>off</code>). Der Set-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des set-Befehls übergeben. Als Rückgabewert kann eine Fehlermeldung in Form Zeichenkette zurückgegeben werden. Der Rückgabewert <code>undef</code> bedeutet hierbei, dass der Set-Befehl erfolgreich durchgeführt wurde. Eine Set-Funktion gibt daher nur im Fehlerfall eine Rückmeldung mit einer entsprechenden Fehlermeldung. Der Wert <code>undef</code> wird als "erfolgreich" interpretiert. <br />
<br />
Standardmäßig wird jeder Set-Befehl, welcher erfolgreich ausgeführt wurde (<code>$error</code> ist <code>undef</code>), als Event getriggert um dies bspw. in einem FileLog festzuhalten. Dieses Verhalten kann optional unterbunden werden indem der zweite Rückgabewert <code>$skip_trigger</code> auf <code>1</code> gesetzt wird. Damit wird das Generieren eines Events für das erfolgreich ausgeführte Set-Kommando unterbunden. Falls nicht gesetzt, wird ein Event erzeugt (<code>$cmd</code> mit sämtlichen <code>@args</code>).<br />
<br />
Rückmeldungen (Fehler) von set-Befehlen sämtlicher Module, die im Rahmen eines ausgeführten [[Notify]] auftreten werden im FHEM Logfile festgehalten.<br />
<br />
Falls nur interne Daten, die ausschließlich für das Modul relevant sind, gesetzt werden müssen, so sollte statt Set die [[#X_Attr|Attr]]-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht, da sie nur zur Steuerungszwecken im laufenden Betrieb von FHEM dienen.<br />
<br />
Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter übergeben um Zustände zu setzen. <br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Set($@)<br />
{<br />
my ( $hash, $name, $cmd, @args ) = @_;<br />
<br />
return "\"set $name\" needs at least one argument" unless(defined($cmd));<br />
<br />
if($cmd eq "status")<br />
{<br />
if($args[0] eq "up")<br />
{<br />
...<br />
}<br />
elsif($args[0] eq "down")<br />
{<br />
...<br />
}<br />
else<br />
{<br />
return "Unknown value $args[0] for $cmd, choose one of status power";<br />
} <br />
}<br />
elsif($cmd eq "power")<br />
{<br />
if($args[0] eq "on")<br />
{<br />
...<br />
}<br />
elsif($args[0] eq "off")<br />
{<br />
...<br />
} <br />
else<br />
{<br />
return "Unknown value $args[0] for $cmd, choose one of status power";<br />
} <br />
}<br />
...<br />
else<br />
{<br />
return "Unknown argument $cmd, choose one of status power";<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Wenn eine unbekannte Option an die Set-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Set-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:<br />
<br />
<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code><br />
<br />
Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Set-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen. <br />
<br />
Beispiel:<br />
<ul><br />
<syntaxhighlight lang="perl">return "unknown argument $cmd choose one of status power";</syntaxhighlight><br />
<br />
Hier werden als mögliche Optionen für einen Set-Befehl folgende Parameter angegeben:<br />
<br />
* <code>status</code><br />
* <code>power</code><br />
<br />
Dies würde in folgenden, mögliche Set-Befehle für einen User resultieren:<br />
<br />
* <code>set ''&lt;NAME&gt;'' status</code><br />
* <code>set ''&lt;NAME&gt;'' power</code><br />
</ul><br />
<br />
Die Ausgabe einer solchen Meldung ist sehr wichtig, da sie im Modul [[FHEMWEB]] verwendet wird um die möglichen <code>set</code>-Optionen zu ermitteln und als Auswahl anzubieten.<br />
<br />
<br />
<u>Nutzung von SetExtensions.pm</u><br />
<br />
Wenn man dem Nutzer zusätzlich zu den Set-Befehlen <code>on</code> und <code>off</code> auch weiterführende Befehle wie <code>on-for-timer</code>, <code>on-till</code>, usw. anbieten möchte, obwohl die zu steuernde Hardware solche Kommandos nicht unterstützt, kann man dies über das Hilfsmodul SetExtensions.pm realisieren.<br />
<br />
Das Hilfsmodul SetExtensions.pm bietet weiterführende Set-Kommandos basierend auf den Befehlen <code>on</code>/<code>off</code> an. Dabei werden durch interne Timer bzw. eigens angelegten [[at]]-Definitionen diese Befehle durch FHEM selber umgesetzt. Je nach ausgeführtem Befehl wird der <code>on</code>- bzw. <code>off</code>-Befehl dann durch FHEM zum richtigen Zeitpunkt ausgeführt. Vorausgesetzt das Modul unterstützt in der Set-Funktion die Befehle <code>on</code> und <code>off</code>, so werden durch den Einsatz von SetExtensions.pm folgende Befehle zusätzlich unterstützt:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Set-Kommando !! Beispiel !! Beschreibung<br />
|-<br />
| style="white-space: nowrap;" | <code>on-for-timer ''&lt;Dauer&gt;''</code> || style="white-space: nowrap;" | <code>on-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und nach der angegebenen Dauer in Sekunden via <code>off</code> wieder aus.<br />
|-<br />
| style="white-space: nowrap;" | <code>off-for-timer ''&lt;Dauer&gt;''</code> || style="white-space: nowrap;" | <code>off-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und nach der angegebenen Dauer in Sekunden via <code>on</code> wieder ein.<br />
|-<br />
| style="white-space: nowrap;" | <code>on-till ''&lt;Zeitpunkt&gt;''</code> || style="white-space: nowrap;" | <code>on-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und zum angegebenen Zeitpunkt via <code>off</code> wieder aus.<br />
|-<br />
| style="white-space: nowrap;" | <code>off-till ''&lt;Zeitpunkt&gt;''</code> || style="white-space: nowrap;" | <code>off-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und zum angegebenen Zeitpunkt via <code>on</code> wieder ein.<br />
|-<br />
| style="white-space: nowrap;" | <code>on-till-overnight ''&lt;Zeitpunkt&gt;''</code> || style="white-space: nowrap;" | <code>on-till-overnight 01:00</code> || Ähnlich wie <code>on-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.<br />
|-<br />
| style="white-space: nowrap;" | <code>off-till-overnight ''&lt;Zeitpunkt&gt;''</code> || style="white-space: nowrap;" | <code>off-till-overnight 01:00</code> || Ähnlich wie <code>off-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.<br />
|-<br />
| style="white-space: nowrap;" | <code>blink ''&lt;Anzahl&gt; &lt;Interval&gt;''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''&lt;Interval&gt;''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''&lt;Interval&gt;''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.<br />
|-<br />
| style="white-space: nowrap;" | <code>intervals ''&lt;Start&gt;-&lt;Ende&gt;'' ''&lt;Start&gt;-&lt;Ende&gt;'' ...</code> || style="white-space: nowrap;" | <code>intervals 07:00-08:00 16:30-18:00</code> || Schaltet das Gerät innerhalb der übergebenen Zeiträumen via <code>on</code> ein. Sobald die aktuelle Zeit ausserhalb dieser Zeiträume liegt, wird das Gerät via <code>off</code> wieder ausgeschaltet. Es können dabei beliebig viele Zeiträume angegeben werden.<br />
|-<br />
| style="white-space: nowrap;" | <code>toggle</code> || style="white-space: nowrap;" | <code>toggle</code> || Sofern der aktuelle Status <code>on</code> ist, wird das Gerät via <code>off</code> ausgeschaltet. Andernfalls wird es via <code>on</code> eingeschaltet.<br />
|}<br />
<br />
Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der commandref zum {{Link2CmdRef|Anker=set|Label=set-Befehl}}.<br />
<br />
Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:<br />
<br />
# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls<br />
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
use SetExtensions;<br />
<br />
...<br />
<br />
sub X_Set($@)<br />
{<br />
my ( $hash, $name, $cmd, @args ) = @_;<br />
my $cmdList = "on off";<br />
<br />
return "\"set $name\" needs at least one argument" unless(defined($cmd)));<br />
<br />
if($cmd eq "on")<br />
{<br />
# Gerät einschalten...<br />
}<br />
elsif($cmd eq "off")<br />
{<br />
# Gerät ausschalten...<br />
}<br />
...<br />
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()<br />
{<br />
return SetExtensions($hash, $cmdList, $name, $cmd, @args);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''&lt;Name&gt;'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.<br />
<br />
Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].<br />
<br />
<br />
<br />
<u>Nutzung von parseParams()</u><br />
<br />
Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Set() ändert sich wie folgt:<br />
<syntaxhighlight lang="perl"><br />
sub X_Set($$$)<br />
{<br />
my ( $hash, $a, $h ) = @_;<br />
...<br />
</syntaxhighlight><br />
<br />
Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.<br />
<br />
<br />
<u>Nutzung von FHEMWEB-Widgets</u><br />
<br />
Das GUI-Modul [[FHEMWEB]] kann für die einzelnen Set-Optionen, die das Modul versteht, automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht der GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknown ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt entsprechende Zusatzinformationen anhängen.<br />
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück. Das Modul FHEMWEB ermittelt die Syntax eines Gerätes jedoch immer mit dem Befehl:<br />
set ''&lt;NAME&gt;'' ?<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
return "Unknown argument $cmd, choose one of status:up,down power:on,off on:noArg off:noArg";<br />
</syntaxhighlight><br />
<br />
Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann<br />
<pre>timer:30,120,300<br />
mode:verbose,ultra,relaxed</pre><br />
<br />
Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.<br />
<br />
Man kann jedoch die Eingabe-/Auswahlmöglichkeiten durch Widgets vereinfachen. Dazu gibt man hinter dem Doppelpunkt einen Widgetnamen und widgetspezifische Parameter an. Es existieren mehrere solcher Widgets in FHEMWEB. Die gebräuchlichsten sind:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Zusatz !! Beispiel !! Beschreibung<br />
|-<br />
| '''noArg''' || <code>reset:noArg</code>|| Es werden keine weiteren Argumente mehr benötigt. In so einem Fall wird bei der Auswahl keine Textbox oder ähnliches angezeigt, da keine weiteren Argumente für diesen Befehl notwendig sind.<br />
|-<br />
| '''slider''',<min>,<step>,<max> || <code>dim:slider,0,1,100</code>|| Es wird ein Schieberegler angezeigt um den Parameter auszuwählen. Dabei werden als Zusatzparameter Minimum, Schrittweite und Maximum angegeben.<br />
|-<br />
| '''colorpicker''' || <code>rgb:colorpicker,RGB</code>|| Es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Die genaue Parametersyntax kann man dem Artikel zum [[Color#Colorpicker|Colorpicker]] entnehmen.<br />
|-<br />
| '''multiple''' || <code>group:multiple,Telefon,Multimedia,Licht,Heizung</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte durch klicken auswählen kann. Optional kann man in einem Freitext eigene Werte ergänzen. dieser Dialog wird bspw. bei der Raum-Auswahl (Attribut "room") oder der Gruppen-Auswahl (Attribut "group") in FHEMWEB genutzt. <br />
|-<br />
| '''sortable''' || <code>command:sortable,monday,tuesday,...</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte auswählen und sortieren kann. Man kann dabei Werte durch Klicken auswählen und durch Drag'n'Drop sortieren.<br />
|}<br />
<br />
Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der {{Link2CmdRef|Anker=widgetOverride}} unter widgetOverride zu FHEMWEB.<br />
<br />
'''Hinweise'''<br />
<br />
* Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet. <br />
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.<br />
<br />
==== X_Attr ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Attr ($$$$)<br />
{<br />
my ( $cmd, $name, $attrName, $attrValue ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Attr-Funktion dient der Prüfung von Attributen, welche über den <code>attr</code>-Befehl gesetzt werden können. Sobald versucht wird, ein Attribut für ein Gerät zu setzen, wird vorher die Attr-Funktion des entsprechenden Moduls aufgerufen um zu prüfen, ob das Attribut aus Sicht des Moduls korrekt ist.<br />
Liegt ein Problem mit dem Attribut bzw. dem Wert vor, so muss die Funktion eine aussagekräftige Fehlermeldung zurückgeben, welche dem User angezeigt wird.<br />
Sofern das übergebene Attribut samt Inhalt korrekt ist, gibt die Attr-Funktion den Wert <code>undef</code> zurück. Erst dann wird das Attribut in der globalen Datenstruktur <code>%attr</code> gespeichert und ist somit erst aktiv.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
X_Attr(@)<br />
{<br />
my ( $cmd, $name, $attrName, $attrValue ) = @_;<br />
<br />
# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen<br />
# $name - Gerätename<br />
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert<br />
<br />
if ($cmd eq "set") {<br />
if ($aName eq "Regex") {<br />
eval { qr/$aVal/ };<br />
if ($@) {<br />
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";<br />
return "Invalid Regex $aVal: $@";<br />
}<br />
}<br />
}<br />
return undef;<br />
}<br />
</syntaxhighlight><br />
<br />
Zusätzlich ist es möglich auch übergebene Attributwerte zu verändern bzw. zu korrigieren, indem man im Parameterarray <code>@_</code> den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 (entspricht dem 4. Element) im Parameterarray, also <code>$_[3]</code>.<br />
<br />
Da das Attribut zum Zeitpunkt des Aufrufs der Attr-Funktion noch nicht gespeichert ist, wird der neue Wert zu diesem Zeitpunkt noch nicht via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] zurückgegeben. Erst, wenn die Attr-Funktion mit <code>undef</code> beendet ist, wird der neue Wert in FHEM gespeichert und steht dann via AttrVal() zur Verfügung.<br />
<br />
Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie normalerweise keine Werte dort speichern muss, sondern lediglich das Attribut auf Korrektheit prüfen muss.<br />
Im obigen Beispiel wird für ein Attribut mit Namen "Regex" geprüft ob der reguläre Ausdruck fehlerhaft ist. Sofern dieser OK ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs in <code>%attr</code>.<br />
<br />
<br />
<u>Attributnamen mit Platzhaltern</u><br />
<br />
Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:<br />
<syntaxhighlight lang="perl"><br />
$hash->{AttrList} =<br />
"reading[0-9]*Name " .<br />
# usw.<br />
</syntaxhighlight><br />
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken in der Web-Oberfläche, da FHEMWEB nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muss solche Attribute manuell über den <code>attr</code>-Befehl eingeben.<br />
<br />
Man kann jedoch in der Attr-Funktion neu gesetzte Ausprägungen von Wildcard-Attributen an die gerätespezifische userattr-Variable anfügen. Dann können bereits gesetzte Attribute in FHEMWEB durch Klicken ausgewählt und geändert werden.<br />
Dazu reicht ein Aufruf der Funktion [[DevelopmentModuleAPI#addToDevAttrList|addToDevAttrList()]]: <br />
<br />
<syntaxhighlight lang="perl"><br />
addToDevAttrList($name, $aName);<br />
</syntaxhighlight><br />
<br />
==== X_Read ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Read ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
Die X_Read-Funktion wird aufgerufen, wenn ein dem Gerät zugeordneter Filedeskriptor (serielle Schnittstelle, TCP-Verbindung, ...) Daten zum Lesen bereitgestellt hat. Die Daten müssen nun eingelesen und interpretiert werden.<br />
<br />
Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Serial-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion [[DevIo#DevIo_SimpleRead()|DevIo_SimpleRead()]] gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.<br />
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten in einem eigenen Puffer (idealerweise in <code>$hash</code>) zwischenspeichern (siehe auch [[DevIo#Hinweis bei der Datenverarbeitung (Buffering)|DevIo]]). Im Beispiel ist dies <code>$hash->{helper}{BUFFER}</code> an den die aktuell gelesenen Daten angehängt werden, bis die folgende Prüfung ein für das jeweilige Protokoll vollständige Frame erkennt.<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# einlesen der bereitstehenden Daten<br />
my $buf = DevIo_SimpleRead($hash); <br />
return "" if ( !defined($buf) );<br />
Log3 $name, 5, "X ($name) - received data: ".$buf; <br />
<br />
# Daten in Hex konvertieren und an den Puffer anhängen<br />
$hash->{helper}{BUFFER} .= unpack ('H*', $buf); <br />
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};<br />
<br />
# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.<br />
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {<br />
...<br />
</syntaxhighlight><br />
<br />
Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{helper}{BUFFER}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und via [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] in Readings gespeichert werden (siehe unten).<br />
<br />
Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.<br />
<br />
==== X_Ready ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Ready ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
...<br />
<br />
return $success;<br />
}<br />
</syntaxhighlight><br />
<br />
Wird im Main-Loop aufgerufen falls das Modul in der globalen Liste <code>%readyfnlist</code> existiert. Diese Funktion hat, je nachdem auf welchem OS FHEM ausgeführt wird, unterschiedliche Aufgaben:<br />
<br />
* '''UNIX-artiges Betriebssystem:''' prüfen, ob eine Verbindung nach einem Verbindungsabbruch wieder aufgebaut werden kann. Sobald der Verbindungsaufbau erfolgreich war, muss die Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1") und den eigenen Eintrag entsprechend aus <code>%readyfnlist</code> löschen.<br />
* '''Windows-Betriebssystem:''' prüfen, ob lesbare Daten für ein serielles Device (via COM1, COM2, ...) vorliegen. Sofern lesbare Daten vorliegen, muss Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1"). Zusätzlich dazu muss die Funktion, wie bei UNIX-artigen Betriebssystem, ebenfalls bei einem Verbindungsabbruch einen neuen Verbindungsversuch initiieren. Der Eintrag in <code>%readyfnlist</code> bleibt solange erhalten, bis die Verbindung seitens FHEM beendet wird.<br />
<br />
Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.<br />
<br />
Bei der Nutzung des Moduls [[DevIo]] wird dem Modulentwickler der Umgang mit <code>%readyfnlist</code> abgenommen, da DevIo sich selbst um die entsprechenden Einträge kümmert und diese selbstständig wieder entfernt.<br />
<br />
In der Regel sieht eine Ready-Funktion immer gleich aus.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Ready($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.<br />
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );<br />
<br />
# This is relevant for Windows/USB only<br />
if(defined($hash->{USBDev})) {<br />
my $po = $hash->{USBDev};<br />
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;<br />
return ( $InBytes > 0 );<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Notify ====<br />
<br />
Die X_Notify-Funktion wird aus der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] in fhem.pl heraus aufgerufen sobald ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind dabei das [[FileLog]]-Modul oder das [[notify]]-Modul.<br />
<br />
Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, dass die Events erzeugt hat. <br />
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.<br />
Über den Hash des Gerätes und der [[DevelopmentModuleAPI#deviceEvents|deviceEvents()]]-Funktion kann man auf die generierten Events zugreifen. Über den zweiten Parameter dieser Routine lässt sich bestimmen ob für das Reading <code>state</code> ein 'normales' Event (d.h. in der form <code>state: <wert></code>) erzeugen soll (Wert: 1) oder ob z.b. aus Gründen der Rückwärtskompatibilität ein Event ohne <code>state: </code> erzeugt werden soll. Falls dem Anwender die Wahl des verwendeten Formats überlassen werden soll ist hierzu das {{Link2CmdRef|Anker=addStateEvent|Lang=de|Label=addStateEvent-Attribut}} vorzusehen.<br />
<br />
Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Notify($$)<br />
{<br />
my ($own_hash, $dev_hash) = @_;<br />
my $ownName = $own_hash->{NAME}; # own name / hash<br />
<br />
return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled<br />
<br />
my $devName = $dev_hash->{NAME}; # Device that created the events<br />
<br />
my $events = deviceEvents($dev_hash,1);<br />
return if( !$events );<br />
<br />
foreach my $event (@{$events}) {<br />
$event = "" if(!defined($event));<br />
<br />
# Examples:<br />
# $event = "readingname: value" <br />
# or<br />
# $event = "INITIALIZED" (for $devName equal "global")<br />
#<br />
# processing $event with further code<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
<u>Begrenzung der Aufrufe auf bestimmte Geräte</u><br />
<br />
Da die Notify-Funktion für jedes definierte Gerät mit all seinen Events aufgerufen wird, muss sie in einer Schleife jedesmal prüfen und entscheiden, ob es mit dem jeweiligen Event etwas anfangen kann. Ein Gerät, dass die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.<br />
<br />
Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer {{Link2CmdRef|Lang=de|Anker=devspec|Label=devspec}} in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eine der Definitionen, auf welche die devspec passt, ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":<br />
<br />
<syntaxhighlight lang="perl"><br />
in der Define-Funktion:<br />
<br />
$hash->{NOTIFYDEV} = "global";<br />
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";<br />
$hash->{NOTIFYDEV} = "global,TYPE=CUL_HM";<br />
</syntaxhighlight><br />
<br />
Dies schont insbesondere bei grossen Installationen Ressourcen, da die Notify-Funktion nicht sämtliche Events, sondern nur noch Events der gewünschten Definitionen erhält. Dadurch erfolgen deutlich weniger Aufrufe der Notify-Funktion, was Systemressourcen schont.<br />
<br />
Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code>&lt;Definitionsname&gt;</code> bzw. <code>&lt;Definitionsname&gt;:&lt;Event&gt;</code> reagiert, so sollte man in der Define-Funktion die Funktion [[DevelopmentModuleAPI#notifyRegexpChanged|notifyRegexpChanged()]] verwenden. Diese versucht einen passenden Eintrag für <code>$hash->{NOTIFYDEV}</code> basierend auf der übergebenen Regexp zu setzen, sofern dies möglich ist.<br />
<br />
<u>Reihenfolge für den Aufruf der Notify-Funktion beeinflussen</u><br />
<br />
Sobald ein Event ausgelöst wurde, stellt sich FHEM eine Liste aller relevanten Geräte-Hashes zusammen, welche via Notify-Funktion prüfen müssen, ob das Event relevant ist. Dabei wird die Liste nach <code>$hash->{NTFY_ORDER}</code> sortiert. Diese enthält ein Order-Präfix in Form einer Ganzzahl, sowie den Namen der Definition (Bsp: <code>'''50'''-Lampe_Wohnzimmer</code>). Dadurch kann man jedoch nicht sicherstellen, dass Events von bestimmten Modulen zuerst verarbeitet werden.<br />
<br />
Wenn das eigene Modul bei der Eventverarbeitung gegenüber den anderen Modulen eine bestimmte Reihenfolge einhalten muss, kann man in der [[#X_Initialize|Initialize]]-Funktion durch Setzen von <code>$hash->{NotifyOrderPrefix}</code> diese Reihenfolge beeinflussen. Standardmäßig werden Module immer mit einem Order-Präfix von "50-" in FHEM registriert. Durch die Veränderung dieses Präfixes kann man das eigene Modul in der Reihenfolge gegenüber anderen Modulen bei der Eventverarbeitung beeinflussen. <br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
...<br />
<br />
$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft<br />
<br />
# oder...<br />
<br />
$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft<br />
<br />
</syntaxhighlight> <br />
<br />
Da dieses Präfix bei eventverarbeitenden Definitionen in <code>$hash->{NTFY_ORDER}</code> dem Definitionsnamen vorangestellt wird bewirkt es bei einer normalen aufsteigenden Sortierung nach <code>$hash->{NTFY_ORDER}</code> eine veränderte Reihenfolge. Alle Module die in der Initialize-Funktion nicht <code>$hash->{NotifyOrderPrefix}</code> explizit setzen, werden mit "50-" als Standardwert vorbelegt.<br />
<br />
==== X_Rename ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Rename ($$)<br />
{<br />
my ( $new_name, $old_name) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Die Rename-Funktion wird ausgeführt, nachdem ein Gerät umbenannt wurde. Auf diese Weise kann ein Modul auf eine Namensänderung reagieren, wenn das Gerät <code>$old_name</code> in <code>$new_name</code> umbenannt wurde. Ein typischer Fall ist das Umsetzen der Namensänderungen bei Daten die mittels [[DevelopmentModuleAPI#setKeyValue|setKeyValue()]] gespeichert wurden. Hierbei müssen die Daten, welche unter dem alten Namen gespeichert sind, auf den neuen Namen geändert werden.<br />
<br />
Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Rename ($)<br />
{<br />
my ( $new_name, $old_name ) = @_;<br />
<br />
my $old_index = "Module_X_".$old_name."_data";<br />
my $new_index = "Module_X_".$new_name."_data";<br />
<br />
my ($err, $data) = getKeyValue($old_index);<br />
return undef unless(defined($old_pwd));<br />
<br />
setKeyValue($new_index, $data);<br />
setKeyValue($old_index, undef);<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Shutdown ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Shutdown ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
Mit der X_Shutdown Funktion kann ein Modul Aktionen durchführen bevor FHEM gestoppt wird. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.). Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_Shutdown($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# Verbindung schließen<br />
DevIo_CloseDev($hash);<br />
return undef;<br />
}<br />
</syntaxhighlight><br />
<br />
=== Funktionen für zweistufiges Modulkonzept ===<br />
<br />
Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:<br />
<br />
{| class="wikitable sortable"<br />
|-<br />
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung<br />
|-<br />
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.<br />
|-<br />
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.<br />
|-<br />
| [[#X_Fingerprint|X_Fingerprint]] || Rückgabe eines "Fingerabdrucks" einer Nachricht. Dient der Erkennung von Duplikaten im Rahmen von [[DevelopmentModuleAPI#Dispatch|Dispatch()]]. Kann im physischen, als auch logischen Modul benutzt werden.<br />
|}<br />
<br />
Für das zweistufige Modulkonzept muss in einem logischen Modul eine [[#X_Parse|Parse]]-Funktion im Modul-Hash registriert werden. In einem physikalischen Modul muss eine [[#X_Write|Write]]-Funktion registriert sein. Diese dienem dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.<br />
<br />
In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{ParseFn} = "X_Parse";<br />
$hash->{WriteFn} = "X_Write";<br />
$hash->{FingerprintFn} = "X_Fingerprint";<br />
</syntaxhighlight><br />
<br />
Diese Funktionen werden in diesem Abschnitt genauer beschrieben.<br />
<br />
==== X_Parse ====<br />
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font><br />
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''logisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit einem übergeordneten, physikalischen Modul austauscht.}}<br />
<syntaxhighlight lang="perl"><br />
sub X_Parse ($$)<br />
{<br />
my ( $io_hash, $message) = @_;<br />
<br />
...<br />
<br />
return $found;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Funktion X_Parse wird aufgerufen, sobald von dem IO-Gerät <code>$io_hash</code> eine Nachricht <code>$message</code> via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] zur Verarbeitung angefragt wird. Die Parse-Funktion muss dann prüfen, zu welcher Gerätedefinition diese Nachricht gehört und diese entsprechend verarbeiten.<br />
<br />
Üblicherweise enthält eine Nachricht immer eine Komponente durch welche sich die Nachricht einem Gerät zuordnen lässt (z.B. Adresse, ID-Nummer, ...). Eine solche Identifikation sollte man im Rahmen der [[#X_Define|Define]]-Funktion im logischen Modul an geeigneter Stelle speichern, um in der Parse-Funktion eine einfache Zuordnung von Adresse/ID einer Nachricht zur entsprechenden Gerätedefinition zu haben. Dazu wird in der Regel im Modul-Hash im modulspezifischen Berreich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:<br />
<br />
<syntaxhighlight lang="perl"><br />
<br />
sub X_Define ($$)<br />
{<br />
my ( $hash, $def) = @_;<br />
my @a = split("[ \t][ \t]*", $def);<br />
my $name = $a[0];<br />
<br />
...<br />
<br />
# erstes Argument ist die eindeutige Geräteadresse<br />
my $address = $a[1];<br />
<br />
# Adresse rückwärts dem Hash zuordnen (für ParseFn)<br />
$modules{X}{defptr}{$address} = $hash;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Auf Basis dieses Definition Pointers kann die Parse-Funktion nun sehr einfach prüfen, ob für die empfangene Nachricht bereits eine entsprechende Gerätedefinition existiert. Sofern diese existiert, kann die Nachricht entsprechend verarbeitet werden. Sollte jedoch keine passende Gerätedefinition zu der empfangenen Nachricht existieren, so muss die Parse-Funktion den Gerätenamen "UNDEFINED" zusammen mit den Argumenten für einen <code>define</code>-Befehl zurückgeben, welcher ein passendes Gerät in FHEM anlegen würde (durch [[autocreate]]).<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
<br />
sub X_Parse ($$)<br />
{<br />
my ( $io_hash, $message) = @_;<br />
<br />
# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts<br />
my $address = substr($message, 10, 5); <br />
<br />
# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)<br />
if(my $hash = $modules{X}{defptr}{$address}) <br />
{<br />
... # Nachricht für $hash verarbeiten<br />
<br />
# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.<br />
return $hash->{NAME}; <br />
}<br />
else<br />
{<br />
# Keine Gerätedefinition verfügbar<br />
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE><br />
return "UNDEFINED X_".$address." X $address";<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Write ====<br />
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font><br />
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''physisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit untergeordneten logischen Modulen austauscht. }}<br />
<syntaxhighlight lang="perl"><br />
sub X_Write ($$)<br />
{<br />
my ( $hash, @arguments) = @_;<br />
<br />
...<br />
<br />
return $return;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Write-Funktion wird durch die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] aufgerufen, sobald eine logische Gerätedefinition Daten per IO-Gerät an die Hardware übertragen möchte. Dazu kümmert sich die Write-Funktion um die Übertragung der Nachricht in geeigneter Form an die verbundene Hardware. Als Argumente wird der Hash des physischen Gerätes übertragen, sowie alle weiteren Argumente, die das logische Modul beim Aufruf von IOWrite() mitgegeben hat. Im Normalfall ist das ein Skalar mit der zu sendenden Nachricht in Textform. Es kann aber auch sein, dass weitere Daten zum Versand notwendig sind (evtl. Schlüssel, Session-Key, ...). Daher ist die Parametersyntax einer zu schreibenden Nachricht via IOWrite-/Write-Funktion zwischen logischem und physikalischen Modul abzustimmen.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Write ($$)<br />
{<br />
my ( $hash, $message, $address) = @_;<br />
<br />
DevIo_SimpleWrite($hash, $address.$message, 2);<br />
<br />
return undef;<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Fingerprint ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Fingerprint($$)<br />
{<br />
my ( $io_name, $msg ) = @_;<br />
<br />
...<br />
<br />
return ( $io_name, $fingerprint );<br />
}<br />
</syntaxhighlight><br />
<br />
Die Fingerprint-Funktion dient der Erkennung von Duplikaten empfangener Nachrichten. Diese Funktion kann dabei sowohl im physischen, als auch im logischen Modul implementiert sein. Je nachdem auf welcher Ebene man für eine Nachricht einen Fingerprint bilden kann. <br />
<br />
Als Parameter wird der Name des IO-Geräts <code>$io_name</code> übergeben, sowie die Nachricht <code>$msg</code>, welche empfangen wurde. Nun muss aus dieser Nachricht ein eindeutiger Fingerprint gebildet werden. Dies bedeutet, dass alle variablen Inhalte, die aufgrund des Empfangs dieser Nachricht über unterschiedliche IO-Geräte enthalten sein können, entfernt werden müssen. Dies können bspw. Empfangsadressen von IO-Geräten sein oder Session-ID's die in der Nachricht enthalten sind. Alle Fingerprints sämtlicher Nachrichten, die innerhalb der letzten 500 Millisekunden (konfigurierbar via <code>global</code> Attribut <code>dupTimeout</code>) empfangen wurden, werden gegen diesen generierten Fingerprint getestet. Sollte innerhalb dieser Zeit bereits eine Nachricht mit diesem Fingerprint verarbeitet worden sein, so wird sie als Duplikat erkannt und nicht weiter verarbeitet. In diesem Fall gibt [[DevelopmentModuleAPI#Dispatch|Dispatch()]] den Namen der Gerätedefinition zurück, welche eine Nachricht mit dem selben Fingerprint bereits verarbeitet hat. Es erfolgt dann kein Aufruf der [[#X_Parse|Parse]]-Funktion.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Fingerprint($$)<br />
{<br />
my ( $io_name, $msg ) = @_;<br />
<br />
substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse<br />
substr( $msg, 4, 1, "-" ); # entferne Hop-Count<br />
<br />
return ( $io_name, $msg );<br />
}<br />
</syntaxhighlight><br />
<br />
Es wird zuerst, sofern implementiert, die Fingerprint-Funktion des physischen Moduls aufgerufen. Sollte sich hierdurch kein Duplikat erkennen lassen, wird die Fingerprint-Funktion jedes möglichen geladenen logischen Moduls aufgerufen, sofern implementiert. <br />
<br />
Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.<br />
<br />
=== FHEMWEB-spezifische Funktionen ===<br />
<br />
FHEMWEB bietet Modulautoren die Möglichkeit an durch spezielle Funktionsaufrufe in Modulen, eigene HTML-Inhalte zu verwenden. Dadurch können in Verbindung mit zusätzlichem JavaScript komplexe Dialoge/Inhalte/Steuermöglichkeiten dargestellt werden. <br />
<br />
Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]<br />
<br />
=== sonstige Funktionen ===<br />
<br />
In diesem Abschnitt werden weitere Funktionen behandelt die zum Teil aus FHEM, aber auch aus anderen Modulen aufgerufen werden. Sie sind dabei nur in speziellen Anwendungsfällen relevant. Hier eine Auflistung aller sonstigen Modulfunktionen:<br />
<br />
{| class="wikitable sortable"<br />
|-<br />
! Funktionsname !! class="unsortable" | Kurzbeschreibung<br />
|-<br />
| [[#X_DbLog_split|X_DbLog_split]] || Wird durch das Modul 93_DbLog.pm aufgerufen. Dient dem korrekten Split eines moduleigenen Events in Name/Wert/Einheit für die Nutzung einer Datenbank.<br />
|-<br />
| [[#X_Except|X_Except]]|| Wird aufgerufen, sobald ein ein geöffneter Filedescriptor in [[#Wichtige_globale_Variablen_aus_fhem.pl|<code>%selectlist</code>]], der unter <code>$hash->{EXCEPT_FD}</code> im Geräte-Hash gesetzt ist, einen Interrupt bzw. Exception auslöst.<br />
|-<br />
| [[#X_Copy|X_Copy]]|| Wird durch das Modul 98_copy.pm aufgerufen im Rahmen des <code>copy</code>-Befehls sobald ein Gerät kopiert wurde.<br />
|-<br />
| [[#X_State|X_State]]|| Wird aufgerufen im Rahmen des <code>setstate</code>-Befehls bevor der Status einer Gerätedefinition bzw. eines zugehörigen Readings gesetzt wird.<br />
|-<br />
| [[#X_AsyncOutput|X_AsyncOutput]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht die asynchrone Ausgabe von Daten via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an einen einzelnen verbundenen Client.<br />
|-<br />
| [[#X_ActivateInform|X_ActivateInform]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht das aktivieren des inform-Mechanismus zum senden von Events für einen einzelnen verbundenen Client.<br />
|-<br />
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorized|Authorized()]] um eine gewünschte Vorgangs-Art zu autorisieren.<br />
|-<br />
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.<br />
|}<br />
<br />
In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:<br />
<br />
<syntaxhighlight lang="perl"><br />
$hash->{DbLog_splitFn} = "X_DbLog_split";<br />
$hash->{ExceptFn} = "X_Except";<br />
$hash->{CopyFn} = "X_Copy";<br />
$hash->{AsyncOutputFn} = "X_AsyncOutput";<br />
$hash->{ActivateInformFn} = "X_ActivateInform";<br />
$hash->{StateFn} = "X_State";<br />
$hash->{AuthorizeFn} = "X_Authorize";<br />
$hash->{AuthenticateFn} = "X_Authenticate";<br />
</syntaxhighlight><br />
<br />
<br />
Diese Funktionen werden in diesem Abschnitt genauer beschrieben.<br />
==== X_DbLog_split ====<br />
<syntaxhighlight lang="perl"><br />
sub X_DbLog_split ($$)<br />
{<br />
my ( $event, $device_name ) = @_;<br />
<br />
...<br />
<br />
return ( $reading, $value, $unit );<br />
}<br />
</syntaxhighlight><br />
<br />
Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modulautor das Auftrennen von Events in den Reading-Namen, -Wert und der Einheit selbst steuern. Andernfalls nimmt DbLog diese Auftrennung selber mittels Trennung durch Leerzeichen sowie vordefinierten Regeln zu verschiedenen Modulen vor. Je nachdem, welche Readings man in seinem Modul implementiert, passt diese standardmäßige Trennung jedoch nicht immer.<br />
<br />
Der Funktion werden folgende Eingangsparameter übergeben:<br />
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)<br />
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)<br />
<br />
Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.<br />
<br />
Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:<br />
# Name des Readings (Bsp: <code>temperature</code>)<br />
# Wert des Readings (Bsp: <code>20.5</code>)<br />
# Einheit des Readings (Bsp: <code>°C</code>)<br />
<br />
Beispiel:<br />
<syntaxhighlight lang="perl"><br />
sub X_DbLog_splitFn($$)<br />
{<br />
my ($event, $device) = @_;<br />
my ($reading, $value, $unit);<br />
my $devhash = $defs{$device}<br />
<br />
if($event =~ m/temperature/) {<br />
$reading = 'temperature';<br />
$value = substr($event,12,4);<br />
$unit = '°C';<br />
} <br />
<br />
return ($reading, $value, $unit);<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Except ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Except ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Die X_Except-Funktion wird durch fhem.pl aufgerufen, wenn die Gerätedefinition <code>$hash</code> in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> aufgeführt ist und der Filedeskriptor in <code>$hash->{EXCEPT_FD}</code> eine Exception bzw. Interrupt auslöst. <br />
<br />
Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
use IO::File;<br />
<br />
...<br />
<br />
sub X_Except ($)<br />
{<br />
my ( $hash ) = @_;<br />
<br />
# Filehandle aus Filedescriptor erstellen<br />
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');<br />
seek($filehandle,0,0); <br />
<br />
# aktuellen Inhalt auslesen<br />
my $current_value = $filehandle->getline;<br />
<br />
if($current_value eq "1")<br />
{<br />
...<br />
}<br />
else<br />
{<br />
...<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Copy ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Copy ($)<br />
{<br />
my ( $old_name, $new_name ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Die X_Copy-Funktion wird durch das Modul [[copy]] aufgerufen nachdem ein Nutzer eine Gerätedefinition über den Befehl <code>copy</code> kopiert hat. Dazu werden als Funktionsparameter die Definitionsnamen der alten und neuen Gerätedefinition übergeben. Es dient dazu zusätzliche Daten aus der zu kopierenden Gerätedefinition in die neue Definition zu übernehmen. Der Befehl <code>copy</code> überträgt lediglich <code>$hash->{DEF}</code> in die neue Definition sowie sämtliche gesetzte Attribute. Weitere Daten müssen dann durch die X_Copy-Funktion übertragen werden. <br />
<br />
Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.<br />
<br />
Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
<br />
sub X_Copy ($$)<br />
{<br />
my ( $old_name, $new_name ) = @_;<br />
<br />
my $old_hash = $defs{$old_name};<br />
my $new_hash = $defs{$new_name};<br />
<br />
# copy also temporary session key<br />
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_AsyncOutput ====<br />
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}<br />
<syntaxhighlight lang="perl"><br />
sub X_AsyncOutput ($)<br />
{<br />
my ( $client_hash, $text ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Funktion X_AsyncOutput wird durch [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] von anderen Modulen aufgerufen. Es erlaubt diesen anderen Modulen die Ausgabe von asynchronen Befehlsergebnissen <code>$text</code> zuvor ausgeführter set-/get-Befehle an den entsprechenden Client (identifiziert durch den Client-Hash <code>$client_hash</code> der temporären Definition) zurückzugeben. <br />
<br />
Wenn ein Client einen set-/get-Befehl ausführt, wird der Client-Hash bei der Ausführung dieser Befehle an die jeweiligen Module übermittelt. Sobald ein Befehl ausgeführt wird, der seine Ausgabe asynchron ausführen möchte und die Client-Verbindung des Server-Moduls dies unterstützt (<code>$client_hash->{canAsyncOutput}</code> ist gesetzt), merkt sich das befehlsausführende Modul den Client-Hash und gibt das Ergebnis des Befehls zu späterer Zeit via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an den ursprünglichen Client zurück. Die Funktion X_AsyncOutput des Server-Moduls kümmert sich darum das Ergebnis dem entsprechenden Client in der notwendigen Form zuzustellen.<br />
<br />
Der Rückgabewert von X_AsyncOutput() wird als Rückgabewert für asyncOutput() verwendet. Man kann hier im Fehlerfall eine Fehlermeldung angeben und im Erfolgsfall <code>undef</code>. Der Rückgabewert wird aber aktuell nicht ausgewertet.<br />
<br />
==== X_ActivateInform====<br />
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}<br />
<syntaxhighlight lang="perl"><br />
sub X_ActivateInform($$)<br />
{<br />
my ( $client_hash, $arg ) = @_;<br />
<br />
...<br />
}<br />
</syntaxhighlight><br />
<br />
Die Funktion X_ActivateInform wird aktuell nur durch den [[update]]-Befehl aufgerufen, sofern ein Client eines Frontend-Moduls diesen Befehl aufgerufen hat um den Inform-Mechanismus (Senden von Events) zu aktivieren. Dadurch wird im Falle von [[update]] die umgehende Anzeige der Logmeldungen für den ausführenden Client aktiviert. In [[FHEMWEB]] geschieht das über den Event-Monitor, bei telnet mit der direkten Ausgabe.<br />
<br />
Da diese Funktion aktuell nur speziell für den update-Befehl implementiert ist, kann man aktuell keine genaue Angaben zu den möglichen Werten von <code>$arg</code> geben. Dieser Parameter dient dazu genauer zu spezifizieren was exakt an Events an den entsprechenden Client <code>$client_hash</code> zu senden ist. Aktuell wird dazu die Parametersyntax des inform-Befehls verwendet (on|off|log|raw|timer|status).<br />
<br />
==== X_State ====<br />
<syntaxhighlight lang="perl"><br />
sub X_State($$$$)<br />
{<br />
my ( $hash, $time, $readingName, $value ) = @_;<br />
<br />
...<br />
<br />
return $error;<br />
}<br />
</syntaxhighlight><br />
<br />
Die X_State-Funktion wird durch fhem.pl aufgerufen, sobald über den Befehl <code>setstate</code> versucht wird ein Wert für ein Reading oder den Status (<code>$hash->{STATE}</code>) einer Gerätedefinition zu setzen. Dieser Befehl wird primär beim Starten von FHEM aufgerufen sobald das State-File eingelesen wird. Je nachdem, ob im gegebenen Fall ein Reading oder der Definitionsstatus gesetzt wird, haben die Übergabeparameter verschiedene Werte:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus<br />
|-<br />
| <code>$hash</code> || colspan=2 align=center | Die Hashreferenz der betreffenden Gerätedefinition<br />
|-<br />
| <code>$time</code>|| Der Zeitstempel auf welchen das Reading <code>$readingName</code> gesetzt werden soll. Das Ergebnis entspricht dem Rückgabewert der Funktion || Der aktuelle Zeitstempel zum jetzigen Zeitpunkt.<br />
|-<br />
| <code>$readingName</code>|| Der Name des Readings, welches auf einen neuen Wert gesetzt werden soll. || Statischer Wert "STATE" um anzuzeigen, dass es sich um den Definitionsstatus handelt, welcher gesetzt werden soll (<code>$hash->{STATE}</code>).<br />
|-<br />
| <code>$value</code> || Den Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Den Wert, welchen die Gerätedefinition als Status annehmen soll.<br />
|}<br />
<br />
Wenn via <code>setstate</code> ein Reading gesetzt wird, kann die X_State-Funktion das Setzen dieses Readings durch die Rückgabe einer aussagekräftigen Fehlermeldung unterbinden. Sofern <code>undef</code> zurückgegeben wird, wird das entsprechende Reading auf den übergebenen Status gesetzt.<br />
<br />
Wenn via <code>setstate</code> der Definitionsstatus gesetzt wird, wird die X_State-Funktion erst nach dem Setzen des Status aufgerufen. Man kann dabei zwar eine Fehlermeldung zurückgeben, der Status wird aber dennoch übernommen. Die Fehlermeldung wird lediglich dem Nutzer angezeigt.<br />
<br />
Beispiel:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_State($$$$)<br />
{<br />
my ( $hash, $time, $readingName, $value ) = @_;<br />
<br />
return undef if($readingName "STATE" || $value ne "inactive");<br />
readingsSingleUpdate($hash, "state", "inactive", 1);<br />
return undef;<br />
}<br />
</syntaxhighlight><br />
<br />
==== X_Authorize ====<br />
<syntaxhighlight lang="perl"><br />
sub X_Authorize($$$$)<br />
{<br />
my ( $hash, $client_hash, $type, $arg ) = @_;<br />
<br />
...<br />
<br />
return $authorized;<br />
}<br />
</syntaxhighlight><br />
<br />
Die Authorize-Funktion wird von fhem.pl aufgerufen um zu erfragen, ob ein bestimmter Client <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf. Auf diese Weise können Module Einfluss nehmen, welcher User welche Funktionen in FHEM nutzen darf. Wenn ein Client eine Aktion ausführen möchte, werden alle Module, die eine Authorize-Funktion implementiert haben, gefragt, ob diese Aktion ausgeführt werden darf. Als Rückgabewert wird das Ergebnis der Überprüfung zurückgegeben, wobei <code>0</code> (unbekannt / nicht zuständig), <code>1</code> (erlaubt) oder <code>2</code> (verboten) zurückgegeben werden können.<br />
<br />
Es gibt aktuell folgende <code>$type</code>/<code>$arg</code> Kombinationen, mit denen die Authorize-Funktion aufgerufen werden:<br />
<br />
{| class="wikitable"<br />
|-<br />
! $type !! $arg !! Überschrift<br />
|- <br />
|rowspan="3" style="white-space: nowrap;" | <code>'''$type''' = "cmd"</code><br />
<br />
<br />
''Befehlsausführung''<br />
| style="white-space: nowrap;" | <code>'''$arg''' = "set Lampe on"</code> || Jeglicher FHEM-Befehl, der ausgeführt werden soll, wird in <code>$arg</code> hinterlegt, sodass innerhalb einer Authorize-Funktion der Befehl genauer geparst werden kann um zu entscheiden, ob dieser Befehl erlaubt ist, oder nicht.<br />
|-<br />
| style="white-space: nowrap;" | <code>'''$arg''' = "perl"</code> || Ausführen von Perl-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.<br />
<br />
Bsp: <code>{ReadingsVal("Lampe", "state", "off"}</code><br />
|-<br />
| style="white-space: nowrap;" | <code>'''$arg''' = "shell"</code> || Ausführen von Shell-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.<br />
<br />
Bsp: <code>"/opt/fhem/myScript.sh"</code><br />
|-<br />
|style="white-space: nowrap;" | <code>'''$type''' = "devicename"</code><br />
<br />
<br />
''Sichtbarkeit von Geräten/Definitionen'' <br />
|style="white-space: nowrap;" | <code>'''$arg''' = "Licht_Wohnzimmer"</code> || Sichtbarkeit des jeweiligen Gerät/Definition in FHEM. Dies bedeutet konkret die Auffindbarkeit im <code>list</code>-Befehl, sowie der Suche via [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wird eine solche Anfrage durch die Authorize-Funktion abgelehnt, ist das entsprechende Gerät bzw. Definition für den jeweiligen Client nicht sichtbar.<br />
|}<br />
<br />
==== X_Authenticate ====<br />
{{Link2Forum|Topic=72757|Message=644098}}<br />
<br />
== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==<br />
<br />
Ein Modul kann primär einen neuen FHEM-Befehl bereitstellen. Man spricht in so einem Fall nicht von einem Gerätemodul, sondern einem Befehlsmodul. Ein solches Befehlsmodul stellt nur einen einzelnen Befehl bereit, der dem Modulnamen entsprechen muss. Nur, wenn der Modulname dem Befehlsname entspricht, kann FHEM das Modul beim ersten Ausführen dieses unbekannten Befehls finden und nachladen.<br />
<br />
Der entsprechende Befehl wird dazu in der [[#X_Initialize|Initialize]]-Funktion im globalen Hash <code>[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|%cmds]]</code> registriert:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($$) {<br />
<br />
$cmds{X} = { Fn => "CommandX",<br />
Hlp => "<argument1> [optional_argument2], print something very useful",<br />
<br />
# optionaler Filter für Clientmodule als regulärer Ausdruck<br />
ClientFilter => "FHEMWEB"<br />
};<br />
}<br />
</syntaxhighlight><br />
<br />
Damit wird der neue Befehl <code>X</code> in FHEM registriert. Die Funktion mit dem Namen <code>CommandX</code> setzt diesen Befehl innerhalb des Moduls um. Desweiteren wird eine kurze Aufrufsyntax mitgegeben, welche beim Aufruf des <code>help</code>-Befehls dem Nutzer angezeigt wird um als Gedankenstütze zu dienen. Optional kann man mittels <code>ClientFilter</code> (regulärer Ausdruck für Modulnamen) die Ausführbarkeit nur auf bestimmte Client-Module (wie FHEMWEB oder telnet) beschränken. <br />
<br />
Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:<br />
<br />
<syntaxhighlight lang="Perl"><br />
sub CommandX($$)<br />
{<br />
my ($client_hash, $arguments) = @_;<br />
<br />
...<br />
<br />
return $output;<br />
}<br />
</syntaxhighlight><br />
<br />
Dabei werden der Befehlsfunktion zwei Parameter übergeben. Zuerst die Hash-Referenz des aufrufenden Clients (sofern manuell ausgeführt, ansonsten <code>undef</code>) zwecks Rechteprüfung via [[allowed|allowed-Definitionen]]. Anschließend folgen die Aufrufparameter als zusammenhängende Zeichenkette. Die Trennung der einzelnen Argumente obligt der Funktion (bspw. via [[DevelopmentModuleAPI#parseParams|parseParams()]]). Als Funktionsrückgabewert wird eine Ausgabemeldung erwartet, die dem Nutzer angezeigt werden soll.<br />
<br />
== Pollen von Geräten ==<br />
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion [[DevelopmentModuleAPI#InternalTimer|InternalTimer()]] verwenden um einen Funktionsaufruf zu einem späteren Zeitpunkt durchführen zu können. Man übergibt dabei den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, sowie den zu übergebenden Parameter. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.<br />
<br />
Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:<br />
<br />
<syntaxhighlight lang="perl"><br />
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash); <br />
</syntaxhighlight><br />
<br />
Alternativ kann man auch in der [[#X_Notify|Notify]]-Funktion auf das Event <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> reagieren und erst dort, den Timer anstoßen, sobald die Konfiguration komplett eingelesen wurde. Dies ist insbesondere notwendig, wenn man sicherstellen will, dass alle Attribute aus der Konfiguration gesetzt sind, sobald man einen Status-Update initiiert.<br />
<br />
In der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_GetUpdate($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
Log3 $name, 4, "X: GetUpdate called ...";<br />
<br />
...<br />
<br />
# neuen Timer starten in einem konfigurierten Interval.<br />
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);<br />
}<br />
</syntaxhighlight><br />
<br />
Innerhalb der Funktion kann man nun das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene [[#X_Read|Read]]-Funktion zu implementieren.<br />
<br />
Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]<br />
<br />
== Logging / Debugging ==<br />
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.<br />
<syntaxhighlight lang="perl"><br />
Log3 $name, 3, "X ($name) - Problem erkannt ...";<br />
</syntaxhighlight><br />
Eine genaue Beschreibung zu der Funktion inkl. Aufrufparameter findet man [[DevelopmentModuleAPI#Log3|hier]]. Es ist generell ratsam in der Logmeldung sowohl den Namen des eigenen Moduls zu schreiben, sowie den Namen des Geräts, welche diese Logmeldung produziert, da die Meldung, so wie sie ist, direkt in das Logfile wandert und es für User ohne diese Informationen schwierig ist, die Meldungen korrekt zuzuordnen.<br />
<br />
Die Funktion Log3() verwendet den Namen der Geräteinstanz um das <code>verbose</code>-Attribut zu prüfen. In der Regel wird bei Modulfunktionen jedoch immer nur der Gerätehash <code>$hash</code> übergeben. Um den Namen der Definition zu ermitteln ist es daher notwendig sich diesen aus dem Hash extrahieren:<br />
<br />
<syntaxhighlight lang="perl"><br />
my $name = $hash->{NAME};<br />
</syntaxhighlight><br />
<br />
Um für eine einzelne Geräteinstanz das Verbose-Level zu erhöhen, ohne gleich für das gesamte FHEM den globalen Verbose-Level zu erhöhen und damit alle Meldungen zu erzeugen, kann man den Befehl <br />
<code>attr <NAME> verbose</code> verwenden. Beispielsweise <code>attr Lichtschalter_Wohnzimmer verbose 5</code><br />
<br />
Logmeldungen sollten je nach Art und Wichtigkeit für den Nutzer in unterschiedlichen Loglevels erzeugt werden. Es gibt insgesamt 5 Stufen in denen geloggt werden kann. Standardmäßig steht der systemweite Loglevel (<code>global</code>-Attribut <code>verbose</code>) auf der Stufe 3. Die Bedeutung der jeweiligen Stufen ist in der {{Link2CmdRef|Lang=de|Anker=verbose}} beschrieben.<br />
<br />
Während der Entwicklung eines Moduls kann man für eigene Debug-Zwecke auch die Funktion [[DevelopmentModuleAPI#Debug|Debug()]] verwenden um schnell und einfach Debug-Ausgaben in das Log zu schreiben. Diese sollten in der endgültigen Fassung jedoch nicht mehr vorhanden sein. Sie dienen ausschließlich zum Debugging während der Entwicklung.<br />
<br />
Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].<br />
<br />
== Zweistufiges Modell für Module ==<br />
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts|Schematische Darstellung am Beispiel CUL]]<br />
Es gibt viele Geräte, welche die Kommunikation mit weiteren Geräten mit tlw. unterschiedlichen Protokollen ermöglichen. Das typischste Beispiel bietet hier der [[CUL]], welcher via Funk mit verschiedenen Protokollen weitere Geräte ansprechen kann (z.B. Aktoren, Sensoren, ...). Hier bildet ein Gerät eine Brücke durch die weitere Geräte in FHEM zugänglich gemacht werden können. Dabei werden über einen Kommunikationsweg (z.B. serielle Schnittstelle, TCP, ...) beliebig viele Geräte gesteuert. Typische Beispiele dazu sind:<br />
<br />
* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)<br />
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit<br />
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit<br />
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit<br />
<br />
Dabei wird die Kommunikation in 2 Stufen unterteilt:<br />
* physisches Modul - z.B. 00_CUL.pm - zuständig für die physikalische Kommunikation mit der Hardware. Empfangene Daten müssen einem logischen Modul zugeordnet werden.<br />
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.<br />
<br />
<u>physisches Modul</u><br />
<br />
Das physische Modul öffnet die Datenverbindung zum Gerät (z.B. CUL) und verarbeitet sämtliche Daten. Es kümmert sich um den Erhalt der Verbindung (bsp. durch Keep-Alives) und konfiguriert das Gerät so, dass eine Kommunikation mit allen weiteren Geräten möglich ist (bsp. Frequenz, Modulation, Kanal, etc.).<br />
<br />
Empfangene Nutzdaten werden als Zeichenkette über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.<br />
<br />
Das Modul stellt eine [[#Die_Match-Liste|Match-Liste]] bereit, anhand FHEM die Nachricht einem Modul zuordnen kann, sofern dieses noch nicht geladen sein sollte. Die Match-Liste enthält eine Liste von regulären Ausdrücken und ordnet diese einem Modul zu. Wenn eine Nachricht auf einen solchen regulären Ausdruck passt und das Modul noch nicht geladen ist, lädt FHEM dieses automatisch nach, zwecks Verarbeitung der Nachricht. <br />
<br />
Anhand einer bereitgestellten [[#Die_Client-Liste|Client-Liste]] (Auflistung von logischen Modulen) kann FHEM feststellen, welche logischen Module mit dem physischen Modul kommunizieren können. Nur die hier aufgelisteten, logischen Module werden beim Aufruf von [[DevelopmentModuleAPI#Dispatch|Dispatch()]] angesprochen.<br />
<br />
Das Modul stellt eine [[#X_Write|Write]]-Funktion zur Verfügung, über die logische Module Daten in beliebiger Form an die Hardware übertragen können. <br />
<br />
<u>logisches Modul</u><br />
<br />
Das logische Modul interpretiert die via Dispatch() übergebene Nachricht (Zeichenkette) durch eine bereitgestellte [[#X_Parse|Parse]]-Funktion und erzeugt entsprechende Readings/Events. Es stellt über <code>set</code>-/<code>get</code>-Kommandos Steuerungsmöglichkeiten dem Nutzer zur Verfügung.<br />
<br />
Es stellt FHEM einen [[#Der_Match-Ausdruck|Match-Ausdruck]] (regulärer Ausdruck) zur Verfügung anhand [[DevelopmentModuleAPI#Dispatch|Dispatch()]] ermitteln kann, ob die Nachricht durch das logische Modul verarbeitet werden kann. Nur Nachrichten, welche auf diesen Ausdruck passen, werden an das logische Modul weitergegeben (Aufruf [[#X_Parse|Parse]]-Funktion).<br />
<br />
=== Die Client-Liste ===<br />
<br />
Die Client-Liste ist eine Auflistung von Modulnamen (genauer: regulären Ausdrücken die auf Modulnamen passen) die in einem physischen Modul gesetzt ist. Damit wird definiert, mit welchen logischen Modulen das physikalische Modul kommunizieren kann. <br />
<br />
Eine Client-Liste ist eine Zeichenkette, welche aus allen logischen Modulnamen besteht. Die einzelnen Namen werden durch einen Doppelpunkt getrennt. Anstatt kompletter Modulnamen können auch reguläre Ausdrücke verwendet werden, die auf mehrere Modulnamen passen (z.B. <code>CUL_.*</code> um die logischen Module CUL_HM, CUL_MAX, etc. zu verwenden).<br />
<br />
Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:<br />
<br />
FS20:FHT.*:KS300:USF1000:BS:HMS:CUL_EM:CUL_WS:CUL_FHTTK:CUL_HOERMANN:ESA2000:CUL_IR:CUL_TX:Revolt:IT:UNIRoll:SOMFY:STACKABLE_CC:CUL_RFR:CUL_TCM97001:CUL_REDIRECT<br />
<br />
Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.<br />
<br />
Die Client-Liste hat generell folgende Funktion:<br />
* Die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur Module, welche in der Client-Liste enthalten sind, ob diese die Nachricht verarbeiten können (Prüfung via [[#Der Match-Ausdruck|Match-Ausdruck]])<br />
* Die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] prüft anhand sämtlicher Client-Listen in FHEM, welches IO-Gerät für ein logisches Gerät nutzbar ist.<br />
<br />
Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
...<br />
$hash->{Clients} = "FS20:KS300:FHT.*";<br />
}<br />
</syntaxhighlight><br />
<br />
Man kann die Client-Liste jedoch auch pro physikalisches Gerät setzen. Eine gesetzte Client-Liste in einem Gerät hat immer Vorrang vor der Liste im Modul-Hash. Eine gerätespezifische Client-Liste wird dann verwendet, wenn bspw. ein Gerät je nach Konfiguration nur bestimmte logische Module bedienen kann. Bspw. kann ein CUL je nach RF-Einstellungen FS20, uvm. oder nur HomeMatic bedienen. In einem solchen Fall wird die Client-Liste im Geräte-Hash gesetzt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ( $hash, $def ) = @_;<br />
...<br />
$hash->{Clients} = "CUL_HM";<br />
}<br />
</syntaxhighlight><br />
<br />
In vielen Modulen, welche nach dem zweistufigem Konzept arbeiten, beginnt und endet die Client-Liste mit einem Doppelpunkt. Dies ist ein historisches Überbleibsel, da der Prüfmechanismus die Client-Liste früher auf das Vorhandensein von <code>'''<u><font color="red">:</font></u>'''&lt;Modulname&gt;'''<u><font color="red">:</font></u>'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.<br />
<br />
=== Die Match-Liste ===<br />
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font><br />
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.<br />
<br />
Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:<br />
<br />
<syntaxhighlight lang="perl"><br />
my %matchListFHEMduino = (<br />
....<br />
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",<br />
....<br />
"13:IT" => "^(?-i)i......\$",<br />
);<br />
</syntaxhighlight><br />
<br />
Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}<br />
}}<br />
Die Match-Liste ordnet eine Nachrichtensyntax (regulärer Ausdruck) einem Modulnamen zu und wird in einem physikalischen Modul gesetzt. Sollte eine Nachricht vom physikalischen Gerät empfangen werden, die durch kein geladenes Modul verarbeitet werden kann ([[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur alle geladenen Module aus der [[#Die Client-Liste|Client-Liste), so wird über die Match-Liste geprüft, welches Modul diese Nachricht verarbeiten kann. Dieses Modul wird anschließend geladen und die Nachricht durch dieses verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.<br />
<br />
Diese Liste wird ausschließlich in der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion verwendet. Sollte keine passendes Modul, welches bereits geladen ist, zur Verarbeitung einer Nachricht gefunden werden, so wird mithilfe der Match-Liste aufgrund der vorliegenden Nachricht das entsprechende Modul ermittelt. Dieses Modul wird dann direkt geladen und die Nachricht wird via [[#X_Parse|Parse]]-Funktion verarbeitet.<br />
<br />
Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:<br />
<br />
<syntaxhighlight lang="perl"><br />
{<br />
"1:FS20" => "^81..(04|0c)..0101a001",<br />
"2:KS300" => "^810d04..4027a001",<br />
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."<br />
}<br />
</syntaxhighlight><br />
<br />
Das Sortierpräfix (<code><u>1:</u><font color="grey">FS20</font></code>) dient als Sortierhilfe um so die Reihenfolge der Prüfung festzulegen. Bei der Prüfung wird die Match-Liste mittels sort() nach dem Schlüssel (Sortierpräfix + Modulname) sortiert und die regulären Ausdrücke werden dann nacheinander getestet. Daher sollten die präzisesten Ausdrücke immer zuerst getestet werden, sofern es weniger präzise Ausdrücke in der Match-Liste gibt. Dabei ist zu beachten, dass der Sortierpräfix nicht nach numerischen Regeln sortiert wird, sondern zeichenbasierend.<br />
<br />
Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
...<br />
<br />
$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",<br />
"2:KS300" => "^810d04..4027a001",<br />
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };<br />
}<br />
</syntaxhighlight><br />
<br />
Man kann die Match-Liste, ähnlich wie bei der Client-Liste, auch pro physikalisches Gerät setzen. Dabei hat auch hier die Match-Liste eines Gerätes immer Vorrang vor der Match-Liste aus dem Modul-Hash:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Define($$)<br />
{<br />
my ($hash, $def) = @_;<br />
<br />
...<br />
<br />
$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };<br />
}<br />
</syntaxhighlight><br />
<br />
=== Der Match-Ausdruck ===<br />
<br />
Ein Match-Ausdruck wird in einem logischen Modul gesetzt und dient der Prüfung, ob eine Nachricht durch das eigene Modul via [[#X_Parse|Parse]]-Funktion verarbeitet werden kann. Es handelt sich hierbei um einen einzelnen regulären Ausdruck, den FHEM innerhalb der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion prüft. Nur wenn eine Nachricht via Dispatch() auf diesen Audruck matcht, wird die Parse-Funktion des eigenen Moduls aufgerufen um die Nachricht zu verarbeiten. <br />
<br />
Der Hintergrund, warum man den Aufruf mit einem solchen Ausdruck vorher abprüft, liegt in der Möglichkeit, dass ein physikalisches Modul mehrere unterschiedliche logische Module ansprechen kann. So kann FHEM jedes geladene Modul durch diesen Match-Ausdruck prüfen, ob es diese Nachricht verarbeiten kann. Erst, wenn alle geladenen Module, aufgrund einer Prüfung des Ausdrucks, die Nachricht nicht verarbeiten können, wird via [[#Die_Match-Liste|Match-Liste]] ermittelt, welches Modul geladen werden muss um die Nachricht zu verarbeiten. <br />
<br />
Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
...<br />
<br />
# Dieses Modul verarbeitet FS20 Nachrichten<br />
$hash->{Match} = "^81..(04|0c)..0101a001"; <br />
}<br />
</syntaxhighlight><br />
=== Die vollständige Implementierung ===<br />
<br />
Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.<br />
<br />
==== physisches Modul ====<br />
<br />
Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:<br />
<br />
* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.<br />
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).<br />
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.<br />
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.<br />
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.<br />
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.<br />
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.<br />
<br />
Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:<br />
<br />
* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können<br />
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.<br />
<br />
==== logisches Modul ====<br />
<br />
Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:<br />
<br />
* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.<br />
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])<br />
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.<br />
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.<br />
<br />
Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:<br />
<br />
* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.<br />
<br />
=== Kommunikation von der Hardware bis zu den logischen Modulen ===<br />
<br />
Die Gerätedefinition des physischen Moduls öffnet eine Verbindung zur Hardware (z.B. via [[DevIo]]). Die [[#X_Read|Read]]-Funktion wird bei anstehenden Daten aus der Hauptschleife von fhem.pl aufgerufen.<br />
<br />
Die Read-Funktion stellt dabei sicher, dass die Daten<br />
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und<br />
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)<br />
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.<br />
<br />
Die Funktion Dispatch() prüft alle geladenen Module aus der [[#Die_Client-Liste|Client-Liste]] des physikalischen Moduls nach möglichen logischen Modulen zur Verarbeitung. Alle zum Zeitpunkt geladenen Module, die in der Client-Liste aufgeführt sind, werden über den [[#Der_Match-Ausdruck|Match-Ausdruck]] geprüft, ob sie mit der Nachricht etwas anfangen können. Sollte bei einem logischen Modul der Match-Ausdruck passen, so wird die entsprechende [[#X_Parse|Parse]]-Funktion des logischen Moduls aufgerufen. Sofern keine passendes Modul gefunden wurde, um die Nachricht zu verarbeiten, wird in der [[#Die_Match-Liste|Match-Liste]] im Geräte- bzw. Modul-Hash der physischen Gerätedefinition nach dem passenden Modul gesucht. Sollte es darin ein Modul geben, was diese Art von Nachricht verarbeiten kann, so wird versucht dieses Modul zu laden um nun die Nachricht via Parse-Funktion zu verarbeiten. Es erfolgt in diesem Fall keine Vorprüfung durch den Match-Ausdruck.<br />
<br />
Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese<br />
* interpretiert die übergebene Nachricht,<br />
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,<br />
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,<br />
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.<br />
<br />
Sollte keine passende Gerätedefinition für die entsprechende Nachricht existieren (Adresse/ID/Kanal/...), wird der Gerätename "UNDEFINED" inkl. einem passenden <code>define</code>-Statement zurückgegeben, um die Definition durch [[autocreate]] erzeugen zu lassen.<br />
<br />
Es findet während der Verarbeitung einer Nachricht durch Dispatch()/Parse-Funktion keine sofortige Eventverarbeitung (via [[DevelopmentModuleAPI#Dispatch|DoTrigger()]]) statt, wenn die [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen verwendet werden.<br />
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )<br />
<br />
Die Funktion Dispatch() triggert das Event-Handling für das von der Parse-Funktion zurückgegebene logische Device selbstständig nach Abschluss der Parse-Funktion.<br />
<br />
Optional führt die Funktion Dispatch() eine Überprüfung auf Nachrichtenduplikate beim Einsatz von mehreren IO-Geräten durch. Dazu wird eine implementierte [[#X_Fingerprint|Fingerprint]]-Funktion im physischen oder logischen Modul benötigt. Sollte der Fingerprint einer Nachricht innerhalb einer bestimmten Zeit (globales Attribut <code>dupTimeout</code>, standardmäßig 500ms) bereits empfangen worden sein, so wird die Nachricht verworfen. Dies ist insbesondere bei funkbasierter Hardware notwendig, wenn mehrere Empfänger die selbe Nachricht empfangen.<br />
<br />
=== Kommunikation von den logischen Modulen bis zur Hardware ===<br />
<br />
Um von einem logischen Modul eine Nachricht an die Hardware senden zu können, muss zunächst im logischen Gerät ein passenden IO-Gerät ausgewählt sein. Dazu muss die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] ein entsprechendes IO-Gerät auswählen und in <code>$hash->{IODev}</code> setzen. Dieser Aufruf wird üblicherweise in der [[#X_Define|Define]]-Funktion des logischen Moduls ausgeführt. Erst, wenn ein IO-Gerät ausgewählt wurde, können Daten über das physikalische Gerät an die Hardware übermittelt werden.<br />
<br />
Zum Senden von Daten ruft das logische Modul die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] samt Daten auf. Diese ruft für das entsprechende IO-Gerät die [[#X_Write|Write]]-Funktion auf und übergibt die Daten zum Schreiben an das physikalische Modul. Die Write-Funktion kümmert sich nun um die Übertragung der Daten an die Hardware. <br />
<br />
Keine direkten Zugriffe zwischen dem logischen und dem physischen Gerät gibt (d.h. keine direkten Aufrufe von Funktionen, kein direktes Überprüfen von <code>$hash</code>-Inhalten, ...), so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie bei der [[RFR_CUL|RFR]]-Funktionalität) oder mittels [[FHEM2FHEM]] im RAW-Modus zwei FHEM-Installationen verbunden werden und die logischen Geräte können dennoch kommunizieren.<br />
<br />
=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===<br />
<br />
Das logische Modul kann im Rahmen der [[#X_Parse|Parse]]-Funktion eine neue Gerätedefinition anlegen, sofern eine passende Definition nicht existieren sollte. Die Parse-Funktion gibt generell den Namen der logischen Gerätedefinition zurück, für welche die Nachricht verarbeitet wurde. Sollte keine passende Definition gefunden werden, so muss die Parse-Funktion folgenden Rückgabewert liefern (zusammenhängende Zeichenkette):<br />
<br />
UNDEFINED ''&lt;Namensvorschlag&gt;'' ''&lt;Modulname&gt;'' ''&lt;Define-Parameter&gt;''<br />
<br />
Sollte also bspw. im Rahmen der Parse-Funktion zu Modul X eine Nachricht nicht einer existierenden Gerätedefinition zugeordnet werden können, so muss ein Namensvorschlag erstellt werden der eine eindeutige Komponente wie bspw. eine Adresse/ID/Kanal-Nr enthält. In der Regel wird hier immer der Modulname zusammen mit der eindeutigen Komponente, durch einen Unterstrich getrennt, verwendet (Bsp: <code>X_4834</code>). Der Modulname ist in der Regel immer der, des eigenen Moduls. In besonderen Fällen kann man hier auch einen abweichenden Modulnamen angeben. Dies wird bspw. bei den [[PanStamp#FHEM-Module.2FDevice_Definition_Files|SWAP-Modulen]] eingesetzt. Als Define-Parameter müssen alle notwendigen Parameter angegeben werden, die beim Aufruf des <code>define</code>-Befehls notwendig sind, damit eine neu angelegte Gerätedefinition Nachrichten zu dieser eindeutigen Adresse Daten verarbeitet. Dazu muss mind. die eindeutige Adresse mitgegeben werden.<br />
<br />
Beispiel für FS20:<br />
<br />
UNDEFINED FS20_0ae42f8 FS20 0ae42 f8<br />
<br />
Sobald [[DevelopmentModuleAPI#Dispatch|Dispatch()]] einen solchen Rückgabewert von einer [[#X_Parse|Parse]]-Funktion erhält, wird diese Zeichenkette so wie sie ist via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] als Event für die Definition <code>global</code> getriggert.<br />
<br />
Sofern der Nutzer das Modul [[autocreate]] verwendet (definiert hat), kümmert sich dieses nun um das Anlegen einer entsprechenden Gerätedefinition. Es lauscht dabei auf generierte Events der Definition <code>global</code> via [[#X_Notify|Notify]]-Funktion. Der Nutzer kann dabei das Verhalten von autocreate durch entsprechende Parameter beeinflussen.<br />
<br />
Das Modul, für welches autocreate eine neue Definition anlegen möchte, kann das Verhalten durch entsprechende Parameter im Modul-Hash beeinflussen. Dabei gilt, dass gesetzte Attribute durch den Nutzer generell Vorrang haben. Die entsprechenden Parameter werden dabei im Rahmen der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub X_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
...<br />
<br />
$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",<br />
FILTER => "%NAME",<br />
GPLOT => "temp4hum4:Temp/Hum,",<br />
autocreateThreshold => "2:140"<br />
}<br />
};<br />
<br />
}<br />
</syntaxhighlight><br />
<br />
Hierbei wird unterhalb von <code>$hash->{AutoCreate}</code> eine Liste angelegt, wo einem regulären Ausdruck für einen anzulegenden Definitionsnamen entsprechende Optionen zugeordnet werden. Sobald durch autocreate eine Gerätedefintion angelegt wird, auf den ein hier gelisteter Ausdruck matcht, so werden die zugeordneten Optionen berücksichtigt.<br />
<br />
Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Optionsname !! Beispiel !! Bedeutung<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>ATTR</code>|| style="vertical-align:top; white-space: nowrap;" | <code>"event-on-change-reading:.* event-min-interval:.*:300"</code> || Eine Auflistung von Attributen, die nach dem Anlegen einer Definition zusätzlich gesetzt werden. Es handelt sich hierbei um eine Leerzeichen-separierte Liste von Doppelpunkt-getrennten Tupels mit Attributname und -wert.<br />
<br />
Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:<br />
<br />
attr ''&lt;Name&gt;'' event-on-change-reading .*<br />
attr ''&lt;Name&gt;'' event-min-interval .*:300<br />
<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>FILTER</code> || style="vertical-align:top; white-space: nowrap;" | <code>"%NAME"</code>|| Sofern in der autocreate-Definiton das Attribut <code>filelog</code> entsprechend durch den Nutzer gesetzt ist, wird eine zugehörige FileLog-Definition angelegt. Diese Option setzt den dabei benutzten Filter-Regexp, der beim Anlegen der FileLog-Definition gesetzt wird. <br />
<br />
Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:<br />
<br />
* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen<br />
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>GPLOT</code> || style="vertical-align:top; white-space: nowrap;" | <code>"temp4hum4:Temp/Hum,"</code> || Sofern eine FileLog-Definition angelegt wurde, kann man weiterführend dazu eine passende SVG-Definition erzeugen um Daten aus dem erzeugten FileLog zu visualisieren. Ein typischer Fall sind hierbei Temperatursensoren, wo es sinnvoll sein kann, einen passenden SVG-Plot mit Temperatur/Luftfeuchtigkeit direkt anzulegen.<br />
<br />
Es handelt sich hierbei um eine kommaseparierte Auflistung von gplot-Dateinamen und optionalen Label-Texten durch einen Doppelpunkt getrennt. Im genannten Beispiel entspricht <code>temp4hum4</code> der zu verwendenden GnuPlot-Datei und <code>Temp/Hum</code> dem zu verwendenden Label ([[SVG]] Attribut <code>label</code>). Das Label wird auch durch FileLog verwendet als Link-Text zum entsprechenden SVG Plot. Alternativ kann auch nur die entsprechende GnuPlot-Datei anegeben werden ohne Label. Für jede angegebene GnuPlot-Datei wird anschließend eine entsprechende SVG-Definition erzeugt mit der vorher erzeugten FileLog-Definition als Datenquelle.<br />
<br />
Der gesamte Inhalt der <code>GPLOT</code>-Option wird beim Anlegen einer FileLog-Definition dem Attribut <code>logtype</code> als Wert plus dem Text <code>text</code> zugewiesen. Daher muss der Inhalt der Option <code>GPLOT</code> immer mit einem Komma enden. <br />
<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>autocreateThreshold</code> || style="vertical-align:top; white-space: nowrap;"| <code>"2:10"</code> || Definiert, wie viele Aufrufe (im Bsp: <code>2</code>) von autocreate innerhalb welcher Zeit (im Bsp: <code>10</code> Sek.) stattfinden müssen, bevor die Gerätedefinition tatsächlich durch autocreate angelegt wird. Dadurch kann das ungewollte Anlegen von Geräten verhindert werden die tatsächlich nicht in Echt existieren. Aufgrund von Funkstörungen kann es durchaus zum ungewollten Anlegen einer Definition kommen. Diese Funktion lässt eine Definition erst zu wenn innerhalb einer vorgegeben Zeit eine Mindestzahl an Nachrichten eintrifft.<br />
<br />
Die erste Zahl stellt dabei die Mindestanzahl an Nachrichten dar. Die Zweite Zahl stellt die Zeit in Sekunden dar, in der die Mindestanzahl an Nachrichten erreicht werden muss um eine entsprechende Gerätedefinition anzulegen. <br />
<br />
Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.<br />
<br />
Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.<br />
|-<br />
| style="vertical-align:top; white-space: nowrap;" | <code>noAutocreatedFilelog</code>|| style="vertical-align:top; white-space: nowrap;" | <code>1</code>|| Flag. Sofern gesetzt, wird keine FileLog- und ggf. SVG-Definition erzeugt. Selbst wenn der Nutzer durch entsprechende Attribute das Anlegen wünscht. Diese Option ist sinnvoll für Module bzw. Geräte die keine Readings erzeugen.<br />
|}<br />
<br />
== Ergänzende Hinweise ==<br />
Die Wahl der vorangestellten Nummer für den Dateinamen eines neuen Moduls hat keine Bedeutung mehr, es sei denn die Nummer ist 99. Module, die mit 99_ beginnen, werden von FHEM automatisch geladen. Module mit einer anderen Nummer nur wenn ein <code>define</code>-Befehl dafür sorgt, dass das Modul geladen wird.<br />
<br />
Wenn ein Modul Initialisierungsdaten benötigt, sollten diese im Modul selbst enthalten sein. Eine zusätzliche Datei oder sogar ein Unterverzeichnis mit mehreren Dateien ist bei FHEM nicht üblich und sollte bei Modulen, die mit FHEM ausgeliefert werden nur in Rücksprache mit Rudolf König angelegt werden, da sie sonst bei einem Update nicht verteilt werden.<br />
<br />
== Weitere Informationen ==<br />
Wenn man weitere Details wissen möchte, ist ein erster sinnvoller Schritt ein Blick in die Datei fhem.pl. Dort sieht man im Perl-Code wie die Module aufgerufen werden, was vorher passiert und was danach. Am Anfang der Datei (ca. ab Zeile 130) findet man beispielsweise eine Liste der globalen Variablen, die den Modulen zur Verfügung stehen sowie Details zu den wichtigen Hashes %modules und %defs. Wer mit Perl noch nicht so gut klar kommt, dem hilft eventuell ein Blick auf die Perldoc Website[http://perldoc.perl.org/] oder in das Perl-Buch seiner Wahl. Auch die FHEM {{Link2CmdRef}} sollte nicht unterschätzt werden. Es stehen oft mehr interessante Details auch für Modulentwickler darin als man zunächst vermuten könnte.<br />
<br />
<br />
== "Hello World" Beispiel ==<br />
<br />
98_Hello.pm<br />
<br />
<syntaxhighlight lang="perl"><br />
package main;<br />
use strict;<br />
use warnings;<br />
<br />
my %Hello_gets = (<br />
"whatyouwant" => "can't",<br />
"whatyouneed" => "try sometimes",<br />
"satisfaction" => "no"<br />
);<br />
<br />
sub Hello_Initialize($) {<br />
my ($hash) = @_;<br />
<br />
$hash->{DefFn} = 'Hello_Define';<br />
$hash->{UndefFn} = 'Hello_Undef';<br />
$hash->{SetFn} = 'Hello_Set';<br />
$hash->{GetFn} = 'Hello_Get';<br />
$hash->{AttrFn} = 'Hello_Attr';<br />
$hash->{ReadFn} = 'Hello_Read';<br />
<br />
$hash->{AttrList} =<br />
"formal:yes,no "<br />
. $readingFnAttributes;<br />
}<br />
<br />
sub Hello_Define($$) {<br />
my ($hash, $def) = @_;<br />
my @param = split('[ \t]+', $def);<br />
<br />
if(int(@param) < 3) {<br />
return "too few parameters: define <name> Hello <greet>";<br />
}<br />
<br />
my $hash->{name} = $param[0];<br />
my $hash->{greet} = $param[2];<br />
<br />
return undef;<br />
}<br />
<br />
sub Hello_Undef($$) {<br />
my ($hash, $arg) = @_; <br />
# nothing to do<br />
return undef;<br />
}<br />
<br />
sub Hello_Get($@) {<br />
my ($hash, @param) = @_;<br />
<br />
return '"get Hello" needs at least one argument' if (int(@param) < 2);<br />
<br />
my $name = shift @param;<br />
my $opt = shift @param;<br />
if(!$Hello_gets{$opt}) {<br />
my @cList = keys %Hello_gets;<br />
return "Unknown argument $opt, choose one of " . join(" ", @cList);<br />
}<br />
<br />
if($attr{$name}{formal} eq 'yes') {<br />
return $Hello_gets{$opt}.', sir';<br />
}<br />
return $Hello_gets{$opt};<br />
}<br />
<br />
sub Hello_Set($@) {<br />
my ($hash, @param) = @_;<br />
<br />
return '"set Hello" needs at least one argument' if (int(@param) < 2);<br />
<br />
my $name = shift @param;<br />
my $opt = shift @param;<br />
my $value = join("", @param);<br />
<br />
if(!defined($Hello_gets{$opt})) {<br />
my @cList = keys %Hello_gets;<br />
return "Unknown argument $opt, choose one of " . join(" ", @cList);<br />
}<br />
$hash->{STATE} = $Hello_gets{$opt} = $value;<br />
<br />
return "$opt set to $value. Try to get it.";<br />
}<br />
<br />
<br />
sub Hello_Attr(@) {<br />
my ($cmd,$name,$attr_name,$attr_value) = @_;<br />
if($cmd eq "set") {<br />
if($attr_name eq "formal") {<br />
if($attr_value !~ /^yes|no$/) {<br />
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";<br />
Log 3, "Hello: ".$err;<br />
return $err;<br />
}<br />
} else {<br />
return "Unknown attr $attr_name";<br />
}<br />
}<br />
return undef;<br />
}<br />
<br />
1;<br />
<br />
=pod<br />
=begin html<br />
<br />
<a name="Hello"></a><br />
<h3>Hello</h3><br />
<ul><br />
<i>Hello</i> implements the classical "Hello World" as a starting point for module development. <br />
You may want to copy 98_Hello.pm to start implementing a module of your very own. See <br />
<a href="http://wiki.fhem.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an <br />
in-depth instruction to your first module.<br />
<br><br><br />
<a name="Hellodefine"></a><br />
<b>Define</b><br />
<ul><br />
<code>define &lt;name&gt; Hello &lt;greet&gt;</code><br />
<br><br><br />
Example: <code>define HELLO Hello TurnUrRadioOn</code><br />
<br><br><br />
The "greet" parameter has no further meaning, it just demonstrates<br />
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a> <br />
for more info about the define command.<br />
</ul><br />
<br><br />
<br />
<a name="Helloset"></a><br />
<b>Set</b><br><br />
<ul><br />
<code>set &lt;name&gt; &lt;option&gt; &lt;value&gt;</code><br />
<br><br><br />
You can <i>set</i> any value to any of the following options. They're just there to <br />
<i>get</i> them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a> <br />
for more info about the set command.<br />
<br><br><br />
Options:<br />
<ul><br />
<li><i>satisfaction</i><br><br />
Defaults to "no"</li><br />
<li><i>whatyouwant</i><br><br />
Defaults to "can't"</li><br />
<li><i>whatyouneed</i><br><br />
Defaults to "try sometimes"</li><br />
</ul><br />
</ul><br />
<br><br />
<br />
<a name="Helloget"></a><br />
<b>Get</b><br><br />
<ul><br />
<code>get &lt;name&gt; &lt;option&gt;</code><br />
<br><br><br />
You can <i>get</i> the value of any of the options described in <br />
<a href="#Helloset">paragraph "Set" above</a>. See <br />
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about <br />
the get command.<br />
</ul><br />
<br><br />
<br />
<a name="Helloattr"></a><br />
<b>Attributes</b><br />
<ul><br />
<code>attr &lt;name&gt; &lt;attribute&gt; &lt;value&gt;</code><br />
<br><br><br />
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about <br />
the attr command.<br />
<br><br><br />
Attributes:<br />
<ul><br />
<li><i>formal</i> no|yes<br><br />
When you set formal to "yes", all output of <i>get</i> will be in a<br />
more formal language. Default is "no".<br />
</li><br />
</ul><br />
</ul><br />
</ul><br />
<br />
=end html<br />
<br />
=cut<br />
</syntaxhighlight><br />
<br />
Der HTML-Code zwischen den Tags <code>=pod</code> und <code>=cut</code> dient zur Generierung der commandref.html. Der HTML-Inhalt wird automatisch beim Verteilen des Moduls im Rahmen des Update-Mechanismus aus jedem Modul extrahiert und daraus die Commandref in verschiedenen Sprachen erstellt. Eine detaillierte Beschreibung wie ein Commandref-Abschnitt in einem Modul definiert wird, siehe: [[Guidelines zur Dokumentation]]<br />
<br />
<br />
[[Kategorie:Development]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=DevIo&diff=26254DevIo2018-03-24T10:05:01Z<p>Eisler: /* TCP/IP-Verbindung */</p>
<hr />
<div>{{Infobox Modul<br />
|ModPurpose=Dienstfunktionen für die Kommunikation per serieller Schnittstelle (USB/RS232), TCP/IP-Verbindung oder UNIX-Socket<br />
|ModType=u<br />
|ModForumArea=FHEM Development<br />
|ModTechName=DevIo.pm<br />
|ModOwner=rudolfkoenig ({{Link2FU|8|Forum}} / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])<br />
}}<br />
<br />
Das Modul [[DevIo]](.pm) ist für Modulentwickler gedacht, um Daten zwischen einem FHEM-Modul und bspw. einer seriellen Schnittstelle, einer TCP/IP-Verbindung oder einem UNIX-Socket auszutauschen. Es übernimmt dabei die gesamte Verbindungsverwaltung und Aufrechterhaltung innerhalb von FHEM und nimmt dem Modulentwickler daher die gesamte Verbindungsverwaltung (Aufbau, Initialisierung, Neu-Verbindung bei Abbruch, etc.) ab. Es berücksichtigt dabei Besonderheiten zwischen Unix-basierten Betriebssystemen und Windows.<br />
<br />
Es dient dabei lediglich dem Zweck einen Kommunikationskanal für eine Definition in FHEM zu etablieren und Daten darüber auszutauschen. Die Interpretation der empfangenen Daten obliegt dem Modul, welches die Verbindung via DevIo geöffnet hat. Die ausgetauschten Daten werden durch DevIo nicht verändert.<br />
<br />
= Allgemeine Funktionsweise =<br />
DevIo hat das Ziel eine besonders einfache Möglichkeit für Modulentwickler zu schaffen, um einen dauerhaften Kommunikationskanal mit einem Hardware- oder Netzwerk-Gerät bzw. Service zu etablieren. Um eine Verbindung aufzubauen muss zunächst die Gegenstelle bekannt sein. Dazu muss vor dem Verbindungsaufbau in dem Internal <code>$hash->{DeviceName}</code> der jeweiligen Definition das Ziel hinterlegt werden. Dies kann bspw. eine serielle Schnittstelle sein (z.B. "/dev/ttyUSB0" oder "COM1" unter Windows) oder eine TCP/IP-Gegenstelle (z.B. "192.168.1.100:1012") sein. Eine detaillierte Aufstellung der möglichen Verbindungsarten und deren Angabe in <code>$hash->{DeviceName}</code> gibt es im folgenden Kapitel [[#Unterstützte Verbindungsarten|Unterstützte Verbindungsarten]].<br />
<br />
Die Funktion [[#DevIo_OpenDev()|DevIo_OpenDev()]] baut dabei die entsprechende Verbindung für eine einzelne Definition in Form eines Filedeskriptors auf und registriert diesen in dem globalen Hash <code>%selectlist</code><ref name="selectlist">[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|Development Module Introduction]] - Wichtige globale Variablen aus fhem.pl</ref>. Sobald die Verbindung erfolgreich aufgebaut wurde, kann eine, durch den Modulautor mitgelieferte, Initialisierungs-Funktion ausgeführt werden, um die Kommunikation zu initialiseren (bspw. das Senden einer Authentifizierungs-/Loginsequenz oder aktivieren der Hardware, etc.).<br />
<br />
FHEM (respektive fhem.pl) prüft nun regelmäßig, ob Daten zum Lesen bereitstehen (also Daten empfangen wurden). Ist dies der Fall, so wird die [[DevelopmentModuleIntro#X_Read|X_Read()]]-Funktion des zugehörigen Moduls für die hinterlegte Definition aufgerufen. Hier können die Daten durch den Aufruf von [[#DevIo_SimpleRead()|DevIo_SimpleRead()]] nun eingelesen und verarbeitet werden. Das Senden von Daten ist durch den Aufruf von [[#DevIo_SimpleWrite()|DevIo_SimpleWrite()]] sehr einfach möglich.<br />
<br />
Sollte die Verbindung zusammenbrechen (USB-Gerät abgezogen, Gerät per Netzwerk nicht mehr erreichbar, etc.), so erkennt dies DevIo und registriert die Definition in <code>%readyfnlist</code><ref name="selectlist" />. FHEM führt nun regelmäßig die [[DevelopmentModuleIntro#X_Ready|X_Ready()]]-Funktion des zugehörigen Moduls<br />
aus um zu prüfen, ob die Verbindung wieder aufgebaut werden kann. Hier wird nun durch die Ausführung von [[#DevIo_OpenDev()|DevIo_OpenDev()]] versucht die Verbindung wieder herzustellen.<br />
<br />
Sobald die Verbindung nicht mehr benötigt wird, oder FHEM bspw. beendet wird, kann die Verbindung via [[#DevIo_CloseDev()|DevIo_CloseDev()]] sauber geschlossen werden.<br />
<br />
= Unterstützte Verbindungsarten = <br />
<br />
Die folgenden Verbindungsarten können via DevIo realisiert werden.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Verbindungsart !! Beispielangabe in<br><code>$hash->{DeviceName}</code> !! Beschreibung<br />
|-<br />
| style="vertical-align:top" | '''Serielle Schnittstelle'''<br />
| style="vertical-align:top" |<br />
* <code>/dev/ttyUSB0</code> <br />
* <code>/dev/ttyUSB0@9600</code><br />
* <code>/dev/ttyUSB0@9600,7,E,2</code><br />
* <code>/dev/ttyUSB0@directio</code><br />
* <code>COM1@9600</code><br />
|| <br />
Durch Angabe eines Geräts in Form eines Gerätepfad (UNIX-basierte Betriebssysteme) oder der Schnittstellenbezeichnung aus Windows kann eine serielle Verbindung geöffnet werden. Der Gerätename kann zusätzliche Angaben zu Baudrate, Datenbits, Parität und Stoppbits enthalten um die Verbindung entsprechend zu konfiguieren. Diese Angaben sind durch ein "@" getrennt an die Gerätebezeichnung angehangen:<br />
<br />
Schematische Syntax: <code>''<font color="grey"><Gerät></font>'''''@'''''<Baudrate>''''','''''<Datenbits>''''','''''<Parität>''''','''''<Stopbits></code><br />
<br />
* <code><Baudrate></code> - Eine gültige Taktfrequenz (Symbole pro Sekunde) mit der die Schnittstelle geöffnet werden soll (Beispiel: <code>9600</code>, <code>14400</code>, <code>115200</code>, ...)<br />
* <code><Datenbits></code> - Die Anzahl an Datenbits (7 oder 8 Datenbits). Standardwert sofern nicht angegeben sind 8 Datenbits.<br />
* <code><Parität></code> - Die zu verwendende Parität, sofern benötigt. Dabei bedeutet der Wert <code>N</code> keine Parität, <code>O</code> bedeutet ungleiche Parität (odd) und <code>E</code> bedeutet gleiche Parität (even) Standardwert sofern nicht angegeben ist <code>N</code> (keine Parität).<br />
* <code><Stopbits></code> - Die Anzahl an zu verwendenden Stopbits (0, 1 oder 2 Stopbits). Standardwert sofern nicht angegeben sind 0 Stopbits.<br />
<br />
Wenn man unter Unix-basierten Betriebssystemen die Schnittstelle nicht explizit konfiguriert öffnen möchte, sondern das Gerät direkt öffnen möchte (und damit die OS-Einstellungen verwendet), kann man durch Angabe von <code>@directio</code> die Konfiguration der Schnittstelle umgehen und das Gerät direkt öffnen:<br />
<br />
Bsp: <code><font color="grey">/dev/ttyUSB0</font>@directio</code><br />
<br />
Unter Windows verwendet man als Gerätename die entsprechende Schnittstellenbezeichung wie bspw. <code>COM1</code>, <code>COM2</code>, usw.<br />
|-<br />
| style="vertical-align:top" | '''TCP/IP-Verbindung'''<br />
| style="vertical-align:top" | <br />
* <code>192.168.1.2:1012</code> <br />
* <code>raspberry:5000</code><br />
||<br />
Durch Angabe eines Hostnamen oder IP-Adresse und einem Port, kann eine TCP-Verbindung aufgebaut werden. Dazu muss Hostname/IP-Adresse und Port in folgendem Schema angegeben werden:<br />
<br />
Schematische Syntax: <code>''<Hostname/IP-Adresse>''''':'''''<Port>''</code><br />
<br />
* <code><Hostname/IP-Adresse></code> - Der Hostname oder die IP-Adresse des zu verbindenden Gerätes/Server.<br />
* <code><Port></code> - Der Zielport zu dem sich verbunden werden soll (0-65535).<br />
<br />
Die Verbindung kann optional verschlüsselt via SSL/TLS aufgebaut werden. Dazu muss das Internal <code>$hash->{SSL}</code> auf 1 gesetzt werden.<br />
|-<br />
| style="vertical-align:top" | '''UNIX-Socket'''<br />
| style="vertical-align:top"|<br />
* <code>UNIX:SEQPACKET:/var/tmp/me_avm_home_external.ctl</code> <br />
* <code>UNIX:STREAM:/var/socket/con</code><br />
|| <br />
Durch Angabe eines Pfads zu einem UNIX-Domain-Socket kann eine Kommunikation mit einem anderen Prozess aufgebaut werden (Inter-Prozess-Kommunikation). Man kann den Socket dabei paketorientiert ("SEQPACKET") oder als Stream ("STREAM") öffnen. <br />
<br />
Schematische Syntax: <code>UNIX:''<Typ>'':''<Pfad>''</code><br />
<br />
* <code><Typ></code> - Der Typ des Sockets. Für einen paketorientierten Socket ist hier <code>SEQPACKET</code> zu verwenden, für einen streamorientierten Socket <code>STREAM</code>. Der Typ muss immer mit angegeben werden.<br />
* <code><Pfad></code> - Der Pfad im Dateisystem zu dem gewünschten UNIX-Socket<br />
|-<br />
| style="vertical-align:top" | '''FHEM IO-Modul'''<br />
| style="vertical-align:top" |<br />
* <code>FHEM:DEVIO:Firmata_SerielleSchnittstelle@9600</code> <br />
|| <br />
Beschreibung siehe {{Link2Forum|Topic=46276}}<br />
|}<br />
<br />
= Wichtige Internals zur Konfiguration =<br />
<br />
Da DevIo ausschließlich definitionsbezogen arbeitet, erfolgt eine Konfiguration von DevIo über Internals, die im übergebenen <code>$hash</code> gesetzt werden müssen (oder können). Hiermit lässt sich das Verhalten von DevIo entsprechend beeinflussen. <br />
<br />
Hier eine Auflistung von allen Internals, die DevIo beeinflussen:<br />
<br />
{| class="wikitable"<br />
|-<br />
! style="min-width: 13em;" | Internal !! Beschreibung<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{DeviceName}</code> <br />
<br />
''mandatory''<br />
| style="vertical-align:top" | Die Gegenstelle zu der eine Verbindung aufgebaut werden soll. Die möglichen Werte und deren Syntax ist im Kapitel [[#Unterstützte Verbindungsarten|Unterstützte Verbindungsarten]] genauer beschrieben.<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{nextOpenDelay}</code> <br />
<br />
''optional''<br />
|| Die Zeit in Sekunden, welche im Falle eines Verbindungsabbruchs gewartet werden soll, bevor ein erneuter Verbindungsversuch stattfindet. <br />
<br />
Standardwert: 60 Sekunden<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{TIMEOUT}</code> <br />
<br />
''optional''<br />
|| Die maximale Zeit in Sekunden für den Aufbau einer TCP/IP-Verbindung. Sollte diese Zeit überschritten werden, bricht der Verbindungsaufbau mit einer Fehlermeldung ab.<br />
<br />
'''WICHTIG:''' Sollte beim Aufruf von [[#DevIo_OpenDev|DevIo_OpenDev()]] keine Callback-Funktion parametrisiert sein und die Gegenstelle antwortet beim Verbindungsaufbau nicht, so wird FHEM für die Dauer von <code>$hash->{TIMEOUT}</code> blockiert.<br />
<br />
Standardwert: 3 Sekunden<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{SSL}</code> <br />
<br />
''optional''<br />
|| Flag (0 oder 1), ob eine TCP/IP-Verbindung verschlüsselt (via SSL/TLS) aufgebaut werden soll. Wenn dieses Flag auf 1 gesetzt ist, wird nach erfolgtem Verbindungsaufbau eine SSL-Session initiiert.<br />
<br />
Standardwert: 0 (keine Verschlüsselung)<br />
|-<br />
| style="vertical-align:top" | <code>$hash->{devioLoglevel}</code> <br />
<br />
''optional''<br />
|| Das Loglevel in dem <code>disconnected</code>/<code>reappeared</code> Meldungen geloggt werden sollen. Standardmäßig werden solche Verbindungsabbrüche (<code>disconnected</code>/<code>reappeared</code>) im Loglevel 1 geloggt. Die erfolgreiche Erstverbindung wird standardmäßig im Loglevel 3 geloggt. Durch das Setzen von <code>$hash->{devioLoglevel}</code> werden diese Meldungen allesamt in dem gesetzten Loglevel ausgegeben. Details dazu siehe {{Link2Forum|Topic=61970}}.<br />
<br />
Standardwert: ''[leer]''<br />
|}<br />
<br />
= Die Funktionen =<br />
== DevIo_OpenDev() ==<br />
:<syntaxhighlight lang="perl">$error = DevIo_OpenDev($hash, $reopen, $initfn);<br />
$error = DevIo_OpenDev($hash, $reopen, $initfn, $callback);</syntaxhighlight><br />
<br />
Die Funktion DevIo_OpenDev() öffnet eine Verbindung zu dem Endpunkt der in <code>$hash->{DeviceName}</code> hinterlegt ist. Sobald die Verbindung erfolgreich hergestellt wurde, wird die Funktion <code>$initfn</code> ausgeführt, sofern gesetzt, um die Verbindung zu initialisieren. Sofern eine TCP/IP-Verbindung hergestellt wird, kann eine optionale Callback-Funktion <code>$callback</code> übergeben werden um den Verbindungsaufbau non-blocking durchzuführen.<br />
<br />
Der Rückgabewert enthält im Fehlerfall eine entsprechende Fehlermeldung. Im Erfolgsfall wird <code>undef</code> zurückgegeben. Sofern eine TCP/IP-Verbindung hergestellt wird und eine Callback-Funktion <code>$callback</code> übergeben wurde, wird immer <code>undef</code> zurückgegeben, da ein evtl. Fehler an diese Callback-Funktion nach dem erfolgten Verbindungsversuch mitgeteilt wird.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
| style="vertical-align:top" | Die Hash-Referenz der Definition, für die eine Verbindung geöffnet werden soll<br />
|-<br />
| style="vertical-align:top" | '''<code>$reopen</code>''' <br />
<br />
''mandatory<br>can be <code>undef</code>''<br />
| style="vertical-align:top" | Flag (0 oder 1), ob es sich um einen erneuten Verbindungsversuch handelt (im Rahmen der [[DevelopmentModuleIntro#X_Ready|X_Ready()]]-Funktion). Sollte es der erste Verbindungsversuch sein, so muss dieser Parameter den Wert 0 besitzen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$initfn</code>''' <br />
<br />
''mandatory<br>can be <code>undef</code>''<br />
|| Der Name (als Zeichenkette) oder die Referenz auf eine Modulfunktion, welche optional nach dem erfolgreichen Aufbau/Wiederaufbau der Verbindung ausgeführt werden soll. Im Rahmen dieser Funktion kann weiterführende Kommunikation über die aufgebaute Verbindung erfolgen um zum Beispiel eine Loginsequenz oder eine Konfiguration der Gegenseite vorzunehmen, bevor die Verbindung allgemein benutzt werden kann. <br />
<br />
Die Funktion welche in <code>$initfn</code> angegeben wurde, wird mit folgenden Parametern aufgerufen:<br />
<br />
<syntaxhighlight lang="perl">$ret = MYMODULE_InitFn($hash)</syntaxhighlight><br />
<br />
Wenn der Rückgabewert <code>$ret</code> einen Inhalt zurückliefert, wird die Initialisierung als fehlgeschlagen bewertet und die Verbindung wieder geschlossen um einen neuen Verbindungsversuch zu einem späteren Zeitpunkt zu versuchen. Der genaue Inhalt von <code>$ret</code> ist dabei unerheblich, da er nicht weiterverwendet wird. Die Rückgabewerte <code>0</code> oder <code>undef</code> signalisieren dabei eine erfolgreiche Initialisierung.<br />
<br />
Beispiel: <br />
* <code>"MYMODULE_InitFn"</code><br />
* <code>\&MYMODULE_InitFn</code><br />
|-<br />
| style="vertical-align:top" | '''<code>$callback</code>''' <br />
<br />
''optional''<br />
|| Der Name (als Zeichenkette) oder die Referenz auf eine Modulfunktion, welche aufgerufen werden soll um evtl. Fehlermeldungen beim Verbindungsaufbau einer TCP/IP-Verbindung an das Modul zurückzuliefern. Wenn eine Callback-Funktion gesetzt ist, erfolgt der Verbindungsaufbau non-blocking. Andernfalls wartet DevIo_OpenDev() bis die Verbindung steht bzw. ein Fehler auftritt (z.B. Timeout).<br />
<br />
Die Funktion welche in <code>$callback</code> angegeben wurde, wird mit folgenden Parametern aufgerufen:<br />
<br />
<syntaxhighlight lang="perl">MYMODULE_ConnectCallbackFn($hash, $error)</syntaxhighlight><br />
<br />
Das Argument <code>$error</code> enthält dabei eine Fehlermeldung als Zeichenkette welche die aufgetretene Fehlermeldung enthält. Der Rückgabewert der Callback-Funktion wird nicht ausgewertet und ist daher irrelevant.<br />
<br />
Beispiel: <br />
* <code>"MYMODULE_ConnectCallbackFn"</code><br />
* <code>\&MYMODULE_ConnectCallbackFn</code><br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$error </code>''' || Eine Fehlermeldung als Zeichenkette, sollte der Verbindungsaufbau fehlschlagen. Im Erfolgsfall wird <code>undef</code> zurückgegeben.<br />
<br />
Wenn es sich um eine TCP/IP-Verbindung handelt und eine Callback-Funktion als Parameter <code>$callback</code> angegeben wurde, wird immer <code>undef</code> zurückgegeben, andernfalls erfolgt der Verbindungsaufbau blocking und eine evtl. Fehlermeldung wird als Rückgabewert zurückgegeben. Im Erfolgsfall wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_IsOpen() ==<br />
:<syntaxhighlight lang="perl">$status = DevIo_IsOpen($hash);</syntaxhighlight><br />
<br />
Die Funktion DevIo_IsOpen() prüft, ob eine Verbindung für <code>$hash</code> geöffnet ist. Falls ja, wird das zugehörige IO-Objekt zurückgegeben, andernfalls <code>undef</code>.<br />
<br />
Diese Funktion kann dabei direkt in typischen if-Konstrukten verwendet werden um zu prüfen, ob eine Verbindung für die jeweilige Definition geöffnet oder geschlossen ist.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, deren Verbindung geprüft werden soll.<br />
|}<br />
<br />
Rückgabewerte:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabewert !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Verbindung. Wenn eine Verbindung besteht, wird das zugehörige IO-Objekt zurückgegeben. Falls keine Verbindung besteht, wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_SimpleRead() ==<br />
:<syntaxhighlight lang="perl">$buf = DevIo_SimpleRead($hash);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleRead() liest anstehende Daten für die Verbindung von <code>$hash</code> ein und gibt diese zurück.<br />
<br />
Sollte beim Versuch Daten zu lesen eine geschlossene Verbindung erkannt werden, so wird <code>undef</code> zurückgegeben und die Verbindung geschlossen. Es erfolgt zu einem späteren Zeitpunkt (siehe Internal <code>$hash->{nextOpenDelay}</code> aus Kapitel [[#Wichtige Internals zur Konfiguration|Wichtige Internals zur Konfiguration]]) ein neuer Verbindungsversuch.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung aktuell anstehende Daten gelesen werden sollen.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die zu lesenden Daten als Zeichenkette. Im Falle eines Verbindungsabruchs wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_SimpleReadWithTimeout() ==<br />
{{Randnotiz|RNTyp=Warn|RNText=<u>'''ACHTUNG:'''</u><br />
<br />
Bei der Benutzung von DevIo_SimpleReadWithTimeout() wird FHEM für die Dauer von bis zu <code>$timeout</code> Sekunden blockiert, sollten keine Daten bis dahin zum Lesen bereitstehen.}}<br />
:<syntaxhighlight lang="perl">$buf = DevIo_SimpleReadWithTimeout($hash, $timeout);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleReadWithTimeout() wartet maximal <code>$timeout</code> Sekunden bis die Verbindung von <code>$hash</code> Daten zum einlesen bereitstellt und gibt diese zurück. Sollte nach dem Warten von <code>$timeout</code> noch immer keine Daten zum Lesen bereitstehen, so wird ein Leerstring zurückgegeben.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung aktuell anstehende Daten gelesen werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$timeout</code>''' <br />
<br />
''mandatory''<br />
|| Die maximale Wartezeit in Sekunden.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die zu lesenden Daten als Zeichenkette.<br />
|}<br />
<br />
== DevIo_TimeoutRead() ==<br />
{{Randnotiz|RNTyp=Warn|RNText=<u>'''ACHTUNG:'''</u><br />
<br />
Bei der Benutzung von DevIo_TimeoutRead() wird FHEM für die Dauer von <code>$timeout</code> Sekunden blockiert.}}<br />
:<syntaxhighlight lang="perl">$buf = DevIo_TimeoutRead($hash, $timeout);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleReadWithTimeout() wartet <code>$timeout</code> Sekunden und liest sämtliche Daten für die Verbindung von <code>$hash</code> ein, die in dieser Zeit eintreffen. Sollten keinerlei Daten während der Wartezeit eintreffen, so wird ein Leerstring zurückgegeben.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung Daten eingelesen werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$timeout</code>''' <br />
<br />
''mandatory''<br />
|| Die Wartezeit in Sekunden.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die eingelesenen Daten als Zeichenkette.<br />
|}<br />
<br />
== DevIo_SimpleWrite() ==<br />
:<syntaxhighlight lang="perl">DevIo_SimpleWrite($hash, $msg, $type);<br />
DevIo_SimpleWrite($hash, $msg, $type, $addnl);</syntaxhighlight><br />
<br />
Die Funktion DevIo_SimpleWrite() sendet den Inhalt von <code>$msg</code> über die Verbindung von <code>$hash</code>. Mit den beiden Argumenten <code>$type</code> und <code>$addnl</code> kann die Formatierung von <code>$msg</code> beeinflusst werden bevor die Daten tatsächlich gesendet werden.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, über deren Verbindung die Daten gesendet werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$msg</code>''' <br />
<br />
''mandatory''<br />
|| Die zu schreibenden Daten als Zeichenkette. Abhängig von <code>$type</code> kann <code>$msg</code> Byte-Characters, HEX-Darstellungen oder normale ASCII-Zeichen enthalten.<br />
|-<br />
| style="vertical-align:top" | '''<code>$type</code>''' <br />
<br />
''mandatory''<br />
|| Die Art des Inhalts von <code>$msg</code>. Abhängig von dem Inhalt von <code>$type</code> wird <code>$msg</code> entsprechend geändert oder nicht. Desweiteren werden die Daten für Logausgaben evtl. leserlich gemacht.<br />
<br />
Folgende Werte sind möglich:<br />
<br />
* <code>0</code> - <code>$msg</code> enthält Daten in Byteform. Der Inhalt von <code>$msg</code> wird 1:1 gesendet. Zur besseren Lesbarkeit werden die Daten bei Logausgaben in HEX-Darstellung umgewandelt.<br />
* <code>1</code> - <code>$msg</code> enthält Binärdaten in HEX-Darstellung (0-9/A-F). Der Inhalt von <code>$msg</code> wird vorher in Byteform umgewandelt und anschließend gesendet. In Logausgaben wird die HEX-Darstellung wie übergeben verwendet.<br />
* <code>2</code> - <code>$msg</code> enthält normale ASCII-Textzeichen. Der Inhalt von <code>$msg</code> wird 1:1 gesendet. In Logausgaben wird <code>$msg</code> wie übergeben ausgegeben.<br />
|-<br />
| style="vertical-align:top" | '''<code>$addnl</code>''' <br />
<br />
''optional''<br />
|| Ein Flag (0/1) welches, sofern aktiviert, einen Zeilenumbruch (<code>\n</code>) an <code>$msg</code> anfügt, bevor es gesendet wird.<br />
<br />
Standardwert: 0<br />
|}<br />
<br />
== DevIo_Expect() ==<br />
{{Randnotiz|RNTyp=Warn|RNText=<u>'''ACHTUNG:'''</u><br />
<br />
# Bei der Benutzung von DevIo_Expect() wird FHEM für die Dauer von bis zu <code>$timeout</code> Sekunden blockiert.<br />
# Sollte im ersten Versuch keine Antwort auf die zuvor gesendeten Daten innerhalb von <code>$timeout</code> Sekunden eintreffen, wird die Verbindung geschlossen und neu aufgebaut. Es erfolgt dabei '''KEINE INITIALISIERUNG''' durch <code>$initfn</code> aus [[#DevIo_OpenDev()|DevIo_OpenDev()]].<br />
}}<br />
:<syntaxhighlight lang="perl">$buf = DevIo_Expect($hash, $msg, $timeout);</syntaxhighlight><br />
<br />
Die Funktion DevIo_Expect() sendet den Inhalt von <code>$msg</code> und wartet bis zu <code>$timeout</code> Sekunden auf eine Antwort. Sollte in dieser Zeit keine Antwort eintreffen, so wird die Verbindung einmalig geschlossen, erneut geöffnet (ohne Aufruf einer Initialisierungs-Funktion) und der Vorgang wiederholt. Die empfangene Antwort wird anschließend als Funktionsergebnis zurückgegeben.<br />
<br />
Wenn beim ersten Versuch keine Antwort innerhalb von <code>$timeout</code> Sekunden eintrifft, wird das Event <code>FAILED</code> generiert (siehe [[#Generierte Events|Generierte Events]]). Anschließend wird die Verbindung geschlossen, neu geöffnet (ohne Initialisierung) und <code>$msg</code> erneut gesendet. Sollte nun eine Antwort eintreffen, so wird das Event <code>CONNECTED</code> generiert und die empfangene Antwort zurückgegeben. Sollte dennoch keine Antwort eintreffen, so wird das Event <code>DISCONNECTED</code> getriggert.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, für deren Verbindung Daten gesendet und anschließen gelesen werden sollen.<br />
|-<br />
| style="vertical-align:top" | '''<code>$msg</code>''' <br />
<br />
''mandatory''<br />
|| Die zu sendenden Daten auf die eine Antwort erwartet wird. Die Daten werden ohne Konvertierung direkt gesendet (entspricht <code>$type</code> gleich <code>0</code> bei [[#DevIo_SimpleWrite()|DevIo_SimpleWrite]]).<br />
|-<br />
| style="vertical-align:top" | '''<code>$timeout</code>''' <br />
<br />
''mandatory''<br />
|| Die maximale Wartezeit in Sekunden bis zum Eintreffen einer Antwort.<br />
|}<br />
<br />
Rückgabewert:<br />
{| class="wikitable"<br />
|-<br />
! Rückgabe!! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$buf</code>''' || Die empfangene Antwort. Sollte es zu einem Fehler gekommen sein (Senden von <code>$msg</code> fehlgeschlagen, keine Antwort innerhalb von <code>$timeout</code> Sekunden erhalten, etc.), so wird <code>undef</code> zurückgegeben.<br />
|}<br />
<br />
== DevIo_CloseDev() ==<br />
:<syntaxhighlight lang="perl">DevIo_CloseDev($hash);<br />
DevIo_CloseDev($hash, $isFork);</syntaxhighlight><br />
<br />
Die Funktion DevIo_CloseDev() schließt eine evtl. geöffnete Verbindung für die Definition <code>$hash</code>. <br />
<br />
Optional kann man mit dem Flag <code>$isFork</code> angeben, dass man sich aktuell in einem Fork vom Hauptprozess befindet. Dadurch wird beim Schließen von seriellen Verbindungen die Kommunikationsparameter nicht zurückgesetzt. Dies verhindert einen Ausfall der nachwievor bestehenden Verbindung im Hauptprozess.<br />
<br />
Parameter:<br />
{| class="wikitable"<br />
|-<br />
! Parameter !! Bedeutung<br />
|-<br />
| style="vertical-align:top" | '''<code>$hash</code>''' <br />
<br />
''mandatory''<br />
|| Die Hash-Referenz der Definition, deren Verbindung geschlossen werden soll.<br />
|-<br />
| style="vertical-align:top" | '''<code>$isFork</code>''' <br />
<br />
''optional''<br />
|| Ein Flag (0 oder 1), welches angibt, dass DevIo_CloseDev() innerhalb eines geforkten Kindprozess ausgeführt wird. Dadurch werden serielle Verbindung so geschlossen, dass dabei die Kommunikationsparameter (Baudrate, Datenbits, Parität, etc.) nicht zurückgesetzt werden. Dieses Flag wird primär von dem Modul [[Blocking_Call|Blocking.pm]] verwendet um Verbindungen in einem geforkten Kindprozess zu schließen, ohne die Verbindung im Hauptprozess zu beeinträchtigen.<br />
<br />
Standardwert: 0 (Verbindung wird im Hauptprozess geschlossen)<br />
|}<br />
<br />
= Generierte Events =<br />
Die Funktionen von DevIo generieren verschiedene Events für die entsprechende Definition (parametrisiert durch <code>$hash</code>). Diese können bspw. in der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion des entsprechenden Moduls verarbeitet werden.<br />
<br />
Hier eine Übersicht der generierten Events:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Event !! Bedeutung<br />
|-<br />
| '''<code>CONNECTED</code>''' || Die Verbindung wurde nach einem Verbindungsabbruch erfolgreich wieder aufgebaut. Dieses Event wird nur nach einem erfolgreichen Reconnect von einer zuvor verlorenen Verbindung generiert. Es wird '''nicht''' nach der erfolgreichen Initialverbindung generiert.<br />
|-<br />
| '''<code>DISCONNECTED</code>''' || Die Verbindung ist zusammengebrochen. Es wird ein neuer Verbindungsversuch nach <code>$hash->{nextOpenDelay}</code> Sekunden erfolgen (siehe [[#Wichtige Internals zur Konfiguration|Wichtige Internals zur Konfiguration]]).<br />
|-<br />
| '''<code>FAILED</code>''' || Dieses Event wird nur bei der Nutzung der Funktion [[#DevIo_Expect|DevIo_Expect()]] generiert, sofern es keine Antwort auf die zuvor gesendeten Daten gibt. Dies bedeutet konkret, dass Gerät hat nicht auf die eigene Anfrage geantwortet und die Verbindung wird daher neu aufgebaut. Details dazu, siehe [[#DevIo_Expect()|DevIo_Expect()]].<br />
|}<br />
<br />
= Hinweis bei der Datenverarbeitung (Buffering) =<br />
DevIo beschränkt sich ausschließlich auf die Verbindungsverwaltung. Sobald die Verbindung etabliert wurde, übernimmt FHEM (fhem.pl) die Verarbeitung von eingehenden Daten und informiert das entsprechende Modul durch Aufruf der [[DevelopmentModuleIntro#X_Read|Read]]-Funktion. Dabei hat weder DevIo, noch FHEM selber Kenntnis von der Struktur der Daten. Sowohl DevIo, als auch FHEM selber können nicht erkennen, ob die empfangenen Daten weder vollständig, noch valide in ihrem Aufbau sind. Dies alles obliegt dem Modul, welches die Verbindung initiiert hat. Man sollte daher immer davon ausgehen, dass beim Lesen von Daten (in [[DevelopmentModuleIntro#X_Read|X_Read()]]) diese unvollständig sein können, oder sogar mehrere Datagramme enthalten sein können. <br />
<br />
Dazu stellt DevIo dem Modulentwickler das Internal <code>$hash->{PARTIAL}</code> in der jeweiligen Definition zur Verfügung um dort Daten zwischenzuspeichern, bis ein vollständiges Datagramm daraus verarbeitet werden kann. Alle eingelesenen Daten werden dazu in der [[DevelopmentModuleIntro#X_Read|Read]]-Funktion immer an <code>$hash->{PARTIAL}</code> hinten angehangen. Sobald ein vollständiges Datagramm in <code>$hash->{PARTIAL}</code> erkannt wurde, wird dieses herausgenommen und verarbeitet, solange bis kein vollständiges Datagramm in <code>$hash->{PARTIAL}</code> erkennbar ist. Hierbei ist jedoch entscheidend, woran man ein abgeschlossenes Datagramm erkennen kann. Dies kann je nach Protokoll sehr unterschiedlich sein (bspw. Zeilenumbruch <code>\r\n</code> oder ein Semikolon <code>;</code>, etc.). <br />
<br />
DevIo initialisiert <code>$hash->{PARTIAL}</code> nach dem erfolgreichen Verbindungsaufbau mit einem Leerstring (<code>""</code>). Sobald eine Verbindung mit [[#DevIo_CloseDev()|DevIo_CloseDev()]] geschlossen wird, wird <code>$hash->{PARTIAL}</code> gelöscht.<br />
<br />
Hier ein Beispiel, wie man ein solches Buffering verwendet für ein Protokoll, welches Datagramme durch einen Zeilenumbruch <code>\n</code> (Newline) abtrennt:<br />
<br />
<syntaxhighlight lang="perl"><br />
sub MY_MODULE_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
my $data = DevIo_SimpleRead($hash);<br />
return if(!defined($buf)); # connection lost<br />
<br />
my $buffer = $hash->{PARTIAL};<br />
<br />
Log3 $name, 5, "MY_MODULE ($name) - received $data (buffer contains: $buf)";<br />
<br />
# concat received data to $buffer<br />
$buffer .= $data;<br />
<br />
# as long as the buffer contains newlines (complete datagramm)<br />
while($buffer =~ m/\n/)<br />
{<br />
my $msg;<br />
<br />
# extract the complete message ($msg), everything else is assigned to $buffer<br />
($msg, $buffer) = split("\n", $buffer, 2);<br />
<br />
# remove trailing whitespaces<br />
chomp $msg;<br />
<br />
# update $hash->{PARTIAL} with the current buffer content<br />
$hash->{PARTIAL} = $buffer; <br />
<br />
# parse the extracted message<br />
MY_MODULE_ParseMessage($hash, $msg);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
= Beispielimplementierung in einem Modul =<br />
== serielle Verbindung ==<br />
<syntaxhighlight lang="perl"><br />
package main;<br />
<br />
use strict;<br />
use warnings;<br />
use DevIo; # load DevIo.pm if not already loaded<br />
<br />
# called upon loading the module MY_MODULE<br />
sub MY_MODULE_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
$hash->{DefFn} = "MY_MODULE_Define";<br />
$hash->{UndefFn} = "MY_MODULE_Undef";<br />
$hash->{SetFn} = "MY_MODULE_Set";<br />
$hash->{ReadFn} = "MY_MODULE_Read";<br />
$hash->{ReadyFn} = "MY_MODULE_Ready";<br />
}<br />
<br />
# called when a new definition is created (by hand or from configuration read on FHEM startup)<br />
sub MY_MODULE_Define($$)<br />
{<br />
my ($hash, $def) = @_;<br />
my @a = split("[ \t]+", $def);<br />
<br />
my $name = $a[0];<br />
<br />
# $a[1] is always equals the module name "MY_MODULE"<br />
<br />
# first argument is a serial device (e.g. "/dev/ttyUSB0@9600")<br />
my $dev = $a[2]; <br />
<br />
return "no device given" unless($dev);<br />
<br />
# add a default baud rate (9600), if not given by user<br />
$dev .= '@9600' if(not $dev =~ m/\@\d+$/);<br />
<br />
$hash->{DeviceName} = $dev;<br />
<br />
# close connection if maybe open (on definition modify)<br />
DevIo_CloseDev($hash) if(DevIo_IsOpen($hash)); <br />
<br />
# open connection with custom init function<br />
my $ret = DevIo_OpenDev($hash, 0, "MY_MODULE_Init"); <br />
<br />
return undef;<br />
}<br />
<br />
# called when definition is undefined <br />
# (config reload, shutdown or delete of definition)<br />
sub MY_MODULE_Undef($$)<br />
{<br />
my ($hash, $name) = @_;<br />
<br />
# close the connection <br />
DevIo_CloseDev($hash);<br />
<br />
return undef;<br />
}<br />
<br />
# called repeatedly if device disappeared<br />
sub MY_MODULE_Ready($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# try to reopen the connection in case the connection is lost<br />
return DevIo_OpenDev($hash, 1, "MY_MODULE_Init"); <br />
}<br />
<br />
# called when data was received<br />
sub MY_MODULE_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# read the available data<br />
my $buf = DevIo_SimpleRead($hash);<br />
<br />
# stop processing if no data is available (device disconnected)<br />
return if(!defined($buf));<br />
<br />
Log3 $name, 5, "MY_MODULE ($name) - received: $buf"; <br />
<br />
#<br />
# do something with $buf, e.g. generate readings, send answers via DevIo_SimpleWrite(), ...<br />
#<br />
<br />
}<br />
<br />
# called if set command is executed<br />
sub MY_MODULE_Set($$@)<br />
{<br />
my ($hash, $name, $cmd) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
my $usage = "unknown argument $cmd, choose one of statusRequest:noArg on:noArg off:noArg";<br />
<br />
if($cmd eq "statusRequest")<br />
{<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
}<br />
elsif($cmd eq "on")<br />
{<br />
DevIo_SimpleWrite($hash, "on\r\n", 2);<br />
}<br />
elsif($cmd eq "off")<br />
{<br />
DevIo_SimpleWrite($hash, "off\r\n", 2);<br />
}<br />
else<br />
{<br />
return $usage;<br />
}<br />
}<br />
<br />
# will be executed upon successful connection establishment (see DevIo_OpenDev())<br />
sub MY_MODULE_Init($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# send a status request to the device<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
<br />
return undef; <br />
}<br />
</syntaxhighlight><br />
<br />
== TCP/IP-Verbindung == <br />
<syntaxhighlight lang="perl"><br />
package main;<br />
<br />
use strict;<br />
use warnings;<br />
use DevIo; # load DevIo.pm if not already loaded<br />
<br />
# called upon loading the module MY_MODULE<br />
sub MY_MODULE_Initialize($)<br />
{<br />
my ($hash) = @_;<br />
<br />
$hash->{DefFn} = "MY_MODULE_Define";<br />
$hash->{UndefFn} = "MY_MODULE_Undef";<br />
$hash->{SetFn} = "MY_MODULE_Set";<br />
$hash->{ReadFn} = "MY_MODULE_Read";<br />
$hash->{ReadyFn} = "MY_MODULE_Ready";<br />
}<br />
<br />
# called when a new definition is created (by hand or from configuration read on FHEM startup)<br />
sub MY_MODULE_Define($$)<br />
{<br />
my ($hash, $def) = @_;<br />
my @a = split("[ \t]+", $def);<br />
<br />
my $name = $a[0];<br />
<br />
# $a[1] is always equals the module name "MY_MODULE"<br />
<br />
# first argument is the hostname or IP address of the device (e.g. "192.168.1.120")<br />
my $dev = $a[2]; <br />
<br />
return "no device given" unless($dev);<br />
<br />
# add a default port (1012), if not explicitly given by user<br />
$dev .= ':1012' if(not $dev =~ m/:\d+$/);<br />
<br />
$hash->{DeviceName} = $dev;<br />
<br />
# close connection if maybe open (on definition modify)<br />
DevIo_CloseDev($hash) if(DevIo_IsOpen($hash)); <br />
<br />
# open connection with custom init and error callback function (non-blocking connection establishment)<br />
DevIo_OpenDev($hash, 0, "MY_MODULE_Init", "MY_MODULE_Callback"); <br />
<br />
return undef;<br />
}<br />
<br />
# called when definition is undefined <br />
# (config reload, shutdown or delete of definition)<br />
sub MY_MODULE_Undef($$)<br />
{<br />
my ($hash, $name) = @_;<br />
<br />
# close the connection <br />
DevIo_CloseDev($hash);<br />
<br />
return undef;<br />
}<br />
<br />
# called repeatedly if device disappeared<br />
sub MY_MODULE_Ready($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# try to reopen the connection in case the connection is lost<br />
return DevIo_OpenDev($hash, 1, "MY_MODULE_Init", "MY_MODULE_Callback"); <br />
}<br />
<br />
# called when data was received<br />
sub MY_MODULE_Read($)<br />
{<br />
my ($hash) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# read the available data<br />
my $buf = DevIo_SimpleRead($hash);<br />
<br />
# stop processing if no data is available (device disconnected)<br />
return if(!defined($buf));<br />
<br />
Log3 $name, 5, "MY_MODULE ($name) - received: $buf"; <br />
<br />
#<br />
# do something with $buf, e.g. generate readings, send answers via DevIo_SimpleWrite(), ...<br />
#<br />
<br />
}<br />
<br />
# called if set command is executed<br />
sub MY_MODULE_Set($$@)<br />
{<br />
my ($hash, $name, $cmd) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
my $usage = "unknown argument $cmd, choose one of statusRequest:noArg on:noArg off:noArg";<br />
<br />
if($cmd eq "statusRequest")<br />
{<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
}<br />
elsif($cmd eq "on")<br />
{<br />
DevIo_SimpleWrite($hash, "on\r\n", 2);<br />
}<br />
elsif($cmd eq "off")<br />
{<br />
DevIo_SimpleWrite($hash, "off\r\n", 2);<br />
}<br />
else<br />
{<br />
return $usage;<br />
}<br />
}<br />
<br />
# will be executed upon successful connection establishment (see DevIo_OpenDev())<br />
sub MY_MODULE_Init($)<br />
{<br />
my ($hash) = @_;<br />
<br />
# send a status request to the device<br />
DevIo_SimpleWrite($hash, "get_status\r\n", 2);<br />
<br />
return undef; <br />
}<br />
<br />
# will be executed if connection establishment fails (see DevIo_OpenDev())<br />
sub MY_MODULE_Callback($)<br />
{<br />
my ($hash, $error) = @_;<br />
my $name = $hash->{NAME};<br />
<br />
# create a log emtry with the error message<br />
Log3 $name, 5, "MY_MODULE ($name) - error while connecting: $error"; <br />
<br />
return undef; <br />
}<br />
</syntaxhighlight><br />
<br />
= Referenzen = <br />
<references /><br />
<br />
<br />
[[Kategorie:Development]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=FHEM_auf_Mac_OS_X&diff=26239FHEM auf Mac OS X2018-03-23T08:50:23Z<p>Eisler: /* FHEM installieren */</p>
<hr />
<div>== OS X vorbereiten ==<br />
<br />
=== Perl installieren ===<br />
Anscheinend ist die [[Perl]]-Installation von OS X nicht komplett oder fehlerhaft wodurch nach der Installation zB die Icon-List nicht komplett geladen wurde. Deshalb wird Perl zur Sicherheit nochmals neu installiert. [http://learn.perl.org/installing/osx.html]<br />
<br />
<pre style="width:50%;">curl -L http://xrl.us/installperlosx | bash</pre><br />
<br />
{{Randnotiz|RNText=Optionale Pakete<br />
* JSON<br />
** [[Hue]]<br />
** [[Volkszaehler]]<br />
** [[Pushbullet]]<br />
** ''withings''<br />
** [[Ubiquit mFi/mPower]]<br />
** etc.<br />
* Net::Telnet<br />
**[[Ubiquit mFi/mPower]]<br />
* Net::WebSocket::Server<br />
** [[Fronthem]]<br />
* XML::Simple<br />
** [[Enigma2 Receiver (Dreambox, VUplus etc.) steuern|ENIGMA2 Modul]]<br />
}}<br />
=== Benötigte Pakete installieren ===<br />
<br />
In der Konsole folgende Befehle eingeben:<br />
<pre style="width:50%;"><br />
sudo -i<br />
cpan install Bundle::CPAN<br />
cpan install Device::SerialPort <br />
cpan install IO::Socket::SSL<br />
</pre><br />
<br />
=== Optionale Pakete installieren ===<br />
In der Konsole folgende Befehle eingeben:<br />
<pre style="width:50%;"><br />
sudo -i<br />
cpan install JSON<br />
cpan install Net::Telnet<br />
cpan install Net::WebSocket::Server<br />
cpan install XML::Simple<br />
</pre><br />
<br />
==FHEM installieren==<br />
<br />
=== FHEM herunterladen ===<br />
Anschließend wird FHEM von der [http://fhem.de/fhem.html#Download Website] heruntergeladen und ins gewünschte Verzeichnis entpackt. <br /><br />
In dieser Anleitung wird FHEM nach ''/Users/Name/fhem-install'' entpackt<br />
<br />
=== Makefile bearbeiten ===<br />
In der Datei ''/Users/Name/fhem-install/Makefile'' <br />
<br />
<pre style="width:50%;">BINDIR=/usr/local/bin</pre><br />
<br />
den Pfad<br />
<br />
<pre style="width:50%;">BINDIR=/Users/Name/fhem</pre><br />
<br />
entsprechend ändern.<br />
<br />
=== FHEM installieren ===<br />
In der Konsole folgende Befehle eingeben:<br />
<br />
<pre style="width:50%;"><br />
cd /Users/Name/fhem-install<br />
sudo make install<br />
</pre><br />
<br />
Nun sollte FHEM korrekt installiert und unter der URL http://IP-Adresse:8083 erreichbar sein.<br />
<br />
== Infos ==<br />
<br />
=== FHEM starten ===<br />
In der Konsole folgenden Befehl eingeben:<br />
<pre style="width:50%;"><br />
cd /Users/Name/fhem/ && perl fhem.pl fhem.cfg<br />
</pre><br />
<br />
=== FHEM stoppen ===<br />
In der Konsole folgende Befehle eingeben:<br />
<pre style="width:50%;"><br />
telnet IP-Adresse 7072<br />
shutdown<br />
</pre><br />
<br />
[[Kategorie:HOWTOS]]<br />
[[Kategorie:OSX]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=FHEM_auf_Mac_OS_X&diff=26238FHEM auf Mac OS X2018-03-23T08:50:02Z<p>Eisler: /* Makefile bearbeiten */</p>
<hr />
<div>== OS X vorbereiten ==<br />
<br />
=== Perl installieren ===<br />
Anscheinend ist die [[Perl]]-Installation von OS X nicht komplett oder fehlerhaft wodurch nach der Installation zB die Icon-List nicht komplett geladen wurde. Deshalb wird Perl zur Sicherheit nochmals neu installiert. [http://learn.perl.org/installing/osx.html]<br />
<br />
<pre style="width:50%;">curl -L http://xrl.us/installperlosx | bash</pre><br />
<br />
{{Randnotiz|RNText=Optionale Pakete<br />
* JSON<br />
** [[Hue]]<br />
** [[Volkszaehler]]<br />
** [[Pushbullet]]<br />
** ''withings''<br />
** [[Ubiquit mFi/mPower]]<br />
** etc.<br />
* Net::Telnet<br />
**[[Ubiquit mFi/mPower]]<br />
* Net::WebSocket::Server<br />
** [[Fronthem]]<br />
* XML::Simple<br />
** [[Enigma2 Receiver (Dreambox, VUplus etc.) steuern|ENIGMA2 Modul]]<br />
}}<br />
=== Benötigte Pakete installieren ===<br />
<br />
In der Konsole folgende Befehle eingeben:<br />
<pre style="width:50%;"><br />
sudo -i<br />
cpan install Bundle::CPAN<br />
cpan install Device::SerialPort <br />
cpan install IO::Socket::SSL<br />
</pre><br />
<br />
=== Optionale Pakete installieren ===<br />
In der Konsole folgende Befehle eingeben:<br />
<pre style="width:50%;"><br />
sudo -i<br />
cpan install JSON<br />
cpan install Net::Telnet<br />
cpan install Net::WebSocket::Server<br />
cpan install XML::Simple<br />
</pre><br />
<br />
==FHEM installieren==<br />
<br />
=== FHEM herunterladen ===<br />
Anschließend wird FHEM von der [http://fhem.de/fhem.html#Download Website] heruntergeladen und ins gewünschte Verzeichnis entpackt. <br /><br />
In dieser Anleitung wird FHEM nach ''/Users/Name/fhem-install'' entpackt<br />
<br />
=== Makefile bearbeiten ===<br />
In der Datei ''/Users/Name/fhem-install/Makefile'' <br />
<br />
<pre style="width:50%;">BINDIR=/usr/local/bin</pre><br />
<br />
den Pfad<br />
<br />
<pre style="width:50%;">BINDIR=/Users/Name/fhem</pre><br />
<br />
entsprechend ändern.<br />
<br />
=== FHEM installieren ===<br />
In der Konsole folgende Befehle eingeben:<br />
<br />
<pre style="width:50%;"><br />
cd /Users/Name/fhem<br />
sudo make install<br />
</pre><br />
<br />
Nun sollte FHEM korrekt installiert und unter der URL http://IP-Adresse:8083 erreichbar sein.<br />
<br />
== Infos ==<br />
<br />
=== FHEM starten ===<br />
In der Konsole folgenden Befehl eingeben:<br />
<pre style="width:50%;"><br />
cd /Users/Name/fhem/ && perl fhem.pl fhem.cfg<br />
</pre><br />
<br />
=== FHEM stoppen ===<br />
In der Konsole folgende Befehle eingeben:<br />
<pre style="width:50%;"><br />
telnet IP-Adresse 7072<br />
shutdown<br />
</pre><br />
<br />
[[Kategorie:HOWTOS]]<br />
[[Kategorie:OSX]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=FHEM_auf_Mac_OS_X&diff=26237FHEM auf Mac OS X2018-03-23T08:49:31Z<p>Eisler: /* FHEM herunterladen */</p>
<hr />
<div>== OS X vorbereiten ==<br />
<br />
=== Perl installieren ===<br />
Anscheinend ist die [[Perl]]-Installation von OS X nicht komplett oder fehlerhaft wodurch nach der Installation zB die Icon-List nicht komplett geladen wurde. Deshalb wird Perl zur Sicherheit nochmals neu installiert. [http://learn.perl.org/installing/osx.html]<br />
<br />
<pre style="width:50%;">curl -L http://xrl.us/installperlosx | bash</pre><br />
<br />
{{Randnotiz|RNText=Optionale Pakete<br />
* JSON<br />
** [[Hue]]<br />
** [[Volkszaehler]]<br />
** [[Pushbullet]]<br />
** ''withings''<br />
** [[Ubiquit mFi/mPower]]<br />
** etc.<br />
* Net::Telnet<br />
**[[Ubiquit mFi/mPower]]<br />
* Net::WebSocket::Server<br />
** [[Fronthem]]<br />
* XML::Simple<br />
** [[Enigma2 Receiver (Dreambox, VUplus etc.) steuern|ENIGMA2 Modul]]<br />
}}<br />
=== Benötigte Pakete installieren ===<br />
<br />
In der Konsole folgende Befehle eingeben:<br />
<pre style="width:50%;"><br />
sudo -i<br />
cpan install Bundle::CPAN<br />
cpan install Device::SerialPort <br />
cpan install IO::Socket::SSL<br />
</pre><br />
<br />
=== Optionale Pakete installieren ===<br />
In der Konsole folgende Befehle eingeben:<br />
<pre style="width:50%;"><br />
sudo -i<br />
cpan install JSON<br />
cpan install Net::Telnet<br />
cpan install Net::WebSocket::Server<br />
cpan install XML::Simple<br />
</pre><br />
<br />
==FHEM installieren==<br />
<br />
=== FHEM herunterladen ===<br />
Anschließend wird FHEM von der [http://fhem.de/fhem.html#Download Website] heruntergeladen und ins gewünschte Verzeichnis entpackt. <br /><br />
In dieser Anleitung wird FHEM nach ''/Users/Name/fhem-install'' entpackt<br />
<br />
=== Makefile bearbeiten ===<br />
In der Datei ''/Users/Name/fhem/Makefile'' <br />
<br />
<pre style="width:50%;">BINDIR=/usr/local/bin</pre><br />
<br />
den Pfad<br />
<br />
<pre style="width:50%;">BINDIR=/Users/Name/fhem</pre><br />
<br />
entsprechend ändern.<br />
<br />
=== FHEM installieren ===<br />
In der Konsole folgende Befehle eingeben:<br />
<br />
<pre style="width:50%;"><br />
cd /Users/Name/fhem<br />
sudo make install<br />
</pre><br />
<br />
Nun sollte FHEM korrekt installiert und unter der URL http://IP-Adresse:8083 erreichbar sein.<br />
<br />
== Infos ==<br />
<br />
=== FHEM starten ===<br />
In der Konsole folgenden Befehl eingeben:<br />
<pre style="width:50%;"><br />
cd /Users/Name/fhem/ && perl fhem.pl fhem.cfg<br />
</pre><br />
<br />
=== FHEM stoppen ===<br />
In der Konsole folgende Befehle eingeben:<br />
<pre style="width:50%;"><br />
telnet IP-Adresse 7072<br />
shutdown<br />
</pre><br />
<br />
[[Kategorie:HOWTOS]]<br />
[[Kategorie:OSX]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=22768Proteus EcoMeter2017-09-28T20:46:31Z<p>Eisler: </p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zur Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=EcoMeter.png<br />
|Bildbeschreibung=EcoMeter Ultraschall Füllstandsanzeige für Heizöltank<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 433,92MHz, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Tekelek<br />
}}<br />
== Features ==<br />
EcoMeter für Heizöl liefert alle 60 Minuten einen Messwert<br />
<br />
EcoMeter S für Zisterne, Wassertank liefert alle 30 Minuten einen Messwert <br />
<br />
Wenn der Sensor eine Füllstandänderung von 3cm pro Minute erkennt, geht der Sensor in den FastModus, d.h. es werden alle 2 - 3 Sekunden neue Werte an den Ecomonitor kommuniziert. Dies ist hilfreich bei einem Leck oder beim Nachtanken. Der FastModus, vergleichbar mit dem Modus nach dem Koppeln, dauert dann ca. 10 Minuten an, so dass die Batterie nicht leer gesaugt wird.<br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== Identifikation ===<br />
Das Proteus EcoMeter verwendet für die Anbindung der seriellen Kommunikation an die USB-Schnittstelle einen sehr weit verbreiteten Chip der Familie <code>CP210x UART Bridges</code>. Dieser Baustein hat die USB <code>ID 10c4:ea60</code> über die auch der Name in <code>/dev/serial/by-id</code> abgeleitet wird. Hat man mehrere Geräte die mit diesem Chip arbeiten (z.B. den optischen Adapter von Viessmann für [[Vitotronic_200_(Viessmann_Heizungssteuerung)|VCONTROL]]) am gleichen Rechner, so werden diese unter <code>lsusb</code> mit identischer ID gelistet, aber nur einer erhält den passenden Namen unter <code>/dev/serial/by-id</code>. Sie sind also auf diese Weise nicht unterscheidbar. Die kurzen Gerätenamen <code>/dev/ttyUSBx</code> werden willkürlich zugeordnet. Damit sind die Geräte auch nicht unterscheidbar.<br />
<br />
Bleibt noch der Pfad wenn man die Geräte immer in die gleiche Buchse steckt. Diese Pfade werden unter Linux in <code>/dev/serial/by-path</code> angelegt. Hier kann man einzelne Buchsen (auch von Hubs) identifizieren. Die Namen enthalten jedoch Doppelpunkte und FHEM verkraftet keine Gerätenamen mit Doppelpunkten. <small>''Wer weiß warum bitte hier Lösung eintragen.''</small> Um diese ohnehin unhandlichen Namen kürzer und verträglicher zu bekommen, kann man Symbolische Links anlegen. Dazu erzeugt man am besten in <code>/opt/fhem</code> ein Verzeichnis <code>dev</code> und verlinkt alle für FHEM relevanten Geräte dort hin. Also in meinem Beispiel TEK603 und VCONTROL:<br />
<syntaxhighlight lang=bash><br />
cd /opt/fhem<br />
mkdir dev<br />
cd dev<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.3:1.0-port0 heizung<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.2:1.0-port0 oelpegel<br />
</syntaxhighlight><br />
Solange man die beiden Geräte immer in die gleiche Buchse steckt, werden sie ab jetzt immer korrekt zugeordnet:<br />
<syntaxhighlight lang=text><br />
defmod Oelpegel TEK603 /opt/fhem/dev/oelpegel<br />
defmod Heizung VCONTROL /opt/fhem/dev/heizung /opt/fhem/mycfg/vitoladens_300-C_J3Ra-24.cfg 120<br />
</syntaxhighlight><br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
<syntaxhighlight lang=text><br />
2017-03-03_13:07:11 Oelpegel CONNECTED<br />
2017-03-03_13:08:27 Oelpegel Time: 13:05:21<br />
2017-03-03_13:08:27 Oelpegel Temperature: 18.33<br />
2017-03-03_13:08:27 Oelpegel Ullage: 100<br />
2017-03-03_13:08:27 Oelpegel RemainingUsableLevel: 3227<br />
2017-03-03_13:08:27 Oelpegel RemainingUsablePercent: 31.0<br />
2017-03-03_13:08:27 Oelpegel TotalUsableCapacity: 10414<br />
</syntaxhighlight><br />
In den ersten 10 Minuten nach dem Anlernen, befindet sich das Gerät im Echtzeit-Modus. Das bedeutet es werden mehrere Messungen pro Sekunde übertragen. Das würde die Batterie sehr schnell lehren. Daher schaltet das Gerät nach 10 Minuten in den Normalbetrieb, in dem nur noch ganz grob alle 30 Minuten Werte übertragen werden. Die Übertragung zu FHEM findet auch nur statt, wenn über die Funkstrecke Daten vom Sensor kommen. Das führt zu der Situation, dass nach diesen 10 Minuten ein neu eingerichtetes <code>TEK603</code> Modul sehr lange (Stunden ?) keine Daten anzeigt, obwohl das Display der Proteus Daten anzeigt. Das liegt einfach daran, dass dieses Display den zuletzt gespeicherten Messwert anzeigt egal wie lange der her ist. Übertragen wird bis zum nächsten Wert auf der Funkstrecke nichts.<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
* Shop: [http://hausautomatisierung.co/haustechnik/ecometer-ultraschall-fuellstandsanzeige-fuer-heizoeltank/ EcoMeter Ultraschall Füllstandsanzeige für Heizöltank]<br />
* Shop: [http://hausautomatisierung.co/haustechnik/ecometer-s-ultraschall-fuellstandsanzeige-fuer-zisterne-wassertank/ EcoMeter S Ultraschall Füllstandsanzeige für Zisterne, Wassertank]<br />
* Hersteller: [http://tekelek.ie/?ddownload=1408 Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Knxd&diff=22359Knxd2017-08-25T10:49:08Z<p>Eisler: cmake zu Jessie hinzugefügt</p>
<hr />
<div>= knxd mit einem IP Gateway einrichten =<br />
Damit FHEM auf den KNX Bus zugreifen kann, benötigt man ein passendes Interface<br />
<br />
Es gibt:<br />
<br />
* RS232<br />
* USB<br />
* IP<br />
<br />
Ich beschreibe die Einrichtung von knxd mit einem IP Gateway auf einen Raspberry Pi2 mit Wheezy oder Jessie.<br />
<br />
== Installation ==<br />
<br />
<br />
'''1. als erstes müssen folgende Pakete installiert werden (Referenz Debian Jessie):'''<br />
<syntaxhighlight lang="bash">sudo apt-get update<br />
sudo apt-get install debhelper cdbs automake libtool libusb-1.0-0-dev git-core build-essential libsystemd-daemon-dev dh-systemd libev-dev cmake<br />
</syntaxhighlight><br />
<br />
'''1.1 als erstes müssen folgende Pakete installiert werden (Referenz Debian Stretch):'''<br />
<syntaxhighlight lang="bash">sudo apt-get update<br />
sudo apt-get install debhelper cdbs automake libtool libusb-1.0-0-dev git-core build-essential libsystemd-dev dh-systemd libev-dev cmake<br />
</syntaxhighlight><br />
<br />
<br />
'''2. knxd herunterladen und installieren'''<br />
Achtung: Wenn Abhängigkeiten fehlen, dann installiere diese nach. Nicht einfach mittels "-d" diese übergehen!<br />
<syntaxhighlight lang="bash"><br />
git clone https://github.com/knxd/knxd.git<br />
cd knxd<br />
git checkout stable<br />
dpkg-buildpackage -b -uc<br />
cd ..<br />
sudo dpkg -i knxd_*.deb knxd-tools_*.deb<br />
</syntaxhighlight><br />
<br />
== Konfiguration ==<br />
'''1. Ohne systemd'''<br />
<br />
es muss als nächstes die Konfigurationsdatei editiert werden.<br />
<br />
das geht mit:<br />
<syntaxhighlight lang="bash"><br />
sudo nano /etc/default/knxd <br />
</syntaxhighlight><br />
dann folgende Einträge anpassen:<br />
<syntaxhighlight lang="bash"><br />
DAEMON_ARGS="-u /tmp/eib -u /var/run/knx -i -b ipt:192.168.188.XX"<br />
</syntaxhighlight><br />
und<br />
<syntaxhighlight lang="bash"><br />
START_KNXD=YES<br />
</syntaxhighlight><br />
'''2. Mit systemd z. B. für Debian Jessie'''<br />
<br />
Die Konfigurationsdatei bei Jessie hat sich wegen der Nutzung von systemd geändert:<br />
<syntaxhighlight lang="bash"><br />
sudo nano /etc/knxd.conf <br />
</syntaxhighlight><br />
dann folgende Einträge anpassen:<br />
<syntaxhighlight lang="bash"><br />
KNXD_OPTS="-u /tmp/eib -u /var/run/knx -b ipt:192.168.188.XX"<br />
</syntaxhighlight><br />
und<br />
<syntaxhighlight lang="bash"><br />
START_KNXD=YES<br />
</syntaxhighlight><br />
== knxd Status überprüfen ==<br />
<syntaxhighlight lang="bash"><br />
/etc/init.d/knxd status<br />
</syntaxhighlight><br />
<br />
== FAQ ==<br />
'''Wie wird eibd vorher deinstalliert?'''<br />
<syntaxhighlight lang="bash"><br />
sudo rm -r /usr/local/bin/{eibd,knxtool,group*} /usr/local/lib/lib{eib,pthsem}*.so* /usr/local/include/pth*<br />
</syntaxhighlight><br />
<br />
'''folgender Fehler: dpkg-buildpackage: Fehler: Fehler-Exitstatus von debian/rules build war 2'''<br />
<syntaxhighlight lang="bash"><br />
sudo apt-get install git-core build-essential<br />
</syntaxhighlight><br />
<br />
'''Fehler: dpkg-buildpackage: error: fakeroot not found, either install the fakeroot <....> '''<br />
<syntaxhighlight lang="bash"><br />
sudo apt-get install fakeroot dpkg-dev<br />
</syntaxhighlight><br />
<br />
== Links ==<br />
[[Benutzer:Marthinx]]<br />
<br />
[https://github.com/knxd/knxd Github knxd]<br />
<br />
[https://knx-user-forum.de/forum/projektforen/knxd/1049547-grundlagen-zum-knxd-mit-installationsanleitung-vor-dem-schreiben-lesen Forums-Thread zu knxd. Sehr informativ.]<br />
<br />
[[Kategorie:Examples]]<br />
[[Kategorie:EIB/KNX]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=21410Proteus EcoMeter2017-04-29T13:26:47Z<p>Eisler: </p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zur Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=EcoMeter.png<br />
|Bildbeschreibung=EcoMeter Ultraschall Füllstandsanzeige für Heizöltank<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 433,92MHz, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Tekelek<br />
}}<br />
== Features ==<br />
EcoMeter für Heizöl liefert alle 60 Minuten einen Messwert<br />
<br />
EcoMeter S für Zisterne, Wassertank liefert alle 30 Minuten einen Messwert <br />
<br />
Wenn der Sensor eine Füllstandänderung von 3cm pro Minute erkennt, geht der Sensor in den FastModus, d.h. es werden alle 2 - 3 Sekunden neue Werte an den Ecomonitor kommuniziert. Dies ist hilfreich bei einem Leck oder beim Nachtanken. Der FastModus, vergleichbar mit dem Modus nach dem Koppeln, dauert dann ca. 10 Minuten an, so dass die Batterie nicht leer gesaugt wird.<br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== Identifikation ===<br />
Das Proteus EcoMeter verwendet für die Anbindung der seriellen Kommunikation an die USB-Schnittstelle einen sehr weit verbreiteten Chip der Familie <code>CP210x UART Bridges</code>. Dieser Baustein hat die USB <code>ID 10c4:ea60</code> über die auch der Name in <code>/dev/serial/by-id</code> abgeleitet wird. Hat man mehrere Geräte die mit diesem Chip arbeiten (z.B. den optischen Adapter von Viessmann für [[Vitotronic_200_(Viessmann_Heizungssteuerung)|VCONTROL]]) am gleichen Rechner, so werden diese unter <code>lsusb</code> mit identischer ID gelistet, aber nur einer erhält den passenden Namen unter <code>/dev/serial/by-id</code>. Sie sind also auf diese Weise nicht unterscheidbar. Die kurzen Gerätenamen <code>/dev/ttyUSBx</code> werden willkürlich zugeordnet. Damit sind die Geräte auch nicht unterscheidbar.<br />
<br />
Bleibt noch der Pfad wenn man die Geräte immer in die gleiche Buchse steckt. Diese Pfade werden unter Linux in <code>/dev/serial/by-path</code> angelegt. Hier kann man einzelne Buchsen (auch von Hubs) identifizieren. Die Namen enthalten jedoch Doppelpunkte und FHEM verkraftet keine Gerätenamen mit Doppelpunkten. <small>''Wer weiß warum bitte hier Lösung eintragen.''</small> Um diese ohnehin unhandlichen Namen kürzer und verträglicher zu bekommen, kann man Symbolische Links anlegen. Dazu erzeugt man am besten in <code>/opt/fhem</code> ein Verzeichnis <code>dev</code> und verlinkt alle für FHEM relevanten Geräte dort hin. Also in meinem Beispiel TEK603 und VCONTROL:<br />
<source lang=bash><br />
cd /opt/fhem<br />
mkdir dev<br />
cd dev<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.3:1.0-port0 heizung<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.2:1.0-port0 oelpegel<br />
</source><br />
Solange man die beiden Geräte immer in die gleiche Buchse steckt, werden sie ab jetzt immer korrekt zugeordnet:<br />
<source lang=text><br />
defmod Oelpegel TEK603 /opt/fhem/dev/oelpegel<br />
defmod Heizung VCONTROL /opt/fhem/dev/heizung /opt/fhem/mycfg/vitoladens_300-C_J3Ra-24.cfg 120<br />
</source><br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
<source lang=text><br />
2017-03-03_13:07:11 Oelpegel CONNECTED<br />
2017-03-03_13:08:27 Oelpegel Time: 13:05:21<br />
2017-03-03_13:08:27 Oelpegel Temperature: 18.33<br />
2017-03-03_13:08:27 Oelpegel Ullage: 100<br />
2017-03-03_13:08:27 Oelpegel RemainingUsableLevel: 3227<br />
2017-03-03_13:08:27 Oelpegel RemainingUsablePercent: 31.0<br />
2017-03-03_13:08:27 Oelpegel TotalUsableCapacity: 10414<br />
</source><br />
In den ersten 10 Minuten nach dem Anlernen, befindet sich das Gerät im Echtzeit-Modus. Das bedeutet es werden mehrere Messungen pro Sekunde übertragen. Das würde die Batterie sehr schnell lehren. Daher schaltet das Gerät nach 10 Minuten in den Normalbetrieb, in dem nur noch ganz grob alle 30 Minuten Werte übertragen werden. Die Übertragung zu FHEM findet auch nur statt, wenn über die Funkstrecke Daten vom Sensor kommen. Das führt zu der Situation, dass nach diesen 10 Minuten ein neu eingerichtetes <code>TEK603</code> Modul sehr lange (Stunden ?) keine Daten anzeigt, obwohl das Display der Proteus Daten anzeigt. Das liegt einfach daran, dass dieses Display den zuletzt gespeicherten Messwert anzeigt egal wie lange der her ist. Übertragen wird bis zum nächsten Wert auf der Funkstrecke nichts.<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
* Shop: [http://hausautomatisierung.co/haustechnik/ecometer-ultraschall-fuellstandsanzeige-fuer-heizoeltank/ EcoMeter Ultraschall Füllstandsanzeige für Heizöltank]<br />
* Shop: [http://hausautomatisierung.co/haustechnik/ecometer-s-ultraschall-fuellstandsanzeige-fuer-zisterne-wassertank/ EcoMeter S Ultraschall Füllstandsanzeige für Zisterne, Wassertank]<br />
* Hersteller: [https://proteus-meter.com/faq/ Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=21409Proteus EcoMeter2017-04-29T12:52:49Z<p>Eisler: </p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zur Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=EcoMeter.png<br />
|Bildbeschreibung=EcoMeter Ultraschall Füllstandsanzeige für Heizöltank<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 433,92MHz, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Tekelek<br />
}}<br />
== Features ==<br />
EcoMeter liefert alle 60 Minuten einen Messwert<br />
EcoMeter liefert alle 30 Minuten einen Messwert und bei schnellen Änderungen<br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== Identifikation ===<br />
Das Proteus EcoMeter verwendet für die Anbindung der seriellen Kommunikation an die USB-Schnittstelle einen sehr weit verbreiteten Chip der Familie <code>CP210x UART Bridges</code>. Dieser Baustein hat die USB <code>ID 10c4:ea60</code> über die auch der Name in <code>/dev/serial/by-id</code> abgeleitet wird. Hat man mehrere Geräte die mit diesem Chip arbeiten (z.B. den optischen Adapter von Viessmann für [[Vitotronic_200_(Viessmann_Heizungssteuerung)|VCONTROL]]) am gleichen Rechner, so werden diese unter <code>lsusb</code> mit identischer ID gelistet, aber nur einer erhält den passenden Namen unter <code>/dev/serial/by-id</code>. Sie sind also auf diese Weise nicht unterscheidbar. Die kurzen Gerätenamen <code>/dev/ttyUSBx</code> werden willkürlich zugeordnet. Damit sind die Geräte auch nicht unterscheidbar.<br />
<br />
Bleibt noch der Pfad wenn man die Geräte immer in die gleiche Buchse steckt. Diese Pfade werden unter Linux in <code>/dev/serial/by-path</code> angelegt. Hier kann man einzelne Buchsen (auch von Hubs) identifizieren. Die Namen enthalten jedoch Doppelpunkte und FHEM verkraftet keine Gerätenamen mit Doppelpunkten. <small>''Wer weiß warum bitte hier Lösung eintragen.''</small> Um diese ohnehin unhandlichen Namen kürzer und verträglicher zu bekommen, kann man Symbolische Links anlegen. Dazu erzeugt man am besten in <code>/opt/fhem</code> ein Verzeichnis <code>dev</code> und verlinkt alle für FHEM relevanten Geräte dort hin. Also in meinem Beispiel TEK603 und VCONTROL:<br />
<source lang=bash><br />
cd /opt/fhem<br />
mkdir dev<br />
cd dev<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.3:1.0-port0 heizung<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.2:1.0-port0 oelpegel<br />
</source><br />
Solange man die beiden Geräte immer in die gleiche Buchse steckt, werden sie ab jetzt immer korrekt zugeordnet:<br />
<source lang=text><br />
defmod Oelpegel TEK603 /opt/fhem/dev/oelpegel<br />
defmod Heizung VCONTROL /opt/fhem/dev/heizung /opt/fhem/mycfg/vitoladens_300-C_J3Ra-24.cfg 120<br />
</source><br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
<source lang=text><br />
2017-03-03_13:07:11 Oelpegel CONNECTED<br />
2017-03-03_13:08:27 Oelpegel Time: 13:05:21<br />
2017-03-03_13:08:27 Oelpegel Temperature: 18.33<br />
2017-03-03_13:08:27 Oelpegel Ullage: 100<br />
2017-03-03_13:08:27 Oelpegel RemainingUsableLevel: 3227<br />
2017-03-03_13:08:27 Oelpegel RemainingUsablePercent: 31.0<br />
2017-03-03_13:08:27 Oelpegel TotalUsableCapacity: 10414<br />
</source><br />
In den ersten 10 Minuten nach dem Anlernen, befindet sich das Gerät im Echtzeit-Modus. Das bedeutet es werden mehrere Messungen pro Sekunde übertragen. Das würde die Batterie sehr schnell lehren. Daher schaltet das Gerät nach 10 Minuten in den Normalbetrieb, in dem nur noch ganz grob alle 30 Minuten Werte übertragen werden. Die Übertragung zu FHEM findet auch nur statt, wenn über die Funkstrecke Daten vom Sensor kommen. Das führt zu der Situation, dass nach diesen 10 Minuten ein neu eingerichtetes <code>TEK603</code> Modul sehr lange (Stunden ?) keine Daten anzeigt, obwohl das Display der Proteus Daten anzeigt. Das liegt einfach daran, dass dieses Display den zuletzt gespeicherten Messwert anzeigt egal wie lange der her ist. Übertragen wird bis zum nächsten Wert auf der Funkstrecke nichts.<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
* Shop: [http://hausautomatisierung.co/haustechnik/ecometer-ultraschall-fuellstandsanzeige-fuer-heizoeltank/ EcoMeter Ultraschall Füllstandsanzeige für Heizöltank]<br />
* Shop: [http://hausautomatisierung.co/haustechnik/ecometer-s-ultraschall-fuellstandsanzeige-fuer-zisterne-wassertank/ EcoMeter S Ultraschall Füllstandsanzeige für Zisterne, Wassertank]<br />
* Hersteller: [https://proteus-meter.com/faq/ Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=21408Proteus EcoMeter2017-04-29T12:52:03Z<p>Eisler: </p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zur Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=EcoMeter.png<br />
|Bildbeschreibung=EcoMeter Ultraschall Füllstandsanzeige für Heizöltank<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 433,92MHz, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Tekelek<br />
}}<br />
== Features ==<br />
EcoMeter liefert alle 60 Minuten einen Messwert<br />
EcoMeter liefert alle 30 Minuten einen Messwert und bei schnellen Änderungen<br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== Identifikation ===<br />
Das Proteus EcoMeter verwendet für die Anbindung der seriellen Kommunikation an die USB-Schnittstelle einen sehr weit verbreiteten Chip der Familie <code>CP210x UART Bridges</code>. Dieser Baustein hat die USB <code>ID 10c4:ea60</code> über die auch der Name in <code>/dev/serial/by-id</code> abgeleitet wird. Hat man mehrere Geräte die mit diesem Chip arbeiten (z.B. den optischen Adapter von Viessmann für [[Vitotronic_200_(Viessmann_Heizungssteuerung)|VCONTROL]]) am gleichen Rechner, so werden diese unter <code>lsusb</code> mit identischer ID gelistet, aber nur einer erhält den passenden Namen unter <code>/dev/serial/by-id</code>. Sie sind also auf diese Weise nicht unterscheidbar. Die kurzen Gerätenamen <code>/dev/ttyUSBx</code> werden willkürlich zugeordnet. Damit sind die Geräte auch nicht unterscheidbar.<br />
<br />
Bleibt noch der Pfad wenn man die Geräte immer in die gleiche Buchse steckt. Diese Pfade werden unter Linux in <code>/dev/serial/by-path</code> angelegt. Hier kann man einzelne Buchsen (auch von Hubs) identifizieren. Die Namen enthalten jedoch Doppelpunkte und FHEM verkraftet keine Gerätenamen mit Doppelpunkten. <small>''Wer weiß warum bitte hier Lösung eintragen.''</small> Um diese ohnehin unhandlichen Namen kürzer und verträglicher zu bekommen, kann man Symbolische Links anlegen. Dazu erzeugt man am besten in <code>/opt/fhem</code> ein Verzeichnis <code>dev</code> und verlinkt alle für FHEM relevanten Geräte dort hin. Also in meinem Beispiel TEK603 und VCONTROL:<br />
<source lang=bash><br />
cd /opt/fhem<br />
mkdir dev<br />
cd dev<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.3:1.0-port0 heizung<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.2:1.0-port0 oelpegel<br />
</source><br />
Solange man die beiden Geräte immer in die gleiche Buchse steckt, werden sie ab jetzt immer korrekt zugeordnet:<br />
<source lang=text><br />
defmod Oelpegel TEK603 /opt/fhem/dev/oelpegel<br />
defmod Heizung VCONTROL /opt/fhem/dev/heizung /opt/fhem/mycfg/vitoladens_300-C_J3Ra-24.cfg 120<br />
</source><br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
<source lang=text><br />
2017-03-03_13:07:11 Oelpegel CONNECTED<br />
2017-03-03_13:08:27 Oelpegel Time: 13:05:21<br />
2017-03-03_13:08:27 Oelpegel Temperature: 18.33<br />
2017-03-03_13:08:27 Oelpegel Ullage: 100<br />
2017-03-03_13:08:27 Oelpegel RemainingUsableLevel: 3227<br />
2017-03-03_13:08:27 Oelpegel RemainingUsablePercent: 31.0<br />
2017-03-03_13:08:27 Oelpegel TotalUsableCapacity: 10414<br />
</source><br />
In den ersten 10 Minuten nach dem Anlernen, befindet sich das Gerät im Echtzeit-Modus. Das bedeutet es werden mehrere Messungen pro Sekunde übertragen. Das würde die Batterie sehr schnell lehren. Daher schaltet das Gerät nach 10 Minuten in den Normalbetrieb, in dem nur noch ganz grob alle 30 Minuten Werte übertragen werden. Die Übertragung zu FHEM findet auch nur statt, wenn über die Funkstrecke Daten vom Sensor kommen. Das führt zu der Situation, dass nach diesen 10 Minuten ein neu eingerichtetes <code>TEK603</code> Modul sehr lange (Stunden ?) keine Daten anzeigt, obwohl das Display der Proteus Daten anzeigt. Das liegt einfach daran, dass dieses Display den zuletzt gespeicherten Messwert anzeigt egal wie lange der her ist. Übertragen wird bis zum nächsten Wert auf der Funkstrecke nichts.<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
* Hersteller: [http://hausautomatisierung.co/haustechnik/ecometer-ultraschall-fuellstandsanzeige-fuer-heizoeltank/ EcoMeter Ultraschall Füllstandsanzeige für Heizöltank]<br />
* Hersteller: [http://hausautomatisierung.co/haustechnik/ecometer-s-ultraschall-fuellstandsanzeige-fuer-zisterne-wassertank/ EcoMeter S Ultraschall Füllstandsanzeige für Zisterne, Wassertank]<br />
* Hersteller: [https://proteus-meter.com/faq/ Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=21407Proteus EcoMeter2017-04-29T12:46:57Z<p>Eisler: </p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zur Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=EcoMeter.png<br />
|Bildbeschreibung=EcoMeter Ultraschall Füllstandsanzeige für Heizöltank<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 433,92MHz, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Tekelek<br />
}}<br />
== Features ==<br />
EcoMeter liefert alle 60 Minuten einen Messwert<br />
EcoMeter liefert alle 30 Minuten einen Messwert und bei schnellen Änderungen<br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== Identifikation ===<br />
Das Proteus EcoMeter verwendet für die Anbindung der seriellen Kommunikation an die USB-Schnittstelle einen sehr weit verbreiteten Chip der Familie <code>CP210x UART Bridges</code>. Dieser Baustein hat die USB <code>ID 10c4:ea60</code> über die auch der Name in <code>/dev/serial/by-id</code> abgeleitet wird. Hat man mehrere Geräte die mit diesem Chip arbeiten (z.B. den optischen Adapter von Viessmann für [[Vitotronic_200_(Viessmann_Heizungssteuerung)|VCONTROL]]) am gleichen Rechner, so werden diese unter <code>lsusb</code> mit identischer ID gelistet, aber nur einer erhält den passenden Namen unter <code>/dev/serial/by-id</code>. Sie sind also auf diese Weise nicht unterscheidbar. Die kurzen Gerätenamen <code>/dev/ttyUSBx</code> werden willkürlich zugeordnet. Damit sind die Geräte auch nicht unterscheidbar.<br />
<br />
Bleibt noch der Pfad wenn man die Geräte immer in die gleiche Buchse steckt. Diese Pfade werden unter Linux in <code>/dev/serial/by-path</code> angelegt. Hier kann man einzelne Buchsen (auch von Hubs) identifizieren. Die Namen enthalten jedoch Doppelpunkte und FHEM verkraftet keine Gerätenamen mit Doppelpunkten. <small>''Wer weiß warum bitte hier Lösung eintragen.''</small> Um diese ohnehin unhandlichen Namen kürzer und verträglicher zu bekommen, kann man Symbolische Links anlegen. Dazu erzeugt man am besten in <code>/opt/fhem</code> ein Verzeichnis <code>dev</code> und verlinkt alle für FHEM relevanten Geräte dort hin. Also in meinem Beispiel TEK603 und VCONTROL:<br />
<source lang=bash><br />
cd /opt/fhem<br />
mkdir dev<br />
cd dev<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.3:1.0-port0 heizung<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.2:1.0-port0 oelpegel<br />
</source><br />
Solange man die beiden Geräte immer in die gleiche Buchse steckt, werden sie ab jetzt immer korrekt zugeordnet:<br />
<source lang=text><br />
defmod Oelpegel TEK603 /opt/fhem/dev/oelpegel<br />
defmod Heizung VCONTROL /opt/fhem/dev/heizung /opt/fhem/mycfg/vitoladens_300-C_J3Ra-24.cfg 120<br />
</source><br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
<source lang=text><br />
2017-03-03_13:07:11 Oelpegel CONNECTED<br />
2017-03-03_13:08:27 Oelpegel Time: 13:05:21<br />
2017-03-03_13:08:27 Oelpegel Temperature: 18.33<br />
2017-03-03_13:08:27 Oelpegel Ullage: 100<br />
2017-03-03_13:08:27 Oelpegel RemainingUsableLevel: 3227<br />
2017-03-03_13:08:27 Oelpegel RemainingUsablePercent: 31.0<br />
2017-03-03_13:08:27 Oelpegel TotalUsableCapacity: 10414<br />
</source><br />
In den ersten 10 Minuten nach dem Anlernen, befindet sich das Gerät im Echtzeit-Modus. Das bedeutet es werden mehrere Messungen pro Sekunde übertragen. Das würde die Batterie sehr schnell lehren. Daher schaltet das Gerät nach 10 Minuten in den Normalbetrieb, in dem nur noch ganz grob alle 30 Minuten Werte übertragen werden. Die Übertragung zu FHEM findet auch nur statt, wenn über die Funkstrecke Daten vom Sensor kommen. Das führt zu der Situation, dass nach diesen 10 Minuten ein neu eingerichtetes <code>TEK603</code> Modul sehr lange (Stunden ?) keine Daten anzeigt, obwohl das Display der Proteus Daten anzeigt. Das liegt einfach daran, dass dieses Display den zuletzt gespeicherten Messwert anzeigt egal wie lange der her ist. Übertragen wird bis zum nächsten Wert auf der Funkstrecke nichts.<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
* Hersteller: [https://proteus-meter.com/produkte/proteus-ecometer/ Shop]<br />
* Hersteller: [https://proteus-meter.com/faq/ Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=21406Proteus EcoMeter2017-04-29T12:46:09Z<p>Eisler: </p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zur Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=EcoMeter.png<br />
|Bildbeschreibung=todo<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 433,92MHz, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Tekelek<br />
}}<br />
== Features ==<br />
EcoMeter liefert alle 60 Minuten einen Messwert<br />
EcoMeter liefert alle 30 Minuten einen Messwert und bei schnellen Änderungen<br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== Identifikation ===<br />
Das Proteus EcoMeter verwendet für die Anbindung der seriellen Kommunikation an die USB-Schnittstelle einen sehr weit verbreiteten Chip der Familie <code>CP210x UART Bridges</code>. Dieser Baustein hat die USB <code>ID 10c4:ea60</code> über die auch der Name in <code>/dev/serial/by-id</code> abgeleitet wird. Hat man mehrere Geräte die mit diesem Chip arbeiten (z.B. den optischen Adapter von Viessmann für [[Vitotronic_200_(Viessmann_Heizungssteuerung)|VCONTROL]]) am gleichen Rechner, so werden diese unter <code>lsusb</code> mit identischer ID gelistet, aber nur einer erhält den passenden Namen unter <code>/dev/serial/by-id</code>. Sie sind also auf diese Weise nicht unterscheidbar. Die kurzen Gerätenamen <code>/dev/ttyUSBx</code> werden willkürlich zugeordnet. Damit sind die Geräte auch nicht unterscheidbar.<br />
<br />
Bleibt noch der Pfad wenn man die Geräte immer in die gleiche Buchse steckt. Diese Pfade werden unter Linux in <code>/dev/serial/by-path</code> angelegt. Hier kann man einzelne Buchsen (auch von Hubs) identifizieren. Die Namen enthalten jedoch Doppelpunkte und FHEM verkraftet keine Gerätenamen mit Doppelpunkten. <small>''Wer weiß warum bitte hier Lösung eintragen.''</small> Um diese ohnehin unhandlichen Namen kürzer und verträglicher zu bekommen, kann man Symbolische Links anlegen. Dazu erzeugt man am besten in <code>/opt/fhem</code> ein Verzeichnis <code>dev</code> und verlinkt alle für FHEM relevanten Geräte dort hin. Also in meinem Beispiel TEK603 und VCONTROL:<br />
<source lang=bash><br />
cd /opt/fhem<br />
mkdir dev<br />
cd dev<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.3:1.0-port0 heizung<br />
ln -s /dev/serial/by-path/pci-0000:00:14.0-usb-0:4.2:1.0-port0 oelpegel<br />
</source><br />
Solange man die beiden Geräte immer in die gleiche Buchse steckt, werden sie ab jetzt immer korrekt zugeordnet:<br />
<source lang=text><br />
defmod Oelpegel TEK603 /opt/fhem/dev/oelpegel<br />
defmod Heizung VCONTROL /opt/fhem/dev/heizung /opt/fhem/mycfg/vitoladens_300-C_J3Ra-24.cfg 120<br />
</source><br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
<source lang=text><br />
2017-03-03_13:07:11 Oelpegel CONNECTED<br />
2017-03-03_13:08:27 Oelpegel Time: 13:05:21<br />
2017-03-03_13:08:27 Oelpegel Temperature: 18.33<br />
2017-03-03_13:08:27 Oelpegel Ullage: 100<br />
2017-03-03_13:08:27 Oelpegel RemainingUsableLevel: 3227<br />
2017-03-03_13:08:27 Oelpegel RemainingUsablePercent: 31.0<br />
2017-03-03_13:08:27 Oelpegel TotalUsableCapacity: 10414<br />
</source><br />
In den ersten 10 Minuten nach dem Anlernen, befindet sich das Gerät im Echtzeit-Modus. Das bedeutet es werden mehrere Messungen pro Sekunde übertragen. Das würde die Batterie sehr schnell lehren. Daher schaltet das Gerät nach 10 Minuten in den Normalbetrieb, in dem nur noch ganz grob alle 30 Minuten Werte übertragen werden. Die Übertragung zu FHEM findet auch nur statt, wenn über die Funkstrecke Daten vom Sensor kommen. Das führt zu der Situation, dass nach diesen 10 Minuten ein neu eingerichtetes <code>TEK603</code> Modul sehr lange (Stunden ?) keine Daten anzeigt, obwohl das Display der Proteus Daten anzeigt. Das liegt einfach daran, dass dieses Display den zuletzt gespeicherten Messwert anzeigt egal wie lange der her ist. Übertragen wird bis zum nächsten Wert auf der Funkstrecke nichts.<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
* Hersteller: [https://proteus-meter.com/produkte/proteus-ecometer/ Shop]<br />
* Hersteller: [https://proteus-meter.com/faq/ Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=MQTT_Einf%C3%BChrung_Teil_3&diff=21116MQTT Einführung Teil 32017-04-02T07:40:16Z<p>Eisler: </p>
<hr />
<div>= MQTT Einführung Teil 3 =<br />
Zeit sich die Hände schmutzig zu machen<br />
<br />
<br />
'''NOCH NICHT GANZ FERTIG'''<br />
<br />
<br />
== Übersicht ==<br />
Im folgenden basteln wir einen einfachen Temperatursensor.<br />
<br />
Das ist nicht aufregend. Jedoch ist der Code im Originalzustand sehr gut überschaubar. Man kann daher gut die Änderungen sehen.<br />
<br />
== Originales Projekt ==<br />
[http://fluuux.de/2012/10/arduino-temperatur-und-luftfeuchtigkeit-mit-dem-dht22-prufen/ hier bitte nachlesen]<br />
<br />
Mit freundlicher Genehmigung des Autors hier der originale Quellcode:<br />
<br />
<syntaxhighlight lang="arduino"><br />
#include "DHT.h"<br />
<br />
#define DHTPIN 9 <br />
#define DHTTYPE DHT22 //DHT11, DHT21, DHT22<br />
<br />
DHT dht(DHTPIN, DHTTYPE);<br />
<br />
void setup() <br />
{<br />
Serial.begin(9600); <br />
Serial.println("DHT22 - Test!");<br />
<br />
dht.begin();<br />
}<br />
<br />
void loop() <br />
{<br />
float h = dht.readHumidity(); //Luftfeuchte auslesen<br />
float t = dht.readTemperature(); //Temperatur auslesen<br />
<br />
// Prüfen ob eine gültige Zahl zurückgegeben wird. Wenn NaN (not a number) zurückgegeben wird, dann Fehler ausgeben.<br />
if (isnan(t) || isnan(h)) <br />
{<br />
Serial.println("DHT22 konnte nicht ausgelesen werden");<br />
} <br />
else<br />
{<br />
Serial.print("Luftfeuchte: "); <br />
Serial.print(h);<br />
Serial.print(" %\t");<br />
Serial.print("Temperatur: "); <br />
Serial.print(t);<br />
Serial.println(" C");<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
=== Benötigte Hardware ===<br />
* Arduino<br />
* DHT-22 Sensor (nicht der Beste, aber seine Verwendung hält den Code einfach)<br />
* 10 kOhm Widerstand<br />
* Steckbrett<br />
* Drähte<br />
<br />
Zusätzlich<br />
* Ethernetshield mit W5100 Chip<br />
* MQTT Broker (Testweise: 37.187.106.16 => IP von test.mosquitto.org)<br />
<br />
== Kurze Beschreibung was der originale Code tut ==<br />
* Zeilen 1-6: Library einbinden, PIN festlegen, initialisieren.<br />
* Zeilen 8-14: Serielle Schnittstelle konfigurieren, netten Text schreiben...<br />
* Zeilen 18-19: Sensorwerte auslesen<br />
* Zeilen 21-25: Fehlerbehandlung<br />
* Zeilen 26-34: Sensorwerte mit Beschreibung an die serielle Schnittstelle senden<br />
<br />
=== Bibliotheken die zu installieren sind ===<br />
Anmerkung:<br />
<br />
Die Arduino IDE bietet viele Möglichkeiten Bibliotheken einzubinden. Bevorzugt verwendet man den eingebauten Library-Manager. Wer das nicht will, kann auch die Bibliotheken als ZIP Datei herunterladen, und dann mit "Bibliothek aus ZIP Datei hinzufügen" einbinden.<br />
<br />
Im folgenden die Links zu den ZIP Dateien<br />
Für den originalen Sketch<br />
* [https://github.com/adafruit/DHT-sensor-library Adafruit DHT Library]<br />
* [https://github.com/adafruit/Adafruit_Sensor Adafruit Sensor Library]<br />
In der Adruino IDE gibt es eine Warnung, ''WARNUNG: Unberechtigter Ordner .github in der Bibliothek 'DHT sensor library'''; diese kann ignoriert werden. Da die Meldung aber immer kommt, löschen wir einfach besagten Ordner ".github" im Ordner der DHT Sensor Library.<br />
<br />
Für MQTT brauchen wir drei weitere Libraries:<br />
* [https://github.com/knolleary/pubsubclient PubSubClient Library, MQTT]<br />
* Ethernet, ist in der Arduino IDE schon mit dabei<br />
* SPI, für das Netzwerkshield, ist auch schon dabei<br />
<br />
== Notwendige Änderungen ==<br />
<br />
Im folgenden bauen wir den Sketch um. Zunächst prüfen wir, was am Sketch an sich geändert werden muss, anschließend fügen wir den MQTT Code hinzu. Zuletzt nutzen wir noch einige MQTT Features für weitere Optimierungen.<br />
<br />
=== Änderungen am Skript selbst ===<br />
Die einfachste Möglichkeit ein Skript auf MQTT umzustellen, ist das Ändern der Ausgabe von Serial.print in ein mqtt.publish. Hier ergibt sich im Sketch ein Problem: Pubsubclient kann keine Werte vom Typ "float" als Payload versenden. Daher müssen wir zwei Konvertierungen hinzufügen:<br />
* dtostrf(h,6, 1, humidity);<br />
* dtostrf(t,6, 1, temperature);<br />
machen den Trick: Nehme float h, benutze insgesamt 6 Stellen, 1 Nachkommastelle und schreibe das Ergebnis in humidity.<br />
<br />
Weiterhin ist es angenehmer, Variablen etc. am Anfang eines Sketches zu definieren, das machen wir auch noch.<br />
<br />
=== Änderungen für MQTT ===<br />
Am einfachsten ist, wir nehmen uns einen der mitgelieferten MQTT Beispielsketche: mqtt_reconnect_nonblocking. Das müssen wir eigentlich nur an den jeweiligen Stellen in den originalen Sketch kopieren.<br />
Dabei sind die IP Adressen anzupassen und eine MAC Adresse zu vergeben.<br />
<br />
Statt oder zusätzlich zu unserer Ausgabe über die serielle Schnittstelle fügen wir noch einen client.publish ein, so dass die Werte auf dem Broker landen.<br />
<br />
Der Vollständigkeit halber, hier der Sketch für das nicht - blockierende MQTT reconnect:<br />
<syntaxhighlight lang="arduino"><br />
/*<br />
Reconnecting MQTT example - non-blocking<br />
<br />
This sketch demonstrates how to keep the client connected<br />
using a non-blocking reconnect function. If the client loses<br />
its connection, it attempts to reconnect every 5 seconds<br />
without blocking the main loop.<br />
<br />
*/<br />
<br />
#include <SPI.h><br />
#include <Ethernet.h><br />
#include <PubSubClient.h><br />
<br />
// Update these with values suitable for your hardware/network.<br />
byte mac[] = { 0xDE, 0xED, 0xBA, 0xFE, 0xFE, 0xED };<br />
IPAddress ip(172, 16, 0, 100);<br />
IPAddress server(172, 16, 0, 2);<br />
<br />
void callback(char* topic, byte* payload, unsigned int length) {<br />
// handle message arrived<br />
}<br />
<br />
EthernetClient ethClient;<br />
PubSubClient client(ethClient);<br />
<br />
long lastReconnectAttempt = 0;<br />
<br />
boolean reconnect() {<br />
if (client.connect("arduinoClient")) {<br />
// Once connected, publish an announcement...<br />
client.publish("outTopic","hello world");<br />
// ... and resubscribe<br />
client.subscribe("inTopic");<br />
}<br />
return client.connected();<br />
}<br />
<br />
void setup()<br />
{<br />
client.setServer(server, 1883);<br />
client.setCallback(callback);<br />
<br />
Ethernet.begin(mac, ip);<br />
delay(1500);<br />
lastReconnectAttempt = 0;<br />
}<br />
<br />
<br />
void loop()<br />
{<br />
if (!client.connected()) {<br />
long now = millis();<br />
if (now - lastReconnectAttempt > 5000) {<br />
lastReconnectAttempt = now;<br />
// Attempt to reconnect<br />
if (reconnect()) {<br />
lastReconnectAttempt = 0;<br />
}<br />
}<br />
} else {<br />
// Client connected<br />
<br />
client.loop();<br />
}<br />
<br />
}<br />
</syntaxhighlight><br />
=== Optimierungsmöglichkeiten === <br />
<br />
==== Unfreiwilliger Netzwerktest ====<br />
Jedesmal wenn die Schleife durchgelaufen wird, bekämen wir eine Nachricht mit der Temperatur und eine mit der Luftfeuchtigkeit. Das ist nicht so wirklich schlau. Hier bieten sich 3 Alternativen an:<br />
* Delay => dumme Idee, blockiert den Arduino, nicht benutzen<br />
* eine nicht-blockierende Methode für den Arduino nehmen => kann man machen<br />
* Senden nur bei Werteänderung => vermutlich das Ressourcenschonendste<br />
<br />
Ich verwende Variante 3.<br />
<br />
Wir benötigen dazu noch zwei weitere Variablen (h_alt und t_alt); jedesmal wenn die Sendeschleife durchlaufen wird, speichern wir h und t in diese Variablen. Zusätzlich benötigt unsere Schleife nach der Fehlerbehandlung noch einen if Zweig, der dafür sorgt, dass nichts getan wird wenn beide Werte sich nicht geändert haben.<br />
<br />
Jetzt können wir MQTT anweisen, die letzten Messwerte retained zu senden. Sonst würden wir erst dann Werte bekommen, wenn sich entweder die Temperatur oder die Luftfeuchte verändert haben.<br />
* client.publish("zuHause/Arduino_1/Kueche/Kuehlschrank/Luftfeuchte",humidity);<br />
wird zu<br />
* client.publish("zuHause/Arduino_1/Kueche/Kuehlschrank/Luftfeuchte",humidity, true);<br />
* das true dahinter ist das Flag für retained Messages<br />
<br />
==== Nachtrag zum Thema Pausen ====<br />
Mit den Codeänderungen oben haben wir schon mal ein dauerhaftes publishen der gleichen Daten verhindert. Jedoch gibt es natürlich noch einige technische Besonderheiten, die wir ebenfalls berücksichtigen sollten:<br />
<br />
Bis jetzt führt unser Sketch bei jedem Durchlauf durch void.loop() eine Messung durch. Das hat zwei Folgen:<br />
* der Sensor ist im Dauerbetrieb<br />
* kleine Schwankungen führen natürlich zu einem erneuten publishen.<br />
Wenn wir den Code, sagen wir, nur alle 2 Minuten ausführen würden, würderd der Sensor weniger belastet. Beim dem Verwendeten spielt es nicht wirklich eine große Rolle, aber es gibt Sensoren die auf einen derart häufigen Zugriff durchaus empfindlich reagieren können.<br />
<br />
Gleichzeitig bekommen wir viele kleine Schwankungen (ich nenne sie mal Messungenauigkeiten) übermittelt, die uns eigentlich nicht interessieren.<br />
<br />
Die einfache Variante wäre wieder ein Delay. Dieses würde recht schnell zu einem Fehler führen: Ein Delay blockiert. Für MQTT bedeutet es, dass keine Keep-alive Pakete mehr gesendet werden. Hätten wir eingehende Nachrichten, dann würden wir diese auch verpassen.<br />
Wir merken uns: nutze niemals Delays.<br />
<br />
Die oben schon angesprochene Lösung, eine nicht blockierende Methode verwenden, ist sehr gut geeignet.<br />
<br />
Wie geht das?<br />
<br />
Zunächst zählt der Arduino seine Laufzeit in Millisekunden. Wir schreiben unseren Temperaturausleseteil in eine kleine Schleife.<br />
* zwei weitere Variablen<br />
** unsigned long previousMillis = 0; //Zählervariable, zählt Millisekunden seit dem letzten Funktionsaufruf nach oben<br />
** const long interval = 120000; //120000 Millisekunden aka 120 Sekunden, das Interval wie oft der Sensor überhaupt benutzt wird<br />
* Drei Zeilen Programmcode mehr:<br />
<br />
<syntaxhighlight lang="arduino"><br />
unsigned long currentMillis = millis();<br />
<br />
if (currentMillis - previousMillis >= interval) {<br />
previousMillis = currentMillis;<br />
<br />
h = dht.readHumidity(); //Luftfeuchte auslesen<br />
t = dht.readTemperature(); //Temperatur auslesen<br />
}<br />
</syntaxhighlight><br />
<br />
==== Last Will & Testament ====<br />
Retten wir auch die Statusmeldungen des Skripts nach MQTT. Dazu ergänzen wir den client.connect Aufruf:<br />
* if (client.connect("Arduino_1")) {<br />
<br />
um folgendes:<br />
* if (client.connect("Arduino_1", "zuHause/Arduino_1", 0, true, "offline")) { <br />
** Arduino_1 nennt sich unser Sensor<br />
** "zuHause/Arduino_1" ist das Topic für dessen Statusmeldungen<br />
** 0 ist die QoS<br />
** true bedeutet, Nachricht retained senden<br />
** "offline" ist das, was auf dem Topic geschrieben werden soll, wenn die Verbindung abbricht<br />
** Anmerkung:<br />
** Unsauberes disconnect wird verursacht durch:<br />
** Abbruch der Netzwerkverbindung<br />
** Protokollfehler (z.B. ungültige Topics, fehlerhafte Payload)<br />
<br />
Warum machen wir das?<br />
* beim Start des Sensors steht nun "online" im Status<br />
* bei einem Sensorfehler werden wir auf den Sensorfehler aufmerksam gemacht "Sensorfehler"<br />
* bricht die Netzwerkverbindung ab, steht automatisch "offline" in dem Topic<br />
* bei einer erfolgreichen Messung mit Datenübertragung steht wieder "online" im Topic<br />
Auf diese Art und Weise haben wir eine aussagekräftige Zustandsmeldung in unserem Topic. Diese können wir bequem mit FHEM überwachen, um bei einem Fehler weitere Maßnahmen einzuleiten. Ein Vergleich des Alters der Sensorwerte wird überflüssig.<br />
<br />
<br />
=== MQTT an sich ===<br />
Wer keinen eigenen Broker hat und (für diesen einen Test) keinen aufsetzen will, kann testweise auch einen öffentlichen Broker benutzen: test.mosquitto.org stellt so einen bereit. Bitte beachten, dass dieser Broker wirklich öffentlich ist. Mit ''ping test.mosquitto.org'' bekommt man die IP Adresse, die man, ich möchte es nochmal betonen, zu Testzwecken, in seinen Sketch schreiben kann.<br />
<br />
Wir benötigen für MQTT entsprechende Topics.<br />
* "zuHause/Arduino_1/Kueche/Kuehlschrank/Luftfeuchte"<br />
* "zuHause/Arduino_1/Kueche/Kuehlschrank/Temperatur"<br />
<br />
== Daus ergibt sich letztlich folgender Sketch ==<br />
<syntaxhighlight lang="arduino"><br />
#include <DHT.h><br />
#include <SPI.h><br />
#include <Ethernet.h><br />
#include <PubSubClient.h><br />
<br />
#define DHTPIN 9 <br />
#define DHTTYPE DHT22 //DHT11, DHT21, DHT22<br />
<br />
DHT dht(DHTPIN, DHTTYPE);<br />
<br />
byte mac[] = { 0xDE, 0xED, 0xBA, 0xFE, 0xFE, 0xED }; //eine MAC Adresse wählen, darf im eigenen Netz nur 1x vorkommen<br />
IPAddress ip(192, 168, 5, 220); //eine gültige IP Adresse für das eigene Netz<br />
IPAddress server(192, 168, 5, 2); //die Adresse wo der eigene MQTT Broker drauf läuft<br />
<br />
void callback(char* topic, byte* payload, unsigned int length) {<br />
// handle message arrived<br />
}<br />
<br />
EthernetClient ethClient;<br />
PubSubClient client(ethClient);<br />
<br />
long lastReconnectAttempt = 0;<br />
<br />
boolean reconnect() {<br />
if (client.connect("Arduino_1", "zuHause/Arduino_1", 0, true, "offline")) {<br />
// Once connected, publish an announcement...<br />
client.publish("zuHause/Arduino_1","online", true);<br />
// ... and resubscribe<br />
client.subscribe("inTopic");<br />
}<br />
return client.connected();<br />
}<br />
static char humidity[15]; //Speicherbereich reservieren um die Fechtigkeit zu speichern<br />
static char temperature[15];<br />
float h = 0.0;<br />
float h_alt = 0.0;<br />
float t = 0.0;<br />
float t_alt = 0.0;<br />
unsigned long previousMillis = 0; //Zählervariable, zählt Millisekunden seit dem letzten Funktionsaufruf nach oben<br />
const long interval = 120000; //120000 Millisekunden aka 120 Sekunden, das Interval wie oft der Sensor überhaupt benutzt wird<br />
<br />
void setup() <br />
{<br />
client.setServer(server, 1883);<br />
client.setCallback(callback);<br />
<br />
Ethernet.begin(mac, ip);<br />
delay(1500);<br />
lastReconnectAttempt = 0;<br />
<br />
Serial.begin(9600); <br />
Serial.println("DHT22 - Test!");<br />
<br />
dht.begin();<br />
}<br />
<br />
void loop() <br />
{<br />
if (!client.connected()) {<br />
long now = millis();<br />
if (now - lastReconnectAttempt > 5000) {<br />
lastReconnectAttempt = now;<br />
// Attempt to reconnect<br />
if (reconnect()) {<br />
lastReconnectAttempt = 0;<br />
}<br />
}<br />
} else {<br />
// Client connected<br />
<br />
client.loop();<br />
}<br />
<br />
unsigned long currentMillis = millis();<br />
<br />
if (currentMillis - previousMillis >= interval) {<br />
previousMillis = currentMillis;<br />
<br />
h = dht.readHumidity(); //Luftfeuchte auslesen<br />
t = dht.readTemperature(); //Temperatur auslesen<br />
}<br />
<br />
// Prüfen ob eine gültige Zahl zurückgegeben wird. Wenn NaN (not a number) zurückgegeben wird, dann Fehler ausgeben.<br />
if (isnan(t) || isnan(h)) <br />
{<br />
Serial.println("DHT22 konnte nicht ausgelesen werden");<br />
client.publish("zuHause/Arduino_1","Sensorfehler",true); //true sendet die Nachricht retained, d.h. die Nachricht bleibt solange auf dem Broker, bis etwas neues kommt<br />
}<br />
else if (h == h_alt && t == t_alt)<br />
{<br />
//nix machen<br />
}<br />
else<br />
{<br />
client.publish("zuHause/Arduino_1","online", true);<br />
dtostrf(h,6, 1, humidity);<br />
dtostrf(t,6, 1, temperature);<br />
client.publish("zuHause/Arduino_1/Kueche/Kuehlschrank/Luftfeuchte",humidity, true);<br />
client.publish("zuHause/Arduino_1/Kueche/Kuehlschrank/Temperatur",temperature, true);<br />
h_alt = h; //den alten Messwert aufheben<br />
t_alt = t; //um nur bei Veränderung zu reagieren<br />
Serial.print("Luftfeuchte: "); <br />
Serial.print(h);<br />
Serial.print(" %\t");<br />
Serial.print("Temperatur: "); <br />
Serial.print(t);<br />
Serial.println(" C");<br />
<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
== Zusammenfassung ==<br />
Um aus einem "normalen" Sketch einen MQTT Sketch zu machen muss man also:<br />
* Netzwerk konfigurieren<br />
* MQTT einrichten<br />
Im wesentlichen kann man einfach den MQTT Beispielsketch "mqtt reconnect nonblocking" in seinen Sketch einbauen.<br />
<br />
Geringe Änderungen im vorhandenen Code sind nötig, um diversen Typen von Variablen als MQTT Payload verwenden zu können<br />
<br />
Als Bonus bekommen wir "vernünftige" Statuswerte für unseren Sensor, die sich einfach in FHEM abfangen und auswerten lassen. Als weiteren Bonus betrachte ich, dass die Netzwerklast sinkt. Zum Vergleich möchte ich hier die Jeelink Sensoren anführen, aber auch viele 433 MHz Sensoren, die einfach im "wenige Sekunden Takt" ihre Werte in der Gegend rumfunken. Von da her kann durch den Einsatz von MQTT-Techniken die Funkbelastung der Umgebung reduziert werden. Einerseits trägt man also weniger zur "Sensorischen Luftverschmutzung" bei, andererseits entlastet man auch sein FHEM vor der Aufgabe, unnötige Werte erst mal zu verwerfen.<br />
<br />
== Danke ==<br />
Hier möchte ich mal Danke sagen. An Beta-User, der seit Teil 1 das Geschreibsel vorab durchliest und immer wertvolle Tipps und Änderungsvorschläge parat hat.<br />
<br />
== Links ==<br />
[http://fluuux.de/2012/10/arduino-temperatur-und-luftfeuchtigkeit-mit-dem-dht22-prufen/ Originales Projekt]<br />
<br />
[https://wiki.fhem.de/wiki/MQTT_Einf%C3%BChrung Teil 1 der MQTT Einführung]<br />
<br />
[https://wiki.fhem.de/wiki/MQTT_Einf%C3%BChrung_Teil_2 Teil 2 der MQTT Einführung]<br />
<br />
[https://forum.fhem.de/index.php/topic,69954.0.html Diskussionsthread im Forum]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=MQTT_Einf%C3%BChrung&diff=20776MQTT Einführung2017-03-18T21:14:40Z<p>Eisler: </p>
<hr />
<div><br />
= MQTT =<br />
<br />
Message Queue Telemetry Transport<br />
<br />
<br />
== Was ist das? ==<br />
<br />
Es handelt sich um ein Protokoll um Daten unter verschiedenen Geräten zu übermitteln. MQTT funktioniert z.B. über eine TCP/IP Verbindung. <br />
(Für die, die etwas verbal posen wollen: Man nennt das M2M, Machine to Machine; im Übrigen handelt es sich bei MQTT um ein Transportprotokoll.)<br />
<br />
<br />
== Grundlegender Aufbau ==<br />
<br />
Herzstück des eigenen MQTT Netzes ist ein Broker. Die mit dem Broker verbundenen Geräte nennen wir der Einfachheit halber mal Clients. (stimmt nicht ganz, aber später lernen wir das genauer kennen)<br />
<br />
<br />
== So tickt MQTT ==<br />
<br />
Wir schreiben/schicken einfach eine Nachricht an den Broker. Wer wann die Nachricht abholt und liest, interessiert an dieser Stelle überhaupt nicht. Das ist einer der großen Vorteile.<br />
<br />
<br />
== Ordnung in das Chaos ==<br />
<br />
Worin liegt nun der Vorteil? Und wie kann nun jemand eine Nachricht lesen?<br />
Hier beginnt das raffinierte Konzept von MQTT:<br />
Wir stellen nicht einfach nur Daten dem Broker zur Verfügung. Wir organisieren sie auch selbst. Das Zauberwort hierfür nennt sich "Topic". <br />
Kann man sich so ähnlich vorstellen wie einen Verzeichnisbaum unter Windows, oder wie eine Datei auf einem Webserver.<br />
Ein anderes Bild für einen "Topic" wäre eine Art schwarzes Brett.<br />
<br />
Ein Topic könnte so lauten:<br />
'''zuHause/1OG/Kueche/Licht/state'''<br />
<br />
Dieses Topic böte sich geradezu an, den Zustand des Küchenlichts im 1. Stock reinzuschreiben.<br />
<br />
Unser kleiner schlauer Lichtschalter könnte in diesem Topic immer den aktuellen Zustand des Lichts notieren. In "MQTT-Sprechweise" würde man sagen, unser Client ist ein Publisher. Er veröffentlicht Informationen.<br />
<br />
Nehmen wir im folgenden einen Sensor:<br />
'''zuHause/1OG/Kueche/Kuehlschrank/Temperatur/state'''<br />
<br />
Das ergäbe ein hübsches Topic für einen im Kühlschrank befindlichen Temperatursensor.<br />
Auch hier hätten wir es mit einem Publisher zu tun.<br />
<br />
Wichtig ist hierbei, dass wir uns nicht um die Technik kümmern müssen. Auch bei der Organisation der Topics haben wir ziemlich freie Hand.<br />
<br />
<br />
== Was kann man jetzt damit anfangen? ==<br />
<br />
Nun wollen wir die Kühlschranktemperatur auf einem Display sehen. Vielleicht lagern wir ja empfindliche Medikamente im Kühlschrank und haben Kinder, die gerne die Kühlschranktür offen lassen?<br />
<br />
Wir nehmen also ein Display und klemmen das auch an unseren Broker. Jetzt möchten wir aber nicht die Temperatur publishen, das macht ja der Sensor. Wir wollen sie lesen. Also melden wir uns mit dem Display beim Broker an und "subscriben" das Topic. Wir teilen dem Broker mit, dass uns diese Information interessiert.<br />
<br />
Unser Display abonniert also die Temperatur. Zukünftig wird der Broker immer versuchen, unserem Display die Temperatur zu übermitteln.<br />
<br />
<br />
== Ah ja. Und was ist daran toll? ==<br />
<br />
Nun, wie wir das Thermometer programmiert haben, wussten wir nichts von dem Display. Wir müssen auch am Thermometer gar nichts mehr verändern. Das bleibt so wie es ist.<br />
<br />
Wenn wir nun ein weiteres Display haben wollen, bauen wir uns eben ein zweites Display und subscriben das Topic ebenfalls beim Broker.<br />
Zukünftig wird er an beide Displays die Information schicken.<br />
<br />
Wenn wir eine grafische Auswertung des Temperaturverlaufs wollen, dann könnten wir das Topic beim Broker zusätzlich mit FHEM subscriben. Temperatur bekommen, in Logfile schreiben, Plot, fertig.<br />
<br />
<br />
== Immer noch: warum ist das so toll? ==<br />
<br />
Nun, bei der Konzeption von MQTT hat man Wert darauf gelegt, dass es ohne große Ressourcen auskommt. Das bedeutet für uns, dass es für viele "Bastelhardware" (Arduino etc.) fertige Libraries gibt. Ich zeige das später. Auch wer gerne mit Javascript, Java, Perl, Python programmiert, findet gut funktionierende Bibliotheken. <br />
Für den "ambitionierten Bastler" bedeutet dies:<br />
Wir können Geräte bauen und programmieren, die sich selbstständig miteinander unterhalten. Ein Taster der Licht an einem entfernten Aktor einschaltet, ist kein Problem. Und zwar ohne FHEM hiermit zu belasten oder es auch nur zu brauchen.<br />
Wir können also sehr schnell unsere Kühlschranktemperatur mit diversen Programmiersprachen auf einer Unzahl von Geräten lesen und auswerten.<br />
<br />
<br />
== Cool, was braucht man? ==<br />
<br />
Einen MQTT Broker; z.B. Mosquitto.<br />
Für den Mikrocontroller der eigenen Wahl eine passende Library. Für Arduinos böte sich der PubSubClient an<br />
Ggfs. ein Analyse-Tool wie MQTT.fx<br />
<br />
<br />
== Nachteile ==<br />
<br />
=== Single Point of Failure ===<br />
<br />
Wo Licht ist, ist bekanntermaßen auch Schatten. Für uns, da wir FHEM zur Haussteuerung einsetzen, stellt sich die erste Frage, warum man seine Geräte nicht einfach gleich an FHEM anbindet, sondern erst noch einen MQTT Broker (letztlich noch ein Stück Software) extra davor setzt.<br />
Möglicher Grund:<br />
MQTT ist besser ausgereift als jedes selbst gestricke Protokoll. Es ist sogar ISO Standard. Es gibt viele Tools und Hilfestellungen dafür; eigene Intelligenz den Geräten beizubringen ist auch recht einfach.<br />
<br />
<br />
=== Sicherheit ===<br />
<br />
Prinzipiell ist MQTT ebenso sicher wie eine Postkarte. Solange man es nicht extra absichert, kann jeder der im eigenen LAN ist (und die Adresse vom Broker kennt) alle Topics mitlesen.<br />
meinHaus/Flur/Haustuer:open / close<br />
Ist da nicht wirklich schlau! <br />
Abhilfe:<br />
==== Username / Passwort ====<br />
Zunächst kann man erst mal einen Username / Passwort vergeben. Da ist zwar auch noch lange nicht sicher, aber zumindest steigert es den Aufwand schon mal. Jetzt muss man zumindest schon mal Pakete sniffen und verstehen, um unbefugt zu lesen oder gar zu publishen.<br />
<br />
==== TLS ====<br />
Um wirklich sicher zu werden, führt kein Weg an TLS vorbei. Leider kann z.B. ein Arduino das schlicht nicht mehr. Irgendwo machen sich der Speicher und die Rechenleistung dann doch bemerkbar.<br />
<br />
=== Änderung der Topic Hierarchie ===<br />
Ja, das ist ein Problem. Wenn man die Hierarchie der Topics ändern will, wird man in den seltensten Fällen drum rum kommen, seinen Programmcode (Arduino..,) anzupassen, neu zu kompilieren und wieder hoch zu laden.<br />
Gleiches gilt, wenn sich z.B. die IP Adresse des Brokers ändert.<br />
<br />
=== Netzwerktraffic ===<br />
Eine weitere Frage, die man sich stellen kann ist eine grundsätzliche:<br />
Welchen Sinn hat es, sein Netzwerk (insbesondere WLAN) mit so Dingen wie Sensordaten zuzukleistern. Das ist nicht völlig unberechtigt. MySensors ist für viele kleine batteriebetriebenen Sensoren vermutlich eine deutlich bessere Wahl. Sensoren mit Akku in ein WLAN einzubinden, ist technisch eine echte Herausforderung. De große Vorteil ist aber, dass man sein WLAN im Fall des Reichweitenendes einfach erweitern kann. WLAN-Repeater, Sache gut.<br />
<br />
== Ausblick ==<br />
Hier endet erst mal der kurze Überblick. Wer neugierig geworden ist, darf sich auf viele weitere spannenden Themen freuen:<br />
<br />
=== QoS ===<br />
Ein weiteres Feature sind die QoS Level von MQTT.<br />
* QoS Level 0: ist eine Art fire and forget. Ob die Daten ankommen, wird nicht weiter geprüft<br />
* QoS Level 1: garantiert die Zustellung der Nachricht; es kann aber auch passieren, dass eine Nachricht öfter zugestellt und empfangen wird<br />
* QoS Level 3: Hier wird garantiert, dass jede Nachricht '''genau 1x''' bei den Empfängern ankommt<br />
<br />
=== Retained Messages ===<br />
Auch eine lustige Sache, lernen wir später kennen. Aber ein Beispiel möchte ich dennoch schon schildern: Wir basteln uns später den oben angesprochenen Temperatursensor und das zugehörige Display. Das erweitern wir um eine blinkende LED, wenn eine bestimmte Temperatur überschritten wird. Quizfrage: woher kennt das Display den gewünschten Schwellenwert? Freilich könnte man ihn im Programmcode hinterlegen. Aber dann ist er fest verdrahtet. Wenn wir ihn einfach nur normal publishen würden, würde das Display ihn erst kennen, wenn der Schwellwert gepublished würde nachdem das Display mit dem Broker verbunden war... Hier kommen retained Messages. Diese werden auch beim Verbinden eines Subscribers gesendet, obwohl es da keine Änderung gab.<br />
<br />
== Links ==<br />
<br />
* [http://mqtt.org Offizielle Homepage von MQTT, englisch]<br />
* [http://www.hivemq.com/blog/mqtt-essentials-part-1-introducing-mqtt Sehr gute Einführung, englisch, sind 5 lesenswerte Teile]<br />
* [https://www.heise.de/developer/artikel/MQTT-Protokoll-fuer-das-Internet-der-Dinge-2168152.html Ein Exkurs von Heise mit Beispielen, deusch, sehr lesenswert]<br />
* [https://forum.fhem.de/index.php/topic,69230.0.html Diskussionsthread im Forum]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Alexa-Fhem&diff=19177Alexa-Fhem2017-01-28T19:28:43Z<p>Eisler: /* Arbeitsweise und Datenfluss */</p>
<hr />
<div>'''Alexa-Fhem''' ist eine in JavaScript und auf NodeJS basierende Software, welche es ermöglicht, der digitalen Amazon Assistentin Alexa zusätzliche Skills für die Heimautomatisierung via FHEM beizubringen. Eine erste funktionierende Version wurde von [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im [https://forum.fhem.de/index.php/topic,60244.0.html Forum] veröffentlicht.<br />
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa<br />
|ModType=x<br />
|ModTechName=<br />
|ModForumArea=Sonstige Systeme<br />
|ModOwner=justme1968<br />
}} <br />
<br />
<br />
==Einführung==<br />
<br />
===Arbeitsweise und Datenfluss===<br />
[[Datei:2gpXyLN.jpg|200px|thumb|right|Grafische Darstellung der beteiligten Komponenten]]<br />
Echo -> AVS -> AWS Lambda -> alexa-fhem -> AWS Lambda -> AVS -> Echo<br />
<br />
*Der Echo (oder ein anderes Alexa/AVS fähiges device) nimmt Audiodaten auf und schickt diese an AVS (Amazon Voice Service) zur Erkennung<br />
*AVS führt die Spracherkennung durch und erzeugt ein Event mit Informationen zu den Erkannten Daten<br />
:*Beim Custom Skill kommen die dazu nötgen Informationen aus dem ''Interaction Model'' der Alexa Skills Konfiguration<br />
:*Beim Home Automation Skill sind die möglichen Sätze fest vorgegeben <br />
*Das Event wird an den unter ''Configruation'' in der Alexa Skills Konfiguration hinterlegten Endpoint geschickt<br />
:*Beim Home Automation Skill ist das zwingend eine AWS Lambda Routine<br />
:*Beim Custom Skill kann das im Prinzip auch ein eigener Web Service sein<br />
*Das Event wird vom <code>lambda.js</code> code an alexa-fhem weitergeleitet<br />
*alexa-fhem steuert FHEM und sendet ein Antwort Event zurück<br />
*<code>lambda.js</code> nimmt diese Antwort entgegen und gibt sie an AVS zurück<br />
*AVS sogt dafür das der echo 'antwortet' und das die Card in der Alexa App erscheint<br />
<br />
===Anmerkungen===<br />
*Ein Skill hat keinen zugriff auf die Audiodaten<br />
*Mit dem Skill API kann ein Skill zu zu keiner Zeit von sich aus aktiv werden und 'einfach' Daten an den Echo schicken oder ihn dazu bringen irgendetwas zu tun.<br />
*Es ist ein kleines Wunder wie schnell die Reaktion auf einen gesprochenen Satz erfolgt wenn man berücksichtigt welchen Weg die Daten insgesamt gehen.<br />
<br />
=== Abgrenzung des '''Alexa Smart Home Skills''' und des '''Alexa Custom Skills''' ===<br />
<br />
Der [[Alexa-Fhem#Smart_Home|Alexa Smart Home Skill]] ist ein Amazon-Alexa-Standard-Skill, der wesentliche Basisfunktionalitäten bereitstellt. Zu diesen gehört im Wesentlichen die Funktionalität, durch Alexa-FHEM bereitgestellte Devices im Alexa-Account des Benutzers anzulegen. Der Alexa Smart Home Skill reagiert auf gesprochene Interaktion in einem beschränkten Umfang. Beispielsweise genügt ein "Alexa, schalte die Wohnzimmerlampe an" um eine Interaktion zwischen Alexa Smart Home Skill und FHEM-Alexa auszulösen. Nach erfolgreicher Einrichtung wird dieser Skill in der Alexa-App bzw. im Web in der Rubrik "Smart Home" als Skill angezeigt.<br />
<br />
Der [[Alexa-Fhem#Custom|Alexa Custom Skill]] ist kein Standard-Smart-Home-Skill, sondern ein individuell entwickelter Skill, so wie alle anderen Skills auch. Er wird daher auch nicht in der Alexa-App unter der Rubrik "Smart Home" angezeigt. Gesprochene Interaktion mit diesem Skill erfolgt dadurch, dass entweder der Skill explizit gestartet wird (z.B. "Alexa, starte [Name des Skills]") oder direkt angesprochen wird (z.B. "Alexa, frage [Name des Skills] wie ist der Status von [Device] "). Der Alexa Custom Skill befindet sich in Entwicklung und wird hinsichtlich seiner Funktionalitäten laufend weiterentwickelt. Die Einrichtung dieses Skills ist grundsätzlich optional, jedoch werden anspruchsvollere Steuerungsmöglichkeiten nur mit diesem realisiert werden können.<br />
<br />
==Installation==<br />
<br />
Grundvoraussetzung für alle folgenden Schritte ist, dass ein Amazon-Account vorhanden ist. Es wird davon ausgegangen, dass bereits für alle folgenden Amazon-Dienste vorab das Konto jeweils eingerichtet wurde, die Einrichtung dieser ist nicht Bestandteil dieser Anleitungen.<br />
<br />
Es sei an dieser Stelle darauf hingewiesen, dass für die Nutzung der Amazon AWS-Dienste zwingend die Daten einer Kreditkarte angegeben werden müssen. Nach gegenwärtigem Kenntnisstand sollen jedoch keine Kosten für die Nutzung der im Rahmen dieses How To beschriebenen Dienste anfallen, sofern diese in einem Rahmen genutzt werden, der selbst eine intensive private Nutzung nicht überschreitet. Der Benutzer sei an dieser Stelle auf die von Amazon veröffentlichten Preislisten verwiesen.<br />
<br />
{{Randnotiz|RNTyp=[g|Info]|RNText=Da die einzelnen Schritte der Anleitung an verschiedenen Stellen unterbrochen und später fortgesetzt werden müssen, empfiehlt es sich, die Anleitung einmal vollständig gelesen zu haben. Dies vermeidet Fehler, die ansonsten geschehen können. Während der Konfiguration bietet es sich an diese Schritte dann parallel in gleichzeitig geöffneten Browserfenster durchzuführen. }}<br />
<br />
<br />
=== Voraussetzungen ===<br />
Folgende grundlegende Voraussetzungen sollten erfüllt sein, bevor du mit der Einrichtung beginnst:<br />
* Amazon Echo oder Amazon Dot<br />
* node.js (vermutlich ab Version 0.12.7, getestet mit 4.2.6. Kann in Debian z.B. mit <source lang="bash" style="width:50%;">sudo apt-get install nodejs-legacy</source> installiert werden)<br />
* Weiterleitung von Port 3000 vom Router aus auf den Rechner, auf dem Alexa-Fhem läuft<br />
* Es empfiehlt sich ein alexa Gerät in FHEM anzulegen.<br />
<br />
=== Alexa-Fhem installieren ===<br />
# Die tgz-Datei unter Linux entpacken (Windows macht die Rechte kaputt!) (Quelle: https://forum.fhem.de/index.php/topic,60244.0.html) (neuere Version verügbar, bitte Hinweise unter Custom Skill beachten:https://forum.fhem.de/index.php/topic,60244.msg540117.html#msg540117) <source lang="bash" style="width:50%;">tar -xzf alexa-fhem-0.1.3.tgz</source><br />
# Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <source lang="bash" style="width:50%;">mv package alexa-fhem</source><br />
# Durch <source lang="bash" style="width:50%;">cd alexa-fhem</source> in das Verzeichnis wechseln<br />
# Mit (kein sudo!) <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren<br />
# SSL Zertifikat erzeugen durch Aufruf von (kein sudo!)<source lang="bash" style="width:50%;">./createKey.sh</source>. Hierbei beachten, dass ein Kennwort vergeben werden soll, das mindestens aus 4 Zeichen besteht.<br />
# Die Datei ''config-sample.json'' nach ''~/.alexa/config.json'' kopieren (~/.alexa gegebenenfalls vorher anlegen) und die Werte auf die eigene Umgebung hin anpassen. Der Filter funktioniert hierbei wie bei [[Homebridge_einrichten#Einstellungen_f.C3.BCr_homebridge|homebridge-fhem]],die folgenden Zeilen sind anzupassen oder zu löschen:<br>"nat-pmp": -> wenn nat-pmp verwendet werden soll: die ip des eigenen routers,<br>"nat-upnp": -> wenn nat-upnp verwendet werden soll: ''true'',<br>"applicationId": -> SkillID aus "Alexa Custom Skill anlegen" Punkt 7 (s.u.),<br>"oauthClientID": -> ''Client Id'' aus Punkt 1. '''Login with Amazon'''<br />
# Durch Aufruf von <source lang="bash" style="width:50%;">./bin/alexa</source> den Dienst starten (kein sudo!)<br />
<br />
Der Start des Alexa-Dienstes auf der Console ist immer dann zu empfehlen, wenn man auf die Ausgaben des Dienstes angewiesen ist und beispielsweise sehen möchte, welche Devices durch den Dienst bereitgestellt werden oder ob Fehler auftreten. Beendet man die Console-Session wird auch der Dienst wieder beendet. Insofern ist die vorgenannte Vorgehensweise nur für ein Debugging zu empfehlen und nicht im Regelbetrieb. Nachfolgend ist beschrieben, wie man den Alexa-Dienst aus FHEM heraus starten / stoppen und neu starten kann.<br />
<br />
=== Alexa-Fhem aus FHEM heraus starten ===<br />
Zunächst das Start-up-Skript aus diesem Post herunterladen [https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271 https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271] und unter /etc/init.d/alexa speichern.<br />
<br />
Das Script geht davon aus, das der alexa-fhem script unter /opt/fhem/alexa-fhem liegt, und die logfiles später unter /opt/fhem/log. Sollte das nicht der Fall sein, muss das Skript angepasst werden.<br />
<br />
Nun folgende Kommandos ausführen:<br />
<source lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa<br />
sudo update-rc.d alexa defaults</source><br />
<br />
In der Datei <code>/etc/sudoers</code> den User fhem für die Nutzung von sudo zulassen (<code>sudo nano /etc/sudoers</code>), z.B. durch Anfügen der nachfolgenden Zeile:<br />
<code>fhem ALL=(ALL) NOPASSWD: ALL</code><br />
<br />
Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):<br />
<br />
<source lang="bash" style="width:75%;">define FHEM.Alexa.Status dummy</source><br />
<br />
<br />
<source lang="bash" style="width:75%;">define FHEM.Alexa dummy<br />
attr FHEM.Alexa event-on-change-reading state<br />
attr FHEM.Alexa webCmd status:start:stop:restart</source><br />
<br />
<br />
<source lang="bash" style="width:75%;">define FHEM.Alexa.DOIF DOIF ([FHEM.Alexa] eq "start") <br />
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa start > /dev/null 2>&1 &")}) <br />
DOELSEIF ([FHEM.Alexa] eq "stop") <br />
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa stop > /dev/null 2>&1 &")}) <br />
DOELSEIF ([FHEM.Alexa] eq "restart") <br />
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa restart > /dev/null 2>&1 &")}) <br />
DOELSEIF ([FHEM.Alexa] eq "status") <br />
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa status > /dev/null 2>&1 &")})</source><br />
<br />
=== Alexa Device mit dem Modul 39_alexa.pm anlegen ===<br />
<br />
Das Modul 39_alexa.pm stellt innerhalb von FHEM verschiedene Attribute z.B. alexaName oder alexaRoom zur Verfügung. Manche dieser Attribute (wie z.b. alexaName) werden in beiden Skills verwendet, andere werden ausschließlich bei einer Nutzung des Alexa Custom Skill verwendet.<br />
<br />
Die Einrichtung des Alexa Device geschieht durch die nachfolgende Definition:<br />
<source lang="bash" style="width:70%;">define MyAlexa alexa</source><br />
<br />
=== Alexa Skills anlegen ===<br />
<br />
==== Smart Home ====<br />
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein<br />
# Anmeldung auswählen<br />[[Datei:Developer.amazon.com-01-login2.png|200px]]<br />
# Anmeldedaten eingeben<br />[[Datei:Developer.amazon.com-02-userpass2.png|200px]]<br />
<br />
===== Apps & Services =====<br />
# Klicke nach der Anmeldung auf ''APPS & SERVICES''<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]<br />
# Klicke anschließend auf ''Security Profiles''<br />[[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]<br />
# Wähle anschließend ''Create a New Security Profile'' aus<br />[[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]<br />
# Gebe dann ein Namen und eine Beschreibung für das Profil ein und bestätige die Eingaben durch anklicken von ''Save''<br />[[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]<br />
<br />
===== Login with Amazon =====<br />
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden ist}}<br />
# Nachdem du die vorherigen Schritte befolgt hast, siehst du im Browser das Profil dass du angelegt hast. Klicke jetzt oben rechts auf ''Login with Amazon''<br/>[[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]<br />
# Auf der neu geladenen Seite klickst du dann auf ''Sign up''<br/>[[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]<br />
# Wähle anschließend im Dropdown Menü das vorher angelegte Profil aus und bestätige das anschließend mit ''Confirm''<br/>[[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]<br />
# Im folgenden Fenster gibst du dann die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] ein und bestätigst die Eingabe mit ''Save''<br/>[[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]<br />
# Klicke dann bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad und wähle ''Web Settings'' aus<br/>[[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]<br />
# Im neu geladenen Fenster klickst du dann auf ''Edit''<br/>[[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]<br />
# Füge zuletzt dann bei ''Allowed Return URLs'' die Adresse [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx], [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx], und [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx] hinzu. xxx muss hierbei durch den Wert ersetzt werden, der bei Punkt 6 '''Skill Kit einrichten''' unter '''Redirect Urls''' am Ende der URLs angezeigt wird.<br/>[[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]<br />
<br />
===== Skill Kit einrichten =====<br />
# Wähle im Menü den Punkt ''Alexa'' aus<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]<br />
# Klicke dann ''Get started'' beim Punkt ''Alexa Skills Kit'' an<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]<br />
# Wähle dann auf der neu geladenen Seite oben rechts ''Add a New Skill'' aus<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]<br />
# Auf der folgenden Seite wählst du ''Smart Home Skill API'' sowie ''German'' als Sprache aus und gibst ein Name für den Skill ein was du dann mit ''Next'' bestätigst.<br />[[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]<br />
# Die folgende Seite klickst du mit ''Next'' dann weiter<br />[[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]<br />
# Auf der Seite Configuration gibst du dann unter '''Authorization URL''' die Adresse: <source lang="bash" style="width:70%;">https://www.amazon.com/ap/oa</source>an, bei '''Scope''': <source lang="bash" style="width:70%;">profile:user_id</source> und bei '''Access Token URI''': <source lang="bash" style="width:70%;">https://api.amazon.com/auth/o2/token</source>sowie bei '''Privacy Policy URL''' die Adresse: <source lang="bash" style="width:70%;">https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</source><br /><br />Folgende Felder müssen individuell ausgefüllt werden:<br />* ''Service Endpoint Type'' -> Europe auswählen und im Textfeld den Wert aus Punkt 12 '''AWS Lambda Funktion anlegen''' eintragen<br />* ''Client Id'' -> ''Client Id'' aus Punkt 1. '''Login with Amazon'''<br />* ''Client Secret'' -> ''Client Secret'' aus Punkt 1. '''Login with Amazon'''<br /><br /><br />[[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]]<br />
# <br />[[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]<br />
<br />
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}<br />
Zur späteren Verwendung unter Punkt 7 '''AWS Lambda Funktion anlegen''' wird noch die Application Id benötigt. An diese kommt man wie folgt:<br />
# Wähle im Menü den Punkt ''Alexa'' aus<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]<br />
# Klicke dann ''Get started'' beim Punkt ''Alexa Skills Kit'' an<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]<br />
# Beim vorher angelegten Eintrag auf ''Edit'' klicken<br />[[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]<br />
# Die Id, die nun oben angezeigt wird, ist die gesuchte <br />[[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]<br />
<br />
==== Custom ====<br />
'''ACHTUNG:''' die daten unter 'interaction model' unten gelten nur für skill version 0.1.3. ab version 0.1.4 werden die daten im alexa device erzeugt. wie das geht steht hier {{Link2Forum|Topic=60244|Message=540117|LinkText=im Forum}}.<br />
<br />
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein{{Randnotiz|RNTyp=[g|Info]|RNText=Bei Punkt 6 wird die Skill ID angezeigt (siehe Screenshot), die später als zusätzlicher Trigger für AWS Lambda verwendet wird. Bitte per Copy / Paste speichern.}}<br />
# Anmeldung auswählen<br />[[Datei:Developer.amazon.com-01-login2.png|200px]]<br />
# Anmeldedaten eingeben<br />[[Datei:Developer.amazon.com-02-userpass2.png|200px]]<br />
# Wähle im Menü den Punkt ''Alexa'' aus und klicke dann ''Get started'' beim Punkt ''Alexa Skills Kit''<br />[[Datei:CustomSkill_1.PNG|400px]]<br />
# Klicke dann oben rechts auf ''Add a new skill''<br />
# Auf der Seite '''Create a new Alexa Skill''' werden folgende Optionen gewählt / Informationen eingetragen:<br />
#:* Skill Type = Custom Interaction Model<br />
#:* Language = German<br />
#:* Name: Hier dem Skill einen beliebigen Namen geben. Dieser wird in der Alexa App unter "Meine Skills" angezeigt.<br />
#:* Invocation Name: Name des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James"<br />[[Datei:CustomSkill_2.PNG|400px]]<br />
# Mit ''Next'' die Seite verlassen.<br />
# Auf der Seite '''Interaction Model''' folgende Eingaben tätigen:<br />
#* In die Box '''Intent Schema''' den Programmcode aus folgendem Post einfügen: [https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230 https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230]<br />[[Datei:CustomSkill_3.PNG|400px]]<br /><br /><br />
#* Nun auf ''Add Slot Type'' klicken und die Custom Slot Types (siehe [https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230 https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230]) einrichten. Bitte beachten, dass das Pipeline-Zeichen einen Zeilenumbruch darstellen soll. Im Screenshot ist sichtbar, wie das aussehen muss.<br /> Für FHEM_DEVICE und FHEM_ROOM bitte die eigenen in FHEM definierten Devices und Räume benennen (siehe oben alexaName und alexaRoom).<br />[[Datei:CustomSkill_4.PNG|400px]]<br />Der Screenshot zeigt die Einrichtung für FHEM_DEVICE. Nach der Einrichtung von FHEM_DEVICE ''SAVE'' klicken und die weiteren Slot Types (FHEM_ROOM, FHEM_SWITCH_ACTION und FHEM_artikel) jeweils durch klicken auf ''Add Slot Type'' einrichten.<br /><br /><br />
#* Unter Sample Utterances bitte den Text aus [https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230 https://forum.fhem.de/index.php/topic,60244.msg528230.html#msg528230] reinkopieren<br />[[Datei:CustomSkill_5.PNG|400px]]<br /><br /><br />
#* Eingaben mit ''Next'' abschließen.<br />
# Auf der Folgeseite ''Configuration'' bitte folgende Angaben machen:<br />
#* Service Endpoint Type = AWS Lambda<br />
#* Geographical Region = Europe<br />
#* Im Feld ''Europe'' wird die ARN eingetragen, die man erst in nachfolgenden Abschnitt erhält! Es muss hier also erst mal pausiert werden! Den Browser Tab geöffnet lassen!<br />
#* Sobald man die ARN hat geht es hier weiter...<br />
#* Do you allow users to create an account or link to an existing account with you? = Yes<br />
#* Authorization URL = https://www.amazon.com/ap/oa<br />
#* Client ID = Client ID von oben aus '''Login with Amazon'''<br />
#* Domain List - nichts eingeben<br />
#* Scope = profile:user_id<br />
#* Redirect URLs - sollten vorbelegt sein<br />
#* Authorization Grant Type - Auth Code Grant auswählen<br />
#* Access Token URI = https://api.amazon.com/auth/o2/token<br />
#* Client Secret = siehe oben bei '''Login with Amazon'''<br />
#* Client Authentication Scheme = HTTP Basic<br />
#* Privacy Policy URL = https://www.amazon.com/gp/help/customer/display.html?nodeId=468496<br />
#* Das sollte jetzt alles wie folgt aussehen:<br />[[Datei:CustomSkill_6.PNG|400px]]<br />[[Datei:CustomSkill_7.PNG|400px]]<br /><br />
<br />
Damit ist die Einrichtung des Custom Skill abgeschlossen. Auf der Folgeseite lässt sich der Skill dann testen. In der Alexa App sollte der Skill nun auch sichtbar sein. Er musshier noch aktiviert werden und die Kontoverknüpfung eingerichtet werden, was selbsterklärend ist.<br />
<br />
=== AWS Lambda Funktion anlegen ===<br />
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein<br />
# Anmeldung auswählen<br />[[Datei:Aws.amazon.com-01-site.png|200px]]<br />
# Anmeldedaten eingeben<br />[[Datei:Aws.amazon.com-02-login.png|200px]]<br />
# Den Punkt ''Lambda'' links auf der Startseite auswählen<br />[[Datei:Aws.amazon.com-03-lambda.png|200px]]<br />
# Anschließend den Punkt ''Get Started Now'' auswählen<br />[[Datei:Aws.amazon.com-04-get_started_now.png|200px]]<br />
# Den Blueprint ''Blank function'' auswählen<br />[[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]<br />
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen<br />[[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]<br />''Achtung! Es ist möglich, dass ihr hier '''Alexa Smart Home''' überhaupt nicht auswählen könnt. Dann solltet ihr ganz rechts oben in der Ecke mal schauen, welche Region bzw. welches Land ausgewählt ist. Ich empfehle hier '''Ireland''' auszuwählen. Dann erscheint bei den Funktionen auch '''Alexa Smart Home'''.''<br />
# Bei ''Application Id'' den Wert eintragen, dessen Ermittlung unter '''Skill Kit einrichten''' in der zusätzlichen Beschreibung beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen <br />[[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]<br />
# Auf der Konfigurationsseite bei ''Name'' den Wert FHEM eingeben, bei ''Runtime'' Node.js 4.3. Bei ''Role'' den Wert ''Choose an existing role'' wählen (wenn es noch keine existing role gibt: zuerst Create a custom role -> in dem Popup dann lambda_basic_execution und auf Allow) und bei ''Existing role'' dann ''x'' wählen. Der Quellcode der Datei lambda.js aus dem Quellpaket wird dann an die Stelle des großen Textfeldes vollständig eingefügt. Dann noch den Hostname im Quellcode an den eigenen anpassen. Anschließend alles mit ''Next'' bestätigen.<br />[[Datei:Aws.amazon.com-07-configure_function.png|200px]]<br />
# Auf der Übersichtsseite dann ''Create function'' anklicken<br />[[Datei:Aws.amazon.com-08-review.png|200px]]<br />
# Klicke dann auf der Übersichtsseite oben links auf ''Functions''<br />[[Datei:Aws.amazon.com-09-go_overview.png|200px]]<br />
# Wähle dann die angelegte Funktion aus und klicke dann im Menü ''Action'' auf den Punkt ''Show ARN''<br />[[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]<br />
# Es wird nun eine ARN Adresse angezeigt, die für den Punkt 6 bei '''Skill Kit einrichten''' benötigt wird<br />[[Datei:Aws.amazon.com-10-2-arn.png|200px]]<br />
<br />
== Einrichtung ==<br />
Nachdem die Alexa Skills installiert bzw. definiert wurden, müssen diese noch in deiner Alexa eingerichtet werden.<br />
<br />
=== Alexa Skill ===<br />
# Auf http://alexa.amazon.de anmelden (Per Desktop-Browser, nicht die App unter iOS oder Android verwenden. Diese hat Probleme mit der OAuth Verknüpfung.)<br />
# Auf ''Skills'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]<br />
# Oben rechts ''Meine Skills'' auswählen<br />[[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]<br />
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken<br />[[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]<br />
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken<br />[[Datei:Alexa.amazon.de-04-skill_details.png|200px]]<br />
# In dem neu geöffneten Fenster die Authorisierung bestätigen<br />[[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]<br />
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein <br />[[Datei:Alexa.amazon.de-06-success.png|200px]]<br />
<br />
=== Geräte ===<br />
# Auf http://alexa.amazon.de anmelden<br />
# Auf ''Smart Home'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]<br />
# Anschließend den Punkt ''Geräte suchen'' anklicken<br />[[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]<br />
# Wurde soweit alles korrekt eingerichtet, werden nun die gefundenen Geräte angezeigt.<br />
<br />
Tip: Es macht Sinn, unter ''Meine Gruppen'' Gruppen benannt nach den Räumen einzurichten. Hierdurch kann Alexa die Geräte besser auseinander halten, vor allem wenn die den gleichen Alias (z.B. "Licht") haben.<br />
== Nutzung ==<br />
Um den Namen zu bestimmen unter dem ein Gerät mit Alexa angesprochen wird verwendet Alexa-Fhem mit absteigender Priorität:<br />
* das alexaName Attribut<br />
* das alias Attribut<br />
* das NAME Internal<br />
<br />
Damit Alexa ein Gerät eindeutig identifizieren kann sollten eindeutige Bezeichnungen möglichst aus einem Wort und ohne Ziffern verwendet werden. Wenn Alexa einen Namen nicht versteht sollte man unter [http://alexa.amazon.de/spa/index.html] nachsehen was tatsächlich verstanden wurde und die Benennung anpassen.<br />
<br />
=== Smart Home Skill ===<br />
Gruppen (Räume) müssen in der Alexa App konfiguriert werden. Über das API lassen sich nur der Name und die Schalteigenschaften übergeben.<br />
<br />
==== Sprachkommandos ====<br />
Nach erfolgreicher Einrichtung des Smart Home Skills sollte Alexa mit den folgenden Befehlen nutzbar sein:<br />
<pre style="width:50%;"><br />
“alexa, schalte <gerät/gruppe> ein”<br />
“alexa, schalte <gerät/gruppe> aus”<br />
“alexa, stelle <gerät/gruppe> auf <wert> prozent”<br />
“alexa, stelle <gerät/gruppe> auf <anzahl> grad”<br />
“alexa, erhöhe <gerät/gruppe> um <anzahl> prozent”<br />
“alexa, reduziere <gerät/gruppe> um <anzahl> prozent”<br />
“alexa, erhöhe <gerät/gruppe> um <anzahl> grad”<br />
“alexa, reduziere <gerät/gruppe> um <anzahl> grad”<br />
</pre><br />
<br />
=== Custom Skill ===<br />
Der Custom Skill erlaubt im Gegensatz zum Smart Home Skill eine weitreichende Konfiguration der möglichen Kommandos.<br />
<br />
Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=im Forum}} beschrieben.<br />
<br />
TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions)<br />
== Troubleshooting ==<br />
<br />
====Allgemeiner Hinweis====<br />
Besonders wichtig ist, dass man sich sehr genau an diese Anleitung hält. Ein häufiger Fehler ist, dass die einfachen Anführungszeichen in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 8 einfach weggelassen werden. Diese sind zwingend notwendig. Es darf auch nur der reine Hostname eingetragen werden. Also kein ''http://'' davor. Entweder eine feste IP Adresse oder den Hostnamen, um den Rechner zu erreichen, den ihr über den Port 3000 freigegeben habt. Das sollte dann so aussehen:<br />
<pre style="width:50%;"><br />
const PORT=3000;<br />
const HOST='mein.host.name';<br />
</pre><br />
<br />
====Freigabe von Port 3000====<br />
{{Randnotiz|RNTyp=Fehl|RNText=Derzeit müsst ihr über einen echten IPv4 Anschluss verfügen, damit der Amazon Lambda-Server euch erreichen kann. DS-Lite Anschlüsse wie die von <b>UnityMedia</b> z.B. funktionieren derzeit leider nicht. Eine möglicher "Workaround" wird hier beschrieben: https://forum.fhem.de/index.php/topic,60244.msg518276.html#msg518276}}<br />
<br />
Auf dem Router muss der Port 3000 Protokoll TCP freigegeben werden. D.h. von außen muss man wenn man den Port 3000 aufruft, auf dem intern laufenden node.js Alexa-Dienst zugreifen können.<br />
Je nach Router gestaltet sich das Portforwarding bzw. die Portumleitung etwas schwieriger.<br />
<br />
Bei einem Speedport Router der Telekom beispielsweise, muss der Router komplett neu gestartet werden, wenn die Portfreigabe eingerichtet wurde. <br />
<br />
Bei der Fritz!Box ist das nicht nötig, bei dieser finden die Freigabe unter ''Internet -> Freigaben -> Portfreigaben'' statt. Dort wählt man dann den Rechner aus und richtet eine neue Freigabe ein. Wichtig hierbei ist, dass man Portfreigabe auswählt und nicht MyFRITZ!-Freigabe. Bei Port von bis trägt man 3000 ein, bei Port extern ebenfalls.<br />
<br />
Um die Portweiterleitung zu testen, solltet ihr euch auch nicht im gleichen Netz befinden. Viele Router blockieren den Netzaufruf aus dem gleichen Netz. Am besten testet ihr es, wenn ihr an eurem Mobiltelefon W-LAN deaktiviert und im Browser folgende Seite aufruft: ''https://mein.hostname:3000''. Wenn ihr im Browser dann einen Quellcode von Alexa seht, funktioniert die Portumleitung.<br />
<br />
Wenn bis hier alles funktioniert und es läuft dennoch nicht rund, liegt das Problem woanders. Kommt z.B. bei der Gerätesuche kein Request rein (sichtbar auf dem Bildschirm, wenn bin/alexa gestartet wurden), kann evtl. der Lambda-Dienst falsch konfiguriert sein.<br />
<br />
====Probleme mit node.js - npm install====<br />
<br />
Falls eine Fehlermeldung auftritt, dass "npm" nicht gefunden werden kann, bitte NodeJS entsprechend der Anleitung im Homebridge-Artikel vorgehen: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|Python, g++, MDNS installieren]], siehe auch folgenden Abschnitt.<br />
<br />
====Es kommen diverse Fehlermeldungen beim Starten von alexa-fhem und es beendet sich====<br />
Wenn man auf der Konsole angemeldet ist, den Befehl<source lang="bash" style="width:50%;">node -v</source>eingeben. Ist die Version niedriger als die geforderte 0.12, muss eine neuere installiert werden. Hier darf man dann im Wiki unter [[Homebridge_einrichten#NodeJS_installieren]] nachschauen. NodeJS V4 sollte hierbei schon ausreichen. Solange die node.js Version nicht passt, gar nicht groß rum experimentieren! Bitte beachtet, dass alle Voraussetzungen unter [[Alexa-Fhem#Voraussetzungen]] erfüllt sind! Keine Experimente mit Versionen die darunter liegen.<br />
<br />
====Fehlermeldung ''NAT-PMP failed: Error: timeout'' Fehler angezeigt beim Start von alexa-fhem====<br />
Wenn ihr dann alexa-fhem über die Konsole startet und bekommt folgenden Fehler: ''NAT-PMP failed: Error: timeout'', lasst euch davon nicht irritieren. Das bedeutet lediglich, dass der Port nicht automatich freigegeben wurde über uPNP. Alternativ prüft, ob die Funktion der Portfreigabe via uPNP auf eurem Router aktiviert ist.<br />
<br />
====Nach Start auf der Console beendet sich Alexa-FHEM sofort wieder====<br />
Unmittelbar nach dem Start von Alexa-FHEM werden ein paar UPNP Fehlermeldungen ausgegeben. Unmittelbar danach beendet sich Alexa-FHEM wieder. <br />
<br />
Viele scheinen ein Problem mit UPNP auf dem Raspberry Pi zu haben. Wenn dieses Problem auftritt einfach in der <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:<br />
<br />
<pre><br />
"nat-pmp": "10.0.1.1",<br />
"nat-upnp": true,<br />
</pre><br />
<br />
Jetzt erneut Alexa-FHEM starten. Sollte nun laufen.<br />
<br />
====Was ist zu tun, wenn alexa-fhem keine Geräte findet?====<br />
Zunächst müssen die Geräte, die angesprochen werden wollen, unter FHEM ein neues Attribut zugewiesen bekommen. Dazu das Gerät in FHEM öffnen und das Attribut ''genericDeviceType switch'' hinzufügen, wenn es ein Schalter mit der Funktiona AN/AUS sein soll. Wenn man will, kann man dem Gerät jetzt noch über das Attribut ''alias'' eine besseren Namen geben, mit dem Alexa das Gerät dann auch finden kann.<br />
Anschließend muss alexa-fhem neu gestartet werden und die definierten Geräte sollten nun gefunden werden.<br />
<br />
====Was ist zu tun, wenn Alexa zwar Geräte findet, diese aber nicht angesprochen werden können?====<br />
Zuerst die Informationen zum Datenfluss ganz oben ansehen. Dann am besten von hinten nach vorne vorgehen:<br />
* wenn nichts bei alexa-fhem ankommt: port forwarding prüfen<br />
* wenn lambda.js nichts los wird: im cloudwatch log nachsehen<br />
* wenn bei lambda.js nichts ankommt: den trigger prüfen<br />
<br />
<br />
Zunächst sollte man sich unter ''http://aws.amazon.com'' das Logfile seiner erstellten Funktion anschauen. Ist überhaupt ein Logfile vorhanden? Falls nicht, liegt es vermutlich am Trigger.<br />
Den solltet ihr überprüfen. Scheinbar kommt es hin und wieder vor, dass dieser nicht gesetzt ist. Dazu einfach auf ''Triggers'' klicken und mit ''Add trigger'' erneut einen anlegen. Hier muss, wie in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 7, die ''Application Id'' stehen und der Haken bei ''Enable trigger'' gesetzt sein. Dann alexa-fhem neu starten.<br />
Wenn ihr Änderugen gemacht habt und den alexa-fhem Dienst noch nicht neu gestartet habt, wäre jetzt der richtige Zeitpunkt.<br />
<br />
====Was ist zu tun, wenn sich der Alexa-Service nicht starten lässt?====<br />
Schaut bitte in das Unterverzeichnis [alexa-fhem (also dort, wo Ihr Alexa-FHEM instelliert habt]/bin. Die dort befindliche Datei ''alexa'' muss ausführbar sein. Also z.B. so:<br />
<source lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</source><br />
Sollte dies nicht der Fall sein bitte mit:<br />
<source lang="bash" style="width:70%;">chmod +x alexa</source><br />
die Datei ausführbar machen. Sofern der User "pi" Eigentümer ist, ist kein sudo erforderlich.<br />
<br />
<br />
====Wie kann ich via Alexa-FHEM auf FHEM zugreifen, wenn der Port mit Benutzername/Kennwort geschützt ist?====<br />
<br />
Hierzu muss die Datei <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre><br />
"auth": {"user": "fhem", "pass": "fhempassword"},</pre><br />
Bei Verwendung von SSL bei FHEM muss auch noch <pre><br />
"ssl": true,</pre> hinzugefügt werden<br />
<br />
[[Kategorie:HOWTOS]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=17694Proteus EcoMeter2016-12-07T14:41:18Z<p>Eisler: </p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zur Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=platzHalter.png<br />
|Bildbeschreibung=todo<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 433,92MHz, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Tekelek<br />
}}<br />
== Features ==<br />
EcoMeter liefert alle 60 Minuten einen Messwert<br />
EcoMeter liefert alle 30 Minuten einen Messwert und bei schnellen Änderungen<br />
<br />
== Hinweise zum Betrieb mit Fhem ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
{{todo| Eventmonitor einfügen}}<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
* Hersteller: [https://proteus-meter.com/produkte/proteus-ecometer/ Shop]<br />
* Hersteller: [https://proteus-meter.com/faq/ Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=17692Proteus EcoMeter2016-12-07T14:38:24Z<p>Eisler: </p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zur Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=platzHalter.png<br />
|Bildbeschreibung=todo<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 868Mhz??, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Tekelek<br />
}}<br />
== Features ==<br />
EcoMeter liefert alle 60 Minuten einen Messwert<br />
EcoMeter liefert alle 30 Minuten einen Messwert und bei schnellen Änderungen<br />
<br />
== Hinweise zum Betrieb mit Fhem ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
{{todo| Eventmonitor einfügen}}<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
* Hersteller: [https://proteus-meter.com/produkte/proteus-ecometer/ Shop]<br />
* Hersteller: [https://proteus-meter.com/faq/ Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Proteus_EcoMeter&diff=17520Proteus EcoMeter2016-11-27T12:16:18Z<p>Eisler: </p>
<hr />
<div>[[Proteus_EcoMeter]] ist ein Ultraschallsensor mit Monitor zum Pegelmessung von Heizöl- oder Wassertanks<br />
<br />
{{Baustelle}}<br />
<br />
* Sensor zum Einbau in den Tank<br />
* Funkverbindung zwischen Sensor und Monitor<br />
* USB-Verbindung zwischen Monitor und FHEM<br />
* Für Wasser oder Öltanks<br />
<br />
EcoMeter für Heizöltanks<br><br />
EcoMeter S für Wassertanks<br><br />
<br />
{{Infobox Hardware<br />
|Bild=platzHalter.png<br />
|Bildbeschreibung=todo<br />
|HWProtocol=unknown<br />
|HWType=Sensor und Sender<br />
|HWCategory=Other Components<br />
|HWComm=Funk, 868Mhz??, USB<br />
|HWChannels=unknown<br />
|HWVoltage=1,5V LR2450, 5V USB<br />
|HWPowerConsumption=unknown<br />
|HWPoweredBy=Battery, USB<br />
|HWSize=21 x 18 x 6 cm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#TEK603 TEK603]<br />
|HWManufacturer=Proteus<br />
}}<br />
== Features ==<br />
EcoMeter liefert alle 60 Minuten einen Messwert<br />
EcoMeter liefert alle 30 Minuten einen Messwert und bei schnellen Änderungen<br />
<br />
== Hinweise zum Betrieb mit Fhem ==<br />
=== Definition/Anlernvorgang ===<br />
# eventuell im Linux fehlende Pakete installieren <code>sudo apt-get install libdigest-crc-perl </code><br />
# Monitor an das FHEM Gerät anschließen<br />
# Festellen, dass die Verbindung geht. Dazu auf der Kommandozeile eingeben: <code>ls -al /dev/serial/by-id <br> lrwxrwxrwx 1 root root 13 Jan 1 1970 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB0 </code> <br />
# ecometer definieren <code>define TEK603 TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 </code><br />
# LogFile definieren <code>define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.* </code><br />
# Gerät wie in der Betriebsanleitung installieren<br />
<br />
=== FHEM Config-Auszug ===<br />
Ein exemplarischer Auszug aus der [[Konfiguration]]:<br />
define ecometer TEK603 /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0<br />
define FileLog_ecometer FileLog %Lecometer-%Y.log ecometer.*<br />
<br />
=== Eventmonitorbeispiel ===<br />
{{todo| Eventmonitor einfügen}}<br />
<br />
== Einsatzbeispiel ==<br />
=== Anzeige des Ölstands in einem Öltank ===<br />
{{todo|Beispielunterlagen erstellen}}<br />
<br />
== Links ==<br />
* Hersteller: [https://proteus-meter.com/produkte/proteus-ecometer/ Shop]<br />
* Hersteller: [https://proteus-meter.com/faq/ Bedienanleitung]<br />
* Forenbeitrag zur FHEM-Einbindung: {{Link2Forum|Topic=27315}}<br />
<br />
[[Kategorie:Other Components]]<br />
[[Kategorie:Füllstandsmesser]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=HM-ES-TX-WM_Z%C3%A4hlersensor_f%C3%BCr_Strom-_und_Gasz%C3%A4hler&diff=10062HM-ES-TX-WM Zählersensor für Strom- und Gaszähler2015-02-13T14:58:40Z<p>Eisler: fix</p>
<hr />
<div>{{Infobox Hardware<br />
|Bild=HM-EM-TX-WM.jpg<br />
|Bildbeschreibung=HomeMatic Zählersensor<br />
|HWProtocol=HomeMatic<br />
|HWType=Powersensor<br />
|HWCategory=HomeMatic<br />
|HWComm=868&nbsp;MHz<br />
|HWChannels=1<br />
|HWVoltage=6 V<br />
|HWPowerConsumption=30 mA<br />
|HWPoweredBy=4 Batterien LR6/AA/Mignon<br />
|HWSize=68x105x30mm<br />
|HWDeviceFHEM=[http://fhem.de/commandref.html#CUL_HM CUL_HM]<br />
|HWManufacturer=ELV / eQ-3 <br />
}}<br />
<br />
'''Dieses Device ist seit Anfang Feb. 2015 als Bausatz auf dem Markt - dieser Artikel ist im Aufbau - bitte Verständnis für Unvollständigkeiten und fehlende Bereiche '''<br />
<br />
== Features ==<br />
Der Zählersensor ist ein Datenerfassungssystem, das den Energieverbräuche (Strom, Gas) direkt am Zähler erfasst und in FHEM als laufender Saldo und als Momentanwerte verfügbar macht.<br />
<br />
'''Technische Daten:'''<br />
<br />
Gewicht: 195 g (inkl. 4 LR6/Mignon/AA-Batterien)<br />
<br />
== Anwendungsszenarien ==<br />
Mit den erfassten und gesammelten Daten lassen sich Aktionen beim Erreichen bestimmter Schwellwerte auslösen, Verbrauchs- und Kostenstatistiken ableiten sowie beliebige weitere Abhängigkeiten bilden. Durch die Funkdatenübertragung sowie den Batteriebetrieb (1 bis 2 Jahre Betriebsdauer verspricht der Hersteller mit einem Satz) ist die Installation denkbar einfach und erfordert lediglich beim Anbringen der Leseeinheit Genauigkeit.<br />
<br />
Aktuell (Feb. 2015) hat die Auslieferung der Geräte als (einfacher) Bausatz begonnen, zu dem es einen Ferraris-Sensor (für Stromzähler mit den markanten Laufscheiben), LED-Sensor (für neue Zähler mit S0-Schnittstelle) sowie BK-G4-Gaszähler von Elster-Kromschröder, die an einer Ziffernrolle einen kleinen Magneten haben, der über einen Sensor mit Reedkontakt erfasst wird.<br />
<br />
Die Zähler werden mit rückstandslos entfernbaren Klebepads angebracht.<br />
<br />
== Parameter ==<br />
'''list: register | range | peer | description''' <br />
0: pairCentral | 0 to 16777215 | | pairing to central <br />
1: mtrConstGas | 0 to 655.36 | | constant gas <br />
1: mtrConstIr | 0 to 65536 | | constant IR <br />
1: mtrConstLed | 0 to 65536 | | constant led <br />
1: mtrSensIr | -99 to 99 | | sensiblity IR <br />
1: mtrType | literal | | type of measurement options:LED,gas,unknown,IR <br />
<br />
== Probleme ==<br />
<ggfls. ergänzen><br />
<br />
== Betrieb mit FHEM ==<br />
Der Sensor wird mit einem FHEM im Update-Stand vom (mindestens) 7.2.2015 funktionsfähig eingebunden (getestet in der Variante mit Feraris-Fühler). Es werden der Fühlertyp und die Fühlerkonstante richtig ausgelesen und im Reading Energy die errechnete Energiemenge ausgegeben (bei Strom: Wattstunden, Wh).<br />
<br />
=== Readings ===<br />
'''Reading: |Beispiel''' <br />
D-firmware |1.0<br />
D-serialNr |MEQ0025452 <br />
boot |off <br />
current |0 <br />
eState |E: 6199.9 P: 1713 I: 0 U: 0 f: 50 <br />
energy |6199.9 <br />
frequency |50 <br />
mpower |1713 <br />
voltage |0<br />
<br />
=== Events Auszug ===<br />
'''Event |Beispielswert'''<br />
energy |10186.6<br />
power |283<br />
current |0<br />
voltage |0<br />
frequency |50<br />
eState |E: 10186.6 P: 283 I: 0 U: 0 f: 50<br />
boot |off<br />
<br />
Mit einem Userreading lässt sich die Angabe aus Energy zum Beispiel für einen Stromzähler (Wh) in die auf dem Zähler übliche Angabe kWh umrechnen und zugleich mit dem Aufaddieren des Unterschieds beim Start (das Zählermodul beginnt ja mit 0 Wh, während der Zähler meist schon einige Jahre auf der "Rolle" hat) die Angaben gleichziehen:<br />
<br />
attr <DeviceName> userReadings kWh {sprintf("%.1f",ReadingsVal("CUL_HM_HM_ES_TX_WM_353594","energy","???")/1000+72031.5639)}<br />
<br />
=== fhem.log Auszug ===<br />
<Bitte ergänzen><br />
<br />
=== [[Konfiguration]] ===<br />
Nach dem Erkennen durch [[autocreate]] wird der Zählersensor mit diesen Angaben eingebunden:<br />
<br />
define CUL_HM_HM_ES_TX_WM_353594 CUL_HM 353594<br />
attr CUL_HM_HM_ES_TX_WM_353594 IODev CUL_0<br />
attr CUL_HM_HM_ES_TX_WM_353594 actCycle 000:10<br />
attr CUL_HM_HM_ES_TX_WM_353594 actStatus alive<br />
attr CUL_HM_HM_ES_TX_WM_353594 expert 2_full<br />
attr CUL_HM_HM_ES_TX_WM_353594 firmware 1.0<br />
attr CUL_HM_HM_ES_TX_WM_353594 model HM-ES-TX-WM<br />
attr CUL_HM_HM_ES_TX_WM_353594 subType powerSensor<br />
<br />
== Logging/Graph. Darstellung ==<br />
[[Datei:PlotStromverbrauchProStunde.png|mini|400px|rechts|Beispiel der graph. Darstellung]]<br />
Der Zähler wird ja fortlaufend aufaddiert. Mit der delta-Funktion von SVG-Plot können die Verbräuche sehr gut visualisiert werden. <br />
Beispiel Stromzähler:<br />
<br />
set terminal png transparent size <SIZE> crop<br />
set output '<OUT>.png'<br />
set xdata time<br />
set timefmt "%Y-%m-%d_%H:%M:%S"<br />
set xlabel " "<br />
set title 'Stündlicher Stromverbrauch | aktuell: $data{currval1} ($data{min1} / $data{avg1} / $data{max1}) kWh'<br />
set ytics <br />
set y2tics <br />
set grid ytics<br />
set ylabel "kWh/h"<br />
set y2label "kWh/h"<br />
#FileLog 4:CUL_HM_HM_ES_TX_WM_353594.kWh\x3a:0:delta-h<br />
plot "<IN>" using 1:2 axes x1y2 title 'Line 1' ls l0 lw 2 with bars<br />
<br />
== Links ==<br />
* Handbuch: <br />
<br />
{{Todo|Artikel vervollständigen}}<br />
<br />
[[Kategorie:HomeMatic Components]]<br />
[[Kategorie:Energieverbrauchsmessung]]<br />
[[Kategorie:Energieerzeugungsmessung]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Harmony&diff=8284Harmony2014-10-31T13:11:01Z<p>Eisler: </p>
<hr />
<div>{{SEITENTITEL:harmoony}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Logitech Harmony Hub basierter Fernsbedienungen<br />
|ModType=d<br />
|ModCmdRef=harmony<br />
|ModForumArea=Multimedia<br />
|ModTechName=37_harmony.pm<br />
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])}}<br />
<br />
Das Fhem-[[:Kategorie:Gerätemodul|Gerätemodul]] [[harmony]] bietet die Möglichkeit Logitech Harmony Hub basierte Fernbedienungen an Fhem anzubinden und so von Fhem aus Aktivitäten zu starten und zu stoppen, in Fhem auf das starten und stoppen von Aktivitäten über eine der mit dem Hub verbundenen Fernbedienungen zu reagieren oder auf Geräteebene jedes im Hub konfigurierte Gerät über IR, Bluetooth und/oder einen Smart Keyboard USB Dongle zu steuern.<br />
<br />
Unterstütz werden zur Zeit die Modelle Ultumate Hub, Ultimate Smart Control, Ultimate, Smart Keyboard sowie alle darauf basierenden Kombinationen mit Smart Control und Smart Keyboard Add-On.<br />
<br />
=== Define ===<br />
define <hub> harmony <ip><br />
<br />
===Allgemeines===<br />
Aktivitäten und Geräte lassen sich an allen stellen entweder als ID oder als Name angeben. Wenn der Name angegeben wird müßen hierbei Leerzeichen durch einen Punkt ersetzt werden. Dies kann auch für eventuell andre im Namen vorhandene Sonderzeichen gelten.<br />
<br />
=== Aktivität ===<br />
Das Reading currentActivity enthält die gerade laufende Aktivität. Beim Wechsel zwischen Aktivitäten erzeugt es Events auf die in Fhem über notify reagiert werden kann. Das Reading previousActivity enthält die davor laufende Aktivität sofern diese bekannt ist. Diese Reading erzeugt keine Events.<br />
<br />
In den Inernal currentActivityID und previousActivityID stehen die dazu gehörenden IDs der Aktivitäten.<br />
<br />
Innerhalb einer laufenden Aktivität kann mit<br />
set <hub> command <command><br />
ein IR Kommando an eines der Beteiligten Geräte gesendet werden.<br />
<br />
=== Geräteebene ===<br />
Innerhalb und außerhalb einer laufenden Aktivität kann mit<br />
set <hub> command <id|name> <command><br />
ein IR Kommando an eines der im Hub bekannten Geräte gesendet werden. Hierbei ist darauf zu achten das innerhalb einer Aktivität keine Kommandos verwendet werden sollten die den Smart-State betreffen.<br />
<br />
==== Fhem Devices auf Geräteebene ====<br />
<br />
Es ist möglich sich für einzelne oder alle im Hub konfigurierten gerät ein zugehöriges Fhem device anlegen zu lassen:<br />
set <hub> autocreate [<id|name>]<br />
<br />
Beim umschalten zwischen Aktivitäten wird in diesen Fhem devices wird im Reading power den in der Aktivität konfigurierten Einschaltzustand: on,off oder manual. Mit einem notify auf power Events lässt sich in Fhem auf einzelne Geräte reagieren.<br />
<br />
'''Wichtig:''' Diese Fhem devices spiegeln nicht den tatsächlichen Gerätezustand wieder sondern den innerhalb einer Aktivität beabsichtigen Zustand. Der tatsächliche zustand kann z.b. auf Grund von Empfangsproblemen abweichen.<br />
<br />
Das get commands sowie die set command, hidDevice, text, cursor und special Kommandos auf Hub ebene stehen hier direkt und ohne Angabe von Device ID oder Name zur verfügung.<br />
<br />
=== Smart Keyboard ===<br />
Der Harmony Hub kann über Bluetooth oder die zum Smart Keyboard gehörenden USB Dongle mit einem Rechner,Media PC oder sonstigem Gerät das Tastatureingabe unterstütz verbunden werden. Fhem kann diese Verbindung nutzen um beliebige Tastendrücke an ein solches gerät zu senden. Das können Texte sein, Bursorbewegungen oder die Power-, Multimedia oder sonstigen Funktionstasten die das Gerät unterstütz.<br />
<br />
Alle gesendeten Tastendrücke beziehen sich normalerweise auf das zur gerade laufenden Aktivität gehörende Tastatureingabegerät. Mit dem hidDevice kommando lässt sich die Tastatureingabe auf jedes im Hub dafür konfigurierte Gerät umschalten.<br />
<br />
'''Wichtig:''' Dieses Umschalten kann einige Sekunden dauern da zum die bestehende Bluetooth Verbindung getrennt und eine neue aufgebaut wird.<br />
<br />
Es stehen die kommandos text, cursor und special zur verfügung.<br />
<br />
Beispiele:<br />
<br />
Gehe in PLEX auf die Library Musik und spiele das erste item in der OnDeck liste:<br />
set <hub> text M<br />
set <hub> cursor right<br />
set <hub> text p<br />
<br />
== Weblinks ==<br />
* [http://myharmony.com myHarmony] Logitech Harmony Hersteller<br />
* [http://www.harmony-remote-forum.de/portal.php Harmony Remote Forum] deutsches Harmony Forum<br />
<br />
<br />
[[Kategorie:Unterhaltungselektronik]]<br />
[[Kategorie:IP Components]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=EnergyCam&diff=8172EnergyCam2014-10-21T18:52:37Z<p>Eisler: </p>
<hr />
<div>{{Infobox Hardware<br />
|Bild=EnergyCam.jpg<br />
|Bildbeschreibung=EnergyCam mit externer Batterie und externer Antenne montiert auf einem Ferraris-Zähler<br />
|HWProtocol=Wireless M-Bus <br />
|HWType=Sensor<br />
|HWCategory=Energieverbrauchsmessung<br />
|HWComm=Funk 868MHz, ModBus<br />
|HWChannels=N/A<br />
|HWVoltage=3,0 - 3,6V<br />
|HWPowerConsumption=<0,2W<br />
|HWPoweredBy=interne CR2032 oder externe Batterie, USB<br />
|HWSize=B x H x T 48,00 x 55,50 x 15,50 mm<br />
|HWDeviceFHEM=WMBUS<br />
|HWManufacturer=Fast Forward AG<br />
}}<br />
Die [[EnergyCam]] ist ein Zähleraufsatz der den Zählerstand erfasst und dann drahtlos (Wireless M-Bus) oder drahtgebunden (Modbus) weiterleitet.<br />
== Features ==<br />
Eine EnergyCam erfasst optisch den Zählerstand eines herkömmlichen Zählers für Elektrizität, Gas oder Wasser und wandelt diesen per optischer Zeichenerkennung (OCR) in einen Zahlenwert um. Dieser Wert wird dann zyklisch versandt und kann vom Empfänger ausgewertet werden.<br />
<br />
Die EnergyCam wird dazu auf den Zähler aufgeklebt. Das Gerät unterstützt dabei durch eine Anzeige die Montage in der richtigen Position. Für die Verwendung mit Gas- und Wasserzählern sind noch zusätzliche Adapter erforderlich.<br />
Es gibt die EnergyCam sowohl mit interner als auch externer Antenne sowie mit interner und externer Energieversorgung.<br />
Der aktuelle Zählerstand kann bei Bedarf auch direkt am Gerät abgelesen werden und wird auf dem internen Display dargestellt. <br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
Die EnergyCam im Wireless M-Bus Modus wird vom Modul [[WMBUS]] vollständig unterstützt. Das Herstellerkürzel ist FFD.<br />
<br />
== Bekannte Probleme ==<br />
Die Erfassung der Zählerstands erfolgt von schräg unterhalb des eigentlichen Zählwerks. Daher darf dieser Bereich nicht durch Aufdruck oder ähnliches die freie Sicht auf das Zählwerk behindern, sonst ist keine fehlerfreie Erfassung möglich.<br />
<br />
== Links ==<br />
* Herstellerseite [http://www.fastforward.ag/]<br />
[[Kategorie:Energieverbrauchsmessung]]<br />
[[Kategorie:Other Components]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=HM-Sec-SFA-SM_Funk-Sirenensteuerung&diff=6742HM-Sec-SFA-SM Funk-Sirenensteuerung2014-07-04T12:18:27Z<p>Eisler: /* Links */</p>
<hr />
<div>'''Homematic HM-SEC-SFA-SM Funk-Sirenensteuerung'''<br />
== Features ==<br />
&lt;Bitte ergänzen&gt;<br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
'''Achtung:'''Die meisten '''Aktoren''' von HomeMatic, die den Namensbestandteil "SEC" haben, sind nicht mit [[CUL]] oder CUNO nutzbar, sondern erfordern [[HMLAN Konfigurator]], da bei ihnen der [[AES Encryption]] genannte Siginingrequest nicht abschaltbar ist.<br />
<br />
<br />
Das Pairing sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden.<br />
<br />
=== FHEM Config-Auszug ===<br />
Per ''autocreate''<br />
<nowiki>define CUL_HM_switch_124DEF CUL_HM 124DEF<br />
attr CUL_HM_switch_124DEF devInfo 820100<br />
attr CUL_HM_switch_124DEF firmware 1.0<br />
attr CUL_HM_switch_124DEF hmClass receiver<br />
attr CUL_HM_switch_124DEF model HM-SEC-SFA-SM<br />
attr CUL_HM_switch_124DEF room CUL_HM<br />
attr CUL_HM_switch_124DEF serialNr GEQ0173622<br />
attr CUL_HM_switch_124DEF subType switch<br />
define FileLog_CUL_HM_switch_124DEF FileLog /var/log/fhem/CUL_HM_switch_124DEF-%Y.log CUL_HM_switch_124DEF<br />
attr FileLog_CUL_HM_switch_124DEF logtype text<br />
attr FileLog_CUL_HM_switch_124DEF room CUL_HM<br />
define CUL_HM_switch_124DEF_Siren CUL_HM 124DEF01<br />
attr CUL_HM_switch_124DEF_Siren model HM-SEC-SFA-SM<br />
attr CUL_HM_switch_124DEF_Siren room CUL_HM<br />
define FileLog_CUL_HM_switch_124DEF_Siren FileLog /var/log/fhem/CUL_HM_switch_124DEF_Siren-%Y.log CUL_HM_switch_124DEF_Siren<br />
attr FileLog_CUL_HM_switch_124DEF_Siren logtype text<br />
attr FileLog_CUL_HM_switch_124DEF_Siren room CUL_HM<br />
define CUL_HM_switch_124DEF_Flash CUL_HM 124DEF02<br />
attr CUL_HM_switch_124DEF_Flash model HM-SEC-SFA-SM<br />
attr CUL_HM_switch_124DEF_Flash room CUL_HM<br />
define FileLog_CUL_HM_switch_124DEF_Flash FileLog /var/log/fhem/CUL_HM_switch_124DEF_Flash-%Y.log CUL_HM_switch_124DEF_Flash<br />
attr FileLog_CUL_HM_switch_124DEF_Flash logtype text<br />
attr FileLog_CUL_HM_switch_124DEF_Flash room CUL_HM</nowiki><br />
=== Log-Auszüge ===<br />
&lt;Bitte ergänzen&gt;<br />
<br />
== Links ==<br />
[http://forum.fhem.de/index.php?t=msg&amp;th=10220&amp;start=0&amp;rid=417 Foren-Thread zum Gerät]<br />
<br />
Anleitung [http://www.eq-3.de/Downloads/eq3/pdf_produkte/HM-Sec-SFA-SM_UM_GE_091209.pdf PDF]<br />
<br />
[[Kategorie:HomeMatic Components]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=HM-WDS40-TH-I_Funk-Temperatur-/Feuchtesensor_innen_(IT)&diff=6569HM-WDS40-TH-I Funk-Temperatur-/Feuchtesensor innen (IT)2014-06-15T07:47:25Z<p>Eisler: WDS40 übermittelt den Batteriestatus mit Firmware 1.3</p>
<hr />
<div>'''HomeMatic HM-WDS40-TH-I Funk-Innensensor ITH'''<br />
Homematic Innensensor für Temperatur und relative Luftfeuchte.<br />
<br />
== Features ==<br />
* Batteriebetrieb (2 x AA)<br />
* Wandaufhängung möglich<br />
* Für Temp. von -20 °C bis +80 °C<br />
* Datenübermittlung alle 120 bis 180 Sekunden<br />
* Übermittlung des Batteriestatus<br />
* Aktuelle Firmware: 1.3<br />
<br />
== Hinweise zum Betrieb mit FHEM ==<br />
Das Pairing sollte wie unter [[HomeMatic Devices pairen]] beschrieben durchgeführt werden. Hierfür muss die von außen erreichbare Anlerntaste betätigt werden.<br />
<br />
=== Probleme ===<br />
Bisher keine.<br />
<br />
=== FHEM Config-Auszug ===<br />
define TEMPERATUR_SENSOR CUL_HM xxxxxx<br />
attr TEMPERATUR_SENSOR .devInfo 030100<br />
attr TEMPERATUR_SENSOR .stc 70<br />
attr TEMPERATUR_SENSOR actCycle 000:10<br />
attr TEMPERATUR_SENSOR actStatus alive<br />
attr TEMPERATUR_SENSOR autoReadReg 4_reqStatus<br />
attr TEMPERATUR_SENSOR expert 2_full<br />
attr TEMPERATUR_SENSOR firmware 1.3<br />
attr TEMPERATUR_SENSOR model HM-WDS40-TH-I<br />
attr TEMPERATUR_SENSOR peerIDs 00000000,xxxxxxxx,<br />
attr TEMPERATUR_SENSOR room xxx<br />
attr TEMPERATUR_SENSOR serialNr KEQxxxxxxx<br />
attr TEMPERATUR_SENSOR subType THSensor<br />
define FileLog_TEMPERATUR_SENSOR FileLog ./log/TEMPERATUR_SENSOR-%Y.log TEMPERATUR_SENSOR<br />
attr FileLog_TEMPERATUR_SENSOR logtype text<br />
attr FileLog_TEMPERATUR_SENSOR room xxx<br />
define SVG_FileLog_TEMPERATUR_SENSOR_1 SVG FileLog_TEMPERATUR_SENSOR:SVG_FileLog_TEMPERATUR_SENSOR_1:CURRENT<br />
attr SVG_FileLog_TEMPERATUR_SENSOR_1 room xxx<br />
<br />
=== FHEM Log-Auszug ===<br />
<nowiki>&lt;Datum&gt;_&lt;Zeit&gt; CUL_HM_THSensor_1ABCDE T: 21.8 H: 56<br />
&lt;Datum&gt;_&lt;Zeit&gt; CUL_HM_THSensor_1ABCDE T: 21.8 H: 56<br />
&lt;Datum&gt;_&lt;Zeit&gt; CUL_HM_THSensor_1ABCDE T: 21.8 H: 56<br />
&lt;Datum&gt;_&lt;Zeit&gt; CUL_HM_THSensor_1ABCDE T: 21.8 H: 56</nowiki><br />
<br />
=== Device-Log ===<br />
<Datum>_<Zeit> CUL_HM_THSensor_1ABCDE temperature: 21.6<br />
<Datum>_<Zeit> CUL_HM_THSensor_1ABCDE humidity: 60<br />
<Datum>_<Zeit> CUL_HM_THSensor_1ABCDE battery: ok<br />
<Datum>_<Zeit> CUL_HM_THSensor_1ABCDE T: 21.6 H: 60<br />
<br />
== Links ==<br />
Anleitung [http://www.elv-downloads.de/service/manuals/76998_HM_GE_WDS40_TH_I_GE_V1_1.pdf PDF]<br />
<br />
[[Kategorie:HomeMatic Components]]<br />
[[Kategorie:Feuchtesensoren]]<br />
[[Kategorie:Temperatursensoren]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Umsetzung&diff=5840Umsetzung2014-04-10T09:21:42Z<p>Eisler: /* Ereignissteuerung */</p>
<hr />
<div>Die '''Umsetzung''' (Implementierung) eines Fhem-Projekts hat zumindest die Teilaspekte der Installation der Geräte und der Entwicklung des Interfaces mit den darüber ansprechbaren Funktionen. Für den Start dieser Phase sollte die [[Planung]] fortgeschritten sein, nach Abschluss der Implementierung kann der (Regel-)[[Betrieb]] aufgenommen werden.<br />
<br />
== Installation der Hardware ==<br />
=== Sonsoren, Aktoren, Verkabelung ===<br />
Sensoren und Aktoren müssen installiert und ggf. (bei kabelgebundenen Systemen) mit der Zentrale verbunden werden.<br />
<br />
=== Fhem Server und Interfaces ===<br />
Die Hardware, auf der Fhem läuft, muss in Betrieb genommen und Fhem installiert werden.<br />
<br />
== Implementierung der Funktionalität ==<br />
=== Definition und Beschreibung der Geräte ===<br />
Alle Geräte müssen in Fhem definiert und ggf. mit zusätzlichen Attributen versehen werden. Die Basisdefinitionen von einigen Geräten wird schon durch die ''autocreate'' Funktion durchgeführt. Es ist sinnvoll, für die (Um-)Benennung von Geräten ein Namensschema festzulegen und zu benutzen.<br />
<br />
=== Bedienelemente ===<br />
''Bedienelemente'' umfasst alle Icons, Buttons, Texte etc., die auf der Bedienoberfläche angezeigt werden.<br />
<br />
=== Automatikfunktionen ===<br />
Automatikfunktionen müssen definiert und getestet werden:<br />
<br />
==== Zeitsteuerung ====<br />
Um Aktionen zeitgesteuert auszuführen, wird in der Regel das '''[http://fhem.de/commandref.html#at at]''' verwendet.<br />
<br />
==== Ereignissteuerung ====<br />
Ereignisse werden mittels '''[http://fhem.de/commandref.html#notify notify]''' verarbeitet.<br />
<br />
=== Test, Probebetrieb ===<br />
Für Test und Probebetrieb sowie zur Problembestimmung/-behebung stellt Fhem die folgenden Hilfsmittel zur Verfügung (Auswahl):<br />
* Details über [[HomeMatic]](-Geräte): [http://fhem.de/commandref.html#HMinfo HMinfo]<br />
* Performance-Analyse: [http://fhem.de/commandref.html#apptime apptime]<br />
* Fhem-Systeminformationen: [http://fhem.de/commandref.html#fheminfo fheminfo]<br />
* ...<br />
<br />
== Sonstiges ==<br />
Die [[Systemübersicht]] kann auch in dieser Phase als Orientierung dienen, bei der Realisierung der Funktionalität stellen [[Anwendungsszenarien]], [[:Kategorie:Examples|Beispiele]], [[:Kategorie:Code Snippets|Code-Schnipsel]] und letztendlich die [http://fhem.de/commandref.htm Befehlsreferenz (commandref)] die Informationsbasis dar.<br />
<br />
{{Todo|Diese Aufstellung sollte noch erweitert und mit sinnvollen Querverweisen an andere Stellen in diesem Wiki versehen werden}}<br />
<br />
[[Kategorie:FHEM]]</div>Eislerhttp://wiki.fhem.de/w/index.php?title=Umsetzung&diff=5839Umsetzung2014-04-10T09:20:52Z<p>Eisler: /* Zeitsteuerung */</p>
<hr />
<div>Die '''Umsetzung''' (Implementierung) eines Fhem-Projekts hat zumindest die Teilaspekte der Installation der Geräte und der Entwicklung des Interfaces mit den darüber ansprechbaren Funktionen. Für den Start dieser Phase sollte die [[Planung]] fortgeschritten sein, nach Abschluss der Implementierung kann der (Regel-)[[Betrieb]] aufgenommen werden.<br />
<br />
== Installation der Hardware ==<br />
=== Sonsoren, Aktoren, Verkabelung ===<br />
Sensoren und Aktoren müssen installiert und ggf. (bei kabelgebundenen Systemen) mit der Zentrale verbunden werden.<br />
<br />
=== Fhem Server und Interfaces ===<br />
Die Hardware, auf der Fhem läuft, muss in Betrieb genommen und Fhem installiert werden.<br />
<br />
== Implementierung der Funktionalität ==<br />
=== Definition und Beschreibung der Geräte ===<br />
Alle Geräte müssen in Fhem definiert und ggf. mit zusätzlichen Attributen versehen werden. Die Basisdefinitionen von einigen Geräten wird schon durch die ''autocreate'' Funktion durchgeführt. Es ist sinnvoll, für die (Um-)Benennung von Geräten ein Namensschema festzulegen und zu benutzen.<br />
<br />
=== Bedienelemente ===<br />
''Bedienelemente'' umfasst alle Icons, Buttons, Texte etc., die auf der Bedienoberfläche angezeigt werden.<br />
<br />
=== Automatikfunktionen ===<br />
Automatikfunktionen müssen definiert und getestet werden:<br />
<br />
==== Zeitsteuerung ====<br />
Um Aktionen zeitgesteuert auszuführen, wird in der Regel das '''[http://fhem.de/commandref.html#at at]''' verwendet.<br />
<br />
==== Ereignissteuerung ====<br />
Ereignisse werden mittels '''[http://fhem.de/commandref.htm#notify notify]''' verarbeitet.<br />
<br />
=== Test, Probebetrieb ===<br />
Für Test und Probebetrieb sowie zur Problembestimmung/-behebung stellt Fhem die folgenden Hilfsmittel zur Verfügung (Auswahl):<br />
* Details über [[HomeMatic]](-Geräte): [http://fhem.de/commandref.html#HMinfo HMinfo]<br />
* Performance-Analyse: [http://fhem.de/commandref.html#apptime apptime]<br />
* Fhem-Systeminformationen: [http://fhem.de/commandref.html#fheminfo fheminfo]<br />
* ...<br />
<br />
== Sonstiges ==<br />
Die [[Systemübersicht]] kann auch in dieser Phase als Orientierung dienen, bei der Realisierung der Funktionalität stellen [[Anwendungsszenarien]], [[:Kategorie:Examples|Beispiele]], [[:Kategorie:Code Snippets|Code-Schnipsel]] und letztendlich die [http://fhem.de/commandref.htm Befehlsreferenz (commandref)] die Informationsbasis dar.<br />
<br />
{{Todo|Diese Aufstellung sollte noch erweitert und mit sinnvollen Querverweisen an andere Stellen in diesem Wiki versehen werden}}<br />
<br />
[[Kategorie:FHEM]]</div>Eisler