FHEMWiki - Benutzerbeiträge [de]

SIGNALduino

2023-04-02T09:24:31Z

Sidey: Aktualisierung auf aktuellen Stand, Pflege von Hyperlinks

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}
== Einleitung ==
=== Übersicht ===
{{Randnotiz|RNTyp=Info|RNText=Wo finde ich was/welche Info?
;Hardware
#SIGNALDuino ((noch) "hier")
#[[Selbstbau CUL]]
#[[Maple-SignalDuino]]
#[[ESP32-SignalDuino]]
;Firmware
#"Sidey" - [[SIGNALduino#Flashen_des_Arduino_mit_der_SIGNALduino_Firmware|mittels Modul]]
#"Ralf9" - [https://github.com/Ralf9/SIGNALDuino Github]
;FHEM Modul
#"Sidey" - [[SIGNALduino]] ("hier")
#"Ralf9" - {{Link2Forum|Topic=111653|Linktext=hier beschrieben}}
}}
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles Weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (z.B. Raspberry) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt änderbarer/updatebarer Rechner-Seite). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung auf Stick-Firmware-Seite korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichenden Frequenzen steuerbar sind. So empfangen die ''Somfy''-Rolladenmotoren beispielsweise auf 433.42 MHz und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen; dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt. In FHEM existieren inzwischen zwei verschiedene Versionen: eine offizielle (Maintainer ist Sidey) und eine inoffizielle (Maintainer ist Ralf9). Die offizielle Version wird über den update-Prozess verteilt, wer die inoffizielle nutzen will, muss hier händisch eingreifen. Beide Versionen sind inzwischen so weit entwickelt, dass sie nicht mehr ohne Weiteres kompatibel sind. Man muss also eine Entscheidung treffen, welches das für einen geeignete Modul ist. Das betrifft inzwischen nicht nur das eigentliche SIGNALduino.pm-Modul, sondern auch die dazugehörige Firmware.

==== Offizielles Modul (Sidey) ====
Die offizielle Version wird in mehreren Forenbeiträgen beschrieben: {{Link2Forum|Topic=58397|Linktext=erster Beitrag]}} (inzwischen geschlossen), {{Link2Forum|Topic=58396|LinkText=weiterer Thread}} sowie {{Link2Forum|Topic=60170|Linktext=noch ein Thread}}.

An einem weiteren Thread ({{Link2Forum|Topic=58396|Linktext=Link}}) scheinen beide Autoren beteiligt zu sein.

==== Inoffizielles Modul (Ralf9) ====
Das Modul von Ralf9 wird {{Link2Forum|Topic=111653|Linktext=hier}} beschrieben. Wer es installieren möchte, muss beim üblichen update-Prozess das Modul 00_SIGNALduino.pm vom [[update]] (Attribut ''[[Update#exclude from update|exclude from update]]'') ausschließen oder nach jedem Update erneut Ralf9s-Modul herunterladen. Die Installation des Moduls wird im ersten Post beschrieben, Hilfe gibt es auch in diesem Thread.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "Aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum FHEMduino
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, Link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist momentan die Übersetzung mittels [https://platformio.org/ Plattform IO]. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] oder [https://de.wikipedia.org/wiki/ESP32 ESP32] nativ läuft.

Auch an den "ESP8266" oder "ESP32" kann ein [[Selbstbau CUL|CC1101]] Modul via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP 8266 Pin
!ESP 32 PIN
|-
|CLK||GPIO14
|D18
|-
|MOSI||GPIO13
|D23
|-
|MISO||GPIO12
|D19
|-
|CSN||GPIO15
|D5
|-
|GDO0||GPIO4
|D4
|-
|GDO2||GPIO5
|D13
|}

Wird eine einfache Empfänger / Sender Kombination verwendet, dann über die Pins:

{| |
! Bezeichnung
! ESP 8266 Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) - es wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:

''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''

Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltagstauglichen Zustand haben. Aktuell wird dort die Version 3.5.4 seit 06.01.2023 verteilt.

Mit Version 3.5.x ist die Unterstützung für Geräte mit '''FSK'''-Modulation integriert.

Die aktuell in Entwicklung befindliche Version kann über folgende Vorgehensweise installiert werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/master<nowiki/>/controls_signalduino.txt</code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.<code><nowiki/></code>
* Es empfiehlt sich, die Github-Quelle dauerhaft einzutragen: <code>update add https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/master/controls_signalduino.txt</code>, um weitere Entwicklungs-Updates zu bekommen, und damit das nächste Standard-<code>update</code> nicht die alte Version wieder einspielt.

Das Gerät kann wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen, ist die Syntax (ebenso wird auch vorgegangen wenn der SIGNALduino beispielsweise über ser2net freigeben wird):
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 -

Verbindungsversuche via telnet müssen dieselbe Baudrate verwenden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

Wenn ein miniCUL geflasht werden soll, sind einige Besonderheiten zu beachten. Details dazu in {{Link2Forum|Topic=114413|LinkText=diesem Forenthema}}.

==== Flashen einer Firmware über HTTP ====
Die Firmware wird nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Die Version 3.4 ist die aktuell stabile Version.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut <code>hardware</code> auf einen gültigen Wert angepasst werden!
Über den GET Befehl <code>availableFirmware</code> werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut <code>updateChannelFW</code> kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten Version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut <code>flashCommand</code> hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|Conrad RSL Funkschalter||E S|| || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen ''Intertechno''-Funksteckdosen (''Brennenstuhl'') kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (<code>verbose</code> >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:

<pre>
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):
</pre>

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Modul, welches diese Protokolle verarbeitet.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist auch kurz und knapp manuell (also ohne Modul und automatisch angelegtem Gerät).

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes [[notify]]-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverständlich muss in diesem Moment auch eine <code>sub my_sender_trigger_indicate()</code> definiert werden (z.B. in <code>FHEM/99_myUtils.pm</code>), die dort z.B. als Test eine Log-Ausgabe (<code>Log3()</code>) machen kann.

=== Das Logfile ===
Im Logfile ab [[verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (<code>verbose</code> 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und Vorzeichen): Die Zahl gibt in Mikrosekunden die Zeitdauer an, das Vorzeichen bestimmt, ob es sich um eine gesendetes Signal gehandelt hat (positives Vorzeichen) oder ob das Signal gerade pausierte (negatives Vorzeichen). Insofern ist die Beschreibung "negatives Signal" irreführend - es gab in der Zeitspanne gerade kein Signal. Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde 395 Mikrosekunden (P1) ein Signal gesendet (weil P1='''+'''395), danach gab es 8916 Mikrosekunden kein Signal (Pause, wegen P5='''-'''8196). CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>
* MN : Nachrichten dieser Art wurden vom cc1101 vor bearbeitet. Die Nachrichten dieser Art enthalten unter D= den Empfangenen Datensatz hexadezimal codiert. Der Wert R= gibt die Empfangsstärke, auch hexadezimal an.<syntaxhighlight lang="bash">
MN;D=3002925F3A1E7B6C000200002584;R=43;
</syntaxhighlight>
Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Internet-Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise folgende Bits-Bereiche enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Daten-Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich (identisch) erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut <code>WhitelistID</code> minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die <code>WhitelistID</code> aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann der Tabelle [[#Unterstützte Geräte|Unterstützte Geräte]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das Signal so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "Rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegebenen Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut <code>ITClock</code> eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt Geräte-Instanz-spezifische Konfiguration) das <code>ITclock</code> eines IT-Client-Devices.

== Fehlerbehandlung ==

=== Modul-Initialisierung ===

==== Perl-Modul Digest::CRC fehlt ====

Das FHEM-Log kann (bei Version ab 3.5.x) folgendes enthalten:

<code>Can't locate Digest/CRC.pm in @INC (you may need to install the Digest::CRC module) (@INC contains: fhem.p/lib fhem.p/FHEM/lib ./FHEM/lib ./lib ./FHEM ./ /usr/local/FHEM/share/fhem/FHEM/lib /opt/fhem . /etc/perl /usr/local/lib/arm-linux-gnueabihf/perl/5.28.1 /usr/local/share/perl/5.28.1 /usr/lib/arm-linux-gnueabihf/perl5/5.28 /usr/share/perl5 /usr/lib/arm-linux-gnueabihf/perl/5.28 /usr/share/perl/5.28 /usr/local/lib/site_perl /usr/lib/arm-linux-gnueabihf/perl-base) at ./FHEM/00_SIGNALduino.pm line 28, <$fh> line 1870.
BEGIN failed--compilation aborted at ./FHEM/00_SIGNALduino.pm line 28, <$fh> line 1870.</code>

In diesem Fall ist der Transceiver nicht funktionsfähig - es muss erst Perl-Modul <code>Digest::CRC</code> (Ubuntu und Debian: Package <code>libdigest-crc-perl</code>) installiert werden und fhem neu gestartet werden.

=== Konfiguration von Firmware/Hardware (Reset usw.) ===
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl im Modul direkt ausgeführt werden können. Sofern möglich, sollte die Abfrage von Werten aus dem Modul allerdings mit den dafür vorgesehenen Kommandos erfolgen, da die Rückmeldungen des <code>set raw</code> Befehls nur im Logfile ab verbose 4 erscheinen. Die Befehle sind nützlich, wenn direkt auf den Microcontroller zugegriffen wird:

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: <code>set raw C35</code> führt ab verbose 4 zu einer Logausgabe folgender Art: <code>Read, msg: C35 = 0D</code>
:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot
:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die EEPROM Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2 des CC1101)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

Unbekannte Funkprotokolle

2023-01-05T12:03:54Z

Sidey: Vorgehen zur Aktualisierung controls Datei überarbeitet

Es gibt jede Menge offiziell in FHEM unterstützte Devices und Funkprotokolle. Solange das Device Ross und Reiter benennt (Homematic, Z-Wave, Intertechno etc.), ist es einfach, dieses in FHEM einzubinden. Was aber, wenn selbst mit hinreichend gut aktualisierter Installation nichts erkannt wird und es ein No-Name Produkt ist, bei dem man nur die Hoffnung hat, dass es im Innern etwas Bekanntes beherbergt?

Dieser Wiki-Artikel soll jenen helfen, die Geräte mit einem unbekannten Funkprotokoll an FHEM anbinden bzw. mit FHEM steuern wollen.

Wenn hier drin irgendetwas unverständlich sein sollte (und wenn es nur deswegen sein sollte, weil es hinreichend bescheuert beschrieben ist :)), dann --> <big>'''MELDEN!'''</big>, vielleicht via BenutzerSeite (oder natürlich einfach direkt verbessern) - die Usability dieses Projekts sollte sehr gut werden...

Dieser Artikel soll eine möglichst gut chronologische Sortierung haben, also:

Einführung ... erste Schritte ... Tests ... Analyse ... stabiler Betrieb ... Verfeinerung / letzte Schritte (Expertise-Details).

== Basics ==

==== Hardware ====

Neben den bekannten Hardware-Dongles gibt es Selbstbaulösungen in Form eines SIGNALduino, CUL oder JeeLink.

Diese unterscheiden sich in verschiedener Hinsicht:
* Sendemodul (SIGNALduino/CUL -> CC1101; JeeLink -> RF12B) [https://de.wikipedia.org/wiki/Amplitudenumtastung]
* Modulationsverfahren (OOK, ASK/FSK)
* Frequenzband (433 MHz, 868 MHz)

(bei SIGNALduino / CUL kann manche Hardware - z.B. nanoCUL - da hardware-kompatibel, mit Projektaktivitäten von CUL ''oder'' SIGNALduino betrieben/firmware-geflasht werden; evt. ist es sogar außerdem empfehlenswert, mehrere baugleiche Geräte zu haben, um Support für SIGNALduino ''und'' CUL gleichzeitig verfügbar zu haben - evt. auch weitere Geräte mit unterschiedlichen Frequenzen: 433/868)

==== Frequenzbereich ====
Für die funkbasierte Heimautomation kommen im Wesentlichen zwei Frequenzbänder in Frage: 433 und 868 MHz. Die meisten Geräte haben auf der Rückseite ein Typenschild, auf dem das Frequenzband ausgewiesen ist.

Dann gibt es noch 2,4 GHz (WLAN, Bluetooth, Funkmaus-Chipsätze...) und 5GHz (WLAN...), diese Frequenzbänder werden in diesem Artikel aber nicht betrachtet.

==== Modulationsverfahren ====

So, wie vom Rundfunk (AM/FM) her bekannt, kennt man auch bei 433/868 MHz verschiedene Modulationsverfahren.

* [https://de.wikipedia.org/wiki/Amplitudenumtastung OOK/ASK/Amplitudenabtastung]
: Das Signal des Senders wird auf der angegebenen Frequenz ein-/ausgeschaltet um die Dateninformationen zu übermitteln.
* [https://de.wikipedia.org/wiki/Frequenzumtastung FSK/Frequenzumtastung]
: Der Sender überträgt den Datenstrom indem, ausgehend von der Trägerfrequenz, zwischen Frequenzen (z.B. Frequenz-Frequenzhub, Frequenz+Frequenzhub) hin- und hergeschaltet wird. Dieses Verfahren kennt verschiedene Ausprägungen: 2-FSK, 4-FSK, GFSK (Details siehe [http://www.rfwireless-world.com/Terminology/2FSK-modulation-vs-4FSK-modulation.html hier]).

==== Encoding oder auch Leitungscode ====

Die Art und Weise wie dieses Signal interpretiert wird, hängt wiederum vom Encoding ab. Dazu sei auf die nachfolgenden Quellen verwiesen.

* [https://de.wikipedia.org/wiki/Leitungscode Leitungscode (Einstieg)]
* [https://de.wikipedia.org/wiki/Non_Return_to_Zero NRZ]
* [https://de.wikipedia.org/wiki/Manchester-Code Manchester]

Je nach verwendetem Encoding wird ggf. mehr als 1 Übertragungs-Bit für ein Datenbit benötigt. Der Empfänger erwartet z.B. einen Bitwechsel zu einem bestimmten Zeitpunkt. Eine Abfolge
* 100 (short high, long low) wird als 0
* 110 (long high, short low) wird als 1
interpretiert.

Im FHEM-Forum gibt es viele freundliche Helfer, die Euch bei Bedarf den richtigen Weg weisen.

==== Signalstruktur ====

Ein typischer Aufbau einer Signalstruktur sieht z.B. so aus

| Pause | Sync | Pause | Daten |

* eine größere Pause zur Trennung der Sequenzen
* ein Sync-Block mit dem sich der Empfänger auf den Sender einstellt
* eine Pause um Sync und Daten zu trennen
* die eigentlichen, zu übertragenden Daten.

Es müssen nicht immer alle Bestandteile in der übertragenen Signalstruktur vorkommen (Details siehe auch [https://de.wikipedia.org/wiki/Datenpr%C3%A4ambel Datenpräambel] oder auch [https://en.wikipedia.org/wiki/Syncword Syncword]).

Die Sequenz wird ggf. mehrfach wiederholt

| Pause | Sync | Pause | Daten | Pause | Sync | Pause | Daten | Pause | Sync | Pause | Daten | ...

==== Protokoll ====

Das ist der herstellerspezifische Teil des Signalstroms - die Daten. Hersteller haben i.d.R. ihre eigene Definition der übertragenen Datenströme. Teils werden feste Code-Sequenzen übertragen, es gibt aber auch rollierende Codes (Engl.: Rolling Codes) bei denen sich die Daten bei jeder Übertragung ändern (Fremd-Manipulations-Sicherheit).

Mit etwas Glück erkennt z.B. SIGNALduino bereits das Protokoll, damit den Hersteller und legt automatisch ein passendes Device in FHEM an. Manchmal gibt es auch Fehlinterpretationen und das vermeintlich bekannte Device entpuppt sich als etwas anderes (Statement aus dem Forum: "Lösung war, wo Dooya drauf steht muss nicht immer Dooya drin stecken.").

== Wie fange ich an? ==

==== Recherche ====

Sucht im Internet nach Informationen zu dem fraglichen Device. Zu bekannten Devices sollten sich Informationen finden lassen, die einem weiter helfen. Solltet Ihr fündig werden, verfolgt die Hinweise, wie diese Devices in FHEM eingebunden werden können.

Evt. haben auch konkrete verwandte Projekte bereits Protokoll-Informationen über das Gerät, z.B.:
* [https://github.com/merbanan/rtl_433/tree/master/src/devices rtl_433: Geräte-Verzeichnis]

Wenn sich nichts Verwertbares finden lässt, geht's mit dem nächsten Abschnitt weiter.

==== Ansatz 1 - Versuchen ====

Einfach probieren: Bau Dir einen [[SIGNALduino]] für das passende Frequenzband (die 433 oder 868 MHz-Variante des CC1101). Stelle im SIGNALduino-Setting die Frequenz auf die genannte ein (durch den Befehl cc1101_freq = 433.000 oder 868.000) und die Bandbreite auf das Maximum (cc1101_bWidth = 325 kHz bzw. 650 kHz). Jetzt noch das Attribut verbose auf 5 setzen und dann das FHEM-log (tail -f fhem-yyyy-mm.log) beobachten.

Ist ein Gerät in Reichweite, das regelmäßig etwas sendet (z.B. ein Funkthermometer), sollte hin und wieder etwas empfangen werden. Wenn [[Autocreate|autocreate]] aktiv ist, werden auf Basis der erkannten, bekannten Funkprotokolle automatisch neue Devices angelegt (dabei können auch diverse Funkthermometer der Nachbarschaft auftauchen).

Ist es ein Gerät, das sich über eine Fernbedienung steuern lässt: Eine Taste betätigen und hoffen, dass sich im FHEM-Log etwas tut. Auch hier gilt: Handelt es sich um ein bekanntes Funkprotokoll, wird automatisch ein Device angelegt, allerdings nur eines für die Gerätefamilie. Bei Baumarkt-Funksteckdosen z.B. nur das erste gefundene. Die anderen müsst Ihr manuell anlegen und die entsprechenden Codes zur Identifikation der einzelnen Steckdosen anpassen (schaut z.B. hier nach: [[Intertechno_Code_Berechnung]]).

Solltet Ihr mit diesem Ansatz Erfolg haben, ist das schon mal gut - Euer Gerät sendet ein bekanntes Protokoll und wird unterstützt.

Solltet Ihr etwas empfangen (MC, MS, MU), aber keine neuen Devices sehen, wird Euer Gerät möglicherweise noch nicht unterstützt. Jetzt gibt es zwei Varianten
* es handelt sich um ein neues, noch nicht bekanntes Protokoll -> postet einen Log-Ausschnitt auf [https://github.com/RFD-FHEM/RFFHEM/issues github] wie im [[SIGNALduino]]-Wiki vorgeschlagen)
* es handelt sich um etwas proprietäres, altes oder ähnlich kompliziertes (nicht aufgeben, weiterlesen)

==== Ansatz 2 - Aufschrauben ====

Fernbedienung aufschrauben, schauen welcher Chip dort verbaut ist.
Endgerät/Device aufschrauben, schauen welcher Chip dort verbaut ist.

Das Teil ist zu klein? Folgende Möglichkeiten:
* so im Winkel gegen ein Lampenlicht halten, dass man die Schrift besonders gut lesen kann
* abfotografieren und das Foto vergrößern bis Ihr den Aufdruck lesen könnt

Danach folgt dann Internet-Suchmaschine und das Studium der zugehörigen Data Sheets der Chips.

Das gibt Euch weitere Anhaltspunkte zum Modulationsverfahren, den Frequenzen und Optionen welche diese Chips unterstützen.

Wenn die Grundsatzfrage geklärt ist, ergeben sich die ersten Handlungsoptionen
* OOK-Modulation -> [[SIGNALduino]]
* ASK/FSK -> [[Selbstbau_CUL]] oder [[JeeLink]]

Die Devices senden/empfangen nicht notwendigerweise auf 433 oder 868 MHz, sondern auf Frequenzen "knapp daneben", das kann z.B. bis zu 870 MHz hochgehen. Darüber, welche Frequenz es genau ist, gibt möglicherweise der verbaute Quarz Auskunft. Meist klein, silber mit einer Gravur wie z.B. 6,70 MHz versehen. Mit Hilfe der Spezifikationen (Frequenzteiler, ...) im Datenblatt des daneben verbauten Chips lässt sich dann die tatsächliche Sende- bzw. Empfangsfrequenz errechnen.

==== Ansatz 3 - Messen ====

Ihr nutzt einen Spektrumanalysator. Es gibt verschiedene preisgünstige Ansätze.

* Zum einen könnt Ihr den nrfmon-Ansatz verfolgen (siehe [https://jeelabs.net/projects/cafe/wiki/NRfMon_-_nano_Spectrum_Analyzer_with_the_RFM12B hier)]. Tipp: bestellt Euch direkt genug Material um zwei zu bauen, denn die RF12demo kann als Sender und Empfänger genutzt werden. Damit lässt sich direkt verifizieren, dass Euer RFM12B-Device wirklich sendet/empfängt.
* Der andere Ansatz nutzt einen DVB-T-Stick (siehe z.B. [https://homematic-forum.de/forum/viewtopic.php?t=11087 hier]. Es gibt aber viele Internet-Suchmaschine-Treffer unter dem Stichwort [https://www.mikrocontroller.net/topic/243367 SDR]. Außerdem ein konkretes Projekt: [https://github.com/merbanan/rtl_433/ rtl_433].
* Mein persönlicher Favorit ist der [https://github.com/jopohl/urh Universal Radio Hacker]. Mit dem war ich in der Lage, mittels RTL-SDR-Stick nicht nur Sequenzen mitzuschneiden sondern auch direkt zu analysieren.

Wieso überhaupt so kompliziert? OOK nutzt nur eine Frequenz, FSK zwei, vier, je nach Variante. Es kann auch vorkommen (so wie bei mir), dass ein FSK-Device auf einen OOK-Sender anspricht. Der Grund dafür sind Oberwellen die mit dem Ein-/Auschalten der Frequenz einher gehen.

Die Spektrumanalyse gibt Aufschluss über
* das Modulationsverfahren (OOK vs. FSK) sowie
* die relevante(n) Frequenz(en)

== SIGNALduino - OOK ==

Dieses Kapitel geht davon aus, dass ihr einen SIGNALduino für alle weiteren Schritte nutzt.

==== Log-Meldungen ====

Der SIGNALduino empfängt die Rohdaten, ermittelt identische Zeitscheiben und ordnet diese den Zahlen 0-7 zu (P0...P7). Ein negativer Zahlenwert bedeutet "kein Empfang" und ein positiver "Signal empfangen". Damit lässt sich der Datenstrom analysieren und für das Senden auch wieder generieren.

Die folgenden Pulslängen-Zahlen stehen für Mikrosekunden.

<code>P0=-13020;P1=15916;P2=-398;P3=415;P4=4008;P5=-794;P6=812;D=01232323232323232323232324532653265353532653262653265326 26262626265353532653265326532653535326265353535353265353532653262653265353265353535353535353265326;</code>

Was bedeutet D=012323...?
: 0 -> P0=-13020 => 13.020 Mikrosekunden Pause
: 1 -> P1=15916 => 15.916 Mikrosekunden Signal
: 2 -> P2=-398 => 398 Mikrosekunden Pause
: 3 -> P3=415 => 415 Mikrosekunden Signal
: 2 -> P2=-398 => 398 Mikrosekunden Pause
: 3 -> P3=415 => 415 Mikrosekunden Signal
: ...

Tip: um hier schnell zu einem guten Analyse-Ergebnis zu kommen, sind einige verfügbare Beispiel-Zeilen sinnvoll - hier könnte folgendes hilfreich sein:
Bei Geräten, die nicht on-demand (Knopfdruck) Funk-Aktivität generieren können:
Nicht langwierig auf das jeweils nächste verzögerte Intervall der Funk-Aktivität des Geräts warten, sondern stattdessen mehrfach die Geräte-Batterien erneut wieder einsetzen, so dass (hoffentlich) das Gerät immer eine erste Funk-Aktivität sendet, die:
* Log-Zeitstempelmäßig genau erkennbar ist
* hoffentlich immer gleich/ähnlich ist --> gute Analyse-Grundlage
Damit dürfte die Funk-Aktivität hinsichtlich Empfangsstärke, Trägerfrequenz etc. leichter festnagelbar sein.

==== Frequenz ermitteln ====

Das folgende Beispiel geht davon aus, dass Ihr im 868 MHz-Band unterwegs seid. Bei 433 MHz könnt Ihr in gleicher Weise vorgehen.

Fangt damit an, dass Ihr den CC101 mittels set-Command cc1101_freq auf 868.000, cc1101_bWidth auf 650 und cc11=1_sens auf 8 einstellt. Kontrollieren könnt Ihr das durch <code>get ccconf</code>. Die Bandbreite bWidth gibt an wie groß der Empfangsbereich ist. Bei 650 kHz sind das z.B. +/- 325 kHz, also der Bereich von 867.675 bis 868.325 MHz.

Wenn ihr etwas empfangt ist das ein Ansatzpunkt. Anderfalls könnt Ihr die cc1101_freq in 200 kHz-Schritten (868.200, 868.400 ...) erhöhen und das Frequenzband auf diese Art und Weise absuchen. Ein Hinweis an der Stelle: Im FHEM-Log folgt bei den SIGNALduino-Einträgen nach dem Datenteil D= die Empfangsstärke R=. Damit könnt Ihr feststellen, ob Ihr Euch der Sendefrequenz nähert oder entfernt.

Wenn Ihr nun Frequenzen gefunden habt bei denen Ihr etwas empfangt, dann könnt Ihr die bWidth jeweils halbieren und den Bereich, in dem etwas empfangen wurde, mit halbierter Frequenz-Schrittweite weiter durchforsten. Das macht Ihr so lange, bis bWidth bei 58 kHz angekommen ist. Damit sollte sich die gesuchte Trägerfrequenz herauskristallisieren.

==== Eingrenzung - Selektiver Empfang ====

Am sichersten geht man selektiv vor - einen Message-Typ nach dem anderen testen. Im SIGNALduino kann man über das set-Command <code>disableMessagetype</code> die Interpretation als MC, MS und MU selektiv ausschalten. Man kann mit MC beginnen und danach beobachten, ob es bei aktivem MS + MU Dekoder jeweils nur eine Art von Nachrichten gibt.

Sobald man sieht, dass die Meldungen im FHEM-Log wechseln, die Message-Typen MS, MU bzw. MC mit nur einem aktiven Dekoder aufzeichnen.

Das sollte Anhaltspunkte geben worauf der S'duino am Besten reagiert.

==== Eingrenzung - Log-Analyse via regex ====

Wenn man schon ziemlich genau weiß, wie das Message-Pattern des relevanten Geräts aussieht, dann kann man sich folgendermaßen sehr elegant und schnell viele weitere zu diesem Gerät gehörige Aktivitäten aus dem Log fischen, ohne sehr störenden Traffic von anderen Geräten mit dabei zu haben:
z.B.:

<code>tail -f log/fhem-2018-11.log|grep "sduino.*msg READ: .*=-4...;"</code>

um sich alle Pattern eines Geräts rauszufischen, bei dem man weiß, dass dessen Sende-Traffic das hinreichend charakteristische Merkmal besitzt, einen Low-Puls mit +- 4000us Länge zu haben:

<code>sduino433/msg READ: MU;P0=-956;P1=450;P2=-1987;P3=-4212;P4=96;P6=-304;D=01212121212121312131212131312121213131312131313431316;CP=1;R=224;</code>

Anmerkung: dies ist natürlich mit einem On-Demand-beherrschbaren Gerät (z.B. Fernbedienung, oder Batterie-basiertes Außerbetriebsetzen) kein Problem: hier kann man direkt live (aktueller Zeitpunkt!) nachvollziehen, ob die aktuelle Regex-Filterung tatsächlich Geräte-Aktivität richtig herausfischt (oder eben dummerweise nicht!). Jedoch bei nicht so leicht kontrollierbaren Geräten (intervall-mäßiges Senden, z.B. Klima-Sensoren, oder noch blöder, nur vereinzeltes Senden, z.B. Schwellwert-Sensoren, oder nicht direkt zugängliche Geräte) muss man natürlich den Regex möglichst wenig strikt formulieren, um sicherzustellen, dass man keine im Log abgelegte Aktivität dieses Geräts fälschlicherweise total übersieht/ignoriert.

==== Variationen ====

Solltet Ihr verschiedene Fernbedienungen für die Produktfamilie besitzen oder so wie ich eine die 8 Rolllädenmotoren bedienen kann, könnt Ihr bei nicht dokumentierten Protokollen trotzdem die Funktion der einzelnen Bytes herausarbeiten.

Spielt jede Tastenkombination durch, extrahiert die Meldungen aus dem FHEM-Log und legt sie in separaten Dateien ab die ihr z.B. mit Motor, Richtung, Fernbedienung kennzeichnet.

==== Signal analysieren ====

Habt Ihr nun den Punkt erreicht an dem Ihr ''reproduzierbar'' (hinreichend stabil erfasste) (Teil-)Code-Sequenzen (oft in mehrfacher, identischer Wiederholung) im FHEM-Log seht, geht es ans Entschlüsseln. Auch hier wieder der einfache Fall: SIGNALduino kennt den Hersteller bzw. Device-Typ schon und legt automatisch ein FHEM-Device an (da das aber öfter nicht der Fall sein wird, muss man hier weiterarbeiten).

Wenn ein Signal demoduliert wurde ist man den Bits und Bytes schon einen Schritt näher gekommen.

Gehen wir wieder von unserem Beispiel aus:

<code>P0=-13020;P1=15916;P2=-398;P3=415;P4=4008;P5=-794;P6=812;D=01232323232323232323232324532653265353532653262653265326 26262626265353532653265326532653535326265353535353265353532653262653265353265353535353535353265326;</code>

Wie ist diese Sequenz zu interpretieren?

Anhand der anfänglich gelisteten Puls-Beschreibungen Px= (Aktiv-Indikator/Dauer):

* Es startet mit einer Pause D='''0'''123232323232
* gefolgt von einem Signal D=0'''1'''23232323232 in der Länge von ca. 16 ms (15916 µs).
* danach folgt ein Sync-Block D=01'''23232323232'''... bei dem jeweils Pärchen von 400 µs Pause/400 µs Signal wiederholt werden.
* Sync- und Datenteil sind durch einen Puls von 4 ms [P4=4008] getrennt D=0123232323232323232323232'''4'''53265
* gefolgt vom Datenteil D=01232323232323232323232324'''53265'''....

Beim Datenteil wird es etwas komplizierter. Hier sind immer ein kurzer (2 oder 3) und ein langer (5 oder 6) Wert kombiniert. Folglich muss man bei der Interpretation zwischen Aktiv-Indikator (Vorzeichen) und Dauer differenzieren. Ein Pärchen ist immer 1.200 µs lang. In der Mitte dieser Zeitscheibe kann der übertragene Wert folglich eine Pause oder ein Signal sein.

Beispiel: Den Vorspann
<code>P0=-32001;P1=15874;P2=-364;P3=447;P4=4060;P5=-762;P6=853;D=01232323232323232323232324</code> (bestehend aus Puls-Beschreibungen und initialer Puls-Aktivität) lassen wir mal außen vor und konzentrieren uns auf den nachfolgenden echten Nutz-Daten-Teil (hinsichtlich dessen logischer Protokoll-Umformung hin zur finalen Nutz-Datenwort-Sequenz):

<code>53265326535326535326265353262653265353535326265353265326262653265326265353535353532653535353262653265353265353535353535353532626 (rohe Abfolge der Puls-Typen)

lSsLlSsLlSlSsLlSlSsLsLlSlSsLsLlSsLlSlSlSlSsLsLlSlSsLlSsLsLsLlSsLlSsLsLlSlSlSlSlSlSsLlSlSlSlSsLsLlSsLlSlSsLlSlSlSlSlSlSlSlSlSsLsL (als sSlL-Notation)

1 0 1 0 1 1 0 1 1 0 0 1 1 0 0 1 0 1 1 1 1 0 0 1 1 0 1 0 0 0 1 0 1 0 0 1 1 1 1 1 1 0 1 1 1 1 0 0 1 0 1 1 0 1 1 1 1 1 1 1 1 1 0 0 (als Bitfolge)

10101101 10011001 01111001 10100010 10011111 10111100 10110111 11111100 (Gruppierung auf Bit-Datenworte)

AD99 79A2 9FBC B7FC (als Hex-Datenworte)</code>

Die Analyse basiert auf folgenden Annahmen (mit Beispiels-Werten)
* Mapping von Puls-Werten auf logische Zustände: wenn 800-ter Pulse: Wert kleiner 0 (z.B. -800) ist ein l (long low), größer 0 ist L (long high), wenn 400-ter Pulse: analog, gemapped auf sS (short low/high) - "sSlL-Notation"...
* Weiter angenommen es werden immer 2 Frequenzen/Zustände verglichen (lS => 1 und sL => 0) (ein Gerät hat ja salopp gesagt nicht mehr zu tun als nur 2 Zustände - 0er und 1er Daten-Bits - robust codiert über Funk zu vermitteln - aus diesen Bits ergibt sich dann zusammengefügt ein gesamtes Geräte-Datenwort, welches anschließend in Bit-Bereiche wie Temperatur, Feuchte, Wind zerlegungs-analysiert werden muss, anhand charakteristischer Werte-Veränderungen, die man idealerweise auch direkt in z.B. einem Sensor-LCD-Display erkennen kann)

Abseits-Bemerkung: Sollte man mit dem SIGNALduino ein ''FSK''-Signal empfangen/interpretieren (im Gegensatz zu "normaleren" ''ASK'', ''OOK''), so hängt die Bewertung davon ab, ob man die Sendefrequenz+Frequenzhub oder Sendefrequenz-Frequenzhub empfängt. Die Bedeutung von 0/1 wird dann negiert. FIXME diese Beschreibung ist (mir) zu unklar, eine Verbesserung sollte erarbeitet werden.

Weitere wichtige Tips:
* es ist wohl sinnvoll, zu versuchen, sich evt. an einem längsten Puls (das ist nämlich evt. eine Sync-Pause) zu orientieren, um nachfolgende Bereiche evt. als startendes Bit-Datenpaket identifizieren zu können
* man sollte die Pulsfolge per Textsuche analysieren, in einem Editor/Reader, der Such-Texte in einer Zeile '''mehrfach''' farbig markieren kann (less, ...) - bei markiertem Suchtreffer kann man dann Teil-Folgen identifizieren, welche sich deterministisch ''wiederholen'' - diese sind dann wohl offensichtlich codierte Bit-Daten, welche es passend zu entschlüsseln gilt
* die identifizierten Merkmale sind dann als ein neues Protokoll (falls kein bereits existierendes Protokoll zu unpräzise formuliert sein sollte!) in <code>FHEM/lib/signalduino_protocols.hash</code> hinzuzufügen (Angabe präziser Durchschnittswerte von Basis-Takt, Gesamt-Patternlänge, Puls-Pause-Verhältnisse, ... - Details dieses Protokolls siehe Header dieser Datei), und dann muss ein <code>reload 00_SIGNALduino</code> gemacht werden, um dies zu testen (hier: beim sduino-Device temporär(!! - hoher Platzbedarf...) Attribute verbose 5 und debug 1 setzen!)
* für Beispiele einer Protokoll-Implementierung sollte man sich wohl auch die History (entsprechende Commits) im [[#Links|RFFHEM git repository]] ansehen
* es ist evt. sinnvoll, sich die Verarbeitungskette anhand von Empfang/Senden bereits funktionsfähiger Protokolle / Geräte zu verdeutlichen, bevor man selber loslegt, neue Geräte (Protokolle) zu unterstützen
* richtige Verarbeitung von empfangenen Funk-Pattern (oder in leicht abgeänderter Form derselben) kann man wohl besonders effizient debuggen, indem man sich einen Dummy-SIGNALduino anlegt:
<code>define sduino_dummy SIGNALduino none</code>

In diesen kann man dann die gewünschten zu unterstützenden Pattern einimpfen:

<code>get sduino_dummy raw MC;;LL=-653;;LH=665;;SL=-317;;SH=348;;D=D55B58;;C=330;;L=21;;</code>

Alle Strichpunkte (Semikolon) müssen hierbei jeweils escaped werden (durch Wiederholung), vermutlich da sie in FHEM's Perl-Code-Umgebung sonst als normale ''sequence points'' interpretiert würden.

Weitere für einen Test verwendbare Beispiel-Pattern siehe [[#Links|RFFHEM git repository]], in Datei: <code>FHEM/14_SD_BELL.pm</code>.

Wenn alles richtig läuft (weil man es richtig implementiert hat), dann sollte die gesamte Kette von Pattern-Fingerprinting bis hin zu Dispatch an Datenwort-Modul und dortige Verarbeitung bis hin zu einem entsprechend sichtbaren Auftauchen der Device-Aktivitäten/-Autocreate in FHEMWEB Event Monitor page und/oder Log durchlaufen werden.

==== Steuern ====

Die empfangenen, im Log ausgewiesenen Sequenzen könnt Ihr als Basis für das Senden verwenden. Relevant sind dabei Puls-Beschreibungen P0...P7 sowie D (Data). Die RSSI-Empfangsstärke wird beim Empfang als R= ausgewiesen. Beim Senden steht R jedoch für die Anzahl der Wiederholungen. Entnehmt die Details und Möglichkeiten bitte der Dokumentation [https://github.com/RFD-FHEM/SIGNALDuino/wiki/Commands Commands].

==== Signal-Protokoll-Beschreibung verfeinern ====

Sobald man bei einem Gerät initial erfolgreich empfangen / dekodieren (/ senden?) konnte, sollte man folgendes noch beachten:

Es ist recht wichtig, dass jede Protokoll-Beschreibung eines Geräte-Signals '''möglichst präzise Geräte-konforme''' Werte aufführt:

wenn mehrere Protokoll-Beschreibungen aufgrund von zu ungenauen Werten jeweils als passend betrachtet werden, dann
landet das Signal-Pattern (auch) bei falschen Protokoll-Beschreibungen - die weitere Zuordnung (dies ist eine Routing-Entscheidung!) hin zu spezifischen Geräte-Datenwort-FHEM-Modulen ist also gefährdet / sinnlos:
* evt. ganz fehlgeschlagen aufgrund von Falsch-Zuordnung
* viel sinnlose Noise im Log, weil gleich mehrere Pfade angeblich passen und dann "noch nicht supported"-Fehlermeldungen werfen
Mit stark steigender Anzahl von bekannten Protokoll-Beschreibungen dürfte dieses Problem immer schlimmer werden.

Daher sollte man folgendes beachten:
* sicherstellen, dass nicht eine andere - also bereits existierende! - Protokoll-Beschreibung eigentlich die richtige gewesen wäre, welche nur aufgrund von Impräzisionen das aktuelle völlig Protokoll-gleiche Gerät NICHT erkannt hat (zudem: "ähnlich" aussehende Protokolle, die allerdings von klar unterschiedlichen Geräte-Familien erzeugt werden, sollten NICHT in der gleichen Protokoll-Beschreibung zusammengemischt werden, und man sollte diese Abgrenzung dort auch klarstellen: durch Referenz-Hinweise auf entsprechende fast gleiche Protokoll-Beschreibungen dort)
* ''length_min'' , ''length_max'' möglichst passend restriktiv spezifizieren (also z.B. 12 , 12)
* ''clockabs''-Basistakt-Mittelwert möglichst präzise ermitteln
* ((die Perl-Demodulations-Implementierung - in <code>00_SIGNALduino.pm</code> etc. - ebenfalls auf möglichst restriktive Checks / Wertebereiche trimmen))

Ermittlung eines präzisen ''clockabs''-Basistakt-Mittelwerts dürfte folgendermaßen gut machbar sein:
* einige Geräte-Pattern aus dem Log fischen
* dort die ''clockabs''-Werte suchen (<code>CP=x</code> verweist darauf)
* aus diesen dann einen Mittelwert bilden, damit man die größte Präzision erreicht
* evt. sogar längere (Sync-)Pulse (z.B.: 15x ''clockabs'' Low, 1x ''clockabs'' High) heranziehen, um durch Mittelung (+ Teilung) über viele dieser z.B. 15x wiederholten Pulslängen einen daraus resultierend maximal präzisen ''clockabs''-Basistakt-Mittelwert zu ermitteln
* evt. ist es auch hilfreich, den im Gerät verbauten Quarz zu berücksichtigen - u.U. lässt sich hieraus (falls eine solche Verarbeitung im Gerät tatsächlich Timer-mäßig relevant sein sollte!) ein sehr präziser da "mechanisch" passender Puls-Takt-Wert ermitteln (Pseudo-Beispiel:
<code>(1 / 8MHz) * 2048 [digitaler Teiler] = 0.256ms == 256us</code>
); wobei der mechanische Gerätetakt evt. doch erstaunlich anders sein könnte als die von SIGNALduino erfassten Werte (inwiefern das dann hinsichtlich Rx-/Tx-Präzision relevant ist - wer weiß...)

==== Development / patch submission ====

Es ist evt. empfehlenswert, auf github einen eigenen Fork des RFFHEM-Upstream-Repositories zu erstellen - dann kann man ''dort'' seine Entwicklung durchführen:
* Änderungen durchführen (im korrekten Branch)
* alles committen
* <code>controls_signalduino.txt</code> updaten (wird via via github actions automatisch aktualisiert), sonst kann nicht über den update Befehl installiert werden!
* mit dem üblichen FHEM-Befehl (<code>update all ...</code>, aber eben sinnigerweise unter Angabe der URL seines ''eigenen'' Repositories!!) seine eigenen Änderungen jeweils korrekt verwaltend und updatend austesten
* evt. hier jeweils <code>reload BEARBEITETES_MODUL</code> nötig
* wenn das alles passt, hat man bereits seinen eigenen Fork fix und fertig (und authentisch getestet) und kann somit direkt - evt. nach einem bereinigenden <code>git rebase -i @{u}</code> - einen Pull Request daraus machen (anders ausgedrückt: "direkt kontext-integrierte Entwicklung", "am Puls der Zeit", "mit voller Tool-Unterstützung"). Dies am besten vollständig Automatisierungs-gekapselt durch ein Shell-Script (FIXME: am besten hier einfach direkt hier präsentieren?), welches an FHEM den <code>update all ...</code> request schickt (über telnet, Port 7072) ''und'' den <code>reload BEARBEITETES_MODUL</code> durchführt.

== SIGNALduino - FSK ==

Dieses Kapitel geht davon aus, dass ihr einen SIGNALduino für alle weiteren Schritte nutzt.

Aktuell laufen Bestrebungen, den SIGNALduino FSK-fähig zu machen: siehe [https://forum.fhem.de/index.php/topic,106582.0.html FSK mit SIGNALduino] (vormals https://forum.fhem.de/index.php/topic,82379.0.html)

Die Summary der CC1101-Settings findet ihr [https://forum.fhem.de/index.php/topic,106594.0.html#new hier].

=== FSK Senden ===

Die ersten Bits des CC1101-Register 12 MDMCFG2 bestimmen die Übertragungsweise:
000 = 2-FSK
001 = GFSK
011 = ASK/OOK
100 = 4-FSK

Schaut Euch den aktuellen Registerinhalt an, bevor Ihr ihn ändert. Am einfachsten geht das über
<code>get <mysduino> ccreg 99</code>
Ihr müsst beim angezeigten Wert die ersten drei Bits entsprechend abändern, also z.B. aus 0x30 dann 0x10 für GFSK statt OOK machen.
Das Register wird über
<code>set <mysduino> raw W1410</code>
abgeändert (bitte beachtet das Offset von 0x02 für das Beschreiben eines Registers, 14 adressiert Register 12).

Nun könnt Ihr FSK senden. Das im URH angezeigte Spektrum sollte nun zwei Spitzen aufweisen. Ihr seht daneben vermutlich auch weitere kleine links und rechts daneben. Das liegt daran, dass es Oberwellen gibt. Bei 2-FSK sind dies mehr als bei dem geglätteten GFSK.

=== Sendefrequenz und Frequenzhub ===

<div class="tright" style="clear:none">[[Datei:PeakLow.png|mini|ohne|300px|FSK, Trägerfrequenz minus Hub]]</div>
<div class="tright" style="clear:none">[[Datei:PeakHigh.png|mini|links|300px|FSK, Trägerfrequenz plus Hub]]</div>

Bei OOK wird das Funksignal ein- und ausgeschaltet, um die bits als 0 und 1 darzustellen. Bei FSK sieht das anders aus. Zur Übertragung wird ein permanentes Signal ausgestrahlt; die Darstellung der bits 0 und 1 erfolgt durch Erniedrigung bzw. Erhöhung der Frequenz. Folglich gilt es sowohl die Trägerfrequenz als auch den Frequenzhub zu ermitteln. Das bit 0 wird i.d.R. durch Trägerfrequenz minus Hub, das bit 1 durch Trägerfrequenz plus Hub dargestellt.

In diesem Beispielspektrum eines FSK-Signals ist ersichtlich, dass die untere Frequenz bei ca. 868,233 Mhz und die obere bei ca. 868,281 Mhz liegt. Die Trägerfrequenz liegt folglich in der Mitte bei 868,257 MHz und der Frequenzhub beträgt ca. 24 kHz.

=== Ermittlung der Frequenzen ===

Wie im OOK-Kapitel bereits angesprochen, ist eine Messung mit Hilfe eines SDR-Sticks hilfreich. Doch Vorsicht - diese Sticks sind oftmals nicht geeicht und die angezeigte Frequenz wird "relativ" genau gemessen. Was aber hilft ist ein Vergleich Original/Kopie. Messt mit dem SDR-Stick unter Nutzung eines Programms wie URH die Frequenzen, sendet mit dem SDUINO ebenfalls ein Signal auf einer von Euch vorgegebenen Frequenz. Nehmt als Basis für den Ver- bzw. Abgleich die von Euch im SDUINO vorgegebene Frequenz. Die ist für die weiteren Aktivitäten relevant. Die Abweichung könnt Ihr in der URH-Software zur Frequenzkorrektur vorgeben, dann werden identische Werte angezeigt.

=== Hub ===

Da hilft Euch das RF Studio für den CC1101. Der darin ermittelte Wert ist in das Register 15 DEVIATN zu übertragen. Bei 25 kHz Hub ist das der Wert 40, der mittels
<code>set <mysduino> raw W1740</code>
an den CC1101 des SDUINO übermittelt wird.

Wenn Ihr soweit seid, sollten die Funksignale der Original-Fernbedienung und Eures SDUINO ähneln.

<div class="tleft" style="clear:none">[[Datei:RIO FB-Signal.png|mini|Spektrum Original-Fernbedienung]]</div>
<div class="tleft" style="clear:none">[[Datei:Signal des SDUINO GFSK .png|mini|Spektrum SDUINO GFSK ]]</div>
<div style="clear:both"></div>

=== Baudrate ===

Beim SDUINO übernimmt der CC1101 die Funktion eines Modems. Die Signalaufbereitung bzw. -erzeugung erfolgt im Arduino. Das können wir auch für das Senden von FSK Signalen nutzen. Der CC1101 bietet eine Fülle weiterer Optionen (Sync, FIFO etc.), die aber eher für Spezialisten geeignet sind.

Welche Baudrate soll/muss ich angeben? Zunächst mal gilt es folgende Teilstrecken zu unterscheiden:
FHEM <-> Arduino <-> CC1101 <-> Sendesignal

Die Baudrate zwischen FHEM und dem Arduino wird in FHEM vorgegeben. Die für den CC1101 angegebene und mittels <code>get <myduino> ccconf</code> ausgegebene Baudrate ist die zwischen dem Arduino und dem CC1101. Mit dieser Baudrate wird das Funksignal gesampled.

Beim Empfang interpretiert der Arduino den Signalpegel und erkennt die Übergänge zwischen 0 und 1. Es wird die Dauer des jeweiligen Signals ermittelt und einem Parameter ('''P'''uls?) 0-7 zugeordnet. Auf diese Weise wird die gesamte empfangene Codesequenz beschrieben.

<div class="tleft" style="clear:both">[[Datei:RIO-Signal.png|mini|600px|RIO-Signal decodiert]]</div>
<div style="clear:both"></div>

Die Baudrate lässt sich im CC1101 nur bedingt präzise einstellen, da dafür nur ein Byte zur Verfügung steht.

Ich habe bei der obigen Sequenz die Baudrate bzw. SCLK aus dem Vorspann (Preamble) ermittelt und bin auf 2.482 Baud gekommen. Für die Übertragung habe ich aber die 10fache Rate verwendet, um die Steuerung des Zustandes 0/1 dem Arduino und nicht dem CC1101 zu überlassen. Statt einer 0 werden dann halt 10x 0 übertragen. Auf Sendeseite ändert sich dadurch nichts. Die Software URH arbeitet ähnlich. Das Signal wird z.B. mit 1 MHz gesampled. Um auf die ermittelte Baudrate und eine reale Darstellung zu kommen, gebe ich 402 Samples/Symbol (Symbol=bit) ein.

Das Ergebnis:

<div class="tleft" style="clear:both">[[Datei:Vergleich RIO-SDUINO-Signale.png|mini|600px|Vergleich RIO/SDUINO-Signale]]</div>
<div style="clear:both"></div>

=== Codesequenzen ===
Die Interpretaion des low- und high-Zustandes hängt von der Sende- und Empfangsfrequenz ab. Wenn Ihr im OOK-Modus Sequenzen mitgeschnitten habt werden die möglicherweise anders interpretiert als die mittels FSK empfangenen. Deshalb: Sequenzen mit der Original-Fernbedienung neu erzeugen und mitschneiden. Achtet dabei darauf, dass diese lang genug sind, um das komplette Steuerungssignal mitzuschneiden. Die Preamble ist recht auffällig (bei mir 01232323 ...). Die wiederholt sich nach dem eigentlichen Steuerungssignal. Ab hier könnt Ihr also abschneiden. Ferner empfiehlt sich, das mitgeschnittene Signal zu dekodieren und in Hex darzustellen. Dann erkennt Ihr, ob identische Inhalte/Sequenzen mitgeschnitten wurden. Das trennt die Spreu vom Weizen.

Damit konnte ich mein Problem meines unbekannten Funkprotokolls (RIO-Fernbedienung) letztendlich lösen.

=== Konfiguration ===

Last but not least meine Konfiguration: SDUINO Firmware war die Version v3.4.1_dev_21.12

Register-Settings:

* Trägerfrequenz: 868.302 MHz
* Deviation: 25 kHz
* Bandwidth: 58 kHz
* Baudrate: 24.795 kBaud
* Modulation: GFSK

<pre>ccregAll:

ccreg 00: 0D 2E 2D 47 D3 91 3D 04 32 00 00 06 00 21 65 6F
ccreg 10: F9 F4 18 23 B9 40 07 00 18 14 6C 07 00 91 87 6B
ccreg 20: F8 56 11 EF 2D 12 1F 41 00 59 7F 3F 88 31 0B

Configuration Register Detail (address, name, value):
0x00 IOCFG2 - 0x0D
0x01 IOCFG1 - 0x2E
0x02 IOCFG0 - 0x2D
0x03 FIFOTHR - 0x47
0x04 SYNC1 - 0xD3
0x05 SYNC0 - 0x91
0x06 PKTLEN - 0x3D
0x07 PKTCTRL1 - 0x04
0x08 PKTCTRL0 - 0x32
0x09 ADDR - 0x00
0x0A CHANNR - 0x00
0x0B FSCTRL1 - 0x06
0x0C FSCTRL0 - 0x00
0x0D FREQ2 - 0x21
0x0E FREQ1 - 0x65
0x0F FREQ0 - 0x6F
0x10 MDMCFG4 - 0xF9
0x11 MDMCFG3 - 0xF4
0x12 MDMCFG2 - 0x18
0x13 MDMCFG1 - 0x23
0x14 MDMCFG0 - 0xB9
0x15 DEVIATN - 0x40
0x16 MCSM2 - 0x07
0x17 MCSM1 - 0x00
0x18 MCSM0 - 0x18
0x19 FOCCFG - 0x14
0x1A BSCFG - 0x6C
0x1B AGCCTRL2 - 0x07
0x1C AGCCTRL1 - 0x00
0x1D AGCCTRL0 - 0x91
0x1E WOREVT1 - 0x87
0x1F WOREVT0 - 0x6B
0x20 WORCTRL - 0xF8
0x21 FREND1 - 0x56
0x22 FREND0 - 0x11
0x23 FSCAL3 - 0xEF
0x24 FSCAL2 - 0x2D
0x25 FSCAL1 - 0x12
0x26 FSCAL0 - 0x1F
0x27 RCCTRL1 - 0x41
0x28 RCCTRL0 - 0x00
0x29 FSTEST - 0x59
0x2A PTEST - 0x7F
0x2B AGCTEST - 0x3F
0x2C TEST2 - 0x88
0x2D TEST1 - 0x31
0x2E TEST0 - 0x0B
</pre>

=== Finale ===

Nach Aktivierung der vormals ausgeschalteten Message-Typen im SIGNALduino werden nunmehr SD_Keeloq-Devices angelegt.

Der SIGNALduino erkennt
<pre>
2020.01.12 14:33:03 4: mySIGNALduino: Parse_MS, Decoded matched MS Protocol id 88 dmsg P88#74D21B18008B48058 length 68 RSSI = -32
2020.01.12 14:33:03 5: mySIGNALduino: Dispatch, P88#74D21B18008B48058, test ungleich: disabled
2020.01.12 14:33:03 5: mySIGNALduino: Dispatch, P88#74D21B18008B48058, -32 dB, dispatch
2020.01.12 14:33:03 5: mySIGNALduino: dispatch P88#74D21B18008B48058
2020.01.12 14:33:04 2: mySIGNALduino: SD_Keeloq_Parse Unknown device unknown with Code 012D100 detected, please define (rawdate=74D21B18008B48058)
2020.01.12 14:33:04 2: autocreate: define SD_Keeloq_012D100 SD_Keeloq 012D100
2020.01.12 14:33:04 2: autocreate: define FileLog_SD_Keeloq_012D100 FileLog ./log/SD_Keeloq_012D100-%Y.log SD_Keeloq_012D100
2020.01.12 14:33:04 4: mySIGNALduino: Parse_MS, Matched MS Protocol id 91.1 -> Atlantic security
2020.01.12 14:33:04 5: mySIGNALduino: Parse_MS, Starting demodulation at Position 3
2020.01.12 14:33:04 4: mySIGNALduino: Parse_MS, last part pair=2 reconstructed, last bit=0
2020.01.12 14:33:04 4: mySIGNALduino: Parse_MS, Matched MS Protocol id 87 -> JAROLIFT
2020.01.12 14:33:04 5: mySIGNALduino: Parse_MS, Starting demodulation at Position 2
2020.01.12 14:33:04 4: mySIGNALduino: Parse_MS, last part pair=1 reconstructed, last bit=1
2020.01.12 14:33:04 4: mySIGNALduino: Parse_MS, Matched MS Protocol id 88 -> HCS300/HCS301
2020.01.12 14:33:04 5: mySIGNALduino: Parse_MS, Starting demodulation at Position 2
</pre>
und routet die Requests an das Modul SD_Keeloq weiter. Der Hinweis auf HCS301 führt auf die richtige Spur. Das analysierte Protokoll KeeLoq ist im Data Sheet des Microchip HCS301 (KeeLoq Code Hopping Encoder) beschrieben. Somit wurde aus einem unbekannten Funkprotokoll letztlich ein bekanntes.

Mittlerweile ist das Protokoll als '''model enjoy_motors_HS''' in das Modul '''SD_Keeloq''' aufgenommen.

== CUL - FSK und Co. ==

Dieses Kapitel geht davon aus, dass ihr einen CUL für alle weiteren Schritte nutzt.

Es befindet sich aber noch im Aufbau....

== FAQ ==

=== Woran genau wird erkannt ob ein Signal ShortHigh, bzw ShortLow ist? ===

Diese Begriffe kommen nur bei der Manchester Codierung zum Einsatz.

Die Bestimmung short High / Low erfolgt einfach dadurch, ob gesendet wird oder ob gerade eine Pause eingelegt wird.

Short und Long wird einfach durch die Kalkulation der Dauer ermittelt.

Die Dauer eines short Intervalles ist in der Regel halb so lang wie die von einem long und entspricht der Taktrate.
Bei der ganzen Berechnung müssen natürlich Toleranzen berücksichtigt werden.

Beispiel einer empfangenen Sequenz

<code>P0=-32001;P1=15874;P2=-364;P3=447;P4=4060;P5=-762;P6=853;D=01232323232323232323232324</code>

P0, P2 + P5 haben ein negatives Vorzeichen. Damit ist gemeint, dass für eine Zeit von 762µs (P5) kein Signal empfangen wurde (Low). Die positiven sind dann High.

Generell sind die absoluten, gemessenen low-Werte bei Signalduino kürzer als die high-Werte.

Wie bereits ausgeführt, werden für die Daten die Pulse P2, P3, P5 und P6 genutzt. Der Mittelwert [ (P2 + P3 + P5 + P6) / 6 ] der absoluten Werte ergibt 404µs für ein Short und 808µs ein Long (2xShort). Idealisiert werden 400µs angenommen.

Das Umwandeln der Pulse in den Daten in eine "sSlL-Notation" vereinfacht die Erkennung von Mustern (in mehreren Nachrichten variieren auch die Pulse).
Dass ein lS=1 und sL=0 entspricht, ist nur eine willkürlich angenommene Arbeitshypothese, die bis dato ganz gute Ergebnisse produziert hat.

== Links ==

* [https://github.com/RFD-FHEM/RFFHEM RFFHEM git repository] (drandenken: korrekten Branch auswählen!)
* [https://www.hamspirit.de/2286/signalanalyse-fuer-dummies/ Signalanalyse für Dummies]
* [https://github.com/jopohl/urh Universal Radio Hacker]
* [https://www.elttam.com.au/blog/intro-sdr-and-rf-analysis/ Intro SDR and RF Analysis]
* [https://www.sigidwiki.com/wiki/Signal_Identification_Guide Signal Identification Guide]
* [https://www.rtl-sdr.com/tag/fsk/ Unknown Signal Reverse Engineering and Decoding AFSK Signals Tutorial]
* [[Intertechno Code Berechnung]]
* [[Funksignalanalyse mit DVB-T Stick]]

[[Kategorie:Intertechno]]
[[Kategorie:HOWTOS]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

DevelopmentModuleIntro

2023-01-04T18:18:03Z

Sidey: 98_Hello aktualisiert, Referenz auf Template Repository auf Github hinterlegt

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}
== Einleitung ==
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.

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.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick könnte beispielsweise mit dem Befehl <code>define JeeLink1 ''JeeLink'' /dev/ttyUSB0@57600</code> definiert werden.

In fhem.pl wird der <code>define</code>-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist. Falls nicht, wird ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und, falls vorhanden, anschließend geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt und durch welche Perl-Funktionen im Modul selbst diese ausimplementiert werden.

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.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''_''['''Modulname''']''.pm</code>

* '''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]])
* '''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 (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<syntaxhighlight lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Hilfsmodule
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deutsche Commandref in HTML
=end html

# Ende der Commandref
=cut
</syntaxhighlight>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# 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.
# 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]].

== Der Hash einer Geräteinstanz ==
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.

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.

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</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.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
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.

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.

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.

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.

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.

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}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <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.
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>.

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 .
|-
| <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.
|-
| <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.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <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.
|-
| <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.
|-
| <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.
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.
|-
| <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.

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>.
|-
| <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.
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>.
|}

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.

== Internals ==
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.

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.

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:

* <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.
* <code>$hash->{'''.'''ELEMENT}</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.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <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]].
|-
| <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.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <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.
|-
| <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".
|-
| <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".
|-
| <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.
|-
| <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.
|-
| <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.
|-
| <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.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
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
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

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.

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.

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.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code> (mehrfach wiederholt), <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code>
*bei einzelnen Updates die Funktion <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code>
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.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</syntaxhighlight>

Um Readings zu löschen, wird für die Modulprogrammierung die Funktion <code>[[DevelopmentModuleAPI#readingsDelete|readingsDelete()]]</code> empfohlen. Beispiel:

<syntaxhighlight lang="perl">
readingsDelete($hash, $readingsname)
</syntaxhighlight>
{{Hinweis|'''Hintergrundinfo dazu aus dem Forum:''' {{Link2Forum|Topic=83069|Message=753066}}

<code>CommandDeleteReading()</code> bzw. <code>deletereading</code> ist eher fuer den Endbenutzer und seine userReadings gedacht, und macht bei den Modulen die unnoetige Schleife ueber [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wenn der Modulautor beim Aufruf auch <code>$cl</code> weitergibt, und der Anwender meint, dieses Geraet auf blacklist setzen zu muessen, dann kann das Modul sein eigenes Reading nicht entfernen, und das ist kontraproduktiv.
}}

== Events ==

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.

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.

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.

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.

=== globale Events ===

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.

Hier eine kurze Zusammenfassung, welche Events durch <code>global</code> getriggert werden können:

Allgemeine Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| 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.
|-
| 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")
|-
| 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")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SHUTDOWN</code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code> DELAYEDSHUTDOWN </code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UPDATE</code>''' || Es wurde ein Update erfolgreich installiert. (FHEM-Befehl: "update")
|}

Definitionsbezogene Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| 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")
|-
| 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")
|-
| 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")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>MODIFIED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde modifiziert. (FHEM-Befehl: "modify")
|-
| 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)]].
|}

=== Begrenzung von Events ===

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.

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()]].

=== Reihenfolge der Eventverarbeitung ===

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.

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.

Details, wie man die Reihenfolge der Eventverarbeitung steuern kann, findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

== Attribute ==
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.
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.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

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).

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.

== Modulfunktionen ==

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.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#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.
|}

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:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#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.
|-
| [[#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.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#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.
|-
| [[#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.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|-
| [[#X_DelayedShutdown | X_DelayedShutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<syntaxhighlight lang="perl">
sub X_Initialize
{
my ($hash) = @_;
...
}
</syntaxhighlight>

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.

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:

<syntaxhighlight lang="perl" line="1">
$hash->{DefFn} = \&X_Define;
$hash->{UndefFn} = \&X_Undef;
$hash->{DeleteFn} = \&X_Delete;
$hash->{SetFn} = \&X_Set;
$hash->{GetFn} = \&X_Get;
$hash->{AttrFn} = \&X_Attr;
$hash->{ReadFn} = \&X_Read;
$hash->{ReadyFn} = \&X_Ready;
$hash->{NotifyFn} = \&X_Notify;
$hash->{RenameFn} = \&X_Rename;
$hash->{ShutdownFn} = \&X_Shutdown;
$hash->{DelayedShutdownFn} = \&X_ DelayedShutdown;
</syntaxhighlight>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</code> definiert ist, in <code>$hash</code> bekanntgemacht werden. Vorzugsweise direkt wie im Beispiel als Codereferenz. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden, wenn diese im Package "main" veröffentlicht werden.
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.

Darüber hinaus sollten die vom Modul unterstützten Attribute definiert werden:

<syntaxhighlight lang="perl">
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</syntaxhighlight>

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.

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}}.

Nutzung von parseParams()

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modul-Autoren 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.

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:
<syntaxhighlight lang="perl">$hash->{parseParams} = 1;</syntaxhighlight>
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.

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</syntaxhighlight>

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.
Sie beginnt typischerweise mit:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</syntaxhighlight>

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

<syntaxhighlight lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</syntaxhighlight>

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:

<syntaxhighlight lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</syntaxhighlight>

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.

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.

===== Verfügbarkeit von Attributen =====
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.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</syntaxhighlight>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

Nutzung von parseParams()

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:
<syntaxhighlight lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Undef ====
<syntaxhighlight lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>
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]]).

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.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Undef($$)
{
my ( $hash, $name) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</syntaxhighlight>

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.

==== X_Delete ====
<syntaxhighlight lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>

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.

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.

Dies kann z.B. folgendes sein:

* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.
* Lösen von evtl. Pairings mit dem physikalischen Gerät

Beispiel:
<syntaxhighlight lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

# Löschen von Geräte-assoziiertem Temp-File
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)

return undef;
}
</syntaxhighlight>

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.

==== X_Get ====
<syntaxhighlight lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</syntaxhighlight>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> für eine Definition 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 Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$opt</code> plus optional weiterer Parameter <code>@args</code> übergeben. Als Rückgabewert <code>$result</code> 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>.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt));

if($opt eq "status")
{
...
}
elsif($opt eq "power")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Dies gilt insbesondere für den Aufruf <code>get ''<NAME>'' '''?'''</code>, welche durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB 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.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $opt choose one of status temperature humidity";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' status</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

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. Vielfach werden aber auch die vorhandenen Readings zurückgegeben.

Nutzung von parseParams()

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:
<syntaxhighlight lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<syntaxhighlight lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
return ($error, $skip_trigger);
}
</syntaxhighlight>

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 Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$cmd</code> und optional weitere Argumente <code>@args</code> übergeben. Als Rückgabewert <code>$error</code> 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.

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 optionale 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>).

Rückmeldungen (Fehler) von set-Befehlen sämtlicher Module, die im Rahmen der Ausführung eines getriggerten [[Notify]] auftreten, werden im FHEM Logfile festgehalten.

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 zu Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter (<code>@args</code>) übergeben um Zustände zu setzen/ändern.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</syntaxhighlight>

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. Dies gilt insbesondere für den Aufruf <code>set ''<NAME>'' '''?'''</code>, welcher durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB 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.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $cmd choose one of status power";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Set-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>power</code>

Dies würde in folgenden, mögliche Set-Befehle für einen User resultieren:

* <code>set ''<NAME>'' status</code>
* <code>set ''<NAME>'' power</code>
</ul>

Nutzung von SetExtensions.pm

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.

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:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</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.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</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.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</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.
|-
| 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.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der commandref zum {{Link2CmdRef|Anker=set|Label=set-Befehl}}.

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<syntaxhighlight lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</syntaxhighlight>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

Nutzung von parseParams()

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:
<syntaxhighlight lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

Nutzung von FHEMWEB-Widgets

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.
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:
set ''<NAME>'' ?

Beispiel:
<syntaxhighlight lang="perl">
return "Unknown argument $cmd, choose one of status:up,down power:on,off on:noArg off:noArg";
</syntaxhighlight>

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>timer:30,120,300
mode:verbose,ultra,relaxed</pre>

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.

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:

{| class="wikitable"
|-
! Zusatz !! Beispiel !! Beschreibung
|-
| '''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.
|-
| '''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.
|-
| '''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.
|-
| '''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.
|-
| '''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.
|}

Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der {{Link2CmdRef|Anker=widgetOverride}} unter widgetOverride zu FHEMWEB.

'''Hinweise'''

* 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.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</syntaxhighlight>

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.
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.
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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $aName, $aValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $aName/$aValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aValue/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aValue: $@";
return "Invalid Regex $aValue: $@";
}
}
}
return undef;
}
</syntaxhighlight>

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>.

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.

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.
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>.

Attributnamen mit Platzhaltern

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<syntaxhighlight lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</syntaxhighlight>
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.

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.
Dazu reicht ein Aufruf der Funktion [[DevelopmentModuleAPI#addToDevAttrList|addToDevAttrList()]]:

<syntaxhighlight lang="perl">
addToDevAttrList($name, $aName);
</syntaxhighlight>

==== X_Read ====
<syntaxhighlight lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
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.

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.
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.

<syntaxhighlight lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</syntaxhighlight>

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).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<syntaxhighlight lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</syntaxhighlight>

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:

* '''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.
* '''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.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

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.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

# This is relevant for Windows/USB only
if(defined($hash->{USBDev})) {
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
}
</syntaxhighlight>

==== X_Notify ====

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.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Ü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.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
}
</syntaxhighlight>

Begrenzung der Aufrufe auf bestimmte Geräte

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, das die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

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

<syntaxhighlight lang="perl">
in der Define-Funktion:

$hash->{NOTIFYDEV} = "global";
$hash->{NOTIFYDEV} = "global,Definition_.*";
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";
$hash->{NOTIFYDEV} = "global,TYPE=CUL_HM";
</syntaxhighlight>

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. Statt den Filter ''NOTIFYDEV'' direkt zu setzen, kann auch [[DevelopmentModuleAPI#setNotifyDev|setNotifyDev()]] aufgerufen werden. Letzteres ist v.a. dann zu empfehlen, wenn Änderungen zur Laufzeit erfolgen sollen.

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></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.

Reihenfolge für den Aufruf der Notify-Funktion beeinflussen

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.

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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</syntaxhighlight>

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.

==== X_Rename ====
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name) = @_;

...
}
</syntaxhighlight>

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.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $old_pwd) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $old_pwd);
setKeyValue($old_index, undef);
}
</syntaxhighlight>

==== X_DelayedShutdown ====
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ( $hash ) = @_;

...

return $delay_needed;
}
</syntaxhighlight>
Mit der X_DelayedShutdown Funktion kann eine Definition das Stoppen von FHEM verzögern um asynchron hinter sich aufzuräumen. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.), welcher mehrfache Requests/Responses benötigt. Als Übergabeparameter wird der Geräte-Hash <code>$hash</code> bereitgestellt. Je nach Rückgabewert <code>$delay_needed</code> wird der Stopp von FHEM verzögert. Ist ein verzögerter Stopp von FHEM notwendig, darf der Rückgabewert in diesem Fall nicht <code>0</code> oder <code>undef</code> sein.

Im Unterschied zur [[#X_Shutdown|Shutdown]]-Funktion steht vor einem bevorstehenden Stopp von FHEM für einen User-konfigurierbaren Zeitraum (global-Attribut: <code>maxShutdownDelay</code> / Standard: 10 Sekunden) weiterhin die asynchrone FHEM Infrastruktur ([[DevIo]]/[[#X_Read|Read]]-Funktion und [[DevelopmentModuleAPI#InternalTimer|InternalTimer]]) zur Verfügung.

Sobald alle nötigen Maßnahmen erledigt sind, muss der Abschluss mit [[DevelopmentModuleAPI#CancelDelayedShutdown|CancelDelayedShutdown(<code>$name</code>)]] an FHEM zurückgemeldet werden.

Beispiel:
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ($hash) = @_;

# Aufräumen starten

return 1;
}
</syntaxhighlight>

==== X_Shutdown ====
<syntaxhighlight lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
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.). Nach der Ausführung der Shutdown-Fuktion wird FHEM sofort beendet. Falls vor dem Herunterfahren von FHEM asynchrone Kommunikation (via [[DevIo]]/[[#X_Read|X_Read]]) notwendig ist um eine vorhandene Verbindung sauber zu beenden, sollte man [[#X_DelayedShutdownFn|X_DelayedShutdownFn]] verwenden.

Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</syntaxhighlight>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#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.
|}

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 dienen dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
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.}}
<syntaxhighlight lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</syntaxhighlight>

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.

Ü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 Bereich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<syntaxhighlight lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</syntaxhighlight>

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]]).

Beispiel:

<syntaxhighlight lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</syntaxhighlight>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
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. }}
<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</syntaxhighlight>

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 physikalischem Modul abzustimmen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</syntaxhighlight>

==== X_Fingerprint ====
<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</syntaxhighlight>

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.

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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</syntaxhighlight>

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.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modul-Autoren 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.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

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:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorized|Authorized()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<syntaxhighlight lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

return ( $reading, $value, $unit );
}
</syntaxhighlight>

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modul-Autor 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.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<syntaxhighlight lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</syntaxhighlight>

==== X_Except ====
<syntaxhighlight lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>

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.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">
use IO::File;

...

sub X_Except ($)
{
my ( $hash ) = @_;

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</syntaxhighlight>

==== X_Copy ====
<syntaxhighlight lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</syntaxhighlight>

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.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</syntaxhighlight>

==== X_AsyncOutput ====
{{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, ...).}}
<syntaxhighlight lang="perl">
sub X_AsyncOutput ($)
{
my ( $client_hash, $text ) = @_;

...

return $error;
}
</syntaxhighlight>

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.

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.

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.

==== X_ActivateInform====
{{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, ...).}}
<syntaxhighlight lang="perl">
sub X_ActivateInform($$)
{
my ( $client_hash, $arg ) = @_;

...
}
</syntaxhighlight>

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.

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).

==== X_State ====
<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</syntaxhighlight>

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:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan="2" align="center" | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <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.
|-
| <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>).
|-
| <code>$value</code> || Den Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Den Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

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.

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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</syntaxhighlight>

==== X_Authorize ====
<syntaxhighlight lang="perl">
sub X_Authorize($$$$)
{
my ( $hash, $client_hash, $type, $arg ) = @_;

...

return $authorized;
}
</syntaxhighlight>

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.

Es gibt aktuell folgende <code>$type</code>/<code>$arg</code> Kombinationen, mit denen die Authorize-Funktion aufgerufen werden:

{| class="wikitable"
|-
! $type !! $arg !! Überschrift
|-
| rowspan="3" style="white-space: nowrap;" | <code>'''$type''' = "cmd"</code>

''Befehlsausführung''
| 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.
|-
| 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.

Bsp: <code>{ReadingsVal("Lampe", "state", "off"}</code>
|-
| 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.

Bsp: <code>"/opt/fhem/myScript.sh"</code>
|-
| style="white-space: nowrap;" | <code>'''$type''' = "devicename"</code>

''Sichtbarkeit von Geräten/Definitionen''
| 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.
|}

==== X_Authenticate ====
{{Link2Forum|Topic=72757|Message=644098}}

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

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.

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:

<syntaxhighlight lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optionaler Filter für Clientmodule als regulärer Ausdruck
ClientFilter => "FHEMWEB"
};
}
</syntaxhighlight>

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.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<syntaxhighlight lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</syntaxhighlight>

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.

== Pollen von Geräten ==
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.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<syntaxhighlight lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</syntaxhighlight>

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.

In der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<syntaxhighlight lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</syntaxhighlight>

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.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<syntaxhighlight lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</syntaxhighlight>
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.

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:

<syntaxhighlight lang="perl">
my $name = $hash->{NAME};
</syntaxhighlight>

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
<code>attr <NAME> verbose</code> verwenden. Beispielsweise <code>attr Lichtschalter_Wohnzimmer verbose 5</code>

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.

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.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts|Schematische Darstellung am Beispiel CUL]]
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:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* 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.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

physisches Modul

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.).

Empfangene Nutzdaten werden als Zeichenkette über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

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.

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.

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.

logisches Modul

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.

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).

=== Die Client-Liste ===

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.

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).

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:
<pre>
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
</pre>
Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* 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]])
* 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.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</syntaxhighlight>

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:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";

# ggf.
$hash->{ClientsKeepOrder} = 1
}
</syntaxhighlight>

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>''':'''<Modulname>''':'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

Wird das Internal "ClientsKeepOrder" auf 1 gesetzt, können in "Clients" keine regulären Ausdrücke mehr angegeben werden. Dies hat einen erheblichen Einfluss, auf die Verarbeitungsdauer und sollte in Betracht gezogen werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<syntaxhighlight lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</syntaxhighlight>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
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 bisher 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 direkt durch Aufruf der [[#X_Parse|Parse]]-Funktion verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

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.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<syntaxhighlight lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</syntaxhighlight>

Das Sortierpräfix (<code>1:FS20</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.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</syntaxhighlight>

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:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</syntaxhighlight>

=== Der Match-Ausdruck ===

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.

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.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</syntaxhighlight>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.
* [[#X_DelayedShutdown | DelayedShutdown]]-Funktion - Verzögertes beenden zum Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

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.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

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.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

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.

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.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

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.

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.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

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.

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.

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.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

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):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter...>''

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.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

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.

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.

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:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</syntaxhighlight>

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.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| 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.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| 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.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| 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.

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.

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.

|-
| 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.

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.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.
|-
| 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.
|}

== Ergänzende Hinweise ==
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.

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.

== Weitere Informationen ==
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.

== "Hello World" Beispiel ==

98_Hello.pm

<syntaxhighlight lang="perl" line="1">
package main;
use strict;
use warnings;

my %Hello_gets = (
"whatyouwant" => "can't",
"whatyouneed" => "try sometimes",
"satisfaction" => "no"
);

sub Hello_Initialize {
my ($hash) = @_;

$hash->{DefFn} = \&Hello_Define;
$hash->{UndefFn} = \&Hello_Undef;
$hash->{SetFn} = \&Hello_Set;
$hash->{GetFn} = \&Hello_Get;
$hash->{AttrFn} = \&Hello_Attr;
$hash->{ReadFn} = \&Hello_Read;

$hash->{AttrList} =
"formal:yes,no "
. $readingFnAttributes;
}

sub Hello_Define {
my ($hash, $def) = @_;
my @param = split('[ \t]+', $def);

if(int(@param) < 3) {
return "too few parameters: define <name> Hello <greet>";
}

$hash->{name} = $param[0];
$hash->{greet} = $param[2];

return ;
}

sub Hello_Undef {
my ($hash, $arg) = @_;
# nothing to do
return ;
}

sub Hello_Get {
my ($hash, @param) = @_;

return '"get Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
if(!$Hello_gets{$opt}) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}

if($attr{$name}{formal} eq 'yes') {
return $Hello_gets{$opt}.', sir';
}
return $Hello_gets{$opt};
}

sub Hello_Set {
my ($hash, @param) = @_;

return '"set Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
my $value = join("", @param);

if(!defined($Hello_gets{$opt})) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
$hash->{STATE} = $Hello_gets{$opt} = $value;

return "$opt set to $value. Try to get it.";
}

sub Hello_Attr {
my ($cmd,$name,$attr_name,$attr_value) = @_;
if($cmd eq "set") {
if($attr_name eq "formal") {
if($attr_value !~ /^yes|no$/) {
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";
Log 3, "Hello: ".$err;
return $err;
}
} else {
return "Unknown attr $attr_name";
}
}
return ;
}

1;

=pod
=begin html

<a name="Hello"></a>
<h3>Hello</h3>
<ul>
Hello implements the classical "Hello World" as a starting point for module development.
You may want to copy 98_Hello.pm to start implementing a module of your very own. See
<a href="http://wiki.fhem.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an
in-depth instruction to your first module.
 
<a name="Hellodefine"></a>
Define
<ul>
<code>define <name> Hello <greet></code>
 
Example: <code>define HELLO Hello TurnUrRadioOn</code>
 
The "greet" parameter has no further meaning, it just demonstrates
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a>
for more info about the define command.
</ul>
 

<a name="Helloset"></a>
Set 
<ul>
<code>set <name> <option> <value></code>
 
You can set any value to any of the following options. They're just there to
get them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a>
for more info about the set command.
 
Options:
<ul>
<li>satisfaction 
Defaults to "no"</li>
<li>whatyouwant 
Defaults to "can't"</li>
<li>whatyouneed 
Defaults to "try sometimes"</li>
</ul>
</ul>
 

<a name="Helloget"></a>
Get 
<ul>
<code>get <name> <option></code>
 
You can get the value of any of the options described in
<a href="#Helloset">paragraph "Set" above</a>. See
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about
the get command.
</ul>
 

<a name="Helloattr"></a>
Attributes
<ul>
<code>attr <name> <attribute> <value></code>
 
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about
the attr command.
 
Attributes:
<ul>
<li>formal no|yes 
When you set formal to "yes", all output of get will be in a
more formal language. Default is "no".
</li>
</ul>
</ul>
</ul>

=end html

=cut
</syntaxhighlight>

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]]

==== Entwicklungsumgebung ====
Eine vorbereite Entwicklungsumgebung steht in Github in Form eines Vorlagen Repository bereit:

Es beinhaltet eine CI/CD Pipeline um das eigene Modul automatisiert zu testen: https://github.com/fhem/mod_template
[[Kategorie:Development]]

DevelopmentModuleIntro

2023-01-04T18:09:49Z

Sidey: Initalize Funktion überarbeitet (coderefs anstelle von Funktionsnamen)

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}
== Einleitung ==
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.

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.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick könnte beispielsweise mit dem Befehl <code>define JeeLink1 ''JeeLink'' /dev/ttyUSB0@57600</code> definiert werden.

In fhem.pl wird der <code>define</code>-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist. Falls nicht, wird ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und, falls vorhanden, anschließend geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt und durch welche Perl-Funktionen im Modul selbst diese ausimplementiert werden.

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.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''_''['''Modulname''']''.pm</code>

* '''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]])
* '''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 (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<syntaxhighlight lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Hilfsmodule
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deutsche Commandref in HTML
=end html

# Ende der Commandref
=cut
</syntaxhighlight>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# 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.
# 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]].

== Der Hash einer Geräteinstanz ==
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.

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.

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</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.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
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.

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.

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.

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.

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.

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}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <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.
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>.

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 .
|-
| <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.
|-
| <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.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <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.
|-
| <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.
|-
| <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.
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.
|-
| <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.

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>.
|-
| <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.
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>.
|}

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.

== Internals ==
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.

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.

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:

* <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.
* <code>$hash->{'''.'''ELEMENT}</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.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <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]].
|-
| <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.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <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.
|-
| <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".
|-
| <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".
|-
| <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.
|-
| <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.
|-
| <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.
|-
| <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.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
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
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

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.

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.

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.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code> (mehrfach wiederholt), <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code>
*bei einzelnen Updates die Funktion <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code>
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.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</syntaxhighlight>

Um Readings zu löschen, wird für die Modulprogrammierung die Funktion <code>[[DevelopmentModuleAPI#readingsDelete|readingsDelete()]]</code> empfohlen. Beispiel:

<syntaxhighlight lang="perl">
readingsDelete($hash, $readingsname)
</syntaxhighlight>
{{Hinweis|'''Hintergrundinfo dazu aus dem Forum:''' {{Link2Forum|Topic=83069|Message=753066}}

<code>CommandDeleteReading()</code> bzw. <code>deletereading</code> ist eher fuer den Endbenutzer und seine userReadings gedacht, und macht bei den Modulen die unnoetige Schleife ueber [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wenn der Modulautor beim Aufruf auch <code>$cl</code> weitergibt, und der Anwender meint, dieses Geraet auf blacklist setzen zu muessen, dann kann das Modul sein eigenes Reading nicht entfernen, und das ist kontraproduktiv.
}}

== Events ==

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.

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.

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.

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.

=== globale Events ===

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.

Hier eine kurze Zusammenfassung, welche Events durch <code>global</code> getriggert werden können:

Allgemeine Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| 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.
|-
| 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")
|-
| 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")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SHUTDOWN</code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code> DELAYEDSHUTDOWN </code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UPDATE</code>''' || Es wurde ein Update erfolgreich installiert. (FHEM-Befehl: "update")
|}

Definitionsbezogene Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| 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")
|-
| 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")
|-
| 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")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>MODIFIED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde modifiziert. (FHEM-Befehl: "modify")
|-
| 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)]].
|}

=== Begrenzung von Events ===

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.

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()]].

=== Reihenfolge der Eventverarbeitung ===

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.

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.

Details, wie man die Reihenfolge der Eventverarbeitung steuern kann, findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

== Attribute ==
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.
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.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

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).

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.

== Modulfunktionen ==

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.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#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.
|}

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:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#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.
|-
| [[#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.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#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.
|-
| [[#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.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|-
| [[#X_DelayedShutdown | X_DelayedShutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
}
</syntaxhighlight>

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.

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:

<syntaxhighlight lang="perl">
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
$hash->{NotifyFn} = "X_Notify";
$hash->{RenameFn} = "X_Rename";
$hash->{ShutdownFn} = "X_Shutdown";
$hash->{DelayedShutdownFn} = "X_ DelayedShutdown";
</syntaxhighlight>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</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.
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.

Darüber hinaus sollten die vom Modul unterstützten Attribute definiert werden:

<syntaxhighlight lang="perl">
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</syntaxhighlight>

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.

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}}.

Nutzung von parseParams()

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modul-Autoren 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.

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:
<syntaxhighlight lang="perl">$hash->{parseParams} = 1;</syntaxhighlight>
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.

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</syntaxhighlight>

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.
Sie beginnt typischerweise mit:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</syntaxhighlight>

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

<syntaxhighlight lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</syntaxhighlight>

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:

<syntaxhighlight lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</syntaxhighlight>

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.

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.

===== Verfügbarkeit von Attributen =====
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.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</syntaxhighlight>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

Nutzung von parseParams()

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:
<syntaxhighlight lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Undef ====
<syntaxhighlight lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>
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]]).

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.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Undef($$)
{
my ( $hash, $name) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</syntaxhighlight>

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.

==== X_Delete ====
<syntaxhighlight lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>

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.

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.

Dies kann z.B. folgendes sein:

* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.
* Lösen von evtl. Pairings mit dem physikalischen Gerät

Beispiel:
<syntaxhighlight lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

# Löschen von Geräte-assoziiertem Temp-File
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)

return undef;
}
</syntaxhighlight>

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.

==== X_Get ====
<syntaxhighlight lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</syntaxhighlight>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> für eine Definition 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 Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$opt</code> plus optional weiterer Parameter <code>@args</code> übergeben. Als Rückgabewert <code>$result</code> 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>.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt));

if($opt eq "status")
{
...
}
elsif($opt eq "power")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Dies gilt insbesondere für den Aufruf <code>get ''<NAME>'' '''?'''</code>, welche durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB 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.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $opt choose one of status temperature humidity";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' status</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

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. Vielfach werden aber auch die vorhandenen Readings zurückgegeben.

Nutzung von parseParams()

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:
<syntaxhighlight lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<syntaxhighlight lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
return ($error, $skip_trigger);
}
</syntaxhighlight>

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 Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$cmd</code> und optional weitere Argumente <code>@args</code> übergeben. Als Rückgabewert <code>$error</code> 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.

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 optionale 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>).

Rückmeldungen (Fehler) von set-Befehlen sämtlicher Module, die im Rahmen der Ausführung eines getriggerten [[Notify]] auftreten, werden im FHEM Logfile festgehalten.

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 zu Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter (<code>@args</code>) übergeben um Zustände zu setzen/ändern.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</syntaxhighlight>

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. Dies gilt insbesondere für den Aufruf <code>set ''<NAME>'' '''?'''</code>, welcher durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB 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.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $cmd choose one of status power";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Set-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>power</code>

Dies würde in folgenden, mögliche Set-Befehle für einen User resultieren:

* <code>set ''<NAME>'' status</code>
* <code>set ''<NAME>'' power</code>
</ul>

Nutzung von SetExtensions.pm

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.

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:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</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.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</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.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</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.
|-
| 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.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der commandref zum {{Link2CmdRef|Anker=set|Label=set-Befehl}}.

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<syntaxhighlight lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</syntaxhighlight>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

Nutzung von parseParams()

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:
<syntaxhighlight lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

Nutzung von FHEMWEB-Widgets

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.
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:
set ''<NAME>'' ?

Beispiel:
<syntaxhighlight lang="perl">
return "Unknown argument $cmd, choose one of status:up,down power:on,off on:noArg off:noArg";
</syntaxhighlight>

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>timer:30,120,300
mode:verbose,ultra,relaxed</pre>

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.

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:

{| class="wikitable"
|-
! Zusatz !! Beispiel !! Beschreibung
|-
| '''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.
|-
| '''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.
|-
| '''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.
|-
| '''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.
|-
| '''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.
|}

Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der {{Link2CmdRef|Anker=widgetOverride}} unter widgetOverride zu FHEMWEB.

'''Hinweise'''

* 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.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</syntaxhighlight>

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.
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.
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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $aName, $aValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $aName/$aValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aValue/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aValue: $@";
return "Invalid Regex $aValue: $@";
}
}
}
return undef;
}
</syntaxhighlight>

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>.

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.

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.
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>.

Attributnamen mit Platzhaltern

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<syntaxhighlight lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</syntaxhighlight>
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.

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.
Dazu reicht ein Aufruf der Funktion [[DevelopmentModuleAPI#addToDevAttrList|addToDevAttrList()]]:

<syntaxhighlight lang="perl">
addToDevAttrList($name, $aName);
</syntaxhighlight>

==== X_Read ====
<syntaxhighlight lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
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.

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.
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.

<syntaxhighlight lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</syntaxhighlight>

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).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<syntaxhighlight lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</syntaxhighlight>

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:

* '''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.
* '''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.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

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.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

# This is relevant for Windows/USB only
if(defined($hash->{USBDev})) {
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
}
</syntaxhighlight>

==== X_Notify ====

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.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Ü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.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
}
</syntaxhighlight>

Begrenzung der Aufrufe auf bestimmte Geräte

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, das die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

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

<syntaxhighlight lang="perl">
in der Define-Funktion:

$hash->{NOTIFYDEV} = "global";
$hash->{NOTIFYDEV} = "global,Definition_.*";
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";
$hash->{NOTIFYDEV} = "global,TYPE=CUL_HM";
</syntaxhighlight>

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. Statt den Filter ''NOTIFYDEV'' direkt zu setzen, kann auch [[DevelopmentModuleAPI#setNotifyDev|setNotifyDev()]] aufgerufen werden. Letzteres ist v.a. dann zu empfehlen, wenn Änderungen zur Laufzeit erfolgen sollen.

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></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.

Reihenfolge für den Aufruf der Notify-Funktion beeinflussen

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.

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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</syntaxhighlight>

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.

==== X_Rename ====
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name) = @_;

...
}
</syntaxhighlight>

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.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $old_pwd) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $old_pwd);
setKeyValue($old_index, undef);
}
</syntaxhighlight>

==== X_DelayedShutdown ====
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ( $hash ) = @_;

...

return $delay_needed;
}
</syntaxhighlight>
Mit der X_DelayedShutdown Funktion kann eine Definition das Stoppen von FHEM verzögern um asynchron hinter sich aufzuräumen. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.), welcher mehrfache Requests/Responses benötigt. Als Übergabeparameter wird der Geräte-Hash <code>$hash</code> bereitgestellt. Je nach Rückgabewert <code>$delay_needed</code> wird der Stopp von FHEM verzögert. Ist ein verzögerter Stopp von FHEM notwendig, darf der Rückgabewert in diesem Fall nicht <code>0</code> oder <code>undef</code> sein.

Im Unterschied zur [[#X_Shutdown|Shutdown]]-Funktion steht vor einem bevorstehenden Stopp von FHEM für einen User-konfigurierbaren Zeitraum (global-Attribut: <code>maxShutdownDelay</code> / Standard: 10 Sekunden) weiterhin die asynchrone FHEM Infrastruktur ([[DevIo]]/[[#X_Read|Read]]-Funktion und [[DevelopmentModuleAPI#InternalTimer|InternalTimer]]) zur Verfügung.

Sobald alle nötigen Maßnahmen erledigt sind, muss der Abschluss mit [[DevelopmentModuleAPI#CancelDelayedShutdown|CancelDelayedShutdown(<code>$name</code>)]] an FHEM zurückgemeldet werden.

Beispiel:
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ($hash) = @_;

# Aufräumen starten

return 1;
}
</syntaxhighlight>

==== X_Shutdown ====
<syntaxhighlight lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
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.). Nach der Ausführung der Shutdown-Fuktion wird FHEM sofort beendet. Falls vor dem Herunterfahren von FHEM asynchrone Kommunikation (via [[DevIo]]/[[#X_Read|X_Read]]) notwendig ist um eine vorhandene Verbindung sauber zu beenden, sollte man [[#X_DelayedShutdownFn|X_DelayedShutdownFn]] verwenden.

Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</syntaxhighlight>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#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.
|}

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 dienen dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
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.}}
<syntaxhighlight lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</syntaxhighlight>

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.

Ü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 Bereich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<syntaxhighlight lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</syntaxhighlight>

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]]).

Beispiel:

<syntaxhighlight lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</syntaxhighlight>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
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. }}
<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</syntaxhighlight>

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 physikalischem Modul abzustimmen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</syntaxhighlight>

==== X_Fingerprint ====
<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</syntaxhighlight>

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.

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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</syntaxhighlight>

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.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modul-Autoren 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.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

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:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorized|Authorized()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<syntaxhighlight lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

return ( $reading, $value, $unit );
}
</syntaxhighlight>

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modul-Autor 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.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<syntaxhighlight lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</syntaxhighlight>

==== X_Except ====
<syntaxhighlight lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>

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.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">
use IO::File;

...

sub X_Except ($)
{
my ( $hash ) = @_;

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</syntaxhighlight>

==== X_Copy ====
<syntaxhighlight lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</syntaxhighlight>

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.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</syntaxhighlight>

==== X_AsyncOutput ====
{{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, ...).}}
<syntaxhighlight lang="perl">
sub X_AsyncOutput ($)
{
my ( $client_hash, $text ) = @_;

...

return $error;
}
</syntaxhighlight>

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.

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.

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.

==== X_ActivateInform====
{{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, ...).}}
<syntaxhighlight lang="perl">
sub X_ActivateInform($$)
{
my ( $client_hash, $arg ) = @_;

...
}
</syntaxhighlight>

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.

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).

==== X_State ====
<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</syntaxhighlight>

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:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan="2" align="center" | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <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.
|-
| <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>).
|-
| <code>$value</code> || Den Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Den Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

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.

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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</syntaxhighlight>

==== X_Authorize ====
<syntaxhighlight lang="perl">
sub X_Authorize($$$$)
{
my ( $hash, $client_hash, $type, $arg ) = @_;

...

return $authorized;
}
</syntaxhighlight>

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.

Es gibt aktuell folgende <code>$type</code>/<code>$arg</code> Kombinationen, mit denen die Authorize-Funktion aufgerufen werden:

{| class="wikitable"
|-
! $type !! $arg !! Überschrift
|-
| rowspan="3" style="white-space: nowrap;" | <code>'''$type''' = "cmd"</code>

''Befehlsausführung''
| 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.
|-
| 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.

Bsp: <code>{ReadingsVal("Lampe", "state", "off"}</code>
|-
| 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.

Bsp: <code>"/opt/fhem/myScript.sh"</code>
|-
| style="white-space: nowrap;" | <code>'''$type''' = "devicename"</code>

''Sichtbarkeit von Geräten/Definitionen''
| 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.
|}

==== X_Authenticate ====
{{Link2Forum|Topic=72757|Message=644098}}

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

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.

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:

<syntaxhighlight lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optionaler Filter für Clientmodule als regulärer Ausdruck
ClientFilter => "FHEMWEB"
};
}
</syntaxhighlight>

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.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<syntaxhighlight lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</syntaxhighlight>

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.

== Pollen von Geräten ==
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.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<syntaxhighlight lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</syntaxhighlight>

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.

In der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<syntaxhighlight lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</syntaxhighlight>

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.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<syntaxhighlight lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</syntaxhighlight>
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.

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:

<syntaxhighlight lang="perl">
my $name = $hash->{NAME};
</syntaxhighlight>

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
<code>attr <NAME> verbose</code> verwenden. Beispielsweise <code>attr Lichtschalter_Wohnzimmer verbose 5</code>

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.

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.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts|Schematische Darstellung am Beispiel CUL]]
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:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* 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.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

physisches Modul

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.).

Empfangene Nutzdaten werden als Zeichenkette über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

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.

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.

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.

logisches Modul

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.

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).

=== Die Client-Liste ===

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.

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).

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:
<pre>
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
</pre>
Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* 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]])
* 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.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</syntaxhighlight>

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:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";

# ggf.
$hash->{ClientsKeepOrder} = 1
}
</syntaxhighlight>

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>''':'''<Modulname>''':'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

Wird das Internal "ClientsKeepOrder" auf 1 gesetzt, können in "Clients" keine regulären Ausdrücke mehr angegeben werden. Dies hat einen erheblichen Einfluss, auf die Verarbeitungsdauer und sollte in Betracht gezogen werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<syntaxhighlight lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</syntaxhighlight>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
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 bisher 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 direkt durch Aufruf der [[#X_Parse|Parse]]-Funktion verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

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.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<syntaxhighlight lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</syntaxhighlight>

Das Sortierpräfix (<code>1:FS20</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.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</syntaxhighlight>

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:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</syntaxhighlight>

=== Der Match-Ausdruck ===

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.

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.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</syntaxhighlight>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.
* [[#X_DelayedShutdown | DelayedShutdown]]-Funktion - Verzögertes beenden zum Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

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.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

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.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

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.

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.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

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.

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.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

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.

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.

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.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

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):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter...>''

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.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

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.

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.

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:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</syntaxhighlight>

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.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| 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.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| 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.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| 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.

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.

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.

|-
| 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.

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.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.
|-
| 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.
|}

== Ergänzende Hinweise ==
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.

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.

== Weitere Informationen ==
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.

== "Hello World" Beispiel ==

98_Hello.pm

<syntaxhighlight lang="perl" line="1">
package main;
use strict;
use warnings;

my %Hello_gets = (
"whatyouwant" => "can't",
"whatyouneed" => "try sometimes",
"satisfaction" => "no"
);

sub Hello_Initialize {
my ($hash) = @_;

$hash->{DefFn} = \&Hello_Define;
$hash->{UndefFn} = \&Hello_Undef;
$hash->{SetFn} = \&Hello_Set;
$hash->{GetFn} = \&Hello_Get;
$hash->{AttrFn} = \&ello_Attr;
$hash->{ReadFn} = \&Hello_Read;

$hash->{AttrList} =
"formal:yes,no "
. $readingFnAttributes;
}

sub Hello_Define($$) {
my ($hash, $def) = @_;
my @param = split('[ \t]+', $def);

if(int(@param) < 3) {
return "too few parameters: define <name> Hello <greet>";
}

my $hash->{name} = $param[0];
my $hash->{greet} = $param[2];

return undef;
}

sub Hello_Undef($$) {
my ($hash, $arg) = @_;
# nothing to do
return undef;
}

sub Hello_Get($@) {
my ($hash, @param) = @_;

return '"get Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
if(!$Hello_gets{$opt}) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}

if($attr{$name}{formal} eq 'yes') {
return $Hello_gets{$opt}.', sir';
}
return $Hello_gets{$opt};
}

sub Hello_Set($@) {
my ($hash, @param) = @_;

return '"set Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
my $value = join("", @param);

if(!defined($Hello_gets{$opt})) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
$hash->{STATE} = $Hello_gets{$opt} = $value;

return "$opt set to $value. Try to get it.";
}

sub Hello_Attr(@) {
my ($cmd,$name,$attr_name,$attr_value) = @_;
if($cmd eq "set") {
if($attr_name eq "formal") {
if($attr_value !~ /^yes|no$/) {
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";
Log 3, "Hello: ".$err;
return $err;
}
} else {
return "Unknown attr $attr_name";
}
}
return undef;
}

1;

=pod
=begin html

<a id="Hello"></a>
<h3>Hello</h3>
<ul>
Hello implements the classical "Hello World" as a starting point for module development.
You may want to copy 98_Hello.pm to start implementing a module of your very own. See
<a href="http://wiki.fhem.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an
in-depth instruction to your first module.
 
<a id="Hello-define"></a>
Define
<ul>
<code>define <name> Hello <greet></code>
 
Example: <code>define HELLO Hello TurnUrRadioOn</code>
 
The "greet" parameter has no further meaning, it just demonstrates
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a>
for more info about the define command.
</ul>
 

<a id="Hello-set"></a>
Set 
<ul>
<code>set <name> <option> <value></code>
 
You can set any value to any of the following options. They're just there to
get them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a>
for more info about the set command.
 
Options:
<ul>
<li>satisfaction 
Defaults to "no"</li>
<li>whatyouwant 
Defaults to "can't"</li>
<li>whatyouneed 
Defaults to "try sometimes"</li>
</ul>
</ul>
 

<a id="Hello-get"></a>
Get 
<ul>
<code>get <name> <option></code>
 
You can get the value of any of the options described in
<a href="#Helloset">paragraph "Set" above</a>. See
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about
the get command.
</ul>
 

<a id="Hello-attr"></a>
Attributes
<ul>
<code>attr <name> <attribute> <value></code>
 
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about
the attr command.
 
Attributes:
<ul>
<li>formal no|yes 
When you set formal to "yes", all output of get will be in a
more formal language. Default is "no".
</li>
</ul>
</ul>
</ul>

=end html

=cut
</syntaxhighlight>

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]]

[[Kategorie:Development]]

SIGNALduino

2022-01-17T21:19:15Z

Sidey: /* FHEM-Modul laden */ Hinweis zu SVN Version aktualisiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (z.B. Raspberry) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt änderbarer/updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung auf Stick-Firmware-Seite korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichenden Frequenzen steuerbar sind; so empfangen die ''Somfy''-Rolladenmotoren beispielsweise auf 433.42 MHz und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "Aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum FHEMduino
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, Link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist momentan (für ordentlich breiten Support müsste man wohl eine CMake-Build-Config hinzufügen - ich sollte hier mal in die Pötte kommen...) nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird eine einfache Empfänger / Sender Kombination verwendet, dann über die Pins:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) - es wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:

''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''

Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltagstauglichen Zustand haben. Aktuell wird dort die Version 3.5.2 seit 18.01.2022 verteilt.

Mit Version 3.5.x ist die Unterstützung für Geräte mit FSK-Modulation integriert.

Die aktuell in Entwicklung befindlichen Version (3.5.3) kann über folgende Vorgehensweise installiert werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/master<nowiki/>/controls_signalduino.txt</code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.<code><nowiki/></code>
* Es empfiehlt sich, die Github-Quelle dauerhaft einzutragen: <code>update add https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/master/controls_signalduino.txt</code>, um weitere Entwicklungs-Updates zu bekommen, und damit das nächste Standard-<code>update</code> nicht die alte Version wieder einspielt.

Das Gerät kann wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen, ist die Syntax (ebenso wird auch vorgegangen wenn der SIGNALduino beispielsweise über ser2net freigeben wird):
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 -

Verbindungsversuche via telnet müssen dieselbe Baudrate verwenden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

Wenn ein miniCUL geflasht werden soll, sind einige Besonderheiten zu beachten. Details dazu in {{Link2Forum|Topic=114413|LinkText=diesem Forenthema}}.

==== Flashen einer Firmware über HTTP ====
Die Firmware wird nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Die Version 3.4 ist die aktuell stabile Version.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut <code>hardware</code> auf einen gültigen Wert angepasst werden!
Über den GET Befehl <code>availableFirmware</code> werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut <code>updateChannelFW</code> kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten Version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut <code>flashCommand</code> hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen ''Intertechno''-Funksteckdosen (''Brennenstuhl'') kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (<code>verbose</code> >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:

<pre>
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):
</pre>

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Modul, welches diese Protokolle verarbeitet.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist auch kurz und knapp manuell (also ohne Modul und automatisch angelegtem Gerät).

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes [[notify]]-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverständlich muss in diesem Moment auch eine <code>sub my_sender_trigger_indicate()</code> definiert werden (z.B. in <code>FHEM/99_myUtils.pm</code>), die dort z.B. als Test eine Log-Ausgabe (<code>Log3()</code>) machen kann.

=== Das Logfile ===
Im Logfile ab [[verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (<code>verbose</code> 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Internet-Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise folgende Bits-Bereiche enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Daten-Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich (identisch) erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut <code>WhitelistID</code> minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die <code>WhitelistID</code> aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann der Tabelle [[#Unterstützte Geräte|Unterstützte Geräte]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das Signal so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "Rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegebenen Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut <code>ITClock</code> eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt Geräte-Instanz-spezifische Konfiguration) das <code>ITclock</code> eines IT-Client-Devices.

== Fehlerbehandlung ==

=== Modul-Initialisierung ===

==== Perl-Modul Digest::CRC fehlt ====

Das FHEM-Log kann (bei ab Version 3.5.x ) folgendes enthalten:

<code>Can't locate Digest/CRC.pm in @INC (you may need to install the Digest::CRC module) (@INC contains: fhem.p/lib fhem.p/FHEM/lib ./FHEM/lib ./lib ./FHEM ./ /usr/local/FHEM/share/fhem/FHEM/lib /opt/fhem . /etc/perl /usr/local/lib/arm-linux-gnueabihf/perl/5.28.1 /usr/local/share/perl/5.28.1 /usr/lib/arm-linux-gnueabihf/perl5/5.28 /usr/share/perl5 /usr/lib/arm-linux-gnueabihf/perl/5.28 /usr/share/perl/5.28 /usr/local/lib/site_perl /usr/lib/arm-linux-gnueabihf/perl-base) at ./FHEM/00_SIGNALduino.pm line 28, <$fh> line 1870.
BEGIN failed--compilation aborted at ./FHEM/00_SIGNALduino.pm line 28, <$fh> line 1870.</code>

In diesem Fall ist der Transceiver nicht funktionsfähig - es muss erst Perl-Modul <code>Digest::CRC</code> (Ubuntu: Package <code>libdigest-crc-perl</code>) installiert werden und fhem neu gestartet werden.

=== Konfiguration von Firmware/Hardware (Reset usw.) ===
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl im Modul direkt ausgeführt werden können. Sofern möglich, sollte die Abfrage von Werten aus dem Modul allerdings mit den dafür vorgesehenen Kommandos erfolgen, da die Rückmeldungen des <code>set raw</code> Befehls nur im Logfile ab verbose 4 erscheinen. Die Befehle sind nützlich, wenn direkt auf den Microcontroller zugegriffen wird:

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: <code>set raw C35</code> führt ab verbose 4 zu einer Logausgabe folgender Art: <code>Read, msg: C35 = 0D</code>
:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot
:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die EEPROM Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2 des CC1101)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

DevelopmentModuleIntro

2022-01-12T21:34:12Z

Sidey: /* Die Client-Liste */ Internal ClientsKeepOrder ergänzt

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}
== Einleitung ==
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.

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.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick könnte beispielsweise mit dem Befehl <code>define JeeLink1 ''JeeLink'' /dev/ttyUSB0@57600</code> definiert werden.

In fhem.pl wird der <code>define</code>-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist. Falls nicht, wird ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und, falls vorhanden, anschließend geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt und durch welche Perl-Funktionen im Modul selbst diese ausimplementiert werden.

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.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''_''['''Modulname''']''.pm</code>

* '''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]])
* '''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 (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<syntaxhighlight lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Hilfsmodule
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deutsche Commandref in HTML
=end html

# Ende der Commandref
=cut
</syntaxhighlight>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# 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.
# 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]].

== Der Hash einer Geräteinstanz ==
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.

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.

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</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.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
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.

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.

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.

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.

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.

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}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <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.
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>.

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 .
|-
| <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.
|-
| <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.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <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.
|-
| <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.
|-
| <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.
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.
|-
| <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.

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>.
|-
| <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.
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>.
|}

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.

== Internals ==
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.

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.

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:

* <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.
* <code>$hash->{'''.'''ELEMENT}</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.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <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]].
|-
| <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.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <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.
|-
| <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".
|-
| <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".
|-
| <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.
|-
| <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.
|-
| <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.
|-
| <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.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
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
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

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.

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.

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.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code> (mehrfach wiederholt), <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code>
*bei einzelnen Updates die Funktion <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code>
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.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</syntaxhighlight>

Um Readings zu löschen, wird für die Modulprogrammierung die Funktion <code>[[DevelopmentModuleAPI#readingsDelete|readingsDelete()]]</code> empfohlen. Beispiel:

<syntaxhighlight lang="perl">
readingsDelete($hash, $readingsname)
</syntaxhighlight>
{{Hinweis|'''Hintergrundinfo dazu aus dem Forum:''' {{Link2Forum|Topic=83069|Message=753066}}

<code>CommandDeleteReading()</code> bzw. <code>deletereading</code> ist eher fuer den Endbenutzer und seine userReadings gedacht, und macht bei den Modulen die unnoetige Schleife ueber [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wenn der Modulautor beim Aufruf auch <code>$cl</code> weitergibt, und der Anwender meint, dieses Geraet auf blacklist setzen zu muessen, dann kann das Modul sein eigenes Reading nicht entfernen, und das ist kontraproduktiv.
}}

== Events ==

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.

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.

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.

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.

=== globale Events ===

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.

Hier eine kurze Zusammenfassung, welche Events durch <code>global</code> getriggert werden können:

Allgemeine Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| 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.
|-
| 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")
|-
| 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")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SHUTDOWN</code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code> DELAYEDSHUTDOWN </code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UPDATE</code>''' || Es wurde ein Update erfolgreich installiert. (FHEM-Befehl: "update")
|}

Definitionsbezogene Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| 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")
|-
| 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")
|-
| 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")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>MODIFIED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde modifiziert. (FHEM-Befehl: "modify")
|-
| 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)]].
|}

=== Begrenzung von Events ===

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.

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()]].

=== Reihenfolge der Eventverarbeitung ===

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.

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.

Details, wie man die Reihenfolge der Eventverarbeitung steuern kann, findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

== Attribute ==
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.
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.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

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).

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.

== Modulfunktionen ==

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.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#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.
|}

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:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#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.
|-
| [[#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.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#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.
|-
| [[#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.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|-
| [[#X_DelayedShutdown | X_DelayedShutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
}
</syntaxhighlight>

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.

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:

<syntaxhighlight lang="perl">
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
$hash->{NotifyFn} = "X_Notify";
$hash->{RenameFn} = "X_Rename";
$hash->{ShutdownFn} = "X_Shutdown";
$hash->{DelayedShutdownFn} = "X_ DelayedShutdown";
</syntaxhighlight>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</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.
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.

Darüber hinaus sollten die vom Modul unterstützten Attribute definiert werden:

<syntaxhighlight lang="perl">
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</syntaxhighlight>

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.

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}}.

Nutzung von parseParams()

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modul-Autoren 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.

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:
<syntaxhighlight lang="perl">$hash->{parseParams} = 1;</syntaxhighlight>
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.

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</syntaxhighlight>

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.
Sie beginnt typischerweise mit:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</syntaxhighlight>

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

<syntaxhighlight lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</syntaxhighlight>

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:

<syntaxhighlight lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</syntaxhighlight>

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.

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.

===== Verfügbarkeit von Attributen =====
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.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</syntaxhighlight>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

Nutzung von parseParams()

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:
<syntaxhighlight lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Undef ====
<syntaxhighlight lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>
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]]).

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.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Undef($$)
{
my ( $hash, $name) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</syntaxhighlight>

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.

==== X_Delete ====
<syntaxhighlight lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>

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.

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.

Dies kann z.B. folgendes sein:

* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.
* Lösen von evtl. Pairings mit dem physikalischen Gerät

Beispiel:
<syntaxhighlight lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

# Löschen von Geräte-assoziiertem Temp-File
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)

return undef;
}
</syntaxhighlight>

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.

==== X_Get ====
<syntaxhighlight lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</syntaxhighlight>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> für eine Definition 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 Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$opt</code> plus optional weiterer Parameter <code>@args</code> übergeben. Als Rückgabewert <code>$result</code> 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>.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt));

if($opt eq "status")
{
...
}
elsif($opt eq "power")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Dies gilt insbesondere für den Aufruf <code>get ''<NAME>'' '''?'''</code>, welche durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB 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.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $opt choose one of status temperature humidity";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' status</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

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. Vielfach werden aber auch die vorhandenen Readings zurückgegeben.

Nutzung von parseParams()

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:
<syntaxhighlight lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<syntaxhighlight lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
return ($error, $skip_trigger);
}
</syntaxhighlight>

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 Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$cmd</code> und optional weitere Argumente <code>@args</code> übergeben. Als Rückgabewert <code>$error</code> 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.

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 optionale 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>).

Rückmeldungen (Fehler) von set-Befehlen sämtlicher Module, die im Rahmen der Ausführung eines getriggerten [[Notify]] auftreten, werden im FHEM Logfile festgehalten.

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 zu Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter (<code>@args</code>) übergeben um Zustände zu setzen/ändern.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</syntaxhighlight>

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. Dies gilt insbesondere für den Aufruf <code>set ''<NAME>'' '''?'''</code>, welcher durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB 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.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $cmd choose one of status power";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Set-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>power</code>

Dies würde in folgenden, mögliche Set-Befehle für einen User resultieren:

* <code>set ''<NAME>'' status</code>
* <code>set ''<NAME>'' power</code>
</ul>

Nutzung von SetExtensions.pm

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.

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:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</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.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</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.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</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.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</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.
|-
| 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.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der commandref zum {{Link2CmdRef|Anker=set|Label=set-Befehl}}.

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<syntaxhighlight lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</syntaxhighlight>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

Nutzung von parseParams()

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:
<syntaxhighlight lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

Nutzung von FHEMWEB-Widgets

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.
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:
set ''<NAME>'' ?

Beispiel:
<syntaxhighlight lang="perl">
return "Unknown argument $cmd, choose one of status:up,down power:on,off on:noArg off:noArg";
</syntaxhighlight>

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>timer:30,120,300
mode:verbose,ultra,relaxed</pre>

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.

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:

{| class="wikitable"
|-
! Zusatz !! Beispiel !! Beschreibung
|-
| '''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.
|-
| '''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.
|-
| '''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.
|-
| '''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.
|-
| '''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.
|}

Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der {{Link2CmdRef|Anker=widgetOverride}} unter widgetOverride zu FHEMWEB.

'''Hinweise'''

* 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.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</syntaxhighlight>

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.
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.
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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal: $@";
}
}
}
return undef;
}
</syntaxhighlight>

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>.

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.

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.
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>.

Attributnamen mit Platzhaltern

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<syntaxhighlight lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</syntaxhighlight>
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.

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.
Dazu reicht ein Aufruf der Funktion [[DevelopmentModuleAPI#addToDevAttrList|addToDevAttrList()]]:

<syntaxhighlight lang="perl">
addToDevAttrList($name, $aName);
</syntaxhighlight>

==== X_Read ====
<syntaxhighlight lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
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.

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.
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.

<syntaxhighlight lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</syntaxhighlight>

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).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<syntaxhighlight lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</syntaxhighlight>

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:

* '''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.
* '''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.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

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.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

# This is relevant for Windows/USB only
if(defined($hash->{USBDev})) {
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
}
</syntaxhighlight>

==== X_Notify ====

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.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Ü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.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
}
</syntaxhighlight>

Begrenzung der Aufrufe auf bestimmte Geräte

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, das die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

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

<syntaxhighlight lang="perl">
in der Define-Funktion:

$hash->{NOTIFYDEV} = "global";
$hash->{NOTIFYDEV} = "global,Definition_.*";
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";
$hash->{NOTIFYDEV} = "global,TYPE=CUL_HM";
</syntaxhighlight>

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.

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></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.

Reihenfolge für den Aufruf der Notify-Funktion beeinflussen

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.

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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</syntaxhighlight>

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.

==== X_Rename ====
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name) = @_;

...
}
</syntaxhighlight>

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.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $old_pwd) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $old_pwd);
setKeyValue($old_index, undef);
}
</syntaxhighlight>

==== X_DelayedShutdown ====
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ( $hash ) = @_;

...

return $delay_needed;
}
</syntaxhighlight>
Mit der X_DelayedShutdown Funktion kann eine Definition das Stoppen von FHEM verzögern um asynchron hinter sich aufzuräumen. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.), welcher mehrfache Requests/Responses benötigt. Als Übergabeparameter wird der Geräte-Hash <code>$hash</code> bereitgestellt. Je nach Rückgabewert <code>$delay_needed</code> wird der Stopp von FHEM verzögert. Ist ein verzögerter Stopp von FHEM notwendig, darf der Rückgabewert in diesem Fall nicht <code>0</code> oder <code>undef</code> sein.

Im Unterschied zur [[#X_Shutdown|Shutdown]]-Funktion steht vor einem bevorstehenden Stopp von FHEM für einen User-konfigurierbaren Zeitraum (global-Attribut: <code>maxShutdownDelay</code> / Standard: 10 Sekunden) weiterhin die asynchrone FHEM Infrastruktur ([[DevIo]]/[[#X_Read|Read]]-Funktion und [[DevelopmentModuleAPI#InternalTimer|InternalTimer]]) zur Verfügung.

Sobald alle nötigen Maßnahmen erledigt sind, muss der Abschluss mit [[DevelopmentModuleAPI#CancelDelayedShutdown|CancelDelayedShutdown(<code>$name</code>)]] an FHEM zurückgemeldet werden.

Beispiel:
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ($hash) = @_;

# Aufräumen starten

return 1;
}
</syntaxhighlight>

==== X_Shutdown ====
<syntaxhighlight lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
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.). Nach der Ausführung der Shutdown-Fuktion wird FHEM sofort beendet. Falls vor dem Herunterfahren von FHEM asynchrone Kommunikation (via [[DevIo]]/[[#X_Read|X_Read]]) notwendig ist um eine vorhandene Verbindung sauber zu beenden, sollte man [[#X_DelayedShutdownFn|X_DelayedShutdownFn]] verwenden.

Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</syntaxhighlight>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#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.
|}

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 dienen dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
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.}}
<syntaxhighlight lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</syntaxhighlight>

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.

Ü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 Bereich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<syntaxhighlight lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</syntaxhighlight>

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]]).

Beispiel:

<syntaxhighlight lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</syntaxhighlight>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
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. }}
<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</syntaxhighlight>

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 physikalischem Modul abzustimmen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</syntaxhighlight>

==== X_Fingerprint ====
<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</syntaxhighlight>

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.

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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</syntaxhighlight>

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.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modul-Autoren 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.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

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:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#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.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorized|Authorized()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<syntaxhighlight lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

return ( $reading, $value, $unit );
}
</syntaxhighlight>

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modul-Autor 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.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<syntaxhighlight lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</syntaxhighlight>

==== X_Except ====
<syntaxhighlight lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>

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.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">
use IO::File;

...

sub X_Except ($)
{
my ( $hash ) = @_;

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</syntaxhighlight>

==== X_Copy ====
<syntaxhighlight lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</syntaxhighlight>

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.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</syntaxhighlight>

==== X_AsyncOutput ====
{{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, ...).}}
<syntaxhighlight lang="perl">
sub X_AsyncOutput ($)
{
my ( $client_hash, $text ) = @_;

...

return $error;
}
</syntaxhighlight>

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.

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.

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.

==== X_ActivateInform====
{{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, ...).}}
<syntaxhighlight lang="perl">
sub X_ActivateInform($$)
{
my ( $client_hash, $arg ) = @_;

...
}
</syntaxhighlight>

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.

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).

==== X_State ====
<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</syntaxhighlight>

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:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan="2" align="center" | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <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.
|-
| <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>).
|-
| <code>$value</code> || Den Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Den Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

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.

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.

Beispiel:

<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</syntaxhighlight>

==== X_Authorize ====
<syntaxhighlight lang="perl">
sub X_Authorize($$$$)
{
my ( $hash, $client_hash, $type, $arg ) = @_;

...

return $authorized;
}
</syntaxhighlight>

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.

Es gibt aktuell folgende <code>$type</code>/<code>$arg</code> Kombinationen, mit denen die Authorize-Funktion aufgerufen werden:

{| class="wikitable"
|-
! $type !! $arg !! Überschrift
|-
| rowspan="3" style="white-space: nowrap;" | <code>'''$type''' = "cmd"</code>

''Befehlsausführung''
| 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.
|-
| 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.

Bsp: <code>{ReadingsVal("Lampe", "state", "off"}</code>
|-
| 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.

Bsp: <code>"/opt/fhem/myScript.sh"</code>
|-
| style="white-space: nowrap;" | <code>'''$type''' = "devicename"</code>

''Sichtbarkeit von Geräten/Definitionen''
| 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.
|}

==== X_Authenticate ====
{{Link2Forum|Topic=72757|Message=644098}}

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

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.

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:

<syntaxhighlight lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optionaler Filter für Clientmodule als regulärer Ausdruck
ClientFilter => "FHEMWEB"
};
}
</syntaxhighlight>

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.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<syntaxhighlight lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</syntaxhighlight>

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.

== Pollen von Geräten ==
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.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<syntaxhighlight lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</syntaxhighlight>

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.

In der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<syntaxhighlight lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</syntaxhighlight>

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.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<syntaxhighlight lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</syntaxhighlight>
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.

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:

<syntaxhighlight lang="perl">
my $name = $hash->{NAME};
</syntaxhighlight>

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
<code>attr <NAME> verbose</code> verwenden. Beispielsweise <code>attr Lichtschalter_Wohnzimmer verbose 5</code>

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.

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.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts|Schematische Darstellung am Beispiel CUL]]
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:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* 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.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

physisches Modul

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.).

Empfangene Nutzdaten werden als Zeichenkette über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

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.

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.

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.

logisches Modul

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.

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).

=== Die Client-Liste ===

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.

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).

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:
<pre>
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
</pre>
Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* 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]])
* 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.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</syntaxhighlight>

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:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";

# ggf.
$hash->{ClientsKeepOrder} = 1
}
</syntaxhighlight>

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>''':'''<Modulname>''':'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

Wird das Internal "ClientsKeepOrder" auf 1 gesetzt, können in "Clients" keine regulären Ausdrücke mehr angegeben werden. Dies hat einen erheblichen Einfluss, auf die Verarbeitungsdauer und sollte in Betracht gezogen werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<syntaxhighlight lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</syntaxhighlight>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
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 bisher 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 direkt durch Aufruf der [[#X_Parse|Parse]]-Funktion verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

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.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<syntaxhighlight lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</syntaxhighlight>

Das Sortierpräfix (<code>1:FS20</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.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</syntaxhighlight>

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:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</syntaxhighlight>

=== Der Match-Ausdruck ===

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.

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.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</syntaxhighlight>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.
* [[#X_DelayedShutdown | DelayedShutdown]]-Funktion - Verzögertes beenden zum Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

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.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

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.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

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.

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.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

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.

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.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

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.

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.

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.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

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):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter...>''

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.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

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.

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.

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:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</syntaxhighlight>

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.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| 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.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| 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.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| 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.

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.

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.

|-
| 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.

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.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.
|-
| 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.
|}

== Ergänzende Hinweise ==
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.

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.

== Weitere Informationen ==
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.

== "Hello World" Beispiel ==

98_Hello.pm

<syntaxhighlight lang="perl">
package main;
use strict;
use warnings;

my %Hello_gets = (
"whatyouwant" => "can't",
"whatyouneed" => "try sometimes",
"satisfaction" => "no"
);

sub Hello_Initialize($) {
my ($hash) = @_;

$hash->{DefFn} = 'Hello_Define';
$hash->{UndefFn} = 'Hello_Undef';
$hash->{SetFn} = 'Hello_Set';
$hash->{GetFn} = 'Hello_Get';
$hash->{AttrFn} = 'Hello_Attr';
$hash->{ReadFn} = 'Hello_Read';

$hash->{AttrList} =
"formal:yes,no "
. $readingFnAttributes;
}

sub Hello_Define($$) {
my ($hash, $def) = @_;
my @param = split('[ \t]+', $def);

if(int(@param) < 3) {
return "too few parameters: define <name> Hello <greet>";
}

my $hash->{name} = $param[0];
my $hash->{greet} = $param[2];

return undef;
}

sub Hello_Undef($$) {
my ($hash, $arg) = @_;
# nothing to do
return undef;
}

sub Hello_Get($@) {
my ($hash, @param) = @_;

return '"get Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
if(!$Hello_gets{$opt}) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}

if($attr{$name}{formal} eq 'yes') {
return $Hello_gets{$opt}.', sir';
}
return $Hello_gets{$opt};
}

sub Hello_Set($@) {
my ($hash, @param) = @_;

return '"set Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
my $value = join("", @param);

if(!defined($Hello_gets{$opt})) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
$hash->{STATE} = $Hello_gets{$opt} = $value;

return "$opt set to $value. Try to get it.";
}

sub Hello_Attr(@) {
my ($cmd,$name,$attr_name,$attr_value) = @_;
if($cmd eq "set") {
if($attr_name eq "formal") {
if($attr_value !~ /^yes|no$/) {
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";
Log 3, "Hello: ".$err;
return $err;
}
} else {
return "Unknown attr $attr_name";
}
}
return undef;
}

1;

=pod
=begin html

<a id="Hello"></a>
<h3>Hello</h3>
<ul>
Hello implements the classical "Hello World" as a starting point for module development.
You may want to copy 98_Hello.pm to start implementing a module of your very own. See
<a href="http://wiki.fhem.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an
in-depth instruction to your first module.
 
<a id="Hello-define"></a>
Define
<ul>
<code>define <name> Hello <greet></code>
 
Example: <code>define HELLO Hello TurnUrRadioOn</code>
 
The "greet" parameter has no further meaning, it just demonstrates
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a>
for more info about the define command.
</ul>
 

<a id="Hello-set"></a>
Set 
<ul>
<code>set <name> <option> <value></code>
 
You can set any value to any of the following options. They're just there to
get them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a>
for more info about the set command.
 
Options:
<ul>
<li>satisfaction 
Defaults to "no"</li>
<li>whatyouwant 
Defaults to "can't"</li>
<li>whatyouneed 
Defaults to "try sometimes"</li>
</ul>
</ul>
 

<a id="Hello-get"></a>
Get 
<ul>
<code>get <name> <option></code>
 
You can get the value of any of the options described in
<a href="#Helloset">paragraph "Set" above</a>. See
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about
the get command.
</ul>
 

<a id="Hello-attr"></a>
Attributes
<ul>
<code>attr <name> <attribute> <value></code>
 
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about
the attr command.
 
Attributes:
<ul>
<li>formal no|yes 
When you set formal to "yes", all output of get will be in a
more formal language. Default is "no".
</li>
</ul>
</ul>
</ul>

=end html

=cut
</syntaxhighlight>

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]]

[[Kategorie:Development]]

DevelopmentModuleAPI

2022-01-12T21:25:43Z

Sidey:

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Diese Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<syntaxhighlight lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===
:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabewert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im strikt mathematischen Sinne, sondern bietet zusätzlich eine Formatierung.

==== Beispiele ====
<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.45

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = "Kein Wert"

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.5

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.45000

# Device foo, Reading bar, Wert "123 °C"
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.00000
</syntaxhighlight>

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

==== Fallstricke ====
Der Rückgabewert muss nicht unbedingt ein numerischer Wert sein, wenn als <code>$default</code> kein numerischer Wert oder <code>undef</code> übergeben wurde. Vergleiche mit numerischen Operatoren werden dann ggf. ein Warning erzeugen.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

# Lese aus dem Reading baz, nicht bar, wird fehlschlagen
if ( ReadingsNum(q(foo), q(baz), q(Kein Wert), 0) == 123.5 ) {
say q(Wert ist 123.5);
}

# Argument "Kein Wert" isn't numeric in numeric eq (==)
</syntaxhighlight><code>$round</code> wird direkt, d.h. ohne Validierung, in den [https://perldoc.perl.org/functions/sprintf format string] in <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code> übernommen und ausgewertet.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert), q{%%p});
# Evaluiert %p zu einer Speicheradresse, z.B. 7fa1fb03d738f

ReadingsNum(q(foo), q(bar), q(Kein Wert), q(foo));
# = 123oof
</syntaxhighlight>

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== computeClientArray ===
<nowiki>#</nowiki> compute the list of defined logical modules for a physical module<syntaxhighlight lang="perl">
$clientArray = computeClientArray($definitionHash, $moduleName);

</syntaxhighlight>Wenn im übergebenen $definitionHash der Wert {ClientsKeepOrder}=1 gesetzt ist, dann wird der ClientArray in der Reihenfolge und mit den Namen aufgebaut, wie diese im phyischen Modul hinterlegt sind.

Der Wert {ClientsKeepOrder}=0 bewirkt, dass eine Sortierung gemäß der Modulreihenfolge vorgenommen wird und dass Module auch über die Angabe einer Regex ausgewählt werden können.
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$definitionHash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, welche an diese Funktion übergeben wird
|-
| style="vertical-align:top" | '''<code>$moduleName</code>'''

''mandatory''
|| Die Angabe eines Modulnamnes, aus welchem der Wert {Clients} verwendet wird, sollte dieser Wert in der Gerätedefinition nicht hinterlegt sein
|}
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$clientArray</code>''' || Liefert auf Basis des übergebenen hashes einer Moduldefinition und des übergebenen Modulnamens einen $clientarray zurück
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2022-01-12T21:22:28Z

Sidey: computeClientArray und Einflussnahme in Dokumentation aufgenommen

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Diese Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<syntaxhighlight lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===
:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabewert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im strikt mathematischen Sinne, sondern bietet zusätzlich eine Formatierung.

==== Beispiele ====
<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.45

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = "Kein Wert"

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.5

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.45000

# Device foo, Reading bar, Wert "123 °C"
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.00000
</syntaxhighlight>

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

==== Fallstricke ====
Der Rückgabewert muss nicht unbedingt ein numerischer Wert sein, wenn als <code>$default</code> kein numerischer Wert oder <code>undef</code> übergeben wurde. Vergleiche mit numerischen Operatoren werden dann ggf. ein Warning erzeugen.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

# Lese aus dem Reading baz, nicht bar, wird fehlschlagen
if ( ReadingsNum(q(foo), q(baz), q(Kein Wert), 0) == 123.5 ) {
say q(Wert ist 123.5);
}

# Argument "Kein Wert" isn't numeric in numeric eq (==)
</syntaxhighlight><code>$round</code> wird direkt, d.h. ohne Validierung, in den [https://perldoc.perl.org/functions/sprintf format string] in <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code> übernommen und ausgewertet.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert), q{%%p});
# Evaluiert %p zu einer Speicheradresse, z.B. 7fa1fb03d738f

ReadingsNum(q(foo), q(bar), q(Kein Wert), q(foo));
# = 123oof
</syntaxhighlight>

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== computeClientArray ===
<nowiki>#</nowiki> compute the list of defined logical modules for a physical module<syntaxhighlight lang="perl">
$clientArray = computeClientArray($definitionHash, $moduleName);

</syntaxhighlight>Wenn im übergebenen $definitionHash der Wert {ClientsKeepOrder}=1 gesetzt ist, dann wird der ClientArray in der Reihenfolge und mit den Namen aufgebaut, wie diese im phyischen Modul hinterlegt sind.

Der Wert {ClientsKeepOrder}=0 bewirkt, dass eine Sortierung gemäß der Modulreihenfolge vorgenommen wird und dass Module auch über die Angabe einer Regex ausgewählt werden können.
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$clientArray</code>''' || Liefert auf Basis des übergebenen hashes einer Moduldefinition und des übergebenen Modulnamens einen $clientarray zurück
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

SIGNALduino

2021-04-23T21:37:14Z

Sidey: /* FHEM-Modul laden */ update branch dev-r34 entfernt

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.5.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/master<nowiki/>/controls_signalduino.txt</code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax. Ebenso wird auch vorgegangen wenn der SIGNALduino beispielsweise über ser2net freigeben wird.
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

Wenn ein miniCUL geflasht werden soll, sind einige Besonderheiten zu beachten. Details dazu in {{Link2Forum|Topic=114413|LinkText=diesem Forenthema}}.

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Die Version 3.4 ist die aktuell stabile Version.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:

<pre>
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):
</pre>

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverständlich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te|Unterstützte Geräte]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl im Modul direkt ausgeführt werden können. Sofern möglich, sollten die Abfrage von Werten aus dem Modul allerdings mit den dafür vorgesehenen Kommandos erfolgen, da die Rückmeldungen des <code>set raw</code> Befehls nur im Logfile ab Verbose 4 erscheinen. Die Befehle sind nützlich, wenn direkt auf den Microcontroller zugegriffen wird:

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: <code>set raw C35</code> führt ab Verbose 4 zu einer Logausgabe folgender Art <code>Read, msg: C35 = 0D</code>
:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot
:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2 des CC1101)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2021-01-15T21:59:30Z

Sidey: /* FHEM-Modul laden */ Auf aktuellen git branch verwiesen

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.5.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/master<nowiki/>/controls_signalduino.txt</code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax. Ebenso wird auch vorgegangen wenn der SIGNALduino beispielsweise über ser2net freigeben wird.
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

Wenn ein miniCUL geflasht werden soll, sind einige Besonderheiten zu beachten. Details dazu in {{Link2Forum|Topic=114413|LinkText=diesem Forenthema}}.

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Die Version 3.4 ist die aktuell stabile Version.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:<syntaxhighlight lang="md">
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):

</syntaxhighlight>3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverständlich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te|Unterstützte Geräte]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl im Modul direkt ausgeführt werden können. Sofern möglich, sollten die Abfrage von Werten aus dem Modul allerdings mit den dafür vorgesehenen Kommandos erfolgen, da die Rückmeldungen des <code>set raw</code> Befehls nur im Logfile ab Verbose 4 erscheinen. Die Befehle sind nützlich, wenn direkt auf den Microcontroller zugegriffen wird:

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: <code>set raw C35</code> führt ab Verbose 4 zu einer Logausgabe folgender Art <code>Read, msg: C35 = 0D</code>
:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot
:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2 des CC1101)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T21:33:46Z

Sidey: /* Fehlerbehandlung */

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (April 2020) ist noch die Version 3.3.1 fertig. Die Version 3.4 ist seit Februar 2020 in einer Vorabversion verfügbar.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:<syntaxhighlight lang="md">
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):

</syntaxhighlight>3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl im Modul direkt ausgeführt werden können. Sofern möglich, sollten die Abfrage von Werten aus dem Modul allerdings mit den dafür vorgesehenen Kommandos erfolgen, da die Rückmeldungen des <code>set raw</code> Befehls nur im Logfile ab Verbose 4 erscheinen. Die Befehle sind nützlich, wenn direkt auf den Microcontroller zugegriffen wird:

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: <code>set raw C35</code> führt ab Verbose 4 zu einer Logausgabe folgender Art <code>Read, msg: C35 = 0D</code>
:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot
:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2 des CC1101)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T21:05:57Z

Sidey: /* Fehlerbehandlung */ C35 Befehl korrigiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (April 2020) ist noch die Version 3.3.1 fertig. Die Version 3.4 ist seit Februar 2020 in einer Vorabversion verfügbar.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:<syntaxhighlight lang="md">
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):

</syntaxhighlight>3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: <code>set raw C35</code> führt zu einer Logausgabe folgender Art <code>Read, msg: C35 = 0D</code>

:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2 des CC1101)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T20:01:19Z

Sidey: /* Fehlerbehandlung */

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (April 2020) ist noch die Version 3.3.1 fertig. Die Version 3.4 ist seit Februar 2020 in einer Vorabversion verfügbar.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:<syntaxhighlight lang="md">
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):

</syntaxhighlight>3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: <code>set raw 35</code> könnte zu folgender Ausgabe führen C35 = 0D

:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T19:43:43Z

Sidey: /* Mein Gerät wird in FHEM nicht erkannt */ Link auf Github issue konkretisiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (April 2020) ist noch die Version 3.3.1 fertig. Die Version 3.4 ist seit Februar 2020 in einer Vorabversion verfügbar.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:<syntaxhighlight lang="md">
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):

</syntaxhighlight>3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: C35 -> C35 = 0D

:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T19:40:18Z

Sidey: /* Flashen des Arduino mit der SIGNALduino Firmware */ Versionsreferenzen aktualisiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (April 2020) ist noch die Version 3.3.1 fertig. Die Version 3.4 ist seit Februar 2020 in einer Vorabversion verfügbar.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>''
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: C35 -> C35 = 0D

:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T19:15:23Z

Sidey: /* Fehlerbehandlung */ Korrektur Befehl zum Abfragen der Sendeleistung

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing. Derzeit ist nur testing verfügbar:
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266 und 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/nightly/SIGNALDuino_ESP8266cc1101nightly.hex
</code>

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>''
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: C35 -> C35 = 0D

:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T12:17:25Z

Sidey: Kleine Korrekturen / Schreibweise / Bezeichnungen

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing. Derzeit ist nur testing verfügbar:
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266 und 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/nightly/SIGNALDuino_ESP8266cc1101nightly.hex
</code>

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>''
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: C35 -> C35 = 0D

:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T12:14:48Z

Sidey: /* Entwicklungsversion */ Bezeichnung der Version korrigiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.0 seit 20.07.2019 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing. Derzeit ist nur testing verfügbar:
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266 und 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/nightly/SIGNALDuino_ESP8266cc1101nightly.hex
</code>

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Haupt-Seite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>''
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: C35 -> C35 = 0D

:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T12:13:17Z

Sidey: /* Entwicklungsversion */ Korrektur Versionsverweis, Fork wegen Verwirrung entfernt

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die Version von Sidey wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.0 seit 20.07.2019 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing. Derzeit ist nur testing verfügbar:
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266 und 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/nightly/SIGNALDuino_ESP8266cc1101nightly.hex
</code>

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Haupt-Seite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>''
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: C35 -> C35 = 0D

:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T12:12:13Z

Sidey: /* Fehlerbehandlung */ Formatierung angepasst

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die Version von Sidey wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben.

Es existiert eine weitere Entwicklungsversion, siehe dazu die {{Link2Forum|Topic=82379|Message=744554|LinkText= Firmware}} (hierzu gibt es auch eine private Version des [https://github.com/Ralf9/RFFHEM/issues/2 Moduls]).

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.0 seit 20.07.2019 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing. Derzeit ist nur testing verfügbar:
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266 und 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/nightly/SIGNALDuino_ESP8266cc1101nightly.hex
</code>

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Haupt-Seite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>''
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: C35 -> C35 = 0D

:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2020-04-10T12:09:36Z

Sidey: /* Fehlerbehandlung */ Befehle aktualisiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die Version von Sidey wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben.

Es existiert eine weitere Entwicklungsversion, siehe dazu die {{Link2Forum|Topic=82379|Message=744554|LinkText= Firmware}} (hierzu gibt es auch eine private Version des [https://github.com/Ralf9/RFFHEM/issues/2 Moduls]).

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.0 seit 20.07.2019 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing. Derzeit ist nur testing verfügbar:
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266 und 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/nightly/SIGNALDuino_ESP8266cc1101nightly.hex
</code>

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Haupt-Seite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>''
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl direkt ausgeführt werden können. Sofern möglich, sollten die Set Befehle aus dem Modul verwendet werden.

<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D

<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot

<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2019-07-19T18:08:19Z

Sidey: /* FHEM-Modul laden */ SVN Version aktualisiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die Version von Sidey wird [https://forum.fhem.de/index.php/topic,58396.0.html hier ]genauer beschrieben.

Es existiert eine weitere Entwicklungsversion, siehe dazu die [https://forum.fhem.de/index.php/topic,82379.msg744554.html#msg744554 Firmware] (hierzu gibt es auch eine private Version des [https://github.com/Ralf9/RFFHEM/issues/2 Moduls]).

== Hardware ==
=== Controller ===

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.0 seit 20.07.2019 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing. Derzeit ist nur testing verfügbar:
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266 und 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/nightly/SIGNALDuino_ESP8266cc1101nightly.hex
</code>

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Haupt-Seite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!
}}

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2019-02-26T20:10:47Z

Sidey: URL zur development Version aktualisiert, Anpassungen durch das Update des Modules am 20.02.2019

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.3.4 seit 24.02.2019 verteilt.

Die in der Entwicklung befindliche Version (3.4.0) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266 und 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/nightly/SIGNALDuino_ESP8266cc1101nightly.hex
</code>

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Haupt-Seite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!
}}

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2019-02-11T11:12:28Z

Sidey: /* Vorabversion einer Firmware */ URL für SignalESP firmware aktualisiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer FHEM-Modul Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanorelease.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_prominirelease.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_miniculcc1101release.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_radinocc1101release.hex
</code>

SIGNALESP_.hex (mit cc1101) für einen ESP8266 und 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/nightly/SIGNALDuino_ESP8266cc1101nightly.hex
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Haupt-Seite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!
}}

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2018-11-24T18:36:37Z

Sidey: Fehlersuche nach dem Flashen ergänzt

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer FHEM-Modul Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nano.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_promini.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_miniculcc1101.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_radinocc1101.hex
</code>

SIGNALESP_331rc4.bin (mit cc1101) für einen ESP8266 mit 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALESP/releases/download/3.3.1RC4/SIGNALESP_331RC4_1M.bin
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!
}}

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2018-11-24T18:22:31Z

Sidey:

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer FHEM-Modul Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nano.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_promini.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_miniculcc1101.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_radinocc1101.hex
</code>

SIGNALESP_331rc4.bin (mit cc1101) für einen ESP8266 mit 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALESP/releases/download/3.3.1RC4/SIGNALESP_331RC4_1M.bin
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!
}}

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2018-11-16T22:13:22Z

Sidey: /* FHEM-Modul laden */ Aktualisierung von Modul und Firmware angepasst.

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer FHEM-Modul Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC9/SIGNALDuino_nanocc1101.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC9/SIGNALDuino_nano.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC9/SIGNALDuino_promini.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC9/SIGNALDuino_miniculcc1101.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC9/SIGNALDuino_radinocc1101.hex
</code>

SIGNALESP_331rc4.bin (mit cc1101) für einen ESP8266 mit 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALESP/releases/download/3.3.1RC4/SIGNALESP_331RC4_1M.bin
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!
}}

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

HomeMatic HMInfo TempList/Weekplan

2018-09-29T21:21:05Z

Sidey: Files in externe Dateien übersetzt

{{Infobox Modul
|ModPurpose=Behandlung von Wochenprogrammen für Thermostate
|ModType=d
|ModCmdRef=HMinfo Weekplan
|ModForumArea=HomeMatic
|ModTechName=98_HMinfo.pm
|ModOwner=martinp876 ({{Link2FU|251|martinp876}} / [[Benutzer Diskussion:Martinp876|Wiki]])
}}

'''HMInfo TempList''' ist eine Funktion des Moduls [[Homematic_HMInfo|HMInfo]], die es erlaubt Temperaturlisten (Wochenprogramme) von [[HomeMatic Type Thermostat|Thermostaten]] zu verwalten.

== Einleitung==
Homematic bietet eine Reihe von Heizkörperthermostaten, welche mit einem Wochenprogramm ausgestattet sind. Die Erstellung und Verwaltung dieser Wochenprogramme ist im Device zumindest umständlich, siehe dazu [[HomeMatic_Type_Thermostat#Templates]]
== Begriffe==
Wir müssen strikt 3 Wochenpläne unterscheiden:
* ''activeList'' Wochenplan im Device. Dieser, und nur dieser ist '''wirksam'''. Er kann nicht direkt in FHEM dargestellt werden. FHEM muss die Daten auslesen um sie verarbeiten zu können. Siehe hierzu kommandos und attribute des Device:getConfig und autoReadReg.
* ''referenceList'' Wochenplan in FHEM. Für jedes Device wird ein Wochenplan (bei einigen Devices können es sogar mehrere sein) dargestellt. Dies ist die aus dem Device gelesene activeList. Es liegt in der Verantwortung des User, die Liste aktuell zu halten.
* ''tempTemplates'' Vorlagen für Wochenpläne. Diese werden in externen Dateien erstellt. Man kann Devices eines der tempTemplates zuweisen um es zu prüfen oder einzuspielen.

== Wochenprogramme ==
=== Datei ===
Zur Verwendung einer Temperaturliste als Wochenprogramm muss eine Datei erzeugt werden, mit folgendem Inhalt:
* Für jede Temperaturliste eine Namensliste in der Form <code>entities:<name1>,<name2>,...</code>
** ein Name darf in einer Datei '''nicht''' doppelt vorkommen.
** der gleiche Name darf in unterschiedlichen Dateien verwendet werden.
* In jeder Temperaturliste eine Zeile pro Tag, beginnend mit <code>tempList<Wochtentag>> ....</code>
** Es muss eine Zeile je Wochentag vorhanden sein
* In jeder Zeile nach dem Wochentagscode eine Liste von Zeit/Wert-Paaren, diese stellen das jeweilige Tagesprogramm dar, z.B. '''08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0''',
** Jedes Tagesprogramm beginnt um 00:00 Uhr.
** Das erste Paar 08:00 14.0 bedeutet also, dass von 00:00 bis 08:00 eine Temperatur von 14.0 eingestellt werden soll.
** Das zweite Paar 15:00 18.0 bedeutet also, dass von 08:00 bis 15:00 18.0 Grad einzustellen sind
** Es sind immer Paare einzutragen
** der Beginn um 00:00 ist nicht einzutragen
** der letzte Eintrag '''muss''' an jeden Tag 24:00 sein
** Uhrzeiten sind auf halbe Stunden beschränkt. Einträge 08:00 und 08:30 sind gültig. 08:20 ist ungültig.
Beispiel:
entities:tempTmpl1
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_1_tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 17.0
R_2_tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_3_tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0
R_4_tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_5_tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_6_tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0
entities:tempTWohnzimmer
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 17.0
R_1_tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_2_tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_3_tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0
R_4_tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_5_tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_6_tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0

==== Erstellen der ersten Template-Datei====
Um nicht auf der grünen Wiese beginnen zu müssen, empfiehlt es sich den aktuellen Ist-Zustand (die ''referenceList'') mit dem unten beschriebenen HMInfo-Befehl <code>save</code> in eine Datei zu schreiben. Vorab sollten die HMInfo-Attribute <code>configDir</code> und <code>configTempFile</code> gesetzt sein.
attr <HMInfo> configDir setup
attr <HMInfo> configTempFile myWeekplan.cfg
set <HMInfo> tempList save
Der letzte Befehl speichert die ''referenceList'' jedes Gerätz in der Datei <code>setup/myWeekplan.cfg</code>. Als ''Entity'' wird der Name des Thermostaten verwendet – das Attribut ''tempListTmpl'' wird nicht beachtet. Die Datei kann anschließend mit einem Text-Editor bearbeitet werden. Wochenpläne können zusammengefasst und verändert werden.

=== Templates zuweisen===
tempListTemplates werden immer in Files verwaltet. Man kann Templates in mehreren Files verwalten. Ferner gibt es unterschiedliche Methoden, ein File zu spezifizieren.
* '''attr tempListTmpl im Device''': hier spezifiziert man das Template. Will man sich von templates entkoppeln sollte man '''tempListTmpl none''' unbedingt setzen.
** '''Wohnzimmer''': das template '''Wohnzimmer''' wird im default File gesucht
** '''myWeekplan.cfg:Wohnzimmer''': das template '''Wohnzimmer''' wird im File ''myWeekplan.cfg'' mit relativen Pfad von FHEM home gesucht
** '''./setup/myWeekplan.cfg:Wohnzimmer''': das template '''Wohnzimmer''' wird im File ''myWeekplan.cfg'' mit relativen Pfad ''./setup'' gesucht
** '''/opt/fhem/myWeekplan.cfg:Wohnzimmer''': das template '''Wohnzimmer''' wird im File ''myWeekplan.cfg'' mit absoluten Pfad ''/opt/fhem/'' gesucht
* '''attr configTempFile in HMInfo''': spezifiziert weekplan configurationsfiles. Es ist eine Liste Wochenplan Files welche genutzt werden. Ist das Attribut nicht gesetzt wird als ''default tempList.cfg'' genutzt.
** '''attr hm configTempFile myWeekPlan.cfg''': FHEM kennt ein File mit Wochenplan. Dies ist auch das Default für alle tempListTmpl in denen kein File spezifiziert.
** '''attr hm configTempFile mySummerPlan.cfg,myWinterPlan.cfg,myPartyPlan.cfg''': FHEM sind 3 Files bekannt. Der erste Eintrag ''mySummerPlan.cfg'' ist der Default für tempListTmpl .
* '''attr configDir in HMInfo''': spezifiziert einen Pfad, der ''auch'' für configTemplFile genutzt wird. Es erleichtert Konfigurations-Dateien in einem separaten Verzeichnis anzulegen. ''attr hm configDir setup'' wäre ein sinnvoller Eintrag. Das Verzeichnis ''setup'' unter fhem sollte erstellt werden. Ist das Attribut nicht gesetzt ist fhemHome der default.

=== HMInfo Kommandos ===
Die HMInfo-Befehle, die Temperaturlisten verwalten, folgen dem Schema:
set <HMInfo> tempList <Befehl> [<Dateiname>]
Die verfügbaren Befehle sind:
; <code>save</code>
: Speichert den aktuellen Zustand der Thermostate (''referenceList'') in der ''tempList''-Datei ab. Zu beachten ist, dass die aktuell in FHEM vorhandenen Werte benutzt werden. Der Benutzer muss selbst sicher stellen, dass diese mit den Werten im Gerät übereinstimmen. Alle eventuell vorher in der Datei vorhandenen Werte werden überschrieben.
; <code>verify</code>
: Vergleicht den Ist-Zustand (''referenceList'') mit dem Soll-Zustand (dem Wochenplan aus dem ''tempListTmpl''-Attribut). Abweichungen werden angezeigt, aber nicht behoben. Diese Prüfung ist auch Teil von HMInfos <code>configCheck</code>.
; <code>restore</code>
: Stellt den Soll-Zustand wieder her. Funktioniert im Prinzip wie <code>verify</code>, jedoch werden alle Abweichungen vom Soll-Zustand korrigiert. Zu beachten ist die Verzögerung beim Schreiben (siehe [[HomeMatic HMInfo#protoEvents|HMInfo protoEvents]], Device Status und Beschreibung des Device) und dass nach dem Schreiben die ''referenceList'' neu geladen werden muss. Es wird empfohlen, <code>autoReadReg</code> auf Level 5 zu setzen. Ein Restore kann jederzeit ausgeführt werden. Sind alle Daten aktuell, wird ''keine'' Temperaturliste geschrieben; es erfolgt keinerlei Funkverkehr.
; <code>status</code>
: Gibt eine Übersicht über die genutzten Templates aus.

Das Web-Frontend verwendet den nahezu identischen Befehl <code>tempListG</code>. Da dieser Befehl keine weiteren Argumente zulässt kann das Frontend ein Pulldown-Menü anzeigen. Das "G" steht für "Global" – da keine Filter unterstützt werden, wirken alle Befehle auf alle HomeMatic-Geräte.

==Nutzungsbeispiele==
=== Mehrere Heizkörper in einem Raum===
Wenn sich in einem Raum mehrere Heizkörperthermostate befinden, sollten diese – wie in [[HM-CC-RT-DN]] beschrieben – gepeert werden.
HomeMatic geht davon aus, dass alle HM-CC-RT-DNs den selben Wochenplan haben (gilt ggf. auch für einen zugehörigen [[HM-TC-IT-WM-W-EU]]).

Um dies zu erreichen definiert man einen Wochenplan für das Zimmer, beispielsweise <code>Wohnzimmer.cfg</code>. Anschließend wird dieser Wochenplan allen Teammitgliedern zugewiesen:

attr <HM-CC-RT-DN#1>_Clima tempListTmpl Wohnzimmer
attr <HM-CC-RT-DN#2>_Clima tempListTmpl Wohnzimmer
attr <HM-CC-RT-DN#3>_Clima tempListTmpl Wohnzimmer
attr <HM-TC-IT-WM-W-EU>_Climate tempListTmpl Wohnzimmer
set hm tempListG restore

=== Mehrere Heizkörper mit gleichen Profil===
Will man Wohnräume identisch behandeln im Hinblick auf den Wochenplan weisst man den Thermostaten identische Profile zu.

attr RTSusi_Clima tempListTmpl Kinderzimmer
attr RTjonas_Clima tempListTmpl Kinderzimmer
attr RTwohnzimmer_Clima tempListTmpl Kinderzimmer
set hm tempListG restore
=== Wohnungsnutzung umschalten===
Das Heizprofil kann man Zentral umstellen. Verlässt man die Wohnung zum Urlaub, der Sommer naht, man macht die üblich 3-Woche Party... . Alle Thermostate sollen umgestellt werden, zentral mit wenigen Kommandos, einfach zu prüfen. Sinnvoll ist es mehrere tempList.cfg Files anzulegen. Nehmen wir 4 Files an, Winter, Urlaub zu hause UrlaubIn, Urlaub nicht zu hause UrlaubOut sowie Sommer. Ferner hat man (der Einfachheit halber) 3 RTs: RTwohn, RTschlaf, RTkueche.
Die RTs haben jeweils ihr attr tempListTmpl gesetzt entsprechend ihrem Namen.
Man legt also die 4 Files an mit entities die man zusammenfassen kann (templisten muss man natürlich befüllen:
File Winter.cfg
entity: RTwohn
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...
entity: RTschlaf
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...
entity: RTkueche
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...

File UrlaubIn.cfg
entity: RTwohn,RTkueche
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...
entity: RTschlaf
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...

File UrlaubOut.cfg
entity: RTwohn,RTschlaf,RTkueche
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...

File Sommer.cfg
entity: RTwohn,RTschlaf,RTkueche
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...

In HMInfo sollte man nun verwalten:
attr RTwohn_Clima tempListTmpl RTwohn
attr RTkueche_Clima tempListTmpl RTkueche
attr RTschlaf_Clima tempListTmpl RTschlaf
attr hm configTempFile Winter.cfg,Sommer.cfg,UrlaubIn.cfg,UrlaubOut.cfg

Winter.cfg ist nun default. Mit set hm tempListG verify kann man prüfen, dass es entsprechend genutzt ist. Nun will man in Urlaub fahren. Man schaltet das Default durch umstellen der Reihenfolge um und aktiviert es durch ein restore:
attr hm configTempFile UrlaubOut.cfg,Winter.cfg,Sommer.cfg,UrlaubIn.cfg
set hm tempListG restore

UrlaubOut.cfg ist default. Alle notwendigen Änderungen werden in die RTs programmiert.
Unberührt bleibt Opas Zimmer, der nicht das default file sondern ein dediziertes nutzt.

attr RTopa_Clima tempListTmpl Winter.cfg:RTopa

Das template RTopa muss also nur im File Winter.cfg vorhanden sein:

[[Kategorie:HomeMatic supportDevice]]
[[Kategorie:HOWTOS]]

SIGNALduino

2018-06-16T22:42:26Z

Sidey: Syntax Korrektur

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Juni 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer FHEM-Modul Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_nanocc1101.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_nano.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_promini.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_miniculcc1101.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_radinocc1101.hex
</code>

SIGNALESP_331rc4.bin (mit cc1101) für einen ESP8266 mit 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALESP/releases/download/3.3.1RC4/SIGNALESP_331RC4_1M.bin
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices. VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2018-06-16T22:38:58Z

Sidey: Firmware Versionen aktualisiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Juni 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer FHEM-Modul Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_nanocc1101.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_nano.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_promini.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_miniculcc1101.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_radinocc1101.hex
</code>

SIGNALESP_331rc4.bin (mit cc1101) für einen ESP8266 mit 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALESP/releases/download/3.3.1RC4/SIGNALESP_331RC4_1M.bin
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher|ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices. VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

DevelopmentGuidelinesReadings

2018-06-04T20:51:55Z

Sidey: Englische Übersetzung verbessert, konjunktive Form entfernt.

=Deutsch=
== Einleitung ==
Auf dieser Seite werden Richtlinien für Readings gesammelt, welche in mehreren Modulen auftauchen können um eine Vereinheitlichung zu erreichen. Dadurch soll es Hilfsmodulen und Anwendern leichter fallen, mit den Werten der Readings zu arbeiten.

== Batterie-Readings ==
Basierend auf dieser {{Link2Forum|Topic=87575|LinkText=Diskussion}} haben sich die Entwickler für Readings, welche in Zusammenhang mit Batterien stehen auf folgendes geeinigt:
Es gibt '''nur''' diese drei Readings für den Batteriestatus:
* batteryState
* batteryPercent
* batteryVoltage

Wertebereich:
*batteryState: ok|low
*batteryPercent: \d{1,2}|100
*batteryVoltage: \d+.\d+

Wichtig:
das jeweilige Modul setzt '''nur''' die Readings, die es aus den aktuellen Daten vom Gerät bestimmen kann. Konkret: niemand kann sich darauf verlassen, welche der drei battery Readings vorhanden sind (es gibt nicht überall ein batteryState). Wenn das Gerät früher ein Percent gemeldet hat, aber in der letzten Nachricht nur state, dann wird das Percent Reading nicht angefasst.

=English=
== Start ==
On this page you will find guidlines how to name common readings. These guidlines are for readings which are used in more than one module and should have the same possible values. This makes it helper modules and users easier, to work with the values from common readings.

== Battery Reading ==
Based on this {{Link2Forum|Topic=87575|LinkText=discussion}} battery-readings should '''only''' be named like:
* batteryState
* batteryPercent
* batteryVoltage

The values should only be:
*batteryState: ok|low
*batteryPercent: \d{1,2}|100
*batteryVoltage: \d+.\d+

Important: The respective module '''only''' uses the values getting from the device. This means nobody can be sure which of the readings is used in the modul (there is not everywhere a batteryState reading). If the device did send batteryPercent befor and now only sends 'battery: low', the batteryPercent readings stays as it was before.

[[Kategorie:Development]]

SIGNALduino

2018-03-11T22:25:44Z

Sidey: /* Vorabversion einer Firmware */

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Anfang 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer FHEM-Modul Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_nanocc1101.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_nano.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_promini.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_miniculcc1101.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_radinocc1101.hex
</code>

SIGNALESP_331rc2.bin (mit cc1101) für einen ESP8266
<code>set ipduino flash https://drive.google.com/uc?export=download&id=1V8ZfLnRnskc64XZkfL-qwmI7AsSd6KRG
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. "ESP8266Flasher.exe" oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]

SIGNALduino

2018-03-11T22:25:23Z

Sidey: /* Vorabversion einer Firmware */

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Anfang 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_nanocc1101.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_nano.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_promini.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_miniculcc1101.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_radinocc1101.hex
</code>

SIGNALESP_331rc2.bin (mit cc1101) für einen ESP8266
<code>set ipduino flash https://drive.google.com/uc?export=download&id=1V8ZfLnRnskc64XZkfL-qwmI7AsSd6KRG
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. "ESP8266Flasher.exe" oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]

SIGNALduino

2018-03-10T23:35:33Z

Sidey: Downloadlinks für Firmware aktualisiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Anfang 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden.

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_nanocc1101.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_nano.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_promini.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_miniculcc1101.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC4/SIGNALDuino_radinocc1101.hex
</code>

SIGNALESP_331rc2.bin (mit cc1101) für einen ESP8266
<code>set ipduino flash https://drive.google.com/uc?export=download&id=1V8ZfLnRnskc64XZkfL-qwmI7AsSd6KRG
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. "ESP8266Flasher.exe" oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]

SIGNALduino

2018-02-22T22:12:18Z

Sidey: vorabversion aktualisiert

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Anfang 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden.

SIGNALDuino_nanoCC1101-331rc2.hex für einen Nano mit CC1101

<code>set sduino flash https://drive.google.com/uc?export=download&id=1sIac8-Qhts4c7OEkFH72Lv6hhgbOadFQ
</code>

SIGNALDuino_nano_331rc3.hex für einen Nano ohne cc1101

<code>set sduino flash https://drive.google.com/uc?export=download&id=1FnnIjJhBI1mjxZKzMnNtnnYzHChyn0lk
</code>

SIGNALDuino_promini_331rc2.hex für einen promini ohne cc1101

<code>set sduino flash https://drive.google.com/uc?export=download&id=1-AJKmO2DjQPi9_O3XI6KqvE9oYLHOyl8
</code>

SIGNALESP_331rc2.bin (mit cc1101) für einen ESP8266
<code>set ipduino flash https://drive.google.com/uc?export=download&id=1V8ZfLnRnskc64XZkfL-qwmI7AsSd6KRG
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. "ESP8266Flasher.exe" oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]

SIGNALduino

2018-01-14T19:44:22Z

Sidey:

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Anfang 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden.

SIGNALDuino_nanoCC1101-331rc2.hex für einen Nano mit CC1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1sIac8-Qhts4c7OEkFH72Lv6hhgbOadFQ
</code>

SIGNALDuino_nano_331rc2.hex für einen Nano ohne cc1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1FnnIjJhBI1mjxZKzMnNtnnYzHChyn0lk
</code>

SIGNALDuino_promini_331rc2.hex für einen promini ohne cc1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1-AJKmO2DjQPi9_O3XI6KqvE9oYLHOyl8
</code>

SIGNALESP_331rc2.bin (mit cc1101) für einen ESP8266
<code>set ipduino flash https://drive.google.com/uc?export=download&id=1V8ZfLnRnskc64XZkfL-qwmI7AsSd6KRG
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. "ESP8266Flasher.exe" oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.nemcon.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]

SIGNALduino

2018-01-14T19:40:59Z

Sidey: /* Vorabversion einer Firmware */

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Anfang 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden.

SIGNALDuino_nanoCC1101-331rc2.hex für einen Nano mit CC1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1sIac8-Qhts4c7OEkFH72Lv6hhgbOadFQ
</code>

SIGNALDuino_nano_331rc2.hex für einen Nano ohne cc1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1FnnIjJhBI1mjxZKzMnNtnnYzHChyn0lk
</code>

SIGNALDuino_promini_331rc2.hex für einen promini ohne cc1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1-AJKmO2DjQPi9_O3XI6KqvE9oYLHOyl8
</code>

SIGNALESP_331rc2.bin (mit cc1101) für einen ESP8266
<code>set ipduino flash https://drive.google.com/uc?export=download&id=1V8ZfLnRnskc64XZkfL-qwmI7AsSd6KRG
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. "ESP8266Flasher.exe" oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Der Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.nemcon.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]

SIGNALduino

2018-01-14T19:40:35Z

Sidey:

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Anfang 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden.

SIGNALDuino_nanoCC1101-331rc2.hex für einen Nano mit CC1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1sIac8-Qhts4c7OEkFH72Lv6hhgbOadFQ
</code>

SIGNALDuino_nano_331rc2.hex für einen Nano ohne cc1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1FnnIjJhBI1mjxZKzMnNtnnYzHChyn0lk
</code>

SIGNALDuino_promini_331rc2.hex für einen promini ohne cc1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1-AJKmO2DjQPi9_O3XI6KqvE9oYLHOyl8
</code>

SIGNALESP_331rc1.bin (mit cc1101) für einen ESP8266
<code>set ipduino flash https://drive.google.com/uc?export=download&id=1V8ZfLnRnskc64XZkfL-qwmI7AsSd6KRG
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. "ESP8266Flasher.exe" oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Der Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.nemcon.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]

SIGNALduino

2018-01-13T21:08:04Z

Sidey: /* FHEM-Modul laden */ Firmware Update via HTTP inkl. Verweise zu Versionen ergänzt

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MOSI||GPIO13
|-
|MIS||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen; im Log-File sieht man, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduiono geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (Anfang 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die Folgenden Microcontroller kann man die Firmware downloaden.

SIGNALDuino_nanoCC1101-331rc2.hex für einen Nano mit CC1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1sIac8-Qhts4c7OEkFH72Lv6hhgbOadFQ
</code>

SIGNALDuino_nano_331rc2.hex für einen Nano ohne cc1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1FnnIjJhBI1mjxZKzMnNtnnYzHChyn0lk
</code>

SIGNALDuino_promini_331rc2.hex für einen promini ohne cc1101
<code>set sduino flash https://drive.google.com/uc?export=download&id=1-AJKmO2DjQPi9_O3XI6KqvE9oYLHOyl8
</code>

SIGNALESP_331rc1.bin (mit cc1101) für einen ESP8266
<code>set ipduino flash https://drive.google.com/uc?export=download&id=1V8ZfLnRnskc64XZkfL-qwmI7AsSd6KRG
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. "ESP8266Flasher.exe" oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:
Das Radino Board muss derzeit noch mit Angabe des Dateinamens geflasht werden:
<code>set sduino flash FHEM/firmware/SIGNALDuino_radinoCC1101.hex</code>

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für Funksteckdose das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

=== Der Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

Die Abfolge ist also ganz klar:
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> generische/zentrale Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.nemcon.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]

SIGNALduino

2018-01-13T20:44:54Z

Sidey: /* Hardware */ SignalESP beschreibung um Ports ergänzt

Update

2017-06-02T21:13:53Z

Sidey: /* Syntax controlfile */ Beschreibung zum MOV Befehl aktualisiert

{{SEITENTITEL:update}}
{{Infobox Modul
|ModPurpose=Befehl zur Aktualisierung der FHEM-Installation
|ModType=cmd
|ModCmdRef=update
|ModForumArea=Sonstiges
|ModTechName=98_update.pm
|ModOwner=rudolfkoenig ([http://forum.fhem.de/index.php?action=profile;u=8 Forum] / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])
}}
[[update]] ist ein Befehl zur Aktualisierung der FHEM-Installation direkt über das FHEM [[FHEMWEB|Webfrontend]]. Von den Entwicklern bis zu einem bestimmten Zeitpunkt freigegebene Änderungen sind jeweils morgens ab 8:00 Uhr über die Update Funktion verfügbar. Änderungen, die später freigegeben werden, werden dementsprechend erst am nächsten Tag verfügbar.

== Syntax ==
:<code><nowiki>update [<fileName>|all|check|force] [http://.../controlfile]</nowiki></code>
oder
:<code><nowiki>update [add source|delete source|list|reset]</nowiki></code>

'''Hinweise:'''
* FHEM sichert mit den Standardeinstellungen während des Updates "nur" die aktualisierten Modul(Installations-)dateien und bei Standardinstallationen ({{Link2Forum|Topic=59669|Message=511367}}) ab Updatestand 29.10.2016 die [[Konfiguration]] und fhem.save, aber beispielsweise nicht [[Plots erzeugen|Plots]] oder [[FileLog]]s. Soll vor dem Update ein vollständiges Backup von FHEM erstellt werden, muss das mit dem Attribut <code>[[#backup_before_update|backup_before_update]]</code> eingeschaltet werden.
* Lesen Sie aufmerksam die nach dem Update auf dem Monitor erscheinenden Meldungen zu Neuerungen und Änderungen.
* Nach einem Update ist immer ein ''shutdown restart'' erforderlich.
* geänderte und neu eingecheckte Module werden grundsätzlich erst am Folgetag ab ca. 8.00 Uhr durch den Update-Befehl verteilt.
* Mit dem Befehl [[version]] lässt sich die Version einzelner oder aller benutzten Module bestimmen.

== Parameter ==
Details zu Parametern des update Befehls:

=== Standardaufrufe ===
==== update ====
Die ganze FHEM-Installation wird auf die neueste Version gebracht. Vorhandene Module werden akualisiert und neue Module installiert.

==== update check ====
Es werden alle Module aufgelistet, von denen eine neuere als die bereits installierte Version verfügbar ist. Es wird nicht installiert.

==== update force ====
Das Update wird erzwungen (falls es beim regulären ''update'' Probleme geben sollte). Dieser Befehl ist nur mit Bedacht und ausschließlich im Notfall einzusetzen. Sollte ein reproduzierbares Problem existieren, dies bitte im FHEM-Forum berichten, damit dem nachgegangen werden kann.

==== update <Dateiname> ====
Mit z.B. <code>update 02_HTTPSRV.pm</code> wird nur von der Datei ''02_HTTPSRV.pm'' eine neue Version installiert. Alle anderen FHEM-Dateien werden nicht angetastet.

==== update all ====
Alle [[Systemübersicht#Module|offiziellen Module]] von FHEM sind in einem gemeinsamen Repository gespeichert. Nur diese Module werden in der Standardeinstellung durch den update-Befehl mit den bisher aufgeführten [[#Standardaufrufe|Standardaufrufen]] aktualisiert bzw. installiert. Einige Entwickler stellen ihre Module jedoch aus verschiedensten Gründen nicht im gemeinsamen Repository zur Verfügung, sondern nutzen eigene, separate Repositorys. Diese sogenannten "Thirdparty-Module" (auch bezeichnet als inoffizielle Module) können ebenfalls über update installiert und aktualisiert werden, wenn der Entwickler eine sogenannte Kontrolldatei (controlfile) in seinem Repository zur Verfügung stellt.

Zur Installation bzw. Update jedes einzelnen Thirdparty-Moduls ist nachfolgender Befehl aufzurufen (Webadresse und Kontrolldateiname sind modulabhängig passend zu ersetzen):
<code><nowiki>update all http://thirdparty.com/controls_funnymodule.txt</nowiki></code>

Die in den vorherigen Abschnitten erläuterten Standardaufruf (bis auf <code>update</code>) können durch Ergänzung um Webadresse und Kontrolldateiname (<nowiki>http://.../controlfile</nowiki> beim Befehls-Aufruf für das Update von einzelnen Thirdparty-Modulen genutzt werden.

=== Repository-Verwaltung ===
In den Standardeinstellungen von FHEM ist für jedes einzelne Repository ein separater Aufruf der [[#Standardaufrufe|Standardaufrufe]] zur Aktualiserung/Installation notwendig. Zur Vereinfachung des Update-Prozesses hat der update-Befehl eine eingebaute Repository-Verwaltung. Mittels der Repository-Verwaltung lassen sich die Standardaufrufe so beeinflußen, dass mit einem einzigen Aufruf sowohl die Module aus dem FHEM-Repository als auch aus verschiedenen Thirdparty-Repositorys beim Update berücksichtigt werden.

==== update add ====
Fügt ein zusätzliches Repository zur vereinfachten Nutzung über die Standardaufrufe hinzu. Ein Aufruf von <code><nowiki>update <Dateiname>|all|check|force</nowiki></code> berücksichtigt dann automatisch neben dem FHEM-eigenen Repository auch das hinzugefügte "Thirdparty-Repository".

Nach dem Hinzufügen durch beispielsweise <code><nowiki>update add http://thirdparty.com/controls_funnymodule.txt</nowiki></code> entfällt somit der manuelle Aufruf der Form <code><nowiki>update all http://thirdparty.com/controls_funnymodule.txt</nowiki></code> zur Aktualiserung. Er kann aber weiterhin genutzt werden, um ausschließlich für ein bestimmtes Repository ein Update zu erhalten und und nicht für alle.

Die Liste der Repositorys wird in der Verwaltungsdatei FHEM/controls.txt gespeichert.

==== update delete ====
Entfernt eine Repository aus der Verwaltungsdatei.

==== update list ====
Listet alle in der Verwaltungsdatei enthaltenen Repositorys auf.

==== update reset ====
Entfernt alle Fremd-Repositorys aus der Verwaltungsdatei. Nur das eigene Repository von FHEM wird noch von den Standardparametern berücksichtigt.

==== Syntax controlfile ====
Das Controlfile, welches durch thirdparty Module angelegt wird unterliegt eine Syntax.
Im Controlfile steht in jeder Zeile ein Dateiname und ein Befehl, was damit passieren soll. Ein Zeilenumbruch wird durch ein \n dargestellt

Es können zwei Befehle verwendet werden
UPD zum Aktualisieren einer Datei, MOV zum Verschieben oder auch Löschen einer Datei.

Aufbau der Befehle:

Zum Aktualisieren einer Datei. Die Aktualisierung wird nur ausgeführt, wenn das Datum von der lokalen Datei unterschiedlich ist und die Dateigröße der heruntergeladenen Datei übereinstimmt:

<code>UPD <Datum> <Dateigröße> <Datei inkl. Pfad> </code>

Zum Verschieben oder umbenennen einer Datei.

<code>MOV <quelldatei inkl. Pfad> <Zieldatei inkl. Pfad> </code>

Dateien lassen sich mit dem MOV Befehl auch in einen Spezielle Ordner unused verschieben. Ein vollständiges Löschen der Dateo ist derzeit nicht möglich:

<code>MOV <quelldatei inkl. Pfad> unused </code>

Bei Verwendung des Befehls UPD ist wichtig, dass das Datum inklusive Uhrzeit übergeben werden.

<source lang="perl">
my $date = POSIX::strftime("%Y-%d-%m", localtime( $fi->{mtime} ));
my $time = POSIX::strftime("%H:%M:%S", localtime( $fi->{mtime} ));
</source>

Erzeugt ''2016_14_10_23:50:13''.

Die Dateigröße ist exakt zu bestimmen:

<source lang="perl">
@line_parts[2] = fileparse($file,"");
@line_parts[3] = $fi->{size};
$modifiy_line = join(" ",@line_parts)."\n";
</source>

Komplettes Beispiel:

<code>UPD 2016_14_10_23:50:13 40341 FHEM/98_Dooya.pm</code>

== Attribute ==
Zur weiteren Beeinflussung der Funktionsweise des update Befehls können Attribute verwendet werden. Diese müssen für das Objekt ''global'' gesetzt werden, also mit einem Konfigurationsbefehl der Art
:<code>attr global ...</code>

=== backup_before_update ===
siehe auch [[backup]]

=== restoreDirs ===
siehe [[#Rücksichern beim Update überschriebener Dateien|Rücksichern beim Update überschriebener Dateien]]

=== exclude_from_update ===
Mit der Definition
:<code>attr global exclude_from_update ...</code>
kann eine Liste von Dateien spezifiziert werden, die bei der Ausführung des update Befehls '''nicht''' aktualisiert werden sollen. Dateien können auch über reguläre Ausdrücke definiert werden, die einzelnen Einträge werden durch Leerzeichen voneinander getrennt.

Einen Spezialfall stellt die ''commandref'' dar, die seit einer Modifikation des Update Prozesses (März 2015, beschrieben in dieser {{Link2Forum|Topic=34450|LinkText=Forendiskusion}}) nicht mehr heruntergeladen wird, sondern auf dem Benutzersystem durch Extraktion der Dokumentation aus den einzelnen Modulen generiert wird, angezeigt durch die Meldung im fhem.log:
:''Calling /usr/bin/perl ./contrib/commandref_join.pl, this may take a while''.
Sollte dieser Prozess (z.B. auf einem langsamen Rechner) zu lange dauern, bleibt die Meldung
:''update finished, "shutdown restart" is needed to activate the changes.''
aus. Wird ''commandref'' in das <code>exclude_from_update</code> Attribut eingetragen, entfällt dieser Schritt, die lokale ''commandref'' wird allerdings dann auch nicht mehr aktualisiert. Die modulspezifische Hilfe, die z.B. über <code>help modulname</code> aufgerufen werden kann, ist davon nicht betroffen.

== Anwendungsbeispiel ==
=== Durchführung eines Updates ===
Zunächst kann mit dem Befehl
:<code>update check</code>
überprüft werden, ob es überhaupt ein neues Update gibt und welche Dateien hierbei ausgetauscht würden (die angezeigten Infos sollten in einer Textdatei gesichert werden. Mit diesen Infos kann gezielter nach Problemen, die vielleicht nach einem Update auftreten, gesucht werden). Anschließend kann mittels:
:<code>update</code>
das Update eingespielt werden. Hierbei ist zu beachten, dass die Befehle auf der FHEM Webseite oben ([[Konfiguration|Befehls-Eingabefeld]]) eingegeben werden und anschließend die "Enter" Taste auf der Tastatur gedrückt werden muss.

Gibt es kein Update für FHEM, sieht die Ausgabe z.B. nach "update check" wie folgt aus:

:<code>List of new / modified files since last update:</code>
:<code>nothing to do...</code>

=== Rücksichern beim Update überschriebener Dateien ===
Per default werden vor dem Überschreiben alle Dateien in einem neuen Verzeichnis (restoreDir/Datum) gesichert. Diese Dateien kann man einzeln oder komplett mit dem Befehl [http://fhem.de/commandref#restore restore] zuruecksichern (z.Bsp.: <code>restore 2014-08-19</code> oder <code>restore 2014-08-19/fhem.pl</code>). Mit dem restoreDirs Attribut kann man die Anzahl der aufgehobenen Sicherungen (== Datum-Verzeichnisse) bestimmen, die Voreinstellung ist 3. Mit 0 kann man das Feature komplett abschalten.

Ab Updatestand 29.10.2016 können bei Standardinstallationen ({{Link2Forum|Topic=59669|Message=511367}}) die fhem.cfg und fhem.save mit der Option -a des restore-Befehl wiederhergestellt werden.

Update

2017-06-01T20:58:38Z

Sidey: /* Syntax controlfile */ Formatierung angepasst

{{SEITENTITEL:update}}
{{Infobox Modul
|ModPurpose=Befehl zur Aktualisierung der FHEM-Installation
|ModType=cmd
|ModCmdRef=update
|ModForumArea=Sonstiges
|ModTechName=98_update.pm
|ModOwner=rudolfkoenig ([http://forum.fhem.de/index.php?action=profile;u=8 Forum] / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])
}}
[[update]] ist ein Befehl zur Aktualisierung der FHEM-Installation direkt über das FHEM [[FHEMWEB|Webfrontend]]. Von den Entwicklern bis zu einem bestimmten Zeitpunkt freigegebene Änderungen sind jeweils morgens ab 8:00 Uhr über die Update Funktion verfügbar. Änderungen, die später freigegeben werden, werden dementsprechend erst am nächsten Tag verfügbar.

== Syntax ==
:<code><nowiki>update [<fileName>|all|check|force] [http://.../controlfile]</nowiki></code>
oder
:<code><nowiki>update [add source|delete source|list|reset]</nowiki></code>

'''Hinweise:'''
* FHEM sichert mit den Standardeinstellungen während des Updates "nur" die aktualisierten Modul(Installations-)dateien und bei Standardinstallationen ({{Link2Forum|Topic=59669|Message=511367}}) ab Updatestand 29.10.2016 die [[Konfiguration]] und fhem.save, aber beispielsweise nicht [[Plots erzeugen|Plots]] oder [[FileLog]]s. Soll vor dem Update ein vollständiges Backup von FHEM erstellt werden, muss das mit dem Attribut <code>[[#backup_before_update|backup_before_update]]</code> eingeschaltet werden.
* Lesen Sie aufmerksam die nach dem Update auf dem Monitor erscheinenden Meldungen zu Neuerungen und Änderungen.
* Nach einem Update ist immer ein ''shutdown restart'' erforderlich.
* geänderte und neu eingecheckte Module werden grundsätzlich erst am Folgetag ab ca. 8.00 Uhr durch den Update-Befehl verteilt.
* Mit dem Befehl [[version]] lässt sich die Version einzelner oder aller benutzten Module bestimmen.

== Parameter ==
Details zu Parametern des update Befehls:

=== Standardaufrufe ===
==== update ====
Die ganze FHEM-Installation wird auf die neueste Version gebracht. Vorhandene Module werden akualisiert und neue Module installiert.

==== update check ====
Es werden alle Module aufgelistet, von denen eine neuere als die bereits installierte Version verfügbar ist. Es wird nicht installiert.

==== update force ====
Das Update wird erzwungen (falls es beim regulären ''update'' Probleme geben sollte). Dieser Befehl ist nur mit Bedacht und ausschließlich im Notfall einzusetzen. Sollte ein reproduzierbares Problem existieren, dies bitte im FHEM-Forum berichten, damit dem nachgegangen werden kann.

==== update <Dateiname> ====
Mit z.B. <code>update 02_HTTPSRV.pm</code> wird nur von der Datei ''02_HTTPSRV.pm'' eine neue Version installiert. Alle anderen FHEM-Dateien werden nicht angetastet.

==== update all ====
Alle [[Systemübersicht#Module|offiziellen Module]] von FHEM sind in einem gemeinsamen Repository gespeichert. Nur diese Module werden in der Standardeinstellung durch den update-Befehl mit den bisher aufgeführten [[#Standardaufrufe|Standardaufrufen]] aktualisiert bzw. installiert. Einige Entwickler stellen ihre Module jedoch aus verschiedensten Gründen nicht im gemeinsamen Repository zur Verfügung, sondern nutzen eigene, separate Repositorys. Diese sogenannten "Thirdparty-Module" (auch bezeichnet als inoffizielle Module) können ebenfalls über update installiert und aktualisiert werden, wenn der Entwickler eine sogenannte Kontrolldatei (controlfile) in seinem Repository zur Verfügung stellt.

Zur Installation bzw. Update jedes einzelnen Thirdparty-Moduls ist nachfolgender Befehl aufzurufen (Webadresse und Kontrolldateiname sind modulabhängig passend zu ersetzen):
<code><nowiki>update all http://thirdparty.com/controls_funnymodule.txt</nowiki></code>

Die in den vorherigen Abschnitten erläuterten Standardaufruf (bis auf <code>update</code>) können durch Ergänzung um Webadresse und Kontrolldateiname (<nowiki>http://.../controlfile</nowiki> beim Befehls-Aufruf für das Update von einzelnen Thirdparty-Modulen genutzt werden.

=== Repository-Verwaltung ===
In den Standardeinstellungen von FHEM ist für jedes einzelne Repository ein separater Aufruf der [[#Standardaufrufe|Standardaufrufe]] zur Aktualiserung/Installation notwendig. Zur Vereinfachung des Update-Prozesses hat der update-Befehl eine eingebaute Repository-Verwaltung. Mittels der Repository-Verwaltung lassen sich die Standardaufrufe so beeinflußen, dass mit einem einzigen Aufruf sowohl die Module aus dem FHEM-Repository als auch aus verschiedenen Thirdparty-Repositorys beim Update berücksichtigt werden.

==== update add ====
Fügt ein zusätzliches Repository zur vereinfachten Nutzung über die Standardaufrufe hinzu. Ein Aufruf von <code><nowiki>update <Dateiname>|all|check|force</nowiki></code> berücksichtigt dann automatisch neben dem FHEM-eigenen Repository auch das hinzugefügte "Thirdparty-Repository".

Nach dem Hinzufügen durch beispielsweise <code><nowiki>update add http://thirdparty.com/controls_funnymodule.txt</nowiki></code> entfällt somit der manuelle Aufruf der Form <code><nowiki>update all http://thirdparty.com/controls_funnymodule.txt</nowiki></code> zur Aktualiserung. Er kann aber weiterhin genutzt werden, um ausschließlich für ein bestimmtes Repository ein Update zu erhalten und und nicht für alle.

Die Liste der Repositorys wird in der Verwaltungsdatei FHEM/controls.txt gespeichert.

==== update delete ====
Entfernt eine Repository aus der Verwaltungsdatei.

==== update list ====
Listet alle in der Verwaltungsdatei enthaltenen Repositorys auf.

==== update reset ====
Entfernt alle Fremd-Repositorys aus der Verwaltungsdatei. Nur das eigene Repository von FHEM wird noch von den Standardparametern berücksichtigt.

==== Syntax controlfile ====
Das Controlfile, welches durch thirdparty Module angelegt wird unterliegt eine Syntax.
Im Controlfile steht in jeder Zeile ein Dateiname und ein Befehl, was damit passieren soll. Ein Zeilenumbruch wird durch ein \n dargestellt

Es können zwei Befehle verwendet werden
UPD zum Aktualisieren einer Datei, MOV zum Verschieben oder auch Löschen einer Datei.

Aufbau der Befehle:

Zum Aktualisieren einer Datei. Die Aktualisierung wird nur ausgeführt, wenn das Datum von der lokalen Datei unterschiedlich ist und die Dateigröße der heruntergeladenen Datei übereinstimmt:

<code>UPD <Datum> <Dateigröße> <Datei inkl. Pfad> </code>

Zum Verschieben oder umbenennen einer Datei.

<code>MOV <quelldatei inkl. Pfad> <Zieldatei inkl. Pfad> </code>

Dateien lassen sich mit dem MOV Befehl auch löschen:

<code>MOV <quelldatei inkl. Pfad> unused </code>

Bei Verwendung des Befehls UPD ist wichtig, dass das Datum inklusive Uhrzeit übergeben werden.

<source lang="perl">
my $date = POSIX::strftime("%Y-%d-%m", localtime( $fi->{mtime} ));
my $time = POSIX::strftime("%H:%M:%S", localtime( $fi->{mtime} ));
</source>

Erzeugt ''2016_14_10_23:50:13''.

Die Dateigröße ist exakt zu bestimmen:

<source lang="perl">
@line_parts[2] = fileparse($file,"");
@line_parts[3] = $fi->{size};
$modifiy_line = join(" ",@line_parts)."\n";
</source>

Komplettes Beispiel:

<code>UPD 2016_14_10_23:50:13 40341 FHEM/98_Dooya.pm</code>

== Attribute ==
Zur weiteren Beeinflussung der Funktionsweise des update Befehls können Attribute verwendet werden. Diese müssen für das Objekt ''global'' gesetzt werden, also mit einem Konfigurationsbefehl der Art
:<code>attr global ...</code>

=== backup_before_update ===
siehe auch [[backup]]

=== restoreDirs ===
siehe [[#Rücksichern beim Update überschriebener Dateien|Rücksichern beim Update überschriebener Dateien]]

=== exclude_from_update ===
Mit der Definition
:<code>attr global exclude_from_update ...</code>
kann eine Liste von Dateien spezifiziert werden, die bei der Ausführung des update Befehls '''nicht''' aktualisiert werden sollen. Dateien können auch über reguläre Ausdrücke definiert werden, die einzelnen Einträge werden durch Leerzeichen voneinander getrennt.

Einen Spezialfall stellt die ''commandref'' dar, die seit einer Modifikation des Update Prozesses (März 2015, beschrieben in dieser {{Link2Forum|Topic=34450|LinkText=Forendiskusion}}) nicht mehr heruntergeladen wird, sondern auf dem Benutzersystem durch Extraktion der Dokumentation aus den einzelnen Modulen generiert wird, angezeigt durch die Meldung im fhem.log:
:''Calling /usr/bin/perl ./contrib/commandref_join.pl, this may take a while''.
Sollte dieser Prozess (z.B. auf einem langsamen Rechner) zu lange dauern, bleibt die Meldung
:''update finished, "shutdown restart" is needed to activate the changes.''
aus. Wird ''commandref'' in das <code>exclude_from_update</code> Attribut eingetragen, entfällt dieser Schritt, die lokale ''commandref'' wird allerdings dann auch nicht mehr aktualisiert. Die modulspezifische Hilfe, die z.B. über <code>help modulname</code> aufgerufen werden kann, ist davon nicht betroffen.

== Anwendungsbeispiel ==
=== Durchführung eines Updates ===
Zunächst kann mit dem Befehl
:<code>update check</code>
überprüft werden, ob es überhaupt ein neues Update gibt und welche Dateien hierbei ausgetauscht würden (die angezeigten Infos sollten in einer Textdatei gesichert werden. Mit diesen Infos kann gezielter nach Problemen, die vielleicht nach einem Update auftreten, gesucht werden). Anschließend kann mittels:
:<code>update</code>
das Update eingespielt werden. Hierbei ist zu beachten, dass die Befehle auf der FHEM Webseite oben ([[Konfiguration|Befehls-Eingabefeld]]) eingegeben werden und anschließend die "Enter" Taste auf der Tastatur gedrückt werden muss.

Gibt es kein Update für FHEM, sieht die Ausgabe z.B. nach "update check" wie folgt aus:

:<code>List of new / modified files since last update:</code>
:<code>nothing to do...</code>

=== Rücksichern beim Update überschriebener Dateien ===
Per default werden vor dem Überschreiben alle Dateien in einem neuen Verzeichnis (restoreDir/Datum) gesichert. Diese Dateien kann man einzeln oder komplett mit dem Befehl [http://fhem.de/commandref#restore restore] zuruecksichern (z.Bsp.: <code>restore 2014-08-19</code> oder <code>restore 2014-08-19/fhem.pl</code>). Mit dem restoreDirs Attribut kann man die Anzahl der aufgehobenen Sicherungen (== Datum-Verzeichnisse) bestimmen, die Voreinstellung ist 3. Mit 0 kann man das Feature komplett abschalten.

Ab Updatestand 29.10.2016 können bei Standardinstallationen ({{Link2Forum|Topic=59669|Message=511367}}) die fhem.cfg und fhem.save mit der Option -a des restore-Befehl wiederhergestellt werden.

Update

2017-06-01T20:46:25Z

Sidey: /* Repository-Verwaltung Syntax für das Controlfile hinterlegt*/

{{SEITENTITEL:update}}
{{Infobox Modul
|ModPurpose=Befehl zur Aktualisierung der FHEM-Installation
|ModType=cmd
|ModCmdRef=update
|ModForumArea=Sonstiges
|ModTechName=98_update.pm
|ModOwner=rudolfkoenig ([http://forum.fhem.de/index.php?action=profile;u=8 Forum] / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])
}}
[[update]] ist ein Befehl zur Aktualisierung der FHEM-Installation direkt über das FHEM [[FHEMWEB|Webfrontend]]. Von den Entwicklern bis zu einem bestimmten Zeitpunkt freigegebene Änderungen sind jeweils morgens ab 8:00 Uhr über die Update Funktion verfügbar. Änderungen, die später freigegeben werden, werden dementsprechend erst am nächsten Tag verfügbar.

== Syntax ==
:<code><nowiki>update [<fileName>|all|check|force] [http://.../controlfile]</nowiki></code>
oder
:<code><nowiki>update [add source|delete source|list|reset]</nowiki></code>

'''Hinweise:'''
* FHEM sichert mit den Standardeinstellungen während des Updates "nur" die aktualisierten Modul(Installations-)dateien und bei Standardinstallationen ({{Link2Forum|Topic=59669|Message=511367}}) ab Updatestand 29.10.2016 die [[Konfiguration]] und fhem.save, aber beispielsweise nicht [[Plots erzeugen|Plots]] oder [[FileLog]]s. Soll vor dem Update ein vollständiges Backup von FHEM erstellt werden, muss das mit dem Attribut <code>[[#backup_before_update|backup_before_update]]</code> eingeschaltet werden.
* Lesen Sie aufmerksam die nach dem Update auf dem Monitor erscheinenden Meldungen zu Neuerungen und Änderungen.
* Nach einem Update ist immer ein ''shutdown restart'' erforderlich.
* geänderte und neu eingecheckte Module werden grundsätzlich erst am Folgetag ab ca. 8.00 Uhr durch den Update-Befehl verteilt.
* Mit dem Befehl [[version]] lässt sich die Version einzelner oder aller benutzten Module bestimmen.

== Parameter ==
Details zu Parametern des update Befehls:

=== Standardaufrufe ===
==== update ====
Die ganze FHEM-Installation wird auf die neueste Version gebracht. Vorhandene Module werden akualisiert und neue Module installiert.

==== update check ====
Es werden alle Module aufgelistet, von denen eine neuere als die bereits installierte Version verfügbar ist. Es wird nicht installiert.

==== update force ====
Das Update wird erzwungen (falls es beim regulären ''update'' Probleme geben sollte). Dieser Befehl ist nur mit Bedacht und ausschließlich im Notfall einzusetzen. Sollte ein reproduzierbares Problem existieren, dies bitte im FHEM-Forum berichten, damit dem nachgegangen werden kann.

==== update <Dateiname> ====
Mit z.B. <code>update 02_HTTPSRV.pm</code> wird nur von der Datei ''02_HTTPSRV.pm'' eine neue Version installiert. Alle anderen FHEM-Dateien werden nicht angetastet.

==== update all ====
Alle [[Systemübersicht#Module|offiziellen Module]] von FHEM sind in einem gemeinsamen Repository gespeichert. Nur diese Module werden in der Standardeinstellung durch den update-Befehl mit den bisher aufgeführten [[#Standardaufrufe|Standardaufrufen]] aktualisiert bzw. installiert. Einige Entwickler stellen ihre Module jedoch aus verschiedensten Gründen nicht im gemeinsamen Repository zur Verfügung, sondern nutzen eigene, separate Repositorys. Diese sogenannten "Thirdparty-Module" (auch bezeichnet als inoffizielle Module) können ebenfalls über update installiert und aktualisiert werden, wenn der Entwickler eine sogenannte Kontrolldatei (controlfile) in seinem Repository zur Verfügung stellt.

Zur Installation bzw. Update jedes einzelnen Thirdparty-Moduls ist nachfolgender Befehl aufzurufen (Webadresse und Kontrolldateiname sind modulabhängig passend zu ersetzen):
<code><nowiki>update all http://thirdparty.com/controls_funnymodule.txt</nowiki></code>

Die in den vorherigen Abschnitten erläuterten Standardaufruf (bis auf <code>update</code>) können durch Ergänzung um Webadresse und Kontrolldateiname (<nowiki>http://.../controlfile</nowiki> beim Befehls-Aufruf für das Update von einzelnen Thirdparty-Modulen genutzt werden.

=== Repository-Verwaltung ===
In den Standardeinstellungen von FHEM ist für jedes einzelne Repository ein separater Aufruf der [[#Standardaufrufe|Standardaufrufe]] zur Aktualiserung/Installation notwendig. Zur Vereinfachung des Update-Prozesses hat der update-Befehl eine eingebaute Repository-Verwaltung. Mittels der Repository-Verwaltung lassen sich die Standardaufrufe so beeinflußen, dass mit einem einzigen Aufruf sowohl die Module aus dem FHEM-Repository als auch aus verschiedenen Thirdparty-Repositorys beim Update berücksichtigt werden.

==== update add ====
Fügt ein zusätzliches Repository zur vereinfachten Nutzung über die Standardaufrufe hinzu. Ein Aufruf von <code><nowiki>update <Dateiname>|all|check|force</nowiki></code> berücksichtigt dann automatisch neben dem FHEM-eigenen Repository auch das hinzugefügte "Thirdparty-Repository".

Nach dem Hinzufügen durch beispielsweise <code><nowiki>update add http://thirdparty.com/controls_funnymodule.txt</nowiki></code> entfällt somit der manuelle Aufruf der Form <code><nowiki>update all http://thirdparty.com/controls_funnymodule.txt</nowiki></code> zur Aktualiserung. Er kann aber weiterhin genutzt werden, um ausschließlich für ein bestimmtes Repository ein Update zu erhalten und und nicht für alle.

Die Liste der Repositorys wird in der Verwaltungsdatei FHEM/controls.txt gespeichert.

==== update delete ====
Entfernt eine Repository aus der Verwaltungsdatei.

==== update list ====
Listet alle in der Verwaltungsdatei enthaltenen Repositorys auf.

==== update reset ====
Entfernt alle Fremd-Repositorys aus der Verwaltungsdatei. Nur das eigene Repository von FHEM wird noch von den Standardparametern berücksichtigt.

==== Syntax controlfile ====
Das Controlfile, welches durch thirdparty Module angelegt wird unterliegt eine Syntax.
Im Controlfile steht in jeder Zeile ein Dateiname und ein Befehl, was damit passieren soll. Ein Zeilenumbruch wird durch ein \n dargestellt

Es können zwei Befehle verwendet werden
UPD zum Aktualisieren einer Datei, MOV zum Verschieben oder auch Löschen einer Datei.

Aufbau der Befehle:

Zum Aktualisieren einer Datei. Die Aktualisierung wird nur ausgeführt, wenn das Datum von der lokalen Datei unterschiedlich ist und die Dateigröße der heruntergeladenen Datei übereinstimmt:

<code>UPD <Datum> <Dateigröße> <Datei inkl. Pfad> </code>

Zum Verschieben oder umbenennen einer Datei.

<code>MOV <quelldatei inkl. Pfad> <Zieldatei inkl. Pfad> </code>

Dateien lassen sich mit dem MOV Befehl auch löschen:

<code>MOV <quelldatei inkl. Pfad> unused </code>

Bei Verwendung des Befehls UPD ist wichtig, dass das Datum inklusive Uhrzeit übergeben werden.

<code>
my $date = POSIX::strftime("%Y-%d-%m", localtime( $fi->{mtime} ));

my $time = POSIX::strftime("%H:%M:%S", localtime( $fi->{mtime} ));
</code>

Erzeugt ''2016_14_10_23:50:13''.

Die Dateigröße ist exakt zu bestimmen:

<code>
@line_parts[2] = fileparse($file,"");

@line_parts[3] = $fi->{size};

$modifiy_line = join(" ",@line_parts)."\n";

</code>

Komplettes Beispiel:

<code>UPD 2016_14_10_23:50:13 40341 FHEM/98_Dooya.pm</code>

== Attribute ==
Zur weiteren Beeinflussung der Funktionsweise des update Befehls können Attribute verwendet werden. Diese müssen für das Objekt ''global'' gesetzt werden, also mit einem Konfigurationsbefehl der Art
:<code>attr global ...</code>

=== backup_before_update ===
siehe auch [[backup]]

=== restoreDirs ===
siehe [[#Rücksichern beim Update überschriebener Dateien|Rücksichern beim Update überschriebener Dateien]]

=== exclude_from_update ===
Mit der Definition
:<code>attr global exclude_from_update ...</code>
kann eine Liste von Dateien spezifiziert werden, die bei der Ausführung des update Befehls '''nicht''' aktualisiert werden sollen. Dateien können auch über reguläre Ausdrücke definiert werden, die einzelnen Einträge werden durch Leerzeichen voneinander getrennt.

Einen Spezialfall stellt die ''commandref'' dar, die seit einer Modifikation des Update Prozesses (März 2015, beschrieben in dieser {{Link2Forum|Topic=34450|LinkText=Forendiskusion}}) nicht mehr heruntergeladen wird, sondern auf dem Benutzersystem durch Extraktion der Dokumentation aus den einzelnen Modulen generiert wird, angezeigt durch die Meldung im fhem.log:
:''Calling /usr/bin/perl ./contrib/commandref_join.pl, this may take a while''.
Sollte dieser Prozess (z.B. auf einem langsamen Rechner) zu lange dauern, bleibt die Meldung
:''update finished, "shutdown restart" is needed to activate the changes.''
aus. Wird ''commandref'' in das <code>exclude_from_update</code> Attribut eingetragen, entfällt dieser Schritt, die lokale ''commandref'' wird allerdings dann auch nicht mehr aktualisiert. Die modulspezifische Hilfe, die z.B. über <code>help modulname</code> aufgerufen werden kann, ist davon nicht betroffen.

== Anwendungsbeispiel ==
=== Durchführung eines Updates ===
Zunächst kann mit dem Befehl
:<code>update check</code>
überprüft werden, ob es überhaupt ein neues Update gibt und welche Dateien hierbei ausgetauscht würden (die angezeigten Infos sollten in einer Textdatei gesichert werden. Mit diesen Infos kann gezielter nach Problemen, die vielleicht nach einem Update auftreten, gesucht werden). Anschließend kann mittels:
:<code>update</code>
das Update eingespielt werden. Hierbei ist zu beachten, dass die Befehle auf der FHEM Webseite oben ([[Konfiguration|Befehls-Eingabefeld]]) eingegeben werden und anschließend die "Enter" Taste auf der Tastatur gedrückt werden muss.

Gibt es kein Update für FHEM, sieht die Ausgabe z.B. nach "update check" wie folgt aus:

:<code>List of new / modified files since last update:</code>
:<code>nothing to do...</code>

=== Rücksichern beim Update überschriebener Dateien ===
Per default werden vor dem Überschreiben alle Dateien in einem neuen Verzeichnis (restoreDir/Datum) gesichert. Diese Dateien kann man einzeln oder komplett mit dem Befehl [http://fhem.de/commandref#restore restore] zuruecksichern (z.Bsp.: <code>restore 2014-08-19</code> oder <code>restore 2014-08-19/fhem.pl</code>). Mit dem restoreDirs Attribut kann man die Anzahl der aufgehobenen Sicherungen (== Datum-Verzeichnisse) bestimmen, die Voreinstellung ist 3. Mit 0 kann man das Feature komplett abschalten.

Ab Updatestand 29.10.2016 können bei Standardinstallationen ({{Link2Forum|Topic=59669|Message=511367}}) die fhem.cfg und fhem.save mit der Option -a des restore-Befehl wiederhergestellt werden.

SIGNALduino

2017-03-05T11:58:57Z

Sidey: Firmware für radino ergänzt

SIGNALduino

2017-03-01T21:16:17Z

Sidey: Hardware Variante angepasst

SIGNALduino

2017-02-02T20:32:08Z

Sidey: Aktualisierung c1101, Somfy RTS Verlinkung, sendMsg Befehl

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digialen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

Das Modul [[SIGNALduino]] unterstützt den gleichnamigen Low-Cost Empfänger für digitale Signale, ähnlich einem [[CUL]]. Der SIGNALduino (Hardware) basiert auf einem Arduino. Hauptsächlich wurde er für den [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano] entwickelt. Es stehen jedoch auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 Mhz. Wer einen Mikrocontroller mit 8 Mhz verwenden möchte, muss die Firmware selbst compilieren.

Er wird hauptsächlich über den USB Port angeschlossen, kann aber auch mit Zusätzlichen ESP Modulen über ein WLAN angebunden werden. Die Schaltung entspricht der des [[FHEMduino]].
In Arbeit ist auch eine Variante zum [[Selbstbau_CUL]].
Und ebenso eine Variante, die auf einem [[ESP8266]] nativ läuft.

# Das Modul wird stetig weiterentwickelt
# Das Modul gibt bei Bedarf sehr viele Meldungen ins Logfile, in den Normaleinstellungen verhält es sich aber relativ ruhig.

== Was macht dieser SIGNALduino? ==
[[Datei:Fhemduino_schematic.png|200px|thumb|right|SIGNAL(FHEM)duino Schaltplan]]
Digitale Signale anhand von Mustern erkennen und zum Auswerten an FHEM weitergeben, dort können die Daten dann dekodiert werden.
Zwischenzeitlich gibt der Arduino alle erkannten Signale an FHEM weiter, dies hilft um vor allem Signale zu finden, die noch nicht bekannt sind.

Beispiel:
Arduino mit 433 Mhz Empfänger an einen FHEM Server anschließen und IT Steckdosen empfangen / schalten

Das System ist jedoch nicht auf 433 Mhz beschränkt. Es funktioniert auch mit anderen Frequenzen oder Medien, z.B. auch mit Infrarot oder direkt angebunden via Draht.

== Worin liegt der Vorteil zu einem CUL oder FHEMduino? ==
Der vorteil besteht darin, dass man sehr schnell das Funksignal demodulieren kann.
Wer Lust hat weitere Protokolle zu dekodieren, braucht dazu nur ein passendes FHEM Modul entwickeln oder ein universelles Modul erweitern. Änderungen am Arduino Code sind "eigentlich" nicht notwendig, dadurch skaliert das System gut.

Andere Möglichkeit: Wer einen Wettersensor dekodieren möchte, muss ja erst mal feststellen, was der Sensor sendet. Dazu kann man den SIGNALduino auch an den Sendeausgang des Sensors anbinden und empfängt die digitalen Signale. Bitte achtet aber auf die passenden Spannungen, bevor ihr eine solche Schaltung vornehmt. Ein Arduino Nano verträgt 5V.

== Unterstützte Geräte ==
Für die folgenden Geräte gibt es derzeit eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen wenn der SIGNALduino mal läuft.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochon eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhel HS 434/6||E || || none || 21
|-
|FA21RF||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}

== Hardware ==
Wie muss der Arduino verkabelt werden?
Die Verkabelung ist Identisch zum [[FHEMduino]]

Des weiteren benötigt man neben dem Arduino ein Sendemodul und auch ein Empfangsmodul.
Für gut befunden sind z.B. ein RXB6 Modul um 433 Mhz Signale empfangen zu können.

== Bauanleitung und Teileliste ==

Benötigt wird ein Arduino Nano, Uno oder mini. Zu empfehlen ist der Nano.
An den Nano, werden Empfänger und Sendeeinheit angeschlossen.
Als weitere Komponenten benötigt man einen Sender und Empfänger im gewünschten Frequenzspektrum. Hierzu kann auch eine bestehende Wetterstation oder Funkfernbedienung ausgeschlachtet werden.

Durch die geringe Anzahl an Bauteilen lässt sich das System sehr gut auf einer Lochrasterplatine aufbauen und ist somit auch für Anwender, die mit dem Aufbau von Schaltungen weniger bewandert sind, leicht zu realisieren.

Anbei eine Auswahl häufig verwendeter Komponenten. Diese sind alle (z.B. auf Ebay) leicht zu finden:
* Arduino Nano V3.0 ATmega328P 5V 16M
* 433 Mhz Transmitter FS1000A (dieser wird in der Regel mit einem Empfänger XY-MK-5V angeboten. Der Empfänger ist jedoch relativ unbrauchbar)
* 433 Mhz Empfänger RXB-6 oder alternativ auch RXB-8
* 433MHz Helix Antenne

== Einbinden in FHEM ==
Die SIGNALduino Module werden über das FHEM [[update]] verteilt.

Die in der Entwicklung befindliche Version kann auch geladen werden. Dazu folgende Befehle in FHEM ausführen:

1. FHEM aktualisieren: <code>update</code>
2. SIGNALduino Modul und Firmware aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>

Gerade wenn neue Entwicklungen für euch interessant sind, könnt ihr FHEM auch dauerhaft die developer Version aktualisieren lassen:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update Befehl immer automatisch die aktuelle dev Version laden.

Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet. Außerdem wird auch die Firmware geladen. Im Log File seht ihr, wo diese hinkopiert wurden: z.B. nach FHEM/firmware/SIGNALduino_nano328.hex

Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB Anschlusses muss natürlich an die aktuellen Gegebenheiten angepasst werden):
:<code>define sduino SIGNALduino /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0@57600</code>

Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

== Flashen des Ardunio mit der SIGNALduino Firmware ==
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino ja bereits mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware Dateien wechseln.

Beispiel:
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

=== Arduino Nano mit cc1101 / NanoCul (nur development Version) ===
Solltet ihr einen Nano mit cc1101 Transreceiver verwenden, so wählt bitte folgende Hadware, damit die richtige Firmware geflasht wird,
<code>attr sduino hardware nanoCC1101</code>

== Daten aus dem Logfile erklärt ==
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird:

Unknown Code, so oder ähnlich bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert, welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:
<code>sduino: Unknown code u1FFFFF0, help me!</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu Zusätzlichen Unknown code Einträgen.
Diese Einträge können mit dem Attribut WhitelistID minimiert werden. Geräte, welche ihr empfangen wollt, könnt ihr in die WhitelistID aufnehmen. Die Geräte werden dadurch anhand einer Protokollnummer identifiziert. Diese kann der obigen Tabelle zum Teil entnommen werden. Hilfreich ist es auch, wenn ihr in den verwendeten Geräten im Internal <gerätename>_DMSG nachseht. Diese sind teilweise nach folgendem Schema aufgebaut: <code>W50#FF553335FFBC</code> W50 bedeutet dann Protokoll #50.
Ist der Aufbau nicht so, hilft noch ein Blick in den Quellcode

MS - Nachricht mit Sync Puls: Es wurde eine Signal empfangen. P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. 15 Bedeutet es wurde ein Signalpegel (1) 395 Mikrosekundenhigh und Anschließend (5) 8916 Mikrosekunden low gemessen. CP=1 ist die Referenz auf den Takt des Signales. Getaktet wird in diesem Fall mit ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.
:
<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code>

MC - Nachricht vom Typ Manchester: Manchester Kodierte Signale, können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:
<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

MU - Message unsynced: Diese Art von Nachrichten, sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht.
Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist.
Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:
<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

== Mein Gerät wird in FHEM nicht erkannt ==
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x
Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Alternativ könnt ihr auch im Forum posten. Um einzelne Erweiterungen besser im Überblick zu behalten, eignet sich das github jedoch besser.

== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ==
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend Notwendig um seine Anforderungen zu erfüllen.

Insbesondere für Schalter bzw. Sensoren die nur zwei Zustände kennen geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden
Im FHEM Log tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu teilen wissen, da er sich ändert:
<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring
<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden. Der Name eures SIGNALduino eventuell auch.

== Wie kann ich etwas Senden ==
Der SIGNALduino kann etwas senden, indem ihm das SIGNAL so übermittelt wird, wie er es moduliert.
Genannt "raw senden".

Um in der FHEM Kommandozeile etwas zu senden muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.
== Es erscheinen viele Logmeldungen für Geräte die ich nicht habe ==
Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Viele dieser Logmeldungen können durch Setzen des ''verbose'' Levels auf den Wert ''3'' unterdrückt werden.

Dennoch kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Das Attribut ''whitelistIDs'' erlaubt es, anzugeben, welche Protokolle vom FHEM Modul berücksichtigt werden. Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei. Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.nemcon.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]