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

package/ios/Source/sgcs/G2KeyboardHid.swift

@@ -0,0 +1,290 @@
+import Foundation
+
+/// Bounded HID report-descriptor decoder for the G2 keyboard bridge. HOGP
+/// passes the Report ID out of band (Report Reference descriptor), so a
+/// characteristic value is decoded as-is; byte zero is never stripped the way
+/// USB HID would. Ported from g2flash `demos/keyboard-hid.ts`; the descriptor
+/// limits match the firmware's 512-byte Report Map cap.
+enum G2KeyboardHid {
+    struct Usage: Hashable {
+        let page: Int
+        let usage: Int
+    }
+
+    struct KeyEvent: Equatable {
+        let page: Int
+        let usage: Int
+        let down: Bool
+    }
+
+    struct Field {
+        let bit: Int
+        let size: Int
+        let count: Int
+        let variable: Bool
+        let min: Int
+        let max: Int
+        let usages: [Usage]
+        let range: (Usage, Usage)?
+    }
+
+    struct Report {
+        let id: Int
+        var bits: Int
+        var fields: [Field]
+    }
+
+    struct DescriptorError: Error, CustomStringConvertible {
+        let reason: String
+        var description: String {
+            "Unsupported or malformed HID descriptor: \(reason)"
+        }
+    }
+
+    struct ReportError: Error, CustomStringConvertible {
+        let reason: String
+        var description: String {
+            reason
+        }
+    }
+
+    private struct Global {
+        var page = 0, min = 0, max = 0, size = 0, count = 0, id = 0
+    }
+
+    /// Parse a Report Map into its input reports keyed by Report ID (0 when the
+    /// map has no Report ID items). Rejects long items, usage delimiters, mixed
+    /// numbered/unnumbered reports and oversized dimensions.
+    static func parseReportMap(_ bytes: [UInt8]) throws -> [Int: Report] {
+        func fail(_ reason: String) -> DescriptorError {
+            DescriptorError(reason: reason)
+        }
+        guard !bytes.isEmpty, bytes.count <= 512 else { throw fail("report map must contain 1..512 bytes") }
+        var reports: [Int: Report] = [:]
+        var order: [Int] = []
+        var g = Global()
+        var stack: [Global] = []
+        var usages: [Usage] = []
+        var lo: Usage?
+        var hi: Usage?
+        var depth = 0
+        var p = 0
+        while p < bytes.count {
+            let prefix = Int(bytes[p])
+            p += 1
+            if prefix == 0xFE {
+                throw fail("long items")
+            }
+            let n = [0, 1, 2, 4][prefix & 3]
+            guard p + n <= bytes.count else { throw fail("truncated item") }
+            var v = 0
+            for j in 0 ..< n {
+                v += Int(bytes[p + j]) << (8 * j)
+            }
+            p += n
+            let signed = n > 0 && v >= 1 << (n * 8 - 1) ? v - (1 << (n * 8)) : v
+            let type = (prefix >> 2) & 3
+            let tag = prefix >> 4
+            func usage(_ v: Int, _ n: Int) -> Usage {
+                n == 4 ? Usage(page: v >> 16, usage: v & 0xFFFF) : Usage(page: g.page, usage: v)
+            }
+            switch type {
+            case 1:
+                switch tag {
+                case 0: g.page = v
+                case 1: g.min = signed
+                case 2: g.max = g.min < 0 ? signed : v
+                case 7: g.size = v
+                case 8:
+                    if v == 0 || v > 255 {
+                        throw fail("Report ID")
+                    }
+                    g.id = v
+                case 9: g.count = v
+                case 10:
+                    if stack.count >= 8 {
+                        throw fail("global stack overflow")
+                    }
+                    stack.append(g)
+                case 11:
+                    guard let popped = stack.popLast() else { throw fail("global stack underflow") }
+                    g = popped
+                case 3, 4, 5, 6: break // physical range, unit/exponent
+                default: throw fail("unknown global item")
+                }
+            case 2:
+                if tag == 0 {
+                    if usages.count >= 512 {
+                        throw fail("too many usages")
+                    }
+                    usages.append(usage(v, n))
+                } else if tag == 1 {
+                    lo = usage(v, n)
+                } else if tag == 2 {
+                    hi = usage(v, n)
+                } else if tag == 10 {
+                    throw fail("usage delimiters")
+                } else if tag > 9 {
+                    throw fail("unknown local item")
+                }
+            case 0:
+                if tag == 10 {
+                    depth += 1
+                    if depth > 32 {
+                        throw fail("collection depth")
+                    }
+                } else if tag == 12 {
+                    depth -= 1
+                    if depth < 0 {
+                        throw fail("collection underflow")
+                    }
+                } else if tag == 8 {
+                    if g.size == 0 || g.size > 32 || g.count == 0 || g.count > 512 {
+                        throw fail("field dimensions")
+                    }
+                    if reports[g.id] == nil {
+                        if reports.count >= 16 {
+                            throw fail("too many input reports")
+                        }
+                        reports[g.id] = Report(id: g.id, bits: 0, fields: [])
+                        order.append(g.id)
+                    }
+                    var r = reports[g.id]!
+                    var range: (Usage, Usage)?
+                    if lo != nil || hi != nil {
+                        guard let lo, let hi, lo.page == hi.page, hi.usage >= lo.usage else { throw fail("usage range") }
+                        range = (lo, hi)
+                    }
+                    let field = Field(
+                        bit: r.bits, size: g.size, count: g.count, variable: v & 2 != 0,
+                        min: g.min, max: g.max, usages: usages, range: range
+                    )
+                    r.bits += g.size * g.count
+                    if r.bits > 4096 {
+                        throw fail("report exceeds 512 bytes")
+                    }
+                    // Constant padding and relative pointer axes are not keys.
+                    if v & 1 == 0, v & 4 == 0 {
+                        r.fields.append(field)
+                    }
+                    reports[g.id] = r
+                } else if tag != 9, tag != 11 {
+                    throw fail("unknown main item")
+                }
+                usages = []
+                lo = nil
+                hi = nil
+            default:
+                throw fail("reserved item type")
+            }
+        }
+        if depth != 0 || !stack.isEmpty {
+            throw fail("unbalanced collection/global stack")
+        }
+        if reports[0] != nil, reports.count > 1 {
+            throw fail("mixed numbered and unnumbered input reports")
+        }
+        if reports.isEmpty {
+            throw fail("no input reports")
+        }
+        return reports
+    }
+
+    private static func usageAt(_ f: Field, _ index: Int) -> Usage? {
+        if index < 0 {
+            return nil
+        }
+        if index < f.usages.count {
+            return f.usages[index]
+        }
+        let rangeIndex = index - f.usages.count
+        if let range = f.range, rangeIndex <= range.1.usage - range.0.usage {
+            return Usage(page: range.0.page, usage: range.0.usage + rangeIndex)
+        }
+        // Variable items reuse their last usage when Report Count exceeds usages.
+        if f.variable {
+            return f.range?.1 ?? f.usages.last
+        }
+        return nil
+    }
+
+    /// Keyboard (page 7) and consumer (page 12) usages currently asserted in
+    /// one input report value. Throws on a length mismatch or a rollover report.
+    static func reportKeys(_ report: Report, _ data: [UInt8]) throws -> [Usage] {
+        guard data.count == (report.bits + 7) / 8 else {
+            throw ReportError(reason: "HID input length does not match Report Map")
+        }
+        var keys: [Usage] = []
+        var seen = Set<Usage>()
+        for f in report.fields {
+            for i in 0 ..< f.count {
+                var value = 0
+                for j in 0 ..< f.size {
+                    let bit = f.bit + i * f.size + j
+                    if data[bit >> 3] & UInt8(1 << (bit & 7)) != 0 {
+                        value += 1 << j
+                    }
+                }
+                if f.min < 0, value >= 1 << (f.size - 1) {
+                    value -= 1 << f.size
+                }
+                if value < f.min || value > f.max {
+                    continue
+                } // null state
+                guard let u = usageAt(f, f.variable ? i : value - f.min) else { continue }
+                if f.variable, value == 0 {
+                    continue
+                }
+                if u.usage == 0 {
+                    continue
+                }
+                if u.page == 7, u.usage <= 3 {
+                    throw ReportError(reason: "HID keyboard rollover/error report")
+                }
+                if u.page == 7 || u.page == 12, !seen.contains(u) {
+                    seen.insert(u)
+                    keys.append(u)
+                }
+            }
+        }
+        return keys
+    }
+
+    /// Key ownership is per characteristic, then unioned: releasing one report
+    /// cannot release a modifier still held by another report.
+    struct HeldKeys {
+        private var reports: [UInt16: [Usage]] = [:]
+        private var held: [Usage] = []
+
+        mutating func update(handle: UInt16, report: Report, data: [UInt8]) throws -> [KeyEvent] {
+            reports[handle] = try reportKeys(report, data)
+            return diff()
+        }
+
+        mutating func reset() -> [KeyEvent] {
+            reports.removeAll()
+            return diff()
+        }
+
+        private mutating func diff() -> [KeyEvent] {
+            var next: [Usage] = []
+            var nextSet = Set<Usage>()
+            for handle in reports.keys.sorted() {
+                for u in reports[handle]! where !nextSet.contains(u) {
+                    nextSet.insert(u)
+                    next.append(u)
+                }
+            }
+            let heldSet = Set(held)
+            var events: [KeyEvent] = []
+            for u in held where !nextSet.contains(u) {
+                events.append(KeyEvent(page: u.page, usage: u.usage, down: false))
+            }
+            for u in next where !heldSet.contains(u) {
+                events.append(KeyEvent(page: u.page, usage: u.usage, down: true))
+            }
+            held = next
+            return events
+        }
+    }
+}

package/ios/Source/sgcs/G2NotificationTuning.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+/// Config values snapped to what the G2 notification firmware accepts.
+enum G2NotificationTuning {
+    /// The firmware takes 0 (its own choice) or one of three popup durations.
+    static let popupSecondsChoices: [Int] = [5, 7, 10]
+
+    static func snapPopupSeconds(_ seconds: Int) -> Int32 {
+        guard seconds > 0 else { return 0 }
+        // Ties round up: distance compared first, then the larger choice wins.
+        let snapped = popupSecondsChoices.min { lhs, rhs in
+            let dl = abs(lhs - seconds)
+            let dr = abs(rhs - seconds)
+            return dl == dr ? lhs > rhs : dl < dr
+        }
+        return Int32(snapped ?? popupSecondsChoices[0])
+    }
+
+    /// The firmware filter is an allowlist; with nothing blocked it stays off so
+    /// an incomplete allowlist can never drop a notification.
+    static func filterEnabled(for config: GlassesNotificationConfig) -> Bool {
+        !config.blockedApps.isEmpty
+    }
+}

package/ios/Source/sgcs/G2RingBattery.swift

@@ -0,0 +1,22 @@
+import Foundation
+
+/// Settings field 106, sent as its own notification after the device-info poll by GLASSLYCFW/24 and later.
+/// This is the R1 connected to the glasses, independent of the phone controller.
+struct G2RingBattery: Equatable {
+    let connected: Bool
+    let level: Int
+    let charging: Bool
+
+    static let disconnected = G2RingBattery(connected: false, level: -1, charging: false)
+
+    static func decode(_ data: Data) -> G2RingBattery? {
+        let bytes = Array(data)
+        guard bytes.count == 5, bytes[0] == 0x52, bytes[1] == 0x42, bytes[2] == 1 else { return nil }
+        guard bytes[3] & 1 != 0 else { return .disconnected }
+        guard bytes[3] & 2 != 0 else {
+            return G2RingBattery(connected: true, level: -1, charging: false)
+        }
+        guard bytes[4] <= 100 else { return nil }
+        return G2RingBattery(connected: true, level: Int(bytes[4]), charging: bytes[3] & 4 != 0)
+    }
+}

package/ios/Source/sgcs/G2Sensors.swift

@@ -0,0 +1,75 @@
+import Foundation
+
+/// Upstream mode 16 / settings field 105 and mode 10 / navigation field 100.
+/// Validate the report format independently of the advertised CFW revision.
+enum G2Sensors {
+    static func heading(_ fields: [Int: Any]) -> Int? {
+        guard let raw = fields[1] else { return 0 }
+        guard let heading = raw as? Int32, (0 ... 359).contains(heading) else { return nil }
+        return Int(heading)
+    }
+
+    static func command(sensor: String, operation: String, options: [String: Double]) -> Data? {
+        func number(_ key: String, _ fallback: Int, _ range: ClosedRange<Int>) -> Int? {
+            guard let value = options[key] else { return fallback }
+            guard value.isFinite, value.rounded() == value,
+                  value >= Double(range.lowerBound), value <= Double(range.upperBound) else { return nil }
+            return Int(value)
+        }
+        func u16(_ n: Int) -> [UInt8] {
+            [UInt8(n & 255), UInt8(n >> 8)]
+        }
+        if sensor == "light" {
+            if operation == "query" {
+                return Data([16, 0])
+            }
+            if operation == "stop" {
+                return Data([16, 2])
+            }
+            guard operation == "start", let interval = number("intervalMs", 500, 100 ... 5000),
+                  let delta = number("minDelta", 1, 0 ... 65535),
+                  let heartbeat = number("heartbeatMs", 5000, 0 ... 65535) else { return nil }
+            return Data([16, 1, 1] + u16(interval) + u16(delta) + u16(heartbeat))
+        }
+        if sensor == "compass" {
+            if operation == "stop" {
+                return Data([10, 0])
+            }
+            guard operation == "start", let interval = number("intervalMs", 1000, 50 ... 2000),
+                  let change = number("minChangeDegrees", 5, 0 ... 359) else { return nil }
+            return Data([10, 2] + u16(interval) + u16(change))
+        }
+        return nil
+    }
+
+    private static func uint(_ b: [UInt8], _ offset: Int, _ count: Int) -> Int64 {
+        (0 ..< count).reduce(Int64(0)) { $0 | (Int64(b[offset + $1]) << ($1 * 8)) }
+    }
+
+    static func light(_ data: Data) -> [String: Any]? {
+        let b = Array(data)
+        guard b.count == 24, b[0] == 65, b[1] == 76, b[2] == 1, b[3] <= 3 else { return nil }
+        return [
+            "reason": ["query", "started", "poll", "stopped"][Int(b[3])],
+            "opened": b[4] & 1 != 0, "passive": b[4] & 2 != 0,
+            "autoBrightness": b[4] & 4 != 0, "readSucceeded": b[4] & 8 != 0,
+            "status": Int(b[5]), "value": uint(b, 6, 4), "peak": uint(b, 10, 4),
+            "targetLevel": uint(b, 14, 2), "brightness": Int(b[16]), "gear": Int(b[17]),
+            "scaleQ10": uint(b, 18, 2), "sampleTimestampMs": uint(b, 20, 4),
+        ]
+    }
+
+    static func compass(_ data: Data) -> [String: Any]? {
+        let b = Array(data)
+        guard b.count == 12, b[0] == 67, b[1] == 77, b[2] == 1,
+              b[3] <= 3 || b[3] == 255, b[4] <= 2 || b[4] == 255, b[5] <= 3 else { return nil }
+        return [
+            "accuracy": b[3] == 255 ? NSNull() : Int(b[3]) as Any,
+            "anomalies": b[4] == 255 ? NSNull() : Int(b[4]) as Any,
+            "source": ["unknown", "grv", "gmrv", "rv"][Int(b[5])],
+            "sampleMatched": b[6] & 128 != 0, "grvValid": b[6] & 1 != 0,
+            "gmrvValid": b[6] & 2 != 0, "rvValid": b[6] & 4 != 0,
+            "magneticDataFresh": b[6] & 8 != 0, "sampleTimestampMs": uint(b, 8, 4),
+        ]
+    }
+}

package/ios/Source/sgcs/G2TouchInput.swift

@@ -0,0 +1,51 @@
+import Foundation
+
+/// Capture before the BLE callback hops to the main queue. Processing time is
+/// not input time: several seconds of queued input can drain in milliseconds.
+struct G2InputArrival {
+    let uptime: TimeInterval
+    let timestamp: Int64
+
+    init(uptime: TimeInterval = ProcessInfo.processInfo.systemUptime,
+         timestamp: Int64 = Int64(Date().timeIntervalSince1970 * 1000))
+    {
+        self.uptime = uptime
+        self.timestamp = timestamp
+    }
+}
+
+/// CFW's field-100 extension identifies raw R1 reports forwarded once through
+/// the right lens. Its tick is a ring clock, not a phone timestamp.
+struct G2RingInput {
+    let wireType: UInt8
+    let tick: UInt32
+
+    init?(fields: [Int: Any]) {
+        guard fields[2] as? Int32 == 2, let data = fields[100] as? Data else { return nil }
+        let bytes = [UInt8](data)
+        guard bytes.count == 12, bytes[0] == 0x52, bytes[1] == 0x49,
+              bytes[2] == 1, bytes[3] == 1, bytes[7] == 0 else { return nil }
+        let events: [UInt8: Int32] = [0: 9, 1: 0, 2: 3, 4: 1, 5: 2, 8: 10, 9: 11, 10: 14]
+        guard fields[1] as? Int32 == events[bytes[4], default: 127] else { return nil }
+        wireType = bytes[4]
+        tick = UInt32(bytes[8]) | UInt32(bytes[9]) << 8 | UInt32(bytes[10]) << 16 | UInt32(bytes[11]) << 24
+    }
+}
+
+struct G2TouchDebounce {
+    private var lastAcceptedAt: TimeInterval?
+
+    mutating func accepts(event: Int32?, ring: G2RingInput?, receivedAt: TimeInterval) -> Bool {
+        // The raw ring stream deliberately bypasses stock suppression. Do not
+        // reinstate it on the phone or discard click/swipe completions after a
+        // touch_down. Edges and unknown markers never consume a debounce slot.
+        if ring != nil || event == 9 || event == 10 || event == 14 || event == 127 {
+            return true
+        }
+        if let lastAcceptedAt, receivedAt - lastAcceptedAt < 0.1 {
+            return false
+        }
+        lastAcceptedAt = receivedAt
+        return true
+    }
+}

package/ios/Source/sgcs/G2WritePacing.swift

@@ -0,0 +1,18 @@
+import UIKit
+
+/// Background CFW traffic uses the original G2 timed writer. Reports show
+/// readiness remaining false for seconds even while gestures and timers run.
+/// Keep foreground throughput without letting that gate freeze background UI.
+enum G2WritePacing: Equatable {
+    case timed, creditBurst
+
+    static let packetDelayNs: UInt64 = 6_000_000
+
+    init(cfwEnabled: Bool, applicationState: UIApplication.State) {
+        self = cfwEnabled && applicationState == .active ? .creditBurst : .timed
+    }
+
+    func canWrite(peripheralReady: Bool) -> Bool {
+        self == .timed || peripheralReady
+    }
+}