docs(quick-260409-m53): parameter backup button + viewer

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

.planning/STATE.md

@@ -73,9 +73,10 @@ None.
 | # | Description | Date | Commit | Directory |
 |---|-------------|------|--------|-----------|
 | 260409-l1l | Add Options Flow to reconfigure IP address and host settings in HA | 2026-04-09 | da8f155 | [260409-l1l-add-options-flow-to-reconfigure-ip-addre](./quick/260409-l1l-add-options-flow-to-reconfigure-ip-addre/) |
+| 260409-m53 | Add parameter backup button and backup viewer to HA integration | 2026-04-09 | df0995f | [260409-m53-add-parameter-backup-button-and-backup-v](./quick/260409-m53-add-parameter-backup-button-and-backup-v/) |
 
 ## Session Continuity
 
 Last session: 2026-04-09
-Stopped at: Quick task 260409-l1l completed
-Resume file: .planning/quick/260409-l1l-add-options-flow-to-reconfigure-ip-addre/260409-l1l-SUMMARY.md
+Stopped at: Quick task 260409-m53 completed
+Resume file: .planning/quick/260409-m53-add-parameter-backup-button-and-backup-v/260409-m53-SUMMARY.md

.planning/quick/260409-m53-add-parameter-backup-button-and-backup-v/260409-m53-PLAN.md

@@ -0,0 +1,378 @@
+---
+phase: quick
+plan: 260409-m53
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - custom_components/luxtronik2_modbus_proxy/button.py
+  - custom_components/luxtronik2_modbus_proxy/sensor.py
+  - custom_components/luxtronik2_modbus_proxy/__init__.py
+  - custom_components/luxtronik2_modbus_proxy/const.py
+  - custom_components/luxtronik2_modbus_proxy/strings.json
+  - custom_components/luxtronik2_modbus_proxy/translations/en.json
+  - custom_components/luxtronik2_modbus_proxy/translations/de.json
+autonomous: true
+must_haves:
+  truths:
+    - "A 'Backup Parameters' button entity appears on the device page under Configuration"
+    - "Pressing the button reads all parameters and saves a timestamped JSON file"
+    - "JSON file is saved to /config/luxtronik2_backups/ with YYYY-MM-DD_HH-MM-SS.json naming"
+    - "A persistent_notification fires after backup with summary (count, filename, timestamp)"
+    - "A sensor entity shows the last backup timestamp and filename"
+  artifacts:
+    - path: "custom_components/luxtronik2_modbus_proxy/button.py"
+      provides: "Button entity + backup logic"
+    - path: "custom_components/luxtronik2_modbus_proxy/sensor.py"
+      provides: "Last backup sensor entity (added to existing sensor platform)"
+    - path: "custom_components/luxtronik2_modbus_proxy/__init__.py"
+      provides: "button platform registration in PLATFORMS"
+  key_links:
+    - from: "button.py"
+      to: "coordinator"
+      via: "coordinator._sync_read pattern to get full parameter data with names/types"
+    - from: "button.py"
+      to: "hass.components.persistent_notification"
+      via: "async_create after backup"
+    - from: "button.py"
+      to: "sensor.py last_backup sensor"
+      via: "hass.data storage of last backup metadata"
+---
+
+<objective>
+Add a "Backup Parameters" button entity that reads all 1,126 parameters from the
+Luxtronik controller and saves them as a timestamped JSON file, plus a sensor showing
+the last backup timestamp.
+
+Purpose: Allow users to create a snapshot of all heat pump parameters before making
+configuration changes, providing a safety net for experimentation.
+
+Output: button.py (new), updated sensor.py, updated __init__.py, updated translations.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@custom_components/luxtronik2_modbus_proxy/__init__.py
+@custom_components/luxtronik2_modbus_proxy/coordinator.py
+@custom_components/luxtronik2_modbus_proxy/const.py
+@custom_components/luxtronik2_modbus_proxy/sensor.py
+@custom_components/luxtronik2_modbus_proxy/strings.json
+@custom_components/luxtronik2_modbus_proxy/translations/en.json
+@custom_components/luxtronik2_modbus_proxy/translations/de.json
+
+<interfaces>
+<!-- Key types and contracts from existing codebase -->
+
+From coordinator.py:
+```python
+class LuxtronikCoordinator(DataUpdateCoordinator[dict]):
+    _host: str
+    _port: int
+    _lock: asyncio.Lock
+    # coordinator.data = {"parameters": dict[int, int], "calculations": dict[int, int]}
+```
+
+From const.py:
+```python
+DOMAIN = "luxtronik2_modbus_proxy"
+MANUFACTURER = "Alpha Innotec / Novelan"
+MODEL = "Luxtronik 2.0"
+DEFAULT_PORT = 8889
+```
+
+From sensor.py (entity pattern):
+```python
+# DeviceInfo imported from homeassistant.helpers.entity (NOT device_registry)
+from homeassistant.helpers.entity import DeviceInfo
+from homeassistant.helpers.update_coordinator import CoordinatorEntity
+
+# Device info pattern used by all entities:
+DeviceInfo(
+    identifiers={(DOMAIN, self.coordinator.config_entry.entry_id)},
+    name=MODEL, manufacturer=MANUFACTURER, model=MODEL,
+)
+```
+
+From luxtronik library (used directly, NOT proxy register_definitions):
+```python
+import luxtronik
+import luxtronik.parameters as _lp
+# _lp.Parameters().parameters -> dict[int, TypedParam]
+# Each TypedParam has: .name (str), .value, .from_heatpump(raw_int), .to_heatpump(value)
+# type(param_obj).__name__ gives the datatype name (e.g., "Celsius", "HeatingMode")
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create button.py with backup logic, add constants, register platform</name>
+  <files>
+    custom_components/luxtronik2_modbus_proxy/button.py,
+    custom_components/luxtronik2_modbus_proxy/__init__.py,
+    custom_components/luxtronik2_modbus_proxy/const.py
+  </files>
+  <action>
+**const.py** — Add constant:
+```python
+BACKUP_DIR = "luxtronik2_backups"
+```
+
+**__init__.py** — Add `"button"` to the PLATFORMS list (line 29):
+```python
+PLATFORMS: list[str] = ["sensor", "select", "number", "button"]
+```
+
+**button.py** — Create new file implementing the backup button entity.
+
+Structure:
+1. Import `ButtonEntity` from `homeassistant.components.button`.
+2. Import `DeviceInfo` from `homeassistant.helpers.entity` (NOT device_registry).
+3. Import `luxtronik` and `luxtronik.parameters as _lp` for parameter name/type extraction.
+4. Import `json`, `os`, `datetime` from stdlib.
+
+Class `LuxtronikBackupButton(ButtonEntity)`:
+- `_attr_name = "Luxtronik Backup Parameters"`
+- `_attr_icon = "mdi:content-save-all"`
+- `_attr_entity_category = EntityCategory.CONFIG` (appears under Configuration)
+- `_attr_unique_id = f"{entry.entry_id}_backup_parameters"`
+- `device_info` property: same DeviceInfo pattern as sensor.py (identifiers, name, manufacturer, model)
+- Store `coordinator` and `hass` references in `__init__`.
+
+`async_press()` method:
+1. Acquire coordinator._lock (ARCH-03 — serialize with reads/writes).
+2. Inside lock, call `await self.hass.async_add_executor_job(self._sync_backup)`.
+3. After lock release, store backup metadata in `hass.data[DOMAIN][f"{entry_id}_last_backup"]` as dict with `timestamp` (ISO string) and `filename`.
+4. Fire `async_dispatcher_send(hass, f"{DOMAIN}_backup_complete", metadata)` so the sensor updates.
+5. Call `hass.components.persistent_notification.async_create(message, title, notification_id)`:
+   - title: "Luxtronik Parameter Backup Complete"
+   - message: f"Backed up {count} parameters to `{filename}`\nTimestamp: {timestamp}"
+   - notification_id: f"{DOMAIN}_backup"
+
+`_sync_backup()` method (runs in executor, blocking I/O OK):
+1. Create a fresh `luxtronik.Luxtronik` instance using the `__new__` pattern from coordinator._sync_read:
+   ```python
+   lux = luxtronik.Luxtronik.__new__(luxtronik.Luxtronik)
+   lux._host = self._host
+   lux._port = self._port
+   lux._socket = None
+   lux.calculations = luxtronik.Calculations()
+   lux.parameters = luxtronik.Parameters()
+   lux.visibilities = luxtronik.Visibilities()
+   lux.read()
+   ```
+2. Build the JSON structure by iterating `lux.parameters.parameters`:
+   ```python
+   params_dict = {}
+   for idx, param_obj in lux.parameters.parameters.items():
+       if param_obj is None:
+           continue
+       entry = {
+           "name": getattr(param_obj, "name", f"Parameter {idx}"),
+           "type": type(param_obj).__name__,
+       }
+       if hasattr(param_obj, "to_heatpump") and param_obj.value is not None:
+           try:
+               entry["raw_value"] = int(param_obj.to_heatpump(param_obj.value))
+           except (TypeError, ValueError, AttributeError):
+               entry["raw_value"] = None
+       else:
+           entry["raw_value"] = None
+       entry["display_value"] = str(param_obj.value) if param_obj.value is not None else None
+       params_dict[str(idx)] = entry
+   ```
+3. Build the full backup dict:
+   ```python
+   now = datetime.datetime.now(datetime.timezone.utc)
+   filename = now.strftime("%Y-%m-%d_%H-%M-%S") + ".json"
+   backup = {
+       "timestamp": now.isoformat(),
+       "host": self._host,
+       "parameters": params_dict,
+   }
+   ```
+4. Write to `{hass.config.path(BACKUP_DIR)}/{filename}`:
+   - Create directory with `os.makedirs(backup_path, exist_ok=True)`.
+   - Write JSON with `json.dump(backup, f, indent=2, ensure_ascii=False)`.
+5. Return `(filename, now.isoformat(), len(params_dict))` tuple for the caller.
+
+`async_setup_entry()` function (platform setup):
+- Get coordinator from `hass.data[DOMAIN][entry.entry_id]`.
+- Create one `LuxtronikBackupButton` instance.
+- Call `async_add_entities([button])`.
+
+IMPORTANT: Use the luxtronik library objects directly for reading parameter data (NOT the proxy package register_definitions). The coordinator pattern with `__new__` is proven and documented in coordinator.py.
+  </action>
+  <verify>
+    <automated>cd /home/dwolbeck/claude-code/PUBLIC-luxtronik2-modbus-proxy && python -c "
+import ast, sys
+# Verify button.py parses
+with open('custom_components/luxtronik2_modbus_proxy/button.py') as f:
+    tree = ast.parse(f.read())
+classes = [n.name for n in ast.walk(tree) if isinstance(n, ast.ClassDef)]
+assert 'LuxtronikBackupButton' in classes, f'Missing class, found: {classes}'
+# Verify PLATFORMS includes button
+with open('custom_components/luxtronik2_modbus_proxy/__init__.py') as f:
+    src = f.read()
+assert '\"button\"' in src, 'button not in PLATFORMS'
+# Verify BACKUP_DIR in const
+with open('custom_components/luxtronik2_modbus_proxy/const.py') as f:
+    src = f.read()
+assert 'BACKUP_DIR' in src, 'BACKUP_DIR not in const.py'
+print('Task 1 verification passed')
+"
+    </automated>
+  </verify>
+  <done>
+    - button.py exists with LuxtronikBackupButton class
+    - Button has EntityCategory.CONFIG (appears under Configuration)
+    - async_press reads all parameters via luxtronik library __new__ pattern
+    - JSON saved to config/luxtronik2_backups/YYYY-MM-DD_HH-MM-SS.json
+    - persistent_notification fires with parameter count, filename, timestamp
+    - Backup metadata stored in hass.data for sensor consumption
+    - "button" added to PLATFORMS in __init__.py
+    - BACKUP_DIR constant added to const.py
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add last backup sensor and update all translation files</name>
+  <files>
+    custom_components/luxtronik2_modbus_proxy/sensor.py,
+    custom_components/luxtronik2_modbus_proxy/strings.json,
+    custom_components/luxtronik2_modbus_proxy/translations/en.json,
+    custom_components/luxtronik2_modbus_proxy/translations/de.json
+  </files>
+  <action>
+**sensor.py** — Add a "Last Backup" sensor entity.
+
+This sensor does NOT use the coordinator data (it is not a Luxtronik register). Instead, it reads the backup metadata stored by button.py in `hass.data[DOMAIN][f"{entry_id}_last_backup"]`.
+
+Add a new class `LuxtronikLastBackupSensor(SensorEntity)` (NOT CoordinatorEntity — it does not depend on poll data):
+- `_attr_name = "Luxtronik Last Backup"`
+- `_attr_icon = "mdi:backup-restore"`
+- `_attr_entity_category = EntityCategory.DIAGNOSTIC`
+- `_attr_unique_id = f"{entry.entry_id}_last_backup"`
+- `_attr_device_class = SensorDeviceClass.TIMESTAMP`
+- `device_info` property: same DeviceInfo pattern as other entities.
+- Store `hass`, `entry_id` references.
+
+`native_value` property:
+- Read `hass.data[DOMAIN].get(f"{entry_id}_last_backup")`.
+- If None, return None (no backup yet).
+- Parse the ISO timestamp string and return as `datetime.datetime` object (required for TIMESTAMP device class).
+
+`extra_state_attributes` property:
+- Return `{"filename": metadata["filename"]}` if backup metadata exists, else `{}`.
+
+Wire the sensor to update when backup completes. In `async_added_to_hass()`:
+- Subscribe to dispatcher signal `f"{DOMAIN}_backup_complete"` using `async_dispatcher_connect`.
+- On signal, call `self.async_write_ha_state()` to refresh the sensor value.
+
+In `async_will_remove_from_hass()`:
+- The dispatcher unsub is handled automatically if stored via `self.async_on_remove()`.
+
+In `async_setup_entry()`: After the existing entity list creation, append one `LuxtronikLastBackupSensor(hass, entry)` to the entities list.
+
+Add these imports to sensor.py:
+```python
+import datetime
+from homeassistant.helpers.dispatcher import async_dispatcher_connect
+```
+
+**strings.json** — Add button and sensor entries to the `entity` section:
+```json
+"button": {
+  "backup_parameters": {
+    "name": "Backup Parameters"
+  }
+},
+"sensor": {
+  "last_backup": {
+    "name": "Last Backup"
+  }
+}
+```
+Note: The existing `entity` section does not have a `sensor` key yet (core sensors use hardcoded names). Add it alongside the existing `select` and `number` keys. Add `button` as a new key.
+
+**translations/en.json** — Mirror the strings.json changes: add the same `button` and `sensor` keys inside the `entity` section.
+
+**translations/de.json** — Add German translations:
+```json
+"button": {
+  "backup_parameters": {
+    "name": "Parameter-Sicherung"
+  }
+},
+"sensor": {
+  "last_backup": {
+    "name": "Letzte Sicherung"
+  }
+}
+```
+Add these inside the existing `entity` section alongside `select` and `number`.
+  </action>
+  <verify>
+    <automated>cd /home/dwolbeck/claude-code/PUBLIC-luxtronik2-modbus-proxy && python -c "
+import ast, json, sys
+# Verify LuxtronikLastBackupSensor in sensor.py
+with open('custom_components/luxtronik2_modbus_proxy/sensor.py') as f:
+    tree = ast.parse(f.read())
+classes = [n.name for n in ast.walk(tree) if isinstance(n, ast.ClassDef)]
+assert 'LuxtronikLastBackupSensor' in classes, f'Missing class, found: {classes}'
+# Verify strings.json has button entity
+with open('custom_components/luxtronik2_modbus_proxy/strings.json') as f:
+    strings = json.load(f)
+assert 'button' in strings['entity'], 'button not in strings.json entity section'
+assert 'backup_parameters' in strings['entity']['button'], 'backup_parameters key missing'
+# Verify en.json
+with open('custom_components/luxtronik2_modbus_proxy/translations/en.json') as f:
+    en = json.load(f)
+assert 'button' in en['entity'], 'button not in en.json'
+# Verify de.json
+with open('custom_components/luxtronik2_modbus_proxy/translations/de.json') as f:
+    de = json.load(f)
+assert 'button' in de['entity'], 'button not in de.json'
+assert de['entity']['button']['backup_parameters']['name'] == 'Parameter-Sicherung'
+print('Task 2 verification passed')
+"
+    </automated>
+  </verify>
+  <done>
+    - LuxtronikLastBackupSensor class exists in sensor.py
+    - Sensor has TIMESTAMP device class and shows last backup time
+    - Sensor extra_state_attributes includes filename
+    - Sensor updates via dispatcher signal when backup completes
+    - strings.json has button.backup_parameters and sensor.last_backup entries
+    - translations/en.json mirrors strings.json
+    - translations/de.json has German translations (Parameter-Sicherung, Letzte Sicherung)
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+1. `python -c "import ast; ast.parse(open('custom_components/luxtronik2_modbus_proxy/button.py').read())"` — button.py is valid Python
+2. `python -c "import json; json.load(open('custom_components/luxtronik2_modbus_proxy/strings.json'))"` — strings.json is valid JSON
+3. `grep -c '"button"' custom_components/luxtronik2_modbus_proxy/__init__.py` — returns 1 (platform registered)
+4. All three translation files have matching button/sensor entity keys
+</verification>
+
+<success_criteria>
+- A "Backup Parameters" button entity exists under the device's Configuration section
+- Pressing it reads all parameters via luxtronik library and saves JSON to /config/luxtronik2_backups/
+- JSON format matches spec: {timestamp, host, parameters: {index: {name, type, raw_value, display_value}}}
+- persistent_notification fires with backup summary
+- "Last Backup" sensor shows timestamp and filename attribute
+- All translation files (strings.json, en.json, de.json) updated
+- "button" registered in PLATFORMS list
+</success_criteria>
+
+<output>
+After completion, create `.planning/quick/260409-m53-add-parameter-backup-button-and-backup-v/260409-m53-SUMMARY.md`
+</output>