Hubitat Hub Integration

• Protocol: HTTP REST API using Makers API
• Authentication: Access token with App ID
• Communication: Local network for minimal latency
• Event Handling: Webhook-based real-time device updates

Flair HVAC Integration

• Protocol: OAuth 2.0 REST API with automatic token refresh
• Components: Structures, rooms, HVAC units, sensor bridges
• Capabilities: Mini-split control, room temperature monitoring

Weather Service Integration (currently disabled)

• Provider: WeatherAPI.com with API key authentication
• Data Points: Temperature, humidity, conditions, feels-like temperature
• Caching: Local cache with 30-minute refresh intervals

Device Management System

Most of my devices are registered in the Hubitat platform, which provides a local API for device management. I have also been evaluating Home Assistant as a potential alternative for future integrations but have not yet migrated. The core requirements for the device management system include:

• Unified Device Model: Abstract representation of devices across platforms
• Capability-Based Architecture: Devices expose capabilities like switches, sensors, and thermostats
• Room Organization: Devices are grouped by rooms with hierarchical structure

Device states are synchronized into local cache storage, providing fast API responses while maintaining eventual consistency with upstream platforms.

Abstract Device Interface

All devices implement a common interface to ensure consistent interaction across platforms:

type Device interface {
  ID() string
	Name() string
	Room() room.Room
	MatchesName(string) bool
	Capabilities() []CapabilityName
	As(CapabilityName) Capability
}

This interface is implemented for each platform / device type once and reused across the system. It allows for flexible device management and interaction without needing to know the underlying platform details.

Capability-Based Controls

Devices expose capabilities that define their functionality, allowing for flexible control and automation. For instance:

• Switch capabilities for on/off control
• Sensor capabilities for environmental data
• Thermostat capabilities for HVAC control
• Button capabilities for trigger events

type Capability interface {
	Name() CapabilityName
	IsStateful() bool
	CurrentState() CapabilityState
	Merge(Capability)
	SendCommand(string) error
}

Room Organization

type Room struct {
	Name    string   `json:"name,omitempty"`

}

- Hierarchical room structure with groups and aliases
- Device-to-room mapping for contextual automation
- Room-based filtering and bulk operations functionality

### Automation Engine

#### Event Processing

The gateway now runs a fully async pipeline. HTTP ingestion returns immediately so device platforms are never blocked waiting on rule evaluation:

1. HTTP ingestion returns 202 immediately (under 50ms)
2. Deduplication window (5 seconds) prevents duplicate event processing
3. Events are persisted to SQLite before processing, so no events are lost on failure
4. Worker pool processes events in parallel (currently 10 workers)
5. Enrichment stage attaches device metadata, room context, and previous state
6. Rule evaluation and action execution across relevant platforms


#### Rules Engine

Rules started as Go handlers and are moving toward declarative YAML definitions. Both coexist in the current system, with the Go approach still in place for backward compatibility.

The Go handler interface:

```go
type Rule struct {
	Name       string
	Aliases    []string
	HandleFunc Handler
}

type Handler func(Event, room.List, device.List) (handled bool, err error)

At the moment, all events flow through all rule handlers so they must handle their own filtering. The goal is smarter routing by device or event type, along with hot-reload so rules can be updated without a deployment.

YAML rule definitions are now available for basic conditions and actions, with validation enforced at load time.

Scene Management

Scenes follow a similar structure to rules but are predefined automation scenarios that coordinate multiple devices across platforms. Currently they’re defined in Go:

func pbChillHandler(_ room.List, curDevices device.List) (bool, error) {
	tableLamp := curDevices.GetDevice(registry.PrimaryBedroomTableLamp)
	ceilingLight := curDevices.GetDevice(registry.PrimaryBedroomCeilingLight)

	switch {
	case timeframe.CurrentDay().IsWeekday() && timeframe.Night().CurTimeInFrame():
		if err := tableLamp.As(device.SwitchName).SendCommand(device.OnCommand); err != nil {
			return false, err
		}
		if err := ceilingLight.As(device.SwitchName).SendCommand(device.OffCommand); err != nil {
			return false, err
		}
		return true, nil
	default:
		return false, nil
	}
}

This works but is a bit clunky. The goal is to get to declarative YAML definitions that can be created and edited without touching Go code:

scenes:
  PBRChill:
    devices:
      - room: "primary_bedroom"
        type: "switch"
        action: "dim_to_30"
      - room: "primary_bedroom"
        type: "hvac"
        action: "cool_to_68"
    window: "weekday night"

YAML scene definitions are planned alongside the dashboard UI.