Startseite » , QR-Code für diese Seite

NIU Roller in openHAB integrieren

16 März 2022, 1.526x angezeigt, 6 Kommentare
Tags: , , , , , , , ,

Da seit einigen Tagen ein openHAB bei mir läuft, versuche ich zunehmend weitere smarte Geräte in die Haussteuerung zu integrieren. Dies wollte ich auch mit dem NIU Roller machen, sodass ich den Batteriestatus und ggf. weitere Informationen auslesen kann. Auf der Recherche bin ich auf folgenden Forum-Eintrag im Elektroroller-Forum gestoßen, welcher von vielen API-Integrationen zitiert bzw. darauf verwiesen wird. Im Netz finden sich einige API-Integrationen in den Programmiersprachen Node/JS oder PHP Skripte diesbezüglich. Ich habe mich aber gegen diese Skripte entschieden, weil ich diese zu umfangreich (Node und seine vielen Abhängigkeiten) oder technisch nicht sauber genug fand (PHP alles in einer Datei). Somit habe ich selbst Hand angelegt und beschreibe euch nun im Detail die Integration ins openHAB Step-By-Step. Viel Spaß.

Wie bekomme ich Daten aus der NIU App in das openHAB? (App Icons iOS)

API Zugriff

Im ersten Schritt habe ich mich mit der API auseinandergesetzt. Da ich die bisherigen Integrationen unzureichend fand, habe ich selbst die API in PHP integriert. Zu finden ist das ganze auf GitHub unter github.com/lochmueller/niu-api-connector. Die Integration der API sieht vor, dass eine PHAR-Datei generiert wird, welche einfach heruntergeladen und mit PHP ausgeführt werden kann, ohne dass man weitere Dinge benötigt. Die aktuellen PHAR Datei können den Actions z.B. hier entnommen werden und werde ich in Kürze auch an die Releases binden. Ich denke, ich werde in den nächsten Tagen noch weitere Funktionen ergänzen, sodass die Benutzung weiter vereinfacht wird.

D.h. es muss nur die aktuelle PHAR Datei heruntergeladen und in dem openHABian z.B. im Home-Verzeichnis platziert werden. Für die Benutzung empfehle ich, wie in der README.md beschrieben, einfach den die Datei ohne Parameter auszuführen. Die integrierte Hilfe leitet einen dann durch die verschiedenen Befehle und Parameter. Für meinen Usecase habe ich „niu:authentication“, „niu:vehicles“ und „niu:motor“ benutzt.

API-Installation auf Raspberry PI

Nachdem die Datei im Home-Verzeichnis liegt, ist Folgendes auszuführen, sodass die API benutzt werden kann. Schaut euch jeden Schritt an und liest den Kommentar dazu sorgfältig durch. Falls ihr Fragen dies bzgl. habt, einfach hier unter dem Beitrag oder auf Github einen Kommentar bzw. Issue anlegen.

sudo apt-get install php8.0-cli php8.0-curl # PHP mit curl installieren.
cd /home/openhabian/ # Ins Home-Verzeichnis wechseln (hier wurde die PHAR Datei platziert).
touch .env # ENV Datei anlegen. Hier Zugangsdaten hinterlegen gemäß Dokumentation von GitHub.
chmod +x niu-api-connector.phar # Datei ausführbar machen.

./niu-api-connector.phar # testen ob alles geht. Ihr solltet eine Ausgabe der Commands sehen.

./niu-api-connector.phar niu:authentication # Wenn die .env passend gefüllt ist, sollte eine Erfolgsmeldung erscheinen, dass ein Token abgelegt wurde. Der Token liegt per Default im gleichen Verzeichnis und heißt “auth.token“.

./niu-api-connector.phar niu:vehicles # Zeigt deine Fahrzeuge an und gibt dir deine SerialNumber des passenden Fahrzeuges aus, welche du für den eigentlichen Aufruf brauchst.

# Finaler Aufruf (XXXXX deine SerialNumber des Fahrzeuges)
/home/openhabian/niu-api-connector.phar niu:motor XXXXXX --format=json --tokenFile=/home/openhabian/auth.token

Als Resultat solltet ihr ein JSON mit technischen Motor-Informationen eures Rollers sehen. Hier ist auch der Batterie-Stand zu finden. Ab damit ins openHAB…

Integration in openHAB

Die Integration ins openHAB habe ich mit dem Exec Binding gemacht. Damit bin ich in der Lage, in gewissen Intervallen einfach das Script auszuführen, welches die Informationen ausgibt. Des Weiteren habe ich die JsonPath Transformation im openHAB (unter weitere Add-Ons) installiert, sodass ich das JSON effizient verarbeiten kann. Damit der „Exec Binding“-Befehle ausgeführt werde kann, muss dieser in eine Whitelist eingetragen werden. Mit folgendem Befehl könnt ihr die Whitelist öffnen und den „finalen Befehl“ in die Liste mit aufnehmen.

sudo vi /etc/openhab/misc/exec.whitelist 

Ist dies geschehen, könnt ihr ein neues “Thing“ vom Typ “Exec Binding“ anlegen und den Befehl in das Binding eintragen. Zusätzlich kann hier auch das Intervall in Sekunden hinterlegt werden. Ich empfehle das Intervall nicht zu niedrig zu wählen. Ich habe mich für 15 Minuten (= 900 Sekunden) entschieden. Jetzt nur noch die Daten weiterverarbeiten…

Transformation und Weiterverarbeitung

Der Exec Befehl liefert das komplette JSON, welches ihr auch beim manuellen Ausführen des Befehls gesehen habt. Wir wollen jedoch ausschließlich Zugriff auf den Batteriestatus, sodass wir diesen in der openHAB App darstellen oder dies bzgl. weitere Dinge steuern können. Somit habe ich die Transformation mittels JsonPath vorgenommen. In das Feld der Transformation ist nun JSONPATH(.totalBatteryCharging) einzutragen. Dadurch wird ausschließlich das komplette Batterie-Ladelevel von dem „Thing“ als Zahl erfasst. Da dies eine numerischer Wert ist, habe ich das Item entsprechend auch als Number im openHAB konfiguriert.

Fazit

Sehr coole & neue Möglichkeiten, welche sich durch die Integration eröffnen. Finde es schade, dass die NIU API nicht solch einen guten Eindruck macht (keine gute Dokumentation gefunden, keine echten Status-Codes in Gebrauch), aber irgendwie kann man sich da „durch Kämpfen“. Bin auf Feedback gespannt und werde den API Connector gerne noch weiter ausbauen.

Der Status der Batterie wird nun aufgezeichnet und kann im openHAB benutzt werden
Tim Lochmüller Autor
Name: Tim Lochmüller
Webseite: http://typo3blogger.de
Posts: 264 Posts

6 Kommentare »

  • openHAB - Erste Block Lib veröffentlicht - 360°Friends
    openHAB - Erste Block Lib veröffentlicht - 360°Friends sagt:

    […] Aufbau der verschiedenen Regeln habe ich auch den NIU-Roller mit integriert. Eine Regeln bzgl. des Rollers soll aber nur etwas tun, wenn dieser auch zu Hause […]

  • Smarte Sonnensteckdose - openHAB - 360°Friends
    Smarte Sonnensteckdose - openHAB - 360°Friends sagt:

    […] musste ich immer ein Verlängerungskabel auslegen, um den Roller laden zu können. Grund genug, eine neue Steckdose zu montieren, sodass das Laden leichter von der […]

  • teH_wHoly
    teH_wHoly sagt:

    Hi!

    Vielen Dank für die Anleitung und das Git repo! Ich habe mir den Token selbst generiert und die Abfrage tatsächlich zum Laufen gebraucht nach der Anleitung! Nächster Schritt ist, dass ich die anderen Infos ebenfalls abhole mit dem Interpreter und mehr Items generiere. Wäre schon super, wenn zu dem Thing mehrere Items rauspurzeln. Da ich aber noch neu in openHAB bin muss ich mich erstmal mit dem System vertraut machen.

    Grüße!

  • Tim Lochmüller
    Tim Lochmüller (Autor) sagt:

    Hallo teH_wHoly.

    Mit den mehr Items gebe ich dir recht. Glaube mittelfristig wäre ein eigenes Binding dafür cool. Mal schauen, wann ich mich damit auseinandersetze… :-)

    Grüße,
    Tim

  • teH_wHoly
    teH_wHoly sagt:

    Hi!
    Ich habe jetzt in OpenHAB 3 mehrere Items verlinkt, die alle auf dem exec command aufbauen.

    JSONPATH als Profile lässt auf einzelne Elemente zugreifen, indem man die Konfiguration:
    .lockStatus
    setzt (Beispielparameter)
    Bei der Entgegennahme von boolschen Werten musste ich etwas tricksen und ein JS als Profile nutzen, das „true“ und „false“ in „ON“ und „OFF“ wandelt und ebenfalls JSON parsed. Dafür kann man folgenden Inhalt unter /transform/bool.js ablegen:

    (function(dataString, itm) {
    var data = JSON.parse(dataString);
    var state = data[0][itm];
    var reply = „error“;
    if (state) reply = „ON“;
    if (!state) reply = „OFF“;
    return reply;
    })(input, item)

    und in „Profile“ unter Konfiguration des items aufgerufen:
    bool.js?item=batteries_compartmentB_isConnected
    (Beispielparameter)

    Alle Transformation AddOns müssen natürlich vorher installiert werden (JSONPath, Javascript).

    Vielleicht hilft es ja jemand weiter, so kann man sich alle Elemente abholen ohne immer wieder eine Anfrage an den Server senden zu müssen. Damit kann man sehr gut in OpenHAB arbeiten, wie es ist und die Integration des NIU ist für mich abgeschlossen.

  • Tim Lochmüller
    Tim Lochmüller (Autor) sagt:

    Danke teH_wHoly, für die ausführlich Ergänzung :)

Hinterlasse einen Kommentar/Leserbrief!

Füge deinen Kommentar hinzu oder sende einen Trackback von deiner Webseite aus.
Du kannst zudem die Kommentare via RSS abonnieren .

Sei freundlich! Halt dich ans Thema! Kein Spam!

Mit dem Absenden bestätigst du, dass es sich um keinen Spam handelt.