Refactor error messages and options for clarity and consistency in mapper.cpp and wp_base.yaml; update README.md for project focus on Tecalor THZ504

jss-devops01 · jss-devops01 · commit f69c3a2cd486 · 2025-09-29T08:43:16.000+02:00
diff --git a/README.md b/README.md
@@ -1,58 +1,120 @@
-This project aims to provide all kinds of useful features for your Home Assistant instance using a single ESP32 board.
+# OneESP32ToRuleThemAll - THZ504 Simplified
+
+This project is a simplified version derived from [OneESP32ToRuleThemAll](https://github.com/kr0ner/OneESP32ToRuleThemAll), specifically focused on controlling the **Tecalor THZ504** heat pump via CAN bus using an ESP32 board and Home Assistant.
+
+## About
+
+This codebase has been streamlined from the original OneESP32ToRuleThemAll project to focus exclusively on the Tecalor THZ504 model, removing support for smart meters, water meters, and other heat pump variants to provide a cleaner, more targeted solution.
 
 ## Features:
 
-  - SmartMeter readings via optical sensor [https://amzn.eu/d/1a28LBy]
-  - WaterMeter readings via [https://amzn.eu/d/8Rx0UVJ]
-  - Controlling a Tecalor THZ 504 (or other Tecalor | Stiebel Eltron heat pumps) via CAN  [https://amzn.eu/d/5nJJK3r]
+  - **Tecalor THZ504 Heat Pump Control** via CAN bus using SN65HVD230 transceiver [https://www.amazon.de/dp/B00KM6XMXO]
+  - Complete climate control (heating, cooling, hot water)
+  - Energy monitoring (daily/total consumption, COP calculations)
+  - Ventilation control with multiple speed levels
+  - Temperature sensors (room, storage, flow, return temperatures)
+  - Binary sensors for system status (compressor, pumps, filters)
+  - Custom ESPHome climate entities with Home Assistant integration
 
 ## Prerequisites:
 
   - A working Home Assistant installation [https://www.home-assistant.io/]
   - ESPHome AddOn installed [https://www.home-assistant.io/integrations/esphome/]
 
-## HowTo:
+## Hardware Requirements:
+
+  - ESP32-C6-Zero board
+  - SN65HVD230 CAN bus transceiver module [https://www.amazon.de/dp/B00KM6XMXO]
+  - Tecalor THZ504 heat pump with CAN bus interface
+
+## Setup Instructions:
+
+1. **Hardware Connection:**
+   - Connect SN65HVD230 CAN transceiver to ESP32-C6-Zero:
+     - TX: GPIO5
+     - RX: GPIO4
+     - VCC: 3.3V
+     - GND: GND
+     - Connect CAN H/L to your THZ504's CAN bus
+
+2. **ESPHome Configuration:**
+   - Navigate to your ESPHome folder
+   - Clone or copy this repository
+   - Use `esp32-c6-thz504.yaml` as your main configuration file
+   - Update `secrets.yaml` with your WiFi credentials and API keys
+   - Modify Home Assistant entity IDs in `common.yaml` for room temperature and humidity sensors
 
-1. navigate to your esphome folder
-2. clone the repo (git clone https://github.com/kr0ner/OneESP32ToRuleThemAll.git)
-3. copy or symlink OneESP32ToRuleThemAll/esp32-poe-technik.yaml to your esphome folder
-4. change board type if needed
-5. comment out packages you don't want/need
-6. add Wifi if necessary
-7. change pins for SPI/CAN if needed
-8. provide HA entities for temperature and humidity
+3. **Home Assistant Integration:**
+   - Install ESPHome add-on if not already installed
+   - Add the device to ESPHome dashboard
+   - Flash the firmware to your ESP32-C6-Zero
+   - Configure room temperature and humidity sensors in Home Assistant
 
-## Add new readings from heat pump / adopt to your device
+## Project Structure
 
-1. Navigate through the menu of the display, mounted to your heat pump
-2. Try to match the values (e.g. 237) to the values you see in the display (23.7°)
-3. Use the existing templates to add new sensors
-4. Add the newly added ids along with their types to property.h
-5. Guard the newly added ids with e.g. #if defined(THZ_5_5_ECO) ... #endif to express that it was tested with that version once it is confirmed for the others, the guards can be removed
-6. Add the entities to the respective yaml and use the already existing templates. For config values that can be set, use the wp_number.yaml. For sensors that are updated automatically chose the template that fits best.
-7. profit
+- **`esp32-c6-thz504.yaml`** - Main ESP32-C6-Zero configuration file
+- **`yaml/thz504.yaml`** - THZ504-specific sensor definitions
+- **`yaml/common.yaml`** - Common CAN bus and core functionality (configured for SN65HVD230)
+- **`yaml/wp_base.yaml`** - Base heat pump sensors and climate entities
+- **`src/`** - C++ source files for custom components
+- **`components/`** - Custom ESPHome components
+
+## Available Entities
+
+The configuration provides comprehensive control and monitoring:
+
+- **Climate Controls:** Heating Day/Night, Hot Water Day/Night with temperature setpoints
+- **Binary Sensors:** Compressor, heating, cooling, ventilation, pumps, filter status
+- **Temperature Sensors:** Room, storage tank, flow/return, outdoor, evaporator
+- **Energy Monitoring:** Daily energy consumption, COP calculations, total energy counters
+- **Ventilation:** 3-speed fan control with airflow monitoring
+- **System Status:** Operating modes, error messages, service indicators
+
+## Customization for THZ504
+
+This version is specifically configured for THZ504 with:
+- ESP32-C6-Zero with built-in CAN controller using SN65HVD230 transceiver
+- CAN bus IDs optimized for THZ504 communication
+- Temperature sensor mappings verified for THZ504
+- Energy calculation formulas based on THZ504 specifications
+- Ventilation control adapted to THZ504 fan characteristics
 
 ## Troubleshooting
-### You are not able to control your heat pump
- --> Increase the log level and try to find out which CAN identifiers to use. Also check the forum and communciation.h
 
-### You get garbage values for certain sensors
- --> There is no offical description of the IDs available. Everything is somewhat trial-and-error. 
-     Also there are many differences between the different heat pumps. Play around with the display and try to find out
-     the correct IDs.
+### Heat Pump Control Issues
+- Increase log level to DEBUG in your YAML configuration
+- Check CAN bus wiring (CAN H/L connections)
+- Verify CAN bus termination resistors are properly installed
+- Monitor CAN traffic using the built-in logging
+
+### Sensor Value Issues
+- THZ504-specific sensor mappings are pre-configured in this version
+- If values appear incorrect, check the heat pump display to verify scaling
+- Some sensors may take time to populate after initial connection
 
+### Connection Problems
+- Ensure ESP32-C6-Zero is properly powered and connected to WiFi
+- Check that the SN65HVD230 CAN transceiver is receiving 3.3V power
+- Verify CAN H/L wiring connections to the THZ504
+- Verify Home Assistant can communicate with the ESPHome device
 
-Forked from https://github.com/kr0ner/OneESP32ToRuleThemAll 
+## Credits & Acknowledgments
 
-Heavily inspired by this post in HA community forum:
+This project is **derived from** [OneESP32ToRuleThemAll](https://github.com/kr0ner/OneESP32ToRuleThemAll) by [@kr0ner](https://github.com/kr0ner) and has been simplified to focus specifically on the **Tecalor THZ504** heat pump model.
 
-https://community.home-assistant.io/t/configured-my-esphome-with-mcp2515-can-bus-for-stiebel-eltron-heating-pump/366053
+**Original project inspiration:**
+- [OneESP32ToRuleThemAll](https://github.com/kr0ner/OneESP32ToRuleThemAll) - The comprehensive multi-device ESP32 solution
+- Home Assistant Community Forum: [Configured my ESPHome with MCP2515 CAN bus for Stiebel Eltron heating pump](https://community.home-assistant.io/t/configured-my-esphome-with-mcp2515-can-bus-for-stiebel-eltron-heating-pump/366053)
+- [ha-stiebel-control](https://github.com/bullitt186/ha-stiebel-control) by [@bullitt186](https://github.com/bullitt186)
 
-and
+**Special thanks to:**
+- [@kr0ner](https://github.com/kr0ner) for the original comprehensive implementation
+- [@hovhannes85](https://github.com/hovhannes85) for contributions to the original project
+- The Home Assistant and ESPHome communities for their ongoing support
 
-https://github.com/bullitt186/ha-stiebel-control
+## License
 
-special thanks to [@hovhannes85](https://github.com/hovhannes85)
+This project maintains the same license as the original OneESP32ToRuleThemAll project.
 
 ### Useful links
 https://www.stiebel-eltron.de/content/dam/ste/cdbassets/historic/bedienungs-_u_installationsanleitungen/ISG_Modbus__b89c1c53-6d34-4243-a630-b42cf0633361.pdf
diff --git a/esp32-c6-thz504.yaml b/esp32-c6-thz504.yaml
@@ -72,11 +72,11 @@ sensor:
 
 # Memory and system info
 text_sensor:
-  - platform: debug
-    device:
-      name: "ESP32-C6 Device Info"
-    reset_reason:
-      name: "ESP32-C6 Reset Reason"
+#  - platform: debug
+#    device:
+#      name: "ESP32-C6 Device Info"
+#    reset_reason:
+#      name: "ESP32-C6 Reset Reason"
       
   - platform: wifi_info
     ip_address:
diff --git a/src/mapper.cpp b/src/mapper.cpp
@@ -48,42 +48,37 @@ std::optional<std::uint16_t> Mapper::getPassivkuehlungId(const std::string& pass
 }
 
 Mapper::Mapper() {
-    errorMap = {{0x0002, "Schuetz klebt"},
+    errorMap = {{0x0002, "CONTACTOR_STUCK"},
                 {0x0003, "ERR HD-SENSOR"},
-                {0x0004, "Hochdruck"},
-                {0x0005, "Verdampferfuehler"},
-                {0x0006, "Relaistreiber"},
-                {0x0007, "Relaispegel"},
-                {0x0008, "Hexschalter"},
-                {0x0009, "Drehzahl Luefter"},
-                {0x000a, "Lueftertreiber"},
+                {0x0004, "HIGH_PRESSURE"},
+                {0x0005, "EVAPORATOR_SENSOR_ERROR"},
+                {0x0006, "RELAY_DRIVER_ERROR"},
+                {0x0007, "RELAY_LEVEL_ERROR"},
+                {0x0008, "HEX_SWITCH_ERROR"},
+                {0x0009, "FAN_SPEED_ERROR"},
+                {0x000a, "FAN_DRIVER_ERROR"},
                 {0x000b, "Reset Baustein"},
                 {0x000c, "ND"},
-                {0x000d, "ROM"},
-                {0x000e, "QUELLEN MINTEMP"},
-                {0x0010, "Abtauen"},
+                {0x000d, "ROM_ERROR"},
+                {0x000e, "SOURCE_MIN_TEMP"},
+                {0x0010, "DEFROST_ERROR"},
                 {0x0012, "ERR T-HEI IWS"},
                 {0x0017, "ERR T-FRO IWS"},
-                {0x001a, "Niederdruck"},
+                {0x001a, "LOW_PRESSURE"},
                 {0x001b, "ERR ND-DRUCK"},
                 {0x001c, "ERR HD-DRUCK"},
                 {0x001d, "HD-SENSOR-MAX"},
                 {0x001e, "HEISSGAS-MAX"},
                 {0x001f, "ERR HD-SENSOR"},
-                {0x0020, "Einfrierschutz"},
-                {0x0021, "KEINE LEISTUNG"}};
+                {0x0020, "FREEZE_PROTECTION"},
+                {0x0021, "NO_POWER"}};
 
-#if defined(TTF_07_C) | defined(WPL_13)
-    betriebsartMap = {{0x0000, "Notbetrieb"}, {0x0100, "Bereitschaft"}, {0x0200, "Programm"},
-                      {0x0300, "Komfort"},    {0x0400, "Eco"},          {0x0500, "Warmwasser"}};
-#else
-    betriebsartMap = {{0x0000, "Notbetrieb"},    {0x0100, "Bereitschaft"}, {0x0300, "Tagbetrieb"},
-                      {0x0400, "Absenkbetrieb"}, {0x0500, "Warmwasser"},   {0x0B00, "Automatik"},
-                      {0x0E00, "Handbetrieb"}};
-#endif
+    betriebsartMap = {{0x0000, "EMERGENCY_MODE"},    {0x0100, "STANDBY_MODE"}, {0x0300, "DAY_MODE"},
+                      {0x0400, "HOLIDAY_MODE"}, {0x0500, "DHW_MODE"},   {0x0B00, "AUTO_MODE"},
+                      {0x0E00, "MANUAL_MODE"}};
 
-    kuehlmodusMap = {{0x0000, "Flaechenkuehlung"}, {0x0001, "Geblaesekuehlung"}};
+    kuehlmodusMap = {{0x0000, "SURFACE_COOLING"}, {0x0001, "FAN_COOLING"}};
 
     passivkuehlungMap = {
-        {0x0000, "Aus"}, {0x0001, "Ablüften"}, {0x0002, "Zulüften"}, {0x0003, "Bypass"}, {0x0004, "Sommerkassette"}};
+        {0x0000, "OFF"}, {0x0001, "EXHAUST_FLUSH"}, {0x0002, "FRESH_AIR_INTAKE"}, {0x0003, "BYPASS_MODE"}, {0x0004, "SUMMER_CASSETTE"}};
 }
diff --git a/upload-log.txt b/upload-log.txt
@@ -1,13 +1,28 @@
 ﻿
-[2025-09-28 23:22:52] Starting ESPHome direct upload process...
-[2025-09-28 23:22:52] Project path: C:\dev\repos\OneESP32ToRuleThemAll
-[2025-09-28 23:22:52] Config file:  esp32-c6-thz504.yaml
-[2025-09-28 23:22:52] Device IP:    192.168.200.80
-[2025-09-28 23:22:53] ESPHome found: Version: 2025.5.1
-[2025-09-28 23:22:53] Starting compilation of esp32-c6-thz504.yaml...
-[2025-09-28 23:22:53] Running: esphome compile esp32-c6-thz504.yaml
-[2025-09-28 23:23:04] Compilation completed successfully!
-[2025-09-28 23:23:04] Testing connection to device at 192.168.200.80...
-[2025-09-28 23:23:05] Device is reachable at 192.168.200.80
-[2025-09-28 23:23:05] Starting upload to device at 192.168.200.80...
-[2025-09-28 23:23:05] Running: esphome upload esp32-c6-thz504.yaml --device 192.168.200.80
+[2025-09-29 00:04:56] Starting ESPHome direct upload process...
+[2025-09-29 00:04:56] Project path: C:\dev\repos\OneESP32ToRuleThemAll
+[2025-09-29 00:04:56] Config file:  esp32-c6-thz504.yaml
+[2025-09-29 00:04:56] Device IP:    192.168.200.80
+[2025-09-29 00:04:57] ESPHome found: Version: 2025.5.1
+[2025-09-29 00:04:57] Starting compilation of esp32-c6-thz504.yaml...
+[2025-09-29 00:04:57] Running: esphome compile esp32-c6-thz504.yaml
+[2025-09-29 00:05:07] Compilation completed successfully!
+[2025-09-29 00:05:07] Testing connection to device at 192.168.200.80...
+[2025-09-29 00:05:08] Device is reachable at 192.168.200.80
+[2025-09-29 00:05:08] Starting upload to device at 192.168.200.80...
+[2025-09-29 00:05:08] Running: esphome upload esp32-c6-thz504.yaml --device 192.168.200.80
+[2025-09-29 00:05:22] Upload completed successfully!
+[2025-09-29 00:05:22] Device should be rebooting now...
+[2025-09-29 00:05:22] === OPERATION SUMMARY ===
+[2025-09-29 00:05:22] Config File: esp32-c6-thz504.yaml
+[2025-09-29 00:05:22] Device IP:   192.168.200.80
+[2025-09-29 00:05:22] Project:     C:\dev\repos\OneESP32ToRuleThemAll
+[2025-09-29 00:05:22] 
+[2025-09-29 00:05:22] Compilation: SUCCESS
+[2025-09-29 00:05:22] Upload:      SUCCESS
+[2025-09-29 00:05:22] 
+[2025-09-29 00:05:22] Log file: C:\dev\repos\OneESP32ToRuleThemAll\upload-log.txt
+[2025-09-29 00:05:22] Next steps:
+[2025-09-29 00:05:22] - Device should be running new firmware
+[2025-09-29 00:05:22] - Check Home Assistant for updated sensors
+[2025-09-29 00:05:22] - Monitor device logs with: .\upload-to-esp32.ps1 -Logs
diff --git a/yaml/wp_base.yaml b/yaml/wp_base.yaml
@@ -6,7 +6,7 @@ esphome:
     then:
       - lambda: |-
           CallbackHandler::instance().addCallback(std::make_pair(Kessel,Property::kPASSIVE_COOLING),[](const SimpleVariant& value){
-            const auto stringValue{Mapper::instance().getPassivkuehlung(value).value_or("Unbekannt")};
+            const auto stringValue{Mapper::instance().getPassivkuehlung(value).value_or("UNKNOWN")};
             const auto index = id(PASSIVE_COOLING).index_of(stringValue);
             if(index.has_value()) {
               id(PASSIVE_COOLING).publish_state(stringValue);
@@ -41,7 +41,10 @@ esphome:
           });
 
           id(ELECTRIC_BACKUP_HEATING).add_on_state_callback([](const bool state){
-            const auto electricHeatingPower = state ? id(BACKUP_HEATER_LEVEL_DHW).state * 230.0 /*V*/ * 12.6 /*A*/ : 0.0f;
+            float electricHeatingPower = 0.0f;
+            if (state && !isnan(id(BACKUP_HEATER_LEVEL_DHW).state)) {
+              electricHeatingPower = id(BACKUP_HEATER_LEVEL_DHW).state * 230.0 /*V*/ * 12.6 /*A*/;
+            }
             id(ELECTRIC_HEATING_POWER).publish_state(electricHeatingPower);
           });
 
@@ -91,13 +94,13 @@ select:
     name: "PASSIVE_COOLING"
     id: PASSIVE_COOLING
     options:
-      - "Aus"
-      - "Ablüften"
-      - "Zulüften"
-      - "Bypass"
-      - "Sommerkassette"
-      - "Unbekannt"
-    initial_option: "Unbekannt"
+      - "OFF"
+      - "EXHAUST_FLUSH"
+      - "FRESH_AIR_INTAKE"
+      - "BYPASS_MODE"
+      - "SUMMER_CASSETTE"
+      - "UNKNOWN"
+    initial_option: "UNKNOWN"
     optimistic: true
     setup_priority: 100
     set_action:
@@ -112,15 +115,15 @@ select:
     name: "PROGRAM_SWITCH"
     id: PROGRAM_SWITCH
     options:
-      - "Notbetrieb"
-      - "Bereitschaft"
-      - "Automatik"
-      - "Tagbetrieb"
-      - "Absenkbetrieb"
-      - "Warmwasser"
-      - "Handbetrieb"
-      - "Unbekannt"
-    initial_option: "Unbekannt"
+      - "EMERGENCY_MODE"
+      - "STANDBY_MODE"
+      - "AUTO_MODE"
+      - "DAY_MODE"
+      - "HOLIDAY_MODE"
+      - "DHW_MODE"
+      - "MANUAL_MODE"
+      - "UNKNOWN_MODE"
+    initial_option: "UNKNOWN_MODE"
     optimistic: true
     setup_priority: 100
     set_action:
@@ -149,6 +152,7 @@ sensor:
     state_class: measurement
     device_class: power
     unit_of_measurement: "W"
+    lambda: "return 0.0f;"  # Initialize with 0W (updated by callback)
 
 #########################################
 #                                       #
