adding documentations and json from bogdan

2026-01-16 15:09:36 +02:00
parent 0247d01c1f
commit 4b6b3b3822
6 changed files with 939 additions and 21 deletions
@@ -1,29 +1,214 @@
-# README #
+# RDZ PDC Heat Pump Monitor - Home Assistant Integration

-This README would normally document whatever steps are necessary to get your application up and running.
+A custom Home Assistant integration for monitoring and controlling RDZ PDC heat pumps via their embedded web interface.

-### What is this repository for? ###
+## Features

-* Quick summary
-* Version
-* [Learn Markdown](https://bitbucket.org/tutorials/markdowndemo)
+- **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 (heating, cooling, pump, alarms, etc.)
+- **Local Polling**: Direct communication with heat pump - no cloud dependency
+- **Dashboard Included**: Pre-configured Lovelace dashboard YAML

-### How do I get set up? ###
+## Supported Data Points

-* Summary of set up
-* Configuration
-* Dependencies
-* Database configuration
-* How to run tests
-* Deployment instructions
+### 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 |

-### Contribution guidelines ###
+### Binary 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 |

-* Writing tests
-* Code review
-* Other guidelines
+### Runtime Statistics
+| Sensor | Description |
+|--------|-------------|
+| Runtime (PDC) | Total compressor operating hours |
+| Auxiliary Heater Runtime | Total backup heater operating hours |

-### Who do I talk to? ###
+## Installation

-* Repo owner or admin
-* Other community or team contact
+### Step 1: Copy Integration Files
+
+Copy the `custom_components/ha_rdz_pdc_config` folder to your Home Assistant `custom_components` directory:
+
+```
+<config_directory>/
+└── custom_components/
+    └── ha_rdz_pdc_config/
+        ├── __init__.py
+        ├── climate.py
+        ├── sensor.py
+        ├── binary_sensor.py
+        ├── water_heater.py
+        ├── config_flow.py
+        ├── manifest.json
+        └── translations/
+            └── en.json
+```
+
+### Step 2: Restart Home Assistant
+
+After copying the files, restart Home Assistant completely.
+
+### Step 3: Add Integration
+
+1. Go to **Settings** → **Devices & Services**
+2. Click **+ Add Integration**
+3. Search for "RDZ" or "Heat Pump Monitor"
+4. Follow the configuration wizard
+
+### Step 4: Configure URL
+
+When prompted, enter your heat pump's status URL. The format is typically:
+
+```
+http://<HEAT_PUMP_IP>/installedplugin/com.innova.pdc/<VERSION>/server/index.php?Action=GetStatus
+```
+
+**Example:**
+```
+http://192.168.11.101/installedplugin/com.innova.pdc/2.0.10/server/index.php?Action=GetStatus
+```
+
+**To find your URL:**
+1. Access your heat pump's web interface in a browser
+2. Open browser developer tools (F12)
+3. Navigate to the Network tab
+4. Look for requests to `index.php?Action=GetStatus`
+5. Copy the full URL
+
+**Verify your URL works** by opening it in a browser - you should see a JSON response like:
+```json
+{
+  "success": true,
+  "sw": { "V": "3.0.49" },
+  "RESULT": {
+    "status": { ... }
+  }
+}
+```
+
+## Troubleshooting
+
+### JSON Field Mapping Issues
+
+Different firmware versions may have different JSON structures. If you encounter issues, you may need to modify the field mappings in `__init__.py`.
+
+**Known differences between firmware versions:**
+
+| 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) | Present | May not exist |
+| sce | Present | May not exist |
+
+**Key mappings to verify in `__init__.py`:**
+
+```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),
+```
+
+### Common Issues
+
+1. **Integration not appearing**: Ensure files are in the correct directory and restart HA completely
+2. **Connection failed**: Verify the URL is accessible from your HA server
+3. **Missing sensors**: Check if your firmware version supports all fields
+4. **Temperature readings incorrect**: Verify JSON field names match your heat pump's response
+
+## Dashboard
+
+A pre-configured dashboard is included in `dashboards/dash.yaml`. To use it:
+
+1. Copy the YAML content
+2. Go to **Settings** → **Dashboards**
+3. Create a new dashboard or edit existing
+4. Use the raw configuration editor to paste the YAML
+
+The dashboard includes:
+- Status buttons (Alarm, Heating, Cooling, SCE, Standby)
+- Thermostat cards for water and DHW control
+- 24-hour history graph
+- Scheduler integration (requires [scheduler-card](https://github.com/nielsfaber/scheduler-card))
+
+## Services
+
+### `ha_rdz_pdc_config.set_water_setpoint`
+
+Manually set the heating water setpoint temperature.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| temperature | float | Yes | Target temperature (35-60°C) |
+| duration | string | No | Duration: "forever" or time-based |
+
+**Example:**
+```yaml
+service: ha_rdz_pdc_config.set_water_setpoint
+data:
+  temperature: 45
+  duration: forever
+```
+
+## API Reference
+
+### Data Fetching
+- **Endpoint**: Configurable URL (typically `index.php?Action=GetStatus`)
+- **Method**: GET
+- **Update Interval**: Configurable (default: 3 seconds)
+
+### Parameter Setting
+- **Endpoint**: `<base_url>/index.php?Action=SetParameter`
+- **Method**: POST (form-urlencoded)
+- **Parameters**:
+  - `Key`: "watersetpoint" or "dhwsetpoint"
+  - `Value`: Temperature as string
+  - `manual`: Duration ("forever" or time limit)
+
+## Technical Details
+
+- **Domain**: `ha_rdz_pdc_config`
+- **IoT Class**: Local Polling
+- **Platforms**: sensor, binary_sensor, climate, water_heater
+- **Configuration**: UI-based (config_flow)
+
+## Contributing
+
+Contributions are welcome! If you have a different firmware version or heat pump model, please share your JSON response structure to help improve compatibility.
+
+## License
+
+This project is provided as-is for personal use with RDZ PDC heat pumps.