v2.1.0-beta.6

Hitachi Yutaki v2.1.0-beta.6 — Electricity Cost & Sentinel Filtering

Track your heat pump's electricity cost with a new sensor, and enjoy cleaner data — the gateway now filters Modbus sentinel values and gates unconfigured modules.

✨ New Features

Electricity Cost Estimation (#273)

Configure an external electricity price sensor and the integration computes a cumulative cost sensor tracking how much your heat pump costs to run.

• New electricity_cost sensor — monetary device class, cumulative total, persisted across restarts
• New electrical_power sensor — real-time electrical power in kW, derived from external power entity or Modbus register
• Repair flow — existing users are prompted to configure the electricity price entity via a non-blocking repair
• Currency-aware — config flow descriptions use {currency} placeholder resolved from your HA currency setting instead of hardcoded €
• Energy pipeline refactor — DerivedMetricsAdapter now centralizes electrical energy resolution (external entity, gateway register, or calculated from current × voltage), replacing scattered _get_energy_value() calls

🐛 Bug Fixes

Gateway Sentinel Filtering (#272)

Modbus gateways return sentinel values for physically absent sensors (-127) and unavailable modules (-67). These were previously propagated as real values to entities and telemetry.

• RegisterDefinition.sentinel_values — each register declares its known sentinels as a frozenset[int]
• 3-way branching — _read_register() returns a _SENTINEL_FILTERED marker (Python equivalent of JS Symbol()), distinguishing sentinel from read error. Sentinels clear stale data; read errors preserve last known value
• No fallback on sentinel — if the primary register returns a sentinel, the fallback register is skipped (sensor is known-absent, not errored)

Module Gating (#272)

Unconfigured modules (DHW, pool, circuit 2) returned default register values that leaked into telemetry snapshots. The gateway now purges data keys for modules not present in system_config after each read cycle.

• Entity conditions simplified — hardcoded -127 checks removed from hydraulic entity conditions, replaced by clean is not None checks since the gateway handles data quality

♻️ Other Changes

• power_consumption sensor attribute source removed — energy source selection is now internal to the adapter (#273)
• Entity recategorization: some entities moved between sensor and diagnostic categories (#273)

📦 Installation

1. Update via HACS to v2.1.0-beta.6
2. Restart Home Assistant

---

Full Changelog: v2.1.0-beta.5...v2.1.0-beta.6

v2.1.0-beta.5

Hitachi Yutaki v2.1.0-beta.5 — DerivedMetricsAdapter & Dict-Based Telemetry

Major architecture refactor: COP, thermal power, and timing calculations are centralized in a new adapter. Telemetry switches from rigid dataclass fields to flexible dicts. Net result: -1600 lines, zero-friction data key additions, and accurate COP for all configurations.

Beta — this is a significant internal refactor. Entity behavior should be identical to beta.4 but the computation path has changed. Please report any discrepancies.

♻️ Architecture Changes

DerivedMetricsAdapter (#269)

COP, thermal power, electrical power, and compressor timing are now computed centrally in adapters/derived_metrics.py — called once per poll cycle, before entities and telemetry consume the data. Previously, each COP/thermal/timing entity instantiated its own domain service (~590 lines of subclass code).

• Entities simplified — HitachiYutakiCOPSensor, HitachiYutakiThermalSensor, and HitachiYutakiTimingSensor subclasses deleted. All sensors now use simple value_fn readers on the base class.
• Recorder rehydration — COP history replay and thermal energy state restoration moved to the adapter, called once at startup.
• Defrost guard — now owned by the adapter instead of the coordinator.

Dict-Based Telemetry (#270)

The MetricPoint dataclass (60+ named fields, duplicated across 7 files) is replaced by plain dicts. The collector buffers coordinator.data as-is — data keys are the vocabulary.

• Zero-friction additions — adding a new data key to telemetry requires no code changes. It flows automatically from coordinator to backend.
• Pattern-based anonymization — temperatures rounded by key pattern (*_temp → 0.5°C) instead of field-by-field dataclass replace.
• Client-side daily stats removed — the TimescaleDB metrics_daily_agg continuous aggregate is now the authoritative source.

🐛 Bug Fixes

COP Accuracy for S80 Cascade

The telemetry COP was computed using only the primary Modbus compressor_current, missing the external power sensor and secondary compressor. For S80 cascade installations, this produced a COP of ~8.2 instead of the correct ~1.3. The DerivedMetricsAdapter uses the same ElectricalPowerCalculatorAdapter as HA entities, including external power entity access and secondary compressor support.

🔧 Tooling

• make bump PART=beta — bump the beta version number (e.g. beta.4 → beta.5)
• make bump (patch) on a beta version promotes to release (e.g. 2.1.0-beta.5 → 2.1.0)

📦 Installation

1. Update via HACS to v2.1.0-beta.5
2. Restart Home Assistant

---

Full Changelog: v2.1.0-beta.4...v2.1.0-beta.5

v2.1.0-beta.4

Hitachi Yutaki v2.1.0-beta.4 — DHW Demand Mode & Telemetry Power Fix

New diagnostic sensor for DHW demand mode and a fix for telemetry power/COP fields that were being sent as null values to the backend.

Beta — all telemetry installations were affected by the null power fields. This release fixes ~49k rows worth of missing data going forward.

✨ New Features

DHW Demand Mode Sensor (#255)

A new diagnostic ENUM sensor exposing the configured DHW demand mode (standard / high demand) read from the STATUS register, independently of whether the water heater is on or off.

• Always available — unlike current_operation which returns off when DHW is not running, this sensor always shows the configured mode
• Disabled by default — enable it in the entity settings when needed for automations
• Gateway support — ATW-MBS-02 (register 1079) and HC-A (offset 130) — not available on pre-2016 gateways

🐛 Bug Fixes

Telemetry Power & COP Computation (#264)

The telemetry collector was sending null for thermal_power, electrical_power, and cop_instant in every metric point. The pipeline was wired end-to-end but the actual computation was missing.

• Thermal power — computed from water inlet/outlet temperatures and flow rate using the existing domain calculator
• Electrical power — computed from compressor current with single/three-phase support
• COP instant — computed as thermal/electrical power ratio, with aberrant values (> 15) discarded as transient noise

📦 Installation

1. Update via HACS to v2.1.0-beta.4
2. Restart Home Assistant

---

Full Changelog: v2.1.0-beta.3...v2.1.0-beta.4

v2.1.0-beta.3

Hitachi Yutaki v2.1.0-beta.3 — Anonymous Telemetry

Anonymous telemetry system to collect anonymized heat pump performance data, helping build realistic test fixtures and improve the integration for all models. Telemetry is disabled by default and requires explicit opt-in.

Beta — looking for early adopters to opt in and help validate the telemetry pipeline. See Discussion #200 for context.

✨ New Features

Anonymous Telemetry System (Discussion #200)

• Binary consent (Off / On) — configurable in integration options or via repair notification for existing users
• Anonymized data — SHA-256 instance hash, temperatures rounded to 0.5°C, coordinates rounded to 1° (~110 km)
• World model data — compressor thermodynamics, valve openings, pressures, setpoints, control state, Köppen-Geiger climate zone
• Diagnostic sensor — sensor.telemetry_status shows telemetry level and send tracking attributes
• Sentinel filtering — Modbus values -127 (no sensor) and -67 (not configured) filtered to NULL
• Daily stats — aggregated performance statistics sent once at day boundary
• One-time register snapshot — full Modbus register dump for fixture generation
• Backend — Cloudflare Worker (ingestion proxy with validation and rate limiting), TigerData (TimescaleDB), R2 cold archive, Grafana dashboards

📦 Installation

1. Update via HACS to v2.1.0-beta.3
2. Restart Home Assistant
3. A repair notification will appear — choose whether to enable telemetry
4. You can change your choice at any time in Settings > Devices & Services > Hitachi Heat Pump > Configure

---

Full Changelog: v2.1.0-beta.2...v2.1.0-beta.3

v2.1.0-beta.2

Hitachi Yutaki v2.1.0-beta.2 — Gateway Sync Resilience

Improves how the integration handles extended gateway synchronization issues (initializing/desynchronized states). Previously the integration would spam logs and silently serve stale data — it now backs off gracefully and marks entities as unavailable until the gateway recovers.

Beta — looking for testers who have experienced intermittent gateway sync issues. See #254 for context.

🐛 Bug Fixes

Gateway Sync Resilience (#254)

When the ATW-MBS-02 gateway enters "initializing" state for extended periods (~50 minutes), the integration now handles it gracefully:

• Entities marked unavailable — entities correctly show as "unavailable" instead of displaying frozen values that appear normal
• Adaptive polling backoff — polling interval gradually increases (5s → 10s → 20s → ... → 5min max), reducing ~700 useless polls to ~25
• Log spam eliminated — ~685 identical warnings replaced by one initial warning + periodic reminders every 5 minutes + a recovery message
• Sync state sensor fixed — the "Gateway Sync State" sensor now correctly displays "Initializing" instead of the raw register value 2
• Automatic recovery — normal polling interval is restored as soon as the gateway returns to "Synchronized" state

🔧 Changes

Config Flow Refactoring

Config flow refactored to provider-based orchestrator — each gateway type declares its own configuration steps via GatewayConfigProvider protocol, eliminating all gateway-specific conditionals from config_flow.py.

v2.1.0-beta.1

Hitachi Yutaki v2.1.0-beta.1 — Before Line-up 2016 Gateway Support

Full read/write support for Gen 1 Yutaki S and S Combi units using the Before Line-up 2016 ATW-MBS-02 register map.

Beta — looking for testers with Gen 1 units. See #248 to participate.

Upgrading from v2.0.x? Update via HACS and restart. Existing configurations are automatically migrated (v2.4 migration adds gateway_variant: gen2).

✨ New Features

Before Line-up 2016 Gateway Support (#248)

Gen 1 Yutaki units (RWD-x.xNWE/NWSE, manufactured before ~2016) use a different Modbus register map than newer models. This release adds full support:

• All sensors: temperatures, operation state, system status, compressor data, DHW
• All controls: unit power/mode, circuit power/OTC/thermostat, DHW power/target/anti-legionella, pool power/target
• Automatic entity filtering: entities that depend on registers absent from Gen 1 (eco mode, DHW boost/high demand, Auto HVAC mode) are automatically hidden — no ghost entities

Gateway Variant System

The config flow now asks for the hardware generation after selecting ATW-MBS-02:

• Auto-detection: after connecting, the integration probes the gateway to suggest the correct generation
• Manual override: users can verify and change the detected generation
• Model decoder tool: an interactive tool helps identify the hardware generation from the unit's model reference

Model Nomenclature Documentation

A comprehensive reference guide explains how to decode Hitachi model references (RWD, RWM, RWH, RASM) to identify the hardware generation, refrigerant type, and applicable register map.

Scanner Support

The scan_gateway.py script now auto-detects Before Line-up 2016 units and annotates register scans with the correct register names.

🐛 Bug Fixes

Cooling OTC Method (#239)

The cooling OTC compensation method was showing "Unknown" and was not settable on ATW-MBS-02 gateways.

Entity Filtering for Missing Registers

Entities depending on registers that don't exist on certain gateways (eco mode, DHW boost/high demand) are now hidden automatically instead of appearing as unavailable.

🔧 Changes

Config Entry Migration v2.4

Existing config entries are automatically migrated to include the gateway_variant field (set to gen2 for all existing installations).

Test Reorganization

Gateway register map tests are reorganized to mirror the source structure (tests/api/modbus/).

v2.0.2

Hitachi Yutaki v2.0.2 — New Sensors, Bug Fixes & Documentation Overhaul

A patch release with new water outlet temperature sensors, several bug fixes, and a complete documentation restructure.

Upgrading from v2.0.1? Simply update via HACS and restart — no migration needed.

✨ New Features

Water Outlet 2 & 3 Temperature Sensors (#161)

New Two2 and Two3 temperature sensors for systems equipped with buffer tanks. These expose the secondary and tertiary water outlet temperatures that were previously unavailable.

Brand Assets for HA 2026.3+

Local brand assets are now included for compatibility with the Home Assistant 2026.3+ brand proxy API.

🐛 Bug Fixes

Pool Target Temperature (#233)

The pool target temperature was incorrectly divided by 10 (tenths conversion), causing the displayed target to be far lower than the actual setpoint.

Phantom Compressor Pressure Registers (#225)

Secondary compressor pressure registers at non-existent Modbus addresses 1150/1151 have been removed. These phantom registers could cause read errors on systems without a secondary compressor.

Scan Interval Not Editable

The scan interval field was missing from the options flow, preventing users from changing the polling interval after initial setup.

🔧 Changes

Runtime Data Migration

Runtime data storage migrated from hass.data[DOMAIN] to ConfigEntry.runtime_data, following modern Home Assistant patterns.

Documentation Restructure

The entire documentation has been restructured into a unified docs/ directory with dedicated sections for architecture, development guides, and reference material. In-code READMEs and the legacy documentation/ directory have been removed.

🏗️ Project Quality

• Quality scale: Bronze tier tracking with quality_scale.yaml
• Config flow tests: 12-test suite covering all flow steps
• Base entity module: entity.py for common-modules quality standard
• CI: now testing against Python 3.13 and 3.14
• License: MIT LICENSE file added
• GitHub templates: issue templates (bug report, feature request) and PR template

v2.0.1

Hitachi Yutaki v2.0.1 — Bug Fixes & Config Flow Cleanup

A patch release fixing COP calculation accuracy issues across multiple scenarios and cleaning up the configuration flow.

Upgrading from v2.0.0 or any v2.0.1-beta? Simply update via HACS and restart — no migration needed.

🐛 Bug Fixes

HC-A(16/64)MB Outdoor Compressor Registers (#96)

Outdoor compressor registers (discharge temp, evaporator temp, current, frequency, EVO opening) were mapped to the wrong address block (5000+offset instead of 30000+offset) on HC-A(16/64)MB gateways, causing these sensors to show as unavailable.

DHW/Pool COP Calculation (#205)

COP calculation for DHW and pool modes used the circuit outlet register (1094) instead of the HP-level outlet register (1201). When the 3-way valve redirects flow to the DHW tank, the circuit register becomes stale, causing zero thermal power and no COP during DHW runs.

Electrical Power Unit Conversion (#182)

The power unit detection used a naive > 50 heuristic to guess whether the measured power was in W or kW. A heat pump in standby consuming < 50 W was incorrectly interpreted as kW (e.g. 49 W treated as 49 kW), causing wildly inaccurate COP values. The adapter now reads the entity's unit_of_measurement attribute and uses Home Assistant's built-in PowerConverter to properly normalize to kW.

Dutch Translations

Updated Dutch (nl) translations.

🔧 Changes

Config Flow Cleanup

• Removed unused dev_mode option from advanced settings
• Moved Modbus Device ID from advanced step to gateway configuration step
• Namespaced Modbus connection keys with modbus_ prefix (modbus_host, modbus_port, modbus_device_id) to prepare for future non-Modbus gateway support
• Automatic config entry migration (v2.1 → v2.2) renames stored connection keys for existing installations

Development

• Bump ruff from 0.13.3 to 0.15.2
• Added CONTRIBUTING.md with contributor workflow documentation

📦 Installation

From v2.0.0

1. Update via HACS to v2.0.1
2. Restart Home Assistant
3. No migration needed

From v2.0.1-beta.x

1. Update via HACS to v2.0.1
2. Restart Home Assistant
3. No migration needed

🐛 Bug Reports

If you encounter issues, please report with:

• Home Assistant version
• Heat pump model and gateway type (ATW-MBS-02 or HC-A(16/64)MB)
• Relevant logs (custom_components.hitachi_yutaki)

---

Full Changelog: v2.0.0...v2.0.1

v2.0.1-beta.3

Hitachi Yutaki v2.0.1-beta.3 — Power Unit Conversion Fix

⚠️ This is a pre-release for testing.

Please report results in #182.

🐛 Bug Fixes

• Electrical power unit conversion now uses HA's PowerConverter (#182) — The domain service used a naive > 50 heuristic to guess whether measured power was in W or kW. A heat pump in standby consuming < 50 W was interpreted as kW (e.g. 30 W → 0.03 kW was left as-is, but more critically values like 49 W were treated as 49 kW), causing wildly inaccurate COP values. The adapter now reads the entity's unit_of_measurement attribute and uses Home Assistant's built-in PowerConverter to properly normalize to kW before passing to the domain layer.

📦 Installation

1. Update via HACS to v2.0.1-beta.3
2. Restart Home Assistant
3. COP sensors should now show correct values when the power entity reports in Watts

🐛 Bug Reports

If you encounter issues, please report with:

• Home Assistant version
• Heat pump model and gateway type
• Power entity unit (W, kW, etc.)
• Relevant logs (custom_components.hitachi_yutaki)

---

Full Changelog: v2.0.1-beta.2...v2.0.1-beta.3

v2.0.1-beta.2

Hitachi Yutaki v2.0.1-beta.2 — DHW/Pool COP Fix & Dutch Translations

⚠️ This is a pre-release for testing.

Please report results in #205 or #96.

🐛 Bug Fixes

• DHW/Pool COP calculation now uses correct water outlet register (#205) — Register 1094 (water_outlet_temp) measures the heating circuit outlet. During DHW runs the 3-way valve redirects flow to the tank, making reg 1094 stale (inlet > outlet → thermal_power = 0 → no COP). The primary read is now register 1201 (HP-level outlet, correct in all modes) with 1093 as fallback for gateways that don't expose it. A generic fallback field on RegisterDefinition enables automatic retry on a secondary register.

• HC-A(16/64)MB outdoor compressor registers mapped to wrong address block (#96) — Outdoor unit registers (section 5.3) use a fixed base address of 30000, not the indoor unit base 5000. This caused compressor discharge temp, evaporator temp, current, frequency, and EVO opening to show as unavailable on HC-A(16/64)MB gateways.

• Dutch (nl) translations updated — Corrected and improved Dutch translation strings.

📦 Installation

1. Update via HACS to v2.0.1-beta.2
2. Restart Home Assistant
3. DHW/Pool COP sensors should now show correct values

🐛 Bug Reports

If you encounter issues, please report with:

• Home Assistant version
• Heat pump model and gateway type
• Relevant logs (custom_components.hitachi_yutaki)

---

Full Changelog: v2.0.1-beta.1...v2.0.1-beta.2