Blue Flower

Einleitung
Ein (mehr oder weniger) fertiger Garten sollte um eine 20m-Hecke erweitert werden.
Um sicherzustellen, dass diese Hecke auch ordentlich anwächst, musste eine Bewässerungslösung her, die schnell, einfach und möglichst kostengünstig und ohne größere Umbauarbeiten im Garten zu installieren sei.
Ein Stromanschluss war nicht gegeben und müsste durch umfangreiche Grabungen erst verlegt werden. Die Hausherrin mochte jedoch keine Gräben im frischen Rasen sehen!
Und von mir aus sollte sich natürlich diese Bewässerungslösung auch in die bestehende Hausautomatisierung (KNX + Visu Loxone) einbinden lassen.

Nach langer Recherche fand ich dann das MIYO-Bewässerungssystem der Firma viRaTec, das mit Solarenergie bestromt wird und eine API zur Verfügung stellt, um auch OHNE Cloud LOKAL darauf zugreifen zu können.
Und tatsächlich ist die API nutzbar! Resultat ist dieses Plugin zur Anbindung an verschiedene Systeme. Hier läuft es jetzt seit einigen Wochen im Verbund mit einem Loxone-Miniserver auf einem Raspi mit LoxBerry.

Haftungsausschluss
Gern teile ich dieses Plugin mit Euch, möchte aber explizit darauf hinweisen, dass ich keine Gewährleistung für nichts was mit dem Einsatz dieser Software verbunden ist, geben kann.
Ich muss auch mitteilen, das ich weder mit Loxone noch mit viRaTec in irgendeinem anderen Verhältnis stehe, als als normaler Nutzer und Kunde. Weder ich als Autor dieses Plugins noch Loxone oder viRaTec sind für etwaige Fehlfunktionen durch Einsatz dieses Plugins haftbar zu machen. Fragen zum Plugin sind vermutlich bei mir hier besser aufgehoben als bei den Geräteherstellern.

Grundlagen
Das MIYO-System besteht aus einer Zentrale (dem Cube), die per LAN-Kabel an das lokale Netzwerk angebunden wird und per Funk im 868MHz-Bereich mit den im Garten verteilten Geräten wie Ventilen und Sensoren kommuniziert.

Wie bei anderen Bewässerungssystemen erfolgt die Zuordnung von Ventilen zu Bewässerungskreisen. Wobei bei MIYO auch mehrere Ventile pro Kreis möglich sind. Diese können gleichzeitig aber auch automatisch nacheinander geöffnet werden, um mit einem evtl. nicht ausreichendem Wasserdruck arbeiten zu können.

Ein Sensor innerhalb eines Bewässerungskreises ist optional aber auch sehr hilfreich.
Anhand der lokalen Sensordaten (Temperatur, Bodenfeuchtigkeit und Helligkeit) und über per Internet am Cube eingehende Wetterdaten erfolgt dann eine Bewässerung in über die MIYO-App konfigurierbaren Zeitplänen.
Meldet der Sensor das der Boden bereits feucht genug ist oder liegt eine Regen-Vorhersage vor, erfolgt keine Bewässerung.

Der Vorteil der Plugin-Lösung
Ich persönlich mag EINE zentrale Visualisierung aller Zustände im Haus. Verschiedene Apps für verschiedene Geräte oder Gewerke sind mir ein Graus. Und die Geräte auch unterschiedlicher Systeme sollten interagieren können.
Außerdem war mir bei Kauf der Komponenten nicht klar, ob die automatische Steuerung durch den Cube tatsächlich so funktioniert, wie ich mir das vorstellte.
Mit dem Plugin können eigene Zeitpläne und erweiterte Bedingungen für die Bewässerung konfiguriert werden. So sind etwa auch andere Bodenfeuchtesensoren nutzbar oder eine Bewässerung lässt sich automatisch unterbrechen, wenn der Rasenmähroboter arbeitet oder der lokale Regensensor oder Bewegungsmelder Alarm schlägt. In Kombination mit anderen Plugins - etwa HA-Bridge - sollte sogar eine Sprachsteuerung mit Alexa möglich sein.
Schließlich gibt mir die Plugin-Lösung eine gewisse Sicherheit, dass die Komponenten trotz evtl. fehlender Internetverbindung oder fehlender Cloud-Anbindung oder defekter App oder weil der Akku des Smartphones gerade leer ist - weiter nutz- und steuerbar sind.

Um eine große Plattformunabhängigkeit zu erreichen, erfolgt die Kommunikation vom und zum Zielsystem per UDP. 
Das Plugin baut eine Websocket-Verbindung zum Cube auf und und verschickt vom Cube eingehende Daten per UDP an einen konfigurierbaren Port in einem festgelegten Format, das durch Parsen vom Zielsystem umgesetzt werden kann. Loxone hat dafür eine eigene Befehlserkennung.

Nachrichten für den Cube werden vom MIYOplugin per UDP empfangen und über die bestehende Websocket-Schnittstelle zum Cube durchgereicht.

Als Zielsystem kommen somit neben Loxone alle Smarthome-Systeme in Frage, die UDP reden können (Edomi, HS4, EIBport, smarthome.py, FHEM, OpenHAB, IP-Symcon, Homematic, vermutlich auch WireGate, Timberwolf usw.).
Nötig ist in jedem Fall ein Python-fähiger Rechner (etwa ein Raspi) auf dem das Plugin als Wandler zwischen Websocket und UDP läuft.

Speziell als Loxone-Optimierung erfolgt eine Umrechnung der Zeit (Loxone rechnet Sekunden nicht ab 1970 sondern ab 2009 und nutzt local time statt UTC) und eine Minimierung der zur Weiterverarbeitung nötigen Schritte (etwa 1 statt true oder Benennung der Geräte mit sprechenden Namen statt IDs).

MIYO-Visualisierung mit Loxone

Über die MIYO-App getätigte Eingaben und Änderungen sind sofort auch im Hausautomatisierungssystem sichtbar. Auch in der anderen Richtung lassen sich MIYO-App und Visualisierung wunderbar parallel betreiben. Man sieht also den aktuellen Status in beiden Systemen und kann die Bewässerungskreise ebenso wechselweise steuern.

allgemeine Installation
Grundsätzlich sollte das komplette MIYO-System zuerst über die MIYO-App des Herstellers eingelernt und konfiguriert werden:

  1. App aus dem jeweiligen Shop holen (siehe Links)
  2. Cube mit LAN und Strom versorgen
  3. MIYO-App starten und den Anweisungen dort folgen
  4. entsprechend der Anweisungen in der App die Geräte per Magneten anlernen

Wenn soweit über die App alles funktioniert, kann die Anbindung an das jeweilige Hausautomatisierungssystem erfolgen.

Achtung!
Aktuell bitte auf Umlaute, Leerzeichen und Sonderzeichen in den Bereichsnamen verzichten! Sonst kann es zu Problemen bei der Konfiguration des Loxberry-Plugins kommen. Ich schau mir das demnächst an.

Installation & Konfiguration für LoxBerry
Nutzer, die bereits eine LoxBerry-Installation ihr Eigen nennen haben es hier leicht:
Im Hauptbildschirm des LoxBerry ist auf Plugin-Verwaltung zu klicken und der Link des loxberry-MIYOplugin.zip unter "Installiere neues Plugin:" sowie die SecurePIN einzugeben und auf Installation klicken:

LoxBerry: MIYOplugin installieren

Nach erfolgreicher Installation steht das MIYOplugin unter Plugins in der Hauptübersicht zur weiteren Konfiguration und Aktivierung bereit.

Auf der Einstellungsseite müssen verschiedene Einstellungen vorgenommen werden, damit das Config-File mit den passenden Werten befüllt wird:

MIYOplugin - LoxBerry-Settings

Zu jedem Eingabefeld kann eine Kurzinformation per MouseOver über das Fragezeichen angezeigt werden. Eine weitere Hilfe-Möglichkeit findet sich über den Button mit dem i in der rechten oberen Ecke.

Ist die IP-Adresse des MIYO-Cube bekannt, bitte im entsprechenden Feld eintragen. Mit einem Klick auf Erkenne Cube kann ein einzelner Cube jedoch auch im Netzwerk gesucht werden. Die IP-Adresse des Loxone-Miniservers sollte bereits durch die LoxBerry-Grundinstallation voreingestellt und bei Loxone-Wahl auswählbar sein. Die UDP-Ports müssen exklusiv für das Plugin zur Verfügung stehen. Der UDP-Port des LoxBerry (LB_PORT) darf also nicht bereits anderweitig auf dem LoxBerry-Rechner gebunden sein wie auch der UDP-Port des Zielsystems (LOX_PORT) am Loxone-Miniserver nicht bereits genutzt werden kann. Für den LoxBerry-Port gibt es einen Button Prüfe Port, der den aktuell eingestellten Port auf Verfügbarkeit prüft. Sollte der Port bereits anderweitig genutzt werden, erfolgt ein Reset des Ports auf 0. Dann bitte einen anderen Port eintragen, der nicht bereits von anderen Anwendungen genutzt wird.

Die Log-Dateien sind optional. Für eine bessere Übersichtlichkeit gibt es drei separate Log-Dateien mit unterschiedlichen Inhalten. Im UDP-Sende-Log (logfile) werden alle UDP-Nachrichten protokolliert, die an den Loxone-Server geschickt werden. Das Cube-Empfangs-Log (rawfile) enthält alle Websocket-Nachrichten vom MIYO-Cube und im UDP-Empfangs-Log (sndfile) werden alle Nachrichten vom Loxone-Server, die an den Cube gerichtet sind, abgespeichert. Über die jeweils daneben befindlichen Buttons anzeigen lassen sich die Log-Dateien ansehen und abspeichern.

Um einen API-Key generieren zu können, ist wenigstens die Angabe der IP-Adresse des MIYO-Cube nötig. Um den bestehenden API-Key nicht versehentlich zu überschreiben, erfolgt eine weitere Abfrage über eine Confirm-Meldung im Browser.

Das weitere Vorgehen:
- Knopf am MIYO-Cube drücken
- Button hole API-Key klicken

Diese Reihenfolge ist wichtig! Nur, wenn zuerst der Knopf am Cube gedrückt wurde, liefert der Cube auch einen API-Key auf Anforderung des Plugins durch den entsprechenden Button. Wurde der Knopf vergessen zu drücken oder ist der Authentifizierungszeitraum von 15 Minuten nach Knopfdruck überschritten, liefert der Cube stattdessen die Fehlermeldung "Link mode not activated". In diesem Fall bitte erneut zuerst den Knopf am MIYO-Cube und dann den Button hole API-Key auf der Konfigurationsseite des MIYOplugin drücken. Es können beliebig viele API-Keys vom Cube erzeugt werden - nur muss man eben in der Nähe des Cubes sein, um dessen Knopf zu drücken.

Die Konfiguration des MIYO-Cube - also die bestehenden Bewässerungskreise, Ventile und Sensoren - werden mit einem gültigen API-Key nach Klick auf CubeConf automatisch eingelesen und zur weiteren Bearbeitung zur Verfügung gestellt. Die Loxone-Namen für die virtuellen In- und Outputs werden automatisch benannt, können jedoch geändert werden. Wichtig dabei: die Namen sollten eineindeutig sein und Sonder- und Leerzeichen sowie Umlaute sollten unbedingt vermieden werden. Dies vereinfacht die Befehlserkennung innerhalb Loxone ungemein.
Zur leichteren Identifizierung der einzelnen Geräte erfolgt die Benennung entsprechend der Namensgebung in der MIYO-App. Ventile und Sensoren werden dort unter Einstellungen/Sensoren & Ventile mit einer eindeutigen ID angezeigt, die sich als Tooltip auch auf der Plugin-Seite beim MouseOver über dem jeweiligen Fragezeichen wiederfindet. Auch hier: um nicht versehentlich die vorhandene Konfiguration zu überschreiben erfolgt vorher nochmals eine Abfrage, ob die vorhandene Konfiguration des Plugins überschrieben werden soll.

MIYOplugin - LoxBerry-Settings CubeConf

Auf einen Blick kann man hier die komplette Konfigurationsseite als Popup betrachten. Ein kleines Video das den Ablauf der Konfiguration im LoxBerry sowie den Download der Vorlagendatei zeigt, ist hier zu sehen.

Ein Klick auf Speichern speichert die Konfiguration in der Config-Datei. Somit ist die Installation und Konfiguration für das MIYOplugin abgeschlossen.

Mit dem Button Vorlage erfolgt der Download einer Loxone-Vorlagendatei MIYOplugin-in-out.xml, um nicht alle virtuellen Ein- und Ausgänge händisch eintragen zu müssen. Diese Vorlage beinhaltet eine Vielzahl von bereits konfigurierten Ein- und Ausgängen auf Grundlage der hier getätigten Eingaben:

virtuelle (analoge) UDP-Eingangsverbinder UDP-Ausgangsverbinder

MIYO-running (ist Plugin gestartet)
MIYO-updated
MIYO-forecast (Sperre wg. Wettervorhersage)
MIYO-temperature (Temperatur lt. Wettervorhersage)
MIYOcircuit-1-irrigationNextStart
MIYOcircuit-1-irrigationNextEnd
MIYOcircuit-1-irrigation
MIYOcircuit-1-externBlock
MIYOcircuit-1-automaticMode
MIYOvalve-1-valveStatus
MIYOvalve-1-lastIrrigationStart
MIYOvalve-1-lastIrrigationEnd
MIYOvalve-1-lastIrrigationDuration
MIYOvalve-1-openValve
MIYOvalve-1-lastUpdate
MIYOvalve-1-rssi
MIYOvalve-1-reachable
MIYOvalve-1-charging
MIYOvalve-1-chargingDurationDay
MIYOvalve-1-solarVoltage
MIYOsensor-1-moisture
MIYOsensor-1-brightness
MIYOsensor-1-temperature
MIYOsensor-1-irrigationNecessary
MIYOsensor-1-irrigationPossible
MIYOsensor-1-lastUpdate
MIYOsensor-1-rssi
MIYOsensor-1-reachable
MIYOsensor-1-charging
MIYOsensor-1-chargingDurationDay
MIYOsensor-1-solarVoltage

digitale Ausgänge je Bewässerungskreis:
MIYOcircuit-1-circuit
MIYOcircuit-1-irrigationStart
MIYOcircuit-1-irrigationStop
MIYOcircuit-1-automaticMode
MIYOcircuit-1-block
MIYOcircuit-1-considerMower

systemweite Ausgänge:
MIYO-reboot
MIYO-externMower
MIYO-externRain
MIYO-externTemperature
MIYO-externWind

externTemperature und externWind sind mit Werten beschreibbar (somit analog); reboot, externMower und externRain sind digital (Zustände).

Zu beachten ist, dass der IE11 leider Probleme mit dem Download der Vorlagen-Datei macht. Hier ist also ggf. ein anderer Browser zu nutzen. Erfolgreich getestet habe ich das hier mit Edge, FireFox und Chrome.

Wurde das Plugin durch den Schiebeschalter Aktiviere das Plugin aktiviert, arbeitet es als systemd-Dienst mit dem Namen miyoplugin und startet automatisch zusammen mit dem Rechner. Wird die Websocket-Verbindung getrennt - etwa weil der Cube rebootet - startet der Dienst nach kurzer Zeit automatisch neu und stellt die Websocket-Verbindung wieder her. Wurde Remanz externBlock aktiviert, wird nach Wiederverbindung ein ggf. vorliegender externBlock-Status reaktiviert.

Um Änderungen an der Konfiguration an den Dienst durchzustellen, muss der Dienst neugestartet werden. Dies geschieht über den Button Restart. Um den Dienst zu stoppen, muss der Schiebeschalter wieder in die "No"-Position gebracht und die Einstellungen gespeichert werden. Eine Kommunikation mit dem Cube ist dann natürlich nicht mehr möglich.

Einbindung in Loxone
Um die Vorlagendatei in Loxone einzulesen sind folgende Arbeitsschritte nötig:

Auf Virtuelle Eingänge klicken, dann erscheint oben der Button Vordefinierte UDP-Geräte und nach Klick darauf kann die vom LoxBerry geladene Vorlage MIYOplugin-in-out.xml per Vorlage importieren importiert werden:

Vorlagendatei importieren - Eingänge

Das gleiche ist dann nochmal für die Virtuellen Ausgänge zu erledigen:

Auf Virtuelle Ausgänge klicken, dann oben nach Erscheinen des Button Vordefinierte Geräte erneut die vom MIYOplugin auf dem LoxBerry erzeugte Vorlage MIYOplugin-in-out.xml importieren:

Vorlagendatei importieren - Ausgänge

Leider werden beim Import keine Raumnamen und Einheiten mit übertragen. Diese sind anschließend also noch anzupassen. Für alle Zeitangaben Start und End schlage ich als Einheit <v.u> und für die Zeitangabe mit einer Zeitdauer <v.t> vor.

Hinweis:
Es empfiehlt sich, nicht genutzte Ein- und Ausgänge zu löschen, denn der Speicherplatz des Loxone Miniservers ist recht knapp.

 

Fortan können diese Ein- und Ausgänge mit den üblichen Loxone-Bausteinen verknüpft werden. Zur Steuerung der Ventile käme eine Loxone-Schaltuhr in Frage. Für die Schalter für Sperre, Automatik und manuelle Bewässerung habe ich EIB-Taster genommen. Zu Testzwecken habe ich auch einen MIYO-Reboot über einen virtuellen UDP-Ausgang als Taster integriert:

Loxone-Bausteine

Hinweis:
Loxone verbietet derzeit (Bug oder Feature?) Leerzeichen im UDP-Ausgangsbefehl (und generiert stattdessen eine 2. UDP-Message der dann aber die Inhalte der ersten fehlen) - daher ist im UDP-Ausgangsverbinder statt eines Leerzeichens der HEX-Wert für das Leerzeichen \x20 oder ein Semikolon zu nutzen!

Alternativ zur Vorlagen-Datei können die Ein- und Ausgänge natürlich auch manuell eingerichtet werden. Nützliche Hinweise zur Befehlserkennung finden sich weiter unten.

Installation & Konfiguration für andere Systeme
Zwar fehlt hier die grafische Web-Oberfläche zu Installation und Konfiguration. Aber auch die Vorarbeiten für andere Ziel-Systeme als Loxone sind überschaubar, wenn man sich mit der Konsole und ssh etwas auskennt:

#Verzeichnis erzeugen
sudo mkdir /opt/MIYOplugin

#in das erzeugte Verzeichnis wechseln
cd /opt/MIYOplugin

#aktuelle Version des Plugins per wget holen
wget -N http://miyoplugin.phantasoft.de/files/generic-MIYOplugin.zip

#ZIP-File entpacken
unzip -o generic-MIYOplugin.zip

#generic-MIYOplugin-install.sh ausführen
sudo ./generic-MIYOplugin-install.sh --install

Dieses Script installiert - falls nicht vorhanden - Python mit den erforderlichen Bibliotheken, sucht die IP-Adresse des MIYO-Cube per UPNP-discovery, holt sich vom Cube einen API-Key und fragt mit diesem alle am Cube angemeldeten Bewässerungskreise und Geräte ab und speichert die gefundenen Daten in eine Config-Datei miyoplugin.conf im gleichen Verzeichnis. Zusätzlich wird das Plugin als systemd-Dienst eingerichtet, damit es automatisch - auch nach einem Reboot des Cube (wieder) startet. Dieser Dienst lässt sich durch Start des Scriptes mit Parameter --uninstall wieder deinstallieren. Eine Upgrade-Installation bei der die Einstellungen erhalten bleiben ist mit dem Parameter --upgrade möglich.

Mit einem Editor Deiner Wahl ist anschließend ggf. die Config-Datei miyoplugin.conf anzupassen.

Der Aufbau der Config-Datei miyoplugin.conf ist selbsterklärend:


[Config]
MIYO_IP = 192.168.15.239   # IP of MIYO-cube
LOX_IP = 192.168.15.255     # Loxone-IP to send data to
LOX_PORT = 12348             # Loxone-Port - port to send data to
LB_IP =                                 # LoxBerry-IP
LB_PORT = 50005                # LoxBerry-Port - port to receive
API_KEY = {2b7e9c14-1da2-4cb0-9b7d-5e63aef44ae7}   # API-Key for WebSocketaccess
LOX_TIME = True                 # adjust time base to 01.01.2009 (for Loxone only)
UPD_INTERVAL = 10           # get complete update after n update-msg
EXT_REM = False                # retentivity for state externBlock

[Logging]
logfile = /root/miyoplugin.log         # logs messages sent from plugin to Loxone
rawfile = /root/raw-miyoplugin.log # logs messages coming from MIYO
sndfile = /root/smiyoplugin.log      # logs messages from plugin to MIYO

[Circuit-1]
circuitid={0632cefd-0d8a-4adf-9c6d-6cc6c4f37555}
circuitname=MIYOcircuit-1
circuitmiyo=Hecke                         # name of the circuit in the MIYO-App

valveid-1={e1c998b3-8ad6-4f4a-a4a6-1e980c4e0ead}
valvename-1=MIYOvalve-1

sensorid-1={870e2d9c-6279-4e6d-b1cc-08c06cd26708}
sensorname-1=MIYOsensor-1

[Circuit-2]
circuitid={circuit2--0d8a-4adf-9c6d-6cc6c4f37555}
circuitname=MIYOcircuit-2
circuitmiyo=Blumenbeet vorn

valveid-1={erstes-ventil-im-zweiten-kreis-ead}
valvename-1=MIYOvalve-2-1

# es kann aber mehrere Ventile pro Bewässerungskreis geben!
valveid-2={zweites-ventil-im-zweiten-kreis-ead}
valvename-2=MIYOvalve-2-2

valveid-3={drittes-ventil-im-zweiten-kreis-ead}
valvename-3=MIYOvalve-2-3


Die IP-Adresse des MIYO-Cube sollte per UPNP-discovery automatisch bereits im Config-File eingetragen sein. Über ./miyoplugin.py -getCubeIP lässt sich jedoch die IP-Adresse des Cubes ausgeben und manuell im Config-File eintragen.
Sollen die UDP-Pakete vom Plugin zum Zielsystem nicht per Broadcast an das komplette Netz geschickt werden, lässt sich dies durch Änderung der LOX_IP auf eine definierte IP-Adresse begrenzen. Die Broadcast-Lösung bietet jedoch die evtl. hilfreiche Möglichkeit (etwa zum Mitschreiben der Daten in eine Datenbank) zur parallelen Verarbeitung auf anderen Systemen.

Der UDP-Sende-Port zum Zielsystem wird über LOX_PORT konfiguriert. Auf diesem Port lauscht das Zielsystem auf eingehende Daten.

Standardmäßig reagiert das Plugin auf UDP-Nachrichten an Port LB_PORT auf allen Netzwerk-Adressen. Über LB_IP kann in einem Mehradress-System eine IP-Adresse festgelegt werden.
Der UDP-Empfangsport LB_PORT muss für das Plugin frei sein, was durch das Installationsscript vorab geprüft wird.

Über den Schalter LOX_TIME wird festgelegt, ob eine Umrechnung der UTC-Zeit auf Loxone-Zeit erfolgen soll. Kommt nicht Loxone zum Einsatz, sollte LOX_TIME auf False gesetzt werden (default in der generic-Version).

Bei jeder Änderung sendet der Cube eine Update-Meldung per Websocket zum Plugin. Wenn die unter UPD_INTERVAL konfigurierte Anzahl von Update-Meldungen eingegangen ist, holt sich das Plugin vom Cube ein komplettes Device-Update. Dies erfolgt nur, um wenigstens alle 10 Minuten den kompletten Status zu erhalten und ist für die Entwicklung hilfreich. Im Normalbetrieb kann der Wert wohl auch bei 100 oder größer konfiguriert werden, da sämtliche Änderungen von den Geräten automatisch - aber eben einzeln - mitgeteilt werden.

Über EXT_REM kann festgelegt werden, ob die extern setzbare Sperre des Bewässerungskreises externBlock  gespeichert und im Falle eines Neustarts des Cube oder des Plugins wieder auf den ursprünglichen Wert gesetzt werden soll. Dies ist hilfreich wenn man temporär die Bewässerungsautomatik zwar abschalten möchte, aber auch sicherstellen will, dass diese Sperre einen Neustart des Cubes (etwa durch ein automatisches Update) oder des Plugins (etwa durch Neustart des Rechners) überlebt. viRaTec selbst hat bewusst auf eine Remanenz dieser Sperre verzichtet, daher wird hier diese Sperre ggf. neu gesetzt.

Die Logging-Funktionalität ist für die Entwicklung und bei Problemen sehr hilfreich. Allerdings werden die Log-Files recht schnell recht groß. Daher sollte für den Regelbetrieb das Logging (partiell) deaktiviert werden.
Dazu einfach ein # vor die entsprechende Zeile setzen oder die Zeilen komplett entfernen oder hinter dem = keinen Dateinamen angeben.

Für jeden Bewässerungskreis gibt es eine Sektion [Circuit-n] wobei n eine laufende Nummer von 1 bis 10 ist.
Die verschiedenen Ventile und ggf. der Sensor sind innerhalb der Sektion ebenfalls mit einer laufenden Nummer durchnummeriert.
Wichtig ist jeweils der Name der bei circuitname, valvename-n oder sensorname-n hinterlegt ist. Mit diesem Namen als SID (System- bzw. Sensor-ID) werden die UDP-Nachrichten vom Plugin an das Zielsystem verschickt. Anhand dieses Namens kann das Zielsystem also unterscheiden, von welchem Gerät die Werte empfangen wurden.

Über das MIYOplugin per Websocket vom Cube empfangene Nachrichten werden dann beispielsweise so per UDP an das Zielsystem weitergeschickt: 

SID=MIYOsensor-1 lastUpdate=323967211 firmware="1.32.0" moisture=65 brightness=6201 temperature=25 frequency=1239150 irrigationNecessary=0 irrigationPossible=0 temperatureOffset=0 rssi=-78 reachable=1 solarVoltage=4.45 sunWithinWeek=1 lowPower=0 otauPossible=0 otauProgress=0 otauStatus= winterMode=0 chargingDurationDay=11.428571428571429 charging=1 chargingLess=0 lastResetTime=0 lastResetType=-1
SID=MIYOvalve-1 lastUpdate=323967198 firmware="1.51.0" valveInitialClose=0 valveStatus=1 openValve=1 lastIrrigationStart=323966584 lastIrrigationEnd=323881241 lastIrrigationDuration=3638 rssi=-88 reachable=1 solarVoltage=4.45 sunWithinWeek=1 lowPower=0 otauPossible=0 otauProgress=0 otauStatus= winterMode=0 chargingDurationDay=11.428571428571429 charging=1 chargingLess=0 lastResetTime=0 lastResetType=-1
SID=MIYOvalve-1 rssi=-84
SID=MIYOvalve-1 solarVoltage=4.42
SID=MIYOcentral updated=1
SID=MIYOvalve-1 openValve=0
SID=MIYOvalve-1 valveInitialClose=1
SID=MIYOvalve-1 valveStatus=0
SID=MIYOvalve-1 lastIrrigationEnd=323967628
SID=MIYOvalve-1 lastIrrigationDuration=1044
SID=MIYOcircuit-1 irrigation=0

Das Zielsystem kann dann anhand der SID den/die Werte einem spezifischen Gerät oder Bewässerungskreis zuordnen und visualisieren.
Neben den in der Config-Datei zugewiesenen Namen für die SID gibt es noch die vom Plugin kommende SID=MIYOcentral sowie SID=MIYOmessage.
MIYOcentral enthält Nachrichten vom Cube wie Wettermeldungen oder die Übermittlung der Extern-Stati, die nach jeder Änderung über das MIYOplugin erneut gepollt werden; SID=MIYOmessage Textmeldungen des Cubes, wenn z.B. das Ventil nicht erreichbar ist:

SID=MIYOcentral description="mist" forecast=0 icon=50 temperature=12
SID=MIYOcentral mower=1 rain=1 temperature=18 wind=5
SID=MIYOmessage message="Valve is not reachable! Irrigation will be changed next time valve is reachable"

Hinweis:
Wert-Änderungen der Extern-Methoden rain, wind, mower und temperature werden von der API nicht automatisch zurückgemeldet, daher fragt MIYOplugin bei jeder Änderung den Extern-Status erneut ab. Dies kann zu etwas mehr Netzwerktraffic führen.
Schlimmer wiegt jedoch, dass diese Werte bei einem Neustart des Cube komplett verloren gehen. Ich überlege noch, wie das Plugin damit zukünftig umgehen soll.

 

Eingehende UDP-Nachrichten mit SID=MIYOplugin werden zur Steuerung des Cubes vom Hausautomatisierungssystem genutzt.

Wenn das Plugin eine UDP-Nachricht auf Port LB_PORT mit dem Inhalt

SID=MIYOplugin,Extern.block,block=false 

erhält, setzt es diesen UDP-Befehl in einen Websocket-Befehl um und sendet diesen an den Cube:

{"id":0,"method":"Extern.block","params":{"circuitId":"{0632cefd-0d8a-4adf-9c6d-6cc6c4f37555}","block":false},"apiKey":"{2b7e9c14-1da2-4cb0-9b7d-5e63aef44ae7}"}

Bei Befehlen, die die Angabe einer circuitId erfordern kann diese sowohl mit der MIYO-circuitId (erkennbar an 38 Zeichen und beginnend mit einem { und auf } endend) als auch mit der kürzeren und sicherlich besser lesbaren Variante aus dem Config-File circuitname übergeben werden. Ist nur ein Bewässerungskreis vorhanden, wird vom Plugin automatisch die korrekte circuitId mit übergeben. 

Die Bedeutung der einzelnen Werte und Parameter ist in der Websocket-API-Beschreibung für das MIYO-Bewässerungssystem nachlesbar. 

Einbindung in andere Systeme
Jedes andere Smarthome-System - welches per UDP kommunizieren kann - sollte mit diesem Plugin ebenfalls anbindbar sein. Da ich diese Systeme jedoch nicht im Einsatz habe, kann ich zur genauen Einbindung leider keine Auskunft geben. Gerne füge ich hier aber entsprechende Hinweise und Anleitungen hinzu. 

Es geht aber eigentlich nur darum, auf dem Zielsystem einen UDP-Server zu betreiben, der auf dem festgelegten Port LOX_PORT eingehende Datagramme annimmt und zerlegt. Kommt also auf dem festgelegten Port LOX_PORT ein String mit dem Inhalt:

SID=MIYOsensor-1 lastUpdate=323967211 firmware="1.32.0" moisture=65 brightness=6201 temperature=25 frequency=1239150 irrigationNecessary=0 irrigationPossible=0 temperatureOffset=0 rssi=-78 reachable=1 solarVoltage=4.45 sunWithinWeek=1 lowPower=0 otauPossible=0 otauProgress=0 otauStatus= winterMode=0 chargingDurationDay=11.428571428571429 charging=1 chargingLess=0 lastResetTime=0 lastResetType=-1

rein, muss zuerst geprueft werden, von welchem Gerät diese Nachricht kommt. SID=gerätename gibt hier den entscheidenden Hinweis. Die einen zu diesem Gerät interessierenden Felder müssen dann im String gesucht und die entsprechenden Werte ausgeschnitten werden. Die vom Sensor mit dem Namen MIYOsensor-1 gemeldete Bodenfeuchte ergibt sich demnach aus:

  1. suche SID=MIYOsensor-1
  2. suche moisture=
  3. alle Zeichen zwischen moisture= und einem Leerzeichen oder dem String-Ende ergeben den Wert: 65

Für das 90-minütige Öffnen eines Ventils im Bewässerungskreis mit Namen MIYOcircuit-1 ist auf dem Zielsystem ein UDP-Datagram an Port LB_PORT auszulösen mit dem Inhalt

SID=MIYOplugin,Circuit.irrigation,mode=start duration=90,MIYOcircuit-1

Ohne Vorgabe der Bewässerungsdauer mit "duration=Minutenanzahl" wird das Ventil vom Cube aus Sicherheitsgründen nur für 10 Minuten geöffnet - ein "mode=start" ohne Angabe einer duration öffnet also das Ventil für nur 10 Minuten.

Nachtrag
Die Bewässerungs-Intelligenz des Cube scheint bisher - die Saison hat aber gerade erst begonnen - ausreichend zu sein, so das ich derzeit keinen Grund sehe, selbst in die Steuerung einzugreifen. Mit den wachsenden Erfahrungen kann ich vermutlich im Herbst 2019 mehr dazu mitteilen. Und weil das MIYO-System bisher so unauffällig funktioniert,  habe ich jetzt auch noch einen zweiten Bewässerungskreis angeschlossen, der über das MIYOplugin angesteuert wird.

Download
MIYOplugin-LoxBerry-Version
MIYOplugin-Generic-Version

Links
die offizielle API-Beschreibung von viRaTec als PDF (externer Link)
Erklärungen zu UDP- Ein- und Ausgängen und Befehlserkennung auf off. Loxone-Seite
Link zum Hersteller des MIYO-Bewässerungssystems
Link zum Loxforum
Übersichtsseite aller Plugins für den LoxBerry (externer Link)
Link zur Android-App im Google PlayStore
Die MIYO-App für Geräte mit dem Apfel (externer Link)

Link zum Support-Thread für das MIYOplugin im Loxforum

Eingetragene Warenzeichen gehören den jeweiligen Eigentümern!
Kontakt: MIYOplugin (at) phantasoft.de