PanStamp

PanStamp
panStamp
Allgemein
Protokoll	SWAP
Typ	Sender, Empfänger, Sensor, Interface
Kategorie
Technische Details
Kommunikation	868MHz (433/915MHz)
Kanäle
Betriebsspannung	3.3V (panStick: 5V USB)
Leistungsaufnahme
Versorgung	Battery (panStick: USB)
Abmessungen	17.7 x 30.5 mm
Sonstiges
Modulname	34_panStamp.pm 34_SWAP.pm 35_SWAP_0000002200000003.pm
Ersteller	Andre / justme1968
Hersteller	panStamp

Dieser Artikel, gedacht als Eingangsartikel zu dem Thema, beschreibt die Zusammenhänge rund um die Hardwaremodule „panStamp“.

Zur Hardware gibt es herstellerseitig eine eigenen Community mit Forum und Wiki, sowie Downloads auf Github.

panStamps sind Arduino Clones, die ein CC1101 Funkmodul beinhalten. Mit ihnen lassen sich Sensoren und Aktoren drahtlos an FHEM anbinden. Sie lassen sich genau wie Arduinos über die Arduino IDE oder mit dem ino Kommandozeilen Binary programmieren.

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

Zur Kommunikation in einem panStamp Netzwerk dient das Simple Wireless Abstract Protocol (SWAP).

Allgemein

Grundsätzlich gehören zur Integration in FHEM das FHEM Modul panStamp-Modul, das FHEM Modul SWAP und je nach Anwendung ein spezifisches FHEM Modul SWAP_XXXXXXXXXXXXXXXX mit entsprechenden Device Definition Files. Details über das Zusammenspiel sind in der Systemübersicht weiter unten beschrieben.

Darüber hinaus muss ein passender [#panStamp Sketches|Sketch]] (wie eine Firmware) auf die Hardwaremodule geladen werden vergleichbar mit der Firmware für einen CUL. Der Sketch bestimmt die Funktion und ist damit abhängig von der Anwendung. Teilweise findet man fertig kompilierte Sketches. Man kann sich aber auch den Sourcecode herunterladen, den eigenen Bedürfnissen anpassen oder gleich einen eigenen Sketch programmieren. Der Sketch wird dann innerhalb einer passenden Entwicklungsumgebung kompilieren und anschießend auf den panStamp hochladen.

Für die Einrichtung (Device Definition) innerhalb von FHEM wird für die Serverseite das IO-Device definiert, für die Seite der Aktuatoren/Sensoren das entsprechende Device.

Eine Übersicht über alle sich mit dem Thema panStamp befassenden Artikel befindet sich hier.

Systemübersicht

panStamp Systemübersicht

Zum besseren Verständnis der Begrifflichkeiten und Zusammenhänge ist hier eine Systemübersicht dargestellt. Die Kommunikationskette ist wie folgt:

FHEM -> Server Hardware -> USB -> panStick -> panStamp (mit Modem-Sketch) -> Funkstrecke (per SWAP-Protokoll) -> panStamp (angepasster Sketch) -> Board -> Sensoren/LED-Strip/etc.

(Ein panShield ersetzt "USB -> PanStick" durch "IO's am Rpi -> panShield").

Zum Betrieb werden mindestens 2 panStamp Hardware-Module benötigt, das panStamp FHEM-Modul als IO-Device für FHEM und das FHEM-Modul SWAP zur Integration des Funkprotokolls der panStamps.

Optional kann es noch weitere Module geben als 3. Ebene, die nach dem Schema SWAP_XXXXXXXXXXXXXXXX.pm benannt sind. Besonders bei Aktoren ist oft eine engere FHEM-Integration sinnvoll, um FHEM Konzepte wie on/off/on-for-timer direkt abzubilden und nicht mehr nur auf die SWAP Registerebene und regSet und regGet Kommandos beschränkt zu sein. Um per autocreate automatisch das passende Modul laden zu können, müssen diese Module nach dem Schema SWAP_XXXXXXXXXXXXXXXX.pm benannt sein wobei XXXXXXXXXXXXXXXX für den jeweiligen ProductCode steht.

panStamp Hardware

Die Beschreibung in folgenden bezieht sich vornehmlich auf die Hardwaremodule der Generation 1 und 1.1, sowie panStick 1.1, 1.2, die derzeit (Mitte 2016) beim Hersteller nicht mehr erworben werden können.

panStick/Shield

Als Schnittstelle zwischen FHEM Server-Hardware und dem Funkprotokoll dient entweder ein panStick mit aufgestecktem panStamp-Hardwaremodul und Modem-Sketch (USB Stick mit Sockel zum Aufstecken eines panStamp) oder ein panShield (mit integriertem panStamp und RTC) an einem Raspberry Pi.

panStick

Der panStick stellt die Verbindung zwischen dem USB-Port auf der einen Seite und dem seriellen Interface der panStamp-Hardware auf der anderen Seite dar. Der panStick wird grundsätzlich für zwei Aufgaben benötigt:

1. Zur Vorbereitung einer panStamp-Hardware für den Betrieb auf einem Board wird die neue panStamp-Hardware in den panStick gesteckt, um die Programmierung (flashen des Sketch) vorzunehmen.
2. Im "normalen" Betrieb steckt eine panStamp-Hardware auf dem panStick. Der so angebundene panStamp wird mit einem (bei Auslieferung des panStamps vorinstallierten) Modem-Sketch als RF-Modem verwendet und dient so der FHEM Server-Hardware als Interface zu anderen panStamp-Hardwaremodulen, zu denen über eine Funkstrecke mittels des SWAP-Protokolls kommuniziert wird. Der panStick kann auch per USB an einer anderen Serverhardware angebunden werden. Die Kommunikation zu FHEM erfolgt dann z.B. über ser2net oder FHEM2FHEM über LAN.

An dieser Stelle sei darauf hingewiesen, dass umgangssprachlich im Forum häufig von panStick die Rede ist, damit aber die Definition des IO-Devices innerhalb von FHEM gemeint ist. Auch kann darunter die Kombination aus panStick, aufgesteckten panStamp und darauf befindlichem Model-Sketch gemeint sein, was gesamt dann als Funk-Interface dient. Ein panStick ohne panStamp-Hardware ist ziemlich nutzlos für die Funktion. Mit panStick ist hier also die reine Hardware als Interface zwischen USB-Port und panStamp gemeint.

panShield

Ein panShield übernimmt die gleiche Funktion wie ein panStick mit aufgestecktem panStamp, wird aber direkt an die IOs eines Raspberries angeschlossen. Da auf dem panShield der panStamp fest eingelötet ist, übernimmt dieser in der Regel nur die Funktion des IO-Interfaces wie für den panStick der "normale" Betrieb oben beschrieben.

Der Einfachheit halber wird im Folgenden nicht mehr auf den panShield im Speziellen eingegangen, da es keinen funktionalen Unterschied zur Kombination aus panStick und panStamp gibt.

panStamp

Die panStamps bilden das zentrale Glied und sind wie eingangs bereits beschrieben Arduino Clones mit einem CC1101 Funkmodul. Mit eine passenden Firmware (Sketch) ausgestattet, stecken sie entweder auf dem panStick oder den entsprechenden Boards/Platinen.

Um einen panStamp in Betrieb zu nehmen muss er unbedingt mit einer Antenne oder einem Stück Draht in der richtigen Länge bestückt sein. Ohne Antenne funktioniert die Übertragung nicht, auch nicht auf kurze Distanzen!

Um die Verwirrung der Namensgebung komplett zu machen, wird im Forum häufig vom "panStamps" als Device gesprochen, obwohl es eigentlich als SWAP-Devices definiert wird.

Mit der Einführung der 2. Generation (AVR2, NRG2) hat sich das Footprint der Module stark verändert. Adapterplatinen, um die Module mit neuem Footprint in Hardware mit altem zu integrieren, konnten auf Anfrage bei Daniel im Shop noch geordert werden (Stand Ende 2015; Forum, Forum). Langfristig ist davon auszugehen, dass diese nicht dauerhaft werden lieferbar sein. Von der Programmierung unterscheiden sich die Module jedoch nicht.

spezifisches "Board"

Im Gegenzug zum panStick, als Hardware-Interface zwischen panStamp und USB-Port des Servers, stellt das spezifische Board das Hardware-Interface zwischen panStamp-Hardware und Input/Outputs (analog/digital) dar. Das "Board" nimmt den panStamp mit dem passenden Sketch auf und setzt die Outputs der panStamp-Hardware auf die Steuerausgänge des Boards um bzw. leitet die Steuereingänge des Boards zur Auswertung an den panStamp Input weiter. Mit panStamp Input und Output sind in diesem Fall die Pins der CPU gemeint. Entsprechend Anwendungsfall und Sketch werden die Steuereingänge und Steuerausgänge des panStamps verarbeitet. Z.B. können an ein Board Temperatur-, Feuchtigkeitssensoren oder LED-Strips angeschlossen werden. Der Sketch auf dem panStamp sollte entsprechend der Anwendung auf dem Board angepasst worden sein um nicht nur über die standardmäßig zur Verfügung stehenden Register kommunizieren zu müssen.

Das Board benötigt irgendeine Art von Stromversorgung, um den panStamp zu betreiben. Das kann im Falle eines Sensorboards und entsprechend stromsparend ausgelegtem Sketch eine Batterie sein oder wie im Falle des panStamp RGBWW Board mit DMX und IR eine externe Stromversorgung. Speziell beim diesem Board kann die Stromversorgung sogar separat für panStamp und LEDs ausgeführt sein oder insgesamt panStamp und LEDs gemeinsam versorgen.

panStamp Sketch

Modem-Sketch

Der Modem-Sketch stellt das Software-Verbindungsglied zwischen panStamp und dem SWAP-Funkprotokoll dar. Das SWAP-Protokoll wird über ein serielles Protokoll dem FHEM-Server zur Verfügung gestellt. Die Verarbeitung des SWAP-Protokolls übernimmt das gleichnamige FHEM-Modul SWAP. Auf jedem panStamp (AVR, bei NRG unbekannt) ist im Auslieferungszustand der Modem-Sketch installiert. Der panStick besitzt ebenfalls eine SWAP-ID, also eine fest zugeordnete Adresse. Das ist immer die Adresse 0x01.

Ein NRG panStamp lässt sich als Modem verwenden, wenn man den Schalter auf dem panStick auf AVR stellt (Forum).

auf Board abgestimmter Sketch

Ein panStamp ist auf einem entsprechenden Board installiert und übernimmt dort lokal die Schnittstelle zwischen Funkstrecke und Board. Der Sketch stellt dabei die passende "Software" auf dem panStamp-Hardwaremodul. Der Sketch verarbeitet die über das SWAP-Protokoll versandten Nachrichten, wertet diese aus, reagiert entsprechend und setzt die Outputs des Boards. In umgekehrter Richtung wertet er die an den Inputs des Board angelegten Signale aus, verarbeitet diese und schickt sie per SWAP-Protokoll zum panStamp mit Modem-Sketch zurück.

Die Kompatibilität der bestehenden Sketches hängt stark vom Typ des panStamps und von der Entwicklungsumgebung ab. D.h. die neuesten panStamps (NRG) sind mit den neuesten Umgebungen Arduino 1.6x und unabhängig davon mit den alten Sketches meistens nicht kompatibel.

FHEM-Module/Device Definition Files

Wie eingangs erwähnt erfolgt die Integration in FHEM erfolgt über eine Reihe von Modulen die im Folgenden genauer beschrieben werden. Zusammengefasst gibt es 3 Ebenen mit der Ergänzung eines Konfigurationsfiles in XML-Format. Beitrag

Ebene 1: 34_panStamp.pm

Das Modul ist dazu da, Nachrichten aus dem Funknetzwerk, die von einem panStamp mit Modem-Sketch auf einem panStick emfangen werden, FHEM zur Verfügung zu stellen und umgekehrt. Alle eintreffenden SWAP-Pakete werden direkt an FHEM durchgereicht und im SWAP-Modul verarbeitet.

Im moduleigenen Artikel ist die Einrichtung des IO-Devices innerhalb von FHEM beschrieben.

Ebene 2: 34_SWAP.pm

Das Modul implementiert das SWAP Protokoll das zwischen den panStamps gesprochen wird. Darüber werden die auf den entsprechenden Boards/Platinen steckenden panStamp innerhalb von FHEM als TYPE SWAP_<ProductCode> definiert.

Das FHEM-Modul SWAP ermöglicht die generische Integration beliebiger panStamp Sensoren und Aktoren in FHEM, und ist in einem eigenen Artikel SWAP erklärt. Für diese werden hier die allgemeinen Grundfunktionen beschrieben, die bei jedem SWAP-Device funktionieren. Die spezifischen Kommandos und Attribute, die durch die 3. Modulebene in Abhängigkeit des ProductCode zur Verfügung stehen, werden in den Wiki-Artikeln der jeweiligen Module beschrieben.

Um die Verwirrung komplett zu machen, wird im Forum meistens von "panStamps" gesprochen, obwohl es eigentlich SWAP-Devices sind.

Ebene 3: SWAP_XXXXXXXXXXXXXXXX.pm

RGB LED Driver Board

Besonders bei Aktoren ist oft eine engere FHEM-Integration sinnvoll, um FHEM Konzepte wie on/off/on-for-timer direkt abzubilden und nicht mehr nur auf die Registerebene und regSet und regGet Kommandos beschränkt zu sein. Mit dieser dritten Modulebene ist es auch für Aktoren wie Schalter/Dimmer/... sehr einfach, diese in FHEM zu integrieren.

Wenn die Namenskonvention SWAP_<ProductCode> für diese Module eingehalten wird, funktioniert auch das autocreate sofern das Modul in FHEM bekannt ist.

Um per autocreate automatisch das passende Modul laden zu können, müssen diese Module nach dem Schema SWAP_XXXXXXXXXXXXXXXX.pm benannt sein wobei XXXXXXXXXXXXXXXX für den jeweiligen ProductCode steht. Ein Beispiel für das RGB-Board dafür ist das Modul 35_SWAP_0000002200000003.pm.

Device Definition Files

Ein XML File was die Ein- und Ausgänge der panStamps beschreibt. Durch diese Datei wird dem FHEM-Modul mitgeteilt wie die Readings zu bennenen sind, welche Werte die Readings haben können und ob die Readings/Register nur ausgelesen werden dürfen, oder auch beschrieben werden können. Im Wiki des Herstellers ist der Aufbau des Device Definition Files beschrieben. Wenn für einen End Point eine Unit angegeben ist, mit entsprechendem Faktor, dann erstellt das SWAP-Modul automatisch ein passendes userReadings mit der angegebenen Umrechnung.

panStamps konfigurieren und in Betrieb nehmen

Die Inbetriebnahme ist grundsätzlich in die Einrichtung des IO-Devices und die Einrichtung des entfernten Hardwaremoduls (Sensor/Aktuator) zu unterscheiden.

Auf die Einrichtung des IO-Devices ist hier bereits verwiesen.

Für die Einrichtung des entfernten Hardwaremoduls müssen im groben folgende Schritte erfolgen:

1. Vorbereiten einer Entwicklungsumgebung, kompilieren und hochladen der Firmware
2. Aufstecken des programmierten panStamps auf das Board
3. Mit Strom versorgen und von Autocreate einrichten lassen
4. Attribute, Namen, Userreading des neuen SWAP-Device nach Bedarf anpassen

während der Einrichtung zu berücksichtigen

Info: Das SWAP Modul unterstützt autocreate. Bei der Inbetriebnahme ist autocreate zu aktivieren!

Neue panStamps sollten nur Einer nach dem Anderen in Betrieb genommen werden, da sie zuerst mit einer eindeutigen Device-Adresse (ungleich FF und grösser 01) versehen werden müssen. Bei batteriebetriebenen Sensoren sollte auch das Sendeintervall auf einen sinnvollen Wert gesetzt werden:

set <device> regSet 09 <device adresse als 2 stellige hex zahl>
set <device> regSet 0A <intervall in Sekunden als 4 stellige hex zahl>

Für panStamp-Hardware im Power-Down-Modus werden diese Kommandos in eine Warteschlange gestellt und übertragen, sobald die panStamp-Hardware seine Initialisierungssequenz durchläuft. Hierzu ist nach Absetzen der Kommandos aus FHEM die Reset-Taste an der panStamp-Hardware zu drücken oder die Stromquelle erneut zu verbinden.

Das SWAP-Modul versucht, panStamp-Hardware mit der Default Adresse FF automatisch auf die erste freie Adresse im Bereich F0-FE zu ändern. Automatisch gesetzte Werte sollten danach manuell auf die jeweilige Installation angepasst werden. Für batteriebetriebene panStamp-Hardware (genauer: Hardware die den Power-Down-Modus unterstützen) wird das Default Sendeintervall von FFFF zu 0384 (900 Sekunden) geändert. Es gibt mit bestimmten panStamp lib Versionen das Problem das ein Wert von FFFF in Systemregister 0A zum Überlauf führt und dann ununterbrochen SWAP Nachrichten gesendet werden. Im FHEM Modul wird versucht das abzufangen. Das funktioniert auf manchen langsamen Host-Systemen (z.B. FritzBox) nicht, weil der panStamp so schnell sendet, dass FHEM so mit dem Abarbeiten beschäftigt ist, dass es selber nicht zum Senden kommt. Zur Abhilfe kann im Sketch in setup() ganz am Anfang ein

 EEPROM.write(EEPROM_TX_INTERVAL, 0x55);
 EEPROM.write(EEPROM_TX_INTERVAL+1, 0x55);

eingefügt werden. Der Sketch ist dann zu flashen und wenn der Sketch einmal durchgelaufen ist, können diese beiden Zeilen wieder entfernen werden und der panStamp muss noch mal geflasht werden. Ansonsten wird die Adresse bei jedem Start erneut auf 5555 gesetzt.

Beispiel für Kurzentschlossene anhand der Einrichtung für das RGB-Board

• Ein panStamp-Hardwaremodul wird in einen panStick gesteckt und der panStick für die Programmierung z.B. unter Windows installiert. Selbstverständlich kann ein panStamp-Hardwaremodul auch über diverse andere Möglichkeiten und unter diversen anderen Betriebssystemen und über diverse andere Schnittstellen programmiert werden.
• Arduino IDE vorbereiten (libs hinzufügen, Board auswählen, etc.).
• Ein Sketch wird in der Arduino IDE entsprechend konfiguriert, kompiliert und auf dem panStamp-Hardwaremodul hochgeladen.
• Das programmierte panStamp-Hardwaremodul, aus dem panStick, in das panStamp_RGBWW_Board stecken.
• Ein panStamp-Hardwaremodul mit Modem-Sketch in den panStick stecken und an den FHEM-Host stecken.
• IO-Device unter FHEM einrichten, wenn nicht durch autocreate automatisch geschehen.
• panStamp_RGBWW_Board mit Strom versorgen und ggf. einmal Reset-Knopf drücken. Dann sollte, falls autocreate aktiv ist, das SWAP-Device automatisch eingerichtet werden.
• SWAP-Device in FHEM an Gegebenheiten anpassen.

Anwendungsbeispiele

Es gibt bereits selbst entwickelte Hardware und Software auf Basis der panStamp Hardware und dem SWAP Protokoll:

• panStamp Umweltsensor
• Bodenfeuchtesensor
• panStamp Innenraumsensor
• panStamp RGBWW Board mit DMX und IR
• Lithium Battery Charging Board für den panStamp AVR2 [1]

Bekannte Probleme

• Beim Systemstart werden einige Perl-Warnings ins Log geschrieben, die aber die Funktion der Module nicht beeinträchtigen.

• Beim Systemstart wird eine SWAP-Broadcast Nachricht verschickt, die von allen empfangsbereiten panStamps beantwortet wird. Dieses führt bei häufig schnell bei kurz aufeinanderfolgenden Systemstarts zur Überschreitung des Transmit Limits im Rahmen der 1%-Regel für das verwendete Frequenzband.

Weitere Troubleshooting Hinweise finden sich hier

Weblinks

• panStamp panStamp Hersteller