[Enhancement]: use /api/groups link data for richer scene status (any-on / all-on / matches-target)

[shbatm]

Idea

The eisy exposes an /api/groups endpoint that expands what /rest/nodes <group> carries. It lists each group's controllers and, per controller, the full member link records — including the link's target parameters (on-level/ramp the scene drives each member to), not just membership.

Captured shape (anonymised structure):

{ successful, data: { groups: [ { id, ctl: [ { id, links: [ { linkdef, node, params, type } ] } ] } ] } }

(93 groups in the sample capture.) links[].params carries the per-member target state the scene sets — which /rest/nodes does not provide.

Why it's useful

Today Group.group_all_on / group_any_on are coarse aggregates over member ST (non-zero = on). With link target data we could offer a much better scene status:

• any-on / all-on (as today, but membership sourced more reliably),
• scene_matches_target — every member's live ST equals the level the scene's link would set → "the scene is actually active as programmed", vs. partially/manually diverged.

That matches-target signal is what consumers really want for a scene switch's is_on and for follower/"chaser" automations, instead of inferring from a single representative member.

Scope / notes

• Strictly additive; load /api/groups alongside the existing /rest/nodes group parse, attach link/target data to GroupRecord, expose a derived scene_matches_target (computed-on-access like the current aggregates).
• Pairs naturally with the member-change re-emit in [Bug]: Group/scene status never updates — no member-change notification (pyisy-3.x regression) #173 / PR fix(events): re-emit member changes as group-addressed events (pyisy-3.x parity) #172 (that delivers the notification; this enriches the value).
• Capture for reference: ~/src/.devcontainer_shared/home-assistant-core/isy994_stashed/eisy_api_data/api_groups.json.

Filed as a separate enhancement (not blocking #173).

[shbatm]

First-slice design — validated against capture, guardrails framed (HOLD until #173/#172 finalized)

Validated the target data is derivable. Decoded radio scene 8499 (an LR-KP "Fan Low" 4-button scene) from the capture:

member	scene-link target OL
40 FD 8 4 (the "on" button)	100 (non-OFF)
40 FD 8 3 / 40 FD 8 5 / 40 FD 8 6	0 (OFF)

Today this scene's group_any_on is always True (a KPL always has some button lit) and group_all_on is structurally impossible (3 buttons are designed off). The fix: aggregate over the target-non-OFF subset only — any_on = any on-target member non-OFF; all_on = all on-target members non-OFF. For 8499 that collapses to "is 40 FD 8 4 on", which is correct. (Single-member scenes like 19359 collapse to that one member — would even make a stale-check viable again.)

This is both a first slice of this issue and a partial resolution of hacs-udi-iox#85 (radio scenes report correctly without per-button sensor entities).

Guardrails for the first implementation:

1. Targets only from type:"native" responder links, from the OL param (UOM-51 %): >0 ⇒ non-OFF target, ==0 ⇒ OFF target. Ignore type:"default" (controller-self, no params) and other/unknown link types. A controller that lights itself appears as both default + native OL=… for the same node — use the native one.
2. All-or-nothing per group. Target-aware aggregation engages only when every stateful, non-stateless member resolves to a known native+OL target. Any unresolved member, or /api/groups absent (older firmware), ⇒ that whole group falls back to today's exact semantics. No partial application; never regress.
3. Stateless-member skip (INSTEON_STATELESS_NODEDEFID) still applies first, on top.
4. Empty on-set (all-OFF scene) ⇒ any_on=False, all_on=False (mirror existing saw_stateful guard).
5. Membership source stays /rest/nodes; /api/groups only enriches targets. Best-effort load; fetch failure non-fatal.
6. Exact-level match (scene_matches_target) deferred — this slice does only the OFF / non-OFF bit.

Sketch: paths.py add /api/groups; client.py fetch+parse → GroupRecord.member_targets: dict[str,int]; runtime/group.py target-aware any_on/all_on with the per-group fallback; fixture-driven test_groups.py. Separate branch off main, composes with #172 (that delivers the change notification; this makes the value correct).

Held until #172 (the member-change re-emit) is finalized in review.

[shbatm]

Guardrail refinement — type:"cmd" (command-only / mixed scenes)

A command-only scene emits a third link type — no OL target, the intent is the cmd:

{ "id": "26134", "ctl": [ { "id": "26134",
  "links": [ { "type": "cmd", "node": "41 E1 58 1", "cmd": "DFON", "params": [] } ] } ] }

Refine target resolution (was native-only) to also resolve cmd links by the command's steady on/off intent:

• type:"native" → target from OL (>0 non-OFF, 0 OFF) — unchanged
• type:"cmd" → from cmd: DON/DFON ⇒ non-OFF (DON with explicit 0 param ⇒ OFF, edge); DOF/DFOF ⇒ OFF; BRT/DIM/FDUP/FDDOWN/FDSTOP/other ⇒ unknown → per-group fallback (guardrail Bump mypy from 0.991 to 1.0.0 #2)
• type:"default" (controller-self, no params) → no target; node's other link governs if present
• other/unknown type ⇒ unknown → per-group fallback

26134 then resolves: on-set {41 E1 58 1} (DFON ⇒ non-OFF); scene on iff that node non-OFF — principled rather than coarse-fallback, and extends to mixed cmd/native scenes. Still conservative: only the 4 steady on/off verbs map; dim/fade/brighten stay unknown → safe per-group fallback. (Note: cmd links are fire-and-forget, so the deferred scene_matches_target stays murkier for them — but the OFF/non-OFF on-set bit this slice needs is well-defined from the verb.)

Guardrail set otherwise unchanged. Still build-held until #172 finalized.

[shbatm]

Guardrail refinement — non-load / config-only cmd links (Tim added a BL-only scene)

{ "id":"26134","ctl":[{"id":"26134","links":[
  {"type":"cmd","node":"41 E1 58 1","cmd":"BL",
   "params":[{"type":"val","id":"","val":{"uom":25,"prec":0,"value":124}}]}]}]}

BL sets the keypad backlight — touches a setting, not the load's on/off. Treating it as "other → unknown → fallback" is wrong (would fall a backlight-only scene back to a meaningless member-ST aggregate). Sharper line — does the link affect the load's on/off state?

cmd link classification (native OL unchanged):

1. Determinate state target — DON/DFON ⇒ non-OFF, DOF/DFOF ⇒ OFF → on-set.
2. Load-affecting, indeterminate — BRT/DIM/FDUP/FDDOWN/FDSTOP → ambiguous → per-group fallback (no resting target; legacy ST is least-wrong).
3. Non-load (config/diagnostic) — BL/BEEP/QUERY/WDU/… → resolved as "no target": excluded from the on-set, does NOT trigger fallback.

Unrecognized cmd, or unknown link type ⇒ ambiguous → per-group fallback (never silently exclude a possibly-stateful verb).

Effect: 26134 (BL-only) → empty on-set → guardrail #4 ⇒ any_on=False, all_on=False — correct (a backlight scene is never an "on" load) and no meaningless legacy fallback. Mixed DON+BL scene → on-set = the DON member only. Nothing regresses.

Possible follow-on (note, not this slice): expose has_state_target: bool so a consumer can avoid modeling a config-only "scene" as a switch — consumer-policy nicety.

Buckets need three small explicit sets (on/off, ramp/fade, non-load) + unknown→fallback. Still build-held until #172 finalized.

[shbatm]

Ground-truth validation

The IoX admin console displays the BL-only scene 26134 as OFF. That confirms the bucket-3 / guardrail-#4 outcome (empty on-set ⇒ any_on=False, all_on=False ⇒ OFF) is the controller-consistent answer, not just a safe default — and it argues against routing non-load scenes through the legacy ST fallback (which could disagree with the console).

Design north star for #174: where link target semantics are ambiguous, match the admin console's scene status. Known anchor: a non-load (config/diagnostic) scene reads OFF. Worth capturing the console's reported status alongside future /api/groups captures so the rules can be checked against it case-by-case.

[shbatm]

SUPERSEDES the cmd-verb bucketing — all cmd links are excluded

Correction (Tim): a cmd link is fire-once; the target node is not a state-maintained responder of the scene and there is no "off" actuation, so scene status cannot derive from any cmd link — DON included. The controller maintains scene state only from native responder links, which is exactly what the admin console reflects (BL-only scene = OFF; a DON-cmd-only scene is OFF too — fire-only, nothing tracked).

Consolidated rule (replaces the earlier 3-way cmd split):

• on-set = members reached by a native responder link with OL > 0 (native OL=0 → excluded).
• every cmd link, any verb → excluded from the on-set — not in the set (adds no all_on constraint), and never triggers fallback (cleanly resolved as non-contributing).
• default (controller-self) → no target; node's native link governs if present.
• Sole fallback trigger: unknown link type, or a native link whose OL can't be parsed → per-group fallback (guardrail Bump mypy from 0.991 to 1.0.0 #2).
• All-cmd / no-native scene → empty on-set → any_on=False/all_on=False → OFF (matches admin console).

No cmd-verb table needed → materially simpler implementation: link-type check + native OL only.

Spun-off consumer question (not this issue)

A group with no state-maintained native responder (purely fire-and-forget) has no meaningful on/off → hacs-udi-iox should model it as a button (press = activate), not a switch left stuck "on" after one fire. pyisyox capability side: expose has_state_target (any native-OL responder member present); switch-vs-button is consumer policy. Tracking separately on hacs-udi-iox.

Still build-held until #172 finalized.

[shbatm]

CONSOLIDATED SPEC v2 — supersedes all prior comments in this issue

Authoritative IoX link-type semantics (Tim, from UDI reference):

type	behavior
native	direct controller→responder (Insteon link / Z-Wave assoc). Carries OL target.
default	ISY forwards whatever command the controller sent to the responder (scene DON ⇒ member DON, DOF ⇒ DOF). State-tracked responder.
cmd	like default, except on the controller's On the ISY sends the link's specified cmd to the responder.
ignore	no link — not a member.

Verified: firing a default/cmd scene, the admin console tracks the member nodes' ST. So:

Value vs. scope

• Value (on/off) always = the member nodes' live ST (computed on access, exactly as the legacy aggregate / admin console do). The link's OL is not the live value — it's only the native target level used to read intent.
• Link data only scopes the on-set + per-member intent:
  • native: OL>0 ⇒ intent ON (on-set, watch ST); OL=0 ⇒ intent OFF (exclude from on-set).
  • default: state-tracked responder, follows the scene ⇒ intent ON (on-set, watch ST). (Controller node listing itself via a default link is a normal responder — not "no target".)
  • cmd — 3 buckets by the substituted cmd: DON/DFON ⇒ intent ON (on-set, watch ST); DOF/DFOF ⇒ intent OFF (exclude); anything else (SETST, BL, BEEP, BRT/DIM/FD*, …) ⇒ state of that child is discarded for the ON calc (exclude that child; not a per-group fallback).
  • ignore: not a member.
  • unknown link type / unparseable native OL ⇒ unresolved ⇒ per-group fallback (legacy all-member ST).
• any_on = any on-set member ST non-OFF; all_on = all on-set members ST non-OFF. Stateless-member skip still applies first. Empty on-set (all cmd-off / cmd-other / ignore) ⇒ any_on=all_on=False ⇒ OFF (matches console for fire/config-only scenes).

Sanity checks

• Radio KPL scene 8499: members are native I_RELAY, one OL=100 + three OL=0 ⇒ on-set = the OL=100 button ⇒ correct.
• Scene 46389: default members (ZW003_1,ZW003_143,n004_38,n004_39) ⇒ on-set, watch ST; cmd SETST on n004_38 ⇒ that child discarded; cmd DON on ZW003_1 ⇒ on-set. Matches "console tracks those nodes' ST".

Implementation: link-type + native OL + a small cmd on/off verb set ({DON,DFON}/{DOF,DFOF}); everything else cmd ⇒ discard child. Membership/ST watch via #172. Still build-held until #172 finalized.