@glassly/bluetooth-sdk 0.1.0-dev.98 → 0.2.8-dev.444

package/ios/Source/sgcs/G2AncsRelay.swift

@@ -0,0 +1,268 @@
+import Foundation
+
+/// Glassly CFW ANCS relay (contract revision 20): the right lens forwards the
+/// iOS notifications it reads over ANCS as private records on the G2 settings
+/// channel, and the phone enables it with a fail-open 90 s lease. The wire
+/// format is pinned by `patches/ancs_relay.c` in g2flash.
+///
+/// Phone -> glasses, G2SettingPackage field 126: `['A','N',1,op,…]`.
+/// Glasses -> phone, field 125: `['A','N',1,kind,…]`, one record per message:
+///   1 SOURCE  [event][flags][category][count][uid LE32]
+///   2 ATTR    [uid LE32][attr id][total LE16][offset LE16][chunk]
+///   3 APP     [total LE16][offset LE16][id_len][bundle id][chunk]  (display name)
+///   4 STATUS  [enabled][side][drops LE16][seq LE16][send errs]
+///
+/// Pure so record reassembly stays unit-testable: chunks of one attribute can
+/// arrive in any order, a notification completes once all eight attributes are
+/// whole, and the app display name is learned from the APP record that follows.
+struct G2AncsRelay {
+    static let protocolVersion: UInt8 = 1
+
+    enum Op: UInt8 {
+        case enable = 1, disable = 2, query = 3, action = 4, renew = 5
+    }
+
+    enum EventID: UInt8 {
+        case added = 0, modified = 1, removed = 2
+    }
+
+    struct Flags: OptionSet {
+        let rawValue: UInt8
+        static let silent = Flags(rawValue: 1 << 0)
+        static let important = Flags(rawValue: 1 << 1)
+        static let preExisting = Flags(rawValue: 1 << 2)
+        static let positiveAction = Flags(rawValue: 1 << 3)
+        static let negativeAction = Flags(rawValue: 1 << 4)
+    }
+
+    /// One fully reassembled notification.
+    struct Notification: Equatable {
+        let uid: UInt32
+        let event: EventID
+        let flags: Flags
+        let category: UInt8
+        let categoryCount: UInt8
+        let appIdentifier: String
+        let title: String
+        let subtitle: String
+        let message: String
+        /// ANCS date attribute, `yyyyMMdd'T'HHmmss` in local time; empty if absent.
+        let date: String
+        let positiveActionLabel: String
+        let negativeActionLabel: String
+
+        var notificationId: String { "ancs-\(uid)" }
+    }
+
+    struct Status: Equatable {
+        let enabled: Bool
+        let side: UInt8
+        let drops: UInt16
+        let sent: UInt16
+        let sendErrors: UInt8
+    }
+
+    enum Event: Equatable {
+        case notification(Notification)
+        case removed(uid: UInt32, appIdentifier: String?)
+        case appName(appIdentifier: String, displayName: String)
+        case status(Status)
+    }
+
+    // MARK: - Encoding (phone -> glasses)
+
+    /// G2SettingPackage{commandId=1 (DEVICE_RECEIVE_INFO), magic=0, field 126}.
+    /// Hand-framed like the firmware's replies: tag 126/wire 2 is 1010 = f2 07.
+    static func controlPacket(op: Op, payload: [UInt8] = []) -> Data {
+        let body = [0x41, 0x4E, protocolVersion, op.rawValue] + payload
+        return Data([0x08, 0x01, 0x10, 0x00, 0xF2, 0x07, UInt8(body.count)] + body)
+    }
+
+    /// Perform the notification's positive (0) or negative (1) action.
+    static func actionPacket(uid: UInt32, positive: Bool) -> Data {
+        controlPacket(op: .action, payload: [
+            UInt8(uid & 0xFF), UInt8((uid >> 8) & 0xFF), UInt8((uid >> 16) & 0xFF), UInt8(uid >> 24),
+            positive ? 0 : 1,
+        ])
+    }
+
+    /// ANCS dates are local wall-clock without a zone; fall back to `now`.
+    static func timestampMs(date: String, now: Date = Date()) -> Int64 {
+        guard !date.isEmpty else { return Int64(now.timeIntervalSince1970 * 1000) }
+        let formatter = DateFormatter()
+        formatter.locale = Locale(identifier: "en_US_POSIX")
+        formatter.calendar = Calendar(identifier: .gregorian)
+        formatter.timeZone = .current
+        formatter.dateFormat = "yyyyMMdd'T'HHmmss"
+        guard let parsed = formatter.date(from: date) else {
+            return Int64(now.timeIntervalSince1970 * 1000)
+        }
+        return Int64(parsed.timeIntervalSince1970 * 1000)
+    }
+
+    // MARK: - Decoding (glasses -> phone)
+
+    private struct PendingAttribute {
+        var total: Int
+        var bytes: [UInt8]
+        var received: Int
+        var filled: [Bool]
+        var complete: Bool { received >= total }
+
+        init(total: Int) {
+            self.total = total
+            bytes = [UInt8](repeating: 0, count: total)
+            filled = [Bool](repeating: false, count: total)
+            received = 0
+        }
+
+        mutating func fill(offset: Int, chunk: ArraySlice<UInt8>) {
+            for (i, byte) in chunk.enumerated() {
+                let at = offset + i
+                guard at < total else { return }
+                if !filled[at] {
+                    filled[at] = true
+                    received += 1
+                }
+                bytes[at] = byte
+            }
+        }
+    }
+
+    private struct Pending {
+        var event: EventID
+        var flags: Flags
+        var category: UInt8
+        var categoryCount: UInt8
+        var attributes: [UInt8: PendingAttribute] = [:]
+        var startedAt: Date
+    }
+
+    /// Notification attribute ids the firmware requests, all of which must land.
+    private static let attributeIDs: [UInt8] = [0, 1, 2, 3, 4, 5, 6, 7]
+    private static let maxPending = 32
+
+    private var pending: [UInt32: Pending] = [:]
+    /// uid -> bundle id, so a removal can name the app after the notification is gone.
+    private var appIdentifiers: [UInt32: String] = [:]
+    private var partialAppName: PendingAttribute?
+    private var partialAppNameFor: String?
+    private(set) var appNames: [String: String] = [:]
+
+    /// Feed one field-125 payload. Returns the event it completes, if any.
+    mutating func ingest(_ record: Data, now: Date = Date()) -> Event? {
+        let b = [UInt8](record)
+        guard b.count >= 4, b[0] == 0x41, b[1] == 0x4E, b[2] == Self.protocolVersion else { return nil }
+        switch b[3] {
+        case 1: return ingestSource(b, now: now)
+        case 2: return ingestAttribute(b)
+        case 3: return ingestAppName(b)
+        case 4: return ingestStatus(b)
+        default: return nil
+        }
+    }
+
+    /// Drop reassemblies that never completed (a lost chunk, a lens reset).
+    mutating func prune(olderThan seconds: TimeInterval, now: Date = Date()) {
+        pending = pending.filter { now.timeIntervalSince($0.value.startedAt) < seconds }
+    }
+
+    mutating func reset() {
+        pending.removeAll()
+        partialAppName = nil
+        partialAppNameFor = nil
+    }
+
+    private mutating func ingestSource(_ b: [UInt8], now: Date) -> Event? {
+        guard b.count >= 12, let event = EventID(rawValue: b[4]) else { return nil }
+        let uid = Self.u32(b, 8)
+        if event == .removed {
+            pending[uid] = nil
+            return .removed(uid: uid, appIdentifier: appIdentifiers.removeValue(forKey: uid))
+        }
+        if pending.count >= Self.maxPending, pending[uid] == nil,
+           let oldest = pending.min(by: { $0.value.startedAt < $1.value.startedAt })
+        {
+            pending[oldest.key] = nil
+        }
+        pending[uid] = Pending(
+            event: event, flags: Flags(rawValue: b[5]), category: b[6], categoryCount: b[7],
+            startedAt: now
+        )
+        return nil
+    }
+
+    private mutating func ingestAttribute(_ b: [UInt8]) -> Event? {
+        guard b.count >= 13 else { return nil }
+        let uid = Self.u32(b, 4)
+        let attrID = b[8]
+        let total = Int(Self.u16(b, 9))
+        let offset = Int(Self.u16(b, 11))
+        guard var entry = pending[uid], Self.attributeIDs.contains(attrID),
+              total <= 4096, offset <= total
+        else { return nil }
+        var attr = entry.attributes[attrID] ?? PendingAttribute(total: total)
+        if attr.total != total { attr = PendingAttribute(total: total) }
+        attr.fill(offset: offset, chunk: b[13...])
+        entry.attributes[attrID] = attr
+        let complete = Self.attributeIDs.allSatisfy { entry.attributes[$0]?.complete ?? false }
+        guard complete else {
+            pending[uid] = entry
+            return nil
+        }
+        pending[uid] = nil
+        func text(_ id: UInt8) -> String {
+            String(decoding: entry.attributes[id]?.bytes ?? [], as: UTF8.self)
+        }
+        let appIdentifier = text(0)
+        appIdentifiers[uid] = appIdentifier
+        return .notification(Notification(
+            uid: uid, event: entry.event, flags: entry.flags,
+            category: entry.category, categoryCount: entry.categoryCount,
+            appIdentifier: appIdentifier, title: text(1), subtitle: text(2), message: text(3),
+            date: text(5), positiveActionLabel: text(6), negativeActionLabel: text(7)
+        ))
+    }
+
+    private mutating func ingestAppName(_ b: [UInt8]) -> Event? {
+        guard b.count >= 9 else { return nil }
+        let total = Int(Self.u16(b, 4))
+        let offset = Int(Self.u16(b, 6))
+        let idLen = Int(b[8])
+        guard b.count >= 9 + idLen, total <= 1024, offset <= total else { return nil }
+        let appIdentifier = String(decoding: b[9 ..< 9 + idLen], as: UTF8.self)
+        var attr: PendingAttribute
+        if let partial = partialAppName, partialAppNameFor == appIdentifier, partial.total == total {
+            attr = partial
+        } else {
+            attr = PendingAttribute(total: total)
+        }
+        attr.fill(offset: offset, chunk: b[(9 + idLen)...])
+        guard attr.complete else {
+            partialAppName = attr
+            partialAppNameFor = appIdentifier
+            return nil
+        }
+        partialAppName = nil
+        partialAppNameFor = nil
+        let name = String(decoding: attr.bytes, as: UTF8.self)
+        appNames[appIdentifier] = name
+        return .appName(appIdentifier: appIdentifier, displayName: name)
+    }
+
+    private func ingestStatus(_ b: [UInt8]) -> Event? {
+        guard b.count >= 11 else { return nil }
+        return .status(Status(
+            enabled: b[4] != 0, side: b[5], drops: Self.u16(b, 6), sent: Self.u16(b, 8),
+            sendErrors: b[10]
+        ))
+    }
+
+    private static func u16(_ b: [UInt8], _ i: Int) -> UInt16 {
+        UInt16(b[i]) | (UInt16(b[i + 1]) << 8)
+    }
+
+    private static func u32(_ b: [UInt8], _ i: Int) -> UInt32 {
+        UInt32(b[i]) | (UInt32(b[i + 1]) << 8) | (UInt32(b[i + 2]) << 16) | (UInt32(b[i + 3]) << 24)
+    }
+}

package/ios/Source/sgcs/G2BleLink.swift

@@ -0,0 +1,102 @@
+import Foundation
+
+/// Glassly CFW BLE link speed control (contract revision 26). The firmware
+/// boots on the stock connection profile; the phone can switch each lens to
+/// the 7.5 ms / latency-0 fast profile (slow mode suppressed) and back. The
+/// wire format is pinned by `patches/ble_link.c` in g2flash.
+///
+/// Phone -> glasses, G2SettingPackage field 127: `['B','L',1,op]`.
+/// Glasses -> phone, field 128 on every settings read reply:
+///   `['B','L',1, fast, side, wanted, applied, min16, max16, latency16,
+///     liveInterval16, liveLatency16]`
+/// Intervals are little-endian in 1.25 ms units. Modes: 0xa3 fast, 0xa4 slow,
+/// 0 = update pending. min/max/latency are the profile the last request used;
+/// the live pair is the connection as the central granted it (absent from the
+/// first revision 26 builds, which sent 13 bytes).
+enum G2BleLink {
+    static let protocolVersion: UInt8 = 1
+
+    enum Op: UInt8 {
+        case stock = 0, fast = 1, query = 2
+    }
+
+    enum Mode: Equatable {
+        case fast, slow, pending, other(UInt8)
+
+        init(_ raw: UInt8) {
+            switch raw {
+            case 0xA3: self = .fast
+            case 0xA4: self = .slow
+            case 0: self = .pending
+            default: self = .other(raw)
+            }
+        }
+
+        var name: String {
+            switch self {
+            case .fast: "fast"
+            case .slow: "slow"
+            case .pending: "pending"
+            case let .other(raw): String(format: "0x%02x", raw)
+            }
+        }
+    }
+
+    struct Status: Equatable {
+        let fast: Bool
+        let side: UInt8
+        let wanted: Mode
+        let applied: Mode
+        /// The profile the last request asked for.
+        let requestedMinMs: Double
+        let requestedMaxMs: Double
+        let requestedLatency: UInt16
+        /// What the central granted; nil on firmware that predates the field.
+        let liveIntervalMs: Double?
+        let liveLatency: UInt16?
+
+        var summary: String {
+            var text = "\(fast ? "FAST" : "stock") wanted=\(wanted.name) applied=\(applied.name)"
+                + String(format: " requested %.2f-%.2f ms / latency %d", requestedMinMs, requestedMaxMs, requestedLatency)
+            if let liveIntervalMs, let liveLatency {
+                text += String(format: " live %.2f ms / latency %d", liveIntervalMs, liveLatency)
+            }
+            return text
+        }
+    }
+
+    // MARK: - Encoding (phone -> glasses)
+
+    /// G2SettingPackage{commandId=1 (DEVICE_RECEIVE_INFO), magic=0, field 127}.
+    /// Hand-framed like the ANCS control: tag 127/wire 2 is 1018 = fa 07.
+    static func controlPacket(op: Op) -> Data {
+        Data([0x08, 0x01, 0x10, 0x00, 0xFA, 0x07, 4, 0x42, 0x4C, protocolVersion, op.rawValue])
+    }
+
+    // MARK: - Decoding (glasses -> phone)
+
+    static func decodeStatus(_ data: Data) -> Status? {
+        let b = [UInt8](data)
+        guard b.count >= 13, b[0] == 0x42, b[1] == 0x4C, b[2] == protocolVersion else { return nil }
+        let live = b.count >= 17
+        return Status(
+            fast: b[3] != 0,
+            side: b[4],
+            wanted: Mode(b[5]),
+            applied: Mode(b[6]),
+            requestedMinMs: ms(u16(b, 7)),
+            requestedMaxMs: ms(u16(b, 9)),
+            requestedLatency: u16(b, 11),
+            liveIntervalMs: live ? ms(u16(b, 13)) : nil,
+            liveLatency: live ? u16(b, 15) : nil
+        )
+    }
+
+    private static func ms(_ units: UInt16) -> Double {
+        Double(units) * 1.25
+    }
+
+    private static func u16(_ b: [UInt8], _ i: Int) -> UInt16 {
+        UInt16(b[i]) | (UInt16(b[i + 1]) << 8)
+    }
+}

package/ios/Source/sgcs/G2CfwClassification.swift

@@ -1,41 +1,59 @@
 import Foundation
 
-/// Stock-vs-Glassly-CFW classification of one G2 settings response's
-/// top-level field 100 ("EVENCFW/NN feat feat …"; stock firmware never emits
-/// the field).
-///
-/// Pure so the identity rules stay unit-testable — they gate the connect
-/// banner: legacy text drawn before classification and cleared after it
-/// splits draw/clear across render paths, and the stock text container then
-/// never leaves the glass.
+/// Firmware identity advertised in settings field 100. Retain its revision for
+/// future protocol changes; current features depend only on the firmware family.
 struct G2CfwClassification: Equatable {
-    /// nil = classified stock.
+    enum Family { case stock, upstream, glassly }
+
+    let family: Family
     let capabilityString: String?
-    let features: Set<String>
-    let protocolVersion: Int
 
-    var isCfw: Bool { capabilityString != nil }
+    /// Numeric contract revision, or nil for stock/unknown revision text.
+    var revision: Int? {
+        guard let header = capabilityString?.split(separator: " ").first,
+              let revision = Int(header.split(separator: "/", maxSplits: 1).last ?? ""),
+              revision > 0
+        else { return nil }
+        return revision
+    }
+
+    var isCfw: Bool {
+        family != .stock
+    }
+
+    var isGlassly: Bool {
+        family == .glassly
+    }
+
+    var displayName: String? {
+        switch family {
+        case .stock: nil
+        case .upstream: "g2flash CFW"
+        case .glassly: revision.map { "Glassly CFW v\($0)" } ?? "Glassly CFW"
+        }
+    }
+
+    static let stock = G2CfwClassification(family: .stock, capabilityString: nil)
 
-    static let stock = G2CfwClassification(capabilityString: nil, features: [], protocolVersion: 0)
+    /// The one revision gate: everything the app uses (SID-0xf0 transport,
+    /// scenes, settle reports, fast BLE link) shipped together in this
+    /// firmware line, so nothing older is special-cased; it is treated as stock.
+    static let minimumRevision = 39
 
-    /// Classify one settings response. Returns nil when the packet proves
-    /// nothing: a non-definitive response without the CFW banner (individual
-    /// settings packets can legitimately omit the field or arrive truncated),
-    /// or an absent banner on a connection already classified CFW — firmware
-    /// identity is connection-sticky, and downgrading would reinterpret an
-    /// installed mode-6 carrier as a stock BMP.
+    /// Partial settings notifications can omit field 100. Keep the connection's
+    /// known identity so a missing field cannot switch the active render path.
     static func classify(
         field100 data: Data?, definitive: Bool, currentCapability: String?
     ) -> G2CfwClassification? {
-        let capability = data.flatMap { String(data: $0, encoding: .utf8) }?
+        if let capability = data.flatMap({ String(data: $0, encoding: .utf8) })?
             .trimmingCharacters(in: CharacterSet(charactersIn: "\0"))
-        if let capability, capability.hasPrefix("EVENCFW/") {
-            let tokens = capability.split(separator: " ").map(String.init)
-            return G2CfwClassification(
-                capabilityString: capability,
-                features: Set(tokens.dropFirst()),
-                protocolVersion: tokens.first.flatMap { Int($0.dropFirst("EVENCFW/".count)) } ?? 0
-            )
+        {
+            if capability.hasPrefix("GLASSLYCFW/") {
+                return G2CfwClassification(family: .glassly, capabilityString: capability)
+            }
+            if capability.hasPrefix("EVENCFW/") {
+                return G2CfwClassification(family: .upstream, capabilityString: capability)
+            }
         }
         guard definitive, currentCapability == nil else { return nil }
         return .stock