Motivation

Ziel ist der einfache Aufbau einer Web-Site zur Online-Manipulation der Konfigurationsdatendatei, wie sie von UrsSettings benötigt wird. Ebenfalls kann ein Neustart des Systems ausgelöst werden.

---

---

Configuration-Editor

Zur Nutzung dieses Systems ist eine HTML-Seite notwendig, die abgerufen werden kann und Platzhalter für die anzuzeigenden Informationen enthält. Hinzu kommt die Klasse UrsAsyncConfigEditorClass, die die Ansteuerung der Seite übernimmt. In der Web-Server-Klasse muss ein Instanz dieser Klasse angelegt und konfiguriert werden.

Die Website dient der Manipulation einer Konfigurationsdatendatei, die zum Füllen eines UrsSettings-Objekts dient (siehe ESP8266 UrsSettings: Alles nur eine Einstellungssache!). Über die Methode setSettings wird der Editor mit einer UrsSettings-Instanz verknüpft. Diese Instanz liefert den Dateinamen der Konfigurationsdatendatei. Beim Abruf der Seite wird die Datei ausgelesen und zur Anzeige gebracht. Nach dem Zurückspeichern der Daten wird auch ein Refresh des UrsSettings-Objekts veranlasst.

Über die Ereignisse (Callback-Funktionen) ConfigStart und ConfigChanged kann das umgebende Programm auf den Aufruf der Seite und auf das Zurückspeichern der Konfigurationsdaten reagieren.

Funktionseinheiten

Die Funktionsweise des SPIFFS-Editors kann man am besten elementweise am Zusammenspiel der Komponenten der HTML-Seite und der UrsAsyncConfigEditorClass erklären. Die Funktionseinheiten:

0. Verknüpfung mit einem UrsSettings-Objekt

Die Website dient der Manipulation einer Konfigurationsdatei, die zum Füllen eines UrsSettings-Objekts dient (siehe ESP8266 UrsSettings: Alles nur eine Einstellungssache!). Über die Methode setSettings wird der Editor mit einer UrsSettings-Instanz verknüpft. Wird die Seite abgerufen, bevor ein UrsSettings-Objekt mit dem Editor verknüpft wurde, wird eine Fehlerseite (Code 404) zurück geliefert:

// Ohne hinterlegtes Settings-Objekt ist dieser Aufruf nicht sinnvoll
if (settings == NULL) {
  request->send(404, String(), F("Kein Außensteuerungsobjekt vorhanden!"));
  return;
}

1. Name der Konfigurationsdatendatei

Für den Namen der Konfigurationsdatei der Platzhalter %filename% zur Verfügung. Im Musterdokument wird er in ein einfaches Paragraph-Element eingebunden:

<p>%filename%</p>

Der Name wird der verknüpften UrsSettings-Instanz entnommen.

2. Anzeige und Änderung der Konfigurationsdaten

Die Anzeige der Daten geschieht in einem Textfeld eines Formulars. Der Platzhalter %config% wird vom Editor mit dem Datei-Inhalt gefüllt .

<!-- Formular zum Editieren und Speichern der Einstellungsdaten -->
<form action="config.html" method="POST">
  <textarea cols="50" name="config" rows="20">%config%</textarea>
  <p><button type="submit">Speichern</button></p>
</form>

Das Textfeld (Tag <textarea>) ist im Browser editierbar. Die Attribute cols und rows geben die Breite und Höhe des Anzeige-Fensters vor. Bei Bedarf werden Scroll-Leisten eingeblendet.

3. Zurückspeichern der geänderten Konfigurationsdaten

Das Zurückspeichern wird über in das Formular integrierte Schaltfläche ausgelöst. Ein HTTP-Request vom Typ POST mit dem Query-Parameter "config" führt zum Speichern der neuen Konfiguration. "config" ist der Name des Textfeldes Der Parameter-Wert ist der geänderte Inhalt des Feldes.

Nach dem Speichern der Datei wird das übergebene UrsSettings-Objekt neu geladen, so dass über dieses Objekt die geänderten Informationen bereit stehen. Danach wird die per onConfigChanged registrierte Callback-Funktion aufgerufen.

Für den Fall eines Fehlers wird eine entsprechende Rückmeldung gegeben:

request->send(200, String(), String(F("Fehler: '")) + settings->getFileName() 
                                                    + String(F("' kann nicht beschrieben werden!")));

Die Callback-Funktion wird in diesem Fall nicht aufgerufen.

4. System-Restart

Der HTML-Code enthält zum Schluss das Formular mit der Schaltfläche "Neustart". Diese löst einen erneuten Abruf der Seite mit dem Query-Parameter "reboot" aus.

<form action="spiffs.html" method="POST">
  <p><input name="reboot" type="submit" value="ESP&nbsp;&nbsp;Neustart"></p>
</form>

Die UrsAsyncSpiffsEditorClass  reagiert darauf indem UrsAsyncWebServer::shouldReboot auf true gesetzt wird. Außerdem wird eine entsprechende Meldung an den Browser zurück gesandt. Das Hauptprogramm sollte darauf hin einen Neustart des Prozessors durch führen wie bei UrsAsyncWebServer: Restart-Steuerung beschrieben.

// POST mit Parameter "reboot" führt zum Neustart 
// =======================================================================
if (request->hasParam("reboot", true)) {
  UrsAsyncWebServer::shouldReboot = true;
  request->send(200, String(), F("Neustart des Servers ausgelöst"));
  return; // fertig
}

Die Rückmeldung, die der Browser nach einer Restart-Anforderung erhält, sieht in etwa so aus:

Ereignisse

Über on...() können Callback-Methoden registriert werden, die bei den entsprechenden Ereignissen aufgerufen werden. Diese Callback-Methoden werden vom  Request-Handler aufgerufen, befinden sich also noch im Kontext des AsyncWebServer und müssen dessen Regeln einhalten. D.h. kein Aufruf von yield() (weder direkt noch indirekt, z.B. durch Aufruf von delay()) und wegen des asynchronen Aufrufs: keine zu lang dauernde Code-Sequenzen. Sollten größere Aktionen notwendig sein, empfiehlt es sich eine entsprechende Variable zu belegen, diese in loop() abzufragen und dort die Aktion ausführen (siehe z.B. oben Abschnitt System-Restart).

Ereignis	Registrierung	Funktionstyp
Bevor die Konfigurationsdaten per Web-Site geändert werden.	onConfigStart	EvConfigStartHandler
Nachdem die Konfigurationsdaten per Web-Site geändert wurden.	onConfigChanged	EvConfigChangedHandler

Die beiden Funktionstypen sind wie folgt definiert:

• typedef std::function<void(void)> EvConfigStartHandler;
• typedef std::function<void(UrsSettingsBaseClass * settings)> EvConfigChangedHandler;

Platzhalterübersicht

Platzhalter	Wert
%filename%	Der Name der Datei mit den Einstellungsparametern.
%config%	Der Dateiinhalt.
%title%	Einstellbar über setConfigTitle(). Default: "Außensteuerung".
%headline%	Einstellbar über setConfigHeadline(). Default: "Außensteuerung".

Query-Parameter

Der Webserver reagiert auf drei Query-Parameter:

• config=<Dateiinhalt> bewirkt bewirkt das Speichern von Dateiinhalt in der angezeigten Datei.
• reboot=<beliebig> bewirkt, dass shouldReboot auf true gesetzt wird.