feat(diagnostics): dump raw redacted REST + MQTT payloads

Diagnostics previously serialized only a curated 6-field subset of parsed
state, omitting sensor_temperature/humidity — so a #83 thermometer dump
couldn't show whether readings were arriving. Now each device carries:
- state: the FULL parsed GoveeDeviceState (dataclasses.asdict)
- raw_api_state: the verbatim /device/state payload it parsed from
- last_mqtt_message: the verbatim AWS IoT push it last received
plus top-level raw_api_devices (verbatim device-list response) and an MQTT
tracked_devices count.

Capture points: GoveeApiClient retains last_raw_devices + last_raw_state;
GoveeAwsIotClient retains last_messages per device. Exposed via
coordinator.api_client.

Redaction widened: 'device'/'deviceName' added to TO_REDACT so the MAC and
user-chosen name inside raw payloads are scrubbed; whole tree is run through
async_redact_data before MAC-key anonymization. New test asserts raw
captures are present AND MAC-free.

Bump version to 2026.5.12.

Author: Tom Lasswell

custom_components/govee/api/client.py

@@ -93,6 +93,13 @@ def __init__(
         self.rate_limit_total: int = 100
         self.rate_limit_reset: int = 0
 
+        # Last raw API responses, retained for diagnostics (redacted at dump
+        # time). Lets a diagnostics download include exactly what the device
+        # list and /device/state endpoints returned — essential for debugging
+        # state-shape issues the parsed model hides (e.g. thermometers, #83).
+        self._last_raw_devices: list[dict[str, Any]] | None = None
+        self._last_raw_state: dict[str, dict[str, Any]] = {}
+
     async def __aenter__(self) -> GoveeApiClient:
         """Async context manager entry."""
         await self._ensure_client()
@@ -267,6 +274,7 @@ async def get_devices(self) -> list[GoveeDevice]:
                             err,
                         )
 
+                self._last_raw_devices = data.get("data", [])
                 _LOGGER.debug("Fetched %d devices from Govee API", len(devices))
                 return devices
 
@@ -313,11 +321,22 @@ async def get_device_state(
                 payload_data = data.get("payload", {})
                 state.update_from_api(payload_data)
 
+                self._last_raw_state[device_id] = payload_data
                 return state
 
         except aiohttp.ClientError as err:
             raise GoveeConnectionError(f"Connection error: {err}") from err
 
+    @property
+    def last_raw_devices(self) -> list[dict[str, Any]] | None:
+        """Raw device-list payload from the most recent get_devices() call."""
+        return self._last_raw_devices
+
+    @property
+    def last_raw_state(self) -> dict[str, dict[str, Any]]:
+        """Raw /device/state payloads keyed by device_id (latest per device)."""
+        return self._last_raw_state
+
     async def control_device(
         self,
         device_id: str,

custom_components/govee/api/mqtt.py

@@ -119,6 +119,14 @@ def __init__(
         self._temp_dir: tempfile.TemporaryDirectory[str] | None = None
         self._max_backoff_count = 0
         self._client: Any | None = None  # aiomqtt.Client when connected
+        # Last raw state payload seen per device, retained for diagnostics so a
+        # dump shows exactly what AWS IoT pushed (redacted at dump time).
+        self._last_messages: dict[str, dict[str, Any]] = {}
+
+    @property
+    def last_messages(self) -> dict[str, dict[str, Any]]:
+        """Most recent raw MQTT state payload per device_id (diagnostics)."""
+        return self._last_messages
 
     @property
     def connected(self) -> bool:
@@ -402,6 +410,8 @@ async def _handle_message(self, message: Any) -> None:
                 state.get("brightness"),
             )
 
+            self._last_messages[device_id] = state
+
             # Invoke callback with device ID and state dict
             try:
                 self._on_state_update(device_id, state)

custom_components/govee/coordinator.py

@@ -243,6 +243,11 @@ def mqtt_client(self) -> GoveeAwsIotClient | None:
         """Return MQTT client instance."""
         return self._mqtt_client
 
+    @property
+    def api_client(self) -> GoveeApiClient:
+        """Return the REST API client (diagnostics reads its raw captures)."""
+        return self._api_client
+
     @property
     def scene_cache_count(self) -> int:
         """Return number of devices with cached scenes."""

custom_components/govee/diagnostics.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 import hashlib
 import re
 from typing import Any
@@ -16,7 +17,9 @@
 from .const import CONF_API_KEY, CONF_EMAIL, CONF_PASSWORD
 from .coordinator import GoveeCoordinator
 
-# Keys to redact from diagnostic output
+# Keys to redact from diagnostic output. Includes the raw-response identity
+# fields ("device" = MAC in /device/state + device-list, "deviceName" = the
+# user's chosen name) so the captured raw API/MQTT payloads stay PII-free.
 TO_REDACT = {
     CONF_API_KEY,
     CONF_EMAIL,
@@ -29,9 +32,29 @@
     "client_id",
     "account_topic",
     "device_id",
+    "device",
+    "deviceName",
     "mac",
 }
 
+
+def _serialize_state(state: Any) -> dict[str, Any] | None:
+    """Full dump of a GoveeDeviceState (all fields, incl. sensor readings).
+
+    Never raises — diagnostics must always produce output.
+    """
+    if state is None:
+        return None
+    try:
+        return dataclasses.asdict(state)
+    except Exception:  # pragma: no cover - defensive
+        return {
+            "online": getattr(state, "online", None),
+            "power_state": getattr(state, "power_state", None),
+            "source": getattr(state, "source", None),
+        }
+
+
 # Govee device IDs are MAC-derived: 8 colon-separated hex octets
 # (e.g., "03:9C:DC:06:75:4B:10:7C"). Group device IDs are numeric-only.
 _MAC_PATTERN = re.compile(r"^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5,7}$")
@@ -62,7 +85,16 @@ async def async_get_config_entry_diagnostics(
     """Return diagnostics for a config entry."""
     coordinator: GoveeCoordinator = entry.runtime_data
 
-    # Collect device information
+    mqtt_client = coordinator.mqtt_client
+    raw_state = coordinator.api_client.last_raw_state
+    raw_mqtt = mqtt_client.last_messages if mqtt_client else {}
+
+    # Collect device information. Each device carries:
+    #  - parsed state (ALL fields, including sensor_temperature/humidity)
+    #  - raw_api_state: the verbatim /device/state payload it was parsed from
+    #  - last_mqtt_message: the verbatim AWS IoT push it last received
+    # These let us debug state-shape issues (e.g. thermometers #83) directly
+    # from a diagnostics download instead of asking for a debug log.
     devices_info: dict[str, Any] = {}
     for device_id, device in coordinator.devices.items():
         state = coordinator.get_state(device_id)
@@ -79,14 +111,9 @@ async def async_get_config_entry_diagnostics(
                 }
                 for cap in device.capabilities
             ],
-            "state": {
-                "online": state.online if state else None,
-                "power_state": state.power_state if state else None,
-                "brightness": state.brightness if state else None,
-                "color": state.color.as_tuple if state and state.color else None,
-                "color_temp_kelvin": state.color_temp_kelvin if state else None,
-                "source": state.source if state else None,
-            },
+            "state": _serialize_state(state),
+            "raw_api_state": raw_state.get(device_id),
+            "last_mqtt_message": raw_mqtt.get(device_id),
             "transport": {
                 "cloud_api": True,
                 "mqtt": coordinator.mqtt_connected,
@@ -95,12 +122,12 @@ async def async_get_config_entry_diagnostics(
         }
 
     # Collect MQTT status
-    mqtt_client = coordinator.mqtt_client
     mqtt_info = None
     if mqtt_client:
         mqtt_info = {
             "available": mqtt_client.available,
             "connected": mqtt_client.connected,
+            "tracked_devices": len(raw_mqtt),
         }
 
     # Collect API client info
@@ -110,20 +137,25 @@ async def async_get_config_entry_diagnostics(
         "rate_limit_reset": coordinator.api_rate_limit_reset,
     }
 
-    # Build diagnostics data — anonymize MAC-format device-id keys before
-    # exposing the device map (MAC = PII per HA diagnostics guidance).
     diagnostics_data = {
         "config_entry": {
             "entry_id": entry.entry_id,
             "version": entry.version,
-            "data": async_redact_data(dict(entry.data), TO_REDACT),
+            "data": dict(entry.data),
             "options": dict(entry.options),
         },
-        "devices": _anonymize_device_keys(devices_info),
+        "devices": devices_info,
+        # Verbatim device-list response from the most recent discovery poll.
+        "raw_api_devices": coordinator.api_client.last_raw_devices,
         "device_count": len(coordinator.devices),
         "mqtt": mqtt_info,
         "api": api_info,
         "scene_cache_count": coordinator.scene_cache_count,
     }
 
-    return diagnostics_data
+    # Redact known-sensitive keys anywhere in the tree (covers the raw API/MQTT
+    # payloads' "device"/"deviceName" fields), then hash the MAC-format device
+    # map keys (MAC = PII per HA diagnostics guidance).
+    redacted: dict[str, Any] = async_redact_data(diagnostics_data, TO_REDACT)
+    redacted["devices"] = _anonymize_device_keys(redacted["devices"])
+    return redacted

custom_components/govee/manifest.json

@@ -24,5 +24,5 @@
     "bleak-retry-connector>=3.0.0",
     "cryptography>=41.0.0"
   ],
-  "version": "2026.5.11"
+  "version": "2026.5.12"
 }

tests/test_diagnostics.py

@@ -15,6 +15,7 @@
     _looks_like_mac,
     async_get_config_entry_diagnostics,
 )
+from custom_components.govee.models import GoveeDeviceState
 
 # Govee device-id MAC pattern: 6-8 colon-separated hex octets
 _MAC_RE = re.compile(r"\b[0-9A-Fa-f]{2}(?::[0-9A-Fa-f]{2}){5,7}\b")
@@ -113,20 +114,43 @@ async def test_no_mac_in_diagnostics_output(self) -> None:
         device_group.is_group = True
         device_group.capabilities = []
 
-        state_mock = MagicMock()
-        state_mock.online = True
-        state_mock.power_state = True
-        state_mock.brightness = 80
-        state_mock.color = None
-        state_mock.color_temp_kelvin = 4000
-        state_mock.source = "cloud_api"
+        # Real state object so the full asdict dump path runs (incl. the
+        # device_id MAC field, which must be redacted).
+        state = GoveeDeviceState.create_empty(mac_id)
+        state.sensor_temperature = 23.4
+        state.sensor_humidity = 48.0
+
+        # Realistic raw API/MQTT captures whose "device"/"deviceName" carry the
+        # MAC + user name — must be redacted out of the dump.
+        raw_state_payload = {
+            "device": mac_id,
+            "sku": "H6601",
+            "capabilities": [
+                {
+                    "type": "devices.capabilities.property",
+                    "instance": "sensorTemperature",
+                    "state": {"value": 23.4},
+                }
+            ],
+        }
+        api_client = MagicMock()
+        api_client.last_raw_state = {mac_id: raw_state_payload}
+        api_client.last_raw_devices = [
+            {"device": mac_id, "sku": "H6601", "deviceName": "Living Room Lamp"}
+        ]
+
+        mqtt_client = MagicMock()
+        mqtt_client.available = True
+        mqtt_client.connected = True
+        mqtt_client.last_messages = {mac_id: {"onOff": 1, "sensorTemperature": 2340}}
 
         coordinator = MagicMock()
         coordinator.devices = {mac_id: device_mac, group_id: device_group}
-        coordinator.get_state = lambda _did: state_mock
+        coordinator.get_state = lambda did: state if did == mac_id else None
         coordinator.mqtt_connected = True
         coordinator.is_ble_available = lambda _did: False
-        coordinator.mqtt_client = None
+        coordinator.mqtt_client = mqtt_client
+        coordinator.api_client = api_client
         coordinator.api_rate_limit_remaining = 100
         coordinator.api_rate_limit_total = 100
         coordinator.api_rate_limit_reset = 0
@@ -158,3 +182,72 @@ async def test_no_mac_in_diagnostics_output(self) -> None:
         # API key and email must also be redacted.
         assert "secret" not in rendered
         assert "user@example.com" not in rendered
+
+    @pytest.mark.asyncio
+    async def test_raw_captures_present_and_redacted(self) -> None:
+        """Raw API/MQTT payloads are included for debugging but redacted.
+
+        The full parsed state (incl. sensor readings) and the verbatim
+        /device/state + MQTT payloads must appear, while the MAC inside their
+        "device" field is redacted.
+        """
+        mac_id = "03:9C:DC:06:75:4B:10:7C"
+
+        device = MagicMock()
+        device.sku = "H5075"
+        device.name = "Office Thermo"
+        device.device_type = "devices.types.thermometer"
+        device.is_group = False
+        device.capabilities = []
+
+        state = GoveeDeviceState.create_empty(mac_id)
+        state.sensor_temperature = 23.4
+        state.sensor_humidity = 48.0
+
+        api_client = MagicMock()
+        api_client.last_raw_state = {
+            mac_id: {"device": mac_id, "sku": "H5075", "capabilities": []}
+        }
+        api_client.last_raw_devices = [{"device": mac_id, "sku": "H5075"}]
+
+        mqtt_client = MagicMock()
+        mqtt_client.available = True
+        mqtt_client.connected = True
+        mqtt_client.last_messages = {mac_id: {"onOff": 1}}
+
+        coordinator = MagicMock()
+        coordinator.devices = {mac_id: device}
+        coordinator.get_state = lambda _did: state
+        coordinator.mqtt_connected = True
+        coordinator.is_ble_available = lambda _did: False
+        coordinator.mqtt_client = mqtt_client
+        coordinator.api_client = api_client
+        coordinator.api_rate_limit_remaining = 100
+        coordinator.api_rate_limit_total = 100
+        coordinator.api_rate_limit_reset = 0
+        coordinator.scene_cache_count = 0
+
+        entry = MagicMock()
+        entry.entry_id = "e"
+        entry.version = 1
+        entry.data = {}
+        entry.options = {}
+        entry.runtime_data = coordinator
+
+        out = await async_get_config_entry_diagnostics(MagicMock(), entry)
+
+        dev = next(iter(out["devices"].values()))
+        # Full parsed state carries the sensor readings (the #83 debug signal).
+        assert dev["state"]["sensor_temperature"] == 23.4
+        assert dev["state"]["sensor_humidity"] == 48.0
+        # Raw captures are attached per-device + the device-list at top level.
+        assert dev["raw_api_state"] is not None
+        assert dev["last_mqtt_message"] == {"onOff": 1}
+        assert out["raw_api_devices"] is not None
+        assert out["mqtt"]["tracked_devices"] == 1
+
+        # But the MAC in the raw payloads' "device" field is redacted, and the
+        # parsed-state device_id MAC is gone too.
+        rendered = json.dumps(out, default=str)
+        assert mac_id not in rendered
+        assert _MAC_RE.search(rendered) is None