docs: document opt-in short-ASCII aux MPPT admission

Author: mikehardy

CHANGELOG.md

@@ -10,16 +10,17 @@ the GitHub release body should be rendered from the matching version section her
 ### Added
 
 - Added an offline MPPT-frame inspector for maintainers, with strict runtime
-  decoding and explicit warnings about overlapping wire formats. This does not
-  enable live PV polling or create additional Home Assistant entities.
+  decoding and explicit warnings about overlapping wire formats. That tool does
+  not poll devices or create Home Assistant entities; live optional PV is a
+  separate admission path below.
 
 - Added a generic read-only **EyeBond Short-ASCII family** profile for the
   captured MP/Q1/MD dialect seen on some Anern and Maxinn devices (#45).
   It provides grid/output voltage, load percentage, output frequency,
   temperature and status diagnostics. Battery Reference Voltage is shown
   separately from full-pack voltage. Identity is family-only: no retail model
-  (including no Anern SPI-12000W claim), serial number, live PV power or
-  inverter controls are inferred. Offline MPPT decode remains maintainer-only.
+  (including no Anern SPI-12000W claim), serial number or inverter controls are
+  inferred.
 
 - Short-ASCII also publishes labelled **Estimated AC Load Power**
   (`estimated_ac_load_power` = load% × rated VA from F). It is an estimate, not
@@ -39,11 +40,25 @@ the GitHub release body should be rendered from the matching version section her
   I/P bounds; RH `0`, unread, expired or failed RH omits those keys. RH=1 is the
   discriminator (no retail-model gate). One live family member has SmartValue
   correlation for that path; other members (e.g. Maxinn) are not separately
-  live-proven. Live PV remains absent; this is not full device or control
-  support (#45).
+  live-proven. This is not full device or control support (#45).
+
+- Optional short-ASCII **live PV/MPPT** uses the shared framed
+  `async_send_auxiliary_read` facade for the documented 21-byte `0200` runtime
+  query only (settings `0202` is not live telemetry; no tip AABB harvest or
+  EyeBond TID `0xAABB` as aux). Values follow the same OptionalSample pattern as
+  RB (30 s solicit / 60 s TTL), at most one optional read per successful Q1
+  cycle. Nine matching schema sensors (`pv_*`, `mppt_*`, `dc_load_current`) stay
+  **disabled by default**; `mppt_error_code` is diagnostic and quiet. Offline
+  `decode_short_ascii_mppt` remains a maintainer capture tool, not this live path.
+  Site live-qualification / Support Archive RECEIPT for the family cutover is
+  still pending (#45).
 
 ### Fixed
 
+- When both are due in one Q1 cycle, short-ASCII optional reads prefer FC4
+  RB/F/RH over the aux MPPT solicit so a virgin MPPT due time cannot starve BMS
+  or rated refreshes (#45).
+
 - Support archives preserve numeric-looking hex sequences in explicitly typed
   wire-evidence fields instead of replacing their bytes with identifier masks.
   Embedded ASCII identifiers remain masked. Short-ASCII archive creation and

README.md

@@ -105,9 +105,10 @@ If your inverter is not listed, it may still work. Add it, create a Support Arch
 
 The unreleased test code also includes a limited **EyeBond Short-ASCII family**
 profile for a protocol observed on some Anern and Maxinn units. It includes
-basic telemetry, a labelled AC-load estimate, and optional BMS/rated readings
-where the device answers them. Live PV and inverter controls are absent. This
-identifies the protocol family, not a retail commercial model. See its
+basic telemetry, a labelled AC-load estimate, optional BMS/rated readings, and
+opt-in PV/MPPT entities (disabled by default) where the device answers them.
+Inverter controls are absent. This identifies the protocol family, not a retail
+commercial model. See its
 [available readings and limits](docs/user/RUNTIME_AND_INVERTER.md#eyebond-short-ascii-family).
 
 ### No factory collector?

README.uk.md

@@ -109,9 +109,9 @@ PI30 та SRNE. Рівень підтримки залежить від моде
 Тестовий код, який ще не увійшов до релізу, також містить обмежений профіль
 **EyeBond Short-ASCII family** для протоколу деяких Anern і Maxinn. Він надає
 базові показання, оцінку потужності навантаження та, на пристроях із
-відповідними відповідями, дані BMS і номінальні параметри. Жива PV-потужність
-і керування відсутні. Це визначення сімейства протоколу, не роздрібної
-комерційної моделі. Додаткові сутності вимкнені за замовчуванням. Дивіться
+відповідними відповідями, дані BMS і номінальні параметри, а також
+опційні сенсори PV/MPPT (вимкнені за замовчуванням). Керування відсутнє. Це
+визначення сімейства протоколу, не роздрібної комерційної моделі. Дивіться
 [доступні показання й обмеження](docs/user/RUNTIME_AND_INVERTER.md#eyebond-short-ascii-family).
 
 ### Немає заводського колектора?

catalog/inverter_models/models/eybond_short_ascii_family.json

@@ -28,21 +28,23 @@
     "vendor_register_map": "partial",
     "notes": [
       "Runtime support is family-only and read-only. Compatible devices appear as EyeBond Short-ASCII family; retail model and serial are not inferred.",
-      "Optional RB/F/RH entities are disabled by default and expire on TTL or invalid replies."
+      "Optional RB/F/RH and aux-0200 MPPT/PV entities are disabled by default and expire on TTL or invalid replies."
     ]
   },
   "known_limitations": [
     "Family identity only: no retail commercial model (including no Anern SPI-12000W claim) and no inverter serial from MP/Q1/MD.",
     "Read-only: no inverter controls; Full Control does not invent settings.",
-    "Live PV power is absent; offline MPPT decode is maintainer-only and does not create HA entities.",
-    "Quiet fault/diagnostic sensors beyond the existing Q1 flags (Q2) are deferred; mppt_error waits on any future live-PV admission.",
+    "Optional live PV/MPPT uses the documented auxiliary 0200 runtime read only (not tip AABB harvest, not settings 0202). Matching schema sensors stay disabled by default; mppt_error_code is diagnostic and quiet. Samples use 30 s solicit / 60 s TTL; at most one optional read per Q1 cycle, with FC4 RB/F/RH preferred when both are due.",
+    "Offline decode_short_ascii_mppt is a maintainer capture inspector only; it is not the live optional admission path and does not create entities by itself.",
+    "Live PV/MPPT admission is code-complete but not yet live-qualified on site HA (family cutover / Support Archive RECEIPT still pending).",
+    "Quiet fault/diagnostic sensors beyond Q1 flags and the quiet mppt_error_code (Q2 extras) remain deferred.",
     "estimated_ac_load_power is load% × rated VA from F — an estimate, not measured active power; load_percent stays separate. Output frequency is not grid frequency.",
     "Optional BMS currents and battery_power publish only when RH reports BMS current display accuracy=1 (decimals) and F ratings are available for I/P hard-reject bounds; RH=0, unread, expired or failed RH omits those keys. RH=1 is the discriminator (no retail-model gate).",
     "Impossible RB V/SoC/I/P values are hard-rejected. Link-loss (V=0 ∧ SoC=0) may hold last-good BMS for up to 180 s without refreshing sample age; normal RB TTL remains 60 s.",
     "Diagnostic counters: bms_link_loss_count and rb_hard_reject_count are runtime-scoped; reading_hold_pending_count stays 0 (physics confirmation-hold deferred).",
     "BMS current / battery_power path is SmartValue-correlated on one live family member; other members (e.g. Maxinn) are not separately live-proven and only light up if RH=1."
   ],
-  "knowledge_summary": "EyeBond Short-ASCII is a capture-qualified read-only family for the fixed MP/Q1/MD dialect shared by some Anern and Maxinn sites. Optional F/RH/RB add rated values and BMS telemetry with TTL expiry, hard-reject/link-loss hold, and an RH+F gate for currents. Labelled AC-load estimate is separate from measured battery DC power. Live PV and retail-model identity remain out of scope.",
+  "knowledge_summary": "EyeBond Short-ASCII is a capture-qualified read-only family for the fixed MP/Q1/MD dialect shared by some Anern and Maxinn sites. Optional F/RH/RB add rated values and BMS telemetry with TTL expiry, hard-reject/link-loss hold, and an RH+F gate for currents. Optional live PV/MPPT uses aux 0200 with opt-in entities and TTL; offline MPPT decode stays maintainer-only. Labelled AC-load estimate is separate from measured battery DC power. Retail-model identity remains out of scope; site live-qualification for the PV path is still pending.",
   "source_keys": [
     "documentation_vendor_19b4_urtu1920_short_ascii",
     "support_archive_short_ascii_family_anern_maxinn"

docs/generated/INVERTER_MODEL_CATALOG.generated.md

@@ -263,21 +263,23 @@ Runtime descriptors with no specific commercial model record. These are generic
 - Coverage: runtime read_only, cloud not_applicable, vendor map partial
   - Coverage notes:
     - Runtime support is family-only and read-only. Compatible devices appear as EyeBond Short-ASCII family; retail model and serial are not inferred.
-    - Optional RB/F/RH entities are disabled by default and expire on TTL or invalid replies.
-- Summary: EyeBond Short-ASCII is a capture-qualified read-only family for the fixed MP/Q1/MD dialect shared by some Anern and Maxinn sites. Optional F/RH/RB add rated values and BMS telemetry with TTL expiry, hard-reject/link-loss hold, and an RH+F gate for currents. Labelled AC-load estimate is separate from measured battery DC power. Live PV and retail-model identity remain out of scope.
+    - Optional RB/F/RH and aux-0200 MPPT/PV entities are disabled by default and expire on TTL or invalid replies.
+- Summary: EyeBond Short-ASCII is a capture-qualified read-only family for the fixed MP/Q1/MD dialect shared by some Anern and Maxinn sites. Optional F/RH/RB add rated values and BMS telemetry with TTL expiry, hard-reject/link-loss hold, and an RH+F gate for currents. Optional live PV/MPPT uses aux 0200 with opt-in entities and TTL; offline MPPT decode stays maintainer-only. Labelled AC-load estimate is separate from measured battery DC power. Retail-model identity remains out of scope; site live-qualification for the PV path is still pending.
 - Variants:
   - `urtu1920_checksum` — EyeBond Short-ASCII read-only family (URTU1920 checksum dialect)
     - Descriptors: eybond_short_ascii_family
     - Known firmware: —
     - `eybond_short_ascii_family` → surface `eybond_short_ascii_read_only` (driver eybond_short_ascii, variant urtu1920_checksum)
       - Protocol: eybond_short_ascii | Detection: anchors (protocol.protocol_id=EYBOND_SHORT_ASCII; protocol.wire_dialect=urtu1920_checksum; shape.q1_length=51; shape.mp_length=38; shape.md_length=24)
       - Tier: partial | Read-only: yes | Profile: — | Schema: eybond_short_ascii/base.json
-      - Capabilities: no model-specific profile | Telemetry: 34 measurements, 8 binary sensors
+      - Capabilities: no model-specific profile | Telemetry: 43 measurements, 8 binary sensors
 - Known limitations:
   - Family identity only: no retail commercial model (including no Anern SPI-12000W claim) and no inverter serial from MP/Q1/MD.
   - Read-only: no inverter controls; Full Control does not invent settings.
-  - Live PV power is absent; offline MPPT decode is maintainer-only and does not create HA entities.
-  - Quiet fault/diagnostic sensors beyond the existing Q1 flags (Q2) are deferred; mppt_error waits on any future live-PV admission.
+  - Optional live PV/MPPT uses the documented auxiliary 0200 runtime read only (not tip AABB harvest, not settings 0202). Matching schema sensors stay disabled by default; mppt_error_code is diagnostic and quiet. Samples use 30 s solicit / 60 s TTL; at most one optional read per Q1 cycle, with FC4 RB/F/RH preferred when both are due.
+  - Offline decode_short_ascii_mppt is a maintainer capture inspector only; it is not the live optional admission path and does not create entities by itself.
+  - Live PV/MPPT admission is code-complete but not yet live-qualified on site HA (family cutover / Support Archive RECEIPT still pending).
+  - Quiet fault/diagnostic sensors beyond Q1 flags and the quiet mppt_error_code (Q2 extras) remain deferred.
   - estimated_ac_load_power is load% × rated VA from F — an estimate, not measured active power; load_percent stays separate. Output frequency is not grid frequency.
   - Optional BMS currents and battery_power publish only when RH reports BMS current display accuracy=1 (decimals) and F ratings are available for I/P hard-reject bounds; RH=0, unread, expired or failed RH omits those keys. RH=1 is the discriminator (no retail-model gate).
   - Impossible RB V/SoC/I/P values are hard-rejected. Link-loss (V=0 ∧ SoC=0) may hold last-good BMS for up to 180 s without refreshing sample age; normal RB TTL remains 60 s.

docs/maintainer/ADDING_DRIVERS.md

@@ -26,9 +26,9 @@ Integrity or boundary failures close the session. In particular, a valid
 EyeBond frame with transaction ID `0xAABB` can overlap the auxiliary grammar:
 neither a valid checksum nor an absent waiter resolves that ambiguity. The
 current foundation refuses such a frame; it does **not** guarantee auxiliary
-availability for every possible payload. Catalog `known_limitations` / retail
-model claims remain separate work (see documentation pass after admission).
-Live-qualify with Support Archive evidence before treating PV as device-proven.
+availability for every possible payload. Catalog `known_limitations` record the
+opt-in aux-0200 PV path and still forbid retail-model claims. Live-qualify with
+Support Archive evidence before treating PV as device-proven.
 Normal connections keep their existing grammar until an explicit auxiliary read
 is requested.
 
@@ -116,15 +116,16 @@ RH=1.
 `short_ascii_optional` owns per-runtime samples, scoped to the transport and
 inverter binding. The hub discards this state on recovery; samples are never
 persisted as identity. Each successful Q1 cycle performs at most one optional
-request (4-second bound), oldest due group first: RB every 30 seconds with a
-60-second TTL, F and RH every 900 seconds with a 900-second TTL, and optional
-MPPT (`0200` aux) every 30 seconds with a 60-second TTL. Freshness is
-checked after the await. Invalid/timeout replies clear that group immediately,
-and FULL-result omission removes it from the hub. A failed or cancelled
-mandatory cycle, lost connection, changed binding or clock rollback clears all
-samples. Only optional failures alongside a successful Q1 count towards the
-shared four-strike command cache; the existing re-check action re-enables
-requests.
+request (4-second bound): RB every 30 seconds with a 60-second TTL, F and RH
+every 900 seconds with a 900-second TTL, and optional MPPT (`0200` aux) every
+30 seconds with a 60-second TTL. When both FC4 (RB/F/RH) and MPPT are due,
+prefer FC4 (oldest due within that set); MPPT runs only when it is the sole due
+sample. Freshness is checked after the await. Invalid/timeout replies clear
+that group immediately, and FULL-result omission removes it from the hub. A
+failed or cancelled mandatory cycle, lost connection, changed binding or clock
+rollback clears all samples. Only optional failures alongside a successful Q1
+count towards the shared four-strike command cache; the existing re-check
+action re-enables requests.
 
 An RB reply with zero voltage and zero SOC explicitly withdraws **all** BMS
 measurements/path flags, including nonzero trailing fields seen in the capture.

docs/user/RUNTIME_AND_INVERTER.md

@@ -121,16 +121,23 @@ then expire. That hold does not prove the physical battery is disconnected.
 Diagnostic counters can show how often link-loss and hard rejects occurred;
 they reset when Home Assistant reloads the entry.
 
+Some devices can also answer an optional auxiliary **PV / MPPT** read
+(documented `0200` runtime query). Matching entities such as PV voltage/power
+and MPPT diagnostics stay disabled by default — enable them only if you need
+them. Those samples refresh on a similar ~30 s cadence with a ~60 s expiry, and
+share the one-extra-request-per-poll budget with BMS/rated reads (BMS and rated
+queries take priority when both are due). This is not the offline maintainer
+MPPT frame inspector, and it is not a retail Anern model claim.
+
 After four failed optional requests while basic telemetry still responds,
 that request is skipped. Use **Re-check supported commands** to try it again,
 for example after connecting a BMS. Missing optional data does not prevent
 basic inverter monitoring.
 
-This profile does not provide live PV power, grid frequency or inverter
-controls. Selecting **Full Control** does not add undocumented settings. If
-readings are missing or implausible, create a Support Archive for review; it
-can include the optional raw replies. Do not select a similar retail model by
-guesswork.
+This profile does not provide grid frequency or inverter controls. Selecting
+**Full Control** does not add undocumented settings. If readings are missing or
+implausible, create a Support Archive for review; it can include the optional
+raw replies. Do not select a similar retail model by guesswork.
 
 ## Control mode
 

docs/user/SUPPORT_ARCHIVE.md

@@ -68,10 +68,12 @@ Depending on what is available for this entry, one archive can include:
 For the **EyeBond Short-ASCII family** in the test code, creating an archive
 also requests the basic `MP/Q1/MD` replies and optional `F/RH/RB` replies. It
 keeps the returned bytes, including malformed responses, and records failed
-requests. It does not enable live PV polling or inverter controls. This is a
-new diagnostic snapshot, not a continuous recording: if a reading jumps, also
-report when it happened and which sensor was affected. A later archive may no
-longer contain the response that caused that jump.
+requests. Archive creation does not solicit the optional auxiliary PV/MPPT
+(`0200`) read, force-enable opt-in PV entities, or enable inverter controls —
+those remain a separate runtime path. This is a new diagnostic snapshot, not a
+continuous recording: if a reading jumps, also report when it happened and
+which sensor was affected. A later archive may no longer contain the response
+that caused that jump.
 
 The archive helps answer questions such as: