feat: expand unsupported device support

Add Sandisolar runtime identification, typed support-acquisition readiness, and fail-closed cloud evidence workflows that remain usable before inverter detection. Document and test the complete active-learning endpoint, command, interception, and recovery consent boundary.

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -7,6 +7,40 @@ the GitHub release body should be rendered from the matching version section her
 
 ## [Unreleased]
 
+### Added
+
+- Added built-in detection and telemetry mapping for the Sandisolar SD 11KP48V
+  WIFI fingerprint (`layout=4`, `model=0x8003`) from issue #13 evidence.
+  Compatible controls remain explicitly untested and Full-Control-only.
+- Added a typed support-acquisition boundary so read-only cloud evidence can be
+  collected for an identified collector before an inverter driver is known.
+
+### Changed
+
+- Moved device-support analysis and collector cloud-traffic capture under one
+  **Expand device support** menu with separate readiness rules for read-only
+  metadata, active learning, and proxy capture.
+- Active-learning consent now explicitly covers the temporary collector
+  endpoint change, bounded cloud test commands, local interception, and route
+  restoration.
+
+### Fixed
+
+- Fixed stale generic-SMG projections that could survive a stronger runtime
+  fingerprint and hide the correct model-specific telemetry surface.
+- Added typed per-route probe evidence so support diagnostics can distinguish
+  framed and raw-serial attempts without exposing endpoints or payloads.
+- Kept support evidence and proxy diagnostics available when the collector is
+  identified but the inverter driver is still unresolved, while active
+  route-owning operations continue to fail closed.
+
+### Docs
+
+- Added safe instructions for manually testing the unreleased `main` branch
+  without creating a tag or GitHub release.
+- Updated device-learning and proxy-capture guides for the current menu names,
+  trust boundaries, and recovery behavior.
+
 ## [0.3.0-beta.4] - 2026-08-25
 
 ### Added

README.md

@@ -127,6 +127,23 @@ It is a small ESP8266/ESP32-based bridge that connects directly to the inverter
 3. Restart Home Assistant.
 4. Add **EyeBond Local** from **Settings → Devices & Services**.
 
+### Testing the unreleased `main` branch
+
+Use this only when a maintainer asks you to test a fix that is not in a release
+yet. It does not update through HACS and may change before the next release.
+
+1. Back up your Home Assistant configuration.
+2. Download the current [`main` branch archive](https://github.com/groove-max/ha-eybond-local/archive/refs/heads/main.zip).
+3. Remove the existing `config/custom_components/eybond_local/` directory, then
+   copy the complete directory from the archive into `config/custom_components/`.
+   Do not mix files from two builds.
+4. Restart Home Assistant and check the EyeBond Local entries.
+5. When reporting a result, include the Git commit shown on the repository page
+   and attach a new Support Archive.
+
+To return to a published build, reinstall the latest release through HACS or
+replace the directory with the complete directory from that release archive.
+
 ---
 
 ## Setup
@@ -235,8 +252,8 @@ mode, and the difference between unavailable and disabled entities.
 
 ## Device learning
 
-Some devices can be added in read-only or partial mode first. **Expand support
-for this device** can then collect extra evidence or check which additional
+Some devices can be added in read-only or partial mode first. **Expand device
+support** can then collect extra evidence or check which additional
 settings and sensors your exact device supports.
 
 Use it when:
@@ -247,12 +264,13 @@ Use it when:
 
 What to expect:
 
-1. Start **Configure → Expand support for this device**.
+1. Start **Configure → Expand device support**.
 2. Choose **Analyze device data** (recommended) or the advanced active-control
    verification.
 3. When more than one compatible API is available, choose the exact cloud
    source for this run.
-4. Read the safety notice when active verification is selected.
+4. For active verification, confirm the temporary collector endpoint change,
+   bounded cloud test commands, and their local interception by Home Assistant.
 5. Sign in to the supported cloud account for this one session, if requested.
 6. Review the result. Read-only evidence does not add entities automatically;
    only locally proven active results can be applied.

README.uk.md

@@ -130,6 +130,23 @@ PI30 та SRNE. Рівень підтримки залежить від моде
 3. Перезапустіть Home Assistant.
 4. Додайте **EyeBond Local** через **Налаштування → Пристрої та служби**.
 
+### Тестування неопублікованої гілки `main`
+
+Використовуйте цей спосіб лише тоді, коли розробник просить перевірити виправлення,
+якого ще немає в релізі. Така збірка не оновлюється через HACS і може змінитися
+до наступного релізу.
+
+1. Створіть резервну копію конфігурації Home Assistant.
+2. Завантажте архів поточної [гілки `main`](https://github.com/groove-max/ha-eybond-local/archive/refs/heads/main.zip).
+3. Видаліть наявну папку `config/custom_components/eybond_local/`, а потім
+   скопіюйте туди всю папку з архіву. Не змішуйте файли з різних збірок.
+4. Перезапустіть Home Assistant і перевірте записи EyeBond Local.
+5. Разом із результатом вкажіть Git commit зі сторінки репозиторію та додайте
+   новий архів підтримки.
+
+Щоб повернутися до опублікованої версії, перевстановіть останній реліз через
+HACS або повністю замініть папку версією з архіву релізу.
+
 ---
 
 ## Налаштування
@@ -243,7 +260,7 @@ Modbus-пристрої можуть оновлюватися частіше, н
 ## Навчання пристрою
 
 Деякі пристрої спочатку додаються в режимі лише читання або часткової
-підтримки. **Розширити підтримку цього пристрою** може зібрати додаткові дані
+підтримки. **Розширити підтримку пристрою** може зібрати додаткові дані
 або перевірити, які локальні сенсори й елементи керування підтримує саме ваш
 пристрій.
 
@@ -255,12 +272,13 @@ Modbus-пристрої можуть оновлюватися частіше, н
 
 Що відбувається:
 
-1. Відкрийте **Налаштувати → Розширити підтримку цього пристрою**.
+1. Відкрийте **Налаштувати → Розширити підтримку пристрою**.
 2. Виберіть **Аналізувати дані пристрою** (рекомендовано) або розширену активну
    перевірку елементів керування.
 3. Якщо доступно кілька сумісних API, виберіть конкретне хмарне джерело для
    цього запуску.
-4. Прочитайте попередження, якщо вибрано активну перевірку.
+4. Для активної перевірки підтвердьте тимчасову зміну endpoint колектора,
+   обмежені тестові команди через хмару та їх локальне перехоплення Home Assistant.
 5. Увійдіть у підтримуваний хмарний акаунт лише для цього сеансу, якщо це буде
    запропоновано.
 6. Перегляньте результат. Дані лише для читання не створюють сутності

catalog/inverter_models/models/sandisolar_sd_11kp48v_wifi.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": 1,
+  "model_key": "sandisolar_sd_11kp48v_wifi",
+  "manufacturer": "Sandisolar",
+  "model": "SD 11KP48V WIFI",
+  "aliases": [],
+  "lifecycle": "experimental",
+  "variants": [
+    {
+      "variant_key": "layout4_model32771",
+      "label": "Protocol-4 fingerprint 171=0x8003, 184=4",
+      "device_descriptor_keys": [
+        "sandisolar_sd_11kp48v"
+      ],
+      "known_firmware": []
+    }
+  ],
+  "validation": {
+    "hardware": "captured",
+    "telemetry": "partial",
+    "controls": "none"
+  },
+  "coverage": {
+    "runtime_control_surface": "available",
+    "smartess_control_surface": "unknown",
+    "vendor_register_map": "documented",
+    "notes": [
+      "The exact layout/model fingerprint is captured from the issue #13 beta.4 support archive.",
+      "Telemetry uses the documented Anenji protocol-4 register schema; this prevents generic SMG interpretation of register 227 as temperature.",
+      "The compatible ANJ write surface is inherited only as untested Full-Control candidates. Automatic control mode exposes none of these writes."
+    ]
+  },
+  "known_limitations": [
+    "No local write has been validated on this exact Sandisolar fingerprint; every inherited control remains Full-Control-only until hardware retesting."
+  ],
+  "knowledge_summary": "Sandisolar SD 11KP48V WIFI with exact layout-4/model-0x8003 identity. Captured telemetry follows the documented ANJ protocol-4 map, while compatible write candidates remain explicitly untested.",
+  "source_keys": [
+    "github_issue_13_sandisolar_sd_11kp48v_beta4",
+    "documentation_anenji_protocol_3_10"
+  ]
+}

catalog/inverter_models/sources/github_issue_13_sandisolar_sd_11kp48v_beta4.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": 1,
+  "source_key": "github_issue_13_sandisolar_sd_11kp48v_beta4",
+  "kind": "github_issue",
+  "title": "Sandisolar SD 11KP48V WIFI beta.4 support archive",
+  "reference": "project-issue:13#support-archive-20260825",
+  "captured_at": "2026-08-25",
+  "visibility": "public",
+  "summary": "A beta.4 support archive captured the exact Modbus fingerprint layout 4 and model code 0x8003 for a Sandisolar SD 11KP48V WIFI reported as an ANJ-11KW-compatible inverter. The live values at registers 227 and 231 follow the documented protocol-4 frequency and temperature layout rather than the generic SMG layout.",
+  "assertions": [
+    "commercial_identity",
+    "fingerprint",
+    "runtime_compatibility",
+    "telemetry_validation"
+  ]
+}

custom_components/eybond_local/config_entry.py

@@ -62,7 +62,7 @@
     CONNECTION_STRATEGIES,
     CONNECTION_STRATEGY_CALLBACK_ON_DEMAND,
     CONNECTION_STRATEGY_INBOUND,
-    CONTROL_MODE_READ_ONLY,
+    DEFAULT_CONTROL_MODE,
     DEFAULT_DRIVER_DETECTION_STRATEGY,
     DEFAULT_POLL_INTERVAL,
     DEFAULT_POLL_MODE,
@@ -359,7 +359,10 @@ async def _async_create_entry_from_result(
             CONF_CONNECTION_TYPE: connection_type,
             **connection_settings,
             CONF_CONNECTION_MODE: stored_connection_mode,
-            CONF_CONTROL_MODE: CONTROL_MODE_READ_ONLY,
+            # ``control_mode`` is durable user intent.  Runtime driver binding
+            # supplies the temporary write interlock while inverter detection
+            # is pending; a new entry must not masquerade as user Read-only.
+            CONF_CONTROL_MODE: DEFAULT_CONTROL_MODE,
             CONF_COLLECTOR_PN: collector_pn,
             CONF_DETECTION_CONFIDENCE: "none",
             CONF_DETECTED_MODEL: "",
@@ -604,7 +607,7 @@ async def _async_create_manual_entry(
             driver_hint=driver_hint,
         )
         data.setdefault(CONF_CONNECTION_TYPE, connection_type)
-        data[CONF_CONTROL_MODE] = CONTROL_MODE_READ_ONLY
+        data[CONF_CONTROL_MODE] = DEFAULT_CONTROL_MODE
         collector_capabilities = _result_collector_capabilities(result)
         data[CONF_COLLECTOR_IP] = collector_ip
         data[CONF_DETECTION_CONFIDENCE] = "none"

custom_components/eybond_local/flow_translations/en.json

@@ -5,11 +5,11 @@
       "action_reload_local_metadata": "Reload local metadata",
       "action_rollback_local_metadata": "Rollback local metadata",
       "action_proxy_capture": "Collector traffic capture",
-      "cloud_tools_title": "Cloud traffic tools",
+      "cloud_tools_title": "Expand device support",
       "shadow_learning_status_overlay_activated": "Discovered controls activated for this device and reload requested.",
       "shadow_learning_status_support_exported": "Support package exported without running control discovery.",
       "shadow_learning_preflight_summary": "Can start: {can_start}; blockers: {blockers}",
-      "shadow_learning_warning": "Control discovery is advanced and optional. It briefly uses {cloud_provider_label} to test which settings Home Assistant can control. Testing all option values or numeric settings can trigger cloud-side actions and requires explicit preview and confirmation.",
+      "shadow_learning_warning": "Active verification is advanced and optional. It temporarily reroutes the collector through Home Assistant, asks {cloud_provider_label} to send bounded test commands, and intercepts the matching local writes. It requires explicit confirmation.",
       "yes": "Yes",
       "no": "No",
       "none": "None",
@@ -62,7 +62,7 @@
       "cloud_learning_metadata_unit_conflict_detail": "cloud unit {observed_unit}; expected {expected_unit}",
       "cloud_learning_metadata_result": "The read-only check found {cloud_metadata_count} metadata field(s), including {cloud_semantic_candidate_count} recognized semantic candidate(s). {cloud_history_summary} No local register mapping was proven, so no entities or controls were added. {cloud_local_history_review_summary} {local_register_observation_summary} Download the support package or return to the menu.",
       "cloud_learning_inactive_draft_available": "{count} exact-route candidate(s) can be saved as an inactive local sensor draft for review. This does not add entities.",
-      "control_discovery_intro_hint": "Home Assistant will briefly sign in to {cloud_provider_label} to find which settings it can control on this device. Your login is used only for this check and is not saved.\n\n⚠️ Before you continue, fully CLOSE the {cloud_app_label} mobile app. If it stays open it competes with this check for the device and can disrupt the scan or interfere with the inverter.\n\nConfirm below to continue.",
+      "control_discovery_intro_hint": "Home Assistant will temporarily change the collector's cloud endpoint to a local Home Assistant route. The selected cloud service will then send bounded test commands for this device. Home Assistant must capture and block the matching local writes before they reach the inverter; if that interception cannot be proven, the check stops. Afterward Home Assistant restores the previous endpoint. The vendor app may briefly lose live data during the switch; if automatic restoration cannot be confirmed, a recovery action remains available. Your login is used only for this check and is not saved.\n\n⚠️ Before you continue, fully CLOSE the {cloud_app_label} mobile app so it does not compete with the check.\n\nConfirm the temporary routing, test commands, and local interception below.",
       "control_discovery_credentials_hint": "Enter your {cloud_provider_label} username and password. They are used only for this one check and are not saved.",
       "control_discovery_progress_status": "Checking device information…",
       "control_discovery_result_intro": "Discovery finished and the temporary cloud connection is closed. {control_discovery_selected_count} control(s) are turned on. Apply them, download the support package, or return to the menu.",