Preparing for public release

2026-01-19 14:02:06 +02:00
parent 4b6b3b3822
commit 75753494ab
19 changed files with 1040 additions and 17 deletions
@@ -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.