Your home as a live 3D model in the Mac menu bar and on iPhone — lights and ACs via Smart Life, Home Assistant, Philips Hue and Apple Home.
import Foundation
/// A Home Assistant server on the local network (or anywhere it is reachable), through its
/// REST API with a long-lived access token. Lights and switches become lamps, `climate`
/// entities become air conditioners and temperature sensors can stand in for an AC's room
/// reading. A WebSocket subscription tells the hub the moment something changes.
@MainActor
public final class HomeAssistantService: DeviceService {
public let id = "homeassistant"
public let title = "Home Assistant"
public var onChange: (() -> Void)?
struct Config: Codable {
var url: String
var token: String
var name: String?
var version: String?
}
private let vault: SecretStore
private var config: Config?
private let session: URLSession
private var socket: URLSessionWebSocketTask?
private var socketRetry: Task<Void, Never>?
/// Each climate entity's own names for the panel's fan speeds and modes, from the last read.
private var fanNames: [String: [String: String]] = [:]
private var modeNames: [String: [String: String]] = [:]
/// The entities linked in the plan: only their changes are worth a read.
private var watched: Set<String> = []
private var changePending = false
public init(vault: SecretStore) {
self.vault = vault
let configuration = URLSessionConfiguration.ephemeral
configuration.timeoutIntervalForRequest = 10
session = URLSession(configuration: configuration)
config = vault.read().flatMap { try? JSONDecoder().decode(Config.self, from: $0) }
if config != nil { listen() }
}
public var isConnected: Bool { config != nil }
public var info: [String: Any] {
guard let config else { return ["connected": false] }
return ["connected": true, "url": config.url, "name": config.name ?? "Home Assistant", "version": config.version ?? ""]
}
/// For the iPhone: the Mac shares its connection over the paired, encrypted sync.
public var shareable: [String: Any]? {
guard let config else { return nil }
return ["url": config.url, "token": config.token, "name": config.name ?? "", "version": config.version ?? ""]
}
// MARK: - Connecting
/// Checks the address and the token, then keeps them.
public func connect(url raw: String, token: String) async throws {
let url = try Self.normalize(raw)
let token = token.trimmingCharacters(in: .whitespacesAndNewlines)
guard !token.isEmpty else { throw ServiceFailure("Paste a long-lived access token (your profile in Home Assistant → Security).") }
var candidate = Config(url: url, token: token)
let about = try await request("GET", "/api/config", config: candidate) as? [String: Any] ?? [:]
candidate.name = about["location_name"] as? String
candidate.version = about["version"] as? String
config = candidate
vault.write(try? JSONEncoder().encode(candidate))
listen()
}
/// Takes a connection shared by the Mac; nil removes it.
public func adopt(_ shared: [String: Any]?) {
guard let shared, let url = shared["url"] as? String, let token = shared["token"] as? String else {
if config != nil { disconnect() }
return
}
let name = (shared["name"] as? String).flatMap { $0.isEmpty ? nil : $0 }
guard config?.url != url || config?.token != token || config?.name != name else { return }
config = Config(url: url, token: token, name: name, version: shared["version"] as? String)
vault.write(try? JSONEncoder().encode(config))
listen()
}
public func watch(_ ids: Set<String>) { watched = ids }
public func disconnect() {
config = nil
vault.write(nil)
socketRetry?.cancel()
socket?.cancel(with: .goingAway, reason: nil)
socket = nil
}
/// "homeassistant.local:8123" → "http://homeassistant.local:8123".
static func normalize(_ raw: String) throws -> String {
var s = raw.trimmingCharacters(in: .whitespacesAndNewlines)
guard !s.isEmpty else { throw ServiceFailure("Enter the address of your Home Assistant, for example http://homeassistant.local:8123") }
if !s.contains("://") { s = "http://" + s }
while s.hasSuffix("/") { s.removeLast() }
guard let url = URL(string: s), url.host != nil, ["http", "https"].contains(url.scheme ?? "") else {
throw ServiceFailure("“\(raw)” is not a web address")
}
if url.port == nil, url.scheme == "http", (url.host ?? "").hasSuffix(".local") || url.host == "homeassistant" {
s += ":8123" // Home Assistant's default port, which people leave out
}
return s
}
// MARK: - Devices
public func devices() async throws -> [ServiceDevice] {
let states = try await request("GET", "/api/states") as? [[String: Any]] ?? []
let areas = (try? await areaNames(for: states.compactMap { $0["entity_id"] as? String })) ?? [:]
return states.compactMap { state in
guard var device = Self.device(from: state) else { return nil }
device.room = areas[device.id]
return device
}.sorted { ($0.kind.rawValue, $0.name) < ($1.kind.rawValue, $1.name) }
}
/// Area of every entity, in one template request (the REST API has no area endpoint).
private func areaNames(for ids: [String]) async throws -> [String: String] {
let template = "{% for e in states %}{{ e.entity_id }}\t{{ area_name(e.entity_id) or '' }}\n{% endfor %}"
guard let text = try await request("POST", "/api/template", body: ["template": template], raw: true) as? String else { return [:] }
var out: [String: String] = [:]
for line in text.split(separator: "\n") {
let parts = line.split(separator: "\t", maxSplits: 1).map(String.init)
if parts.count == 2, !parts[1].isEmpty, parts[1] != "None" { out[parts[0]] = parts[1] }
}
return out
}
public func read(_ ids: Set<String>) async throws -> [String: DeviceReading] {
guard !ids.isEmpty else { return [:] }
let states = try await request("GET", "/api/states") as? [[String: Any]] ?? []
var out: [String: DeviceReading] = [:]
for state in states {
guard let id = state["entity_id"] as? String, ids.contains(id) else { continue }
let attributes = state["attributes"] as? [String: Any] ?? [:]
if id.hasPrefix("climate.") {
fanNames[id] = FanNames.table(attributes["fan_modes"] as? [String] ?? [])
modeNames[id] = Self.modeTable(attributes["hvac_modes"] as? [String] ?? [])
}
out[id] = Self.reading(from: state)
}
return out
}
public func send(kind: DeviceKind, id: String, patch: [String: Any], state: [String: Any]) async throws {
for call in Self.calls(for: id, patch: patch, state: state,
fans: fanNames[id] ?? [:], modes: modeNames[id] ?? [:]) {
_ = try await request("POST", "/api/services/\(call.domain)/\(call.service)", body: call.data)
}
}
// MARK: - Mapping (static, so the tests can run it without a server)
static func device(from state: [String: Any]) -> ServiceDevice? {
guard let id = state["entity_id"] as? String else { return nil }
let attributes = state["attributes"] as? [String: Any] ?? [:]
let name = attributes["friendly_name"] as? String ?? id
let domain = id.split(separator: ".").first.map(String.init) ?? ""
var device: ServiceDevice
switch domain {
case "light":
device = ServiceDevice(id: id, name: name, kind: .light)
let modes = attributes["supported_color_modes"] as? [String] ?? []
device.capabilities = lightCapabilities(modes)
device.detail = "light · " + (modes.isEmpty ? "on/off" : modes.joined(separator: ", "))
case "switch":
device = ServiceDevice(id: id, name: name, kind: .light)
device.detail = "switch · on/off"
case "climate":
device = ServiceDevice(id: id, name: name, kind: .ac)
if let lo = attributes.double("min_temp"), let hi = attributes.double("max_temp") {
device.range = (max(lo, 10), min(hi, 32))
}
device.detail = "climate · " + (attributes["hvac_modes"] as? [String] ?? []).joined(separator: ", ")
case "sensor":
guard isTemperature(attributes) else { return nil }
device = ServiceDevice(id: id, name: name, kind: .sensor)
device.detail = "temperature sensor"
default:
return nil
}
device.online = !["unavailable", "unknown"].contains(state["state"] as? String ?? "")
return device
}
static func lightCapabilities(_ modes: [String]) -> [String] {
var caps: [String] = []
if modes.contains(where: { $0 != "onoff" }) { caps.append("brightness") }
if modes.contains("color_temp") { caps.append("temp") }
if modes.contains(where: { ["hs", "xy", "rgb", "rgbw", "rgbww"].contains($0) }) { caps.append("color") }
return caps
}
static func isTemperature(_ attributes: [String: Any]) -> Bool {
(attributes["device_class"] as? String) == "temperature"
|| ["°C", "°F"].contains(attributes["unit_of_measurement"] as? String ?? "")
}
/// The panel's AC modes and the climate entity's names for them.
static func modeTable(_ hvacModes: [String]) -> [String: String] {
var out: [String: String] = [:]
for (panel, names) in [("cool", ["cool"]), ("heat", ["heat"]), ("dry", ["dry"]),
("fan", ["fan_only"]), ("auto", ["auto", "heat_cool"])] {
if let name = names.first(where: hvacModes.contains) { out[panel] = name }
}
return out
}
static func reading(from state: [String: Any]) -> DeviceReading {
let id = state["entity_id"] as? String ?? ""
let value = state["state"] as? String ?? ""
let attributes = state["attributes"] as? [String: Any] ?? [:]
var reading = DeviceReading(online: !["unavailable", "unknown"].contains(value))
guard reading.online else { return reading }
if id.hasPrefix("light.") || id.hasPrefix("switch.") {
var light: [String: Any] = ["on": value == "on"]
if value == "on", let b = attributes.double("brightness") { light["brightness"] = max(0.05, min(1, b / 255)) }
switch attributes["color_mode"] as? String {
case "color_temp":
if let k = attributes.double("color_temp_kelvin") { light["temp"] = max(2200, min(6500, k)); light["color"] = NSNull() }
case "hs", "xy", "rgb", "rgbw", "rgbww":
if let rgb = attributes["rgb_color"] as? [Any], rgb.count == 3 {
let c = rgb.compactMap { ($0 as? NSNumber)?.doubleValue }
if c.count == 3 { light["color"] = ColorMath.hex(r: c[0] / 255, g: c[1] / 255, b: c[2] / 255) }
}
default: break
}
reading.light = light
} else if id.hasPrefix("climate.") {
let modes = modeTable(attributes["hvac_modes"] as? [String] ?? [])
var ac: [String: Any] = ["on": value != "off"]
// On, but not running right now: a thermostat whose room is already warm (or cool) enough.
let action = attributes["hvac_action"] as? String
ac["idle"] = value != "off" && (action == "idle" || action == "off")
if let mode = modes.first(where: { $0.value == value })?.key { ac["mode"] = mode }
if let t = attributes.double("temperature") {
ac["target"] = t
} else if let lo = attributes.double("target_temp_low"), let hi = attributes.double("target_temp_high") {
ac["target"] = ((lo + hi) / 2).rounded()
}
if let room = attributes.double("current_temperature") { ac["roomTemp"] = room }
let fans = FanNames.table(attributes["fan_modes"] as? [String] ?? [])
if let current = attributes["fan_mode"] as? String, let fan = FanNames.panel(current), fans[fan] != nil { ac["fan"] = fan }
let swings = attributes["swing_modes"] as? [String] ?? []
if let swing = attributes["swing_mode"] as? String, !swings.isEmpty { ac["swing"] = swing == "off" ? "off" : "swing" }
let presets = attributes["preset_modes"] as? [String] ?? []
let preset = attributes["preset_mode"] as? String ?? ""
if presets.contains("sleep") { ac["sleep"] = preset == "sleep" }
if presets.contains("eco") { ac["eco"] = preset == "eco" }
reading.ac = ac
reading.features = [
"modes": ["cool", "heat", "dry", "fan", "auto"].filter { modes[$0] != nil },
"fans": FanNames.order.filter { fans[$0] != nil },
"swing": swings.contains("off") && swings.count > 1,
"sleep": presets.contains("sleep"), "eco": presets.contains("eco"),
]
} else if id.hasPrefix("sensor."), let t = Double(value) {
reading.temperature = (attributes["unit_of_measurement"] as? String) == "°F" ? (t - 32) * 5 / 9 : t
}
return reading
}
struct Call {
var domain: String
var service: String
var data: [String: Any]
}
static func calls(for id: String, patch: [String: Any], state: [String: Any],
fans: [String: String], modes: [String: String]) -> [Call] {
let domain = id.split(separator: ".").first.map(String.init) ?? ""
let target: [String: Any] = ["entity_id": id]
func call(_ service: String, _ data: [String: Any] = [:], domain d: String = domain) -> Call {
Call(domain: d, service: service, data: target.merging(data) { $1 })
}
if domain == "switch" {
guard let on = patch["on"] as? Bool else { return [] }
return [call(on ? "turn_on" : "turn_off")]
}
if domain == "light" {
if patch["on"] as? Bool == false { return [call("turn_off")] }
var data: [String: Any] = [:]
if let b = patch["brightness"] as? Double { data["brightness_pct"] = Int((b * 100).rounded()) }
if let k = patch["temp"] as? Double { data["color_temp_kelvin"] = Int(k) }
if let hex = patch["color"] as? String, let (r, g, b) = ColorMath.rgb(hex) {
data["rgb_color"] = [Int(r * 255), Int(g * 255), Int(b * 255)]
}
guard !data.isEmpty || patch["on"] as? Bool == true else { return [] }
return [call("turn_on", data)]
}
guard domain == "climate" else { return [] }
var out: [Call] = []
let on = patch["on"] as? Bool
if on == false { return [call("set_hvac_mode", ["hvac_mode": "off"])] }
// Picking a mode is what switches a climate entity on.
if on == true || patch["mode"] != nil {
let mode = (patch["mode"] as? String) ?? (state["mode"] as? String) ?? "cool"
if let name = modes[mode] ?? modes.values.first { out.append(call("set_hvac_mode", ["hvac_mode": name])) }
}
if let t = patch["target"] as? Double {
out.append(call("set_temperature", ["temperature": t]))
}
if let fan = patch["fan"] as? String, let name = fans[fan] {
out.append(call("set_fan_mode", ["fan_mode": name]))
}
if let swing = patch["swing"] as? String {
out.append(call("set_swing_mode", ["swing_mode": swing == "off" ? "off" : "on"]))
}
for preset in ["sleep", "eco"] {
if let enabled = patch[preset] as? Bool {
out.append(call("set_preset_mode", ["preset_mode": enabled ? preset : "none"]))
}
}
return out
}
// MARK: - HTTP
@discardableResult
private func request(_ method: String, _ path: String, body: [String: Any]? = nil,
raw: Bool = false, config: Config? = nil) async throws -> Any? {
guard let config = config ?? self.config, let url = URL(string: config.url + path) else {
throw ServiceFailure("Connect Home Assistant first")
}
var request = URLRequest(url: url)
request.httpMethod = method
request.setValue("Bearer \(config.token)", forHTTPHeaderField: "Authorization")
if let body {
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONSerialization.data(withJSONObject: body)
}
let data: Data, response: URLResponse
do {
(data, response) = try await session.data(for: request)
} catch {
throw ServiceFailure("Home Assistant at \(config.url) did not answer: \(error.localizedDescription)")
}
let status = (response as? HTTPURLResponse)?.statusCode ?? 0
switch status {
case 200..<300: break
case 401, 403: throw ServiceFailure("Home Assistant refused the token. Create a new long-lived access token and connect again.")
case 404: throw ServiceFailure("Home Assistant does not know \(path). Is the API enabled?")
default:
let text = String(data: data, encoding: .utf8)?.prefix(200) ?? ""
throw ServiceFailure("Home Assistant answered \(status) \(text)")
}
if raw { return String(data: data, encoding: .utf8) }
return data.isEmpty ? nil : try? JSONSerialization.jsonObject(with: data)
}
// MARK: - Live updates
/// Subscribes to state changes of the entities the hub cares about, and says so through
/// `onChange`. Reconnects by itself; polling covers the gaps.
private func listen() {
socketRetry?.cancel()
socket?.cancel(with: .goingAway, reason: nil)
guard let config, var parts = URLComponents(string: config.url + "/api/websocket") else { return }
parts.scheme = parts.scheme == "https" ? "wss" : "ws"
guard let url = parts.url else { return }
let task = session.webSocketTask(with: url)
socket = task
task.resume()
Task { @MainActor [weak self] in
await self?.run(task, token: config.token)
}
}
private func run(_ task: URLSessionWebSocketTask, token: String) async {
do {
_ = try await task.receive() // auth_required
try await task.send(.string(Self.json(["type": "auth", "access_token": token])))
_ = try await task.receive() // auth_ok
try await task.send(.string(Self.json(["id": 1, "type": "subscribe_events", "event_type": "state_changed"])))
while task === socket {
let message = try await task.receive()
guard case .string(let text) = message,
let event = (try? JSONSerialization.jsonObject(with: Data(text.utf8)) as? [String: Any])?["event"] as? [String: Any],
let entity = (event["data"] as? [String: Any])?["entity_id"] as? String,
watched.contains(entity), !changePending else { continue }
// A burst of changes (a scene) becomes one read.
changePending = true
Task { @MainActor [weak self] in
try? await Task.sleep(nanoseconds: 400_000_000)
self?.changePending = false
self?.onChange?()
}
}
} catch {
guard task === socket, config != nil else { return }
socketRetry = Task { @MainActor [weak self] in
try? await Task.sleep(nanoseconds: 15_000_000_000)
guard !Task.isCancelled else { return }
self?.listen()
}
}
}
private static func json(_ object: [String: Any]) -> String {
(try? JSONSerialization.data(withJSONObject: object)).flatMap { String(data: $0, encoding: .utf8) } ?? "{}"
}
}