omniesp

OmniESP Funktionen

3.2 OmniESP Funktionen
- Kommunikationsstruktur
- WiFi StateMachine

Kommunikationsstruktur

Wesentlicher Bestandteil des OmniESP-Frameworks ist die universelle Kommunikationsstruktur. Unser Ziel war es, sowohl die interne als auch die externe Kommunikation nach dem gleichen Schema abzuarbeiten. Hieraus ist die auf Topics basierende Kommunikationsstruktur entstanden.
Bei der externen Kommunikation haben wir uns für MQTT entschieden. Daher lag es nahe, die MQTT-Topics hierfür als Standardinformationsträger sowohl für die externe als auch für die interne Kommunikation zu nutzen.

Ein Topic ist immer eine Hierarchiestruktur nach folgender Syntax:
[Topic] [Argument], wobei das Argument optional ist.

Beispiele:

Topic	Funktion
`Node52/get/ffs/cfg/root`	Liefert als Antwort den root-String der OmniESP.json vom Device mit dem Namen `Node52`; ein Argument ist nicht notwendig.
`Node52/set/ffs/cfg/item/wifi_ssid MySSID`	Schreibt eine neue WiFi-SSID in die OmniESP.json vom Device mit dem Namen `Node52`

Die Kommunikationsstruktur basiert auf drei Arten von Topics:

set
get
event

Der Name des Device ist immer erforderlich, wenn MQTT für die Kommunikation benutzt wird. Wenn Topics direkt an das Device gegeben werden, also über das Webinterface oder das Web-API, dann kann der Name beliebig sein. Im folgenden verwenden wir für den Namen stellvertretend eine Tilde ~.

TOP

set-command - `~/set/..`

Mit dem set-command werden aktiv Funktionen innerhalb des Frameworks aufgerufen. Die ankommenden set-Topics werden zerlegt und dem Empfänger im Device über den Controller zugestellt.

Die entsprechenden set-commands für das Device müssen vom Entwickler des Devices ausprogrammiert werden.
String customDevice::set(Topic &topic) { }

Beispiel:

Topic	Funktion
`~/set/ffs/cfg/item/wifi_ssid MySSID`	Wird an die Klasse `ffs` zur weiteren Bearbeitung durchgereicht und ausgeführt.
`~/set/device/relay 1`	Wird an die Klasse `device` zur weiteren Bearbeitung durchgereicht und ausgeführt.

TOP

get-command - `~/get/..`

Mit dem get-command werden aktiv Informationsanfragen innerhalb des Frameworks gestellt. Die ankommenden get-Topics werden zerlegt und dem Empfänger über den Controller zugestellt.

Die entsprechenden get-commands für das Device müssen vom Entwickler des Devices ausprogrammiert werden.
String customDevice::get(Topic &topic) { }

Beispiel:

Topic	Funktion
`~/get/ffs/cfg/item/wifi_ssid`	Wird an die Klasse `ffs` zur weiteren Bearbeitung durchgereicht. Im Rückgabewert der Topicanfrage befindet sich dann die angefragte Information.
`~/get/device/button`	Wird an die Klasse `device` zur weiteren Bearbeitung durchgereicht. Im Rückgabewert der Topicanfrage befindet sich dann die angefragte Information.

TOP

event-information - `~/event/..`

Alle Arten von Ereignissen innerhalb des Frameworks und innerhalb des Devices werden über das event-Topic der Umwelt mitgeteilt. So kann innerhalb und außerhalb des Frameworks eine Event-getriggerte Kommunikationsstruktur aufgebaut werden. Alle publizierten Events werden auch an die View-Objekte MQTT und WebIf weitergereicht.

Die entsprechenden event-infomations für das Device müssen vom Entwickler des Devices ausprogrammiert werden.
void customDevice::on_events(Topic &topic) { }

Beispiel:

Topic	Funktion
`~/event/wifi/wl_connected`	Die WiFi-Verbindung wurde erfolgreich hergestellt.
`~/event/mqtt/connected`	Der MQTT-Client hat sich erfolgreich mit dem Broker verbunden.

TOP

WiFi StateMachine

Ist eine WLAN-Verbindung möglich wird diese genutzt (STA-Mode), wenn nicht wird ein Accesspoint aufgespannt (AP-Mode). Zusätzlich kann das Aufspannen des Accesspoints auch durch den ConfigMode erzwungen werden.

Restriktionen: Der STA-Mode und der AP-Mode können nicht parallel betrieben werden. Ist der AP-Mode auf ON geschaltet, hat dieser Vorrang vor dem STA-Mode. Der STA-Mode kann dann nicht genutzt werden.

Daraus ergeben sich folgende Konfigurationsmöglichkeiten:

Mode	AP-Mode	STA-Mode	Funktionen
1	OFF	OFF	AP-Mode und STA-Mode sind aus !ACHTUNG! WiFi kann dann nur über das manuelle Flashen der OmniESP.json wieder aktiviert werden!
2	OFF	DHCP	WiFi-Verbindung im STA-Mode wird aufgebaut (IP-Adresse wird vom DHCP-Server zugewiesen), AP-Mode ist aus
3	OFF	Manual	WiFi-Verbindung im STA-Mode wird aufgebaut (statische IP-Adresse aus OmniESP.json), AP-Mode ist aus
4	ON	OFF	AP-Mode ist dauerhaft an, Beenden nur über Reboot, STA-Mode ist aus
5	ON	DHCP	AP-Mode ist dauerhaft an, Beenden nur über Reboot, STA-Mode wird verhindert
6	ON	Manual	AP-Mode ist dauerhaft an, Beenden nur über Reboot, STA-Mode wird verhindert
7	AUTO	OFF	schaltet AP-Mode an, der dauerhaft an bleibt, Beenden nur über Reboot, STA-Mode ist aus
8	AUTO	DHCP	WiFi-Verbindung im STA-Mode wird aufgebaut (IP-Adresse wird vom DHCP-Server zugewiesen), AP-Mode startet, wenn STA-Mode nicht aufgebaut werden kann oder die Verbindung verliert
9	AUTO	Manual	WiFi-Verbindung im STA-Mode wird aufgebaut (statische IP-Adresse aus OmniESP.json), AP-Mode startet, wenn STA-Mode nicht aufgebaut werden kann oder die Verbindung verliert

TimeOut-Handling:

staTimeout: Kann im STA-Mode keine Verbindung aufgebaut werden (WL_CONNECT_FAILED, WL_NO_SSID_AVAIL), wird nach staTimeout der STA-Mode verlassen und der AP-Mode gestartet. Ist in der OmniESP.json keine SSID konfiguriert, wird der AP ohne Verzögerung gestartet.
apTimeout: Ist eine Station mit dem AP verbunden (AP_OPEN_WITH_STATION), kann der AP-Mode nur durch einen Reboot durch den User beendet werden. Ohne verbundene Station (AP_OPEN_WITHOUT_STATION), wenn AP-Mode = AUTO, wird der AP-Mode nach eingestelltem apTimeout beendet und ein staReconnect versucht. Ist in der OmniESP.json keine SSID konfiguriert, wird der AP-Mode nicht beendet.

TOP