various

Author: kellerza

.cursor/rules/sunsynk-addons.mdc

@@ -11,54 +11,57 @@ alwaysApply: true
 
 ## Editing policy (agents)
 
-**Do not** create, edit, delete, or move files under **`hass-addon-sunsynk-multi/`** unless the user **explicitly** asks for
-stable-multi work (e.g. “sync multi”, “release prep”, “fix CI output in multi”, “cherry-pick to stable addon”). Normal
-tasks — config, schema, translations, Dockerfile, run scripts, CHANGELOG in the add-on folder — **must only be proposed
-under `hass-addon-sunsynk-edge/`**.
+**Do not** create, edit, delete, or move files under **`hass-addon-sunsynk-multi/`** unless the user
+**explicitly** asks for stable-multi work (e.g. “sync multi”, “release prep”, “fix CI output in
+multi”, “cherry-pick to stable addon”). Normal tasks — config, schema, translations, Dockerfile, run
+scripts, CHANGELOG in the add-on folder —
+**must only be proposed under `hass-addon-sunsynk-edge/`**.
 
-If the user has **`hass-addon-sunsynk-multi/**`** open or asks for a change that would touch multi, **redirect**: apply the
-same change under **`hass-addon-sunsynk-edge/`** (or `src/` / docs as below) and state that multi is updated by **CI when
-a GitHub tag is pushed**.
+If the user has **`hass-addon-sunsynk-multi/**`** open or asks for a change that would touch multi,
+**redirect**: apply the same change under **`hass-addon-sunsynk-edge/`** (or `src/` / docs as below)
+and state that multi is updated by **CI when a GitHub tag is pushed**.
 
 ## Repository layout
 
-- **`hass-addon-sunsynk-edge`** — **Development add-on.** All manual add-on packaging work happens here (`config.yaml`,
-  `schema`, `translations/`, Docker/run scripts).
+- **`hass-addon-sunsynk-edge`** — **Development add-on.** All manual add-on packaging work happens
+  here (`config.yaml`, `schema`, `translations/`, Docker/run scripts).
 
-- **`hass-addon-sunsynk-multi`** — **Stable / release add-on.** **CI-maintained** for routine changes; do not hand-edit
-  as part of feature work.
+- **`hass-addon-sunsynk-multi`** — **Stable / release add-on.** **CI-maintained** for routine
+  changes; do not hand-edit as part of feature work.
 
-- **`src/ha_addon_sunsynk_multi`** — **Add-on Python** used in the Docker build. Implement behaviour here; it ships with
-  edge builds immediately and is what the multi image is built from on release (no second code path).
+- **`src/ha_addon_sunsynk_multi`** — **Add-on Python** used in the Docker build. Implement behaviour
+  here; it ships with edge builds immediately and is what the multi image is built from on release
+  (no second code path).
 
 ## Supervisor options (documentation workflow)
 
-When you add or change a **Supervisor option**, keep these in sync — **using edge for packaging strings**:
+When you add or change a **Supervisor option**, keep these in sync —
+**using edge for packaging strings**:
 
 ### 1. Home Assistant UI (`translations/en.yaml`)
 
-- Add or update **`hass-addon-sunsynk-edge/translations/en.yaml`** only (short `name` / `description` for the Supervisor
-  UI).
-- **Do not** update `hass-addon-sunsynk-multi/translations/` unless the user explicitly requests stable-multi sync; CI /
-  release flow is expected to align multi with edge.
+- Add or update **`hass-addon-sunsynk-edge/translations/en.yaml`** only (short `name` /
+  `description` for the Supervisor UI).
+- **Do not** update `hass-addon-sunsynk-multi/translations/` unless the user explicitly requests
+  stable-multi sync; CI / release flow is expected to align multi with edge.
 
 ### 2. Reference docs (`www/docs/reference/multi-options.md`)
 
-- Document every user-facing option; this page is built into the **VitePress** site. Use the same `OPTION_KEY` as in
-  `config.yaml` (uppercase with underscores).
+- Document every user-facing option; this page is built into the **VitePress** site. Use the same
+  `OPTION_KEY` as in `config.yaml` (uppercase with underscores).
 
-**Dev / edge only:** if the option exists **only** in `hass-addon-sunsynk-edge/config.yaml` (not yet in multi’s
-`config.yaml`), prefix the bullet in `multi-options.md` with:
+**Dev / edge only:** if the option exists **only** in `hass-addon-sunsynk-edge/config.yaml` (not yet
+in multi’s `config.yaml`), prefix the bullet in `multi-options.md` with:
 
 ```markdown
 - <i-mdi-dev-to class="vp-edge-option-icon" /> `YOUR_OPTION` – …
 ```
 
-**After release:** when CI adds the option to **`hass-addon-sunsynk-multi/config.yaml`**, remove that icon prefix and any
-“edge only” wording for that option (edits to **`multi-options.md`** are fine; still avoid hand-editing multi **addon**
-files unless the user asked).
+**After release:** when CI adds the option to **`hass-addon-sunsynk-multi/config.yaml`**, remove
+that icon prefix and any “edge only” wording for that option (edits to **`multi-options.md`** are
+fine; still avoid hand-editing multi **addon** files unless the user asked).
 
 ### 3. Python (`src/ha_addon_sunsynk_multi/options.py`)
 
-- Add or update `Options` / `InverterOptions` fields so YAML/env loading matches the edge schema (uppercase keys map to
-  lowercase attributes via `mqtt_entity`).
+- Add or update `Options` / `InverterOptions` fields so YAML/env loading matches the edge schema
+  (uppercase keys map to lowercase attributes via `mqtt_entity`).

.cursor/rules/sunsynk-definitions.mdc

@@ -0,0 +1,39 @@
+---
+description: Inverter Modbus sensor definitions — profiles, inheritance, single vs three phase
+globs:
+  - src/sunsynk/definitions/**
+alwaysApply: false
+---
+
+# Sunsynk inverter definitions (`src/sunsynk/definitions/`)
+
+## What lives here
+
+All **Modbus register → sensor** mappings for supported inverters live under
+**`src/sunsynk/definitions/`**. Each **named definition profile** (loaded via `import_defs` in
+`__init__.py`) corresponds to a **distinct inverter family / register layout**, not a small tweak on
+the same map.
+
+## Building on another profile
+
+Some definitions **reuse another module’s `SENSORS`** and patch or append registers (e.g.
+`single_phase_16kw.py` starts from `single_phase` and overrides selected sensors). That pattern
+means a **large common register set** with **local overrides** — but only where the hardware
+actually matches.
+
+## Single-phase vs three-phase
+
+**Single-phase** (`single_phase.py`, …) and **three-phase** (`three_phase_common.py` plus
+`three_phase_lv.py` / `three_phase_hv.py`) are **not** two views of the same register file: they use
+**different definitions and different register semantics**. When adding or comparing sensors:
+
+- **Do not assume** the same holding register number means the same physical quantity across
+  profiles.
+- Prefer **reading the target profile’s file** end-to-end for that inverter before copying a sensor
+  from another profile.
+
+## Canonical profile names
+
+The add-on / library config string for each profile is listed in **`ALL_DEFS`** in
+`src/sunsynk/definitions/__init__.py` (e.g. `single-phase`, `single-phase-16kw`, `three-phase`,
+`three-phase-hv`). New profiles must be wired there (and in docs / schema as needed).

.github/copilot-instructions.md

@@ -0,0 +1,31 @@
+# Sunsynk — align with Cursor rules
+
+This project keeps its agent and contributor policies in **`.cursor/rules/`** as
+Markdown-with-frontmatter files (**`*.mdc`**). **Follow those files as the source of truth** for how
+to work in this repository.
+
+## What to do
+
+1. **Before** suggesting or applying changes in an area covered by a rule’s `globs` (see the YAML
+   frontmatter at the top of each `.mdc` file), **read the relevant `.cursor/rules/*.mdc` file** in
+   the repo and obey its body (the markdown after the closing `---` of the frontmatter block).
+2. **Repository-wide / always-on rules:** if a rule sets `alwaysApply: true` in its frontmatter,
+   treat it as binding for **all** work in this repo unless the user explicitly overrides it in the
+   current conversation.
+3. **When new rules are added** under `.cursor/rules/`, use them the same way: prefer the rule text
+   over assumptions from similar projects.
+
+## Current rule files (index)
+
+| Path | Typical scope | Topic |
+| ------ | ---------------- | -------- |
+| `.cursor/rules/sunsynk-addons.mdc` | Home Assistant add-ons, add-on Python (`src/ha_addon_sunsynk_multi/`), `www/docs/reference/multi-options.md` | Edit **`hass-addon-sunsynk-edge/`** for packaging; do not hand-edit **`hass-addon-sunsynk-multi/`** unless the user explicitly asks for stable-multi work; keep Supervisor options, docs, and `options.py` in sync as described in the rule. |
+| `.cursor/rules/sunsynk-definitions.mdc` | `src/sunsynk/definitions/**` | Inverter Modbus definitions: profiles, inheritance, single- vs three-phase; how to extend `ALL_DEFS` and avoid wrong cross-profile register assumptions. |
+
+If this index drifts, **trust the `.mdc` files**; update this table when you add or rename rules.
+
+## Conflicts
+
+If another document in the repo disagrees with a **`.cursor/rules/*.mdc`** rule,
+**follow the `.mdc` rule** unless the user or maintainer explicitly says otherwise in the current
+thread.

.pre-commit-config.yaml

@@ -33,7 +33,7 @@ repos:
 
       - id: codespell
         name: codespell
-        entry: uv run codespell --toml pyproject.toml
+        entry: uv run codespell --toml pyproject.toml src www/docs www/README.md README.md scripts .github .cursor/rules hass-addon-sunsynk-edge hass-addon-sunsynk-multi hass-addon-mbusd
         language: system
         pass_filenames: false
 

pyproject.toml

@@ -76,7 +76,8 @@ lint.pylint.max-args = 7
 
 [tool.codespell]
 ignore-words-list = "HASS,hass,Hass,ist"
-skip = "data,*.map,package-lock.json,*.map,**/cache/*,**/node_modules/*"
+# Scan roots are the paths on the codespell pre-commit hook (not the whole repo).
+skip = "*.map"
 
 [tool.pyrefly]
 project-includes = [
@@ -99,6 +100,7 @@ warn_unreachable = false
 warn_unused_ignores = true  # Not yet supported in 0.6.0
 
 [tool.rumdl]
+include = [ "**/*.md", "**/*.mdc" ]
 respect-gitignore = true
 extend-enable = [ "MD060" ]  # table formatting
 MD013.severity = "info"

scripts/gen_sensors.py

@@ -7,6 +7,7 @@
 from ha_addon_sunsynk_multi.sensor_options import SENSOR_GROUPS
 from sunsynk import RWSensor, Sensor, SensorDefinitions
 from sunsynk.definitions import import_all_defs
+from sunsynk.helpers import ensure_tuple
 from sunsynk.utils import pretty_table, table_data
 
 
@@ -34,13 +35,15 @@ def generate_all_sensors(
             sensors[key]["Group"] = "<br>".join(sorted(sen_groups.get(sen.id, [])))
 
     def getname(row: list[Sensor | str | None]) -> str:
-        """Get the name of the row."""
+        """Get the name of the row (HTML: name, then aliases on separate lines)."""
         for sen in row:
             if not sen or isinstance(sen, str):
                 continue
-            if isinstance(sen, RWSensor):
-                return f"{sen.name} (R/W)"
-            return sen.name
+            base = f"{sen.name} (R/W)" if isinstance(sen, RWSensor) else sen.name
+            aliases = ensure_tuple(sen.alias)
+            if aliases:
+                return "<br>".join((base, *aliases))
+            return base
         return "?"
 
     def get_sensor_info(sensor: Sensor | str | None) -> str:

src/ha_addon_sunsynk_multi/a_inverter.py

@@ -58,7 +58,7 @@ class AInverter:
     """Where this inverter is in the add-on poll loop (see `AInverterLifecycle`)."""
 
     _stale_quiet_until: float = 0
-    _stale_enter_at: float = float("inf")
+    _stale_enter_at: float = 0
 
     write_queue: dict[Sensor, str | int | float | bool] = field(default_factory=dict)
     """Write queue for RWSensors."""
@@ -119,8 +119,12 @@ async def set_lifecycle(self, lifecycle: AInverterLifecycle | None) -> None:
         except Exception as err:
             _LOG.debug("Lifecycle availability publish failed: %s", err)
 
-    async def lifecycle_enter_stale(self, reason: str | None = None) -> None:
+    async def lifecycle_enter_stale(self, reason: str | None = None) -> bool:
         """Start or extend stale quiet: refresh deadline, set lifecycle, and log."""
+        past_stale = time.monotonic() >= self._stale_enter_at
+        if self.lifecycle in ("running", "starting") and not past_stale:
+            return False
+
         self._stale_quiet_until = time.monotonic() + OPT.stale_inverter_skip_seconds
         await self.set_lifecycle("stale_quiet")
         if reason is None:
@@ -131,6 +135,7 @@ async def lifecycle_enter_stale(self, reason: str | None = None) -> None:
             OPT.stale_inverter_skip_seconds,
             reason,
         )
+        return True
 
     async def lifecycle_attempt_recovery(self) -> None:
         """Handle stale quiet or run a serial probe when quiet has elapsed."""
@@ -173,18 +178,22 @@ def serial_matches_config(self) -> bool:
     async def read_sensors(self, *, sensors: Iterable[Sensor], msg: str = "") -> bool:
         """Read from the Modbus interface."""
         async with self.lock_io() as inv:
+            await asyncio.sleep(0.005)
             try:
-                await asyncio.sleep(0.005)
-                await inv.read_sensors(sensors)
+                async with asyncio.timeout(OPT.timeout * 2):
+                    await inv.read_sensors(sensors)
                 self.read_errors = 0
                 self._stale_enter_at = (
                     time.monotonic() + OPT.stale_inverter_after_seconds
                 )
                 return True
+            except TimeoutError:
+                self.read_errors += 1
+                await self.lifecycle_enter_stale("read timeout")
+                return False
             except ExceptionGroup as err:
                 self.read_errors += 1
-                if time.monotonic() > self._stale_enter_at:
-                    await self.lifecycle_enter_stale()
+                if await self.lifecycle_enter_stale():
                     return False
                 if msg:
                     arg0, *argn = err.args if err.args else ("",)
@@ -301,7 +310,7 @@ def hass_create_discovery_info(self) -> None:
 
         if self.mqtt_dev.id == "":
             self.mqtt_dev = MQTTDevice(
-                identifiers=[("serial", serial_nr)],
+                identifiers=[serial_nr],
                 # https://github.com/kellerza/sunsynk/issues/165
                 # name=f"{OPT.manufacturer} AInverter {serial_nr}",
                 name=self.opt.ha_prefix,

src/sunsynk/definitions/single_phase.py

@@ -68,37 +68,47 @@
     Sensor(192, "Load frequency", HZ, 0.01),
 )
 
-#################
-# AUX / Generator
-#################
+######################
+# AUX / Generator Port
+######################
 SENSORS += (
-    Sensor(166, "AUX power", WATT, -1),
-    # Sensor(166, "Generator Power", WATT, -1),
-    Sensor(181, "AUX voltage", VOLT, 0.1),
-    Sensor(196, "AUX frequency", HZ, 0.1),
+    SelectRWSensor(
+        235,
+        "AUX port usage",
+        "",
+        options={0: "Disable", 1: "Smartload", 2: "Generator"},
+        alias="Generator input",
+    ),
+    Sensor(166, "Gen power", WATT, -1, alias="AUX power"),
+    Sensor(181, "Gen L1 voltage", VOLT, 0.1, alias="AUX L1 voltage"),
+    Sensor(182, "Gen L2 voltage", VOLT, 0.1, alias="AUX L2 voltage"),
+    Sensor(183, "Gen L3 voltage", VOLT, 0.1, alias="AUX L3 voltage"),
+    Sensor(184, "Gen L1 current", AMPS, -0.01, alias="AUX L1 current"),
+    Sensor(185, "Gen L2 current", AMPS, -0.01, alias="AUX L2 current"),
+    Sensor(186, "Gen L3 current", AMPS, -0.01, alias="AUX L3 current"),
 )
 
-#############
-# Solar PV 1
-#############
+#####################
+# MPPT 1 Solar Power
+#####################
 SENSORS += (
     Sensor(186, "PV1 power", WATT, -1),
     Sensor(109, "PV1 voltage", VOLT, 0.1),
     Sensor(110, "PV1 current", AMPS, 0.1),
 )
 
-#############
-# Solar PV 2
-#############
+#####################
+# MPPT2 Solar Power
+#####################
 SENSORS += (
     Sensor(187, "PV2 power", WATT, -1),
     Sensor(111, "PV2 voltage", VOLT, 0.1),
     Sensor(112, "PV2 current", AMPS, 0.1),
 )
 
-#############
-# Solar PV 3
-#############
+#####################
+# MPPT 3 Solar Power
+#####################
 SENSORS += (
     Sensor(188, "PV3 power", WATT, -1),
     Sensor(113, "PV3 voltage", VOLT, 0.1),
@@ -182,9 +192,6 @@
     SwitchRWSensor(43, "Inverter enabled", on=1),  # 0=off, 1=on
     Sensor(200, "Control mode"),
     SwitchRWSensor(232, "Grid charge enabled", "", bitmask=1),
-    SelectRWSensor(
-        235, "Generator input", "", options={0: "Disable", 1: "Output", 2: "Input"}
-    ),
     Sensor(312, "Battery charging voltage", VOLT, 0.01),
     Sensor(603, "Bat1 SOC", "%"),
     Sensor(611, "Bat1 Cycle"),