|
| 1 | +"""Diagnostics support for Growatt Modbus. |
| 2 | +
|
| 3 | +Surfaces a one-click state dump from the integration and device pages, so the |
| 4 | +questions that dominate issue triage — which profile is selected, which version is |
| 5 | +running, what the options are, whether the coordinator thinks it is online — can be |
| 6 | +answered without a round trip. |
| 7 | +
|
| 8 | +This is deliberately NOT a replacement for the Universal Register Scanner service. |
| 9 | +The two answer different questions: |
| 10 | +
|
| 11 | + diagnostics (here) What is the integration's current state? |
| 12 | + Works even when every read is failing, which is exactly when |
| 13 | + it is needed. Cannot see registers the profile does not define. |
| 14 | +
|
| 15 | + register scanner What does the hardware actually respond to? |
| 16 | + Probes ranges outside the selected profile, offers decode |
| 17 | + candidates per register, and reports per-register error text. |
| 18 | + That is how 31059 (total PV power) and the TL-XH2 VPP-only |
| 19 | + layout were found — neither is visible to diagnostics. |
| 20 | +
|
| 21 | +Ask for diagnostics first; ask for a scan when register discovery is needed. |
| 22 | +""" |
| 23 | +from __future__ import annotations |
| 24 | + |
| 25 | +from dataclasses import asdict, is_dataclass |
| 26 | +from typing import Any |
| 27 | + |
| 28 | +from homeassistant.components.diagnostics import async_redact_data |
| 29 | +from homeassistant.config_entries import ConfigEntry |
| 30 | +from homeassistant.core import HomeAssistant |
| 31 | + |
| 32 | +from .const import DOMAIN |
| 33 | + |
| 34 | +# Host/device path can identify a network or a person's hardware layout, and the |
| 35 | +# serial number identifies the unit itself. Users routinely paste diagnostics into |
| 36 | +# public issues, so redact by default rather than relying on them to remember. |
| 37 | +TO_REDACT = { |
| 38 | + "host", |
| 39 | + "device_path", |
| 40 | + "serial_number", |
| 41 | + "unique_id", |
| 42 | +} |
| 43 | + |
| 44 | + |
| 45 | +def _safe(value: Any) -> Any: |
| 46 | + """Coerce a value into something JSON-serialisable. |
| 47 | +
|
| 48 | + Diagnostics must never raise — a dump that fails is worse than one with a gap, |
| 49 | + because it fails precisely when the integration is already misbehaving. |
| 50 | + """ |
| 51 | + if value is None or isinstance(value, (bool, int, float, str)): |
| 52 | + return value |
| 53 | + if isinstance(value, dict): |
| 54 | + return {str(k): _safe(v) for k, v in value.items()} |
| 55 | + if isinstance(value, (list, tuple, set)): |
| 56 | + return [_safe(v) for v in value] |
| 57 | + return str(value) |
| 58 | + |
| 59 | + |
| 60 | +async def async_get_config_entry_diagnostics( |
| 61 | + hass: HomeAssistant, entry: ConfigEntry |
| 62 | +) -> dict[str, Any]: |
| 63 | + """Return diagnostics for a config entry.""" |
| 64 | + coordinator = hass.data.get(DOMAIN, {}).get(entry.entry_id) |
| 65 | + |
| 66 | + diagnostics: dict[str, Any] = { |
| 67 | + "entry": { |
| 68 | + "title": entry.title, |
| 69 | + "version": entry.version, |
| 70 | + "source": entry.source, |
| 71 | + "state": str(entry.state), |
| 72 | + "data": _safe(dict(entry.data)), |
| 73 | + "options": _safe(dict(entry.options)), |
| 74 | + }, |
| 75 | + } |
| 76 | + |
| 77 | + if coordinator is None: |
| 78 | + # Entry not loaded — still worth returning what we have. This is a state a |
| 79 | + # user can genuinely be in (failed setup, disabled entry) and the entry data |
| 80 | + # alone answers "which profile" and "what options". |
| 81 | + diagnostics["coordinator"] = None |
| 82 | + diagnostics["note"] = ( |
| 83 | + "Coordinator not loaded — the entry may be disabled, or setup may have " |
| 84 | + "failed. Entry data and options above are still accurate." |
| 85 | + ) |
| 86 | + return async_redact_data(diagnostics, TO_REDACT) |
| 87 | + |
| 88 | + client = getattr(coordinator, "_client", None) |
| 89 | + hub = getattr(coordinator, "_hub", None) |
| 90 | + |
| 91 | + diagnostics["coordinator"] = { |
| 92 | + # Health — the first thing to look at when someone reports "unavailable" |
| 93 | + # or "stuck at zero". |
| 94 | + "inverter_online": getattr(coordinator, "_inverter_online", None), |
| 95 | + "ever_had_real_data": getattr(coordinator, "_ever_had_real_data", None), |
| 96 | + "last_update_success": getattr(coordinator, "last_update_success", None), |
| 97 | + "consecutive_failures": getattr(coordinator, "_consecutive_failures", None), |
| 98 | + "failure_threshold": getattr(coordinator, "_failure_threshold", None), |
| 99 | + "update_interval": _safe(getattr(coordinator, "update_interval", None)), |
| 100 | + "normal_update_interval": _safe(getattr(coordinator, "_normal_update_interval", None)), |
| 101 | + "offline_update_interval": _safe(getattr(coordinator, "_offline_update_interval", None)), |
| 102 | + "in_slow_poll_mode": ( |
| 103 | + getattr(coordinator, "update_interval", None) |
| 104 | + == getattr(coordinator, "_offline_update_interval", None) |
| 105 | + ), |
| 106 | + # Identity |
| 107 | + "register_map_key": getattr(coordinator, "_register_map_key", None), |
| 108 | + "serial_number": getattr(coordinator, "_serial_number", None), |
| 109 | + "firmware_version": getattr(coordinator, "_firmware_version", None), |
| 110 | + # Energy-guard state — relevant to every "my totals look wrong" report |
| 111 | + "midnight_grace_expires": _safe(getattr(coordinator, "_midnight_grace_expires", None)), |
| 112 | + "retained_daily_totals": _safe(getattr(coordinator, "_retained_daily_totals", None)), |
| 113 | + "retained_lifetime_totals": _safe(getattr(coordinator, "_retained_lifetime_totals", None)), |
| 114 | + "pending_write_checks": _safe(getattr(coordinator, "_pending_write_checks", None)), |
| 115 | + } |
| 116 | + |
| 117 | + if client is not None: |
| 118 | + diagnostics["client"] = { |
| 119 | + "connection_type": getattr(client, "connection_type", None), |
| 120 | + "slave_id": getattr(client, "slave_id", None), |
| 121 | + "backed_off": getattr(client, "_backed_off", None), |
| 122 | + "consecutive_read_failures": getattr(client, "_consecutive_read_failures", None), |
| 123 | + "min_read_interval": getattr(client, "min_read_interval", None), |
| 124 | + "block_size_override": getattr(client, "_block_size_override", None), |
| 125 | + "profile_max_block_size": _safe( |
| 126 | + (getattr(client, "register_map", None) or {}).get("max_block_size") |
| 127 | + ), |
| 128 | + # Ranges suppressed after repeated failure — explains "why is this |
| 129 | + # sensor empty" without needing a scan. |
| 130 | + "failed_optional_ranges": _safe(getattr(client, "_failed_optional_ranges", None)), |
| 131 | + } |
| 132 | + |
| 133 | + if hub is not None: |
| 134 | + diagnostics["shared_connection"] = { |
| 135 | + "active": True, |
| 136 | + "port": getattr(hub, "port", None), |
| 137 | + "refcount": getattr(hub, "_refcount", None), |
| 138 | + "connected": getattr(hub, "_connected", None), |
| 139 | + "recoveries_this_poll": getattr(hub, "_recoveries_this_poll", None), |
| 140 | + "max_recoveries_per_poll": getattr(hub, "_max_recoveries_per_poll", None), |
| 141 | + } |
| 142 | + else: |
| 143 | + diagnostics["shared_connection"] = {"active": False} |
| 144 | + |
| 145 | + # Current decoded values. Shows at a glance which sensor groups are populated |
| 146 | + # and which are flat zero — the signature of a failed or unsupported range. |
| 147 | + data = getattr(coordinator, "data", None) |
| 148 | + if data is not None and is_dataclass(data): |
| 149 | + diagnostics["data"] = _safe(asdict(data)) |
| 150 | + else: |
| 151 | + diagnostics["data"] = None |
| 152 | + |
| 153 | + return async_redact_data(diagnostics, TO_REDACT) |
0 commit comments