From 75753494ab410c92f41ee96c0ef3e38ca540b083 Mon Sep 17 00:00:00 2001 From: Constantin Pascal Date: Mon, 19 Jan 2026 14:02:06 +0200 Subject: [PATCH] Preparing for public release --- CLAUDE.md | 8 +- README.md | 10 +- .../__init__.py | 4 +- .../binary_sensor.py | 2 +- .../climate.py | 2 +- .../config_flow.py | 2 +- .../manifest.json | 2 +- .../sensor.py | 2 +- .../translations/en.json | 0 .../water_heater.py | 2 +- docs/_config.yml | 30 ++ docs/api.md | 275 ++++++++++++++++++ docs/assets/images/.gitkeep | 0 docs/assets/images/README.md | 49 ++++ docs/configuration.md | 124 ++++++++ docs/dashboard.md | 187 ++++++++++++ docs/index.md | 74 +++++ docs/installation.md | 82 ++++++ docs/troubleshooting.md | 202 +++++++++++++ 19 files changed, 1040 insertions(+), 17 deletions(-) rename custom_components/{ha_rdz_pdc_config => rdz_innova_heatpump}/__init__.py (98%) rename custom_components/{ha_rdz_pdc_config => rdz_innova_heatpump}/binary_sensor.py (96%) rename custom_components/{ha_rdz_pdc_config => rdz_innova_heatpump}/climate.py (98%) rename custom_components/{ha_rdz_pdc_config => rdz_innova_heatpump}/config_flow.py (97%) rename custom_components/{ha_rdz_pdc_config => rdz_innova_heatpump}/manifest.json (88%) rename custom_components/{ha_rdz_pdc_config => rdz_innova_heatpump}/sensor.py (98%) rename custom_components/{ha_rdz_pdc_config => rdz_innova_heatpump}/translations/en.json (100%) rename custom_components/{ha_rdz_pdc_config => rdz_innova_heatpump}/water_heater.py (95%) create mode 100644 docs/_config.yml create mode 100644 docs/api.md create mode 100644 docs/assets/images/.gitkeep create mode 100644 docs/assets/images/README.md create mode 100644 docs/configuration.md create mode 100644 docs/dashboard.md create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/troubleshooting.md diff --git a/CLAUDE.md b/CLAUDE.md index 89c7bcd..26b30f8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,12 +6,12 @@ This file provides context for AI assistants working with this codebase. 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` +**Domain**: `rdz_innova_heatpump` ## Architecture ``` -custom_components/ha_rdz_pdc_config/ +custom_components/rdz_innova_heatpump/ ├── __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 @@ -110,7 +110,7 @@ Different firmware versions have different JSON structures. Sample responses in ```yaml # Set heating water temperature -service: ha_rdz_pdc_config.set_water_setpoint +service: rdz_innova_heatpump.set_water_setpoint data: temperature: 45.0 # 35-60°C duration: "forever" @@ -124,7 +124,7 @@ data: 3. Reference via `self.coordinator.data.get("field_name")` ### Debugging -- Check HA logs for `ha_rdz_pdc_config` domain +- Check HA logs for `rdz_innova_heatpump` domain - Test URL manually in browser to verify JSON response - Compare response against `jsons/*.json` samples diff --git a/README.md b/README.md index 9126d2e..d8e6cab 100755 --- a/README.md +++ b/README.md @@ -47,12 +47,12 @@ A custom Home Assistant integration for monitoring and controlling RDZ PDC heat ### Step 1: Copy Integration Files -Copy the `custom_components/ha_rdz_pdc_config` folder to your Home Assistant `custom_components` directory: +Copy the `custom_components/rdz_innova_heatpump` folder to your Home Assistant `custom_components` directory: ``` / └── custom_components/ - └── ha_rdz_pdc_config/ + └── rdz_innova_heatpump/ ├── __init__.py ├── climate.py ├── sensor.py @@ -166,7 +166,7 @@ The dashboard includes: ## Services -### `ha_rdz_pdc_config.set_water_setpoint` +### `rdz_innova_heatpump.set_water_setpoint` Manually set the heating water setpoint temperature. @@ -177,7 +177,7 @@ Manually set the heating water setpoint temperature. **Example:** ```yaml -service: ha_rdz_pdc_config.set_water_setpoint +service: rdz_innova_heatpump.set_water_setpoint data: temperature: 45 duration: forever @@ -200,7 +200,7 @@ data: ## Technical Details -- **Domain**: `ha_rdz_pdc_config` +- **Domain**: `rdz_innova_heatpump` - **IoT Class**: Local Polling - **Platforms**: sensor, binary_sensor, climate, water_heater - **Configuration**: UI-based (config_flow) diff --git a/custom_components/ha_rdz_pdc_config/__init__.py b/custom_components/rdz_innova_heatpump/__init__.py similarity index 98% rename from custom_components/ha_rdz_pdc_config/__init__.py rename to custom_components/rdz_innova_heatpump/__init__.py index 2b95dba..bcdaef8 100755 --- a/custom_components/ha_rdz_pdc_config/__init__.py +++ b/custom_components/rdz_innova_heatpump/__init__.py @@ -1,6 +1,6 @@ """ Custom integration for heat pump monitoring and control via web interface. -Place this code in custom_components/ha_rdz_pdc_config/__init__.py +Place this code in custom_components/rdz_innova_heatpump/__init__.py """ import asyncio import logging @@ -22,7 +22,7 @@ import voluptuous as vol import homeassistant.helpers.config_validation as cv _LOGGER = logging.getLogger(__name__) -DOMAIN = "ha_rdz_pdc_config" +DOMAIN = "rdz_innova_heatpump" DEFAULT_SCAN_INTERVAL = 3 # Add climate to the platforms diff --git a/custom_components/ha_rdz_pdc_config/binary_sensor.py b/custom_components/rdz_innova_heatpump/binary_sensor.py similarity index 96% rename from custom_components/ha_rdz_pdc_config/binary_sensor.py rename to custom_components/rdz_innova_heatpump/binary_sensor.py index dc181cc..48d81fe 100755 --- a/custom_components/ha_rdz_pdc_config/binary_sensor.py +++ b/custom_components/rdz_innova_heatpump/binary_sensor.py @@ -1,5 +1,5 @@ """ -Place this code in custom_components/ha_rdz_pdc_config/binary_sensor.py +Place this code in custom_components/rdz_innova_heatpump/binary_sensor.py """ from homeassistant.components.binary_sensor import ( BinarySensorEntity, diff --git a/custom_components/ha_rdz_pdc_config/climate.py b/custom_components/rdz_innova_heatpump/climate.py similarity index 98% rename from custom_components/ha_rdz_pdc_config/climate.py rename to custom_components/rdz_innova_heatpump/climate.py index ae62256..699ae53 100755 --- a/custom_components/ha_rdz_pdc_config/climate.py +++ b/custom_components/rdz_innova_heatpump/climate.py @@ -1,5 +1,5 @@ """ -Place this code in custom_components/ha_rdz_pdc_config/climate.py +Place this code in custom_components/rdz_innova_heatpump/climate.py """ import logging from typing import Any, Dict, List, Optional diff --git a/custom_components/ha_rdz_pdc_config/config_flow.py b/custom_components/rdz_innova_heatpump/config_flow.py similarity index 97% rename from custom_components/ha_rdz_pdc_config/config_flow.py rename to custom_components/rdz_innova_heatpump/config_flow.py index c19ba46..d77801d 100755 --- a/custom_components/ha_rdz_pdc_config/config_flow.py +++ b/custom_components/rdz_innova_heatpump/config_flow.py @@ -5,7 +5,7 @@ from homeassistant import config_entries from homeassistant.const import CONF_URL, CONF_SCAN_INTERVAL import voluptuous as vol -class HeatPumpMonitorConfigFlow(config_entries.ConfigFlow, domain="ha_rdz_pdc_config"): +class HeatPumpMonitorConfigFlow(config_entries.ConfigFlow, domain="rdz_innova_heatpump"): """Handle a config flow.""" VERSION = 1 diff --git a/custom_components/ha_rdz_pdc_config/manifest.json b/custom_components/rdz_innova_heatpump/manifest.json similarity index 88% rename from custom_components/ha_rdz_pdc_config/manifest.json rename to custom_components/rdz_innova_heatpump/manifest.json index bf35dc7..55d0034 100755 --- a/custom_components/ha_rdz_pdc_config/manifest.json +++ b/custom_components/rdz_innova_heatpump/manifest.json @@ -1,6 +1,6 @@ { - "domain": "ha_rdz_pdc_config", + "domain": "rdz_innova_heatpump", "name": "Heat Pump Monitor", "documentation": "https://github.com/your_username/heat_pump_monitor", "dependencies": [], diff --git a/custom_components/ha_rdz_pdc_config/sensor.py b/custom_components/rdz_innova_heatpump/sensor.py similarity index 98% rename from custom_components/ha_rdz_pdc_config/sensor.py rename to custom_components/rdz_innova_heatpump/sensor.py index 66be67e..f8f9dc4 100755 --- a/custom_components/ha_rdz_pdc_config/sensor.py +++ b/custom_components/rdz_innova_heatpump/sensor.py @@ -1,5 +1,5 @@ """ -Place this code in custom_components/ha_rdz_pdc_config/sensor.py +Place this code in custom_components/rdz_innova_heatpump/sensor.py """ from homeassistant.components.sensor import ( SensorEntity, diff --git a/custom_components/ha_rdz_pdc_config/translations/en.json b/custom_components/rdz_innova_heatpump/translations/en.json similarity index 100% rename from custom_components/ha_rdz_pdc_config/translations/en.json rename to custom_components/rdz_innova_heatpump/translations/en.json diff --git a/custom_components/ha_rdz_pdc_config/water_heater.py b/custom_components/rdz_innova_heatpump/water_heater.py similarity index 95% rename from custom_components/ha_rdz_pdc_config/water_heater.py rename to custom_components/rdz_innova_heatpump/water_heater.py index cd24cb3..672e433 100755 --- a/custom_components/ha_rdz_pdc_config/water_heater.py +++ b/custom_components/rdz_innova_heatpump/water_heater.py @@ -1,5 +1,5 @@ """ -Place this code in custom_components/ha_rdz_pdc_config/water_heater.py +Place this code in custom_components/rdz_innova_heatpump/water_heater.py """ from homeassistant.components.water_heater import ( WaterHeaterEntity, diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..1add512 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,30 @@ +title: RDZ PDC Heat Pump Monitor +description: Home Assistant custom integration for RDZ PDC heat pumps +remote_theme: pages-themes/cayman@v0.2.0 +plugins: + - jekyll-remote-theme + +# Navigation +header_pages: + - index.md + - installation.md + - configuration.md + - dashboard.md + - troubleshooting.md + - api.md + +# Build settings +markdown: kramdown +highlighter: rouge + +# GitHub repository info +github: + is_project_page: true + repository_url: https://github.com/your-username/rdz_innova_heatpump + +# Defaults +defaults: + - scope: + path: "" + values: + layout: default diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..a171e06 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,275 @@ +--- +layout: default +title: API Reference +nav_order: 6 +--- + +# API Reference + +## Heat Pump Web API + +The integration communicates with the heat pump's embedded web server. + +### Get Status + +Retrieves current heat pump status and sensor readings. + +**Endpoint:** +``` +GET /installedplugin/com.innova.pdc//server/index.php?Action=GetStatus +``` + +**Response:** +```json +{ + "sw": { "V": "3.0.49" }, + "success": true, + "model": "RDZ", + "RESULT": { + "TSLastUpdate": 1759138628, + "info": { + "datetime": "29/09/2025 12:37" + }, + "status": { + "ISP": "34.3 °C", + "SSP": 47.0, + "watert1": 32.1, + "watert2": 32.0, + "dhwt3": 46.8, + "t4": 9.6, + "watersetpoint": 43.0, + "dhwsetpoint": 47.0, + "heating": true, + "cooling": false, + "pwr": false, + "san": false, + "pump": true, + "res": false, + "standby": false, + "sce": true, + "alarm": { + "status": false, + "type": "", + "label": "" + }, + "worktime_pdc": 11614, + "worktime_res": 593 + } + } +} +``` + +### Status Fields + +| Field | Type | Description | +|-------|------|-------------| +| `ISP` | string | Inlet Setpoint (e.g., "34.3 °C") | +| `SSP` | float | System Setpoint | +| `watert1` | float | Inflow water temperature | +| `watert2` | float | Outflow water temperature | +| `dhwt3` | float | Domestic hot water temperature | +| `t4` | float | Outdoor temperature | +| `watersetpoint` | float | Water temperature setpoint | +| `dhwsetpoint` | float | DHW temperature setpoint | +| `heating` | bool | Heating mode active | +| `cooling` | bool | Cooling mode active | +| `pwr` | bool | Compressor running | +| `san` | bool | DHW mode active | +| `pump` | bool | Circulation pump active | +| `res` | bool | Auxiliary heater active | +| `standby` | bool | Standby mode | +| `sce` | bool | Smart Consumer Electronics | +| `alarm.status` | bool | Alarm active | +| `alarm.type` | string | Alarm type code | +| `alarm.label` | string | Alarm description | +| `worktime_pdc` | int | Compressor runtime (hours) | +| `worktime_res` | int | Aux heater runtime (hours) | + +### Set Parameter + +Sets a heat pump parameter (temperature setpoint). + +**Endpoint:** +``` +POST /installedplugin/com.innova.pdc//server/index.php?Action=SetParameter +``` + +**Content-Type:** `application/x-www-form-urlencoded` + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `Key` | string | Yes | Parameter name: `watersetpoint` or `dhwsetpoint` | +| `Value` | string | Yes | Temperature value | +| `manual` | string | Yes | Duration: `forever` or time-based | + +**Example:** +```bash +curl -X POST "http://192.168.1.100/installedplugin/com.innova.pdc/2.0.10/server/index.php?Action=SetParameter" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "Key=watersetpoint&Value=45&manual=forever" +``` + +**Response:** HTTP 200 on success + +--- + +## Home Assistant Services + +### rdz_innova_heatpump.set_water_setpoint + +Manually set the heating water temperature setpoint. + +**Service Data:** + +| Attribute | Type | Required | Description | +|-----------|------|----------|-------------| +| `temperature` | float | Yes | Target temperature (35-60°C) | +| `duration` | string | No | Duration: "forever" (default) or time-based | + +**Example YAML:** +```yaml +service: rdz_innova_heatpump.set_water_setpoint +data: + temperature: 45 + duration: forever +``` + +**Example Automation:** +```yaml +automation: + - alias: "Set water temperature on schedule" + trigger: + - platform: time + at: "06:00:00" + action: + - service: rdz_innova_heatpump.set_water_setpoint + data: + temperature: 45 + duration: forever +``` + +--- + +## Entities + +### Climate Entity + +**Entity ID:** `climate.heat_pump_water_temperature` + +**Attributes:** + +| Attribute | Description | +|-----------|-------------| +| `current_temperature` | Current water temperature (T1) | +| `temperature` | Target temperature setpoint | +| `hvac_mode` | Current mode: `heat`, `cool`, `off` | +| `hvac_action` | Current action: `heating`, `cooling`, `idle`, `off` | +| `min_temp` | Minimum setpoint (35°C) | +| `max_temp` | Maximum setpoint (60°C) | +| `target_temp_step` | Temperature step (0.5°C) | + +**Supported Features:** +- `TARGET_TEMPERATURE` + +**HVAC Modes:** +- `heat` - Heating mode +- `cool` - Cooling mode +- `off` - Standby + +### Water Heater Entity + +**Entity ID:** `water_heater.heat_pump_dhw` + +**Attributes:** + +| Attribute | Description | +|-----------|-------------| +| `current_temperature` | Current DHW temperature (T3) | +| `temperature` | Target DHW setpoint | +| `operation_mode` | `on` when DHW active, `off` otherwise | +| `min_temp` | Minimum setpoint (35°C) | +| `max_temp` | Maximum setpoint (60°C) | + +### Sensor Entities + +| Entity ID | Unit | Description | +|-----------|------|-------------| +| `sensor.heat_pump_inlet_setpoint_temperature` | °C | ISP value | +| `sensor.heat_pump_system_setpoint_temperature` | °C | SSP value | +| `sensor.heat_pump_water_temperature_t1` | °C | Inflow temperature | +| `sensor.heat_pump_outflow_temperature_t2` | °C | Outflow temperature | +| `sensor.heat_pump_dhw_temperature_t3` | °C | DHW temperature | +| `sensor.heat_pump_outdoor_temperature_t4` | °C | Outdoor temperature | +| `sensor.heat_pump_water_setpoint` | °C | Water setpoint | +| `sensor.heat_pump_dhw_setpoint` | °C | DHW setpoint | +| `sensor.heat_pump_runtime` | h | Compressor hours | +| `sensor.heat_pump_auxiliary_heater_runtime` | h | Aux heater hours | +| `sensor.heat_pump_software_version` | - | Firmware version | + +### Binary Sensor Entities + +| Entity ID | Device Class | Description | +|-----------|--------------|-------------| +| `binary_sensor.heat_pump_heating` | heat | Heating mode | +| `binary_sensor.heat_pump_cooling` | cold | Cooling mode | +| `binary_sensor.heat_pump_working` | running | Compressor active | +| `binary_sensor.heat_pump_dhw_mode` | running | DHW mode | +| `binary_sensor.heat_pump_water_pump` | running | Pump active | +| `binary_sensor.heat_pump_auxiliary_heater` | heat | Aux heater active | +| `binary_sensor.heat_pump_standby` | power | Standby mode | +| `binary_sensor.heat_pump_disabled_prod` | power | Production disabled | +| `binary_sensor.heat_pump_sce` | power | SCE active | +| `binary_sensor.heat_pump_alarm` | problem | Alarm active | + +--- + +## Internal Data Structure + +The coordinator maintains this internal data structure: + +```python +{ + "software_version": "3.0.49", + "last_update": 1759138628, + "datetime": "29/09/2025 12:37", + + # Temperatures + "inlet_setpoint_temp": 34.3, + "system_setpoint_temp": 47.0, + "water_temp_t1": 32.1, + "water_temp_t2": 32.0, + "dhw_temp_t3": 46.8, + "outdoor_temp_t4": 9.6, + "water_setpoint": 43.0, + "dhw_setpoint": 47.0, + "aux_heater": 0, + + # States + "is_heating": True, + "is_cooling": False, + "is_working": False, + "is_dhw": False, + "is_pump_active": True, + "is_aux_heater": False, + "is_standby": False, + "disabled_prod": False, + "sce": True, + + # Runtimes + "worktime_pdc": 11614, + "worktime_res": 593, + + # Alarms + "has_alarm": False, + "alarm_type": "", + "alarm_label": "" +} +``` + +Access in custom code: +```python +coordinator = hass.data[DOMAIN][entry.entry_id] +temp = coordinator.data.get("water_temp_t1") +``` \ No newline at end of file diff --git a/docs/assets/images/.gitkeep b/docs/assets/images/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/assets/images/README.md b/docs/assets/images/README.md new file mode 100644 index 0000000..7dde1ac --- /dev/null +++ b/docs/assets/images/README.md @@ -0,0 +1,49 @@ +# Image Placeholders + +Add screenshots to this folder. The documentation references the following images: + +## Home Page +- `dashboard-overview.png` - Main dashboard overview screenshot + +## Installation Page +- `file-structure.png` - File explorer showing correct directory structure +- `restart-ha.png` - Home Assistant restart screen +- `search-integration.png` - Integration search dialog +- `add-integration.png` - Add integration confirmation +- `device-overview.png` - Device page showing all entities + +## Configuration Page +- `devtools-network.png` - Browser DevTools Network tab showing API request +- `json-response.png` - Example JSON response in browser +- `config-url.png` - Configuration wizard URL input step +- `config-interval.png` - Configuration wizard interval input step +- `config-confirm.png` - Configuration confirmation screen +- `reconfigure.png` - Integration options/reconfigure screen +- `rename-entity.png` - Entity customization dialog + +## Dashboard Page +- `dashboard-full.png` - Complete dashboard view +- `dashboard-import.png` - Raw configuration editor for importing +- `dashboard-status-buttons.png` - Status button row close-up +- `dashboard-thermostats.png` - Thermostat cards close-up +- `dashboard-history.png` - History graph close-up +- `dashboard-scheduler.png` - Scheduler card (if installed) +- `dashboard-gauge.png` - Example gauge card +- `dashboard-mobile.png` - Mobile view of dashboard + +## Troubleshooting Page +- `troubleshoot-logs.png` - Home Assistant logs showing errors +- `troubleshoot-missing-sensors.png` - Entities showing unavailable +- `troubleshoot-set-temp.png` - Logs when setting temperature + +## Recommended Screenshot Dimensions +- Full page screenshots: 1200x800 px +- Close-up/detail shots: 600x400 px +- Mobile screenshots: 375x667 px (iPhone size) + +## Tips for Good Screenshots +1. Use a clean Home Assistant installation or demo mode +2. Hide personal information (IP addresses, names) +3. Use consistent theme (light or dark) +4. Crop to show relevant areas +5. Add annotations if helpful (arrows, highlights) \ No newline at end of file diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..72307d7 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,124 @@ +--- +layout: default +title: Configuration +nav_order: 3 +--- + +# Configuration + +## Finding Your Heat Pump URL + +The integration requires the URL to your heat pump's status API. The format is typically: + +``` +http:///installedplugin/com.innova.pdc//server/index.php?Action=GetStatus +``` + +### Method 1: Browser Developer Tools + +1. Access your heat pump's web interface in a browser +2. Open browser developer tools (F12) +3. Navigate to the **Network** tab +4. Refresh the page or navigate the heat pump interface +5. Look for requests to `index.php?Action=GetStatus` +6. Copy the full URL + +![Finding URL in DevTools](assets/images/devtools-network.png) +*Use browser developer tools to find the correct API URL* + +### Method 2: Common URL Patterns + +Try these common URL patterns (replace IP with your heat pump's IP): + +``` +http://192.168.1.100/installedplugin/com.innova.pdc/2.0.10/server/index.php?Action=GetStatus +http://192.168.1.100/installedplugin/com.innova.pdc/3.0.49/server/index.php?Action=GetStatus +``` + +### Verify Your URL + +Open the URL in a browser. You should see a JSON response like: + +```json +{ + "success": true, + "sw": { "V": "3.0.49" }, + "RESULT": { + "status": { + "watert1": 32.1, + "watert2": 32.0, + "heating": true, + ... + } + } +} +``` + +![JSON Response](assets/images/json-response.png) +*Expected JSON response when accessing the URL* + +## Configuration Wizard + +### Step 1: Enter URL + +When adding the integration, enter your heat pump URL: + +![Enter URL](assets/images/config-url.png) +*Enter the heat pump status URL* + +### Step 2: Set Update Interval + +Optionally configure the update interval (default: 3 seconds): + +| Setting | Description | Recommended | +|---------|-------------|-------------| +| 1-2 seconds | Very frequent updates | High network load | +| 3 seconds | Default, good balance | Recommended | +| 5-10 seconds | Less frequent | Low network load | + +![Update Interval](assets/images/config-interval.png) +*Configure the polling interval* + +### Step 3: Confirm Configuration + +Review and confirm your settings: + +![Confirm Config](assets/images/config-confirm.png) +*Review configuration before completing setup* + +## Configuration Options + +After initial setup, you can modify options: + +1. Go to **Settings** > **Devices & Services** +2. Find "Heat Pump Monitor" +3. Click **Configure** + +![Reconfigure](assets/images/reconfigure.png) +*Access configuration options after setup* + +## Entity Customization + +After setup, you may want to customize entities: + +### Rename Entities + +1. Go to **Settings** > **Devices & Services** +2. Click on the Heat Pump device +3. Click on an entity +4. Change the name as desired + +![Rename Entity](assets/images/rename-entity.png) +*Customize entity names* + +### Hide Unused Entities + +If some sensors don't apply to your setup: + +1. Click on the entity +2. Toggle "Enable" off + +## Next Steps + +- [Set up the dashboard](dashboard.md) +- [Troubleshoot issues](troubleshooting.md) \ No newline at end of file diff --git a/docs/dashboard.md b/docs/dashboard.md new file mode 100644 index 0000000..ea5f2ec --- /dev/null +++ b/docs/dashboard.md @@ -0,0 +1,187 @@ +--- +layout: default +title: Dashboard +nav_order: 4 +--- + +# Dashboard Setup + +A pre-configured dashboard is included with the integration to help you get started quickly. + +## Dashboard Overview + +![Dashboard Full View](assets/images/dashboard-full.png) +*Complete dashboard view with all components* + +The dashboard includes: +- Status indicator buttons +- Thermostat cards for temperature control +- History graphs for monitoring +- Scheduler integration (optional) + +## Installing the Dashboard + +### Method 1: Import YAML + +1. Go to **Settings** > **Dashboards** +2. Click **+ Add Dashboard** +3. Choose "New dashboard from scratch" +4. Give it a name (e.g., "Heat Pump") +5. Open the dashboard and click the three dots menu +6. Select **Edit Dashboard** +7. Click the three dots again and select **Raw configuration editor** +8. Paste the contents of `dashboards/dash.yaml` +9. Click **Save** + +![Import Dashboard](assets/images/dashboard-import.png) +*Import dashboard using raw configuration editor* + +### Method 2: Add Cards Manually + +You can also add individual cards to an existing dashboard. + +## Dashboard Components + +### Status Buttons + +![Status Buttons](assets/images/dashboard-status-buttons.png) +*Status indicator buttons* + +The top row shows quick status indicators: + +| Button | Entity | Description | +|--------|--------|-------------| +| Alarm | `binary_sensor.heat_pump_alarm` | Shows alarm status | +| Heating | `binary_sensor.heat_pump_heating` | Heating mode active | +| Cooling | `binary_sensor.heat_pump_cooling` | Cooling mode active | +| SCE | `binary_sensor.heat_pump_sce` | Smart Consumer Electronics | +| Standby | `binary_sensor.heat_pump_standby` | Standby mode | + +### Thermostat Cards + +![Thermostat Cards](assets/images/dashboard-thermostats.png) +*Thermostat cards for temperature control* + +Two thermostat cards provide temperature control: + +#### Water Temperature Thermostat +- Entity: `climate.heat_pump_water_temperature` +- Controls heating/cooling water setpoint +- Shows current water temperature + +#### DHW (Boiler) Thermostat +- Entity: `water_heater.heat_pump_dhw` or `climate.boiler_temperature` +- Controls domestic hot water setpoint +- Shows current DHW temperature + +### History Graph + +![History Graph](assets/images/dashboard-history.png) +*24-hour history graph showing all sensors* + +The history graph tracks: +- All temperature sensors (T1, T2, T3, T4, setpoints) +- Binary status sensors (heating, cooling, pump, DHW) +- Runtime statistics + +Configuration: +```yaml +type: history-graph +hours_to_show: 24 +entities: + - entity: sensor.heat_pump_water_temperature_t1 + - entity: sensor.heat_pump_dhw_temperature_t3 + - entity: sensor.heat_pump_outdoor_temperature_t4 + - entity: binary_sensor.heat_pump_heating + - entity: binary_sensor.heat_pump_working + # ... more entities +``` + +### Scheduler Card (Optional) + +![Scheduler Card](assets/images/dashboard-scheduler.png) +*Scheduler card for automation* + +The scheduler requires the [scheduler-card](https://github.com/nielsfaber/scheduler-card) custom component. + +Install via HACS: +1. Open HACS +2. Search for "scheduler-card" +3. Install and restart + +## Customizing the Dashboard + +### Changing Time Range + +Edit the history graph `hours_to_show` value: + +```yaml +type: history-graph +hours_to_show: 48 # Change from 24 to 48 hours +``` + +### Adding More Sensors + +Add entities to the history graph: + +```yaml +entities: + - entity: sensor.heat_pump_water_temperature_t1 + - entity: sensor.your_additional_sensor # Add new sensors +``` + +### Changing Layout + +Adjust grid columns for different screen sizes: + +```yaml +grid_options: + columns: 12 # Full width + rows: 4 +``` + +## Mobile View + +![Mobile Dashboard](assets/images/dashboard-mobile.png) +*Dashboard optimized for mobile view* + +The dashboard is responsive and works on mobile devices. For better mobile experience, consider: +- Using the sections layout +- Reducing the number of history graph entities +- Using compact card styles + +## Example Cards + +### Simple Temperature Display + +```yaml +type: entities +entities: + - entity: sensor.heat_pump_water_temperature_t1 + name: Inflow Temperature + - entity: sensor.heat_pump_water_temperature_t2 + name: Outflow Temperature + - entity: sensor.heat_pump_outdoor_temperature_t4 + name: Outdoor Temperature +``` + +### Gauge Card + +```yaml +type: gauge +entity: sensor.heat_pump_water_temperature_t1 +min: 20 +max: 60 +severity: + green: 35 + yellow: 45 + red: 55 +``` + +![Gauge Card](assets/images/dashboard-gauge.png) +*Temperature gauge card example* + +## Next Steps + +- [Troubleshoot issues](troubleshooting.md) +- [API Reference](api.md) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..9c85bef --- /dev/null +++ b/docs/index.md @@ -0,0 +1,74 @@ +--- +layout: default +title: Home +nav_order: 1 +--- + +# RDZ PDC Heat Pump Monitor + +A custom Home Assistant integration for monitoring and controlling RDZ PDC heat pumps via their embedded web interface. + +![Heat Pump Dashboard Overview](assets/images/dashboard-overview.png) +*Dashboard overview showing heat pump status and controls* + +## Features + +- **Climate Control** - Thermostat entity for controlling heating/cooling water temperature +- **Water Heater Control** - Dedicated entity for domestic hot water (DHW) temperature control +- **Comprehensive Monitoring** - 12+ sensors for temperatures, setpoints, and runtime statistics +- **Status Indicators** - 10 binary sensors for operational states +- **Local Polling** - Direct communication with heat pump, no cloud dependency +- **Dashboard Included** - Pre-configured Lovelace dashboard YAML + +## Supported Data Points + +### Temperature Sensors + +| Sensor | Description | +|--------|-------------| +| Inlet Setpoint (ISP) | Smart heating setpoint temperature | +| System Setpoint (SSP) | System setpoint temperature | +| Water T1 | Inflow/supply water temperature | +| Water T2 | Outflow/return water temperature | +| DHW T3 | Domestic hot water temperature | +| Outdoor T4 | External/outdoor temperature | +| Water Setpoint | Target heating water temperature | +| DHW Setpoint | Target domestic hot water temperature | + +### Status Sensors + +| Sensor | Description | +|--------|-------------| +| Heating | Heat pump is in heating mode | +| Cooling | Heat pump is in cooling mode | +| Working | Compressor is running | +| DHW Mode | Domestic hot water heating active | +| Water Pump | Circulation pump is active | +| Auxiliary Heater | Backup electric heater running | +| Standby | System in standby mode | +| Alarm | System alarm active | + +### Runtime Statistics + +| Sensor | Description | +|--------|-------------| +| Runtime (PDC) | Total compressor operating hours | +| Auxiliary Heater Runtime | Total backup heater operating hours | + +## Quick Links + +- [Installation Guide](installation.md) +- [Configuration](configuration.md) +- [Dashboard Setup](dashboard.md) +- [Troubleshooting](troubleshooting.md) +- [API Reference](api.md) + +## Requirements + +- Home Assistant 2023.1 or newer +- RDZ PDC heat pump with web interface +- Network access to heat pump from Home Assistant + +## License + +This project is provided as-is for personal use with RDZ PDC heat pumps. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..923046f --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,82 @@ +--- +layout: default +title: Installation +nav_order: 2 +--- + +# Installation + +## Step 1: Download the Integration + +Download or clone this repository to get the integration files. + +```bash +git clone https://github.com/your-username/rdz_innova_heatpump.git +``` + +## Step 2: Copy Integration Files + +Copy the `custom_components/rdz_innova_heatpump` folder to your Home Assistant `custom_components` directory. + +``` +/ +└── custom_components/ + └── rdz_innova_heatpump/ + ├── __init__.py + ├── climate.py + ├── sensor.py + ├── binary_sensor.py + ├── water_heater.py + ├── config_flow.py + ├── manifest.json + └── translations/ + └── en.json +``` + +![File Structure](assets/images/file-structure.png) +*Expected file structure after installation* + +## Step 3: Restart Home Assistant + +After copying the files, restart Home Assistant completely. This is required for Home Assistant to detect the new integration. + +![Restart Home Assistant](assets/images/restart-ha.png) +*Restart Home Assistant from Settings > System* + +## Step 4: Add Integration + +1. Go to **Settings** > **Devices & Services** +2. Click **+ Add Integration** button +3. Search for "RDZ" or "Heat Pump Monitor" + +![Search Integration](assets/images/search-integration.png) +*Search for the integration in the Add Integration dialog* + +4. Select "Heat Pump Monitor" from the results +5. Follow the configuration wizard (see [Configuration](configuration.md)) + +![Add Integration](assets/images/add-integration.png) +*The integration should appear in search results* + +## Step 5: Verify Installation + +After configuration, you should see: +- A new device "Heat Pump" in your devices list +- Multiple entities (sensors, binary sensors, climate, water heater) + +![Device Overview](assets/images/device-overview.png) +*Device overview showing all entities* + +## Next Steps + +- [Configure the integration](configuration.md) +- [Set up the dashboard](dashboard.md) + +## Troubleshooting Installation + +If the integration doesn't appear: + +1. Verify files are in the correct directory +2. Check Home Assistant logs for errors +3. Ensure you restarted Home Assistant completely (not just reload) +4. See [Troubleshooting](troubleshooting.md) for more help \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..d17e786 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,202 @@ +--- +layout: default +title: Troubleshooting +nav_order: 5 +--- + +# Troubleshooting + +## Common Issues + +### Integration Not Appearing + +**Symptoms:** After copying files and restarting, "Heat Pump Monitor" doesn't appear in the integrations list. + +**Solutions:** +1. Verify the folder structure is correct: + ``` + custom_components/ + └── rdz_innova_heatpump/ + ├── __init__.py + ├── manifest.json + └── ... other files + ``` +2. Check file permissions +3. Perform a full restart (not just reload) +4. Check Home Assistant logs for errors + +![Check Logs](assets/images/troubleshoot-logs.png) +*Check Home Assistant logs for error messages* + +### Connection Failed + +**Symptoms:** "Failed to connect" error during setup. + +**Solutions:** +1. Verify the URL is accessible from your HA server: + ```bash + curl http://YOUR_HEAT_PUMP_IP/installedplugin/com.innova.pdc/VERSION/server/index.php?Action=GetStatus + ``` +2. Check network connectivity between HA and heat pump +3. Verify the URL format is correct +4. Check if heat pump web interface is responding + +### Missing Sensors + +**Symptoms:** Some sensors show "Unknown" or "Unavailable". + +**Solutions:** +This is often due to firmware version differences. Different versions have different JSON structures. + +![Missing Sensors](assets/images/troubleshoot-missing-sensors.png) +*Some sensors may show unavailable due to firmware differences* + +## Firmware Version Differences + +### Known Differences + +| Field | v3.0.49+ | v2.3.x | +|-------|----------|--------| +| ISP (Inlet Setpoint) | `"34.3 °C"` (string with unit) | May not exist | +| SSP (System Setpoint) | Present | May not exist | +| alarm.status | `true/false` | May only have `type` field | +| res (aux heater state) | Present | May not exist | +| sce | Present | May not exist | + +### Checking Your Firmware Version + +1. Access your heat pump URL in a browser +2. Look for the `sw.V` field in the response: + ```json + { + "sw": { "V": "3.0.49" }, + ... + } + ``` + +### Adapting for Different Firmware + +If your firmware has different field names, you may need to modify `__init__.py`. + +**Key mappings (line ~122-158):** + +```python +"inlet_setpoint_temp": float(status.get("ISP", "0").split()[0]), +"system_setpoint_temp": status.get("SSP"), +"water_temp_t1": status.get("watert1"), +"water_temp_t2": status.get("watert2"), +"dhw_temp_t3": status.get("dhwt3"), +"outdoor_temp_t4": status.get("t4"), +"water_setpoint": status.get("watersetpoint"), +"dhw_setpoint": status.get("dhwsetpoint"), +"is_heating": status.get("heating", False), +"is_working": status.get("pwr", False), +"is_cooling": status.get("cooling", False), +"is_dhw": status.get("san", False), +"is_pump_active": status.get("pump", False), +"is_aux_heater": status.get("res", False), +"is_standby": status.get("standby", False), +``` + +**To find correct field names:** +1. Save your heat pump's JSON response to a file +2. Compare with the sample files in `jsons/` folder +3. Adjust the field names in `__init__.py` accordingly + +## Temperature Reading Issues + +### Incorrect Values + +**Symptoms:** Temperature shows wrong values (e.g., 0 or very high numbers). + +**Solutions:** +1. Check the JSON response format for temperature fields +2. Some fields may be strings with units (e.g., `"34.3 °C"`) that need parsing +3. Verify field names match your firmware version + +### ISP Field Parsing Error + +The ISP field often contains a string with unit: `"34.3 °C"` + +The code parses this with: +```python +float(status.get("ISP", "0").split()[0]) +``` + +If your firmware returns a different format, adjust accordingly. + +## Setting Temperature Issues + +### Set Temperature Not Working + +**Symptoms:** Changing temperature in thermostat card doesn't affect heat pump. + +**Solutions:** +1. Check Home Assistant logs for errors +2. Verify the SetParameter endpoint is correct +3. Test manually: + ```bash + curl -X POST "http://YOUR_IP/installedplugin/com.innova.pdc/VERSION/server/index.php?Action=SetParameter" \ + -d "Key=watersetpoint&Value=45&manual=forever" + ``` + +![Set Temperature Logs](assets/images/troubleshoot-set-temp.png) +*Check logs when setting temperature fails* + +## Debug Logging + +Enable debug logging for more information: + +Add to `configuration.yaml`: +```yaml +logger: + default: info + logs: + custom_components.rdz_innova_heatpump: debug +``` + +Then restart Home Assistant and check logs. + +## Sample JSON Files + +The repository includes sample JSON responses for reference: + +| File | Firmware | Description | +|------|----------|-------------| +| `jsons/og.json` | v3.0.49 | Full feature set | +| `jsons/bogdan.json` | v2.3.2 | Reduced features | + +Compare your heat pump's response with these files to identify differences. + +## Getting Help + +### Gathering Information + +When reporting issues, include: +1. Home Assistant version +2. Heat pump firmware version (from JSON `sw.V` field) +3. Full JSON response from your heat pump (sanitize IP if needed) +4. Relevant log entries +5. Steps to reproduce + +### Sharing Your JSON + +If you have a different firmware version, consider sharing your JSON response to help improve compatibility: + +1. Save your JSON response +2. Remove any sensitive information +3. Submit as an issue or pull request + +## FAQ + +**Q: How often does the integration poll the heat pump?** +A: Default is every 3 seconds. Configurable during setup or in options. + +**Q: Can I use this with other heat pump brands?** +A: This integration is designed for RDZ PDC heat pumps with Innova web interface. Other brands may have different APIs. + +**Q: Does this work without internet?** +A: Yes, this is a local polling integration. No cloud services required. + +**Q: Why are some fields missing in my version?** +A: Different firmware versions expose different data. Older versions may lack some sensors. \ No newline at end of file