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

package/ios/Source/sgcs/G2CfwTransport.swift

@@ -0,0 +1,485 @@
+import Foundation
+import zlib
+
+/// Private SID-0xf0 message-stream transport of the Glassly CFW (GLASSLYCFW/31,
+/// upstream Faceclaw/10+). Custom commands (modes 3/6/8/9/10/11/15/16/17/18/19/
+/// 20/36/37/38) no longer ride an EvenHub image container: they are records in
+/// a byte stream that the firmware reconstructs before any TPL reassembly, on
+/// whichever lenses the options byte selects (the other lens receives them over
+/// the frame bridge, in arrival order), and each record is answered with an ACK
+/// or NACK notification through the BLE ingress lens.
+///
+/// Wire format (see g2flash `patches/message_transport.c`):
+///
+/// * packet: `[0xAA][0x21][seq][len+2][1][1][0xF0][0][options][stream bytes][crc16 LE]`
+///   where `options` = lens bits (1 left, 2 right) | 0x80 RESET on the first
+///   packet of a stream | 0x40 END on its last, `seq` increments per packet
+///   (uint8 wrap) and the CRC (CCITT-FALSE) covers `options` + stream bytes.
+///   The stream id is the RESET packet's `seq`.
+/// * record: `[flags][len:u16][crc16 of the plain message:u16][body]` where
+///   flags = lens bits | 4 COMPRESSED | 8 RESET_CONTEXT. A compressed body is
+///   the output of one persistent deflate context ending in a SYNC_FLUSH
+///   (never Z_FINISH); RESET_CONTEXT tells the glasses to start a fresh
+///   inflater, which the phone must set whenever its own deflater is new.
+/// * ACK: `[1][stream][ordinal:u16][lens][size:u16][crc:u16]` + up to three
+///   7-byte history entries `[stream][ordinal:u16][size:u16][crc:u16]` of
+///   preceding successes; NACK is `[3]...` with no history.
+///
+/// This client sends one record per stream (RESET..END), so every ordinal is
+/// 0 and a stream id identifies the message. After a NACK or a timeout the
+/// glasses have dropped their inflater, so the encoder starts a new context
+/// and the next record carries RESET_CONTEXT.
+enum G2CfwTransport {
+    static let serviceId: UInt8 = 0xF0
+    static let lensLeft: UInt8 = 1
+    static let lensRight: UInt8 = 2
+    static let lensBoth: UInt8 = 3
+    static let flagCompressed: UInt8 = 4
+    static let flagResetContext: UInt8 = 8
+    static let packetReset: UInt8 = 0x80
+    static let packetEnd: UInt8 = 0x40
+    static let ackKind: UInt8 = 1
+    static let nackKind: UInt8 = 3
+    /// GLASSLYCFW/38: an object-cache reply, sent by each lens before its ACK.
+    static let replyKind: UInt8 = 5
+    /// A record body is length-prefixed with two bytes.
+    static let maxMessageBytes = 0xFFFF
+    /// The firmware caps a packet at 252 stream bytes; our writes stay within
+    /// the driver's 232-byte packet payload (options byte + chunk + CRC).
+    static let maxChunkBytes = 229
+
+    /// Persistent deflate context: records share dictionary state across
+    /// messages, so a keyframe after a delta compresses against it.
+    final class Encoder {
+        private var stream = z_stream()
+        private var ready = false
+        private(set) var needsContextReset = true
+
+        deinit {
+            if ready { deflateEnd(&stream) }
+        }
+
+        /// Drop the context: the next record carries RESET_CONTEXT so the
+        /// glasses discard theirs too (they already have after a NACK).
+        func resetContext() {
+            if ready {
+                deflateEnd(&stream)
+                ready = false
+            }
+            needsContextReset = true
+        }
+
+        /// One stream record for `message`, or nil when it cannot be framed.
+        /// Falls back to an uncompressed record (still resetting the context)
+        /// when deflate would not fit the two-byte length.
+        ///
+        /// Each lens inflates only the records addressed to it, so a record for
+        /// one lens can neither continue the shared context (the other lens
+        /// would fall out of sync) nor be continued from: it is deflated from a
+        /// fresh context and the next record starts fresh again.
+        func record(_ message: Data, targets: UInt8) -> Data? {
+            guard message.count <= G2CfwTransport.maxMessageBytes, targets & ~G2CfwTransport.lensBoth == 0
+            else { return nil }
+            let exclusive = targets != G2CfwTransport.lensBoth
+            if exclusive { resetContext() }
+            defer { if exclusive { resetContext() } }
+            let crc = BinaryCodec.crc16CCITT(message)
+
+            var flags = targets
+            var body: Data
+            if let compressed = deflateSyncFlush(message), compressed.count <= G2CfwTransport.maxMessageBytes {
+                body = compressed
+                flags |= G2CfwTransport.flagCompressed
+                if needsContextReset {
+                    flags |= G2CfwTransport.flagResetContext
+                    needsContextReset = false
+                }
+            } else {
+                // The glasses cannot resume a context this record skipped.
+                resetContext()
+                body = message
+                flags |= G2CfwTransport.flagResetContext
+            }
+            var record = Data(capacity: 5 + body.count)
+            record.append(flags)
+            record.append(UInt8(body.count & 0xFF))
+            record.append(UInt8((body.count >> 8) & 0xFF))
+            record.append(UInt8(crc & 0xFF))
+            record.append(UInt8((crc >> 8) & 0xFF))
+            record.append(body)
+            return record
+        }
+
+        private func deflateSyncFlush(_ message: Data) -> Data? {
+            if !ready {
+                stream = z_stream()
+                guard deflateInit_(&stream, Z_DEFAULT_COMPRESSION, ZLIB_VERSION, Int32(MemoryLayout<z_stream>.size)) == Z_OK
+                else { return nil }
+                ready = true
+                needsContextReset = true
+            }
+            let bound = Int(deflateBound(&stream, UInt(message.count))) + 16
+            var output = Data(count: bound)
+            var input = message
+            var produced = 0
+            let status: Int32 = input.withUnsafeMutableBytes { inRaw -> Int32 in
+                output.withUnsafeMutableBytes { outRaw -> Int32 in
+                    guard let outBase = outRaw.bindMemory(to: Bytef.self).baseAddress else { return Z_MEM_ERROR }
+                    stream.next_in = inRaw.bindMemory(to: Bytef.self).baseAddress
+                    stream.avail_in = uInt(message.count)
+                    stream.next_out = outBase
+                    stream.avail_out = uInt(bound)
+                    let rc = deflate(&stream, Z_SYNC_FLUSH)
+                    produced = bound - Int(stream.avail_out)
+                    stream.next_in = nil
+                    stream.next_out = nil
+                    return rc
+                }
+            }
+            guard status == Z_OK, stream.avail_in == 0, produced >= 4 else {
+                resetContext()
+                return nil
+            }
+            output.removeSubrange(produced ..< output.count)
+            return output
+        }
+    }
+
+    /// Split `stream` (one or more records) into SID-0xf0 packets. `sequence`
+    /// is the first packet's `seq` and the stream id; packets count up from it.
+    static func packets(stream: Data, sequence: UInt8, targets: UInt8, chunkBytes: Int = maxChunkBytes) -> [Data] {
+        let chunk = max(1, min(chunkBytes, 252))
+        var packets: [Data] = []
+        var offset = 0
+        var index: UInt8 = 0
+        repeat {
+            let end = min(offset + chunk, stream.count)
+            var options = targets & lensBoth
+            if offset == 0 { options |= packetReset }
+            if end >= stream.count { options |= packetEnd }
+            var body = Data(capacity: 1 + end - offset)
+            body.append(options)
+            if end > offset { body.append(stream[stream.startIndex + offset ..< stream.startIndex + end]) }
+            var packet = Data(capacity: 10 + body.count)
+            packet.append(contentsOf: [0xAA, 0x21, sequence &+ index, UInt8(body.count + 2), 1, 1, serviceId, 0])
+            packet.append(body)
+            packet.append(contentsOf: BinaryCodec.crc16CCITTLittleEndian(body))
+            packets.append(packet)
+            index &+= 1
+            offset = end
+        } while offset < stream.count
+        return packets
+    }
+
+    struct Ack: Equatable {
+        struct Entry: Equatable {
+            let streamId: UInt8
+            let ordinal: UInt16
+            let size: UInt16
+            let crc: UInt16
+        }
+
+        let success: Bool
+        let lens: UInt8
+        /// The message this reply is about, then preceding successes (newest first).
+        let entries: [Entry]
+        var current: Entry { entries[0] }
+    }
+
+    /// Parse a reply body (the packet payload with header and CRC stripped).
+    static func parseAck(_ body: Data) -> Ack? {
+        let b = [UInt8](body)
+        guard b.count >= 9, (b.count - 9) % 7 == 0, b.count <= 9 + 3 * 7,
+              b[0] == ackKind || b[0] == nackKind,
+              b[4] == lensLeft || b[4] == lensRight
+        else { return nil }
+        if b[0] == nackKind, b.count != 9 { return nil }
+        var entries = [Ack.Entry(
+            streamId: b[1], ordinal: UInt16(b[2]) | UInt16(b[3]) << 8,
+            size: UInt16(b[5]) | UInt16(b[6]) << 8, crc: UInt16(b[7]) | UInt16(b[8]) << 8
+        )]
+        var i = 9
+        while i < b.count {
+            entries.append(Ack.Entry(
+                streamId: b[i], ordinal: UInt16(b[i + 1]) | UInt16(b[i + 2]) << 8,
+                size: UInt16(b[i + 3]) | UInt16(b[i + 4]) << 8, crc: UInt16(b[i + 5]) | UInt16(b[i + 6]) << 8
+            ))
+            i += 7
+        }
+        return Ack(success: b[0] == ackKind, lens: b[4], entries: entries)
+    }
+
+    /// Object-cache reply (GLASSLYCFW/38): `[5][stream][ordinal:u16][lens]` then
+    /// `[mode][request:u16][status][epoch:u16][revision:u32][extra]`.
+    struct CacheReply: Equatable {
+        static let applied: UInt8 = 0, stale: UInt8 = 1, missing: UInt8 = 2, capacity: UInt8 = 3
+        static let refused: UInt8 = 4, unchanged: UInt8 = 5, delta: UInt8 = 6, snapshot: UInt8 = 7, reset: UInt8 = 8
+        let streamId: UInt8
+        let ordinal: UInt16
+        let lens: UInt8
+        let mode: UInt8
+        let request: UInt16
+        let status: UInt8
+        let epoch: UInt16
+        let revision: UInt32
+        let extra: [UInt8]
+
+        /// A RESET reply's store size in bytes (0 when the reply did not carry it).
+        var storeBytes: Int {
+            guard mode == 41, status == Self.applied, extra.count >= 3 else { return 0 }
+            return (Int(extra[1]) | Int(extra[2]) << 8) * 1024
+        }
+
+        /// Ids a MISSING reply names (objects and assets share the field).
+        var missingIds: [UInt32] {
+            guard status == Self.missing, extra.count >= 2 else { return [] }
+            var out: [UInt32] = []
+            var i = 2
+            while i + 4 <= extra.count {
+                out.append(UInt32(extra[i]) | UInt32(extra[i + 1]) << 8 | UInt32(extra[i + 2]) << 16 | UInt32(extra[i + 3]) << 24)
+                i += 4
+            }
+            return out
+        }
+
+        var summary: String {
+            let names = ["applied", "stale", "missing", "capacity", "refused", "unchanged", "delta", "snapshot", "reset"]
+            let name = Int(status) < names.count ? names[Int(status)] : "status \(status)"
+            switch status {
+            case Self.missing: return "\(name) \(missingIds)"
+            case Self.refused: return "\(name) reason \(extra.first ?? 0)"
+            case Self.applied, Self.capacity: return (extra.first ?? 0) > 0 ? "\(name), evicted \(extra[0])" : name
+            default: return name
+            }
+        }
+    }
+
+    static func parseCacheReply(_ body: Data) -> CacheReply? {
+        let b = [UInt8](body)
+        guard b.count >= 15, b[0] == replyKind, b[4] == lensLeft || b[4] == lensRight else { return nil }
+        return CacheReply(
+            streamId: b[1], ordinal: UInt16(b[2]) | UInt16(b[3]) << 8, lens: b[4],
+            mode: b[5], request: UInt16(b[6]) | UInt16(b[7]) << 8, status: b[8],
+            epoch: UInt16(b[9]) | UInt16(b[10]) << 8,
+            revision: UInt32(b[11]) | UInt32(b[12]) << 8 | UInt32(b[13]) << 16 | UInt32(b[14]) << 24,
+            extra: Array(b[15...])
+        )
+    }
+
+    /// True for messages of the object cache (modes 37-41), which carry an epoch and a request id.
+    static func isCacheMessage(_ message: Data) -> Bool {
+        message.count >= 5 && message[message.startIndex] >= 37 && message[message.startIndex] <= 41
+    }
+
+    /// Copy of a cache message with the session epoch filled in and, when the
+    /// encoder left the request id 0 (never for STATE, whose bytes are the
+    /// revision), `request` stamped: the firmware acknowledges a SHOW or HIDE
+    /// repeating the last applied request id without applying it again, so
+    /// every distinct message needs its own. Other messages return unchanged.
+    static func stamp(_ message: Data, epoch: UInt16, request: UInt16) -> Data {
+        guard isCacheMessage(message) else { return message }
+        var out = Data(message)
+        out[out.startIndex + 1] = UInt8(epoch & 0xFF)
+        out[out.startIndex + 2] = UInt8(epoch >> 8)
+        if out[out.startIndex] != 40, out[out.startIndex + 3] == 0, out[out.startIndex + 4] == 0, request != 0 {
+            out[out.startIndex + 3] = UInt8(request & 0xFF)
+            out[out.startIndex + 4] = UInt8(request >> 8)
+        }
+        return out
+    }
+
+    /// Read-only, single-packet parse of a raw notify frame: the reply body if
+    /// this is a complete SID-0xf0 frame with a valid CRC.
+    static func replyBody(fromNotifyFrame raw: Data) -> Data? {
+        guard raw.count >= 10 else { return nil }
+        let b = { (i: Int) -> UInt8 in raw[raw.startIndex + i] }
+        guard b(0) == 0xAA, Int(b(3)) + 8 == raw.count, b(4) == 1, b(5) == 1, b(6) == serviceId else { return nil }
+        let resultCode = (Int(b(7)) >> 1) & 0x0F
+        guard resultCode == 0 else { return nil }
+        let body = raw.subdata(in: (raw.startIndex + 8) ..< (raw.endIndex - 2))
+        let crc = BinaryCodec.crc16CCITT(body)
+        guard b(raw.count - 2) == UInt8(crc & 0xFF), b(raw.count - 1) == UInt8(crc >> 8) else { return nil }
+        return body
+    }
+
+    /// ACK deadline for a message of `streamBytes`: a both-lens stream acks at
+    /// ~1.1 KB/s once the right lens has it over the frame bridge (GLASSLYCFW/39),
+    /// so allow 1 ms per byte on top of 3.5 s. A tighter deadline times out
+    /// uploads that are still landing, and each timeout re-uploads more.
+    static func ackTimeoutNs(streamBytes: Int) -> UInt64 {
+        3_500_000_000 + UInt64(streamBytes) * 1_000_000
+    }
+}
+
+/// Thread-safe holder for the single in-flight stream ACK continuation — the
+/// SID-0xf0 counterpart of `ImgAckBox`, resolved inline on the BLE callback
+/// queue. A message sent to both lenses completes when each lens has acked
+/// it (the right lens's reply returns through the left, our ingress); any
+/// NACK, a timeout, or cancellation fails it.
+final class G2CfwAckBox {
+    private let lock = NSLock()
+    private var streamId: UInt8?
+    private var expectedLenses: UInt8 = 0
+    private var ackedLenses: UInt8 = 0
+    private var cont: CheckedContinuation<Bool, Never>?
+    private var token: UInt64 = 0
+    private var timer: Task<Void, Never>?
+    private var lastSuccessMs: Int64 = 0
+    private var lastOutcome: (at: TimeInterval, reason: String)?
+    /// Object-cache replies of the armed stream, by lens; kept until the next arm.
+    private var replies: [UInt8: G2CfwTransport.CacheReply] = [:]
+
+    func outcome() -> (at: TimeInterval, reason: String)? {
+        lock.lock()
+        defer { lock.unlock() }
+        return lastOutcome
+    }
+
+    /// The cache replies the last message drew, by lens (1 left, 2 right).
+    func cacheReplies() -> [UInt8: G2CfwTransport.CacheReply] {
+        lock.lock()
+        defer { lock.unlock() }
+        return replies
+    }
+
+    /// Feed one cache reply; it is kept when it belongs to the armed stream.
+    func record(_ reply: G2CfwTransport.CacheReply) {
+        lock.lock()
+        if let armed = streamId, armed == reply.streamId, reply.ordinal == 0 {
+            replies[reply.lens] = reply
+        }
+        lock.unlock()
+    }
+
+    /// Milliseconds since the last fully acked stream, or Int64.max if none yet.
+    func msSinceLastSuccess() -> Int64 {
+        lock.lock()
+        let last = lastSuccessMs
+        lock.unlock()
+        guard last > 0 else { return .max }
+        return Int64(Date().timeIntervalSince1970 * 1000) - last
+    }
+
+    /// Arm before sending, then `send`. The supplied guard expires with this
+    /// wait: queued packets must check it before writing, even while waiting
+    /// for BLE credits. A timed-out stream must not replay during recovery.
+    @MainActor
+    func wait(streamId: UInt8, lenses: UInt8, timeoutNs: UInt64, send: (_ isPending: @escaping () -> Bool) -> Void) async -> Bool {
+        await withTaskCancellationHandler {
+            await withCheckedContinuation { cont in
+                let token = arm(streamId: streamId, lenses: lenses, cont: cont)
+                guard !Task.isCancelled else {
+                    timeout(token: token)
+                    return
+                }
+                let timer = Task.detached { [self] in
+                    try? await Task.sleep(nanoseconds: timeoutNs)
+                    guard !Task.isCancelled else { return }
+                    timeout(token: token)
+                }
+                attachTimer(timer, token: token)
+                send { [self] in isPending(token: token) }
+            }
+        } onCancel: {
+            self.fail(reason: "cancelled")
+        }
+    }
+
+    private func isPending(token: UInt64) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return self.token == token && cont != nil
+    }
+
+    func arm(streamId: UInt8, lenses: UInt8, cont: CheckedContinuation<Bool, Never>) -> UInt64 {
+        lock.lock()
+        token &+= 1
+        let t = token
+        self.streamId = streamId
+        expectedLenses = lenses & G2CfwTransport.lensBoth
+        ackedLenses = 0
+        self.cont = cont
+        lastOutcome = nil
+        replies.removeAll()
+        let stale = timer
+        timer = nil
+        lock.unlock()
+        stale?.cancel()
+        return t
+    }
+
+    func attachTimer(_ task: Task<Void, Never>, token: UInt64) {
+        lock.lock()
+        let current = self.token == token && cont != nil
+        if current {
+            timer = task
+        }
+        lock.unlock()
+        if !current {
+            task.cancel()
+        }
+    }
+
+    func timeout(token: UInt64) {
+        lock.lock()
+        guard self.token == token, let c = cont else {
+            lock.unlock()
+            return
+        }
+        clearLocked(reason: "timeout")
+        lock.unlock()
+        c.resume(returning: false)
+    }
+
+    private func fail(reason: String) {
+        lock.lock()
+        guard let c = cont else {
+            lock.unlock()
+            return
+        }
+        let t = timer
+        clearLocked(reason: reason)
+        lock.unlock()
+        t?.cancel()
+        c.resume(returning: false)
+    }
+
+    /// Feed one reply. Returns true when it resolved the in-flight message.
+    @discardableResult
+    func resolve(_ ack: G2CfwTransport.Ack) -> Bool {
+        lock.lock()
+        guard let armed = streamId, armed == ack.current.streamId, ack.current.ordinal == 0, let c = cont else {
+            lock.unlock()
+            return false
+        }
+        if !ack.success {
+            let t = timer
+            clearLocked(reason: "nack")
+            lock.unlock()
+            t?.cancel()
+            c.resume(returning: false)
+            return true
+        }
+        ackedLenses |= ack.lens & expectedLenses
+        guard ackedLenses == expectedLenses else {
+            lock.unlock()
+            return false
+        }
+        let t = timer
+        lastSuccessMs = Int64(Date().timeIntervalSince1970 * 1000)
+        clearLocked(reason: "ack")
+        lock.unlock()
+        t?.cancel()
+        c.resume(returning: true)
+        return true
+    }
+
+    private func clearLocked(reason: String) {
+        streamId = nil
+        expectedLenses = 0
+        ackedLenses = 0
+        cont = nil
+        timer = nil
+        lastOutcome = (ProcessInfo.processInfo.systemUptime, reason)
+    }
+}

package/ios/Source/sgcs/G2DisplayDiagnostics.swift

@@ -0,0 +1,154 @@
+import Foundation
+
+/// Bounded, main-actor counters. No payload text, per-packet logging, or sample arrays.
+/// Durations use uptime; wall time is only for correlating exported reports.
+/// Disabled by default; opt in explicitly when investigating display performance.
+/// Lines stay small: a sample is logged only for a window with display work, a
+/// backlog or a late tick; zero, false and empty values and sub-millisecond
+/// timings are left out; the link's fixed facts go in a separate session line.
+@MainActor
+final class G2DisplayDiagnostics {
+    /// Link upkeep that runs whether or not anything is drawn: IMU reports,
+    /// touch debouncing and heartbeat writes alone leave a window idle.
+    private static let ambientCounters: Set<String> = [
+        "imuReceived", "imuSamples", "touchDebounced", "txBytes", "txPackets", "readyCallbacksL", "readyCallbacksR",
+    ]
+    private static let ambientTimings: Set<String> = ["notifyDispatchMs", "creditWaitMsL", "creditWaitMsR", "writeQueueMs"]
+    /// A tick this late means the main actor or the process was held up: logged even when idle.
+    static let stretchedWindow: TimeInterval = 2
+    /// The session line is repeated this often so a trimmed log excerpt still has it.
+    static let sessionRepeat: TimeInterval = 60
+
+    nonisolated static var now: TimeInterval {
+        ProcessInfo.processInfo.systemUptime
+    }
+
+    struct Timing {
+        var count = 0
+        var total = 0.0
+        var maximum = 0.0
+        mutating func add(_ ms: Double) {
+            count += 1
+            total += max(0, ms)
+            maximum = max(maximum, ms)
+        }
+    }
+
+    @MainActor final class Fragment {
+        let queuedAt = G2DisplayDiagnostics.now
+        var firstWrite: TimeInterval?
+        var lastWrite: TimeInterval?
+        func wrote() {
+            let now = G2DisplayDiagnostics.now
+            if firstWrite == nil {
+                firstWrite = now
+            }
+            lastWrite = now
+        }
+    }
+
+    private let enabled: Bool
+    private var started: TimeInterval
+    private var counters: [String: Int] = [:]
+    private var timings: [String: Timing] = [:]
+    /// Short: it is on every line, and only has to tell apart the runs in one log.
+    private let run = String(UUID().uuidString.prefix(8)).lowercased()
+    private var sequence = 0
+    private var lastStall: TimeInterval = -.infinity
+    private var sessionKey: String?
+    private var lastSession: TimeInterval = -.infinity
+
+    init(enabled: Bool = false, now: TimeInterval = G2DisplayDiagnostics.now) {
+        self.enabled = enabled
+        started = now
+    }
+
+    var isSampleDue: Bool {
+        enabled && Self.now - started >= 1
+    }
+
+    func count(_ name: String, _ amount: Int = 1) {
+        guard enabled else { return }
+        counters[name, default: 0] += amount
+    }
+
+    func timing(_ name: String, _ milliseconds: Double) {
+        guard enabled else { return }
+        timings[name, default: Timing()].add(milliseconds)
+    }
+
+    private func event(_ type: String, fields: [String: Any]) -> String {
+        sequence += 1
+        var record = fields
+        record["v"] = 1
+        record["run"] = run
+        record["id"] = sequence
+        record["t"] = Int64(Date().timeIntervalSince1970 * 1000)
+        record["type"] = type
+        let data = try? JSONSerialization.data(withJSONObject: record, options: [.sortedKeys])
+        return "G2PERF " + (data.flatMap { String(data: $0, encoding: .utf8) } ?? "{}")
+    }
+
+    /// At most one detail line/second; every failure still enters the summary counters.
+    func stall(fields: [String: Any], now: TimeInterval = G2DisplayDiagnostics.now) -> String? {
+        guard enabled, now - lastStall >= 1 else { return nil }
+        lastStall = now
+        return event("stall", fields: fields)
+    }
+
+    /// The link's fixed facts (firmware, MTUs, frame cap): logged when they
+    /// change and once a minute, instead of on every sample.
+    func session(_ fields: [String: Any], now: TimeInterval = G2DisplayDiagnostics.now) -> String? {
+        guard enabled else { return nil }
+        let key = fields.sorted { $0.key < $1.key }.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
+        guard key != sessionKey || now - lastSession >= Self.sessionRepeat else { return nil }
+        sessionKey = key
+        lastSession = now
+        return event("session", fields: fields)
+    }
+
+    /// The window's summary, or nil when it is not due or was idle. `busy`
+    /// means something is queued for the glasses, which is never idle.
+    func sample(context: [String: Any], busy: Bool = false, now: TimeInterval = G2DisplayDiagnostics.now) -> String? {
+        guard enabled else { return nil }
+        let elapsed = now - started
+        guard elapsed >= 1 else { return nil }
+        started = now
+        let counters = counters
+        let timings = timings
+        self.counters.removeAll(keepingCapacity: true)
+        self.timings.removeAll(keepingCapacity: true)
+        let active = busy || elapsed >= Self.stretchedWindow
+            || counters.keys.contains { !Self.ambientCounters.contains($0) }
+            || timings.keys.contains { !Self.ambientTimings.contains($0) }
+        guard active else { return nil }
+        var fields = context
+        fields["windowMs"] = Int((elapsed * 1000).rounded())
+        for (key, value) in counters {
+            fields[key] = value
+        }
+        // A timing that never reached a millisecond shows no delay: left out.
+        for (key, value) in timings where value.maximum >= 1 {
+            fields[key + "Avg"] = Self.tenths(value.total / Double(value.count))
+            fields[key + "Max"] = Self.tenths(value.maximum)
+        }
+        return event("sample", fields: fields.filter { !Self.isEmpty($0.value) })
+    }
+
+    /// One decimal that serializes as written: a Double 7.2 prints as 7.2000000000000002.
+    private static func tenths(_ value: Double) -> NSDecimalNumber {
+        let scaled = Int((value * 10).rounded())
+        return NSDecimalNumber(mantissa: UInt64(abs(scaled)), exponent: -1, isNegative: scaled < 0)
+    }
+
+    private static func isEmpty(_ value: Any) -> Bool {
+        switch value {
+        case let value as NSDecimalNumber: return value == .zero
+        case let value as Bool: return !value
+        case let value as Int: return value == 0
+        case let value as Double: return value == 0
+        case let value as String: return value.isEmpty
+        default: return false
+        }
+    }
+}

package/ios/Source/sgcs/G2FlashProtocol.swift

@@ -288,8 +288,8 @@ enum G2FlashProtocol {
     }
 
     static let goldenStock = GoldenVector(
-        sha256: "a03fbea9f68a9de6bc271daabb9f3a41c59053d1086622c76a4e990f829cc561",
-        ps: 3_697_284, progEnd: 0x007B_EA64, pass: true
+        sha256: "187ccf2bcc5c17a212106e8a376745511e8289c4232b634a7ea94b9bf25a0979",
+        ps: 3_758_720, progEnd: 0x007C_DA60, pass: true
     )
 
     /// Run the parse+guard on `img` and assert it reproduces the golden vector. Returns

package/ios/Source/sgcs/G2Flasher.swift

@@ -27,18 +27,18 @@ enum G2FirmwareCatalog {
         G2FirmwareArtifact(
             id: "stock",
             displayName: "Stock firmware",
-            version: "2.2.9.22",
-            fileName: "g2-stock-2.2.9.22.evenota.bin",
-            sha256: "a03fbea9f68a9de6bc271daabb9f3a41c59053d1086622c76a4e990f829cc561",
-            size: 4_476_518
+            version: "2.3.0.24",
+            fileName: "g2-stock-2.3.0.24.evenota.bin",
+            sha256: "187ccf2bcc5c17a212106e8a376745511e8289c4232b634a7ea94b9bf25a0979",
+            size: 4_537_963
         ),
         G2FirmwareArtifact(
             id: "glassly-cfw",
-            displayName: "Glassly CFW",
-            version: "2.2.9.22 CFW",
-            fileName: "g2-glassly-cfw-2.2.9.22.evenota.bin",
-            sha256: "ceeede999529505ebc0a1369f57ab3c941273379a90b16669ccd39cc6bd99135",
-            size: 4_515_846
+            displayName: "Glassly CFW v39",
+            version: "2.3.0.24",
+            fileName: "g2-glassly-cfw-2.3.0.24.evenota.bin",
+            sha256: "4c7bf9a552df1a42f26b3378425c7c2121ca4058fed7283ec863c3f8d2cd13fe",
+            size: 4_661_963
         ),
     ]