ADR-0009: Interface Event Consolidation¶

Status¶

Completed (2025-12-26)

• CallbackStateChangedEvent added
• Legacy CALLBACK event removed from enum and code
• Legacy PROXY event removed from enum and code
• FetchDataFailedEvent added (replaces FETCH_DATA)
• PingPongMismatchEvent added (replaces PENDING_PONG and UNKNOWN_PONG)
• DeviceAvailabilityChangedEvent added (new)
• Legacy InterfaceEvent dataclass removed
• Legacy InterfaceEventType enum removed
• Legacy publish_interface_event() method removed
• Home Assistant integration migrated (external dependency)

Context¶

aiohomematic had two parallel event systems for connection/interface status:

1. Legacy System: InterfaceEventType published via HomematicEvent with EventType.INTERFACE
2. Modern System: State-based events (CentralStateChangedEvent, ClientStateChangedEvent, ConnectionStateChangedEvent)

This created redundancy and potential confusion for consumers.

Legacy InterfaceEventType Events¶

Published via publish_interface_event() → HomematicEvent(EventType.INTERFACE):

Modern State Events¶

Published directly via EventBus.publish():

Analysis¶

Overlap Matrix¶

Detailed Comparison¶

PROXY vs ClientStateChangedEvent¶

PROXY:

• Published when device availability changes
• Data: {AVAILABLE: bool}

ClientStateChangedEvent:

• Published on state transitions
• Data: interface_id, old_state, new_state

Mapping: | ClientState | PROXY equivalent | | -------------- | ----------------------- | | CONNECTED | {AVAILABLE: true} | | DISCONNECTED | {AVAILABLE: false} | | FAILED | {AVAILABLE: false} |

Conclusion: PROXY can be derived from ClientStateChangedEvent.

CALLBACK vs CallbackStateChangedEvent¶

Difference: CALLBACK provides SECONDS_SINCE_LAST_EVENT which ConnectionStateChangedEvent does not.

Solution: Created CallbackStateChangedEvent to preserve this diagnostic data.

PENDING_PONG / UNKNOWN_PONG¶

These have no modern equivalent. They provide unique diagnostic information about PING/PONG health.

Solution: Created PingPongMismatchEvent to replace both.

Decision¶

Consolidate all interface events into typed event classes, removing the legacy InterfaceEvent system entirely.

Phase 1: Document and Deprecate (Non-Breaking) ✅ COMPLETE¶

Marked legacy events as deprecated in documentation and added new typed events.

Phase 2: Migration Path ✅ COMPLETE¶

Provided migration guidance for each legacy event.

Phase 3: Consolidation (Breaking Change) ✅ COMPLETE¶

Removed entire legacy InterfaceEvent system (dataclass, enum, publish method).

Migration Guide¶

PROXY Migration¶

Before:

# Legacy: Listen to PROXY event
if event_data[EventKey.TYPE] == InterfaceEventType.PROXY:
    available = event_data[EventKey.DATA][EventKey.AVAILABLE]

After:

# Modern: Use ClientStateChangedEvent
def on_client_state_changed(*, event: ClientStateChangedEvent):
    available = event.new_state == ClientState.CONNECTED

event_bus.subscribe(
    event_type=ClientStateChangedEvent,
    event_key=interface_id,
    handler=on_client_state_changed,
)

CALLBACK Migration¶

Before:

# Legacy: CALLBACK event with seconds info
if event_data[EventKey.TYPE] == InterfaceEventType.CALLBACK:
    available = event_data[EventKey.DATA][EventKey.AVAILABLE]
    seconds = event_data[EventKey.DATA].get(EventKey.SECONDS_SINCE_LAST_EVENT)

After:

# Modern: CallbackStateChangedEvent preserves all data
def on_callback_changed(*, event: CallbackStateChangedEvent):
    alive = event.alive
    seconds = event.seconds_since_last_event

event_bus.subscribe(
    event_type=CallbackStateChangedEvent,
    event_key=interface_id,
    handler=on_callback_changed,
)

FETCH_DATA Migration¶

After:

# Modern: FetchDataFailedEvent
def on_fetch_failed(*, event: FetchDataFailedEvent):
    _LOGGER.warning("Data fetch failed for %s", event.interface_id)

event_bus.subscribe(
    event_type=FetchDataFailedEvent,
    handler=on_fetch_failed,
)

PENDING_PONG / UNKNOWN_PONG Migration¶

After:

# Modern: PingPongMismatchEvent
def on_ping_pong_mismatch(*, event: PingPongMismatchEvent):
    if event.mismatch_type == "pending_pong":
        _LOGGER.warning("PING without PONG for %s", event.interface_id)
    else:
        _LOGGER.warning("Unexpected PONG for %s", event.interface_id)

event_bus.subscribe(
    event_type=PingPongMismatchEvent,
    handler=on_ping_pong_mismatch,
)

Summary Table¶

Note: The entire legacy InterfaceEvent system (dataclass, enum, publish method) has been removed.

Consequences¶

Positive¶

✅ Cleaner API: Type-safe events with proper dataclasses ✅ Better IDE Support: Autocomplete and type checking ✅ Reduced Duplication: Single event system ✅ More Discoverable: Events are explicit classes, not enum values ✅ Consistent Patterns: All events follow same subscribe API

Negative¶

⚠️ Breaking Change: Existing consumers must update ⚠️ Migration Effort: Home Assistant integration needs updates ⚠️ Temporary Documentation: Both systems documented during transition

Neutral¶

ℹ️ Home Assistant Dependency: Integration must be updated separately ℹ️ Backward Compatibility: Not maintained for internal event system

Implementation¶

Status: ✅ Completed in version 2025.12.26

New Event Classes¶

aiohomematic/central/events/bus.py:

• CallbackStateChangedEvent - Callback alive/dead with seconds info
• FetchDataFailedEvent - Data fetch failures
• PingPongMismatchEvent - PING/PONG diagnostic events
• DeviceAvailabilityChangedEvent - Device availability changes

Removed¶

Legacy components completely removed:

• InterfaceEvent dataclass
• InterfaceEventType enum
• publish_interface_event() method

Updated¶

Event publishers updated to use new typed events:

• Callback monitoring → CallbackStateChangedEvent
• Device availability → DeviceAvailabilityChangedEvent
• Data fetch failures → FetchDataFailedEvent
• PING/PONG monitoring → PingPongMismatchEvent

References¶

• Event Reference - Complete event catalog
• EventBus Architecture - Event system overview
• ADR-0006: Event System Priorities - Event batching strategy

Created: 2025-12-26 Author: Architecture Review