WiFiThermostat/docs/ESP8266-WiFi-Thermostat.txt

ESP8266-WiFi-Thermostat und Raumsensor
======================================

Einfacher WiFi-fernsteuerbarer Thermostat aus billigen Komponenten

Ziel war die Entwicklung eines auf wesentliche Funktionen reduzierten Raumthermostat, der über WiFi an ein 
Netzwerk angebunden und fernbedient werden kann. Der Aufbau sollte möglichst mit günstigen Standardkomponenten 
auskommen und in ein möglichst platzsparendes Gehäuse untergebracht werden. 
Das Gerät soll zur direkten Ansteuerung einer Gastherme benutzt werden und den vorhandenen mechanischen oder 
elektronischen/programmierbaren Raumthermostat ersetzen. Es wurde bewusst auf erweiterte Funktionen wie 
Uhr und Programmierbarkeit verzichtet, um die Komplexität gering zu halten. Da das Gerät sowieso in Verbindung mit 
einer zentralen, "intelligenten" Haussteuerung genutzt werden soll ist das nicht erforderlich. 
Lediglich die Grundfunktionalität muss für den Fall eines Ausfalls der zentralen Steuerung oder des Netzwerks 
autark gegeben sein. Als Haussteuerung soll die Open-Source Software Domoticz zum Einsatz kommen. 
Die implementierten Funktionen reduzieren sich somit auf: 
 - Messung der aktuellen Raumtemperatur (und Luftfeuchtigkeit, nur für Telemetrie, für die Regelung nicht erforderlich)
 - Thermostat mit Hysterese und umschaltbarem Modus mit zwei unterschiedlichen Solltemperaturen (Normalbetrieb und Absenkbetrieb) + Aus
 - direkte Bedienung über Tasten
 - Ausgabe auf LCD: aktuelle Temperatur, Soll-Temperatur, Betriebsmodus
 - Telemetrie über WiFi (MQTT-Protokoll)
 - Fernbedienung von Solltemperatur und Modus via MQTT und der Vollständigkeit halber auch über Webinterface
 - direkte MQTT-Anbindung an die Domoticz-Zentrale für Temperatursensor, Solltemperatur und Betriebsmodus
 - einfaches Webinterface
 - Konfiguration der wichtigsten Parameter via UART/MQTT-Befehle sowie Webinterface
 - Speicherung des aktuellen Betriebsmodus sowie der Soll-Temperatur
 - WiFi und MQTT-Anbindung im non-blocking mode
 
Optional: 
 - IR Abstandssensor (aktivierung der Displaybeleuchtung bei Annäherung)
 - PIR-Bewegungssensor (Anwesenheitserkennung durch Steuerzentrale - Statusänderung wird nur via MQTT gepublished)
 - Anzeige der Aussentemperatur (wenn diese via MQTT angeliefert wird - in diesem Fall wechselt die Anzeige wie im per DisplayInterval festgelegt)
  
- Bedienung lokal: 
	- Umschaltung des Betriebsmodus (Normal, Absenkung, Heizung aus)
	- Änderung der Solltemperatur für Normalbetrieb (+ und - Taste)
	- bei Tastendruck - egal welcher Taste - wird zunächst nur die Displaybeleuchtung eingschaltet, nach einstellbarem Timeout ohne Bedienung wieder aus
	  erst bei aktiver Beleuchtung ist die Eingabe aktiv (dies wird wenn vorhanden durch den IR-Abstandssensor ersetzt bzw. ergänzt)
	  
 - Fernsteuerung über MQTT: 
	- Solltemperatur ändern
	- Betriebsmodus umschalten
	- Konfigurationsparameter setzen
	
 - Einstellungen: 
    - Solltemperatur für Absenkbetrieb
    - Hysterese
	- minimale Einschaltzeit der Heizung (Verhinderung zu häufiger Taktung bei zu kleiner Hysterese)
	- minimale und maximale über Tasten und MQTT/Domoticz einstellbare Soll-Temperatur
	- MQTT out topic, an welches die verschiedenen Werte zyklisch gepublished werden (jeweils eigenes hardcoded subtopic)
	- domoticz/out topic (zur empfohlenen Nutzung des Hierarchical out topic in Domoticz - domoticz/out/${floorplan name}/${plan name})
    - Domoticz-Idx für die einzelnen Messwerte/Steuerfunktionen
	- MQTT-Server Host, Port, User, Passwort, Last-Will-Topic usw. 
	- Webinterface User und Passwort

 - Konfiguration via WiFi-Manager - wenn kein WiFi konfiguriert ist oder nicht verbunden werden kann wird ein AP geöffnet, über den die Konfiguration erreichbar ist
    - SSID und WPA-Key
	
 - Konfiguration nur zur Compile-Zeit:
    - Pin-Zuordnungen
    - I2C-Adressen (LCD)
    - Fallback AP-Name für WiFiManager, sowie Passwort dafür
	
 - Speicherung: 
   Konfigurationsänderungen werden im SPIFFS dauerhaft gespeichert. 
   Bei Änderung via MQTT/UART-command erst nach Ausführung des save-Befehls, bei Änderung über das Webinterface direkt. 
   Änderung des Betriebsmodus sowie der Solltemperatur wird - wenn dies in der Konfiguration aktiviert ist - nach einem Timeout von 5 Sekunden nach der letzten Änderung
   gespeichert. 
   
 - Domoticz-Anbindung: 
   Domoticz wird über MQTT direkt unterstützt, wenn mindestens eine Idx konfiguriert wurde. 
   Folgende Domoticz-Dummy-Devices werden unterstützt bzw. benötigt: 
   - Thermostat SetPoint - für die Soll-Temperatur
   - Selector Switch mit 3 Stufen - für die Betriebsart, 0 = Aus, 10 = Normal, 20 = Absenkung
   - Temp + Humidity
   
   Es wird, sofern mindestens eine Idx und ein domoticz/out-topic konfiguriert ist, das konfigurierte domoticz/out-topic subscribed und jede darin eingehende Payload geprüft. 
   Da die Payloads relativ groß und im json-Format sind, und die Idx anhand jedes Gerät "seine" messages identifiziert nicht im topic name sondern nur 
   in der Payload selbst ersichtlich ist, muss dabei jede eingehende Payload verarbeitet werden. Je nach Umfang der Domoticz-Installation kann das eine 
   sehr große Zahl an Payloads pro Zeit bedeuten - das ist mit den limitierten Ressourcen auf einem MCU sehr problematisch. 
   Aus diesem Grund sollte NIEMALS das komplette domoticz/out-topic benutzt werden, sondern immer ausschließlich das Hierarchische. 
   Hierbei werden alle Geräte einem Floorplan zugewiesen und sind dann unter dem topic domoticz/out/${floorplan name}/${plan name} verfügbar. 
   
   Kommt ein neuer Wert für eines der Devices via domoticz/out herein, so wird dieser Wert unmittelbar übernommen und ohne Verzögerung die Speicherung im Flash ausgelöst. 
   Wirklich im Flash gespeichert wird allerdings nur wenn sich der Wert auch tatsächlich geändert hat. 
   
   Bei Änderung eines lokalen Werts (Betriebsmodus, Soll-Temperatur) - über Tasten, Webinterface oder MQTT - wird dieser neue Wert wie schon beschrieben 5 Sekunden nach 
   der letzten Änderung im Flash gespeichert. Gleichzeitig wird der neue Wert über MQTT an das topic domoticz/in mit gleicher Idx gepublished. 
   Das ist auch dann der Fall, wenn die Änderung von domoticz/out gekommen ist. Um eine Endlosschleife zu verhindern wird nach einem solchen publish für 2 Sekunden die 
   domoticz/out-Verarbeitung deaktiviert. Dadurch ist gewährleistet, dass jede Änderung in beide Richtungen aktuell gehalten wird, aber in keinem Fall eine Endlosschleife 
   zwischen dem Thermostat und Domoticz auftreten kann.