@glassly/bluetooth-sdk 0.1.0-dev.99 → 0.2.8-dev.445

package/ios/Source/sgcs/G2KeyboardBridge.swift

@@ -0,0 +1,438 @@
+import Foundation
+
+/// Owns the phone side of the CFW keyboard bridge for one G2 connection:
+/// the client, the remembered keyboard, the reconnect loop, and what the
+/// app sees (glasses-status keys plus `keyboard_*` events). The G2 driver
+/// hands it right-lens field-131 payloads and a sender for settings payloads;
+/// everything else stays in here so the driver only tracks link lifecycle.
+///
+/// Firmware state is volatile (a lens reboot returns to stock behaviour), so
+/// the remembered keyboard is re-enabled and reconnected on every CFW
+/// detection and after every keyboard-side disconnect, with backoff. The
+/// discovered handle mapping is only valid for one connection epoch and is
+/// never persisted.
+@MainActor
+final class G2KeyboardBridge {
+    static let minimumRevision = 39
+    private static let defaultsKey = "g2_keyboard"
+
+    struct Saved: Equatable {
+        let address: String
+        let addressType: Int
+        let name: String
+
+        var values: [String: Any] {
+            ["address": address, "addressType": addressType, "name": name]
+        }
+
+        init(address: String, addressType: Int, name: String) {
+            self.address = address
+            self.addressType = addressType
+            self.name = name
+        }
+
+        init?(values: [String: Any]?) {
+            guard let values, let address = values["address"] as? String,
+                  let addressType = values["addressType"] as? Int
+            else { return nil }
+            self.init(address: address, addressType: addressType, name: values["name"] as? String ?? "")
+        }
+    }
+
+    enum State: String {
+        case idle, scanning, connecting, pairing, configuring, connected, error
+    }
+
+    struct BridgeError: Error, LocalizedError, CustomStringConvertible {
+        let description: String
+        var errorDescription: String? { description }
+    }
+
+    private let send: (Data) -> Void
+    private var client: G2KeyboardClient?
+    private(set) var supported = false
+    private(set) var ready = false
+    private(set) var state = State.idle
+    private var busy = false
+    /// `busy` is held by the automatic reconnect loop (not the user).
+    private var autoReconnecting = false
+    private var userDisconnected = false
+    private var lastError: String?
+    private var connectedName = ""
+    private var scanResults: [G2KeyboardProtocol.Advert] = []
+    private var reconnectTask: Task<Void, Never>?
+    private var reconnectAttempt = 0
+    private(set) var saved: Saved? {
+        didSet { UserDefaults.standard.set(saved?.values, forKey: Self.defaultsKey) }
+    }
+
+    /// `send` delivers a complete G2SettingPackage payload to the right lens.
+    init(send: @escaping (Data) -> Void) {
+        self.send = send
+        saved = Saved(values: UserDefaults.standard.dictionary(forKey: Self.defaultsKey))
+    }
+
+    // MARK: - Link lifecycle (driven by G2)
+
+    /// CFW classification landed (or changed). Re-arms the remembered keyboard.
+    func cfwDetected(revision: Int?) {
+        let now = (revision ?? 0) >= Self.minimumRevision
+        if now != supported {
+            Bridge.log("G2: keyboard bridge \(now ? "available" : "unavailable") (revision \(revision ?? 0))")
+        }
+        supported = now
+        userDisconnected = false
+        reconnectAttempt = 0
+        if !supported {
+            teardownClient()
+        }
+        publish()
+        if supported, saved != nil {
+            scheduleReconnect(after: 1)
+        }
+    }
+
+    /// The glasses link is gone: drop everything but the remembered keyboard.
+    func linkLost() {
+        supported = false
+        teardownClient()
+        publish()
+    }
+
+    /// Right-lens sid-0x09 field 131.
+    func accept(_ payload: Data) {
+        client?.accept(payload)
+    }
+
+    private func teardownClient() {
+        reconnectTask?.cancel()
+        reconnectTask = nil
+        client?.close()
+        client = nil
+        ready = false
+        busy = false
+        state = .idle
+        lastError = nil
+    }
+
+    // MARK: - App-facing commands
+
+    /// Five-second active scan; returns every distinct advertiser seen.
+    func scan() async throws -> [G2KeyboardProtocol.Advert] {
+        try requireSupported()
+        await interruptReconnect()
+        try requireIdle()
+        busy = true
+        defer { busy = false }
+        let client = ensureClient()
+        scanResults = []
+        lastError = nil
+        setState(.scanning)
+        do {
+            try await releaseLink(client)
+            try await client.enable()
+            try await client.scan()
+            setState(.idle)
+        } catch {
+            fail(error)
+            throw friendly(error)
+        }
+        return scanResults
+    }
+
+    /// Connect, pair and subscribe a keyboard, then remember it.
+    func connect(address: String, addressType: Int, name: String) async throws {
+        try requireSupported()
+        guard let bytes = G2KeyboardProtocol.address(fromText: address), (0 ... 3).contains(addressType) else {
+            throw BridgeError(description: "Invalid keyboard address")
+        }
+        await interruptReconnect()
+        try requireIdle()
+        busy = true
+        defer { busy = false }
+        userDisconnected = false
+        let client = ensureClient()
+        lastError = nil
+        setState(.connecting)
+        do {
+            try await releaseLink(client)
+            try await client.enable()
+            try await client.connect(addressType: UInt8(addressType), address: bytes)
+            setState(.configuring)
+            let config = try await client.configure()
+            ready = true
+            connectedName = name
+            saved = Saved(address: address, addressType: addressType, name: name)
+            reconnectAttempt = 0
+            Bridge.log("G2: keyboard ready — \(config.inputCount) input reports, epoch \(config.epoch)")
+            setState(.connected)
+        } catch {
+            ready = false
+            fail(error)
+            throw friendly(error)
+        }
+    }
+
+    /// Drop the keyboard link but keep the bond and the remembered identity.
+    /// No automatic reconnect until the next CFW detection or explicit connect.
+    func disconnect() async throws {
+        userDisconnected = true
+        cancelReconnect()
+        ready = false
+        guard let client else {
+            setState(.idle)
+            return
+        }
+        do {
+            try await client.disable()
+            setState(.idle)
+        } catch {
+            fail(error)
+            throw error
+        }
+    }
+
+    /// Forget the remembered keyboard. The firmware keeps its bond; a stale
+    /// bond is cleared with the glasses' own device tools.
+    func forget() async {
+        try? await disconnect()
+        saved = nil
+        connectedName = ""
+        publish()
+    }
+
+    /// Reconnect the remembered keyboard now (an app-driven retry).
+    func reconnect() async throws {
+        guard let saved else { throw BridgeError(description: "No remembered keyboard") }
+        try await connect(address: saved.address, addressType: saved.addressType, name: saved.name)
+    }
+
+    func passkey(_ pin: Int) async throws {
+        guard let client, (0 ... 999_999).contains(pin) else { throw BridgeError(description: "No pending keyboard pairing") }
+        try await client.authenticate(UInt32(pin))
+    }
+
+    func compare(_ accept: Bool) async throws {
+        guard let client else { throw BridgeError(description: "No pending keyboard pairing") }
+        try await client.confirm(accept)
+    }
+
+    /// Firmware status query plus the bridge's own view.
+    func status() async -> [String: Any] {
+        var values = statusValues()
+        if let client, supported, let status = try? await client.query() {
+            values["firmware"] = [
+                "enabled": status.enabled, "conn": Int(status.conn), "connected": status.connected,
+                "encrypted": status.encrypted, "scanning": status.scanning,
+            ]
+        }
+        return values
+    }
+
+    // MARK: - Internals
+
+    private func requireSupported() throws {
+        guard supported else {
+            throw BridgeError(description: "Keyboard bridge requires Glassly CFW revision \(Self.minimumRevision) on connected G2 glasses")
+        }
+    }
+
+    private func requireIdle() throws {
+        guard !busy else { throw BridgeError(description: "Keyboard operation already in progress") }
+    }
+
+    private func ensureClient() -> G2KeyboardClient {
+        if let client {
+            return client
+        }
+        let client = G2KeyboardClient(send: { [weak self] payload, _ in self?.send(payload) }) { [weak self] event in
+            self?.handle(event)
+        }
+        self.client = client
+        return client
+    }
+
+    private func setState(_ next: State) {
+        state = next
+        publish()
+    }
+
+    private func fail(_ error: Error) {
+        lastError = "\(error)"
+        Bridge.log("G2: keyboard error — \(lastError ?? "")")
+        setState(.error)
+    }
+
+    private func cancelReconnect() {
+        reconnectTask?.cancel()
+        reconnectTask = nil
+    }
+
+    /// Hand the bridge to a user-driven scan/connect: cancel a pending retry
+    /// and, when an attempt is mid-flight (a sleeping keyboard keeps one busy
+    /// for up to 30 s at a time), close its client so its waits throw, then
+    /// let it unwind. Without this the scan screen mostly saw "operation
+    /// already in progress" whenever a keyboard was remembered.
+    private func interruptReconnect() async {
+        let task = reconnectTask
+        reconnectTask = nil
+        task?.cancel()
+        if autoReconnecting {
+            client?.close()
+            client = nil
+        }
+        if let task {
+            await task.value
+        }
+    }
+
+    /// The firmware refuses SCAN/CONNECT while it still owns a keyboard slot,
+    /// and an interrupted connect keeps initiating until DM close: drop the
+    /// link and poll until the slot is free (close is asynchronous).
+    private func releaseLink(_ client: G2KeyboardClient) async throws {
+        // DISABLE is epoch-checked and a fresh client has not seen the
+        // firmware's epoch yet (it bumps on every CONNECT); QUERY is not, and
+        // its STATUS record carries the epoch, so sync before disabling.
+        _ = try await client.query()
+        try await client.disable()
+        ready = false
+        for _ in 0 ..< 20 {
+            let status = try await client.query()
+            if status.conn == 0 { return }
+            try? await Task.sleep(nanoseconds: 150_000_000)
+        }
+        throw BridgeError(description: "The glasses are still closing the previous keyboard link; try again in a moment")
+    }
+
+    /// Firmware BUSY almost always means the ring's own scan/reconnect holds
+    /// the radio; say so instead of leaking the raw control error.
+    private func friendly(_ error: Error) -> Error {
+        if "\(error)".hasSuffix("firmware busy") {
+            return BridgeError(
+                description: "The glasses' radio is busy (usually the ring reconnecting). Wait a few seconds and try again."
+            )
+        }
+        return error
+    }
+
+    private func scheduleReconnect(after seconds: Double) {
+        cancelReconnect()
+        // The task stays in `reconnectTask` for the whole attempt so
+        // interruptReconnect() can await it unwinding.
+        reconnectTask = Task { @MainActor [weak self] in
+            try? await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+            guard let self, !Task.isCancelled else { return }
+            await self.attemptReconnect()
+        }
+    }
+
+    private func attemptReconnect() async {
+        guard supported, let saved, !userDisconnected, !ready, !busy else { return }
+        autoReconnecting = true
+        defer { autoReconnecting = false }
+        do {
+            try await connect(address: saved.address, addressType: saved.addressType, name: saved.name)
+        } catch {
+            if Task.isCancelled { return } // a user scan/connect took over
+            reconnectAttempt += 1
+            // Keyboards sleep and the ring's own scan can hold the controller
+            // (BUSY); back off to 30 s and keep trying while the glasses stay up.
+            let delay = min(30.0, 5.0 * pow(2.0, Double(min(reconnectAttempt - 1, 3))))
+            scheduleReconnect(after: delay)
+        }
+    }
+
+    private func handle(_ event: G2KeyboardClient.Event) {
+        switch event {
+        case let .keys(events):
+            let now = Int64(Date().timeIntervalSince1970 * 1000)
+            for e in events {
+                Bridge.sendTypedMessage("keyboard_key", body: [
+                    "page": e.page, "usage": e.usage, "down": e.down, "timestamp": now,
+                ])
+            }
+        case let .advert(advert):
+            // An active scan reports the advertisement and its scan response as
+            // separate records, and the name usually only rides in the latter:
+            // merge per address instead of keeping whichever came first.
+            let merged: G2KeyboardProtocol.Advert
+            if let i = scanResults.firstIndex(where: { $0.address == advert.address && $0.addressType == advert.addressType }) {
+                merged = scanResults[i].merging(advert)
+                guard merged != scanResults[i] else { return }
+                scanResults[i] = merged
+            } else {
+                merged = advert
+                scanResults.append(advert)
+            }
+            Bridge.sendTypedMessage("keyboard_advert", body: Self.advertValues(merged))
+        case let .status(status):
+            if ready, !status.connected || !status.encrypted {
+                keyboardDropped("status")
+            }
+        case .gap:
+            break
+        case let .dm(event, dmStatus):
+            if event == 0x28 || event == 0x2B || event == 0x2D {
+                Bridge.log("G2: keyboard DM event 0x\(String(event, radix: 16)) status \(dmStatus)")
+                if ready {
+                    keyboardDropped("dm")
+                }
+            }
+        case .passkeyRequest:
+            setState(.pairing)
+            Bridge.sendTypedMessage("keyboard_pairing", body: ["kind": "passkey"])
+        case let .passkeyDisplay(pin):
+            setState(.pairing)
+            Bridge.sendTypedMessage("keyboard_pairing", body: ["kind": "display", "value": Int(pin)])
+        case let .compareRequest(value):
+            setState(.pairing)
+            Bridge.sendTypedMessage("keyboard_pairing", body: ["kind": "compare", "value": Int(value)])
+        case .servicesChanged:
+            Bridge.log("G2: keyboard services changed; rediscovering")
+            ready = false
+            publish()
+            Task { @MainActor [weak self] in
+                guard let self, let saved = self.saved else { return }
+                self.busy = false
+                try? await self.connect(address: saved.address, addressType: saved.addressType, name: saved.name)
+            }
+        case let .error(message):
+            lastError = message
+            Bridge.log("G2: keyboard — \(message)")
+            publish()
+        }
+    }
+
+    private func keyboardDropped(_ reason: String) {
+        Bridge.log("G2: keyboard disconnected (\(reason))")
+        ready = false
+        setState(.idle)
+        if saved != nil, !userDisconnected {
+            scheduleReconnect(after: 2)
+        }
+    }
+
+    static func advertValues(_ advert: G2KeyboardProtocol.Advert) -> [String: Any] {
+        [
+            "address": advert.addressText, "addressType": Int(advert.addressType), "name": advert.name,
+            "hid": advert.hid, "rssi": Int(advert.rssi),
+        ]
+    }
+
+    private func statusValues() -> [String: Any] {
+        [
+            "keyboardBridge": supported,
+            "keyboardConnected": ready,
+            "keyboardName": ready ? connectedName : (saved?.name ?? ""),
+            "keyboardSaved": saved != nil,
+            "keyboardState": state.rawValue,
+            "keyboardError": lastError ?? "",
+        ]
+    }
+
+    private func publish() {
+        for (key, value) in statusValues() {
+            DeviceStore.shared.apply("glasses", key, value)
+        }
+    }
+}