# 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.*`

```python
# 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

```yaml
# 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 |