External Integrations

The external integrations layer handles communication with smart home platforms - SmartThings, Yale, Hive, and Daikin. It provides a unified abstraction that hides platform differences from the rest of the codebase.

Overview

Four external platforms are integrated:

Platform	Devices	Integration Type
SmartThings Enterprise	Hubs, sensors, multichannel meters	REST API + Webhooks
Yale Access	Smart locks, doorbells, alarm hub	REST API + Webhooks
Hive	Thermostats	REST API
Daikin Onecta	Daikin Altherma heat pumps (space heating + hot water)	REST API (OAuth 2.0)

┌─────────────────────────────────────────────────────────────────────┐
│                    Smart Device Integration                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    Application Layer                         │   │
│  │                                                              │   │
│  │     execute_capability(device_id, Lock)                      │   │
│  │     get_device_state(device_id)                              │   │
│  └──────────────────────────┬───────────────────────────────────┘   │
│                             │                                       │
│                             ▼                                       │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    SmartClient Trait                         │   │
│  │                                                              │   │
│  │     categorize_capability() → Platform routing               │   │
│  │     resolve_external_id() → Platform-specific ID lookup      │   │
│  └──────────────────────────┬───────────────────────────────────┘   │
│                             │                                       │
│              ┌──────────────┼──────────────┐                       │
│              ▼              ▼              ▼                       │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│  │  SmartThings  │ │     Yale      │ │     Hive      │ │    Daikin     │ │
│  │    Client     │ │    Client     │ │    Client     │ │    Client     │ │
│  └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Key Concepts

Device Resolution

During IT setup, internal devices are matched to external platform devices:

1. Name Matching - Fuzzy matching by device label
2. Capability Verification - Confirm device has expected capabilities
3. Type Validation - Ensure device model matches expected type
4. External ID Storage - Store SmartThings ID, Yale ID in external_device_ids table

Capability Routing

Each capability is routed to the appropriate platform:

match capability {
    Lock | Unlock | SetPinCode | ... => Platform::Yale,
    SetThermostatMode | SetHeatingSetpoint | ... => Platform::Hive,
    SetDaikinClimateOnOff | SetDaikinRoomTemperature | ... => Platform::Daikin,
    _ => Platform::SmartThings,
}

State Refresh

Device states are fetched from external APIs with a capability presence hierarchy - the system checks for required capabilities on each device type before attempting to fetch state.

Documentation

• Smart Device Abstraction - SmartClient trait and capability system
• Device Resolution - Matching internal devices to external IDs
• Webhook Handling - Signature verification and event processing

Integration Patterns

Real-Time Updates

Webhooks provide real-time device events:

1. SmartThings/Yale send webhook to bf_notify
2. bf_notify verifies signature and queues event
3. Event routed to appropriate property DO
4. DO processes event and broadcasts to connected clients

Mock Mode

For development and testing, a mock layer simulates all external platforms:

• Compile-time excluded from production (#[cfg(feature = "mock")])
• State persistence in D1 for consistency
• Realistic state transitions
• No external API calls required