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

package/ios/Tests/BluetoothSDKTests/G2ImageAckTests.swift

@@ -0,0 +1,104 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+final class G2ImageAckTests: XCTestCase {
+    func testOmittedZeroSessionAndFragmentDecodeAsDefaults() throws {
+        let ack = try XCTUnwrap(ImgAckBox.decodeResult(Data([0x40, 0x04])))
+        XCTAssertEqual(ack.session, 0)
+        XCTAssertEqual(ack.fragment, 0)
+        XCTAssertTrue(ack.success)
+        let explicit = try XCTUnwrap(ImgAckBox.decodeResult(Data([0x18, 0, 0x30, 0, 0x40, 4])))
+        XCTAssertEqual(explicit.session, ack.session)
+        XCTAssertEqual(explicit.fragment, ack.fragment)
+    }
+
+    func testNonzeroSessionAndNackRemainCorrelated() throws {
+        let ack = try XCTUnwrap(ImgAckBox.decodeResult(Data([0x18, 0xFF, 1, 0x30, 2, 0x40, 5])))
+        XCTAssertEqual(ack.session, 255)
+        XCTAssertEqual(ack.fragment, 2)
+        XCTAssertFalse(ack.success)
+        XCTAssertNil(ImgAckBox.decodeResult(Data()))
+        XCTAssertNil(ImgAckBox.decodeResult(Data([0x18, 1])))
+        XCTAssertNil(ImgAckBox.decodeResult(Data([0x1A, 0, 0x40, 4])))
+    }
+
+    @MainActor
+    func testWireAckAtSessionWrapResumesWithoutTimingOut() async throws {
+        let box = ImgAckBox()
+        for session in [254, 255, 0, 1] {
+            // Protobuf encoders can omit default-valued scalar fields.
+            var wire: [UInt8] = [0x40, 4]
+            if session > 0 {
+                wire += session < 128 ? [0x18, UInt8(session)] : [0x18, UInt8(session & 0x7F) | 0x80, 1]
+            }
+            let ack = try XCTUnwrap(ImgAckBox.decodeResult(Data(wire)))
+            let ok = await box.wait(session: session, fragment: 0, timeoutNs: 100_000_000) {
+                XCTAssertTrue(box.resolve(session: ack.session, fragment: ack.fragment, success: ack.success))
+            }
+            XCTAssertTrue(ok)
+            XCTAssertEqual(box.outcome()?.reason, "ack")
+        }
+    }
+
+    @MainActor
+    func testImmediateAckAndDuplicateDuringSustainedTransfers() async {
+        let box = ImgAckBox()
+        // Cross the session wrap repeatedly. No timer from an earlier arming
+        // may complete a newer transfer, including one with the same wire key.
+        for index in 0 ..< 1024 {
+            let session = index % 256
+            let ok = await box.wait(session: session, fragment: 0, timeoutNs: 1_000_000_000) {
+                XCTAssertFalse(box.resolve(session: session, fragment: 1, success: true))
+                XCTAssertTrue(box.resolve(session: session, fragment: 0, success: true))
+                XCTAssertFalse(box.resolve(session: session, fragment: 0, success: true))
+            }
+            XCTAssertTrue(ok)
+        }
+    }
+
+    @MainActor
+    func testCancelledBeforeArmingDoesNotSend() async {
+        let box = ImgAckBox()
+        let task = Task { @MainActor in
+            await box.wait(session: 1, fragment: 0, timeoutNs: 1_000_000_000) {
+                XCTFail("cancelled transfer sent a packet")
+            }
+        }
+        task.cancel()
+        let ok = await task.value
+        XCTAssertFalse(ok)
+    }
+
+    @MainActor
+    func testCancellationReleasesAnArmedWaiter() async {
+        let box = ImgAckBox()
+        let sent = expectation(description: "sent")
+        let task = Task { @MainActor in
+            await box.wait(session: 1, fragment: 0, timeoutNs: 60_000_000_000) {
+                sent.fulfill()
+            }
+        }
+        await fulfillment(of: [sent], timeout: 1)
+        task.cancel()
+        let ok = await task.value
+        XCTAssertFalse(ok)
+        XCTAssertFalse(box.resolve(session: 1, fragment: 0, success: true))
+    }
+
+    func testOldTimeoutCannotResolveReusedSession() async {
+        let box = ImgAckBox()
+        var oldToken: UInt64 = 0
+        let first = await withCheckedContinuation { cont in
+            oldToken = box.arm(session: 1, fragment: 0, cont: cont)
+            box.resolve(session: 1, fragment: 0, success: true)
+        }
+        XCTAssertTrue(first)
+        let second = await withCheckedContinuation { cont in
+            _ = box.arm(session: 1, fragment: 0, cont: cont)
+            box.timeout(token: oldToken)
+            XCTAssertTrue(box.resolve(session: 1, fragment: 0, success: true))
+        }
+        XCTAssertTrue(second)
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2KeyboardTests.swift

@@ -0,0 +1,274 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+/// Pins the keyboard bridge wire format and HID decoding shared with g2flash's
+/// patches/keyboard_core.h and demos/keyboard.test.ts (same vectors).
+final class G2KeyboardTests: XCTestCase {
+    private static let boot: [UInt8] = [
+        0x05, 1, 0x09, 6, 0xA1, 1, 0x05, 7, 0x19, 0xE0, 0x29, 0xE7, 0x15, 0, 0x25, 1, 0x75, 1, 0x95, 8, 0x81, 2,
+        0x75, 8, 0x95, 1, 0x81, 1, 0x95, 6, 0x75, 8, 0x15, 0, 0x25, 0x65, 0x05, 7, 0x19, 0, 0x29, 0x65, 0x81, 0, 0xC0,
+    ]
+
+    private static let numbered: [UInt8] = Array(boot[0 ..< 6]) + [0x85, 1] + Array(boot[6 ..< (boot.count - 1)]) + [
+        0x85, 2, 0x05, 0x0C, 0x15, 0, 0x25, 1, 0x75, 1, 0x95, 3, 0x09, 0xE9, 0x09, 0xEA, 0x09, 0xE2, 0x81, 2,
+        0x75, 5, 0x95, 1, 0x81, 1, 0xC0,
+    ]
+
+    private func le16(_ v: Int) -> [UInt8] {
+        [UInt8(v & 0xFF), UInt8((v >> 8) & 0xFF)]
+    }
+
+    private func le32(_ v: UInt32) -> [UInt8] {
+        [UInt8(v & 0xFF), UInt8((v >> 8) & 0xFF), UInt8((v >> 16) & 0xFF), UInt8(v >> 24)]
+    }
+
+    private func frame(
+        _ kind: UInt8, _ seq: UInt32, _ epoch: Int, _ request: Int, _ code: Int, _ handle: Int,
+        _ data: [UInt8], offset: Int = 0, total: Int? = nil
+    ) -> Data {
+        var p: [UInt8] = [75, 66, 1, kind] + le32(seq) + le16(epoch) + le16(request) + le16(code) + le16(handle)
+        p += le16(total ?? data.count) + le16(offset) + le32(1234) + data
+        return Data(p)
+    }
+
+    private func usages(_ keys: [G2KeyboardHid.Usage]) -> [[Int]] {
+        keys.map { [$0.page, $0.usage] }
+    }
+
+    private func events(_ keys: [G2KeyboardHid.KeyEvent]) -> [[Int]] {
+        keys.map { [$0.page, $0.usage, $0.down ? 1 : 0] }
+    }
+
+    // MARK: - HID decoding
+
+    func testBootArrayModifiersReleaseRepeatsAndRollover() throws {
+        let r = try XCTUnwrap(G2KeyboardHid.parseReportMap(Self.boot)[0])
+        var keys = G2KeyboardHid.HeldKeys()
+        XCTAssertEqual(try events(keys.update(handle: 12, report: r, data: [2, 0, 4, 0, 0, 0, 0, 0])), [[7, 0xE1, 1], [7, 4, 1]])
+        XCTAssertEqual(try keys.update(handle: 12, report: r, data: [2, 0, 4, 0, 0, 0, 0, 0]), [])
+        XCTAssertThrowsError(try keys.update(handle: 12, report: r, data: [0, 0, 1, 1, 1, 1, 1, 1])) { error in
+            XCTAssertTrue("\(error)".contains("rollover"))
+        }
+        XCTAssertEqual(keys.reset().map(\.down), [false, false])
+        XCTAssertThrowsError(try G2KeyboardHid.reportKeys(r, [0])) { XCTAssertTrue("\($0)".contains("length")) }
+    }
+
+    func testHogpReportIdsAreOutOfBandWithConsumerKeys() throws {
+        let maps = try G2KeyboardHid.parseReportMap(Self.numbered)
+        XCTAssertEqual(try usages(G2KeyboardHid.reportKeys(XCTUnwrap(maps[1]), [0, 0, 5, 0, 0, 0, 0, 0])), [[7, 5]])
+        XCTAssertEqual(try usages(G2KeyboardHid.reportKeys(XCTUnwrap(maps[2]), [5])), [[12, 0xE9], [12, 0xE2]])
+        XCTAssertThrowsError(try G2KeyboardHid.reportKeys(XCTUnwrap(maps[2]), [2, 5]))
+    }
+
+    func testNkroBitmapWithUnalignedFieldsAndReportUnion() throws {
+        let map: [UInt8] = [5, 7, 0x19, 4, 0x29, 19, 0x15, 0, 0x25, 1, 0x75, 1, 0x95, 16, 0x81, 2]
+        let r = try XCTUnwrap(G2KeyboardHid.parseReportMap(map)[0])
+        XCTAssertEqual(try usages(G2KeyboardHid.reportKeys(r, [0x81, 0x80])), [[7, 4], [7, 11], [7, 19]])
+        var keys = G2KeyboardHid.HeldKeys()
+        XCTAssertEqual(try keys.update(handle: 10, report: r, data: [1, 0]).count, 1)
+        XCTAssertEqual(try keys.update(handle: 11, report: r, data: [1, 0]), [])
+        XCTAssertEqual(try keys.update(handle: 10, report: r, data: [0, 0]), [])
+        XCTAssertEqual(try events(keys.update(handle: 11, report: r, data: [0, 0])), [[7, 4, 0]])
+    }
+
+    func testArrayValuesIndexUsagesRelativeToLogicalMinimum() throws {
+        let r = try XCTUnwrap(G2KeyboardHid.parseReportMap([5, 7, 0x19, 4, 0x29, 6, 0x15, 1, 0x25, 3, 0x75, 8, 0x95, 1, 0x81, 0])[0])
+        XCTAssertEqual(try usages(G2KeyboardHid.reportKeys(r, [2])), [[7, 5]])
+        XCTAssertEqual(try G2KeyboardHid.reportKeys(r, [0]), [])
+    }
+
+    func testDescriptorBoundsAndMalformedItems() {
+        let malformed: [[UInt8]] = [
+            [], [UInt8](repeating: 0, count: 513), [0xFE], [0x75], [0xB4], [0xC0], [0x85, 0],
+            [0x75, 33, 0x95, 1, 0x81, 2], [0x75, 32, 0x96, 0, 2, 0x81, 2], [0xA1, 1],
+        ]
+        for data in malformed {
+            XCTAssertThrowsError(try G2KeyboardHid.parseReportMap(data))
+        }
+        // Deterministic malformed corpus; parsing must be bounded and never hang.
+        var seed: UInt32 = 1
+        for i in 0 ..< 1000 {
+            let data = (0 ..< (i % 128 + 1)).map { _ -> UInt8 in
+                seed = seed &* 1_664_525 &+ 1_013_904_223
+                return UInt8(seed >> 24)
+            }
+            _ = try? G2KeyboardHid.parseReportMap(data)
+        }
+    }
+
+    // MARK: - Relay protocol
+
+    func testShortUuidsEncodedWithTheBluetoothBase() throws {
+        let uuid = try G2KeyboardClient.AttributeUuid([0xFB, 0x34, 0x9B, 0x5F, 0x80, 0, 0, 0x80, 0, 0x10, 0, 0, 0x12, 0x18, 0, 0])
+        XCTAssertEqual(uuid, .short(0x1812))
+    }
+
+    func testWireControlHasTheDedicatedFieldAndEpoch() {
+        let packet = [UInt8](G2KeyboardProtocol.controlPacket(op: .connect, request: 0x1234, epoch: 0x5678, body: [1, 2, 3, 4, 5, 6, 7], magic: 5))
+        XCTAssertEqual(packet, [8, 2, 16, 5, 0x22, 2, 8, 1, 0x92, 8, 15, 75, 66, 1, 4, 0x34, 0x12, 0x78, 0x56, 1, 2, 3, 4, 5, 6, 7])
+        // Magic ids above 127 take two varint bytes.
+        XCTAssertEqual(Array([UInt8](G2KeyboardProtocol.controlPacket(op: .query, request: 1, epoch: 0, magic: 200))[0 ..< 5]), [8, 2, 16, 0xC8, 0x01])
+    }
+
+    func testFragmentsDuplicatesGapsEpochsAndSequenceWrap() {
+        var stream = G2KeyboardProtocol.RecordAssembler()
+        let data = (0 ..< 200).map { UInt8($0) }
+        XCTAssertNil(stream.push(frame(3, 0xFFFF_FFFF, 1, 0, 13, 33, Array(data[0 ..< 96]), offset: 0, total: 200)))
+        XCTAssertNil(stream.push(frame(3, 0xFFFF_FFFF, 1, 0, 13, 33, Array(data[96 ..< 192]), offset: 96, total: 200)))
+        XCTAssertEqual(stream.push(frame(3, 0xFFFF_FFFF, 1, 0, 13, 33, Array(data[192...]), offset: 192, total: 200))?.data, data)
+        let status = frame(1, 0, 1, 0, 0, 0, [UInt8](repeating: 0, count: 10))
+        XCTAssertEqual(stream.push(status)?.sequence, 0)
+        XCTAssertNil(stream.push(status))
+        XCTAssertEqual(stream.gaps, 1)
+        _ = stream.push(frame(1, 2, 1, 0, 0, 0, [UInt8](repeating: 0, count: 10)))
+        XCTAssertEqual(stream.gaps, 2)
+        XCTAssertNil(stream.push(status))
+        XCTAssertEqual(stream.gaps, 2)
+        _ = stream.push(frame(1, 3, 2, 0, 0, 0, [UInt8](repeating: 0, count: 10)))
+        XCTAssertEqual(stream.gaps, 3)
+    }
+
+    func testMismatchedFragmentsNeverEmitPartialInput() {
+        var stream = G2KeyboardProtocol.RecordAssembler()
+        _ = stream.push(frame(3, 1, 1, 0, 13, 10, [UInt8](repeating: 0, count: 96), offset: 0, total: 100))
+        XCTAssertNil(stream.push(frame(3, 1, 1, 0, 13, 11, [UInt8](repeating: 0, count: 4), offset: 96, total: 100)))
+        XCTAssertEqual(stream.gaps, 2)
+        XCTAssertNil(stream.push(frame(3, 1, 1, 0, 13, 10, [UInt8](repeating: 0, count: 4), offset: 96, total: 100)))
+        XCTAssertNil(stream.push(Data(repeating: 0, count: 513)))
+    }
+
+    func testAdvertParsingNamesHidDevicesAndReversesAddresses() throws {
+        let body: [UInt8] = [1, 0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA, 0xC4, 0, 12, 3, 3, 0x12, 0x18, 5, 9, 0x4B, 0x65, 0x79, 0x73]
+        let advert = try XCTUnwrap(G2KeyboardProtocol.Advert.parse(body))
+        XCTAssertEqual(advert.addressText, "aa:bb:cc:dd:ee:ff")
+        XCTAssertEqual(advert.rssi, -60)
+        XCTAssertTrue(advert.hid)
+        XCTAssertEqual(advert.name, "Keys")
+        XCTAssertEqual(G2KeyboardProtocol.address(fromText: advert.addressText), advert.address)
+        XCTAssertNil(G2KeyboardProtocol.address(fromText: "aa:bb"))
+    }
+
+    func testAdvertAppearanceMarksHidAndScanResponseMerges() throws {
+        // ADV_IND with only a keyboard appearance (0x03C1), no 0x1812 service list.
+        let adv: [UInt8] = [1, 0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA, 0xC4, 0, 4, 3, 0x19, 0xC1, 0x03]
+        let first = try XCTUnwrap(G2KeyboardProtocol.Advert.parse(adv))
+        XCTAssertTrue(first.hid)
+        XCTAssertEqual(first.name, "")
+        // SCAN_RSP for the same address carries the name and a better RSSI.
+        let rsp: [UInt8] = [1, 0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA, 0xCE, 4, 6, 5, 9, 0x4B, 0x65, 0x79, 0x73]
+        let second = try XCTUnwrap(G2KeyboardProtocol.Advert.parse(rsp))
+        XCTAssertFalse(second.hid)
+        let merged = first.merging(second)
+        XCTAssertEqual(merged.name, "Keys")
+        XCTAssertTrue(merged.hid)
+        XCTAssertEqual(merged.rssi, -50)
+        XCTAssertEqual(merged.address, first.address)
+        // A non-HID appearance (generic phone) does not qualify.
+        let phone: [UInt8] = [1, 0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA, 0xC4, 0, 4, 3, 0x19, 0x40, 0x00]
+        XCTAssertFalse(try XCTUnwrap(G2KeyboardProtocol.Advert.parse(phone)).hid)
+    }
+
+    // MARK: - Simulated HOGP keyboard
+
+    @MainActor
+    func testFullSimulatedHogpDiscoveryTypingAndLossRecovery() async throws {
+        struct Attr { let uuid: Int; let value: [UInt8] }
+        var attrs: [Int: Attr] = [:]
+        func add(_ h: Int, _ uuid: Int, _ bytes: [UInt8]) {
+            attrs[h] = Attr(uuid: uuid, value: bytes)
+        }
+        let mockMap = Array(Self.numbered[0 ..< (Self.numbered.count - 1)]) + [0x85, 3, 0x05, 6, 0x09, 0x20, 0x15, 0, 0x25, 100, 0x75, 8, 0x95, 1, 0x81, 2, 0xC0]
+        add(1, 0x2800, [1, 0x18]); add(2, 0x2803, [0x20, 3, 0, 5, 0x2A]); add(3, 0x2A05, []); add(4, 0x2902, [0, 0])
+        add(20, 0x2800, [0x12, 0x18])
+        add(21, 0x2803, [2, 22, 0, 0x4B, 0x2A]); add(22, 0x2A4B, mockMap); add(23, 0x2907, [0x19, 0x2A])
+        add(24, 0x2803, [6, 25, 0, 0x4E, 0x2A]); add(25, 0x2A4E, [1])
+        add(26, 0x2803, [0x12, 27, 0, 0x4D, 0x2A]); add(27, 0x2A4D, []); add(28, 0x2902, [0, 0]); add(29, 0x2908, [1, 1])
+        add(30, 0x2803, [0x12, 31, 0, 0x4D, 0x2A]); add(31, 0x2A4D, []); add(32, 0x2902, [0, 0]); add(33, 0x2908, [2, 1])
+        add(40, 0x2800, [0x0F, 0x18]); add(41, 0x2803, [0x12, 42, 0, 0x19, 0x2A]); add(42, 0x2A19, [100]); add(43, 0x2902, [0, 0]); add(44, 0x2908, [3, 1])
+
+        var seq: UInt32 = 0
+        var epoch = 0
+        var writes: [Int] = []
+        var watches: [Int] = []
+        var typed: [[Int]] = []
+        var client: G2KeyboardClient!
+        func emit(_ kind: UInt8, _ request: Int, _ code: Int, _ handle: Int, _ data: [UInt8]) {
+            seq += 1
+            client.accept(frame(kind, seq, epoch, request, code, handle, data))
+        }
+        let sorted = { attrs.keys.sorted() }
+        client = G2KeyboardClient(send: { pb, _ in
+            let p = [UInt8](pb)
+            // Field 130 (tag 0x92 0x08) follows a magic varint of one or two bytes.
+            let tag = p.indices.first { p[$0] == 0x92 && p[$0 + 1] == 0x08 }!
+            let body = Array(p[(tag + 3)...])
+            let op = Int(body[3]), req = Int(G2KeyboardProtocol.u16(body, 4))
+            let h = body.count >= 10 ? Int(G2KeyboardProtocol.u16(body, 8)) : 0
+            switch op {
+            case 1: emit(1, req, 0, 0, [1, 0, 0, 0, 0, 0, 0, 0, 0, 0])
+            case 4:
+                epoch += 1
+                emit(1, req, 0, 0, [1, 3, 1, 1, 0, 0, 0, 0, 0, 0])
+            case 9:
+                let batch = sorted().filter { $0 >= h }.prefix(4)
+                var payload: [UInt8] = []
+                if !batch.isEmpty {
+                    payload = [1] + batch.flatMap { handle in self.le16(handle) + self.le16(attrs[handle]!.uuid) }
+                }
+                emit(2, req, batch.isEmpty ? (10 << 8) | 2 : 2, h, payload)
+            case 10:
+                let data = attrs[h]!.value
+                let offset = Int(G2KeyboardProtocol.u16(body, 10))
+                let status = offset >= data.count ? (7 << 8) | 6 : (offset > 0 ? 6 : 5)
+                emit(2, req, status, h, Array(data[min(offset, data.count) ..< min(offset + 20, data.count)]))
+            case 11:
+                writes.append(h)
+                emit(2, req, body[10] != 0 ? 10 : 9, h, [])
+            case 12:
+                let count = Int(body[8])
+                watches = (0 ..< count).map { Int(G2KeyboardProtocol.u16(body, 9 + 2 * $0)) }
+                emit(1, req, 0, 0, [1, 3, 1, 1, 0, 0, 0, 0, 0, 0])
+            default:
+                XCTFail("Unexpected op \(op)")
+            }
+        }, onEvent: { event in
+            if case let .keys(events) = event {
+                typed += events.map { [$0.usage, $0.down ? 1 : 0] }
+            }
+        })
+
+        try await client.enable()
+        try await client.connect(addressType: 1, address: [0, 0, 0, 0, 0, 0])
+        let config = try await client.configure()
+        XCTAssertEqual(watches, [27, 31, 42, 3])
+        XCTAssertEqual(writes, [25, 4, 28, 32, 43])
+        XCTAssertEqual(config.reports.map(\.id), [1, 2, 3])
+
+        emit(3, 0, 13, 27, [0, 0, 4, 0, 0, 0, 0, 0])
+        emit(3, 0, 13, 31, [1])
+        XCTAssertEqual(typed, [[4, 1], [0xE9, 1]])
+        seq += 1 // release lost in the firmware queue or phone notification path
+        emit(1, 0, 0, 0, [1, 3, 1, 1, 0, 0, 0, 0, 0, 0])
+        XCTAssertEqual(typed.suffix(2).map { $0[1] }, [0, 0])
+
+        let restored = G2KeyboardClient(send: { _, _ in }, onEvent: { event in
+            if case let .keys(events) = event {
+                typed += events.map { [$0.usage, $0.down ? 1 : 0] }
+            }
+        })
+        try restored.restore(config)
+        seq += 1
+        restored.accept(frame(3, seq, epoch, 0, 13, 27, [0, 0, 5, 0, 0, 0, 0, 0]))
+        XCTAssertEqual(typed.last, [5, 1])
+        restored.lostPhoneLink()
+        XCTAssertEqual(typed.last, [5, 0])
+
+        emit(3, 0, 14, 3, [1, 0, 255, 255]) // Service Changed invalidates the mapping
+        let count = typed.count
+        emit(3, 0, 13, 27, [0, 0, 6, 0, 0, 0, 0, 0])
+        XCTAssertEqual(typed.count, count)
+        client.close()
+        restored.close()
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2NotifyFileTests.swift

@@ -22,7 +22,7 @@ final class G2NotifyFileTests: XCTestCase {
         XCTAssertEqual(G2NotifyFile.crc32c(content), 0xE96D_1DA8)
 
         let header = G2NotifyFile.fileCheckHeader(
-            filename: G2NotifyFile.whitelistFilename, content: content
+            filename: G2NotifyFile.whitelistFilename, content: content, fileType: .whitelist
         )
         XCTAssertEqual(header.count, 93)
 
@@ -33,10 +33,18 @@ final class G2NotifyFileTests: XCTestCase {
             }
             return value
         }
-        XCTAssertEqual(u32(0), 0x100) // mode
-        XCTAssertEqual(u32(4), 41472) // size = len * 256
-        XCTAssertEqual(u32(8), 0x6D1D_A800) // checksum = crc << 8
-        XCTAssertEqual(header[12], 0xE9) // extra = crc >> 24
+        XCTAssertEqual(header[0], 0x00) // SEND_START
+        XCTAssertEqual(u32(1), 0) // NOTIFICATION_JSON_WHITELIST
+        XCTAssertEqual(u32(5), 162) // size
+        XCTAssertEqual(u32(9), 0xE96D_1DA8) // crc32c
+
+        // The docs' shifted view of the same bytes: "mode" 0x100 would have been
+        // the Android-notification type, which is what put blank cards in the
+        // stock viewer.
+        XCTAssertEqual(u32(0), 0x000) // mode == fileType << 8
+        XCTAssertEqual(u32(4), 41472) // size * 256
+        XCTAssertEqual(u32(8), 0x6D1D_A800) // crc << 8
+        XCTAssertEqual(header[12], 0xE9) // crc >> 24
 
         let nameBytes = header.subdata(in: 13 ..< 93)
         let expectedName = Array(G2NotifyFile.whitelistFilename.utf8)
@@ -44,6 +52,14 @@ final class G2NotifyFileTests: XCTestCase {
         XCTAssertTrue(nameBytes.dropFirst(expectedName.count).allSatisfy { $0 == 0 })
     }
 
+    func testFileCheckHeaderTypesTheAndroidNotification() {
+        let header = G2NotifyFile.fileCheckHeader(
+            filename: G2NotifyFile.whitelistFilename, content: Data("{}".utf8), fileType: .androidNotification
+        )
+        XCTAssertEqual(header[0], 0x00)
+        XCTAssertEqual(Array(header[1 ..< 5]), [0x01, 0x00, 0x00, 0x00])
+    }
+
     func testWhitelistJsonShape() throws {
         let json = G2NotifyFile.whitelistJson(
             filterEnabled: true,

package/ios/Tests/BluetoothSDKTests/G2RingBatteryTests.swift

@@ -0,0 +1,56 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+final class G2RingBatteryTests: XCTestCase {
+    func testConnectedBatteryIncludingEmptyFullAndCharging() {
+        for level: UInt8 in [0, 62, 100] {
+            XCTAssertEqual(G2RingBattery.decode(Data([0x52, 0x42, 1, 3, level])),
+                           G2RingBattery(connected: true, level: Int(level), charging: false))
+            XCTAssertEqual(G2RingBattery.decode(Data([0x52, 0x42, 1, 7, level])),
+                           G2RingBattery(connected: true, level: Int(level), charging: true))
+        }
+    }
+
+    func testDisconnectedAndUnknownReportsClearCachedBattery() {
+        XCTAssertEqual(G2RingBattery.decode(Data([0x52, 0x42, 1, 0, 255])), .disconnected)
+        XCTAssertEqual(G2RingBattery.decode(Data([0x52, 0x42, 1, 6, 62])), .disconnected)
+        XCTAssertEqual(G2RingBattery.decode(Data([0x52, 0x42, 1, 1, 255])),
+                       G2RingBattery(connected: true, level: -1, charging: false))
+        XCTAssertEqual(G2RingBattery.decode(Data([0x52, 0x42, 1, 5, 62])),
+                       G2RingBattery(connected: true, level: -1, charging: false))
+    }
+
+    func testBatterySurvivesSnapshotAndPartialStatusBridge() throws {
+        let battery = try XCTUnwrap(G2RingBattery.decode(Data([0x52, 0x42, 1, 7, 62])))
+        let values: [String: Any] = [
+            "ringConnected": battery.connected, "ringBatteryLevel": battery.level, "ringCharging": battery.charging,
+        ]
+        let status = GlassesStatus(values: values)
+        XCTAssertEqual(status.dictionary["ringBatteryLevel"] as? Int, 62)
+        XCTAssertTrue(status.ringConnected)
+        XCTAssertTrue(status.ringCharging)
+        XCTAssertFalse(status.controllerConnected)
+        XCTAssertEqual(status.controllerBatteryLevel, -1)
+        let update = GlassesStatusUpdate(values: values)
+        XCTAssertEqual(update.dictionary as NSDictionary, values as NSDictionary)
+        XCTAssertEqual(update.ringBatteryLevel, 62)
+        XCTAssertNil(GlassesStatusUpdate(values: [:]).ringBatteryLevel)
+        XCTAssertEqual(GlassesStatus(values: [:]).ringBatteryLevel, -1)
+        let disconnected = status.disconnected()
+        XCTAssertFalse(disconnected.ringConnected)
+        XCTAssertEqual(disconnected.ringBatteryLevel, -1)
+        XCTAssertFalse(disconnected.ringCharging)
+    }
+
+    func testMalformedReportsAreIgnored() {
+        let malformed: [[UInt8]] = [
+            [], [0x52, 0x42, 1, 3], [0x52, 0x42, 1, 3, 62, 0],
+            [0x41, 0x42, 1, 3, 62], [0x52, 0x41, 1, 3, 62],
+            [0x52, 0x42, 2, 3, 62], [0x52, 0x42, 1, 3, 101], [0x52, 0x42, 1, 3, 255],
+        ]
+        for bytes in malformed {
+            XCTAssertNil(G2RingBattery.decode(Data(bytes)), "Invalid report: \(bytes)")
+        }
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2SensorsTests.swift

@@ -0,0 +1,56 @@
+@testable import BluetoothSDK
+import XCTest
+
+final class G2SensorsTests: XCTestCase {
+    func testNorthMayOmitTheProtobufScalarButMalformedHeadingsAreRejected() {
+        XCTAssertEqual(G2Sensors.heading([:]), 0)
+        XCTAssertEqual(G2Sensors.heading([1: Int32(0)]), 0)
+        XCTAssertEqual(G2Sensors.heading([1: Int32(359)]), 359)
+        XCTAssertNil(G2Sensors.heading([1: Int32(360)]))
+        XCTAssertNil(G2Sensors.heading([1: Data([0])]))
+    }
+
+    func testControlsMatchUpstreamModesAndLittleEndianOptions() {
+        XCTAssertEqual(G2Sensors.command(sensor: "light", operation: "query", options: [:]), Data([16, 0]))
+        XCTAssertEqual(G2Sensors.command(sensor: "light", operation: "start", options: [:]), Data([16, 1, 1, 244, 1, 1, 0, 136, 19]))
+        XCTAssertEqual(G2Sensors.command(sensor: "compass", operation: "start", options: ["intervalMs": 250, "minChangeDegrees": 0]), Data([10, 2, 250, 0, 0, 0]))
+        XCTAssertEqual(G2Sensors.command(sensor: "light", operation: "stop", options: [:]), Data([16, 2]))
+        XCTAssertEqual(G2Sensors.command(sensor: "compass", operation: "stop", options: [:]), Data([10, 0]))
+        XCTAssertNil(G2Sensors.command(sensor: "light", operation: "start", options: ["intervalMs": 99]))
+        XCTAssertNil(G2Sensors.command(sensor: "compass", operation: "start", options: ["intervalMs": .nan]))
+        XCTAssertNil(G2Sensors.command(sensor: "compass", operation: "start", options: ["minChangeDegrees": 0.5]))
+    }
+
+    func testLightReportPreservesRawValuesAndFreshness() throws {
+        let bytes: [UInt8] = [65, 76, 1, 2, 15, 3, 210, 4, 0, 0, 46, 22, 0, 0, 250, 0, 9, 3, 0, 4, 66, 0, 0, 240]
+        let report = try XCTUnwrap(G2Sensors.light(Data(bytes)))
+        XCTAssertEqual(report["reason"] as? String, "poll")
+        XCTAssertEqual(report["value"] as? Int64, 1234)
+        XCTAssertEqual(report["peak"] as? Int64, 5678)
+        XCTAssertEqual(report["sampleTimestampMs"] as? Int64, 4_026_531_906)
+        XCTAssertEqual(report["readSucceeded"] as? Bool, true)
+        XCTAssertEqual(report["autoBrightness"] as? Bool, true)
+        XCTAssertEqual(report["passive"] as? Bool, true)
+        XCTAssertNil(G2Sensors.light(Data(bytes.dropLast())))
+        var stale = bytes; stale[4] = 0
+        XCTAssertEqual(G2Sensors.light(Data(stale))?["readSucceeded"] as? Bool, false)
+        stale[2] = 2
+        XCTAssertNil(G2Sensors.light(Data(stale)))
+    }
+
+    func testCompassDiagnosticsAndUnknownMarkers() throws {
+        var bytes: [UInt8] = [67, 77, 1, 3, 1, 2, 143, 0, 66, 0, 0, 240]
+        let report = try XCTUnwrap(G2Sensors.compass(Data(bytes)))
+        XCTAssertEqual(report["source"] as? String, "gmrv")
+        XCTAssertEqual(report["accuracy"] as? Int, 3)
+        XCTAssertEqual(report["sampleMatched"] as? Bool, true)
+        XCTAssertEqual(report["magneticDataFresh"] as? Bool, true)
+        XCTAssertEqual(report["sampleTimestampMs"] as? Int64, 4_026_531_906)
+        bytes[3] = 255; bytes[4] = 255; bytes[5] = 0; bytes[6] = 0
+        XCTAssertTrue(G2Sensors.compass(Data(bytes))?["accuracy"] is NSNull)
+        XCTAssertEqual(G2Sensors.compass(Data(bytes))?["sampleMatched"] as? Bool, false)
+        bytes[3] = 4
+        XCTAssertNil(G2Sensors.compass(Data(bytes)))
+        XCTAssertNil(G2Sensors.compass(Data(bytes.dropLast())))
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2TouchInputTests.swift

@@ -0,0 +1,71 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+final class G2TouchInputTests: XCTestCase {
+    private func fields(event: Int32, wire: UInt8, tick: UInt32 = 123) -> [Int: Any] {
+        [1: event, 2: Int32(2), 100: Data([
+            0x52, 0x49, 1, 1, wire, 0, 0, 0,
+            UInt8(truncatingIfNeeded: tick), UInt8(truncatingIfNeeded: tick >> 8),
+            UInt8(truncatingIfNeeded: tick >> 16), UInt8(truncatingIfNeeded: tick >> 24),
+        ])]
+    }
+
+    func testRawRingCompletionsSurviveCloselySpacedInput() throws {
+        var debounce = G2TouchDebounce()
+        // swipe, next touch_down, click: the old global 100 ms gate lost the
+        // click and left GestureDotsService holding the second touch_down.
+        for (event, wire) in [(Int32(1), UInt8(4)), (14, 10), (0, 1)] {
+            let ring = try XCTUnwrap(G2RingInput(fields: fields(event: event, wire: wire)))
+            XCTAssertTrue(debounce.accepts(event: event, ring: ring, receivedAt: 1))
+        }
+    }
+
+    func testDelayedProcessingUsesReceiptTimeForLegacyInput() {
+        var debounce = G2TouchDebounce()
+        // These calls run together, but the BLE callbacks arrived a second apart.
+        XCTAssertTrue(debounce.accepts(event: 0, ring: nil, receivedAt: 1))
+        XCTAssertTrue(debounce.accepts(event: 0, ring: nil, receivedAt: 2))
+        XCTAssertFalse(debounce.accepts(event: 0, ring: nil, receivedAt: 2.01))
+    }
+
+    func testEdgesAndUnknownReportsDoNotConsumeLegacyDebounce() {
+        var debounce = G2TouchDebounce()
+        for event: Int32 in [9, 10, 14, 127] {
+            XCTAssertTrue(debounce.accepts(event: event, ring: nil, receivedAt: 1))
+        }
+        XCTAssertTrue(debounce.accepts(event: 0, ring: nil, receivedAt: 1))
+        XCTAssertFalse(debounce.accepts(event: 0, ring: nil, receivedAt: 1.01))
+        XCTAssertTrue(debounce.accepts(event: 10, ring: nil, receivedAt: 1.02))
+    }
+
+    func testRingInputDoesNotSuppressIndependentTempleInput() throws {
+        var debounce = G2TouchDebounce()
+        let ring = try XCTUnwrap(G2RingInput(fields: fields(event: 0, wire: 1)))
+        XCTAssertTrue(debounce.accepts(event: 0, ring: ring, receivedAt: 1))
+        XCTAssertTrue(debounce.accepts(event: 0, ring: nil, receivedAt: 1))
+    }
+
+    func testRingMetadataValidatesSourceFormatAndEventMapping() throws {
+        let valid = fields(event: 10, wire: 8, tick: 0xF123_4567)
+        let ring = try XCTUnwrap(G2RingInput(fields: valid))
+        XCTAssertEqual(ring.wireType, 8)
+        XCTAssertEqual(ring.tick, 0xF123_4567)
+        for key in [1, 2, 100] {
+            var malformed = valid
+            malformed.removeValue(forKey: key)
+            XCTAssertNil(G2RingInput(fields: malformed))
+        }
+        for index in [0, 1, 2, 3, 4, 7] {
+            var malformed = valid
+            var bytes = try XCTUnwrap(valid[100] as? Data)
+            bytes[index] = 255
+            malformed[100] = bytes
+            XCTAssertNil(G2RingInput(fields: malformed))
+        }
+        var truncated = valid
+        truncated[100] = Data([0x52, 0x49])
+        XCTAssertNil(G2RingInput(fields: truncated))
+        XCTAssertNotNil(G2RingInput(fields: fields(event: 127, wire: 255)))
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2WritePacingTests.swift

@@ -0,0 +1,35 @@
+@testable import BluetoothSDK
+import UIKit
+import XCTest
+
+final class G2WritePacingTests: XCTestCase {
+    func testBackgroundingUnblocksAWriterWithNoCreditsAndForegroundingRestoresTheGate() {
+        // Model a false readiness flag across lifecycle transitions. The
+        // drainer must reselect its policy while a packet waits to be sent.
+        var submitted = 0
+        let transitions: [(UIApplication.State, Int)] = [(.active, 0), (.inactive, 1), (.background, 2), (.active, 2)]
+        for (state, expectedSubmissions) in transitions {
+            let pacing = G2WritePacing(cfwEnabled: true, applicationState: state)
+            if pacing.canWrite(peripheralReady: false) {
+                submitted += 1
+                XCTAssertEqual(pacing, .timed)
+                XCTAssertEqual(G2WritePacing.packetDelayNs, 6_000_000)
+            }
+            XCTAssertEqual(submitted, expectedSubmissions)
+        }
+        XCTAssertEqual(submitted, 2)
+        let resumed = G2WritePacing(cfwEnabled: true, applicationState: .active)
+        XCTAssertFalse(resumed.canWrite(peripheralReady: false))
+        XCTAssertTrue(resumed.canWrite(peripheralReady: true))
+        XCTAssertEqual(resumed, .creditBurst)
+    }
+
+    func testStockKeepsTimedPacingRegardlessOfReadinessOrApplicationState() {
+        for state in [UIApplication.State.active, .inactive, .background] {
+            let pacing = G2WritePacing(cfwEnabled: false, applicationState: state)
+            XCTAssertEqual(pacing, .timed)
+            XCTAssertTrue(pacing.canWrite(peripheralReady: false))
+            XCTAssertTrue(pacing.canWrite(peripheralReady: true))
+        }
+    }
+}