147 lines
5.3 KiB
Markdown
147 lines
5.3 KiB
Markdown
# 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 | |