SWAP: Unterschied zwischen den Versionen
TeeVau (Diskussion | Beiträge) (1. Auskopplung aus der Diskussion vom Artikel PanStamp) |
TeeVau (Diskussion | Beiträge) Keine Bearbeitungszusammenfassung |
||
Zeile 17: | Zeile 17: | ||
== Voraussetzungen == | == Voraussetzungen == | ||
Für den Betrieb ist XML:Simple notwendig, dass bei Bedarf folgendermaßen nachinstalliert werden kann [http://forum.fhem.de/index.php?topic=12487.msg87373#msg87373]. | |||
<pre> | |||
sudo apt-get install libxml-simple-perl | |||
</pre> | |||
Diese Abhängigkeit kann beim Betrieb auf einer Fritzbox ebenfalls zu Problemen führen. Das SWAP Modul greift auf das [[PanStamp]] Modul zu, was vorher per define anglegt werden muss. | |||
== Anwendung == | == Anwendung == | ||
Zeile 46: | Zeile 50: | ||
[http://forum.fhem.de/index.php/topic=12487.msg78502#msg78502] | [http://forum.fhem.de/index.php/topic=12487.msg78502#msg78502] | ||
=== Define === | === Define === | ||
'''Info: Das SWAP Modul unterstützt autocreate. Bei der Inbetriebnahme sollte autocreate aktiviert sein, da dies die Einrichtung deutlich vereinfacht.''' | |||
Wenn der panStick läuft, sollten die SWAP-Devices per autocreate angelegt werden, sobald sie das erste mal senden, z.B. nach dem Einschalten oder nach einem Reset. | |||
Normalerweise werden beim autocreate alle Werte abgefragt und angezeigt. Das geht normalerweise ohne jedes Zutun. | |||
Panstick rein -> broadcast -> discovery -> anlegen. | |||
Bei Devices mit power down mode erfolgt dieses das erste mal wenn sie Strom haben. | |||
Alle panStamps durchlaufen beim Starten eine bestimmte Einschaltsequenz. Sie melden sich mit ihrer ID und ihrem productcode. Die ID ist die device Addresse und bei einem frisch geflashten panStamp in der Regel FF. Das SWAP Modul versucht, ein Device mit der Default Adresse <code>FF</code> automatisch auf die erste freie Adresse im Bereich <code>F0</code>-<code>FE</code> zu ändern. | |||
Neue panStamps sollten nur Einer nach dem Anderen in Betrieb genommen werden, sonst haben mehrere die gleiche Addresse und das gibt Konflikte. | |||
Wer mehrere devices hat, sollte jedem nach dem Anlegen mit | |||
<pre> | |||
set <device> regSet 09 <device adresse als 2 stellige hex zahl> | |||
</pre> | |||
eine eigene id zuweisen. Die landen auf dem panStamp im EEPROM und sind auch nach Neustart noch vorhanden. | |||
Die anderen Adressen sind wie folgt belegt: | |||
* 00 ist die Broadcast-ID | |||
* 01 ist die ID des Pansticks am FHEM-System | |||
* FF ist die Default ID, die jeder panStamp im Auslieferungszustand besitzt | |||
* F0-FE sind die IDs, auf die autocreate die Adresse automatisch ändert, wenn ein neuer mit der ID FF erkannt wird und kein entsprechender Device-Name definiert ist. | |||
{{Link2Forum|Topic= 12487 |Message=87261 }} | |||
[http://forum.fhem.de/index.php?topic=12487.msg87261#msg87261] | |||
Ändert man die Adresse, dauert es einen Augenblick, bis alle Register neu übertragen worden sind. | |||
Autocreate ändert bei der Einrichtung und Änderung der ID auch automatisch den Namen. Belässt man die ID im Bereich F0-FE und ändert den Namen des Device, ist zu berücksichtigen, dass autocreate für neue Devices eine freie neue Adresse anhand der Device-Namen sucht. Dadurch könnte es zu Doppeltverwendung von IDs kommen. | |||
Alternativ zum autocreate kann man ein Device auch von Hand anlegen mit | |||
<pre> | |||
define <device> SWAP <ID> | |||
</pre> | |||
Bis allerdings der Productcode nicht per Attribut hinterlegt ist, was bei autocreate ebenfalls automatisch geschied, funktionieren nur die grundlegenden Funktionen bis zur 2. Modulebene. | |||
=== set === | |||
Ist ein SWAP-Device definiert, stehen folgende set-Befehle zur Verfügung: | |||
* regGet <reg> | |||
Fragt den Wert des Registers mit der id <reg> ab. Für die Systemregister kann hierzu statt der RegisterID auch der Registername (siehe regListAll) verwendet werden. | |||
{{Link2Forum|Topic= 12487 |Message=87679 }} | |||
[http://forum.fhem.de/index.php/topic,12487.msg87679.html#msg87679] | |||
* regSet <reg> <data> | |||
Schreibt <data> in den Register mit der id <reg>. Für die Systemregister kann hierzu statt der RegisterID auch der Registername (siehe regListAll) verwendet werden. | |||
* regSet <reg>.<ep> <data> | |||
write <data> to endpoint <ep> of register <reg>. will not work if no reading for register <reg> is available as all nibbles that are not part of endpoint <ep> will be filled from this reading. ? | |||
* statusRequest | |||
Veranlasst, dass alle Register und deren Werte einmal übertragen werden. | |||
* readDeviceXML | |||
Liest das Device-Description-XML-File neu ein. | |||
* clearUnconfirmed | |||
Löscht die liste der unbestätigten Nachrichten. | |||
* flash [<productCode>|<firmwareFile>] | |||
Initiiert das „over-the-air“ Firmware update, dass (derzeit) nur von NRG panStamps unterstützt wird. | |||
** ohne Parameter: Verwendet das SWAP_<current productCode>.hex-File aus dem Verzeichnis ./FHEM/firmware. | |||
** <productCode>: Verwendet das SWAP_<productCode>.hex-File aus dem Verzeichnis ./FHEM/firmware. | |||
** <firmwareFile>: Verwendet ein <firmwareFile> als absoluten File-Namen des HEX-Files. | |||
=== get === | |||
* regList | |||
Listet alle User-Register des SWAP-Device (Readings). | |||
* regListAll | |||
Listet alle Register des SWAP-Device (Internals und Readings). | |||
* listUnconfirmed | |||
Listet alle unbestätigten Nachrichten in der Warteschlange. | |||
* products | |||
Gibt alle auf dem System bekannten Productcodes nebst Daten aus. | |||
* deviceXML | |||
Gibt die Daten des zum derzeit zum per Attribut (Productcode) eingerichteten Device-XML-Files aus. | |||
=== Attribute === | === Attribute === | ||
Wird der Productcode bei der Definition nicht gesetzt, stehen auch nur die Standardbefehle bei zur 2. Modulebene zur Verfügung. | |||
* createUnknownReadings | |||
Erzeug Readings auch für Register, die im Device-XML-File nicht definiert werden. | |||
* ProductCode | |||
Legt den ProductCode eines SWAP-Device fest. Dieses Attribut wird dazu benutzt, die Konfiguration vom Device-XML-File festzulegen. | |||
Erst wenn der Produktcode als Attribut vorgegeben wurde, z.B. für einen RGB-Sktech: | |||
attr <device> ProductCode 0000002200000003 | |||
kommen zu den allgemeinen Kommandos die spezifischen der nächst höheren Modulebene 35_SWAP_<productcode>.pm mit hinzu. Dann werden die SWAP-Nachrichten an das entsprechende Modul weitergegeben und dort verarbeitet. | |||
Für batteriebetriebene Devices, die während der Definition nicht aktiv sind, muss dieses Attribut manuell angelegt werden. | |||
=== Device Description File === | === Device Description File === |
Version vom 17. Juli 2015, 09:51 Uhr
An dieser Seite wird momentan noch gearbeitet. |
SWAP | |
---|---|
Zweck / Funktion | |
Modul zur allgemeinen Ansteuerung sämtlicher PanStamp Boards. | |
Allgemein | |
Typ | Gerätemodul |
Details | |
Dokumentation | EN / DE |
Modulname | 34_SWAP.pm |
Ersteller | André/ justme1968 (Forum / Wiki) |
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref! |
SWAP ist das Basismodul für die Unterstützung der PanStamp Baugruppen. Zur Kommunikation in einem PanStamp Netzwerk dient das Simple Wireless Abstract Protocol (SWAP). Die komplette SWAP- Kommunikation ist registerbasiert und erfolgt mit Nachrichten um diese Register abzufragen, zu setzen und deren Inhalt zu senden. Alle Register lassen sich lesen, manche auch beschreiben. Für eine tiefgreifende FHEM Integration können weitere Module (wie z.B. xxxx) vorhanden sein. Diese Module bauen auf das SWAP Modul auf und bedienen im backend ebenfalls die PanStamp Module über die Register. Der PanStamp Software Stack unterstützt einen stromsparenden Power-Down- oder Sleep-Modus für batteriebetriebene Sensoren, aus dem diese dann nur zur eigentlichen Messung und Übertragung "aufwachen".
Voraussetzungen
Für den Betrieb ist XML:Simple notwendig, dass bei Bedarf folgendermaßen nachinstalliert werden kann [1].
sudo apt-get install libxml-simple-perl
Diese Abhängigkeit kann beim Betrieb auf einer Fritzbox ebenfalls zu Problemen führen. Das SWAP Modul greift auf das PanStamp Modul zu, was vorher per define anglegt werden muss.
Anwendung
Bei SWAP geht alle Kommunikation über 'Register', dies sind unterschiedlich lange Werte die entweder nur gelesen oder gelesen und geschrieben werden können. Jedes Device hat eine Reihe Systemregister (00-0A) und beliebig viele Userregister die vom jeweiligen Sketch abhängen. Welche Register dies sind, steht unter anderem jeweils im Device Description xml file im Verzeichnis .../FHEM/lib/SWAP.
In den System Registern steht z.b. der productcode, die device adresse und das Übertragungsintervall. Konfigurierbare Register werden im EEPROM gesichert und die Werte gehen auch beim Neustart nicht verloren. Beim aller ersten Starten ist das EEPROM mit "FF" initialisiert und alle konfigurierbaren Register haben diesen Wert. also z.b. Adresse FF und Intervall FFFF (HEX in Sekunden, das wären dann zwischen 18 und 19 Stunden).
Die Inhalte der System Register stehen als INTERNAL im oberen Bereich der Detail Ansicht einer Komponente in FHEM, die user register als Readings im unteren.
Alle low level Dinge wie Register ID oder Register Wert können mit hex Werten direkt angepasst werden. Im Normalbetrieb ist dieses aber nicht notwendig und es kann über 'vereinfachte' Kommandos mit den Registernamen verwenden kann. Diese Funktionalität stellt das eines der Module zur Verfügung.
set <device> regSet 0A <intervall in sekunden als 4 stellige hex zahl> set <device> regSet 08 <netzwerk id als 2 stellige hex zahl>
Dieses Modul stellt unter anderem folgende grundlegende Funktionalitäten zur Verfügung
- Es wird eine command Liste für Devices im power down Modus gehalten. Sobald das Device online kommt werden die Kommandos automatisch übertragen.
- Die userReadings für 'menschenlesbare' Readings werden anhand des device description files automatisch erzeugt
- Es ist jetzt möglich direkt endpoints (Teile eines Registers) zu schreiben (???)
- (Fast) keine hardkodierte Sonderbehandlung mehr für das RGB-Board. Das SWAP Modul kann mit jedem beliebige Swap Device umgehen.
- Es gibt eine dritte (optionale) Modulschicht neben dem PanStamp modul für die Hardware und dem SWAP Modul für das Protokoll. Mit dem generellen SWAP Modul lasen sich alle SWAP devices 'zu fuss' über die Register ansprechen. Um die register auf einer höheren Ebene auf FHEM Kommandos wie on/off/on-for-timer zu mappen ist dann diese dritte schicht zuständig.
Define
Info: Das SWAP Modul unterstützt autocreate. Bei der Inbetriebnahme sollte autocreate aktiviert sein, da dies die Einrichtung deutlich vereinfacht.
Wenn der panStick läuft, sollten die SWAP-Devices per autocreate angelegt werden, sobald sie das erste mal senden, z.B. nach dem Einschalten oder nach einem Reset.
Normalerweise werden beim autocreate alle Werte abgefragt und angezeigt. Das geht normalerweise ohne jedes Zutun.
Panstick rein -> broadcast -> discovery -> anlegen.
Bei Devices mit power down mode erfolgt dieses das erste mal wenn sie Strom haben.
Alle panStamps durchlaufen beim Starten eine bestimmte Einschaltsequenz. Sie melden sich mit ihrer ID und ihrem productcode. Die ID ist die device Addresse und bei einem frisch geflashten panStamp in der Regel FF. Das SWAP Modul versucht, ein Device mit der Default Adresse FF
automatisch auf die erste freie Adresse im Bereich F0
-FE
zu ändern.
Neue panStamps sollten nur Einer nach dem Anderen in Betrieb genommen werden, sonst haben mehrere die gleiche Addresse und das gibt Konflikte.
Wer mehrere devices hat, sollte jedem nach dem Anlegen mit
set <device> regSet 09 <device adresse als 2 stellige hex zahl>
eine eigene id zuweisen. Die landen auf dem panStamp im EEPROM und sind auch nach Neustart noch vorhanden.
Die anderen Adressen sind wie folgt belegt:
- 00 ist die Broadcast-ID
- 01 ist die ID des Pansticks am FHEM-System
- FF ist die Default ID, die jeder panStamp im Auslieferungszustand besitzt
- F0-FE sind die IDs, auf die autocreate die Adresse automatisch ändert, wenn ein neuer mit der ID FF erkannt wird und kein entsprechender Device-Name definiert ist.
Ändert man die Adresse, dauert es einen Augenblick, bis alle Register neu übertragen worden sind.
Autocreate ändert bei der Einrichtung und Änderung der ID auch automatisch den Namen. Belässt man die ID im Bereich F0-FE und ändert den Namen des Device, ist zu berücksichtigen, dass autocreate für neue Devices eine freie neue Adresse anhand der Device-Namen sucht. Dadurch könnte es zu Doppeltverwendung von IDs kommen.
Alternativ zum autocreate kann man ein Device auch von Hand anlegen mit
define <device> SWAP <ID>
Bis allerdings der Productcode nicht per Attribut hinterlegt ist, was bei autocreate ebenfalls automatisch geschied, funktionieren nur die grundlegenden Funktionen bis zur 2. Modulebene.
set
Ist ein SWAP-Device definiert, stehen folgende set-Befehle zur Verfügung:
- regGet <reg>
Fragt den Wert des Registers mit der id <reg> ab. Für die Systemregister kann hierzu statt der RegisterID auch der Registername (siehe regListAll) verwendet werden. Beitrag [5]
- regSet <reg>
Schreibt in den Register mit der id <reg>. Für die Systemregister kann hierzu statt der RegisterID auch der Registername (siehe regListAll) verwendet werden.
- regSet <reg>.<ep>
write to endpoint <ep> of register <reg>. will not work if no reading for register <reg> is available as all nibbles that are not part of endpoint <ep> will be filled from this reading. ?
- statusRequest
Veranlasst, dass alle Register und deren Werte einmal übertragen werden.
- readDeviceXML
Liest das Device-Description-XML-File neu ein.
- clearUnconfirmed
Löscht die liste der unbestätigten Nachrichten.
- flash [<productCode>|<firmwareFile>]
Initiiert das „over-the-air“ Firmware update, dass (derzeit) nur von NRG panStamps unterstützt wird.
- ohne Parameter: Verwendet das SWAP_<current productCode>.hex-File aus dem Verzeichnis ./FHEM/firmware.
- <productCode>: Verwendet das SWAP_<productCode>.hex-File aus dem Verzeichnis ./FHEM/firmware.
- <firmwareFile>: Verwendet ein <firmwareFile> als absoluten File-Namen des HEX-Files.
get
- regList
Listet alle User-Register des SWAP-Device (Readings).
- regListAll
Listet alle Register des SWAP-Device (Internals und Readings).
- listUnconfirmed
Listet alle unbestätigten Nachrichten in der Warteschlange.
- products
Gibt alle auf dem System bekannten Productcodes nebst Daten aus.
- deviceXML
Gibt die Daten des zum derzeit zum per Attribut (Productcode) eingerichteten Device-XML-Files aus.
Attribute
Wird der Productcode bei der Definition nicht gesetzt, stehen auch nur die Standardbefehle bei zur 2. Modulebene zur Verfügung.
- createUnknownReadings
Erzeug Readings auch für Register, die im Device-XML-File nicht definiert werden.
- ProductCode
Legt den ProductCode eines SWAP-Device fest. Dieses Attribut wird dazu benutzt, die Konfiguration vom Device-XML-File festzulegen. Erst wenn der Produktcode als Attribut vorgegeben wurde, z.B. für einen RGB-Sktech: attr <device> ProductCode 0000002200000003 kommen zu den allgemeinen Kommandos die spezifischen der nächst höheren Modulebene 35_SWAP_<productcode>.pm mit hinzu. Dann werden die SWAP-Nachrichten an das entsprechende Modul weitergegeben und dort verarbeitet.
Für batteriebetriebene Devices, die während der Definition nicht aktiv sind, muss dieses Attribut manuell angelegt werden.
Device Description File
Mit Hilfe der im jeweiligen Device Description File hinterlegten Beschreibung werden hierzu automatisch userReadings angelegt die neben den reinen Registerwerten in hex auch 'menschenlesbare' readings der Sensorwerte erzeugen. Damit dies funktioniert, muss das Attribut ProductCode korrekt gesetzt sein. Das geschieht normalerweise automatisch beim Anlegen des Device.
Hier Beispielhaft anhand eines BMP085 Temperatur- und Luftdrucksensors dargestellt:
attr temppress userReadings voltage:0B-Voltage {hex(ReadingsVal($name,"0B-Voltage","0"))*0.001}, temperature:0C.0-Temperature {hex(ReadingsVal($name,"0C.0-Temperature","0"))*0.1-50}, pressure:0C.1-Pressure {hex(ReadingsVal($name,"0C.1-Pressure","0"))*0.01}, pressureNN:0C.1-Pressure {sprintf("%.2f",hex(ReadingsVal($name,"0C.1-Pressure","0"))*0.01 + AttrVal("global", "altitude", 0)/8.5)}
Aus diesen readings kann dann mit stateFormat die gewünschte Darstellung für die Raumübersicht erzeugt werden:
attr temppress stateFormat {sprintf("%.1f",ReadingsVal($name,"temperature",0))."°C ".sprintf("%.1f",ReadingsVal($name,"pressureNN",0))."mbar"}
Ein weiteres Beispiel ist das Description File für das RGB-Board rgbdriver.xml.