ha_rdz_pdc_config/CLAUDE.md

CLAUDE.md - AI Assistant Context

This file provides context for AI assistants working with this codebase.

Project Overview

This is a Home Assistant custom integration for RDZ PDC heat pumps. It communicates with the heat pump's embedded web server via HTTP to monitor status and control temperatures.

Domain: ha_rdz_pdc_config

Architecture

custom_components/ha_rdz_pdc_config/
├── __init__.py       # Core: HeatPumpDataCoordinator, HeatPumpEntity base class, service registration
├── config_flow.py    # UI configuration wizard (URL + scan interval)
├── climate.py        # Climate entity for heating water temperature control
├── water_heater.py   # Water heater entity for DHW (domestic hot water) control
├── sensor.py         # Temperature sensors, runtime sensors, version sensor
├── binary_sensor.py  # Status binary sensors (heating, cooling, pump, alarm, etc.)
├── manifest.json     # Integration metadata
└── translations/en.json

Key Components

HeatPumpDataCoordinator (__init__.py:88)

Central data manager using Home Assistant's DataUpdateCoordinator pattern.

• Fetches JSON data from heat pump at configurable intervals (default 3s)
• Parses status response into normalized dict
• Provides set_water_setpoint() and set_dhw_setpoint() methods

HeatPumpEntity (__init__.py:224)

Base class for all entities. Provides common device_info linking all entities to "Heat Pump" device.

API Endpoints

• GET Status: Configurable URL (typically index.php?Action=GetStatus)
• POST SetParameter: <base_url>/index.php?Action=SetParameter with form data:
  • Key: "watersetpoint" or "dhwsetpoint"
  • Value: temperature string
  • manual: duration ("forever" or time-based)

Data Flow

1. User configures URL via config_flow
2. Coordinator fetches JSON every N seconds
3. JSON parsed into normalized dict with keys like water_temp_t1, is_heating, etc.
4. Platform entities read from coordinator.data
5. Climate/water_heater call coordinator methods to set temperatures

JSON Response Structure

Heat pump returns nested JSON. Key path: RESULT.status.*

# Main data extraction in __init__.py:122-158
status = data.get("RESULT", {}).get("status", {})

Critical fields:

Internal Key	JSON Path	Notes
water_temp_t1	status.watert1	Inflow temperature
water_temp_t2	status.watert2	Outflow temperature
dhw_temp_t3	status.dhwt3	Domestic hot water temp
outdoor_temp_t4	status.t4	Outdoor temperature
water_setpoint	status.watersetpoint	Heating target
dhw_setpoint	status.dhwsetpoint	DHW target
inlet_setpoint_temp	status.ISP	Smart setpoint (parse: "34.3 °C" -> 34.3)
is_heating	status.heating	Boolean
is_cooling	status.cooling	Boolean
is_working	status.pwr	Compressor running
is_dhw	status.san	DHW mode active
is_pump_active	status.pump	Circulation pump
is_aux_heater	status.res	Backup heater
is_standby	status.standby	Standby mode
has_alarm	status.alarm.status	Alarm active

Firmware Variations

Different firmware versions have different JSON structures. Sample responses in jsons/:

File	Version	Key Differences
og.json	v3.0.49	Has ISP, SSP, res, sce fields; ISP is string with unit
bogdan.json	v2.3.2	Missing ISP/SSP; simpler alarm structure; different temp ranges

Common issues requiring code modification:

• ISP field may not exist or have different format
• alarm.status vs just alarm.type
• Field names may vary

Entities Created

Climate (1):

• climate.heat_pump_water_temperature - Heating water thermostat

Water Heater (1):

• water_heater.heat_pump_dhw - DHW temperature control

Sensors (12):

• Temperature sensors: inlet_setpoint, system_setpoint, t1, t2, t3, t4, water_setpoint, dhw_setpoint, aux_heater
• Runtime sensors: worktime_pdc, worktime_res
• Info: software_version

Binary Sensors (10):

• heating, cooling, working, dhw_mode, water_pump, auxiliary_heater, standby, disabled_prod, sce, alarm

Services

# Set heating water temperature
service: ha_rdz_pdc_config.set_water_setpoint
data:
  temperature: 45.0  # 35-60°C
  duration: "forever"

Development Notes

Adding New Sensors

1. Add field extraction in HeatPumpDataCoordinator._async_update_data()
2. Add sensor definition in sensor.py or binary_sensor.py
3. Reference via self.coordinator.data.get("field_name")

Debugging

• Check HA logs for ha_rdz_pdc_config domain
• Test URL manually in browser to verify JSON response
• Compare response against jsons/*.json samples

Temperature Ranges

• Water setpoint: 35-60°C (hardcoded in service schema and climate entity)
• DHW setpoint: 35-60°C
• Step: 0.5°C

File Purposes Quick Reference

File	Purpose
__init__.py	Coordinator, base entity, service registration, data parsing
config_flow.py	UI setup wizard
climate.py	Heating water thermostat
water_heater.py	DHW thermostat
sensor.py	Temperature and runtime sensors
binary_sensor.py	Status on/off sensors
dashboards/dash.yaml	Example Lovelace dashboard
jsons/*.json	Sample API responses for testing/reference