DocBigsLab – HP-Remote

Vollständige bidirektionale Fernsteuerung für Bosch / Buderus Brauchwasser-Wärmepumpen

Ein ESP32-S3-CAM liest das selbstleuchtende 7-Segment-Display optisch aus und simuliert alle 6 kapazitiven Fronttasten über eine PCB mit I2C-Touch-Interface. Dank Rückkopplung von OCR und Tastensteuerung lassen sich Solltemperatur und Uhrzeit verifiziert einstellen – auf Wunsch vollautomatisch durch Tastensperre und Standby hindurch. Die Anbindung läuft universell über MQTT – Messwerte und Tastensteuerung sind so in jede MQTT-fähige Umgebung integrierbar. Für Home Assistant gibt es zusätzlich MQTT Auto-Discovery, sodass alle Sensoren und Tasten dort ohne manuelle Konfiguration erscheinen.

Basiert auf dem ESP32-Display-Reader von DocBig, portiert auf den ESP32-S3-CAM und um I2C Touch-Steuerung erweitert.

Über dieses Repository: HP-Remote ist von DocBigs-Lab/HP-Remote ausgegangen und wird hier eigenständig weiterentwickelt, unter anderem mit reproduzierbaren Builds und GitHub Releases. Herzlichen Dank an DocBig für die hervorragende Vorarbeit: Hardware, Firmware, Web-UI und Web-Installer aus dem DocBigs Lab sind die Grundlage für alles, was hier entsteht. Hardware (z. B. die Touch-PCB) gibt es weiterhin über das DocBigs Lab; dieses Repository entwickelt nur die Software weiter und bietet selbst keine Hardware an.

---

Letzte Änderungen

Siehe CHANGELOG.md für die vollständige Historie.

---

Kompatible Geräte

Getestet mit der Steuerung der folgenden baugleichen Brauchwasser-Wärmepumpen:

Hersteller	Modell
Bosch	Compress 5000 DW – CS5001DW 200 / 200 C / 260 / 260 C
Buderus	WPT 200.4A / WPT 260.4A (baugleich)

Andere Geräte mit identischem kapazitivem Bedienpanel (selbstleuchtendes 7-Segment-Display, 6 Touch-Tasten) lassen sich vermutlich ebenfalls anbinden, sind aber nicht getestet.

---

Was das Projekt macht

Funktion	Mechanismus
Display auslesen	OV2640-Kamera → OCR → MQTT (Set Temp, Water Temp, Symbole)
Tasten drücken	PCF8574 I2C → 6 × TLP281-4 Optokoppler → kapazitive Kontaktflächen auf PCB. Einzel-, Mehrfach-, Lang-Druck, Tastenkombinationen, Sequenzen und benannte Shortcuts (Standby, Gebläse, Tastensperre, Timer)
Solltemperatur setzen	Verifizierter Closed-Loop (set_temp): liest per OCR, regelt nach, trifft den Zielwert exakt. Grobsprung + Feinschliff für Tempo, optional vollautomatisch durch Tastensperre und Standby hindurch (auto)
Uhrzeit setzen	Verifiziertes Stellen der WP-Uhr (set_time) für Sommer-/Winterzeit oder Drift – Stunden und Minuten getrennt, kürzeste Richtung, mit Feintuning-Durchgängen
Live-Stream	MJPEG-Stream (Port 81) auf /live mit ausklappbarer Direktsteuerung: Tasten, Shortcuts und Temperatur-Stepper/Presets
Home Assistant	Optionale MQTT Auto-Discovery: Sensoren + 6 Button-Entities + Live-URL
Konfiguration	Webinterface im Browser, ROI-Editor, OTA-Updates
Config-Storage	NVS (Preferences) – kein Dateisystem nötig

---

Dokumentation

Die ausführliche Dokumentation ist in vier Bereiche aufgeteilt:

Dokument	Inhalt
Hardware & Montage	Board, Touch-PCB, Pinouts, Schaltungsprinzip, Aufbau & Montage
Inbetriebnahme & Konfiguration	Flashen, WLAN/MQTT, ROIs einrichten, MQTT-API (inkl. Solltemperatur- & Uhrzeit-Closed-Loop mit auto), Home Assistant
Test & Debugging	I2C-Scan, Multimeter-Test, OCR-Diagnose (Test Detection), REST-API
Entwicklung	Firmware bauen, Host-Tests ausführen und schreiben
MQTT ohne Home Assistant	Direkte Steuerung per CLI, MQTT-Tools, Cron & Node-RED

---

🚀 Web Installer

Firmware direkt im Browser flashen – kein Tool erforderlich:

👉 Web Installer starten

ESP32-S3-CAM per USB anschließen, „Install" klicken (Chrome / Edge).

---

Firmware bauen

Die Firmware-Artefakte liegen unter .pio/build/xiao_esp32s3/artifacts/.

pio run -e xiao_esp32s3

Alternativ kann der Build mit Docker oder Podman ausgeführt werden:

docker build -t hp-remote-builder -f Containerfile .
docker run --rm -v "$PWD:/workspace" -w /workspace hp-remote-builder run -e xiao_esp32s3

Für Podman wird docker durch podman ersetzt.

Host-Tests

Reine C++-Module der Firmware werden mit g++ auf dem PC getestet, ohne ESP32-Toolchain (Details in docs/DEVELOPMENT.md):

make -C tests

---

Release erstellen

In GitHub Actions Firmware build > Run workflow starten und die Release-Version ohne Präfix eingeben, zum Beispiel 1.2.0. Der Workflow baut den aktuellen main-Commit, erstellt den Tag v1.2.0 und veröffentlicht das GitHub Release.

Das Release enthält HP-Remote-OTA.bin und HP-Remote-merged.bin. Anschließend veröffentlicht der Workflow den Web-Installer (docs/) zusammen mit der HP-Remote-merged.bin des Releases auf GitHub Pages. Dafür muss unter Settings > Pages > Source einmalig GitHub Actions ausgewählt sein.

Zum Testen ohne Release: In GitHub Actions Run workflow für den gewünschten Branch ausführen.

---

Projektstruktur

HP-Remote/
├── src/
│   ├── main.cpp                  ← Setup + Loop + Solltemperatur-Closed-Loop (set_temp/auto)
│   ├── touch_config.h            ← PCF8574 Adresse, I2C-Pins, Port-Zuordnung
│   ├── touch_controller.h/.cpp   ← I2C/PCF8574: press(), hold(), releaseAll(), rescan()
│   ├── camera_service.cpp        ← OV2640 Pinout ESP32-S3-CAM, MJPEG-Stream
│   ├── analyzer.cpp/.h           ← 7-Segment OCR
│   ├── mqtt_service.cpp/.h       ← MQTT + Touch-Callback + Shortcuts + Subscribe
│   ├── mqtt_ha_discovery.cpp/.h  ← HA Auto-Discovery: Sensoren, Buttons, Stream
│   ├── web_server.cpp/.h         ← Webinterface + REST API + MJPEG Port 81
│   ├── web_ui.h                  ← eingebettetes HTML/JS
│   ├── app_config.cpp/.h         ← Konfiguration + JSON
│   ├── storage_service.cpp/.h    ← NVS (Preferences)
│   ├── device_identity.cpp/.h    ← MAC-basierte Geräte-UID
│   ├── wifi_manager.cpp/.h       ← WiFi + AP-Setup
│   ├── ota_service.cpp/.h        ← OTA
│   └── debug_log.h               ← Log-Makros
├── docs/                          ← Dokumentation + Web-Installer
│   ├── HARDWARE.md                ← Hardware & Montage
│   ├── SETUP.md                   ← Inbetriebnahme & Konfiguration
│   ├── DEBUG.md                   ← Test & Debugging
│   ├── DEVELOPMENT.md             ← Firmware bauen, Host-Tests
│   ├── MQTT-EXAMPLES.md           ← MQTT-Steuerung ohne Home Assistant
│   └── images/                    ← Bilder für die Doku
├── tests/                         ← Host-Tests (g++) + Testbilder vom Gerät
├── platformio.ini                ← Board: esp32-s3-devkitc-1, qio_opi PSRAM
├── partitions_ota.csv            ← OTA-Partitionstabelle
├── version_build.py              ← injiziert FW_VERSION + FW_BUILD
├── merge_bin.py                  ← erzeugt Firmware-Artefakte unter .pio/build/
└── README.md                     ← Übersicht (dieses Dokument)

---

Lizenz

MIT – basiert auf ESP32-Display-Reader von DocBig.