RadioShuttle Sketch-Installation für ESP32

Dieses Kapitel behandelt die Installation von RadioShuttle-Sketches. Informationen zum „ECO Power“-Board finden Sie hier. Für Hinweise zur Inbetriebnahme lesen bitte dieses Kapitel.

RadioShuttle Library installieren

Die komplette RadioShuttle-Software wird in einem Zip-Archiv ausgeliefert und kann unter Angabe der Board-ID hier geladen werden. Die ID finden Sie auf der Platinenrückseite, z.⁥ B. 5678.
Geladen wird ein Zip-Archiv mit der aktuellen Software, z.⁥ B. „RadioShuttle-Arduino-2018-05-10.zip“.
Das Zip-Archiv muss entpackt und der Inhalt des Ordners „libraries“  in den Ordner „Documents/Arduino/libraries“ kopiert werden.

Hinweis: Bei einer bereits vorhandenen RadioShuttle-Library muss der Inhalt komplett überschrieben werden (nicht mergen)!

Nach dem Kopieren sollte im Ordner „libraries“ Folgendes zu sehen sein:

  • „Adafruit_Si7021“ (Library für den Temperatur-/Luftfeuchtigkeitssensor)
  • „Arduino-mbed-APIs“ (zusätzliche Treiber und neue Timer-Funktionen für den ESP32- und D21-Chip)
  • „ds3231“ (Library für die RTC-Uhr des „ECO Power“-Boards)
  • „OLED“ (Library für den SSD1306-Bildschirm, z. B. Heltec LoRa-Board (siehe Tech Info „ECO Power“-Board mit OLED-Display betreiben)
  • „RadioShuttle“ (Funkprotokollsoftware und Beispiele)
  • „RTCZero“ (RTC-Library für den Atmel D21-Chip)
  • „SX1276GenericLib“ (Treiber für den LoRa-Funkchip)

PinMap.h anpassen

Die Datei „PinMap.h“ definiert die Anschlussverbindungen der ESP32 MCU mit dem Funkchip und der übrigen Peripherie. Sie muss für jedes Programm, das neu installiert wird, überprüft und ggf. angepasst werden. Man findet sie in der Arduino IDE oben als zusätzlichen Reiter.

Damit Programmcode und Board-Revision zusammen passen, suchen Sie nach #elif defined(ARDUINO_ESP32_DEV) und stellen sicher, dass diese Zeile aktiv ist. Sollten Sie eine andere Version des „ECO Power“-Boards besitzen, aktivieren Sie die entsprechende Zeile und deaktivieren Sie ggf. die ältere „ECO Power“-Revision:
#define ESP32_ECO_POWER_REV_1 // our rev1 ESP32 ECO Power Boards

Beispielanwendung „PropertyEditor“

Es gibt einen Speicher, in dem Einstellungen, die nach einer neuen Programminstallation („Sketch“) auf dem Board erhalten bleiben sollen, permanent gespeichert werden können. Hier bietet es sich an, Einstellungen wie WiFi-Zugangsdaten o.⁥ ä. zu speichern. Das Programm „PropertyEditor“ erlaubt es Ihnen, eigene Werte für Properties in den Speicher zu schreiben. Auf der Seite Permanentspeicher für Einstellungen finden Sie Hintergrundinformationen zu den unterschiedlichen Speicherorten sowie eine Übersicht aller verfügbaren Properties.

Nach dem Start der Arduino IDE muss für das „ECO Power“-Board unter „Werkzeuge > Board“ der Eintrag „ESP32 Dev Module“ ausgewählt werden, da die Arduino IDE immer nur die Libraries anzeigt, welche auf dem aktuell ausgewählten Board lauffähig sind.

Anschließend kann das Beispiel „PropertyEditor“ über den Menüpunkt „Datei > Beispiele > Arduino-mbed-APIs > PropertyEditor“ in die Arduino IDE geladen werden.

Öffnen Sie das Fenster „Serieller Monitor“ (siehe Arduino-Fenster „Serieller Monitor“ öffnen unten) und laden Sie den „PropertyEditor“-Sketch mit der Upload-Funktion auf das „ECO Power“-Board. Wenn alles geklappt hat, sollten Sie diesen Text im Fenster sehen:

Zum Auflisten aller verfügbaren Properties geben Sie in der Eingabezeile „l“ (für list) ein, wie im Bild oben zu sehen, und klicken Sie auf die Schaltfläche „Senden“:

Um einen Wert für eine Property zu setzen, müssen Sie in der Eingabezeile ein „s“ (für set), gefolgt von der Nummer der Property und deren Wert eingeben. Klicken Sie dann auf die Schaltfläche „Senden“. In diesem Beispiel soll der Property „WIFI_SSID“ (Nummer 30) der Wert „radioshuttleuser“ zugeordnet werden:

Nach einem erneuten Listenaufruf ist zu erkennen, dass die Property „WIFI_SSID“ mit dem Wert „radioshuttleuser“ belegt wurde:

Durch Eingabe des Befehls „d“ (für delete) lassen sich einzelne Properties aus dem Speicher löschen.

Properties für „RadioTest“ definieren

Eine einfache RadioShuttle-Testanwendung („RadioTest“) ist für den Einstieg gedacht. Es gibt zwei Geräte, die miteinander kommunizieren und eine einfache Nachricht austauschen. Ein Gerät nennt sich Knoten und das zweite ist eine Station. Per Tastendruck („User“-Taste) wird eine Nachricht vom Knoten zur Station übertragen. Das geht auch umgekehrt, die Station kann auch eine Nachricht an den Knoten übertragen.

Für die Beispielanwendung „RadioTest“ müssen mindestens folgende Properties mit dem PropertyEditor gesetzt werden:

Property Typ Erklärung
LORA_DEVICE_ID T_32BIT Geräte-ID des Boards (voreingestellt)
LORA_CODE_ID T_32BIT Code des Boards (voreingestellt)
LORA_RADIO_TYPE T_32BIT Art der Nutzung (nicht gesetzt):
1 = Node offline (Betrieb als Funksensor im „deepsleep“-Modus)
3 = Node online (Betrieb als Funksensor, permanent empfangsbereit)
4 = Station Basic (Betrieb als Server für kleine Netzwerke)
5 = Station Server (Betrieb als Server für größere Netzwerke)
LORA_REMOTE_ID T_32BIT Kommunikations-ID der Gegenstelle (nicht gesetzt)
LORA_APP_PWD
(optional)
T_32BIT Beschränkt die Kommunikation auf Boards mit demselben Passwort

Wenn „LORA_REMOTE_ID“ und „LORA_RADIO_TYPE“ nicht gesetzt sind, und #define USE_DEMOBOARD_PAIR in der Datei „RadioTest.ino“ aktiv ist, wird ein Demo-Testbetrieb zwischen den beiden Boards genutzt (siehe RadioTest.ino anpassen unten).

Beispielanwendung „RadioTest“ aktivieren

Nach dem Start der Arduino IDE muss für das „ECO Power“-Board unter „Werkzeuge > Board“ der Eintrag „ESP32 Dev Module“ ausgewählt werden, da die Arduino IDE immer nur die Libraries anzeigt, welche auf dem aktuell ausgewählten Board lauffähig sind.

Laden Sie das Beispiel „RadioTest“ über den Menüpunkt „Datei > Beispiele > RadioShuttle > RadioTest“ in die IDE. Mit diesem Beispielprogramm kann man Nachrichten von einem Knoten zu einer Station oder umgekehrt verschicken. Es besteht aus den Dateien „PinMap.h“, „RTCUtil.cpp“ und „RadioTest.ino“.

Folgende Anpassungen müssen vor der Verwendung überprüft bzw. vorgenommen werden:

RadioTest.ino anpassen

Die Zeile: #define USE_DEMOBOARD_PAIR kann wie folgt auskommentiert werden:
// #define USE_DEMOBOARD_PAIR

Sie diente dazu, die ausgelieferten Boardpärchen automatisch aufeinander abzustimmen.

Beispielanwendung „RadioTest“ prüfen

Einfach am Knoten die „User“-Taste drücken. Daraufhin wird eine Netzwerknachricht vom Knoten zum Server geschickt. Bei der Nachrichtenübertragung sollten die Sende- und Empfangs-LEDs kurz blinken. Das ist auch umgekehrt möglich, indem am Server die „User“-Taste gedrückt wird und der Knoten eine Nachricht empfangen sollte.

Zusätzlich werden die Nachrichten im Konsolenfenster „Serieller Monitor“ angezeigt.

Arduino-Fenster „Serieller Monitor“ öffnen

Es empfiehlt sich, das Arduino-Konsolenfenster „Serieller Monitor“ immer geöffnet zu haben, da hier wichtige Meldungen angezeigt werden. Voraussetzung ist natürlich ein angeschlossener Programmieradapter. Auch Reset-Meldungen wie Watchdog-Reset, Stromausfall-Reset (Brownout) und Bootmeldungen werden dort angezeigt.

Empfangene RadioShuttle-Meldungen und versendete Nachrichten werden hier ebenfalls angezeigt. Über die Funktion EnablePacketTrace() kann die Protokollierung von Meldungen abgestellt bzw. angepasst werden.

Sollte das Fenster „Serieller Monitor“ erst später geöffnet werden, sind vorherige Meldungen natürlich nicht sichbar.

Beispiel A: Erfolgreicher Start der RadioShuttle-Software

Unmittelbar nach Start oder Reset des Boards sollte im Fenster „Serieller Monitor“ eine Meldung ähnlich der obigen zu sehen sein. Wichtige Parameter, wie z.⁥ B. Frequenz, Bandbreite sowie der Spreading-Faktor sind ersichtlich. Die „TimeOnAir“-Meldung signalisiert, wie lange die Daten mit den eingestellten Parametern unterwegs sind. Die Uhrzeit wird, falls vorhanden, von der RTC-Zeit übernommen, ansonsten wird die Compile-Zeit genutzt. Wichtig ist auch die Information der Knotennummer (hier „ID=201“) sowie die Einstellung, ob das System als Knoten („Node“) oder Station läuft.

Beispiel B: Nachricht erfolgreich versendet

Nach Drücken der „User“-Taste wurde eine Testnachricht an einen zweiten Knoten gesendet. Dieser hat den Empfang bestätigt.

Beispiel C: Time-out beim Verschicken einer Nachricht

Nach Drücken der „User“-Taste wurde eine Testnachricht gesendet. Der Empfang wurde aber nicht bestätigt. Nach drei Versuchen wird dieser Vorgang abgebrochen und eine Time-Out-Fehlermeldung („MSG_SentTimeout“) erscheint.

LED-Zustände im Beispiel „RadioTest“

LED 2 (grüne LED rechts):

  • Aus 
    Das Board hat keinen Strom oder es befindet sich im „deepsleep“-Modus
  • Blinkt kurz alle 10 Sekunden
    Das Board läuft und befindet sich im ESP32 „deepsleep“-Modus, um möglichst wenig Energie zu verbrauchen, der Prozessor wird dabei weitgehend abgeschaltet. Das kuze Aufblinken signalisiert, dass es regelmäßig aktiv wird um zu prüfen, ob es etwas zu tun gibt
  • Leuchtet permanent schwach 
    Das Board ist aktiv und arbeitet in der Arduino „loop“ Ergeignisse ab. Danach nutzt es einen einfach „sleep“ und wird ca. 1000 mal pro Sekunde durch das Betriebssystem aufgeweckt
  • Flackert etwas
    Hiermit wird der Empfang von LoRa-Funkdaten signalisiert
  • Dauerhaft an
    Das Board ist aktiv und arbeitet in der Arduino „loop“. Während diese durchläuft, ist die LED an; wenn also die „loop“ permanent aktiv ist (Dauerläufer), leuchet die LED durchgängig. Für den energieoptimierten Einsatz sollte die „loop“ natürlich so wenig wie möglich laufen bzw. nur wenn es etwas zu Verarbeiten gibt. Stichwort: kein Polling

LED 1 (rote LED links):

  • Aus 
    Im Regelfall leuchet die rote LED nicht, kann aber vom Anwender genutzt werden
  • Flackert etwas
    Beim Senden von LoRa-Funkdaten leuchtet die rote LED – abhängig von der Datenlänge – kurz auf. Dies passiert während des Sendens bei jeder Nachricht

Natürlich lassen sich die LEDs vom Anwender auch indivuell oder zusätzlich nutzen.

Permanentspeicher für Einstellungen

Es gibt einen Speicher, in dem Einstellungen, die nach einer neuen Programminstallation („Sketch“) auf dem Board erhalten bleiben sollen, permanent gespeichert werden können. Hier bietet es sich an, Einstellungen wie WiFi-Zugangsdaten o.⁥ ä. zu speichern. Die Beispielanwendungen „PropertyEditor“ und „PropertyTest“ (siehe Tabelle unten) können dazu verwendet werden. Die Seite Permanentspeicher für Einstellungen erklärt dies detailliert.

Übersicht aller Beispielanwendungen

Name Library Erklärung
Blinky Arduino-mbed-APIs Periodisches Blinken einer LED
BlinkyEnhanced Arduino-mbed-APIs Timergesteuertes Blinken einer LED
BlinkyEnhanced_C_Plus_Plus Arduino-mbed-APIs Timergesteuertes Blinken einer LED (in C++)
CPUBench Arduino-mbed-APIs Misst die Float- und Integer-CPU-Leistung
DisplayI2CSample Arduino-mbed-APIs Verwendung eines OLED-Displays (128×64 Pixel, I2C). Siehe „ECO Power“-Board mit OLED-Display betreiben
ESP32AsyncHTTPClient Arduino-mbed-APIs Ein einfaches HTTP-Clientprogramm, das einen HTTP GET– oder POST-Request ausführt. Das ganze passiert asynchron ohne die Arduino-Hauptschleife (loop) zu blockieren
ESP32BlinkyDeepSleep Arduino-mbed-APIs „deepsleep“-Beispiel (geringer Energiebedarf); blinkt alle 10 Sek. während des „deepsleep“, LED2 blinkt jede Minute beim Wakeup
ESP32FrequencyThrottle Arduino-mbed-APIs MCU-Prozessortaktung auf 2 MHz herabsetzen um Energie zu sparen
ESP32MQTTAlarmSystem Arduino-mbed-APIs Kleines Alarmsystem, das per Bewegungsmelder einen Alarm über MQTT auslöst, inklusive Status- und Temperaturdaten per Display
ESP32MQTTClient Arduino-mbed-APIs Stellt eine WiFi-Verbindung zu einem MQTT-Broker her, verschickt Nachrichten dorthin und empfängt registrierte Topics vom Broker
ESP32RadioShuttleMQTT Arduino-mbed-APIs Empfängt Daten von Knoten und leitet diese an einen MQTT-Broker weiter. Empfangene MQTT-Nachrichten können an LoRa-Knoten weitergeleitet werden
HelloWorld Arduino-mbed-APIs Einfaches Ausgabebeispiel; erläutert verschiedene „printf“-Optionen
PropertyEditor Arduino-mbed-APIs Programm zum Setzen von Einstellungen (Properties), welche im Board permanent gespeichert werden. Bleiben nach dem Neustart bzw. auch nach dem Aufspielen eines neuen Programms erhalten. Siehe auch Permanentspeicher für Einstellungen
PropertyTest Arduino-mbed-APIs Zeigt, wie Properties, z.⁥ B. Strings und Nummernwerte in permanentem Flash-Speicher für die Verwendung in Sketches gespeichert werden können. Siehe auch Permanentspeicher für Einstellungen
RTC3231Calibration Arduino-mbed-APIs Kalibrierungswerkzeug zum Messen von Frequenzfehlern der RTC des „ECO Power“-Boards
TimerTest Arduino-mbed-APIs Beispiel, welches mehrere asynchrone Timer aufruft, die Erledigungsfunktionen aufrufen, wenn ein Timeout ansteht. Arbeitet präzise und energiesparend
PMSensorRadio RadioShuttle Umweltsensor; misst periodisch die Staubkonzentration in µg/m3 (nach PM10- und PM2.5-Standard)
RadioTest RadioShuttle Siehe detailliertes Beispiel oben

PDF-Datenblatt