Update docs for timeslot errors

.github/ISSUE_TEMPLATE/issue.md

@@ -6,11 +6,9 @@ about: Create a report to help us improve
 
 <!-- Before you open a new issue, search through the existing issues to see if others have had the same problem.
 
-Issues not containing the minimum requirements will be closed:
-
-- Issues without a description (using the header is not good enough) will be closed.
-- Issues without debug logging will be closed.
+There is also a Troubleshooting page linked from the repository README.
 
+Every placeholder in this template must be completed, otherwise your issue may be closed.
 -->
 
 ## Hardware and versions

README.md

@@ -29,6 +29,7 @@ Your Home Assistant instance must be able to establish a TCP connection to your
 
 * [Energy dashboard](docs/energy-dashboard.md)
 * [Inverter controls](docs/controls.md)
+* [Troubleshooting](docs/troubleshooting.md)
 * [Uploading to pvoutput.org](docs/pvoutput.md)
 
 ## Limitations

custom_components/givenergy_local/coordinator.py

@@ -11,7 +11,7 @@
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
 
 from .givenergy_modbus.client.client import Client
-from .givenergy_modbus.exceptions import CommunicationError
+from .givenergy_modbus.exceptions import CommunicationError, ConversionError
 from .givenergy_modbus.model.plant import Plant
 from .givenergy_modbus.pdu.transparent import TransparentRequest
 
@@ -153,8 +153,17 @@ def _is_data_valid(plant: Plant) -> bool:
         try:
             inverter_data = plant.inverter
             _ = plant.batteries
+
+        except ConversionError as err:
+            _LOGGER.warning(
+                "Failed to convert %s from %s: %s",
+                err.key,
+                err.source_registers,
+                err.message,
+            )
+            return False
         except Exception as err:  # pylint: disable=broad-except
-            _LOGGER.warning("Inverter model failed validation: %s", err)
+            _LOGGER.warning("Unexpected register validation error: %s", err)
             return False
 
         for check in _INVERTER_QUALITY_CHECKS:

custom_components/givenergy_local/givenergy_modbus/exceptions.py

@@ -32,3 +32,8 @@ class CommunicationError(ExceptionBase):
 
 class ConversionError(ExceptionBase):
     """Exception to indicate an error converting register values."""
+
+    def __init__(self, key: str, source_registers: list[int], message: str) -> None:
+        super().__init__(message)
+        self.key = key
+        self.source_registers = source_registers

custom_components/givenergy_local/givenergy_modbus/model/register.py

@@ -182,9 +182,7 @@ def get(self, key: str, default: Any = None) -> Any:
                     return r.post_conv(val)
             return val
         except ValueError as err:
-            raise ConversionError(
-                f"Failed to convert {key} from {regs}: {err}"
-            ) from err
+            raise ConversionError(key, regs, str(err)) from err
 
     @classmethod
     def to_fields(cls) -> dict[str, tuple[Any, None]]:

docs/troubleshooting.md

@@ -0,0 +1,38 @@
+# Troubleshooting
+
+## Debugging techniques
+
+### Debug logs
+
+If something isn't right, the first place to start (before raising an issue) is the debug logs.
+
+There are two ways to capture debug logs:
+
+1. Via the UI, see https://www.home-assistant.io/docs/configuration/troubleshooting/#enabling-debug-logging
+2. Via the configuration file, see https://www.home-assistant.io/components/logger/
+
+There will often be clues as to what's going wrong, and these logs are essential to include when raising an issue.
+
+When capturing logs, it's important to include the moment the integration loads, as certain log entries may only be produced once at this point. You can achieve this by reloading the integration via the Home Assistant UI.
+
+### GivEnergy portal
+
+The GivEnergy web portal provides a more detailed view on to inverter configuration, compare to the app which is a fairly simplified view.
+
+To access this:
+
+- Go to https://www.givenergy.cloud/ and log in.
+- Select "My Inverter" from the menu.
+- Find the icon for "Remote Control" in the top-right of the page.
+
+The "Remote Control History" panel is particularly useful, as the "Show Raw Values" checkbox exposes the values get sent to/from the inverter.
+
+## Data issues
+
+Sometimes inverters supply bad data to the integration that can't be understood. This may cause the integration to fail.
+
+### Timeslots with invalid values
+
+If you can't connect at all and your logs mention failure to convert charge/discharge slot values, you may find that these values are not correctly set on the inverter.
+
+To see all available slots, you must log in to the GivEnergy web portal (see above). If any of the start/end times are blank, update these with a value, even if it's just to set the start and end times to the same value.