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

package/ios/Source/sgcs/G2Keyboard.swift

@@ -0,0 +1,780 @@
+import Foundation
+
+/// Glassly CFW BLE keyboard bridge (contract revision 39). The right lens
+/// acts as a BLE central for one HID-over-GATT keyboard; the phone drives
+/// the connection over private sid-0x09 fields and receives raw input reports
+/// back. The wire format is pinned by `patches/keyboard_core.h` and documented
+/// in `docs/keyboard.md` in g2flash.
+///
+/// Phone -> glasses, field 130 on a cmd=2 settings request with a magic id:
+///   `['K','B',1,op, request LE16, epoch LE16, body…]` (at most 80 bytes).
+/// Glasses -> phone, field 131 on cmd=3 EVENT notifications:
+///   `['K','B',1,kind, sequence LE32, epoch LE16, request LE16, code LE16,
+///     handle LE16, total LE16, offset LE16, timestamp LE32, fragment…]`.
+enum G2KeyboardProtocol {
+    static let protocolVersion: UInt8 = 1
+
+    enum Op: UInt8 {
+        case query = 0, enable = 1, disable = 2, scan = 3, connect = 4, disconnect = 5,
+             pair = 6, auth = 7, compare = 8, find = 9, read = 10, write = 11, watch = 12
+    }
+
+    enum Kind: UInt8 {
+        case status = 1, att = 2, input = 3, dm = 4, advert = 5
+    }
+
+    /// Firmware control error codes carried by STATUS records.
+    static func errorName(_ code: UInt16) -> String {
+        switch code {
+        case 0: "ok"
+        case 1: "bad request"
+        case 2: "keyboard bridge disabled"
+        case 3: "busy"
+        case 4: "stale epoch"
+        case 5: "no connection or bond space"
+        case 6: "not connected"
+        case 7: "not encrypted"
+        case 8: "timeout"
+        case 9: "allocation failure"
+        default: "error \(code)"
+        }
+    }
+
+    struct Record: Equatable {
+        let kind: UInt8
+        let sequence: UInt32
+        let epoch: UInt16
+        let request: UInt16
+        let code: UInt16
+        let handle: UInt16
+        let timestamp: UInt32
+        var data: [UInt8]
+    }
+
+    /// G2SettingPackage{commandId=2, magic, field 4 {1:1}, field 130}: the
+    /// keyboard control rides an ordinary settings request so the stock parser
+    /// still runs; the firmware only applies it on the right lens.
+    static func controlPacket(op: Op, request: UInt16, epoch: UInt16, body: [UInt8] = [], magic: UInt8 = 1) -> Data {
+        precondition(body.count <= 72, "keyboard control bounds")
+        let data: [UInt8] = [0x4B, 0x42, protocolVersion, op.rawValue] + le16(request) + le16(epoch) + body
+        var packet: [UInt8] = [0x08, 0x02, 0x10] + varint(UInt32(magic))
+        packet += [0x22, 0x02, 0x08, 0x01, 0x92, 0x08, UInt8(data.count)] + data
+        return Data(packet)
+    }
+
+    static func le16(_ v: UInt16) -> [UInt8] {
+        [UInt8(v & 0xFF), UInt8(v >> 8)]
+    }
+
+    static func u16(_ b: [UInt8], _ i: Int) -> UInt16 {
+        UInt16(b[i]) | (UInt16(b[i + 1]) << 8)
+    }
+
+    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)
+    }
+
+    private static func varint(_ v: UInt32) -> [UInt8] {
+        var out: [UInt8] = []
+        var value = v
+        while value >= 0x80 {
+            out.append(UInt8(value & 0x7F) | 0x80)
+            value >>= 7
+        }
+        out.append(UInt8(value))
+        return out
+    }
+
+    /// Bounded, ordered reassembly of field-131 fragments. A gap (lost or
+    /// out-of-order event, epoch change, malformed fragment) is reported so the
+    /// caller releases every held key and cancels setup transactions; heartbeats
+    /// make a lost final release visible.
+    struct RecordAssembler {
+        private var epoch: UInt16?
+        private var last: UInt32?
+        private var fragment: (record: Record, total: Int, used: Int)?
+        private(set) var gaps = 0
+
+        mutating func reset() {
+            epoch = nil
+            last = nil
+            fragment = nil
+            gaps += 1
+        }
+
+        /// Feed one field-131 payload. Returns a complete record, or nil while a
+        /// fragmented record is still arriving. `gaps` increments on any break.
+        mutating func push(_ payload: Data) -> Record? {
+            let p = [UInt8](payload)
+            func invalid() -> Record? {
+                fragment = nil
+                gaps += 1
+                return nil
+            }
+            guard p.count >= 24, p.count <= 120, p[0] == 0x4B, p[1] == 0x42, p[2] == G2KeyboardProtocol.protocolVersion
+            else { return invalid() }
+            let r = Record(
+                kind: p[3], sequence: u32(p, 4), epoch: u16(p, 8), request: u16(p, 10), code: u16(p, 12),
+                handle: u16(p, 14), timestamp: u32(p, 20), data: []
+            )
+            let total = Int(u16(p, 16))
+            let offset = Int(u16(p, 18))
+            let n = p.count - 24
+            if r.kind < 1 || r.kind > 5 || total > 512 || offset + n > total || (total > 0 && n == 0) {
+                return invalid()
+            }
+            if epoch != r.epoch {
+                gaps += 1
+                fragment = nil
+                last = nil
+                epoch = r.epoch
+            }
+            if offset == 0 {
+                if let last {
+                    let distance = r.sequence &- last
+                    if distance == 0 || distance >= 0x8000_0000 {
+                        return nil
+                    } // duplicate/old delivery
+                }
+                if fragment != nil || (last != nil && r.sequence != last! &+ 1) {
+                    gaps += 1
+                }
+                last = r.sequence
+                var started = r
+                started.data = [UInt8](repeating: 0, count: total)
+                fragment = (started, total, 0)
+            }
+            guard var f = fragment, f.used == offset, f.total == total, f.record.sequence == r.sequence,
+                  f.record.kind == r.kind, f.record.request == r.request, f.record.code == r.code,
+                  f.record.handle == r.handle, f.record.timestamp == r.timestamp
+            else { return invalid() }
+            f.record.data.replaceSubrange(offset ..< offset + n, with: p[24...])
+            f.used += n
+            if f.used != total {
+                fragment = f
+                return nil
+            }
+            fragment = nil
+            return f.record
+        }
+    }
+
+    /// Parsed ADVERT record body: addrType, addr[6] (LSB first), RSSI, event type, AD data.
+    struct Advert: Equatable {
+        let addressType: UInt8
+        /// Little-endian as the controller reports it; `addressText` is the usual MSB-first form.
+        let address: [UInt8]
+        let rssi: Int8
+        let name: String
+        let hid: Bool
+
+        var addressText: String {
+            address.reversed().map { String(format: "%02x", $0) }.joined(separator: ":")
+        }
+
+        /// Fold a later record for the same advertiser (typically its scan
+        /// response, which is where the name usually rides) into this one:
+        /// keep a name once seen, HID once seen, and the best signal.
+        func merging(_ other: Advert) -> Advert {
+            Advert(
+                addressType: addressType, address: address, rssi: max(rssi, other.rssi),
+                name: name.isEmpty ? other.name : name, hid: hid || other.hid
+            )
+        }
+
+        static func parse(_ body: [UInt8]) -> Advert? {
+            guard body.count >= 10 else { return nil }
+            var name = ""
+            var hid = false
+            var i = 10
+            while i < body.count {
+                let n = Int(body[i])
+                i += 1
+                if n == 0 || i + n > body.count {
+                    break
+                }
+                let type = body[i]
+                if type == 8 || type == 9 {
+                    name = String(decoding: body[(i + 1) ..< (i + n)], as: UTF8.self)
+                }
+                if type == 2 || type == 3 {
+                    var j = i + 1
+                    while j + 1 < i + n {
+                        if body[j] == 0x12, body[j + 1] == 0x18 {
+                            hid = true
+                        }
+                        j += 2
+                    }
+                }
+                // Appearance 0x03C0..0x03FF is the HID category (0x03C1 keyboard);
+                // some keyboards advertise that without the 0x1812 service list.
+                if type == 0x19, n >= 3, body[i + 2] == 0x03, body[i + 1] >= 0xC0 {
+                    hid = true
+                }
+                i += n
+            }
+            return Advert(
+                addressType: body[0], address: Array(body[1 ..< 7]), rssi: Int8(bitPattern: body[7]),
+                name: name, hid: hid
+            )
+        }
+    }
+
+    /// Parse "aa:bb:cc:dd:ee:ff" into the controller's LSB-first byte order.
+    static func address(fromText text: String) -> [UInt8]? {
+        let parts = text.split(separator: ":")
+        guard parts.count == 6 else { return nil }
+        var bytes: [UInt8] = []
+        for part in parts {
+            guard part.count == 2, let value = UInt8(part, radix: 16) else { return nil }
+            bytes.append(value)
+        }
+        return bytes.reversed()
+    }
+}
+
+/// Transport-independent keyboard client: enable/scan/connect/pair, HOGP
+/// discovery, subscription, and raw input decoding into key events. Ported
+/// from g2flash `demos/keyboard-client.ts`; the async command path replaces
+/// its promise map with continuations. Callers own the G2 link: `send` is
+/// handed complete settings payloads for the right lens and `accept` receives
+/// every field-131 payload. Everything runs on the main actor with the rest
+/// of the G2 driver.
+@MainActor
+final class G2KeyboardClient {
+    typealias Op = G2KeyboardProtocol.Op
+    typealias Record = G2KeyboardProtocol.Record
+
+    struct Status: Equatable {
+        var enabled = false
+        var conn: UInt8 = 0
+        var connected = false
+        var encrypted = false
+        var scanning = false
+    }
+
+    struct Report {
+        let service: UInt16
+        let handle: UInt16
+        let id: Int
+        let type: UInt8
+        let ccc: UInt16?
+        let properties: UInt8
+        let map: [UInt8]
+    }
+
+    struct Configuration {
+        let epoch: UInt16
+        let reports: [Report]
+        let serviceChanged: UInt16?
+        var inputCount: Int {
+            reports.filter { $0.type == 1 }.count
+        }
+    }
+
+    enum Event {
+        case keys([G2KeyboardHid.KeyEvent])
+        case advert(G2KeyboardProtocol.Advert)
+        case status(Status)
+        /// Held keys were released because of a stream gap or link change.
+        case gap
+        /// Device-manager event from the controller (0x27 open, 0x28 close, 0x2a paired, …).
+        case dm(event: UInt8, status: UInt8)
+        /// The keyboard shows a six-digit passkey the user must type into the phone.
+        case passkeyRequest
+        /// The phone chose a passkey the user must type on the keyboard (then Enter).
+        case passkeyDisplay(UInt32)
+        /// Numeric comparison: the user confirms the keyboard shows this value.
+        case compareRequest(UInt32)
+        case servicesChanged
+        case error(String)
+    }
+
+    struct ClientError: Error, LocalizedError, CustomStringConvertible {
+        let description: String
+        /// Expo surfaces `localizedDescription`; without this the app only sees
+        /// "The operation couldn't be completed. (… ClientError error 1.)".
+        var errorDescription: String? { description }
+    }
+
+    private struct Pending {
+        let op: Op
+        let continuation: CheckedContinuation<Record, Error>
+        let timeout: Task<Void, Never>
+    }
+
+    private struct Attribute {
+        let handle: UInt16
+        let uuid: AttributeUuid
+    }
+
+    enum AttributeUuid: Equatable {
+        case short(UInt16)
+        case long(String)
+
+        /// ATT UUIDs are little endian; the Bluetooth base UUID collapses to
+        /// its 16-bit form, vendor UUIDs stay as hex strings.
+        init(_ bytes: [UInt8]) throws {
+            if bytes.count == 2 {
+                self = .short(G2KeyboardProtocol.u16(bytes, 0))
+                return
+            }
+            guard bytes.count == 16 else { throw ClientError(description: "Invalid ATT UUID length") }
+            let base: [UInt8] = [0xFB, 0x34, 0x9B, 0x5F, 0x80, 0, 0, 0x80, 0, 0x10, 0, 0]
+            if Array(bytes[0 ..< 12]) == base, bytes[14] == 0, bytes[15] == 0 {
+                self = .short(G2KeyboardProtocol.u16(bytes, 12))
+            } else {
+                self = .long(bytes.map { String(format: "%02x", $0) }.joined())
+            }
+        }
+    }
+
+    private(set) var epoch: UInt16 = 0
+    private(set) var status = Status()
+    private(set) var configuration: Configuration?
+    private var serial: UInt16 = 0
+    private var magic: UInt8 = 30
+    private var pending: [UInt16: Pending] = [:]
+    private var held = G2KeyboardHid.HeldKeys()
+    private var inputs: [UInt16: (report: G2KeyboardHid.Report, id: Int, service: UInt16)] = [:]
+    private var records = G2KeyboardProtocol.RecordAssembler()
+    private var seenGaps = 0
+    private var closed = false
+
+    private let send: (Data, UInt8) -> Void
+    private let onEvent: (Event) -> Void
+
+    /// `send` receives the settings payload and its magic id for the right lens.
+    init(send: @escaping (Data, UInt8) -> Void, onEvent: @escaping (Event) -> Void) {
+        self.send = send
+        self.onEvent = onEvent
+    }
+
+    // MARK: - Inbound
+
+    /// Feed one field-131 payload from a right-lens settings notification.
+    func accept(_ payload: Data) {
+        let complete = records.push(payload)
+        if records.gaps != seenGaps {
+            seenGaps = records.gaps
+            gap()
+        }
+        guard let r = complete else { return }
+        epoch = r.epoch
+        if r.kind == G2KeyboardProtocol.Kind.status.rawValue, r.data.count == 10 {
+            status = Status(
+                enabled: r.data[0] != 0, conn: r.data[1], connected: r.data[2] != 0,
+                encrypted: r.data[3] != 0, scanning: r.data[4] != 0
+            )
+            if !status.enabled || !status.connected || !status.encrypted {
+                release()
+            }
+            onEvent(.status(status))
+        }
+        if let p = pending[r.request], r.kind == 1 || r.kind == 2 {
+            pending[r.request] = nil
+            p.timeout.cancel()
+            if r.kind == 1, r.code != 0 {
+                p.continuation.resume(throwing: ClientError(
+                    description: "Keyboard command \(p.op): firmware \(G2KeyboardProtocol.errorName(r.code))"
+                ))
+            } else {
+                p.continuation.resume(returning: r)
+            }
+        }
+        switch r.kind {
+        case G2KeyboardProtocol.Kind.dm.rawValue:
+            let event = UInt8(r.code & 0xFF)
+            let dmStatus = UInt8(r.code >> 8)
+            if event == 0x28 || event == 0x2B || event == 0x2D {
+                gap()
+                inputs.removeAll()
+                configuration = nil
+            }
+            if event == 0x2E, r.data.count == 2 {
+                if r.data[0] != 0 {
+                    Task { [weak self] in
+                        guard let self else { return }
+                        _ = try? await self.command(.disconnect)
+                    }
+                    onEvent(.error("OOB-only keyboard pairing is unsupported"))
+                } else if r.data[1] != 0 {
+                    // KeyboardDisplay on our side: choose the passkey, show it, and
+                    // answer immediately; the user types it on the keyboard.
+                    let pin = UInt32.random(in: 0 ... 999_999)
+                    onEvent(.passkeyDisplay(pin))
+                    Task { [weak self] in
+                        guard let self else { return }
+                        do { try await self.authenticate(pin) } catch { self.onEvent(.error("\(error)")) }
+                    }
+                } else {
+                    onEvent(.passkeyRequest)
+                }
+            }
+            if event == 0x35, r.data.count == 4 {
+                onEvent(.compareRequest(G2KeyboardProtocol.u32(r.data, 0)))
+            }
+            onEvent(.dm(event: event, status: dmStatus))
+        case G2KeyboardProtocol.Kind.input.rawValue:
+            if let changed = configuration?.serviceChanged, r.handle == changed {
+                gap()
+                inputs.removeAll()
+                configuration = nil
+                onEvent(.servicesChanged)
+                return
+            }
+            guard let input = inputs[r.handle], configuration?.epoch == r.epoch else {
+                gap()
+                return
+            }
+            do {
+                let events = try held.update(handle: r.handle, report: input.report, data: r.data)
+                if !events.isEmpty {
+                    onEvent(.keys(events))
+                }
+            } catch {
+                release()
+                onEvent(.error("\(error)"))
+            }
+        case G2KeyboardProtocol.Kind.advert.rawValue:
+            if let advert = G2KeyboardProtocol.Advert.parse(r.data) {
+                onEvent(.advert(advert))
+            }
+        default:
+            break
+        }
+    }
+
+    private func release() {
+        let events = held.reset()
+        if !events.isEmpty {
+            onEvent(.keys(events))
+        }
+    }
+
+    private func gap() {
+        release()
+        onEvent(.gap)
+        for (id, p) in pending where p.op.rawValue >= Op.find.rawValue {
+            p.timeout.cancel()
+            p.continuation.resume(throwing: ClientError(description: "Keyboard stream gap during ATT transaction"))
+            pending[id] = nil
+        }
+    }
+
+    /// Call on phone-link loss: clear held state and fail every command.
+    func lostPhoneLink() {
+        records.reset()
+        seenGaps = records.gaps
+        release()
+        cancel()
+    }
+
+    func close() {
+        closed = true
+        lostPhoneLink()
+    }
+
+    private func cancel() {
+        for p in pending.values {
+            p.timeout.cancel()
+            p.continuation.resume(throwing: ClientError(description: "Keyboard client closed"))
+        }
+        pending.removeAll()
+    }
+
+    // MARK: - Commands
+
+    /// Send one control and await its STATUS/ATT result record. ENABLE and
+    /// QUERY ignore the epoch; every other control must match the live one.
+    @discardableResult
+    func command(_ op: Op, body: [UInt8] = []) async throws -> Record {
+        if closed {
+            throw ClientError(description: "Keyboard client closed")
+        }
+        if pending.count >= 8 {
+            throw ClientError(description: "Too many keyboard commands")
+        }
+        serial = serial % 65535 + 1
+        magic = magic % 200 + 1
+        let request = serial
+        let magicId = magic
+        let packet = G2KeyboardProtocol.controlPacket(op: op, request: request, epoch: epoch, body: body, magic: magicId)
+        return try await withCheckedThrowingContinuation { continuation in
+            let timeout = Task { @MainActor [weak self] in
+                try? await Task.sleep(nanoseconds: 32_000_000_000)
+                guard let self, !Task.isCancelled, let p = self.pending.removeValue(forKey: request) else { return }
+                p.continuation.resume(throwing: ClientError(description: "Keyboard command \(op) timed out"))
+            }
+            pending[request] = Pending(op: op, continuation: continuation, timeout: timeout)
+            send(packet, magicId)
+        }
+    }
+
+    func enable() async throws {
+        try await command(.enable)
+    }
+
+    func disable() async throws {
+        try await command(.disable)
+        release()
+    }
+
+    func query() async throws -> Status {
+        try await command(.query)
+        return status
+    }
+
+    /// Active scan for five seconds; adverts arrive as `.advert` events. The
+    /// firmware only clears `scanning` once the stock scanner is idle again,
+    /// and a ring hunting for its lens can hold the radio well past that, so
+    /// the fixed five-second window is the real end of the scan: results that
+    /// already streamed stand even when the flag lingers.
+    func scan() async throws {
+        try await command(.scan)
+        do {
+            try await until({ !self.status.scanning }, timeout: 8)
+        } catch {
+            if closed { throw error }
+        }
+    }
+
+    /// Connect, then pair unless the link is already encrypted. `address` is
+    /// LSB first as the controller reports it.
+    func connect(addressType: UInt8, address: [UInt8]) async throws {
+        guard address.count == 6, addressType <= 3 else { throw ClientError(description: "Invalid BLE address") }
+        release()
+        inputs.removeAll()
+        configuration = nil
+        try await command(.connect, body: [addressType] + address)
+        try await until({ self.status.connected }, timeout: 32)
+        if !status.encrypted {
+            // A peripheral security request can have started pairing already;
+            // BUSY is not success, the encrypted status below still decides.
+            do {
+                try await command(.pair)
+            } catch let error as ClientError where error.description.hasSuffix("firmware busy") {
+                // fall through to the encryption wait
+            }
+            try await until({ self.status.encrypted }, timeout: 65)
+        }
+    }
+
+    private func until(_ test: @escaping () -> Bool, timeout seconds: Double) async throws {
+        let end = Date().addingTimeInterval(seconds)
+        while !test() {
+            if closed {
+                throw ClientError(description: "Keyboard client closed")
+            }
+            if Date() >= end {
+                throw ClientError(description: "Keyboard state timeout")
+            }
+            try? await Task.sleep(nanoseconds: 50_000_000)
+        }
+    }
+
+    /// Answer a pending passkey prompt (the value the keyboard displayed).
+    func authenticate(_ pin: UInt32) async throws {
+        guard pin <= 999_999 else { throw ClientError(description: "Invalid pairing passkey") }
+        try await command(.auth, body: [UInt8(pin & 0xFF), UInt8((pin >> 8) & 0xFF), UInt8(pin >> 16)])
+    }
+
+    /// Answer a pending numeric comparison.
+    func confirm(_ accept: Bool) async throws {
+        try await command(.compare, body: [accept ? 1 : 0])
+    }
+
+    private func att(_ op: Op, _ body: [UInt8]) async throws -> Record {
+        let r = try await command(op, body: body)
+        guard r.kind == G2KeyboardProtocol.Kind.att.rawValue else {
+            throw ClientError(description: "Expected keyboard ATT response")
+        }
+        return r
+    }
+
+    /// Read Blob until a short/empty response or Invalid Offset; never assumes MTU 23.
+    func read(_ handle: UInt16) async throws -> [UInt8] {
+        var parts: [UInt8] = []
+        while true {
+            let r = try await att(.read, G2KeyboardProtocol.le16(handle) + G2KeyboardProtocol.le16(UInt16(parts.count)))
+            let status = r.code >> 8
+            if !parts.isEmpty, status == 7 || status == 11 {
+                break
+            }
+            if status != 0 {
+                throw ClientError(description: "ATT read \(handle): \(status)")
+            }
+            if r.data.isEmpty {
+                break
+            }
+            parts += r.data
+            if parts.count > 512 {
+                throw ClientError(description: "Attribute exceeds 512 bytes")
+            }
+            if parts.count == 512 {
+                break
+            }
+        }
+        return parts
+    }
+
+    /// Read a short attribute once (Report Reference, declaration, service UUID).
+    private func shortRead(_ handle: UInt16) async throws -> [UInt8] {
+        let r = try await att(.read, G2KeyboardProtocol.le16(handle) + [0, 0])
+        if r.code >> 8 != 0 {
+            throw ClientError(description: "ATT read \(handle): \(r.code >> 8)")
+        }
+        return r.data
+    }
+
+    func write(_ handle: UInt16, _ value: [UInt8], withoutResponse: Bool = false) async throws {
+        guard !value.isEmpty, value.count <= 18 else { throw ClientError(description: "Keyboard write supports 1..18 bytes") }
+        let r = try await att(.write, G2KeyboardProtocol.le16(handle) + [withoutResponse ? 1 : 0, UInt8(value.count)] + value)
+        if r.code >> 8 != 0 {
+            throw ClientError(description: "ATT write \(handle): \(r.code >> 8)")
+        }
+    }
+
+    private func attributes() async throws -> [Attribute] {
+        var attrs: [Attribute] = []
+        var start = 1
+        while start <= 65535 {
+            let r = try await att(.find, G2KeyboardProtocol.le16(UInt16(start)) + [0xFF, 0xFF])
+            let status = r.code >> 8
+            if status == 10 {
+                break
+            } // attribute not found: normal end
+            if status != 0 {
+                throw ClientError(description: "ATT Find Information: \(status)")
+            }
+            let width = r.data.first == 1 ? 4 : r.data.first == 2 ? 18 : 0
+            guard width > 0, r.data.count > 1, (r.data.count - 1) % width == 0 else {
+                throw ClientError(description: "Malformed Find Information response")
+            }
+            var i = 1
+            while i < r.data.count {
+                let handle = Int(G2KeyboardProtocol.u16(r.data, i))
+                if handle < start || attrs.count >= 512 {
+                    throw ClientError(description: "Invalid or excessive GATT handles")
+                }
+                try attrs.append(Attribute(handle: UInt16(handle), uuid: AttributeUuid(Array(r.data[(i + 2) ..< (i + width)]))))
+                start = handle + 1
+                i += width
+            }
+        }
+        return attrs
+    }
+
+    /// Discover HIDS instances, Report Maps and each Report Reference; select
+    /// Report Protocol and subscribe input reports. No fixed keyboard handles.
+    @discardableResult
+    func configure() async throws -> Configuration {
+        let attrs = try await attributes()
+        var reports: [Report] = []
+        func descriptorsFor(_ handle: UInt16) -> [Attribute] {
+            let end = attrs.first { a in
+                a.handle > handle && [AttributeUuid.short(0x2800), .short(0x2801), .short(0x2803)].contains(a.uuid)
+            }.map { Int($0.handle) } ?? 65536
+            return attrs.filter { $0.handle > handle && Int($0.handle) < end }
+        }
+        func addReport(service: UInt16, _ a: Attribute, map: [UInt8], parsed: [Int: G2KeyboardHid.Report]) async throws {
+            let descriptors = descriptorsFor(a.handle)
+            guard let ref = descriptors.first(where: { $0.uuid == .short(0x2908) }),
+                  let decl = attrs.filter({ $0.handle < a.handle }).last(where: { $0.uuid == .short(0x2803) })
+            else { throw ClientError(description: "HID Report has no declaration/reference") }
+            let reference = try await shortRead(ref.handle)
+            let declaration = try await shortRead(decl.handle)
+            guard reference.count == 2, declaration.count == 5 || declaration.count == 19,
+                  G2KeyboardProtocol.u16(declaration, 1) == a.handle,
+                  try AttributeUuid(Array(declaration[3...])) == a.uuid
+            else { throw ClientError(description: "Invalid HID Report metadata") }
+            let id = Int(reference[0])
+            let type = reference[1]
+            let properties = declaration[0]
+            guard type >= 1, type <= 3 else { throw ClientError(description: "Invalid Report Reference type") }
+            let ccc = descriptors.first { $0.uuid == .short(0x2902) }?.handle
+            if type == 1, parsed[id] == nil || ccc == nil || properties & 0x10 == 0 {
+                throw ClientError(description: "Input Report lacks map/notify/CCC")
+            }
+            if reports.contains(where: { $0.handle == a.handle }) {
+                throw ClientError(description: "Ambiguous report shared by multiple HID services")
+            }
+            reports.append(Report(service: service, handle: a.handle, id: id, type: type, ccc: ccc, properties: properties, map: map))
+        }
+        for (i, service) in attrs.enumerated() {
+            guard service.uuid == .short(0x2800) else { continue }
+            guard try AttributeUuid(await shortRead(service.handle)) == .short(0x1812) else { continue }
+            let end = attrs[(i + 1)...].first { $0.uuid == .short(0x2800) || $0.uuid == .short(0x2801) }?.handle
+            let members = attrs.filter { $0.handle > service.handle && (end == nil || $0.handle < end!) }
+            guard let mapAttr = members.first(where: { $0.uuid == .short(0x2A4B) }) else {
+                throw ClientError(description: "HID service has no Report Map")
+            }
+            let map = try await read(mapAttr.handle)
+            let parsed = try G2KeyboardHid.parseReportMap(map)
+            for mode in members.filter({ $0.uuid == .short(0x2A4E) }) {
+                try await write(mode.handle, [1], withoutResponse: true)
+            }
+            for a in members.filter({ $0.uuid == .short(0x2A4D) }) {
+                try await addReport(service: service.handle, a, map: map, parsed: parsed)
+            }
+            // HOGP can refer to input reports in other services (commonly Battery).
+            for ext in descriptorsFor(mapAttr.handle).filter({ $0.uuid == .short(0x2907) }) {
+                let uuid = try AttributeUuid(await shortRead(ext.handle))
+                let matches = attrs.filter { $0.uuid == uuid && ($0.handle < service.handle || (end != nil && $0.handle >= end!)) }
+                if matches.isEmpty {
+                    throw ClientError(description: "External HID report characteristic missing")
+                }
+                for a in matches {
+                    try await addReport(service: service.handle, a, map: map, parsed: parsed)
+                }
+            }
+        }
+        let inputReports = reports.filter { $0.type == 1 }
+        guard !inputReports.isEmpty, inputReports.count <= 16 else {
+            throw ClientError(description: "Keyboard requires 1..16 input reports")
+        }
+        let changed = attrs.first { $0.uuid == .short(0x2A05) }
+        let changedCcc = changed.flatMap { c in descriptorsFor(c.handle).first { $0.uuid == .short(0x2902) } }
+        var watches = inputReports.map(\.handle)
+        if let changed, changedCcc != nil {
+            watches.append(changed.handle)
+        }
+        guard watches.count <= 16 else { throw ClientError(description: "More than 16 subscribed report/Service Changed handles") }
+        let config = Configuration(epoch: epoch, reports: reports, serviceChanged: changedCcc != nil ? changed?.handle : nil)
+        try restore(config)
+        do {
+            try await command(.watch, body: [UInt8(watches.count)] + watches.flatMap(G2KeyboardProtocol.le16))
+            if let changedCcc {
+                try await write(changedCcc.handle, [2, 0])
+            }
+            for r in inputReports {
+                try await write(r.ccc!, [1, 0])
+            }
+        } catch {
+            inputs.removeAll()
+            configuration = nil
+            release()
+            throw error
+        }
+        return config
+    }
+
+    /// Install a discovered mapping. Valid only for the same connection epoch:
+    /// a fresh firmware boot needs enable/connect/configure again.
+    func restore(_ config: Configuration) throws {
+        guard !config.reports.isEmpty, config.reports.count <= 64 else { throw ClientError(description: "Invalid keyboard configuration") }
+        var next: [UInt16: (report: G2KeyboardHid.Report, id: Int, service: UInt16)] = [:]
+        for r in config.reports where r.type == 1 {
+            guard r.handle >= 1, next[r.handle] == nil else { throw ClientError(description: "Invalid restored Report handle") }
+            guard !r.map.isEmpty, r.map.count <= 512 else { throw ClientError(description: "Invalid restored Report Map") }
+            guard let report = try G2KeyboardHid.parseReportMap(r.map)[r.id] else {
+                throw ClientError(description: "Restored Report ID missing")
+            }
+            next[r.handle] = (report, r.id, r.service)
+        }
+        guard !next.isEmpty, next.count <= 16 else { throw ClientError(description: "Invalid restored input count") }
+        release()
+        inputs = next
+        configuration = config
+    }
+}