Wie ich dem SmartThings Hub ein neues Gerät hinzugefügt habe, Teil 1

In diesem Artikel möchte ich über meine Erfahrungen bei der Entwicklung des sogenannten Device Handler für SmartThings sprechen. Die Aufgabe bestand darin, ein universelles Gerät hinzuzufügen, das auf dem Z-Wave-Protokoll basiert - Z-Uno - sowie die Verarbeitung der damit verbundenen untergeordneten Geräte.



Die Einführung in die Entwicklung hat mich ziemlich viel Zeit gekostet, aber nachdem ich die meisten Dokumentationen sorgfältig studiert hatte, erforderte die weitere Entwicklung keinen großen Aufwand mehr. Aus diesem Grund wurde beschlossen, diesen Artikel zu schreiben, um die Arbeit des russischsprachigen Benutzers zu erleichtern.

Der gesamte Entwicklungsprozess findet in der SmartThings IDE-Webanwendung in der Sprache GroThy statt. Das Testen ist bequemer von einem mobilen Gerät aus durchzuführen. Es ist jedoch möglich, Gerätesimulatoren in derselben Entwicklungsumgebung zu erstellen. Beim Testen der grafischen Shell muss bereits die mobile Anwendung SmartThings Classic ( Android , iOS ) verwendet werden.

Ein Plug-In-Gerät ist eine Karte, mit der Sie fast jedem Gerät in Z-Wave die Steuerung hinzufügen können. Darüber hinaus können die angeschlossenen Geräte eine andere Nummer haben (bis zu 32 Stück). Dementsprechend müssen auf Softwareebene auch alle Arten verbundener Geräte verarbeitet und die Ausgabe an die Anwendung gesteuert werden.

Liste der verarbeiteten Typen:

• Binär schalten - Geräte mit nur zwei Positionen: Ein / Aus
• Multilevel wechseln - Geräte, die mit unterschiedlichen Bedeutungen ein- oder ausgeschaltet werden können. Zum Beispiel ein Dimer.
• Sensor Multilevel - Sensoren, die nicht-binäre Werte senden. Zum Beispiel ein Temperatursensor.
• Messgerät - Geräte wie ein Zähler
• Benachrichtigung - Binärsensoren werden von diesem Typ sein. Zum Beispiel ein Reed-Schalter.
• Thermostat - eine separate Klasse von Teams, die für die Arbeit mit dem Thermostat verantwortlich sind

Dokumentstruktur

Es können zwei logische Blöcke unterschieden werden:

• Beschreibung und Metainformationen zum Handler. Dies beinhaltet Informationen über das Gerät, wie die Benutzeroberfläche und andere Informationen gezeichnet werden sollen. Es wird nach der Methode metadata() zugewiesen.
  
  
  
• Handler-Methoden sind Handler-Logik. Sie sind für die „Kommunikation“ mit dem Gerät verantwortlich.
  
  Separat können wir die parse () -Methode unterscheiden, die die vom Gerät empfangenen Befehle interpretiert.

Ich werde den Zweck und den Inhalt jedes Blocks während der Artikelserie genauer beschreiben.

Metadaten

Wie Sie dem Namen der Methode entnehmen können, enthält diese Metainformationen.

Betrachten wir in der Reihenfolge, was in diesem Block enthalten ist:

Definition ()

Bei dieser Methode geben Argumente jeweils drei Dinge an: den Namen des Handlers, den Namespace und den Namen des Autors.

• Der Name des Handlers wird zukünftig beim Veröffentlichen und beim Erstellen von untergeordneten Geräten verwendet.
• Der Namespace wird bei der Suche nach Handlern nach Namen verwendet, um sicherzustellen, dass der richtige gefunden wird, z. B. unter Handlern mit demselben Namen. SmartThings empfiehlt, Ihren Spitznamen auf github zu verwenden.
• Der Name des Autors wird mit Ihrem Namen ausgefüllt.

  definition(name: "Your device", namespace: "yournamespace", author: "your name") {} 

Die folgenden Variablen können im Hauptteil der Methode deklariert werden: attribute, capability, command, fingerprint . Weiter werden wir genauer betrachten, was es ist und wann es angewendet wird.

Verbindung und Fingerabdruck

Wir verbinden unser Gerät. In unserem Fall werden SmartThings V2 Hub und Z-Uno verwendet.

Beim Hinzufügen eines neuen Z-Wave- oder ZigBee-Geräts versucht der Hub zu erkennen, mit welchem ​​Gerätetyp eine Verbindung hergestellt werden soll, und sucht nach dem relevantesten Handler. Er wird es durch "Fingerabdrücke" auswählen. Wenn der Hub in den benutzerdefinierten Handlern keine Übereinstimmungen findet, versucht er, eine der nächstgelegenen Standardvorlagen zu verwenden.

Im Handler selbst werden „Fingerabdrücke“ festgelegt, um anzugeben, welche Arten von Geräten unterstützt werden. Die offizielle Dokumentation besagt, dass sie für Z-Wave-Geräte und ZigBee-Geräte unterschiedlich sein werden. Wir werden die Implementierung für Z-Wave in Betracht ziehen.

Z-Wave-Protokollgeräte speichern Informationen über Hersteller, Gerätetyp, Funktionen usw. Während des sogenannten „Interviews“ mit dem Gerät sammelt ST diese Informationen in der Z-Wave-Rohbeschreibung. Ein Beispiel für eine solche Zeile:

 zw:Ss type:2101 mfr:0086 prod:0102 model:0064 ver:1.04 zwv:4.05 lib:03 cc:5E,86,72,98,84 ccOut:5A sec:59,85,73,71,80,30,31,70,7A role:06 ff:8C07 ui:8C07 

Der Wert jedes Schlüssels wird verwendet, um den „Fingerabdruck“ auszufüllen. Eine detaillierte Beschreibung der einzelnen Artikel finden Sie hier . Wir werden diejenigen berücksichtigen, die in unserem Handler verwendet werden.

Um diese Zeile mit Informationen zu finden, müssen Sie auf die Registerkarte "Meine Geräte" klicken und auf das Gerät klicken, an dem wir interessiert sind (vorher muss das Gerät dem Netzwerk hinzugefügt werden).



mfr ist ein 16-Bit-Wert, der die Hersteller-ID enthält. Eine Liste der Hersteller und ihrer IDs finden Sie hier .

prod - ein 16-Bit-Wert, der die Produkttyp-ID enthält - eine eindeutige Gerätetyp-ID.

Modell ist ein 16-Bit-Wert, der die Produkt-ID enthält.

inClusters - Ein 8-Bit-Wert, der die Notwendigkeit einer bestimmten Befehlsklasse festlegt. Wenn wir beispielsweise angeben müssen, dass unser Handler mit MultiChannel CC funktioniert, müssen Sie den Code 0x60 schreiben. Die Liste der für SmartThings CC verfügbaren Geräte finden Sie hier .

Diese vier Schlüssel reichen aus, damit der Hub genau versteht, zu welchem ​​Gerät dieser Handler gehört. Ein Beispiel, wie sie bei mir verwendet werden:

 fingerprint mfr: "0115", prod: "0110", model: "0001", inClusters: "0x60" fingerprint mfr: "0115", prod: "0111", inClusters: "0x60" 

Ein Gerät kann eine größere Anzahl von Parametern haben. In diesem Fall kann es erfolgreich eine Verbindung zu diesem Handler herstellen. Wenn jedoch mindestens einer von ihnen nicht mit dem deklarierten Fingerabdruck übereinstimmt, ignoriert das Gerät diesen Handler.

Smartthings empfiehlt, Informationen über den Hersteller (Hersteller) und das Modell (Produkt, Modell) in den Fingerabdruck aufzunehmen, um Fälle auszuschließen, in denen die Wahl eines Handlers nicht offensichtlich ist. Zum Beispiel, wenn Fingerabdrücke einer der standardmäßig verwendeten Vorlagen oder Beispiele mit Ihren übereinstimmen.

Position im Code

 metadata { definition(...) { ... fingerprint mfr: "0115", prod: "0110", model: "0001", inClusters: "0x60" fingerprint mfr: "0115", prod: "0111", inClusters: "0x60" } ... } 

Bis zur Veröffentlichung ist ein vollständiger Artikelzyklus geplant. Ich hoffe, diese Informationen helfen Ihnen bei der Entwicklung.