Smart-Controller WLAN-Firmware

Der VanTurtle Smart Controller ist ein mit ESP32-C3 betriebenes Nachrüst-Kit, kompatibel mit deinem Maxxfan®, das deutlich mehr Flexibilität bietet als die IR-Fernbedienung oder das Bedienfeld. Er kann den Lüfter ein- und ausschalten, die Geschwindigkeit anpassen, die Drehrichtung umkehren und sogar den aktuellen Stromverbrauch des Lüfters messen.

Dieses Handbuch behandelt den WiFi-Firmware-Stack, der eine Web-App, REST-API, WebSocket, MQTT-Client und Tuya-Integration ermöglicht. Ein separater Bluetooth-Firmware-Build ist für die Home-App auf iOS und eine Begleit-App auf Android verfügbar. Nur eine dieser Optionen kann sich gleichzeitig auf dem Gerät befinden, da sie dieselben Hardware-Ressourcen nutzen. Wähle beim Kauf die gewünschte Option aus.

Verbindung mit dem Controller

Beim ersten Start befindet sich der Controller im AP-Modus und betreibt ein Hotspot-WLAN-Netzwerk, mit dem du dich für die Ersteinrichtung verbinden kannst. Nach der Konfiguration wechselt er in den STA-Modus und verbindet sich mit deinem lokalen WLAN-Netzwerk, wo er von jedem Gerät im selben Netzwerk erreichbar ist. Die Hotspot-Netzwerkkonfiguration lautet wie folgt:

SSID	VanTurtle Fan
Passwort	Ungefähr so: 0000-0000
Adresse	192.168.4.1

Verbinde dich von einem Smartphone oder Laptop aus mit diesem Netzwerk. Die meisten Geräte öffnen automatisch das Anmeldeportal, das die Web-Oberfläche des Controllers direkt anzeigt. Wenn diese Aufforderung nicht erscheint, öffne einen Browser und navigiere manuell zu http://192.168.4.1. Achte darauf, die http-URL zu verwenden und nicht https.

Sobald du die Web-App geöffnet hast, siehst du die Slider-Steuerung für den Lüfter und kannst die Geschwindigkeit einstellen. Wenn alles wie erwartet funktioniert, kannst du zu den Einstellungen gehen (Zahnrad-Symbol oben rechts) und die WLAN-Einstellungen auswählen.

Gib den WLAN-Netzwerknamen (SSID) und das Passwort deines Vans ein und speichere die Einstellungen. Der Controller startet neu und versucht, sich mit deinem WLAN zu verbinden. Wenn die Zugangsdaten korrekt sind und die Verbindung erfolgreich hergestellt wird, wechselt der Controller in den STA-Modus. Bei einem Fehler fällt er zurück in den AP-Modus, damit du es erneut versuchen kannst.

Wenn dein Netzwerk mDNS unterstützt (bei den meisten Heimroutern der Fall), ist der Controller unter http://vanturtle-fan.local erreichbar. Andernfalls musst du die vom Router zugewiesene IP-Adresse des Controllers ermitteln (DHCP-Tabelle des Routers prüfen) und damit auf die Web-App zugreifen.

Die Web-App verwenden

Der Hauptbildschirm zeigt einen vertikalen Slider. Ziehe ihn nach oben oder unten, um die Lüftergeschwindigkeit einzustellen, oder tippe auf eine Position auf der Leiste, um direkt dorthin zu springen. Der Slider hat 10 Stufen plus eine Aus-Position am unteren Ende.

Drei Schaltflächen befinden sich unterhalb des Sliders:

Auto temp	Aktiviert oder deaktiviert die automatische Temperaturbeibehaltung.
Open / close	Öffnet oder schließt die Lüfterklappe, auch bei ausgeschaltetem Lüfter.
Reverse airflow	Schaltet die Lüfterrichtung zwischen vorwärts und rückwärts um.

Wenn der Browser den Controller nicht erreichen kann, blendet sich das gesamte Bedienfeld aus, um den Verbindungsabbruch anzuzeigen. Die App stellt die Verbindung automatisch alle paar Sekunden wieder her und wird sofort wieder bedienbar, sobald die Verbindung steht.

Auf einem Mobilgerät kannst du die Web-App zum Startbildschirm hinzufügen, um ein nativeres App-Erlebnis zu erhalten. In Safari tippst du auf das Teilen-Symbol und wählst „Zum Startbildschirm“. In Chrome öffnest du das Menü und wählst „Zum Startbildschirm hinzufügen“. Die genauen Schritte können je nach Gerät und Browser variieren.

MQTT

Der Controller kann sich mit einem MQTT-Broker in deinem lokalen Netzwerk (oder einem Remote-Broker, wenn gewünscht) verbinden, Lüfterstatusänderungen an konfigurierbare Topics senden und Befehle durch das Abonnieren dieser Topics entgegennehmen. Dadurch lässt er sich problemlos in viele Systeme integrieren, darunter Home Assistant, Node-RED (wie auf dem Victron Cerbo GX) oder jedes andere System, das MQTT unterstützt.

MQTT ist standardmäßig deaktiviert. Um es zu aktivieren, öffne die Einstellungen, gehe zum MQTT-Bereich und trage mindestens die Broker-Adresse ein. Der Controller verbindet sich beim nächsten Speichern. Lasse das Feld für die Broker-Adresse leer, um MQTT wieder zu deaktivieren.

Alle Topics sind frei konfigurierbar und standardmäßig nicht gesetzt. Es werden nur Topics abonniert oder veröffentlicht, für die ein Wert in den Einstellungen eingetragen ist. Jedes Topic überträgt einen Klartextwert.

Topic	Richtung	Werte
Geschwindigkeit	Senden & Empfangen	Ganzzahl 1–10
Richtung	Senden & Empfangen	0 = evtl. vorwärts, 1 = evtl. rückwärts
Auto temp	Senden & Empfangen	0 = aus, 1 = ein
Ein/Aus	Senden & Empfangen	0 = aus, 1 = ein
Open/close	Nur empfangen	Jeder Wert löst die Aktion aus
Spannung	Nur senden	Dezimalzahl, z. B. 12.345 (Volt)
Strom	Nur senden	Dezimalzahl, z. B. 1.234 (Ampere)
Leistung	Nur senden	Dezimalzahl, z. B. 15.678 (Watt)
Keepalive	Nur senden	Sendet alle 60 Sekunden 1

Alle gesendeten Topics verwenden QoS 1. Der Controller veröffentlicht den vollständigen Lüfterstatus unmittelbar nach der Verbindung mit dem Broker, sodass die gespeicherten Werte des Brokers ab der ersten Verbindung immer aktuell sind.

Wenn ein Broker so konfiguriert ist, dass er Nachrichten speichert, erhält der Controller beim erneuten Verbinden seine zuletzt gesendeten Werte zurück. Ohne Unterdrückung kann dies dazu führen, dass der Controller auf seine eigenen Statusberichte reagiert, als wären es neue Befehle. Die Einstellung Echo-Unterdrückung legt ein Zeitfenster in Millisekunden fest, in dem eingehende Nachrichten nach dem Senden ignoriert werden. Ein Wert von etwa 500 reicht aus, um die meisten eigenen Echos zu filtern, ohne legitime externe Befehle zu verzögern. Setze ihn auf 0, um die Funktion zu deaktivieren.

REST API

Der Controller stellt eine REST API über HTTP auf Port 80 bereit. Dieser Abschnitt behandelt den /state-Endpunkt, der den Lüfter ausliest und steuert. Um den aktuellen Status abzurufen:

GET http://vanturtle-fan.local/state

Beispielantwort:

{
  "active": true,
  "speed": 6,
  "direction": 0,
  "auto_hold": true,
  "voltage": 12.341,
  "current": 0.874,
  "power": 10.786,
  "has_calibration": true,
  "is_calibrating": false
}

active	Gibt an, ob der Lüfter läuft.
speed	Aktuelle Geschwindigkeitsstufe, 1–10.
direction	Eine Schätzung der Luftstromrichtung, nicht zuverlässig.
auto_hold	Gibt an, ob die automatische Beibehaltung aktiv ist.
voltage	Spannung an den Lüfteranschlüssen in Volt.
current	Stromaufnahme in Ampere.
power	Leistung in Watt gemäß INA226.
has_calibration	Gibt an, ob der Controller kalibriert wurde.
is_calibrating	Gibt an, ob gerade eine Kalibrierung läuft.

Verwende den POST-Endpunkt, um ein oder mehrere Lüfterstatus-Felder zu aktualisieren. Sende einen JSON-Body mit einer beliebigen Teilmenge der beschreibbaren Felder. Unbekannte Felder werden ignoriert. Die Antwort ist der vollständige aktualisierte Status im gleichen Format wie die GET-Antwort.

POST http://vanturtle-fan.local/state
Content-Type: application/json

{"active": true, "speed": 8}

active	Boolean oder 0/1. Schaltet den Lüfter ein oder aus.
speed	Ganzzahl 1–10. Legt die Lüftergeschwindigkeit fest. Werte außerhalb dieses Bereichs werden ignoriert.
direction	Schaltet die Lüfterrichtung um. Der Wert spielt keine Rolle.
auto_hold	Boolean oder 0/1. Aktiviert oder deaktiviert die automatische Beibehaltung.

Statusänderungen über die REST API werden in der Web-App angezeigt und genauso über MQTT und Tuya veröffentlicht wie Änderungen aus jeder anderen Quelle.

WebSocket

Der Controller stellt einen WebSocket-Endpunkt unter /ws bereit. Er überträgt zwei Arten von Daten: Echtzeit-Lüfterstatusupdates, die vom Controller an alle verbundenen Clients gesendet werden, und die rohe Log-Ausgabe. Der WebSocket ist dem regelmäßigen Abfragen der REST API für Echtzeit-Updates vorzuziehen und für den Empfang der Log-Ausgabe erforderlich.

Statusupdates werden bei der Verbindung und bei jeder Statusänderung gesendet. Das Format ist identisch mit der GET /state-Antwort:

{"active":true,"speed":6,"direction":0,"auto_hold":true,"voltage":12.341,"current":0.874,"power":10.786,"has_calibration":true,"is_calibrating":false}

Zusätzlich zum Status leitet der Controller seine interne Log-Ausgabe an alle verbundenen Clients weiter. Log-Frames tragen ein type-Feld, um sie von Statusupdates zu unterscheiden:

{"type":"log","raw":"I (12345) MQTT: Connected to broker"}

Es ist auch möglich, Befehle über den WebSocket an den Controller zu senden. Sende einen JSON-Textframe mit einem command-Feld und einem optionalen value. Der Controller wendet den Befehl an und sendet einen aktualisierten Status an alle Clients.

Befehl	Wert	Wirkung
active	Boolean, 0/1 oder 2	Schaltet den Lüfter ein oder aus. Wert 2 wechselt den Zustand.
speed	Ganzzahl 1–10 oder "+" / "-"	Legt die Geschwindigkeit fest. Die Zeichenformen erhöhen oder verringern um eine Stufe.
direction	Beliebig (ignoriert)	Schaltet die Lüfterrichtung um.
hold	Boolean oder 0/1	Aktiviert oder deaktiviert die automatische Beibehaltung.
openclose	N/A	Löst ein kurzes Öffnen/Schließen aus.
get	N/A	Antwortet nur an diesen Client mit dem aktuellen Status, ohne zu senden.
calibrate	N/A	Startet eine INA226-Neukalibrierung. Hat keine Wirkung, wenn bereits eine läuft.
reset	N/A	Löst einen Werksreset aus und löscht alle gespeicherten Einstellungen.

Beispiel – Geschwindigkeit auf 7 setzen:

{"command":"speed","value":7}