Als Vorarbeiten wird im Wesentlichen der Artikel „Entfernungsmessung auf Basis eines ESP32 und SmartHomeNG“ vorausgesetzt.

Mittlerweile bin ich bei der Messung des Ultraschallsignales des HR-SR04 allerdings auf die Arduino Bibliothek NewPing umgestiegen, die die Messung übernimmt:Als Display kommt ein kleines OLED Display mit SSD 1306 Controller zum Einsatz (https://www.az-delivery.de/products/0-96zolldisplay, ca. 7 Euro).

Das Display wird wie folgt zusätzlich zum HC-SR04 angeschlossen:

Als Bibliothek kommt die „ESP8266 and ESP32 Oled Driver for SSD1306 display“ von Daniel Eichhorn und Fabrice Weinberg in Version 4.0.0 zum Einsatz:

Der angepasst Sourcecode sieht nun wie folgt aus. Es ist dabei zu beachten, dass das Webservices- Plugin inzwischen über die REST Schnittstelle angesteuert wird. Weiterhin sind alle Log-Outputs für den Seriellen Monitor entfernt worden. Sämtliche relevanten Outputs werden jetzt auf dem Display ausgegeben.

#include <HTTPClient.h>
#include <NewPing.h>
#include <WiFi.h>
#include <WiFiClient.h>
#include <WiFiServer.h>
#include <WiFiUdp.h>
#include <Wire.h>
#include "SSD1306.h"

const int triggerPin = 15;   // HC-SR04: Trigger Pin
const int echoPin = 4;       // HC-SR04: Echo Pin
const int sdaPin = 21;       // Display: SDA Pin
const int sclPin = 22;       // Display: SCL Pin
const int sensorRange = 280; // Reichweite (< maximale Reichweite)

// HC-SR04
NewPing sonar(triggerPin, echoPin, sensorRange); // create NewPing instance

// Wifi
char ssid[] = "<wlan_ssid>";     // your network SSID (name)
char pass[] = "<wlan_password>"; // your network password
char host[] = "192.168.178.100"; // ip of service interface in SmartHomeNG
int port = 4321;                 // port of service interface in SmartHomeNG
char cm_item[] = "test.numeric";
int status = WL_IDLE_STATUS;
WiFiClient client;

// Display
SSD1306Wire display(0x3c, sdaPin, sclPin);

void setup() {
  Serial.begin(19200);
  // Init Display
  display.init();
  display.flipScreenVertically();
  // Init Wifi
  initialise_wifi();
}

void loop() {
  delay(50);
  unsigned int result = sonar.ping();
  float cm = sonar.convert_cm(result); //(result/2)/29.1; //

  while (client.available()) {
    char c = client.read();
    Serial.write(c);
  }

  if (cm > 0) {
    if (client.connect(host, port)) {
      HTTPClient http;
      char portStr[12];
      sprintf(portStr, "%d", port);
      char url[128];
      sprintf(url, "http://%s:%s/rest/items/%s", host, portStr, cm_item);
      http.begin(url);
      http.addHeader("Content-Type", "application/json");
      char cmStr[12];
      char cmStrFull[24];
      sprintf(cmStr, "%f", cm);
      sprintf(cmStrFull, "%i cm", (int)cm);
      int httpCode = http.PUT(cmStr);
      String payload = http.getString();
      http.end();

      display.clear();
      display.setFont(ArialMT_Plain_16);
      display.drawString(0, 0, "Wasserstand:");
      display.setFont(ArialMT_Plain_24);
      display.drawString(0, 17, cmStrFull);
      display.display();
    }
  }
  // Wait 5 seconds and do next measurement
  delay(5000);
}

static void initialise_wifi(void) {
  display.setFont(ArialMT_Plain_10);
  display.drawString(0, 0, "Setting up wifi...");
  display.display();

  while (status != WL_CONNECTED) {
    display.drawString(0, 11, "Attempting to connect...");
    display.display();
    status = WiFi.begin(ssid, pass);
    delay(10000);
  }
  display.drawString(0, 22, "Connected to wifi!");
  display.display();
  printWifiStatus();
}

void printWifiStatus() {
  IPAddress ip = WiFi.localIP();
  String ipStr = String(ip[0]) + '.' + String(ip[1]) + '.' + String(ip[2]) + '.' + String(ip[3]);
  display.drawString(0, 33, "IP: "+ipStr);
  display.display();
  long rssi = WiFi.RSSI();
  char rssiStr[255];
  sprintf(rssiStr, "RSSI: %d dBm", rssi);
  display.drawString(0, 44, rssiStr);
  display.display();
}

Nach der Initialisierung des Displays in der Methode setup, kann mittels display.drawString(...) Text auf das Display gesendet werden. Der erste Parameter ist dabei die X-, der zweite die Y-Koordinate. Im dritten Parameter wird der String gesetzt. Mit display.display(); werden alle zuvor eingesteuerten Operationen dann wirklich auf dem Display ausgegeben. Ein display.clear(); leert die auf dem Display ausgegebenen Werte, damit neuer Text dargestellt werden kann. Wird kein display.display(); aufgerufen, so wird immer mehr auf das Display geschrieben. Dies kann soweit führen, dass Text über bestehenden Text geschrieben wird.

Dies kann am Beispiel der WLAN-Initialisierung gut gesehen werden. Das Gehäuse ist dabei wieder von Thingiverse bezogen und via 3D Drucker gedruckt worden (https://www.thingiverse.com/thing:2176764):

Nach der Initialisierung wird nun auf dem Display der Abstand angezeigt:

In Teil 3 folgt nun in Kürze noch ein Update zu meiner tatsächlichen Installation in der Zisterne und der Garage. Die Arbeiten sind bereits vollendet und die Werte werden via Kabel in die Garage auf den ESP32 übertragen. Mehr dazu aber in der nächsten Zeit…

(Die in diesem Artikel verwendeten Screenshots und Fotos wurden selber erstellt. Für den Schaltplan wurde das Tool Fritzing verwendet.)

ich möchte Euch kurz vorstellen, wie man Sensoren schnell und einfach in shNG einbinden kann. Das Ganze basiert auf der Verwendung eines ESP8266 (bspw. Wemos D1 mini), der Firmware ESPEasy und des shNG Webservices-Plugins.

Die Firmware ESPEasy bietet viele Konfigurationsmöglichkeiten, dies betrifft sowohl Sensoren also auch Kommunikationsschnittstellen.

Teil 0: Allgemeine Informationen

• ESPEasy arbeitet auch im Github.
• Die Liste der unterstützten Sensoren gibt es hier.
• Bei ESPEasy wird jede Nacht automatisch ein Release erzeugt. Diese sind hier zu finden. Es gibt 2 Ausführungen der ESPEasy: A) Released aktuell in der Version 2.0 und B) Develop. als mit mehr Plugins aber auch noch in der Testphase.

Teil 1: Flashen der Firmware

• Download des letzten (Pre-)Releases der V2.0 von hier als zip (heute wäre das Release v2.0-20180321)
• Entpacken des ZIP. Darin sind diverse Binaries und das Flashtool selbst.
  Zu den Binaries: Hier gibt es 3 Ausbaustufen und das ganze für 2 SpeicherGrößen: normal – enthält nur die getesteten und freigegebenen Teile von ESPeasy; test – enthält zusätzlich noch die getesteten; dev – enthält zusätzlich noch die sich in Entwicklung befindlichen; Die Speichergrößen sind 1MB und 4MB. Der erwähnte WEMOS D1 mini hat 4MB Speicher.
• Verbinde den ESP via USB mit einem Windows PC.
• Firmware mit Hilfe des Flashtools auf dem ESP schreiben, dabei Serielle Schnittstelle (COM-Port) und das entsprechende Binary auswählen. Ich nutze immer die Dev-Version. Die COM Schnittstelle kann man auch über den Windows-Gerätemanager in Erfahrung bringen.
  
  
• Neustart des ESP (Reset Taste).
• Der ESP öffnet einen WLAN AccessPoint „ESP_Easy_0“; Passwort: configesp
  Wenn man nicht automatisch zur Anmeldeseite kommt, dann nach 192.168.4.1 browsen
• In der Config seine eigenen WLAN-Daten eingeben und den ESP wieder neu starten. Nun sollte er sich in eigenen Netzwerk anmelden.
  (Über den Weg, das fertige Binary der Firmware zu flashen, muss man immer den Weg über den Hotspot zur Konfiguration und damit zu Einbindung in das eigene Netzwerk machen.)
• Eine detaillierte Beschreibung ist hier
• Nun ist der ESP vorbereitet und kann konfiguriert werden

Teil 2: Verbinden der Sensoren mit dem ESP8266 (Wemos D1 Mini)

• Der verwendetete Sensor DHT22 wird wie folgt mit dem Wemos D1 Mini verbunden:
  
  Den verwendeten GPIO könnt ihr frei wählen. Er muss später in ESPEasy angegeben werden. Hier im Bild ist D0 (GPIO16) verwendet.

Teil 3: Konfiguration in ESPEasy

• Mit dem Aufruf der IP des ESP kommt man zur Konfigurationsseite
• Die Möglichkeiten der Konfiguration sind hier beschrieben.
• Auf der Seite Devices muss der entsprechende Sensor konfiguriert werden. Dabei wird definiert, welcher Sensor an welchem Eingang angeschlossen wurde.
  
• In meinem Beispiel ist es ein DHT22 an GPIO16 (D0).
  
  Im Beispiel sendet er seine Werte an den 3. definierten Controller mit einer Verzögerung von 30sec. Es werden 2 Werte übermittelt, Termperatur und Humidity, jeweils mit 1 Dezimalstelle.
• Auf der Seite Controller wird die Schnittstelle konfiguriert.
  Im Beispiel sind 3 Controller (also Schnittstellen definiert), wobei nur die dritte aktiv ist.
• Wir nutzen „Generic HTTP“, tragen als Controller IP die IP-Adresse von shNG ein und bei Controller Port den Port, den wir für das Webservices-Plugin nutzen.
  Bei Controller Publish setzen wir:
  /shNG/ws/items/ESP_Easy.%sysname%.%tskname%.%valname%/%value%
• Verwendet wird das einfachere „Simple Webservices“ HTTP-Interface, bei dem der eigentliche Wert Teil der HTTP-Adresse ist (kein Payload).
• Zur Erklärung von /shNG/ws/items/ESP_Easy.%sysname%.%tskname%.%valname%/%value%:
  • /shNG/: wird von ESPEasy beim Versenden verschluckt und dient somit nur als „Futter“
  • /ws/items/: Wird vom WebservicePlugin erwartet, um den Inhalt einem Item zuzuordnen
  • /ESP-Easy/: verwende ich als „root“ des Items, so dass alle folgenden Items Kinder von ESP-Easy sind.
  • %sysname%: Name des ESP8266, definiert im Reiter „Config“ unter „Unit Name“  (Im Beispiel: „Wemos_1“)
  • %tskname%: Name des Sensors, definiert im Reiter „Devices“ unter „Name“ (Im Beispiel: „Umwelt“)
  • %valname%: Name des Wertes des Sensors, definiert im Reiter „Devices“ unter „Value“ (Im Beispiel: „Temperature“)
  • %value%: ist der eigentliche Wert
    Damit ergibt sich das Item: ESP_Easy.Wemos_1.Umwelt.Temperature. Der Wert selbst ist 17.36

Teil 4: Konfiguration shNG

• Damit wir in shNG auch etwas empfangen, muss das Webservices-Plugin aktiviert und konfiguriert werden. Man kann die Standardkonfiguration, wie in der Anwenderdokumentation beschrieben, verwenden, d.h. der Port ist 8384.
• Dazu gibt es auch bereits einen Blog-Artikel.
• Nach der Aktivierung und Konfiguration des Plugins sowie einem Neustart müssten im Logfile bereits die Items und Werte sichtbar sein.
  Bspw.: CP Server Thread-19 192.168.2.25 - - [18/Apr/2018:21:41:48] "GET /ws/items/ESP_Easy.Wemos_1.Umwelt.Humidity/64.0 HTTP/1.1" 200 80 "" ""
• Nun noch die Items in einer yaml-Datei im Ordner /items/ definieren: (Beispiel: ESP-Easy.Wemos_1.Umwelt.Temperatur) und shNG neu starten.

  
  ESP_Easy:
      Wemos_1:
          Umwelt:
              Temperature:
                  type: num 
              Humidity:
                  type: num
  

• Nun müssten über das „Simple Webservices“ HTTP-Interface des Webservices-Plugins den Items die Werte zugwiesen werden.

Viel Spaß beim Anwenden!

Das hier vorgestellte Beispiel, das u.a. für die Überwachung des Füllstands einer Zisterne verwendet werden kann, ist auf Basis eines Espressif ESP32 entwickelt worden, der zum Zeitpunkt dieses Artikels für ca. 15 Euro zu haben ist. Dazu wird für die Entfernungsmessung ein HC-SR04 Ultraschallsensor verwendet, der für knapp 2 Euro erhältlich ist.

Die Daten werden dabei an ein Item übermittelt, das via Webservices-Plugin erreichbar ist. Mehr zu diesem Plugin ist unter https://www.smarthomeng.de/das-smarthomeng-webservices-plugin zu finden. Die korrekte Konfiguration des Items wird in diesem Artikel als Voraussetzung angenommen.

Update: Inzwischen ist der zweite Teil zum Thema erschienen, bei dem ich erläutere, wie man die Entfernungsdaten auf ein OLED Display bringt. Direkteinstieg unter Entfernungsmessung mit ESP32 und SmartHomeNG Teil 2: Anbindung eines SSD1306 OLED Displays.

Installation des Espressif ESP32 unter Windows

Als erstes muss der ESP32 als USB Gerät erkannt werden. Dazu kann die Anleitung unter https://dl.espressif.com/doc/esp-idf/latest/get-started/establish-serial-connection.html befolgt werden. Eine alternative Anleitung für MacOS und Linux ist dort ebenfalls zu finden.

Zusammengefasst muss der Treiber für das ESP32 Core Board von https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers installiert werden. Danach sollte das Gerät als COM3 auftauchen, wie in untenstehendem Bild zu sehen ist. In meinen Tests klappte dies nicht mit jedem Micro-USB-Kabel. Daher sind ggf. Kabel durchzuprobieren.

Einrichtung der Arduino IDE

Als nächstes muss die Arduino IDE installiert werden. Diese kann kostenlos über https://www.arduino.cc/en/main/software oder bei Windows 10 den Microsoft Store bezogen werden.

Über „Werkzeuge“ → „Board“ muss dort nun das „ESP32 Dev Module“ ausgewählt werden. Die weiteren Einstellungen sind ebenfalls im folgenden Bild zu sehen:

Wird rechts unten noch ein „None auf COM3“ angezeigt, so ist das nicht weiter dramatisch, sofern der ESP32 bereits im Geräte-Manager auf COM3 sichtbar ist.

Versuchsaufbau: Espressif ESP32 mit HC-SR04 Ultraschallsensor

Die Funktionsweise des HC-SR04 Ultraschallsensors ist schnell erklärt:

Der HC-SR04 hat einen Lautsprecher und ein Mikrofon verbaut. Über den Lautsprecher wird ein Ultraschall-Ton ausgegeben. Dieser wird von einem Objekt reflektiert und über das direkt neben dem Lautsprecher platzierte Mikrofon erfasst. Die Zeitdauer zwischen dem Senden des Signals und dem Empfang des Echos wird gemessen. Über die Schallgeschwindigkeit von 343,2 m/s bei 20° Celsius kann nun die Distanz zu demjenigen Objekt berechnet werden, an dem das Signal relektiert wird.

Da der Sensor in Mikrosekunden misst, muss zur Bestimmung der Distanz der gemessene Wert erst halbiert (einfache Strecke) und dann mit 0,03432 multipliziert bzw. grob überschlagen durch 29.1 geteilt werden (1/29.1 = 0,03436).

Für den Versuchsaufbau muss der HC-SR04 an den ESP angeschlossen werden. Der HC-SR04 besitzt dabei die Anschlüsse „Gnd“, „Echo“, „Trig“ und „Vcc“.

„Gnd“ wird am ESP ebenfalls an „Gnd“ angeschlossen. „Vcc“ kommt an den „5V“ Anschluss für die Stromversorgung. „Echo“ und „Trig“ werden an die jeweiligen GPIOs angeschlossen. Im Beispiel wird „Echo“ auf „IO4“ und „Trig“ auf „IO15“ gelegt. Diese sind später im Programmcode zu referenzieren.

Programmierung des ESP32 via Arduino IDE und C-Code

Als letztes ist nun der ESP32 via Arduino IDE zu programmieren.

Als Bibliotheken werden via „Sketch“ → „Bibliothek einbinden“ → „Bibliotheken verwalten“ die „WiFi“ Bibliothek (1.2.7) und die „Wire“ Bibliothek (1.0.0) installiert. Erstere ist für den WiFi-Zugriff, zweitere für den Zugriff auf die GPIO’s.

Als Nächstes ist der Quellcode zu erstellen. Dabei sind im Wesentlichen die PINs für den Trigger („Trig“ → triggerPin) und den Echo-Anschluss („Echo“ → echoPin) des HC-SR04 Ultraschallsensors, die WiFi-SSID (ssid[]), das WiFi-Passwort (pass[]), die IP von SmartHomeNG (host[]) und der Port des Webservices Interfaces in SmartHomeNG (port) zu setzen. Weiterhin ist der Itempfad desjenigen Items zu setzen, dass die Entfernung in Zentimeter aufnehmen soll (cm_item[]). Im Beispiel hat dieses Item den Pfad test.numeric.

Das zugehörige Item ist bei aktiviertem Webservices-Plugin wie folgt konfiguriert:

%YAML 1.1
---
test:

    numeric:
        type: num
        visu_acl: rw
        webservices_set: outside
        webservices_data: 'val'

Die Initialisierung der WiFi-Verbindung wird in der Methode setup aufgerufen. Des Weiteren werden dort die Input- und Output GPIO PINs gesetzt.

Die Methode initialise_wifi sorgt dafür, dass die WiFi Verbindung aufgebaut wird. Am Ende der Methode werden via print_wifi_status die Daten der Verbindung ausgegeben:

Attempting to connect to SSID: 
<wifi-name>
Connected to wifi
SSID: <wifi-name>
IP Address: 192.168.178.23
signal strength (RSSI):-77 dBm

#include <WiFi.h>
#include <WiFiClient.h>
#include <WiFiServer.h>
#include <WiFiUdp.h>
#include <Wire.h>

// PINs
const int triggerPin = 15;
const int echoPin = 4;

// VARs
const int runs = 3;

// Wifi
char ssid[] = "<wlan_id>";          // your network SSID (name)
char pass[] = "<wlan_password>";    // your network password
char host[] = "192.168.178.100";    // ip of service interface in SmartHomeNG
int port = 4321;                    // port of service interface in SmartHomeNG
char cm_item[] = "test.numeric";
int status = WL_IDLE_STATUS;
WiFiClient client;

void setup() {
  Serial.begin(19200);
  initialise_wifi();
 
  // PIN-Modes
  pinMode(triggerPin, OUTPUT);
  pinMode(echoPin, INPUT);
  digitalWrite(triggerPin, HIGH);
}

void loop() {
  float distance = get_distance();
  float avg_distance = get_distance_avg();
 
  Serial.write("distance: ");
  Serial.print(distance) ;
  Serial.write(" , avg. distance: ");
  Serial.print(avg_distance) ;
  Serial.write(" cm\n");
 
  Serial.println("\nStarting connection to server...");
  // Wenn die Verbindung möglich ist, Verbindungsdaten an Serial zurückgeben.
  while (client.available()) {
    char c = client.read();
    Serial.write(c);
  }

  if (client.connect(host, port)) {
    Serial.println("\nconnected to server");
    // HTTP Request gegen SmartHomeNG / das Webservices-Plugin durchführen
    char buffer[64];
    int ret = snprintf(buffer, sizeof buffer, "GET /ws/items/%s/%f HTTP/1.1", cm_item, avg_distance);
    Serial.println(buffer);
    client.println(buffer);
    client.println("Host: ");
    client.println();
  } 
  Serial.print("\n");
  // 1 Sekunde Warten
  delay(1000);
}

float get_distance() {
  float duration=0;
  float distance=0;
 
  digitalWrite(triggerPin, LOW);
  delayMicroseconds(2); 
  noInterrupts();
  digitalWrite(triggerPin, HIGH);
  delayMicroseconds(10);
  digitalWrite(triggerPin, LOW); 
  duration = pulseIn(echoPin, HIGH); // Erfassung - Dauer in Mikrosekunden 
  interrupts();

  distance = (duration / 2) / 29.1; // Distanz in CM
  return(distance);
}

float get_distance_avg() {
  float alt = 0;
  float avg;
  float dist;
  int i;

  delay(10);
  alt = get_distance();
  delay(10);
  for (i=0; i<runs; i++) {
    dist = get_distance();
    avg = (0.8*alt) + (0.2*dist);
    alt = avg;
    delay(10);
  }
  return (avg);
}

static void initialise_wifi(void)
{
  // Versuche ins WiFi Netzwerk zu verbinden
  while (status != WL_CONNECTED) {
    Serial.println("");
    Serial.println("Attempting to connect to SSID: ");
    Serial.println(ssid);
    // Ins WPA/WPA2 Netzwerk verbinden. 
    status = WiFi.begin(ssid, pass);
    // 10 Sekunden auf die Verbindung warten:
    delay(10000); 
  }
  Serial.println("Connected to wifi");
  print_wifi_status();
}

void print_wifi_status() {
  // SSID des WiFi Netzwerkes ausgeben:
  Serial.print("SSID: ");
  Serial.println(WiFi.SSID()); 

  // WiFi IP Adresse des ESP32 ausgeben:
  IPAddress ip = WiFi.localIP();
  Serial.print("IP Address: ");
  Serial.println(ip);

  // WiFi Signalstärke ausgeben:
  long rssi = WiFi.RSSI();
  Serial.print("signal strength (RSSI):");
  Serial.print(rssi);
  Serial.println(" dBm");
}

In der Methode loop findet nun die konkrete Ermittlung des Abstands statt. In der dort aufgerufenen Methode get_distance_avg() werden mehrere Messungen (runs) durchgeführt, um Messfehler zu minimieren. get_distance() wird zum Vergleich ebenfalls einzeln aufgerufen.

In jedem run wird in der Methode get_distance_avg() nun ebenfalls get_distance() aufgerufen. Dort findet der technische Teil des Messung statt: Zuerst wird der Trigger auf LOW gesetzt: digitalWrite(triggerPin, LOW);. Danach wird 2 Mikrosekunden gewartet und der Trigger auf HIGH gesetzt (digitalWrite(triggerPin, HIGH);). Nach erneutem Warten von 10 Mikrosekunden (erst nach dieser Zeit sendet der Sensor Ultraschallwellen) wird der Trigger wieder auf LOW gesetzt (digitalWrite(triggerPin, LOW);) und via duration = pulseIn(echoPin, HIGH); die Dauer zwischen Puls und Empfang des Echos gemessen. Während der Zeitmessung sollten Interrupts zudem abgeschaltet werden (noInterrupts();).
Zuletzt wird die Entfernung in Zentimetern, wie oben bereits erklärt, mit distance = (duration / 2) / 29.1; berechnet und zurückgegeben.

In get_distance_avg() wird dies nun mehrfach wiederholt und ein gleitender gewichteter Durchschnittswert (avg = (0.8*alt) + (0.2*dist);) gebildet. Werden dort trotzdem noch starke Abweichungen festgestellt, können bspw. die Anzahl der runs erhöht oder die Gewichtung verändert werden.

Das Ergebnis von get_distance_avg() wird dann via HTTP Get Request an das Webservices-Plugin (Simple Interface) und das konfigurierte Item übertragen. Auch diese Vorgänge werden im Code ausgegeben:

distance: 17.41 , avg. distance: 17.42 cm

Starting connection to server...
HTTP/1.1 200 OK
Content-Length: 65
Server: CherryPy/14.0.1
Content-Type: application/json
Date: Tue, 03 Apr 2018 19:31:48 GMT

{"Success": "Item with item path test.numeric set to 17.419243."}
connected to server
GET /ws/items/test.numeric/17.419930 HTTP/1.1

Wir das REST-Interface des Webservices-Plugins verwendet, so sieht der Codeblock zum Senden der Daten wie folgt aus:

#include <HTTPClient.h>
[...]
if (client.connect(host, port)) {
     HTTPClient http;    //Declare object of class HTTPClient
     char portStr[12];
     sprintf(portStr, "%d", port);
     char url[128];
     sprintf(url, "http://%s:%s/rest/items/%s", host, portStr, cm_item);
     http.begin(url);  //Specify request destination
     Serial.println(url);
     http.addHeader("Content-Type", "application/json");                //Specify content-type header
     char cmStr[12];
     sprintf(cmStr, "%f", cm);
     int httpCode = http.PUT(cmStr);                                    //Send the request
     String payload = http.getString();                                 //Get the response payload
     http.end();                                                        //Close connection
} 

Erster Programmstart und Test

Ist der ESP32 via USB verbunden, so kann das Programm über das „Haken“-Icon links oben auf Syntaxfehler geprüft und kompiliert und mittels des „Pfeil“-Icons daneben auf den ESP32 übertragen werden.

Gleichzeitig sollte vor einer Übertragung (und damit dem Programmstart) über „Werkzeuge“ → „Serieller Monitor“ der Monitor für die Testausgaben geöffnet werden.

Tipp: Plausible Distanzen kommen nur heraus, wenn der Sensor etwas erhöht, bspw. auf einer Kaffeetasse platziert wird. Anstonsten stören Reflektionen am Boden die Messwerte. Bei der Messung sollte daher generell beachtet werden, dass sich das Ultraschallsignal kegelförmig ausbreitet. Auf große Distanzen (> 1m) muss der Sensor so genau wie möglich auf das Zielobjekt ausgerichtet werden. Man sollte zudem Acht geben, dass das emittierte Signal auf einer möglichst parallelen Fläche reflektiert wird. Als Oberfläche für den Abprall der Impulse kann testweise bspw. ein Buch platziert werden. Die im Beispiel gemessenen 12,6 cm sind dabei bis auf ca. 5 mm genau.

Fazit

Mit dem ESP32 und einem HC-SR04 lässt sich für unter 20 Euro eine relativ genaue Abstandsmessung implementieren, die sehr simpel via WLAN an SmartHomeNG Daten sendet. Als Anwendungsfall wird die Installation im Sommer in meiner Zisterne installiert werden. Dazu folgt ein separater Bericht in diesem Blog.

Als Gehäuse für den HC-SR04 dient eine Vorlage von Thingiverse, die mittels 3D Drucker „gedruckt“ wurde:

Aber auch andere Sensoren lassen sich auf ähnliche Art und Weise kostengünstig und schnell verbauen und mit SmartHomeNG verbinden.

Für weniger versierte Programmierer bietet sich hier ESPEasy an, das Thema eines anderen Artikels ist.

Im zweiten Teil zum Thema wird erläutert, wie man die Entfernungsdaten auf ein OLED Display bringt. Direkteinstieg unter Entfernungsmessung mit ESP32 und SmartHomeNG Teil 2: Anbindung eines SSD1306 OLED Displays.

(Die in diesem Artikel verwendeten Screenshots und Fotos wurden selber erstellt. Für den Schaltplan wurde das Tool Fritzing verwendet.)

Dieser Artikel beschreibt, wie man Itemwerte von SmartHomeNG als ConnectIQ App auf Garmin Sportuhren bringt. Das Beispiel wurde dazu auf einer Garmin Fenix^® 5 erstellt und erprobt.

Weiterführend wäre auf die gleiche Art und Weise auch eine Steuerung von Hausfunktionen (bspw. Tor öffnen, wenn man vom Laufen zurück kommt) denkbar.

Die ConnectIQ App bedient sich dabei technisch der Garmin Connect App am Handy, um Anfragen auf Webservices von SmartHomeNG zu richten. Getestet wurde dies mit der Android Version dieser App.

Einrichten der Entwicklungsumgebung:

Als erstes muss die Entwicklungsumgebung aufgesetzt werden. Verwendet wird dabei die Software Eclipse, die im Bereich der Java Entwicklung sehr populär ist. Zum Stand dieses Artikel liegt sie in der Version Oxygen.3 Release (4.7.3) vor.

Nach erfolgter Installation, muss der ConnectIQ SDK von Garmin heruntergeladen und eingerichtet werden. Detaillierte Informationen dazu finden sich unter https://developer.garmin.com/connect-iq/programmers-guide/getting-started/ bzw. https://developer.garmin.com/connect-iq/sdk/.

Die Installation in Eclipse geht dabei gemäß dem ersten Link wie folgt:

Zuerst muss das Eclipse Plugin installiert werden:

1.  Im installierten Eclipse auf das „Help“ Menü klicken.
2. Dort „Install New Software…“ auswählen und den Knopf „Add…“ drücken.
3. Im nun folgenden Dialog die URL „https://developer.garmin.com/downloads/connect-iq/eclipse/“ als Name und Location eintragen (siehe Screenshot) und mit „OK“ bestätigen.
4. Im nun folgenden Fenster die Checkbox direkt neben „Connect IQ“ anhaken und auf „Next“ klicken.
5. Den Lizenzbedingungen zustimmen und „Finish“ anklicken.
6. Eclipse neu starten

Als nächstes muss das SDK heruntergeladen werden.

1. Auf das nun sichtbare Menüitem „Connect IQ“ klicken und „Open SDK Manager auswählen.
2. Dort nun das Ziel-Verzeichnis eintragen und beim jeweiligen SDK (idealerweise der aktuellste) den Knopf „Download“ bestätigen. Dabei müssen ebenfalls die Lizenzbedingungen bestätigt werden.
3. Sobald der Download erfolgt ist, „Yes“ anklicken um die SDK Version als aktiven SDK zu verwenden. Im Nachhinein kann die SDK Version aber auch noch gewechselt werden. Im Beispiel wurde der aktuellste SDK (2.4.4) gewählt.
4. Ist dies erfolgt, kann der SDK Manager geschlossen werden.

Projekt erstellen

Als nächstes muss über „File“ -> „New“ -> „Connect IQ Project“ ein neues Projekt erstellt werden.

Diesem gibt man dann einen Namen, bspw. „SmartHomeNG_on_a_Watch“ und bestätigt mit „Next“. Nun kann man den Project Type (hier: „Watch App“, die Version der App (hier: 0.0.0) und die minimale SDK Version setzen (hier: 2.4.x). Nach dem Bestätigen mit „Next“ wählt man „Simple“ als Template aus und bestätigt erneut.

Nun kommt die Wahl der unterstützten Geräte. Hier wird im Beispiel „Fenix^® 5 / quatix^® 5″ selektiert.

Bevor man „Finish“ klick sollte man noch über „Next“ die Sprache wählen. Im Beispiel wird hier „English (eng)“ selektiert.

Mit „Finish“ wird nun das Projekt angelegt und taucht nun links im Project Explorer auf:

Das Programm ausführen

Nun muss über Run -> Run Configuration das Projekt für die Ausführung konfiguriert werden.

Dazu ist wie oben zu sehen ein aussagekräftiger Name zu wählen („Fenix5 Configuration“). Die Projektzuordnung, das Target Device und die Target SDK Version sollten bereits stimmen. Mittels „Apply“ werden die Einstellungen gespeichert. Danach via „Close“ verlassen.

Nun muss noch der Simulator gestartet werden, entweder über das neue Icon in der oberen Iconleiste oder via „Connect IQ“ -> „Start Simulator“. Der Simulator startet als separates Fenster:

Über das bekannte Menü Run -> Run Configuration kann nun die Fenix5 Configuration gewählt und mittels „Run“ die Applikation gestartet werden.

Nach dem erfolgreichen Build ist nun die Dummy App auf dem Simulator zu sehen:

Anbindung von SmartHomeNG

Um SmartHomeNG anzubinden, ist nun folgendes zu tun:

Zuerst sind die anzuzeigenden Items in SmartHomeNG über das Webservices Plugin als Itemset zu definieren. Hier wurde als Setname „1“ gewählt. Details zum Webservices Plugin finden sich in diesem Artikel: https://www.smarthomeng.de/das-smarthomeng-webservices-plugin.

In diesem Set ist bspw. das Item eta_pu.temperature_outside.value. Um Übertragungszeit zu sparen, wurde hier val gesetzt:

eta_pu:
    temperature_outside:
        eta_pu_uri: '40/10241/0/0/12197'
        type: num

        value:
            eta_pu_type: calc
            type: num
            database@mysqldb: init
            webservices_set: 1
            webservices_data: 'val'

Nach einen Restart von SmartHomeNG sollte das Set wie in https://www.smarthomeng.de/das-smarthomeng-webservices-plugin erklärt, verfügbar sein.

Da ConnectIQ über die Garmin Connect App nur Requests gegen Internet Endpunkte machen kann, wurde ein SmartHomeNG vorgeschalteter NGINX wie folgt angepasst.

Tipp: Grundlegende Informationen zur Nutzung von NGINX als Reverse Proxy für SmartHomeNG und die smartVISU können unter https://www.smarthomeng.de/nginx-als-reverseproxy gefunden werden!

In der /etc/nginx/.shng sind dabei mit htpasswd ein Username und ein Passwort generiert worden. So steht der Endpunkt geschützt im Internet. Diese Daten müssen später in der ConnectIQ App eingetragen werden.

location /rest {
        auth_basic "Restricted Area: SmartHomeNG";
        auth_basic_user_file /etc/nginx/.shng;

        proxy_pass http://192.168.178.100:4321/rest;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

Anpassung des ConnectIQ Programms

Auf Site des zuvor angelegten ConnectIQ Programms müssen nun folgende Anpassungen gemacht werden.

Berechtigung für Webservice Aufrufe setzen

Damit die App berechtigt ist, Webservices aufzurufen, muss zuerst das Manifest File unter /manifest.xml editiert werden. Eclipse bietet dazu mit dem ConnectIQ Plugin einen Editor an. Ist die Datei geöffnet, so findet sich der entsprechende Menüpunkt im Reiter „Permissions“ etwa in der Mitte des Fensters. Dort ist „Communications“ anzuklicken und danach die Datei zu speichern.

SmartHomeNG_on_a_WatchApp.mc

Zuerst wird eine Konstante für den Internet Endpunkt angelegt, über den das Itemset erreichbar ist. In der Methode getInitialView wird ein „Loading“ Text ergänzt.
Der Zugriff gegen den REST Webservice wird in der Methode makeRequest gekapselt, die in der Methode onStart beim Start aufgerufen wird. makeRequest bekommt am ende onReceive als Callback mitgegeben. Hier findet das Parsen der JSON Antwort statt, welche danach an ein neues View übergeben wird. Der View schaltet direkt um (Ui.SLIDE_IMMEDIATE), so dass der Loading-Screen bei Antwort verschwindet.

using Toybox.Application as App;
using Toybox.WatchUi as Ui;

const URL = "https://<dyndnsurl>/rest/itemset/1";

class SmartHomeNG_on_a_WatchApp extends App.AppBase {

    function initialize() {
        AppBase.initialize();
    }

    // onStart() is called on application start up
    function onStart(state) {
    	makeRequest();
    }

    // onStop() is called when your application is exiting
    function onStop(state) {
    }

    // Return the initial view of your application here
    function getInitialView() {
        return [ new SmartHomeNG_on_a_WatchView("Loading"), new SmartHomeNG_on_a_WatchDelegate() ];
    }
    
    function onReceive(responseCode, data) {
       if (responseCode == 200){
           System.println("Request Successful, Data: "+data);                   // print success
           var tempValue = data["eta_unit.temperature_outside.value"];  
           var resultString = "Temperatur: "+tempValue.format("%.1f")+" °C\n";           
           var view = new SmartHomeNG_on_a_WatchView(resultString);
           var delegate = new SmartHomeNG_on_a_WatchDelegate();
           Ui.switchToView(view, delegate, Ui.SLIDE_IMMEDIATE);           
       }
       else {
           System.println("Response: " + responseCode + ", Data: "+data);            // print response code
       }
    }
   
    function makeRequest() {
       var url = URL;
       
       var params = null;
       
	   var headers = {
	   "Content-Type" => Communications.REQUEST_CONTENT_TYPE_JSON, 
	   "Authorization" => "Basic " + StringUtil.encodeBase64(Lang.format("$1$:$2$", [ "<user>", "<password>" ])),
	   "Accept" => "application/json"};
	   
       var options = {                                           
           :method => Communications.HTTP_REQUEST_METHOD_GET,  
           :headers => headers,                                                                 
           :responseType => Communications.HTTP_RESPONSE_CONTENT_TYPE_JSON
       };

       var responseCallback = method(:onReceive);                  // set responseCallback to 
                                                                   // onReceive() method
       // Make the Communications.makeWebRequest() call
       Communications.makeWebRequest(url, params, options, method(:onReceive));
    }
}

SmartHomeNG_on_a_WatchView.mc

In der zugehörigen View-Datei, wird die Variable _message definiert, die den Text mit dem Temperaturwert aufnimmt. Dieser wird in onLayout gerendert.
Damit dies geschehen kann, muss unter /resources/layouts/layout.xml zuerst ein Label mit ID message hinterlegt werden:

<layout id="MainLayout">
    <label id="message" x="center" y="25" font="Gfx.FONT_XTINY" justification="Gfx.TEXT_JUSTIFY_CENTER"></label>
</layout>

Der Code in SmartHomeNG_on_a_WatchView.mc sieht dann wie folgt aus:

using Toybox.WatchUi as Ui;

class SmartHomeNG_on_a_WatchView extends Ui.View {

    hidden var _message;
	
    function initialize(message) {
        View.initialize();
        _message = message;
        System.println(message);
    }

    // Load your resources here
    function onLayout(dc) {
        setLayout(Rez.Layouts.MainLayout(dc));
    	View.findDrawableById("message").setText(_message);
    }

    // Called when this View is brought to the foreground. Restore
    // the state of this View and prepare it to be shown. This includes
    // loading resources into memory.
    function onShow() {
    }

    // Update the view
    function onUpdate(dc) {
        // Call the parent onUpdate function to redraw the layout
        View.onUpdate(dc);
    }

    // Called when this View is removed from the screen. Save the
    // state of this View here. This includes freeing resources from
    // memory.
    function onHide() {
    }
}

Ausführen des fertigen Programms

Das Programm kann nun wie oben beschrieben über „Run -> Run Configuration“ als Fenix5 Configuration ausgeführt werden. Die Temperatur erscheint nun, sofern alles richtig gemacht wurde, im Emulator.

Wenn man die App auf die Uhr übertragen möchte, so geht dies über „Connect IQ“ -> „Build For Device Wizard..“. Mit einem entsprechenden Developer Key lässt sich nun eine Datei generieren, die auf der Uhr in das Verzeichns \GARMIN\APPS kopiert werden muss. Dies macht der Wizard gleich mit.

Zieht man danach die Uhr vom USB Port ab, kann die App gestartet werden.

(Die in diesem Artikel verwendeten Screenshots und Fotos wurden selber erstellt.)

Daneben verfügt das Webservices Plugin über eine webbasierte GUI, über die alle Items und die dazugehörigen Webservice-URLs angesehen werden können.

Die automatisch generierte Dokumentation findet sich unter http://smarthomeng.de/user/plugins_doc/config/webservices.html.

Der Sourcecode im Master-Branch von SmartHomeNG unter https://github.com/smarthomeNG/plugins/tree/master/webservices.

Support findet ihr im Forum unter: https://www.smarthomeng.de/?category_name=plugins&s=webservicessupport: https://knx-user-forum.de/forum/supportforen/smarthome-py/1163886-support-thread-f%C3%BCr-das-webservices-plugin.

Beispiele zur Nutzung sind in den Artikeln „SmartHomeNG on a Watch – Anbindung des Garmin ConnectIQ SSK an SmartHomeNG“ und „Entfernungsmessung auf Basis eines ESP32 und SmartHomeNG“ dargestellt.

Konfiguration

In der Datei etc/module.yaml sollte der Port für das Webservice-Interface gesetzt werden. Dies geschieht über die Angabe des servicesport:

# etc/module.yaml
http:
    class_name: http
    class_path: modules.http
    port: '1234'
    user: admin
    password: ''
    hashed_password: '...'
    servicesport: '4321'
    starturl: backend

Bei Bedarf eines Schutzes via Basic Authentication, kann zusätzlich noch der service_user, das service_password bzw. das service_hashed_password gesetzt werden:

    service_user: serviceuser
    service_password: ''
    service_hashed_password: 'xxx'

In der etc/plugin.yaml wird nun das Plugin aktiviert:

WebServices:
    class_name: WebServices
    class_path: plugins.webservices
    mode: set

Der mode lässt sich alternativ auf all setzen. Damit werden automatisch alle Items via Webservice-API verfügbar gemacht. Ist wie oben set gesetzt, müssen Items explizit freigegeben und zu sogenannten „Itemsets“ (Mengen von Items) gruppiert werden.

Ist dies geschehen, so wird das Plugin nach einem Neustart aktiv und kann verwendet werden. Im Beispiel set ist nun noch folgendes zu tun:

In der Definition der Items, muss das Attribut webservices_set gesetzt werden. Die Idee des Itemsets ist, dass man beispielsweise bei der Verwendung in einer Android oder iOS App nur einen Request pro Seite machen muss, auch wenn es mehrere Items gibt, die angezeigt werden soll. Items die zu einem Set gruppiert werden, lassen sich also über dieses gemeinsam via Webservice auslesen. Eine Seite der GUI in der App entspräche also einem Itemset.
Schreibend ist nur der Zugriff auf einzelne Items möglich. Alle Items die in Sets sind, sind auch einzeln lesend zugreifbar.

Ein Item kann zudem mehrere Sets haben, wie im Item MyItem2 unten verdeutlicht ist:

MyItem:
    type: str
    webservices_set: 'MySet1'
    webservices_data: 'val'

MyItem2:
    type: num
    webservices_set:
     - 'MySet1'
     - 'MySet2'
    webservices_data: 'full'

Das optionale Attribut webservices_data bedeutet folgendes: Ist hier nur val gesetzt, wird nur der Wert und der Pfad des Items im JSON Format zurückgeliefert. Dies dient bspw. bei mobilen Anwendungen der Reduzierung der Datenmenge.

Will man auch sämtliche Metadaten des Items haben, so setzt man full

Zugriff auf Items

Simple Webservice Interface

Das „Simple Webservices Plugin“ erlaubt lesenden und schreibenden Zugriff auf Items ausschliesslich über URLs als GET Request.

Lesend wird dabei nach folgendem Schema zugegriffen:

http://«your_server_ip»:«your_services_port»/ws/items/«item_path»

Ein Beispiel ist http://192.168.178.100:1234/ws/items/knx.gf.office.light

Will man einen Wert schreiben, so hängt man diesen URL-codiert einfach hinten an:

http://«your_services_port»/ws/items/«item_path»/«value»

Also beispielsweise http://192.168.178.100:1234/ws/items/office.light/0 oder http://192.168.178.100:1234/ws/items/office.light/False, was das Licht ausschaltet.

REST (compliant) Interface

Um auch den REST Standard zu unterstützen, gibt es weiterhin auch das REST Interface. Dieses verhält sich leicht anders, als das Simple Webservices Interface.

Lesend bleibt bis auf die URL alles beim Gleichen:

http://«your_server_ip»:«your_services_port»/rest/items/«item_path»

Analog zu oben also im Beispiel http://192.168.178.100:1234/rest/items/knx.gf.office.light

Schreibend müssen die Daten aber als HTTP Body in einem PUT oder POST Request übergeben werden, so wie es durch den REST Standard vorgegeben wird. Dabei ist sicherzustellen, dass im HTTP Header der Content-Type: application/json gesetzt ist.
Der Request wird dann direkt gegen die Basis URL des Items gesendet:

http://«your_server_ip»:«your_services_port»/rest/items/«item_path»

Ein POST/PUT Request mit 0 im HTTP Body an http://192.168.178.100:1234/rest/items/office.light ebenfalls das Licht ausschalten.

Testen lässt sich das Ganze dann beispielsweise mit dem Plugin Postman aus dem Chrome App Store (Link):

Die HTTP Methoden PATCH und DELETE werden zur Zeit noch nicht unterstützt!

Fehlerfall

Im Fehlerfall, etwa bei einem falschen oder nicht freigegebenen Itempfad, wird bei beiden Interfaces (REST und Simple) eine JSON Fehlermeldung zurückgegeben:

Itemsets (lesend) zugreifen

Sowohl via REST, als auch das Simple Webservices Interface lassen sich Itemsets lesend zugreifen.

Dies geschieht über folgende URL:

http://«your_server_ip»:«your_services_port»/ws/itemset/«set_name»

bzw.

http://«your_server_ip»:«your_services_port»/rest/itemset/«set_name»

Das Ergebnis sind die jeweiligen Daten der enthaltenen Items als Dictionary. Der key für den Zugriff ist dabei jeweils der Pfad des Items. Je nachdem, ob val oder full gesetzt ist, werden die Daten entsprechend gemerged:

Neben dem expliziten Zugriff auf die Itemsets, lassen sich auch alle (erlaubten) Items auf einmal abfragen:

http://«your_server_ip»:«your_services_port»/ws/items

bzw.

http://«your_server_ip»:«your_services_port»/rest/items

Für den Zugriff auf die Items im resultierenden JSON Dictionary, wird ebenfalls der Pfad des jew. Items verwendet.

Web GUI

Die Liste der zugreifbaren Items und Itemsets kann wie oben geschrieben auch via WebGUI abgerufen werden. Diese ist aus dem Backend-Plugin in der Pluginliste verlinkt.

In zukünftigen Artikeln wird die Nutzung des Webservices Plugins in Beispielapplikationen beschrieben.

Ein Proof of Concept existiert bereits für die ConnectIQ IDE (Garmin Uhren) und ein Projekt auf Basis eines ESP32. Hier kann unter https://www.smarthomeng.de/entfernungsmessung-auf-basis-eines-esp32-und-smarthomeng auch nachgelesen werden, wie sich die Daten via REST und Simple Webservices Interface aus C-Code heraus übertragen lassen. Auch ein erster Ansatz für ESPEasy wurde bereits umgesetzt.

(Die in diesem Artikel verwendeten Screenshots wurden selber erstellt. Das Titelbild ist unter der Creative Commons Zero (CC0) Lizenz veröffentlicht und wurde von www.pexels.com bezogen.)