diff --git a/.github/ISSUE_TEMPLATE/issue.md b/.github/ISSUE_TEMPLATE/issue.md index eb6caf7..e46cea2 100644 --- a/.github/ISSUE_TEMPLATE/issue.md +++ b/.github/ISSUE_TEMPLATE/issue.md @@ -6,11 +6,9 @@ about: Create a report to help us improve ## Hardware and versions diff --git a/README.md b/README.md index e0d4398..186f317 100644 --- a/README.md +++ b/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 diff --git a/custom_components/givenergy_local/coordinator.py b/custom_components/givenergy_local/coordinator.py index 48540f8..7967a24 100644 --- a/custom_components/givenergy_local/coordinator.py +++ b/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: diff --git a/custom_components/givenergy_local/givenergy_modbus/exceptions.py b/custom_components/givenergy_local/givenergy_modbus/exceptions.py index 8d31e29..a35960b 100644 --- a/custom_components/givenergy_local/givenergy_modbus/exceptions.py +++ b/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 diff --git a/custom_components/givenergy_local/givenergy_modbus/model/register.py b/custom_components/givenergy_local/givenergy_modbus/model/register.py index 8b64364..a841ff0 100644 --- a/custom_components/givenergy_local/givenergy_modbus/model/register.py +++ b/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]]: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..7e42449 --- /dev/null +++ b/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.