Hcv

Viessmann Vitocal (E3) CAN-Bus to MQTT Bridge with Home Assistant Support

Please also read the HCV Description in the docu folder.

An isolated, passive CAN-bus adapter to fetch local data from Viessmann E3-generation heat pumps (e.g., Vitocal 250-A, 252-A) and stream it via Wi-Fi to MQTT with native Home Assistant Auto-Discovery.

🚀 Key Features

• 100% Local Control: No internet dependency, no official ViCare Cloud API rate limits.
• Hardware Protection: Features full galvanic isolation to protect your expensive heat pump from electrical damage.
• Passive Sniffing: Read-only operation ensures zero interference with the heating system's warranty.
• Plug & Play for Home Assistant: Built-in MQTT Discovery automatically creates all entities (temperatures, flow rates in L/h, energy in kWh, and states) without writing a single line of YAML.
• Universal Compatibility: Works seamlessly with Home Assistant, ioBroker, Node-RED, openHAB, and Symcon.

🔀 Supported Series & Target Selection (V200 vs. V250)

This project supports both the E3 Generation (e.g., Vitocal 250-A, 252-A) and the V200/WO1C CAN Protocol (e.g., Vitocal 200-S, 200-A, HCV) via dedicated software builds.

Selective DID Profile (vcalobj200.did) for Vitocal 200

When using the Vitocal 200 Firmware, the DID profile file must be uploaded as vcalobj200.did. Addresses correspond strictly to the WO1C / HCV hexadecimal address map:

# ==============================================================================
# embdes Viessmann Vitocal 200 / WO1C Custom DID Profile
# Line comments starting with '#' are fully supported.
# ==============================================================================

# Core Temperatures & Controls (WO1C Hex Format)
{0x0100, OutdoorTemp, Aussentemperatur, 0, 1, FLOAT_TEMP_10},
{0x0371, OperatingMode, Betriebsart, 0, 1, INTEGER},
{0x0401, MixerPumpState, StatusMischerPumpe, 0, 1, ON_OFF},

🛠️ Project Structure & License Model

This project follows a hybrid Open Hardware / Commercial Software model to support the community while funding the extensive reverse-engineering work behind the Viessmann CAN protocols.

1. Open Hardware (Free)

All hardware files are open-source. You can find the schematics, PCB layout files (KiCAD/EasyEDA), Bill of Materials (BOM), and a 3D-printable enclosure STL file in the /hardware folder. Feel free to DIY and order your own boards.

2. Pre-Assembled Hardware (Optional)

If you do not want to solder SMD components or lack the equipment, you can buy a fully assembled and tested hardware unit inside its enclosure directly from me for **approx. €35 + MwSt ** (plus shipping from Germany).

3. Firmware & Software License

• Demo Version (Free): Includes the local Wi-Fi/MQTT captive portal captive setup, hardware connection test, and displays your unique ESP32 Chip ID.
• Full Version (€48 + MwSt) Unlocks all heating data points, daily energy counters, and native Home Assistant Auto-Discovery. It is a one-time payment per device and works 100% offline (via a license file uploaded to the file system).

💻 Getting Started

Hardware Connection

Connect the adapter to the INTERNAL CAN-bus of your Viessmann heat pump (typically labeled as "Plug 72" / Stecker 72 on the main terminal block).

Firmware Setup

1. Flash the free firmware build to your ESP32.
2. Power on the device and connect to the Wi-Fi Access Point generated by the adapter.
3. Open http://192.168.1.1 in your browser, enter your local Wi-Fi and MQTT broker credentials.
4. Copy the unique Chip ID shown on the web interface.

Activating the Full Version

To unlock all sensors and Home Assistant Auto-Discovery:

1. Reach out to me via PM in the Forums or via Email at info@embdes.com with your Chip ID.
2. After payment (€50), you will receive a license.txt file.
3. Upload this file through the adapter's web interface and reboot the device.
4. Open Home Assistant ➔ Settings ➔ Devices & Services ➔ MQTT—your heat pump will show up automatically!

📊 Supported Data Points (Extract)

• Analogue Sensors: Flow/Return temperatures, Outdoor temperature, Domestic Hot Water (DHW) temp, Compressor frequency.
• Flowrates: Allengra Sensor / Volumetric flow rate (properly formatted in L/h).
• Energy Dashboard: Daily energy consumption (properly formatted in kWh with total_increasing state class).
• Binary States: Compressor status, Mixer pump status, Error flags (formatted with native running and problem device classes).

⚙️ Customizing Data Points (Selective DIDs)

By default, the adapter processes all available data points. To keep your MQTT broker clean and reduce network traffic, you can now upload a custom selection profile via a vcalobj.did file through the web interface.

Only the DIDs specified in this file will be active on the CAN bus, transmitted via MQTT, and displayed in the local web app.

CAN Bus Logging

• Integrated CAN bus logging to record and analyze raw network traffic.
• Supports capturing all bus messages or filtering by specific CAN IDs to easily discover and map new DIDs for custom MQTT messages.

Data Identifier (DID) Management & Web Interface

• Structured handling and parsing of Data Identifiers (vcalobj.did).
• Responsive Web UI featuring dedicated help text styling to cleanly separate parameter descriptions from real-time sensor data.

File Format (vcalobj.did)

The file must be uploaded as a plain text or CSV-like format using the following structure: {ID, Description_Original, Description_Custom, Byte_Position, Display_Flag, DID_TYPE}

Here is a verified example for a minimal setup (Core temperatures, flowrate, and energy counters).

Note: New releases may expand the configuration; the file itself is always the source of truth.

# ==============================================================================
# embdes Viessmann E3 Custom DID Profile
# Remove or add rows to customize your MQTT payload and local dashboard.
# Line comments starting with '#' are fully supported.
# ==============================================================================

# Core Temperatures
{268, FlowTemperatureSensor, Vorlauftemperatur, 0, 1, FLOAT_TEMP_10},
{269, "ReturnTemperatureSensor", "AußeneinheitRücklauftemperatur", ...},
{271, DomesticHotWaterSensor, WarmwasserTemperatur, 0, 1, FLOAT_TEMP_10},
{274, OutdoorTemperatureSensor, Aussentemperatur, 0, 1, FLOAT_TEMP_10},

# Flowrate & Hydraulics
{1043, VolumetricFlowrateSensor, DurchflussSensorStd, 0, 1, FLOAT_LH},

# Energy Dashboard
{548, EnergyConsumptionPerDay, EnergieaufnahmeProTagInKWh, 0, 1, P_KWH},

# Binary States (On/Off)
{401, MixerPumpStatus, StatusMischerPumpe, 0, 1, ON_OFF},

⚠️ Critical Formatting Rules

To avoid parsing errors on the microcontroller, ensure your vcalobj.did strictly adheres to these rules:

1. No trailing spaces before commas: Ensure numeric values do not contain spaces before a comma (e.g., use 1, instead of 1 ,).
2. Entity naming: Avoid special characters like % within the custom description strings. Use clean alphanumeric names (e.g., LuefterEinsDrehzahl instead of LuefterEinsDrehzahl%).
3. Valid Data Types: Supported DID_TYPE tokens are:
   • FLOAT_TEMP_10, FLOAT_PRES_10, FLOAT_PRES_100
   • ON_OFF, INT_TIME, INT_PERC, P_KWH, P_WATT
   • FLOAT_LH, INTEGER

How to apply changes

1. Create or edit your vcalobj.did file using a standard text editor (like VS Code or Notepad++).
2. Open the adapter's web interface in your browser.
3. Navigate to the File Upload section, select your vcalobj.did file, and hit upload.
4. The adapter will validate the file, save it to the internal flash storage, and dynamically reload the database into RAM without needing a manual hardware reset.

🚗 Integration with evcc (PV Charging Manager)

The embdes adapter can be integrated into evcc as a passive heat pump power meter. Since the adapter operates strictly in read-only mode, it is 100% safe and will not interfere with your Viessmann warranty.

To display your heat pump's consumption in evcc, add the following configuration to your evcc.yaml:

meters:
  - name: viessmann_heatpump
    type: custom
    power:
      source: mqtt
      topic: viessmann/wp/state
      jq: .EnergieaufnahmeProTagInKWh oder EnergyConsumptionCentralHeating # Fetches the daily energy counter from the JSON payload

Note: The adapter acts as a pure data provider (Push-to-MQTT). No active HTTP polling or writing to the CAN-bus is required or supported.

Web UI Parameter Control (Write Support)

Starting with v1.14.0, the HCV Web Interface allows you to adjust parameters directly on the Vitocal 250 heating unit without needing external automation scripts or manual MQTT commands.

Key Features:

• Direct Web Control: Click on writable parameters within the dashboard to bring up the interaction dialog.
• Safety & Boundary Checks: Displays allowed minimum and maximum boundaries (e.g., Min: 10 | Max: 60 for WarmwasserSolltemperaturNormal) defined by vcalobj.did to prevent invalid inputs.
• DID Transparency: Clearly displays the active Data Identifier (e.g., DID: 0x18C).
• Instant Bus Dispatch: Clicking Senden formats and transmits the updated setpoint straight to the Vitocal CAN bus.

🛠️ Changelog & What's New

Release v1.41 – Smart Connector Assignment, Transparent VX3 DID Allocation & Ethernet Rescue Mode

This release introduces a streamlined, connector-driven DID management architecture, transparent Vitocharge VX3 integration, and solidifies the Early-Boot Ethernet Rescue Mode for reliable recovery. What’s New in v1.41

• Smart Connector-Driven DID Assignment Connector Selection: Added a dedicated CAN Connector dropdown (Stecker 72 vs. Stecker 91) in the Web UI (/options).

  • Stecker 72 (Internal Refrigerant Circuit CAN): Tailored for local heat pump sensors & circuit modules.

  • Stecker 91 (System CAN Bus): Used for system-wide metrics and external device integration.

    Dynamic UI Form Adaptation: Selecting Stecker 91 automatically hides module-specific checkboxes (Heizkreis 1–3, DHW, Buffer) in the frontend to prevent invalid or conflicting configuration options.

• Transparent Vitocharge VX3 / PV Integration

  • Removed UI Clutter: The standalone VX3 / c_pv checkbox has been removed from the frontend UI.
  • Unified Object Storage: Vitocharge VX3 DIDs are now natively embedded within the core /vobjects.dat file.
  • Automatic Backend Activation: When Stecker 91 is selected, the firmware automatically injects the CAT_VX3 bit (0x0040 / Bit 64) into the active object bitmask (activeMask) during loadVcalObjDat(). PV, battery, and inverter metrics are loaded seamlessly without requiring user intervention.

• Early-Boot Ethernet Rescue Mode (Hot-Plug Recovery)

  • Deterministic Network Modes: Strict separation between Ethernet (netMode = 0) and Wi-Fi (netMode = 1). No unexpected fallback switching.

    Bootloop & Freeze Prevention: If a corrupted or oversized custom .did file prevents the device from starting, trigger the rescue mode via hot-plug:

    Unplug the Ethernet cable.
    
    Power-cycle the HCV module.
    
    Re-plug the Ethernet cable within 10 seconds of cold boot.

    Safe Recovery Environment: The device enters Rescue Mode (http://hcv.local and Telnet on Port 23). Custom user DID files (/uobjects.dat) are completely bypassed, allowing web/FTP/Telnet access to delete or repair damaged files.

Release v1.38

Comprehensive stability update focusing on Wi-Fi connection resilience, LwIP stack crash prevention, and UI setup flexibility.

Key Improvements & Fixes

• Active Wi-Fi Watchdog & Auto-Recovery:

  • Integrated background monitoring for Wi-Fi connection state.
  • Periodically retries connection every 15 seconds if disconnected.
  • Triggers an automatic system reboot (ESP.restart()) after 5+ minutes of continuous disconnection (e.g., during night-time router/repeater reboots) to guarantee clean re-association with the AP.

• Deterministic Network Mode:

  • Ethernet Mode: PHY initializes on boot and strictly waits for cable connection and DHCP IP lease. Prevents unintended fallback to Wi-Fi. Supports hot-plugging.
  • Wi-Fi Mode: Connects strictly to the configured Wi-Fi network.

• LwIP Stack & Crash Prevention (mbox Fix):

  • Optimized initialization sequence in startNetwork().
  • WiFi.mode(WIFI_STA) is invoked at the very start to ensure LwIP mailboxes and tasks are fully operational before launching CAN bus tasks, WebServer, or MQTT sockets.

• Flexible Wi-Fi Pre-Configuration (Web UI):

  • Replaced static select dropdown with a free-text <input> linked to an HTML5 <datalist>.
  • Allows manual SSID entry in Ethernet mode to pre-configure Wi-Fi credentials without requiring an active Wi-Fi scan.

Release v1.33

• Added:  Expanded Telnet terminal functions and command handling for remote diagnostics.
• Added:  Dedicated logging for MQTT connection status and WiFi disconnect reason codes.
• Improved:  Enhanced WiFi stability and compatibility with modern routers (PMF handling & disabled modem-sleep).
• Improved:  Reliability of NTP time synchronization across network interfaces.
• Fixed:  Cold-boot panic crash (ESP_RST_PANIC) during W5500 Ethernet initialization with plugged cable.
• Fixed:  Byte-alignment offset issue causing incorrect IP address rendering ("IP address all equal").
• Fixed:  Telnet session lifecycle and socket handling for the Ethernet variant.
• Fixed:  Relative boot timestamp calculations and log message update frequency.

🆕 New: HCV Ethernet & WLAN Edition - Release 1.30

In addition to the Wi-Fi-only version, the HCV Ethernet Edition is now available.

• 🔌 Dual Connectivity (LAN & Wi-Fi): Connect either via a standard RJ45 Ethernet network cable or Wi-Fi.
• 📶 Ideal for Basement Installations: Maximum stability and reliability – even in utility rooms with poor Wi-Fi reception.
• ⚡ Same Full Feature Set: Full support for all CAN data points, Home Assistant Auto-Discovery, and 100% cloud-free local operation.

Release v1.29

• Fixed: Resolved issue with Access Point (AP) mode selection.
• Fixed: Fixed main page rendering and display issues in Google Chrome browsers.
• Fixed: Corrected DID access for CAN ID 0x693 (Display Unit).
• Added: Password visibility toggle in the WebUI configuration panel.

Hardware 1.6

• Changed CAN Line protection

Release v1.25 – Dynamic VX3 DID Engine & Multi-Mode Support

🚀 Key Improvements & Features

• Dedicated vx3obj.did Table File: Fully decoupled VX3 data points from the standard Vitocal table (vcalobj.did).
• Three Flexible Operating Modes:
  1. Heat Pump Only (without VX3): Standard operating mode for standalone Vitocal heat pump systems.
  2. Heat Pump + VX3: Combined mode to read data from both the heating system and the PV/battery storage.
  3. VX3 Only (without Heat Pump): Dedicated mode for standalone Vitocharge storage/inverter installations.
• Enhanced DID Engine (v1.25 / v1.24): Fully dynamic decoding for all payload sizes (1, 2, and 4 bytes) including Big-Endian processing, signed power values (charge/discharge), and 32-bit multi-frame UDS responses (e.g., grid feed-in/consumption meters like DID 535).

📜 Changelog Summary (v1.22 – v1.25)

• v1.25: Improved VX3 mode detection and web display logic.
• v1.24: Added 32-bit integer handling (P_KWH / P_WATT) and improved sign/endianness processing.
• v1.23: Removed page refresh flicker on httpMain, corrected write-filter logic (writeFlg) for read-only sensor points, and added new VX3 configuration options in the Web UI.
• v1.22: Added dedicated VX3 data handler (active & passive mode), introduced vx3obj.did file, and fixed vcalobj.did mappings (corrected DID 534/535 to 526/528).

Enhancements (v1.21)

• Multi-Frame DID Support: Added ISO-TP multi-frame decoding support for long DIDs spanning multiple CAN messages.

Bug Fixes & Stability (v1.20)

• Critical Wi-Fi Auto-Connect Fix: Corrected WiFi.begin() parameter passing in auto-select mode, resolving connection issues when BSSID lock is unused.
• Wi-Fi 6 (802.11ax) Support: Explicitly enabled 802.11ax protocol support on ESP32-C6 targets (TARG_V250_C6) to prevent connection timeouts on Wi-Fi 6 routers (e.g., FRITZ!Box AX).
• AP Mode Wi-Fi Scanning: Configured AP mode to run in dual WIFI_AP_STA mode to allow asynchronous scanning of nearby networks during setup.
• Watchdog Stability (TWDT Fix): Offloaded OTA reboot and factory reset operations from the async_tcp task context to prevent Task Watchdog resets.

New Features & UI Enhancements

• SSID Selection Dropdown: Populates nearby Wi-Fi SSIDs with signal strength indicators (dBm) directly from the scan cache.
• Web UI Factory Reset: Added factory reset trigger into the setup dropdown menu (accessible exclusively in AP mode with safety prompt).
• Clean UI Formatting: Improved active SSID dropdown rendering.

🐛 Bug Fixes & Refinement (v1.19)

• CAN Data Display: Fixed an issue introduced in v1.18 where CAN data was not displaying correctly in the interface.
• DID Integer Display: Fixed false DID value formatting and display for integer units.

🌐 MQTT & System Stability (v1.18)

• Home Assistant Auto-Discovery: Fixed HA Discovery functionality upon MQTT reconnect, including proper handling of retained messages.
• Boot State Display: Set default DID value display to -- right after HCV boot until valid data is received.
• DID Object Management: Fixed automatic reloading of DID objects immediately after a new file upload.
• Wi-Fi Auto-Reconnect: Improved Wi-Fi reconnect mechanism by resetting the Wi-Fi channel after a timeout event.

⚙️ System Control & Network Configuration (v1.16 – v1.17)

• Global Reset: Added a global system reset function with safe CAN bus deinitialization (can deinit).
• Wi-Fi Manager: Reworked Wi-Fi configuration with integrated Access Point (AP) selection.

⚠️ Upgrade Note

If you are upgrading from v1.18, updating to v1.19.0 is strongly recommended to resolve the CAN data display issue.

✉️ Contact & Support

If you want to buy a pre-assembled board or a software license, please contact me:

• Home Assistant Forum: @chrkir
• ioBroker Forum: @chrkir
• Email: info@embdes.com

Disclaimer: This is a third-party community project. This project is not affiliated with, authorized, or endorsed by Viessmann.

Links & Resources

• GitHub Repository
• Dokumentation
• Hardware Ordner
• Software Ordner

Update-Info: Modulare DID-Auswahl & Einbindung eigener DIDs

Dieses Update passt die DID-Verarbeitung im HCV-Adapter direkt an die individuelle Ausstattung der jeweiligen Vitocal-Anlage an.

1. Abbildung der eigenen Vitocal-Konfiguration

Die zentrale DID-Tabelle (vcalobj.did) deckt verschiedene Anlagentypen und Erweiterungen ab. Über das Web-Interface unter Optionen lässt sich die Konfiguration exakt auf die tatsächlich verbauten Komponenten einstellen:

• [BASE]: Grundfunktionen (Außentemperatur, Vorlauf, Systemdruck, Verdichter)
• [HK1] / [HK2] / [HK3]: Heiz- und Mischerkreise
• [DHW]: Warmwasserbereitung und Zirkulation
• [BUFFER]: Pufferspeicher
• [PV_VX3]: Photovoltaik & Vitocharge VX3
• [SOLAR]: Solaranlage

Ablauf: Im Web-Interface werden nur die Haken bei den Modulen gesetzt, die in der eigenen Heizung vorhanden sind. Der Adapter liest daraufhin ausschließlich diese Datenpunkte in den Speicher ein.

2. Eigene DIDs und Update-Sicherheit (user.did)

Um eigene Anpassungen bei Updates der Standard-Tabelle nicht zu verlieren, ist die Konfiguration getrennt:

• Standard-Datei (vcalobj.did): Enthält die vom Adapter mitgelieferten Viessmann-DIDs.
• Eigene Datei (user.did): Enthält benutzerdefinierte DIDs in der Sektion [USER].

Beim Aktualisieren der vcalobj.did bleibt die user.did auf dem Gerät erhalten. Der Adapter lädt beim Start die ausgewählten Standard-Sektionen und hängt die Einträge aus der user.did an.

3. Funktionsweise im Hintergrund

• Upload: Beim Hochladen einer .did-Datei wird der Inhalt einmalig in eine Binärdatei auf dem Gerät umgewandelt (/vobjects.dat bzw. /uobjects.dat).
• Systemstart: Das zeilenweise Einlesen und Zerlegen von Textzeilen entfällt. Der Adapter lädt die gefilterten Datenblöcke direkt in den Arbeitsspeicher.

Kurzanleitung zur Einrichtung

1. vcalobj.did im Web-Interface hochladen.
2. Unter Optionen die Sektionen aktivieren, die in der eigenen Vitocal verbaut sind.
3. Eigene DIDs (falls vorhanden) in der Datei user.did unter [USER] ablegen und hochladen:

[USER]
{ 9999, "CustomSensor", "Mein_Eigener_Wert", 0, FLOAT_TEMP_10, 0, 0, 0x680, 1, 0, 2 }