HomeKit Device Integration in Mobile IoT App

HomeKit Device Integration into Mobile IoT App

HomeKit — closed ecosystem, but in 2019 Apple opened HAP (HomeKit Accessory Protocol) and specifications. For mobile app developer this means working with HomeKit.framework on iOS, watchOS and tvOS. Without this — no way: third-party apps control HomeKit devices only via official API, no workarounds.

HomeKit API: Structure and Limitations

Hierarchy: HMHomeManager → HMHome → HMRoom → HMAccessory → HMService → HMCharacteristic. Device (Accessory) provides services (Service) — e.g., smart bulb has HMServiceTypeLightbulb service. Service contains characteristics (Characteristic) — HMCharacteristicTypePowerState, HMCharacteristicTypeBrightness, HMCharacteristicTypeHue.

import HomeKit

class HomeKitManager: NSObject, HMHomeManagerDelegate {
    private let homeManager = HMHomeManager()

    override init() {
        super.init()
        homeManager.delegate = self
    }

    func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
        guard let primaryHome = manager.primaryHome else { return }
        fetchLightbulbs(in: primaryHome)
    }

    private func fetchLightbulbs(in home: HMHome) {
        let lightbulbs = home.accessories.flatMap { $0.services }
            .filter { $0.serviceType == HMServiceTypeLightbulb }

        for service in lightbulbs {
            if let brightness = service.characteristics.first(where: {
                $0.characteristicType == HMCharacteristicTypeBrightness
            }) {
                brightness.readValue { error in
                    if let error { print("Read error: \(error)") }
                    print("Brightness: \(brightness.value ?? "nil")")
                }
            }
        }
    }
}

Writing Values and Asynchronicity

writeValue(_:completionHandler:) — asynchronous, returns error via callback. iOS 16+ supports async/await via wrapper or directly via HMCharacteristic.writeValue:

func setLightOn(_ isOn: Bool, characteristic: HMCharacteristic) async throws {
    try await characteristic.writeValue(isOn)
}

Command latency via HomeKit — 100-500 ms for local devices, up to 2 seconds via remote (through Apple TV or HomePod as hub). If device behind hub offline, get HMError.accessoryNotReachable (code 6).

State Change Notifications

HAP supports push notifications from devices via enableNotification(true). App subscribes to characteristic changes:

class AccessoryDelegate: NSObject, HMAccessoryDelegate {
    func accessory(_ accessory: HMAccessory,
                   service: HMService,
                   didUpdateValueFor characteristic: HMCharacteristic) {
        if characteristic.characteristicType == HMCharacteristicTypeMotionDetected {
            let motionDetected = characteristic.value as? Bool ?? false
            NotificationCenter.default.post(
                name: .motionDetected,
                object: motionDetected
            )
        }
    }
}

One nuance: notifications arrive only while app in foreground or has background execution permission. For background events use HMEventTrigger — HomeKit automation executed without app participation.

Automation and Triggers

HMEventTrigger allows creating rules directly from app:

let motionCharacteristic = // HMCharacteristic of type MotionDetected
let triggerEvent = HMCharacteristicEvent(
    characteristic: motionCharacteristic,
    triggerValue: true
)

let trigger = HMEventTrigger(
    name: "Motion Detected",
    events: [triggerEvent],
    end: nil,
    recurrences: nil,
    executionConditions: nil
)

let lightCharacteristic = // HMCharacteristic of type PowerState
let action = HMCharacteristicWriteAction(
    characteristic: lightCharacteristic,
    targetValue: true
)

let actionSet = HMActionSet(name: "Turn on light")
// Add action to actionSet, then attach to trigger
home.addTrigger(trigger) { error in
    if let error { print("Trigger error: \(error)") }
}

Triggers execute on Hub (HomePod, Apple TV) and run even when app closed.

Entitlements and App Store

HomeKit requires entitlement com.apple.developer.homekit and NSHomeKitUsageDescription key in Info.plist. Without NSHomeKitUsageDescription app crashes on first HMHomeManager access without warning — common setup mistake.

Testing — only on real device. Simulator doesn't support HomeKit physical accessories; for development use HomeKit Accessory Simulator from Additional Tools for Xcode.

HomeKit integration into existing iOS app with devices for testing takes 2-3 weeks: rights setup, device management layer, automation, background event handling. Cost calculated individually.