RE: dimmer fade/transition — IPBox → UDP wire vs EEPROM Soft AAN/UIT

[markminnoye]

Why

Home Assistant lets users pass a transition parameter (fade duration in seconds) on light.turn_on, light.turn_off, and light.toggle — in automations, scripts, scenes, and dashboard actions. Today the companion ignores this: dimmer commands go out as absolute S/C setpoints or native T toggle, with no fade duration from HA.

That creates a gap between what users expect from HA lights and what IPBuilding dimmers do physically:

• Slider / turn_off can feel abrupt or, conversely, use the module’s fixed EEPROM Soft AAN/UIT fade — not the duration the user chose in HA.
• Automations that specify transition: 5 have no effect on the wire.
• We need to know how fade is really implemented (UDP field vs EEPROM-only vs IPBox-side stepping) before we can support HA transition correctly in the companion/gateway.

This RE is the prerequisite for a product feature: users should be able to set fade time via HA’s standard transition parameter and have dimmers behave accordingly.

Goal

End state: HA transition on IPBuilding dimmer entities is honoured by the companion (and gateway if needed) — e.g. light.turn_on / light.turn_off with transition: 3 produces a ~3 second fade where possible.

This issue: determine how to implement that:

1. Wire-native — if IPBox sends a per-command fade duration on UDP/1001 we have not decoded, document and encode it in gateway/payloads/dimmer.py.
2. EEPROM-only — if fade speed is only module EEPROM (Soft AAN/UIT, Snelheid msec), document limits and decide whether HA transition maps to EEPROM (not per-command) or must be emulated.
3. Emulated — if neither applies, implement stepped S frames in the companion over the requested duration (separate implementation issue).

Context (known today)

• IP0300PoE dimmers have EEPROM-configured fade (diagnose software):
  • Soft AAN % (default 15%) — ramp-up start level
  • Soft UIT % (default 70%) — soft-off threshold before ramp to 0%
  • Snelheid (msec) — transition speed
• Documented in resources_and_docs/IPBUILDING_KNOWLEDGE.md §12.3.
• Hub commands (S…1030, C…001030) set the target level; physical fade may follow EEPROM rules. Toggle (T…991000) uses a different path (last-level memory).
• Companion/gateway northbound API does not map HA transition to any UDP/1001 frame today.

Open question

Does the IPBox ever send a per-command fade duration on UDP/1001 that we have not decoded? Or does it only rely on EEPROM + absolute S/C setpoints (with HA/client doing stepped fades)?

resources_and_docs/reference/IPBOX_REST_API_TEST_CALLS.md notes no dedicated delay/transition REST endpoint on :30200 — but the IPBox may still encode fade on the field bus in a way we have not captured.

Investigation plan

1. IPBox stimulus + mirror capture on dimmer port (7←12, host 10.10.1.40 and udp port 1001):
   • REST action DIM/OFF with same channel at different levels
   • WebConfig dimmer actions if they differ from REST
   • Compare wire when EEPROM Snelheid / Soft AAN/UIT are changed (before/after EEPROM upload)
2. Correlate REST :30200 POST /api/v1/action/action payloads with UDP frames (timestamps).
3. Check legacy HA-IPBuilding — does it send transition to IPBox REST, and if so, what does IPBox do on the wire?
4. Document verdict and recommended implementation path for HA transition support.

Acceptance

• Short evidence note under resources_and_docs/evidence/ with pcap/HAR references
• Update IPBUILDING_KNOWLEDGE.md §6.6 / §12.3 and fieldbus matrix if a wire field is found
• Clear recommendation for companion/gateway: wire encoder vs EEPROM limits vs emulated stepped DIM — unblocks a follow-up feature issue to implement HA transition in ha-ipbuilding-gateway

Related

• Companion dimmer toggle fix (always TOGGLE on light.toggle) — separate; does not block this RE
• Fieldbus matrix: resources_and_docs/2026-05-17_ipbuilding_fieldbus_capability_matrix.md