quickStart

QuickStart

Der schnelle Weg zum Erfolg....

Installation der benötigten Softwarepakete
Clonen des OmniESP GitHub Repositories
Vorbereitung des Devices
OmniESP Setup (omniESP.json)
Device Setup (config.json / customDeviceSetup.h)
Projekt kompilieren
Flashen des ESP8266 (.bin & SPIFFS)
Serial-Debug
Web-Interface
MQTT
Einrichten des FHEM-Devices
Update der Firmware über das Web-Interface
geschafft....

1. Installation der benötigten Softwarepakete

Die Installation der benötigten Software ist im Kapitel 2. Installation der benötigten Softwarepakete beschrieben.

TOP

2. Clonen des OmniESP GitHub Repositories

Im GitKraken kann jetzt unter File/Clone Repo das OmniESP-Repositorie auf einen lokalen Speicherplatz geklont werden.

URL: https://github.com/Pfannex/OmniESP

Im GitKraken ist jetzt der gesamte Verlauf des OmniESP-Projektes zu sehen.

Im GitKraken kann jetzt der entsprechende tag oder der aktuelle branch ausgewählt werden. Hier empfiehlt es sich einen versionierten tag zu nutzen.

Wer später auch eigene Programmierungen verwirklichen möchte sollte sich einen Fork des OmniESP-Repositories anlegen. Um weiterhin auf dem Laufenden zu bleiben kann im eigenen Fork-Repositorie ein Remote-Clone des original OmniESP-Repositories angelegt werden. Jetzt können Teile des original OmniESP-Repositories in den eigen Fork "gemerged" werden.

Fork
cd [Verzeichnis des Forks]
git remote add parent https://github.com/Pfannex/OmniESP
git pull parent

TOP

3. Vorbereitung des Devices

Nach dem Clonen des OmniESP-Repositories kann das Verzeichnis in ATOM geöffnet werden.
Mit File/Open Folder.. kann das geklonte OmniESP-Repositorie geöffnet werden.

OmniESP wurde für die modulare Nutzung von unterschiedlichen Devices konzipiert. Im Auslieferungszustand befindet sich noch kein Device im Source-Ordner (src) und muss daher erst einmal "eingesteckt" werden.

Die Dateien des fertigen Devices befinden sich im Ordner _customDevices und
brauchen nur in die entsprechenden Ordner kopiert (Plug-In) werden.

Zum Testen bietet sich das Device SimpleSwitch an, dieses besitzt einen GPIO-Input für einen Button zur Steuerung eines Relaisausganges, einen GPIO-Output für die Ansteuerung eines Relais und einen weiteren GPIO-Output zur Ansteuerung einer Status-LED.

Quelle	Ziel
OmniESP\_customDevice\DeviceName\src\customDevice\.	OmniESP\src\customDevice
OmniESP\_customDevice\DeviceName\data\customDevice\.	OmniESP\data\customDevice
OmniESP\_customDevice\DeviceName\firmware\version.json	OmniESP\data\version.json
OmniESP\_customDevice\omniESP.json	OmniESP\data\omniESP.json

Im Ordner \doc befindet sich ggf. weiterführende Dokumentation.

Alle notwenigen Files befinden sich jetzt im Projekt und können genutzt werden.
The Device is plugged in!

Zum schnellen Wechsel (laden/sichern) der Devices kann auch der Rapidloader genutzt werden.

TOP

4. OmniESP Setup (omniESP.json)

Die Grundeinstellungen des Devices werden im Konfigurationsfile omniESP.json vorgenommen. Vorsicht bei manueller Änderung der Filestruktur, der Inhalt ist im json-File-Format abgelegt und darf nur unter Einhaltung der json-Syntax verändert werden. Fehlende Anführungszeichen oder Doppelpunkte etc. können dazu führen, dass der Konfigurationsfile nicht mehr gelesen werden kann.
Das Device würde unter Umständen nicht mehr starten oder sporadisch abstürzen.

{
  "device_name":            "",
  "device_username":        "admin",
  "device_password":        "admin",

  "wifi":                   "dhcp",
  "wifi_ssid":              "",
  "wifi_password":          "",
  "wifi_ip":                "",
  "wifi_netmask":           "",
  "wifi_gateway":           "",
  "wifi_dns":               "",

  "ap":                     "off",
  "ap_ssid":                "",
  "ap_password":            "admin",

  "lan":                    "off",
  "lan_ip":                 "",
  "lan_netmask":            "",
  "lan_gateway":            "",
  "lan_dns":                "",

  "ntp":                    "on",
  "ntp_serverip":           "europe.pool.ntp.org",

  "update_localpath":       "",
  "update":                 "manual",
  "update_remoteurl":       "",

  "mqtt":                   "off",
  "mqtt_ip":                "",
  "mqtt_port":              "",
  "mqtt_username":          "",
  "mqtt_password":          "",
  "mqtt_aliases":           "",

  "ftp":                    "off"
}

Alle Einstellungen in der omniESP.json können aber auch später aus dem Web-Interface heraus vorgenommen werden. Ohne gültige SSID für das Hauseigene WLAN-NETZ muss dann die Erstkonfiguration über das Web-Interface via Accesspoint erfolgen.

TOP

5. Device Setup (config.json / customDeviceSetup.h)

Neben der allgemeinen Konfiguration in der omniESP.json besitzt jedes Device noch zwei weitere Konfigurationsfiles config.json und customDeviceSetup.h.
Die config.json bietet die Möglichkeit, eigene Konfigurationseinstellungen im SPIFFS abzulegen.
In der customDeviceSetup.h werden Einstellungen für die jeweilige Geräteklasse hart kodiert. Im Wesentlichen sind dies die Zuordnung der GPIO-PINs oder aber auch devicespezifische #define Zuweisungen z.B. von Timern oder Zeitkonstanten.

//###############################################################################
// ESP8266
//###############################################################################
/*
GPIO WeMos ESPpin Function  Connection
 2   D4    17               PullUp
 0   D3    18               PullUp
 4   D2    19     SDA
 5   D1    20     SCL
 3   RX    21
 1   TX    22
15   D8    16     SS        PullDown
13   D7     7     MOSI
12   D6     6     MISO
14   D5     5     SCK
16   D0     4     SLEEP!
ADC  A0     2     Analog
*/


//###############################################################################
// GPIO
//###############################################################################

#define PIN_BUTTON 13
#define PIN_LED 4
#define PIN_RELAY 5

TOP

6. Projekt kompilieren

Nach dem Plug-In des Devices und der Konfiguration des WLAN-Zuganges kann jetzt der Erste Kompilationsdurchlauf gestartet werden.
Die Kompilierung wird über den Buildbefehl ATL+CMD+B gestartet.

Der kompilierte Code ist jetzt bereit zum Flashen!

TOP

7. Flashen des ESP8266 (.bin & SPIFFS)

Das Flashen des Devices erfolgt in ATOM in zwei Schritten.
Im Ersten Schritt muss das Serial-Peripheral-Interface-Flash-File-System oder kurz SPIFFS mit den Konfigurationsfiles und den Files für das Web-Interface beschrieben werden.
Der Upload des \data Verzeichnisses geschieht über den Befehl Alt+Cmd-T \ PIO Upload SPIFFS image.

Im zweiten Schritt muss jetzt die Firmware in den Flashspeicher des ESP8266 übertragen werden.
Der Upload der Firmware erfolgt über den Befehl Alt+Cmd+U.

Das SPIFFS und die Firmware sind fertig geladen!
Glückwunsch, das Device SimpleSwitch ist jetzt voll einsatzbereit!

Nicht vergessen das Device nach dem seriellen Flaschen einmal von Spannung zu nehmen bzw. eine Reset durchzuführen, das beugt lästiger Fehlersuche vor!

TOP

8. Serial-Debug

In PlatformIO ist ein Serial-Monitor integriert. Der serielle Monitor wird mit dem Befehl SHIFT+CMD+M gestartet. Bei angeschlossenem USB/RS232-Adapter oder eines WEMOS-D1-mini sollte der serielle Monitor den seriellen COM-Port anzeigen.

Um den vollständigen Startvorgang zu sehen muss das Device durch ein Reset neu gestartet werden.

Zum Debuggen kann der Compilerschalter DEBUG in der platformio.ini gesetzt werden.

build_flags = -Wl,-Teagle.flash.4m2m.ld -O2 -DDEBUG -DMQTT_MAX_PACKET_SIZE=2048

Danach plaudert das OmniESP munter vor sich hin.

TOP

9. Web-Interface

Das Web-Interface ist sehr vielseitig.

Unter dem Reiter Configuration können die notwendigen Grundeinstellungen des Devices vorgenommen werden.

Der Reiter Log liefert Informationen über die den Status der Device-Readings, zusätzlich werden die Events und das Device-Log angezeigt.

Im Dashboard können API-Calls abgesetzt werden und devicespezifische Funktionen dargestellt und gesteuert werden.

Das Dashboard kann im File data\customDevice\dashboard.json frei Konfiguriert werden! Siehe Dashboard-Entwicklung.

TOP

10. MQTT

Alle devicespezifischen Funktionen und Events stehen als MQTT-Topics zur Verfügung.
MQTT ist die Standardschnittstelle zur Außenwelt.

Screenshots MQTT-Spy:

TOP

11. Einrichten des FHEM-Devices

Für einige Devices wird unter _customDevice\<deviceName>\fhem\ eine Vorlage für die FHEM-Konfiguration mitgeliefert.
Die Beschreibung hierzu ist in den bereits fertigen Devices abgelegt.

Beispiel: SWA1

TOP