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

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2Keyboard.kt

@@ -0,0 +1,689 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withTimeoutOrNull
+
+/**
+ * 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…]`.
+ */
+internal object G2KeyboardProtocol {
+    const val PROTOCOL_VERSION = 1
+
+    enum class Op(val value: Int) {
+        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),
+    }
+
+    const val KIND_STATUS = 1
+    const val KIND_ATT = 2
+    const val KIND_INPUT = 3
+    const val KIND_DM = 4
+    const val KIND_ADVERT = 5
+
+    /** Firmware control error codes carried by STATUS records. */
+    fun errorName(code: Int): String = when (code) {
+        0 -> "ok"
+        1 -> "bad request"
+        2 -> "keyboard bridge disabled"
+        3 -> "busy"
+        4 -> "stale epoch"
+        5 -> "no connection or bond space"
+        6 -> "not connected"
+        7 -> "not encrypted"
+        8 -> "timeout"
+        9 -> "allocation failure"
+        else -> "error $code"
+    }
+
+    data class Record(
+        val kind: Int,
+        val sequence: Long,
+        val epoch: Int,
+        val request: Int,
+        val code: Int,
+        val handle: Int,
+        val timestamp: Long,
+        val data: ByteArray,
+    )
+
+    /**
+     * 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.
+     */
+    fun controlPacket(op: Op, request: Int, epoch: Int, body: ByteArray = ByteArray(0), magic: Int = 1): ByteArray {
+        require(body.size <= 72) { "keyboard control bounds" }
+        val data = byteArrayOf(0x4B, 0x42, PROTOCOL_VERSION.toByte(), op.value.toByte()) + le16(request) + le16(epoch) + body
+        return byteArrayOf(0x08, 0x02, 0x10) + varint(magic) +
+            byteArrayOf(0x22, 0x02, 0x08, 0x01, 0x92.toByte(), 0x08, data.size.toByte()) + data
+    }
+
+    fun le16(v: Int): ByteArray = byteArrayOf((v and 0xFF).toByte(), ((v shr 8) and 0xFF).toByte())
+
+    fun u16(b: ByteArray, i: Int): Int = (b[i].toInt() and 0xFF) or ((b[i + 1].toInt() and 0xFF) shl 8)
+
+    fun u32(b: ByteArray, i: Int): Long =
+        (b[i].toLong() and 0xFF) or ((b[i + 1].toLong() and 0xFF) shl 8) or
+            ((b[i + 2].toLong() and 0xFF) shl 16) or ((b[i + 3].toLong() and 0xFF) shl 24)
+
+    private fun varint(v: Int): ByteArray {
+        val out = ArrayList<Byte>()
+        var value = v
+        while (value >= 0x80) {
+            out.add(((value and 0x7F) or 0x80).toByte())
+            value = value ushr 7
+        }
+        out.add(value.toByte())
+        return out.toByteArray()
+    }
+
+    /**
+     * Bounded, ordered reassembly of field-131 fragments. A gap (lost or
+     * out-of-order event, epoch change, malformed fragment) bumps [gaps] so the
+     * caller releases every held key and cancels setup transactions.
+     */
+    class RecordAssembler {
+        private var epoch: Int? = null
+        private var last: Long? = null
+        private var fragment: Fragment? = null
+        var gaps = 0
+            private set
+
+        private class Fragment(val record: Record, val total: Int, var used: Int)
+
+        fun reset() {
+            epoch = null
+            last = null
+            fragment = null
+            gaps++
+        }
+
+        /** Feed one field-131 payload; returns a complete record or null. */
+        fun push(p: ByteArray): Record? {
+            fun invalid(): Record? {
+                fragment = null
+                gaps++
+                return null
+            }
+            if (p.size < 24 || p.size > 120 || p[0] != 0x4B.toByte() || p[1] != 0x42.toByte() || p[2] != PROTOCOL_VERSION.toByte()) {
+                return invalid()
+            }
+            val kind = p[3].toInt() and 0xFF
+            val sequence = u32(p, 4)
+            val r = Record(kind, sequence, u16(p, 8), u16(p, 10), u16(p, 12), u16(p, 14), u32(p, 20), ByteArray(0))
+            val total = u16(p, 16)
+            val offset = u16(p, 18)
+            val n = p.size - 24
+            if (kind < 1 || kind > 5 || total > 512 || offset + n > total || (total > 0 && n == 0)) return invalid()
+            if (epoch != r.epoch) {
+                gaps++
+                fragment = null
+                last = null
+                epoch = r.epoch
+            }
+            if (offset == 0) {
+                val previous = last
+                if (previous != null) {
+                    val distance = (r.sequence - previous) and 0xFFFF_FFFFL
+                    if (distance == 0L || distance >= 0x8000_0000L) return null // duplicate/old delivery
+                }
+                if (fragment != null || (previous != null && r.sequence != ((previous + 1) and 0xFFFF_FFFFL))) gaps++
+                last = r.sequence
+                fragment = Fragment(r.copy(data = ByteArray(total)), total, 0)
+            }
+            val f = fragment
+            if (f == null || 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
+            ) {
+                return invalid()
+            }
+            System.arraycopy(p, 24, f.record.data, offset, n)
+            f.used += n
+            if (f.used != total) return null
+            fragment = null
+            return f.record
+        }
+    }
+
+    /** Parsed ADVERT record body: addrType, addr[6] (LSB first), RSSI, event type, AD data. */
+    data class Advert(
+        val addressType: Int,
+        /** Little-endian as the controller reports it; [addressText] is the usual MSB-first form. */
+        val address: List<Int>,
+        val rssi: Int,
+        val name: String,
+        val hid: Boolean,
+    ) {
+        val addressText: String
+            get() = address.reversed().joinToString(":") { "%02x".format(it) }
+
+        /**
+         * 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.
+         */
+        fun merging(other: Advert) =
+            copy(rssi = maxOf(rssi, other.rssi), name = name.ifEmpty { other.name }, hid = hid || other.hid)
+
+        companion object {
+            fun parse(body: ByteArray): Advert? {
+                if (body.size < 10) return null
+                var name = ""
+                var hid = false
+                var i = 10
+                while (i < body.size) {
+                    val n = body[i++].toInt() and 0xFF
+                    if (n == 0 || i + n > body.size) break
+                    val type = body[i].toInt() and 0xFF
+                    if (type == 8 || type == 9) name = String(body, i + 1, n - 1, Charsets.UTF_8)
+                    if (type == 2 || type == 3) {
+                        var j = i + 1
+                        while (j + 1 < i + n) {
+                            if (body[j] == 0x12.toByte() && body[j + 1] == 0x18.toByte()) 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].toInt() and 0xFF) == 0x03 && (body[i + 1].toInt() and 0xFF) >= 0xC0) {
+                        hid = true
+                    }
+                    i += n
+                }
+                return Advert(
+                    body[0].toInt() and 0xFF,
+                    (1..6).map { body[it].toInt() and 0xFF },
+                    body[7].toInt(),
+                    name,
+                    hid,
+                )
+            }
+        }
+    }
+
+    /** Parse "aa:bb:cc:dd:ee:ff" into the controller's LSB-first byte order. */
+    fun addressFromText(text: String): ByteArray? {
+        val parts = text.split(":")
+        if (parts.size != 6) return null
+        val bytes = ByteArray(6)
+        for ((index, part) in parts.withIndex()) {
+            if (part.length != 2) return null
+            val value = part.toIntOrNull(16) ?: return null
+            bytes[5 - index] = value.toByte()
+        }
+        return bytes
+    }
+}
+
+/**
+ * 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`. Everything runs on [scope] (the G2
+ * driver's main-thread scope): [accept] must be called there too.
+ */
+internal class G2KeyboardClient(
+    private val scope: CoroutineScope,
+    private val send: (ByteArray, Int) -> Unit,
+    private val onEvent: (Event) -> Unit,
+) {
+    data class Status(
+        val enabled: Boolean = false,
+        val conn: Int = 0,
+        val connected: Boolean = false,
+        val encrypted: Boolean = false,
+        val scanning: Boolean = false,
+    )
+
+    data class Report(
+        val service: Int,
+        val handle: Int,
+        val id: Int,
+        val type: Int,
+        val ccc: Int?,
+        val properties: Int,
+        val map: ByteArray,
+    )
+
+    data class Configuration(val epoch: Int, val reports: List<Report>, val serviceChanged: Int?) {
+        val inputCount: Int get() = reports.count { it.type == 1 }
+    }
+
+    sealed class Event {
+        data class Keys(val events: List<G2KeyboardHid.KeyEvent>) : Event()
+        data class Advertisement(val advert: G2KeyboardProtocol.Advert) : Event()
+        data class StatusChanged(val status: Status) : Event()
+        /** Held keys were released because of a stream gap or link change. */
+        object Gap : Event()
+        /** Device-manager event from the controller (0x27 open, 0x28 close, 0x2a paired, …). */
+        data class Dm(val event: Int, val status: Int) : Event()
+        /** The keyboard shows a six-digit passkey the user must type into the phone. */
+        object PasskeyRequest : Event()
+        /** The phone chose a passkey the user must type on the keyboard (then Enter). */
+        data class PasskeyDisplay(val pin: Int) : Event()
+        /** Numeric comparison: the user confirms the keyboard shows this value. */
+        data class CompareRequest(val value: Long) : Event()
+        object ServicesChanged : Event()
+        data class Error(val message: String) : Event()
+    }
+
+    class ClientException(message: String) : Exception(message)
+
+    private class Pending(val op: G2KeyboardProtocol.Op, val result: CompletableDeferred<G2KeyboardProtocol.Record>)
+
+    private class Attribute(val handle: Int, val uuid: Any)
+
+    private class Input(val report: G2KeyboardHid.Report, val id: Int, val service: Int)
+
+    var epoch = 0
+        private set
+    var status = Status()
+        private set
+    var configuration: Configuration? = null
+        private set
+    private var serial = 0
+    private var magic = 30
+    private val pending = LinkedHashMap<Int, Pending>()
+    private val held = G2KeyboardHid.HeldKeys()
+    private var inputs = LinkedHashMap<Int, Input>()
+    private val records = G2KeyboardProtocol.RecordAssembler()
+    private var seenGaps = 0
+    private var closed = false
+
+    // ---------- Inbound ----------
+
+    /** Feed one field-131 payload from a right-lens settings notification. */
+    fun accept(payload: ByteArray) {
+        val complete = records.push(payload)
+        if (records.gaps != seenGaps) {
+            seenGaps = records.gaps
+            gap()
+        }
+        val r = complete ?: return
+        epoch = r.epoch
+        if (r.kind == G2KeyboardProtocol.KIND_STATUS && r.data.size == 10) {
+            status = Status(
+                enabled = r.data[0].toInt() != 0, conn = r.data[1].toInt() and 0xFF,
+                connected = r.data[2].toInt() != 0, encrypted = r.data[3].toInt() != 0, scanning = r.data[4].toInt() != 0,
+            )
+            if (!status.enabled || !status.connected || !status.encrypted) release()
+            onEvent(Event.StatusChanged(status))
+        }
+        val p = pending[r.request]
+        if (p != null && (r.kind == 1 || r.kind == 2)) {
+            pending.remove(r.request)
+            if (r.kind == 1 && r.code != 0) {
+                p.result.completeExceptionally(
+                    ClientException("Keyboard command ${p.op}: firmware ${G2KeyboardProtocol.errorName(r.code)}"),
+                )
+            } else {
+                p.result.complete(r)
+            }
+        }
+        when (r.kind) {
+            G2KeyboardProtocol.KIND_DM -> {
+                val event = r.code and 0xFF
+                val dmStatus = r.code shr 8
+                if (event == 0x28 || event == 0x2B || event == 0x2D) {
+                    gap()
+                    inputs.clear()
+                    configuration = null
+                }
+                if (event == 0x2E && r.data.size == 2) {
+                    when {
+                        r.data[0].toInt() != 0 -> {
+                            scope.launch { runCatching { command(G2KeyboardProtocol.Op.DISCONNECT) } }
+                            onEvent(Event.Error("OOB-only keyboard pairing is unsupported"))
+                        }
+                        r.data[1].toInt() != 0 -> {
+                            // KeyboardDisplay on our side: choose the passkey, show it, and
+                            // answer immediately; the user types it on the keyboard.
+                            val pin = (0..999_999).random()
+                            onEvent(Event.PasskeyDisplay(pin))
+                            scope.launch {
+                                runCatching { authenticate(pin) }.onFailure { onEvent(Event.Error(it.message ?: "$it")) }
+                            }
+                        }
+                        else -> onEvent(Event.PasskeyRequest)
+                    }
+                }
+                if (event == 0x35 && r.data.size == 4) onEvent(Event.CompareRequest(G2KeyboardProtocol.u32(r.data, 0)))
+                onEvent(Event.Dm(event, dmStatus))
+            }
+            G2KeyboardProtocol.KIND_INPUT -> {
+                val changed = configuration?.serviceChanged
+                if (changed != null && r.handle == changed) {
+                    gap()
+                    inputs.clear()
+                    configuration = null
+                    onEvent(Event.ServicesChanged)
+                    return
+                }
+                val input = inputs[r.handle]
+                if (input == null || configuration?.epoch != r.epoch) {
+                    gap()
+                    return
+                }
+                try {
+                    val events = held.update(r.handle, input.report, r.data)
+                    if (events.isNotEmpty()) onEvent(Event.Keys(events))
+                } catch (e: IllegalArgumentException) {
+                    release()
+                    onEvent(Event.Error(e.message ?: "$e"))
+                }
+            }
+            G2KeyboardProtocol.KIND_ADVERT -> G2KeyboardProtocol.Advert.parse(r.data)?.let { onEvent(Event.Advertisement(it)) }
+        }
+    }
+
+    private fun release() {
+        val events = held.reset()
+        if (events.isNotEmpty()) onEvent(Event.Keys(events))
+    }
+
+    private fun gap() {
+        release()
+        onEvent(Event.Gap)
+        val iterator = pending.entries.iterator()
+        while (iterator.hasNext()) {
+            val entry = iterator.next()
+            if (entry.value.op.value >= G2KeyboardProtocol.Op.FIND.value) {
+                entry.value.result.completeExceptionally(ClientException("Keyboard stream gap during ATT transaction"))
+                iterator.remove()
+            }
+        }
+    }
+
+    /** Call on phone-link loss: clear held state and fail every command. */
+    fun lostPhoneLink() {
+        records.reset()
+        seenGaps = records.gaps
+        release()
+        cancel()
+    }
+
+    fun close() {
+        closed = true
+        lostPhoneLink()
+    }
+
+    private fun cancel() {
+        for (p in pending.values) p.result.completeExceptionally(ClientException("Keyboard client closed"))
+        pending.clear()
+    }
+
+    // ---------- 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.
+     */
+    suspend fun command(op: G2KeyboardProtocol.Op, body: ByteArray = ByteArray(0)): G2KeyboardProtocol.Record {
+        if (closed) throw ClientException("Keyboard client closed")
+        if (pending.size >= 8) throw ClientException("Too many keyboard commands")
+        serial = serial % 65535 + 1
+        magic = magic % 200 + 1
+        val request = serial
+        val magicId = magic
+        val result = CompletableDeferred<G2KeyboardProtocol.Record>()
+        pending[request] = Pending(op, result)
+        send(G2KeyboardProtocol.controlPacket(op, request, epoch, body, magicId), magicId)
+        return withTimeoutOrNull(32_000) { result.await() }
+            ?: run {
+                pending.remove(request)
+                throw ClientException("Keyboard command $op timed out")
+            }
+    }
+
+    suspend fun enable() {
+        command(G2KeyboardProtocol.Op.ENABLE)
+    }
+
+    suspend fun disable() {
+        command(G2KeyboardProtocol.Op.DISABLE)
+        release()
+    }
+
+    suspend fun query(): Status {
+        command(G2KeyboardProtocol.Op.QUERY)
+        return status
+    }
+
+    /** Active scan for five seconds; adverts arrive as [Event.Advertisement]. */
+    /**
+     * Active scan for five seconds; adverts arrive as [Event.Advertisement].
+     * 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.
+     */
+    suspend fun scan() {
+        command(G2KeyboardProtocol.Op.SCAN)
+        try {
+            until(8_000) { !status.scanning }
+        } catch (e: ClientException) {
+            if (closed) throw e
+        }
+    }
+
+    /** Connect, then pair unless the link is already encrypted. [address] is LSB first. */
+    suspend fun connect(addressType: Int, address: ByteArray) {
+        if (address.size != 6 || addressType !in 0..3) throw ClientException("Invalid BLE address")
+        release()
+        inputs.clear()
+        configuration = null
+        command(G2KeyboardProtocol.Op.CONNECT, byteArrayOf(addressType.toByte()) + address)
+        until(32_000) { status.connected }
+        if (!status.encrypted) {
+            // A peripheral security request can have started pairing already;
+            // BUSY is not success, the encrypted status below still decides.
+            try {
+                command(G2KeyboardProtocol.Op.PAIR)
+            } catch (e: ClientException) {
+                if (e.message?.endsWith("firmware busy") != true) throw e
+            }
+            until(65_000) { status.encrypted }
+        }
+    }
+
+    private suspend fun until(timeoutMs: Long, test: () -> Boolean) {
+        val end = System.currentTimeMillis() + timeoutMs
+        while (!test()) {
+            if (closed) throw ClientException("Keyboard client closed")
+            if (System.currentTimeMillis() >= end) throw ClientException("Keyboard state timeout")
+            delay(50)
+        }
+    }
+
+    /** Answer a pending passkey prompt (the value the keyboard displayed). */
+    suspend fun authenticate(pin: Int) {
+        if (pin !in 0..999_999) throw ClientException("Invalid pairing passkey")
+        command(G2KeyboardProtocol.Op.AUTH, byteArrayOf((pin and 0xFF).toByte(), ((pin shr 8) and 0xFF).toByte(), (pin shr 16).toByte()))
+    }
+
+    /** Answer a pending numeric comparison. */
+    suspend fun confirm(accept: Boolean) {
+        command(G2KeyboardProtocol.Op.COMPARE, byteArrayOf(if (accept) 1 else 0))
+    }
+
+    private suspend fun att(op: G2KeyboardProtocol.Op, body: ByteArray): G2KeyboardProtocol.Record {
+        val r = command(op, body)
+        if (r.kind != G2KeyboardProtocol.KIND_ATT) throw ClientException("Expected keyboard ATT response")
+        return r
+    }
+
+    /** Read Blob until a short/empty response or Invalid Offset; never assumes MTU 23. */
+    suspend fun read(handle: Int): ByteArray {
+        var parts = ByteArray(0)
+        while (true) {
+            val r = att(G2KeyboardProtocol.Op.READ, G2KeyboardProtocol.le16(handle) + G2KeyboardProtocol.le16(parts.size))
+            val status = r.code shr 8
+            if (parts.isNotEmpty() && (status == 7 || status == 11)) break
+            if (status != 0) throw ClientException("ATT read $handle: $status")
+            if (r.data.isEmpty()) break
+            parts += r.data
+            if (parts.size > 512) throw ClientException("Attribute exceeds 512 bytes")
+            if (parts.size == 512) break
+        }
+        return parts
+    }
+
+    private suspend fun shortRead(handle: Int): ByteArray {
+        val r = att(G2KeyboardProtocol.Op.READ, G2KeyboardProtocol.le16(handle) + byteArrayOf(0, 0))
+        if (r.code shr 8 != 0) throw ClientException("ATT read $handle: ${r.code shr 8}")
+        return r.data
+    }
+
+    suspend fun write(handle: Int, value: ByteArray, withoutResponse: Boolean = false) {
+        if (value.isEmpty() || value.size > 18) throw ClientException("Keyboard write supports 1..18 bytes")
+        val body = G2KeyboardProtocol.le16(handle) + byteArrayOf(if (withoutResponse) 1 else 0, value.size.toByte()) + value
+        val r = att(G2KeyboardProtocol.Op.WRITE, body)
+        if (r.code shr 8 != 0) throw ClientException("ATT write $handle: ${r.code shr 8}")
+    }
+
+    /**
+     * ATT UUIDs are little endian; the Bluetooth base UUID collapses to its
+     * 16-bit form (an Int), vendor UUIDs stay as hex strings.
+     */
+    private fun attributeUuid(bytes: ByteArray): Any {
+        if (bytes.size == 2) return G2KeyboardProtocol.u16(bytes, 0)
+        if (bytes.size != 16) throw ClientException("Invalid ATT UUID length")
+        val base = intArrayOf(0xFB, 0x34, 0x9B, 0x5F, 0x80, 0, 0, 0x80, 0, 0x10, 0, 0)
+        val isBase = base.indices.all { (bytes[it].toInt() and 0xFF) == base[it] } && bytes[14].toInt() == 0 && bytes[15].toInt() == 0
+        return if (isBase) G2KeyboardProtocol.u16(bytes, 12) else bytes.joinToString("") { "%02x".format(it.toInt() and 0xFF) }
+    }
+
+    private suspend fun attributes(): List<Attribute> {
+        val attrs = ArrayList<Attribute>()
+        var start = 1
+        while (start <= 65535) {
+            val r = att(G2KeyboardProtocol.Op.FIND, G2KeyboardProtocol.le16(start) + byteArrayOf(0xFF.toByte(), 0xFF.toByte()))
+            val status = r.code shr 8
+            if (status == 10) break // attribute not found: normal end
+            if (status != 0) throw ClientException("ATT Find Information: $status")
+            val format = r.data.firstOrNull()?.toInt() ?: 0
+            val width = when (format) { 1 -> 4; 2 -> 18; else -> 0 }
+            if (width == 0 || r.data.size <= 1 || (r.data.size - 1) % width != 0) throw ClientException("Malformed Find Information response")
+            var i = 1
+            while (i < r.data.size) {
+                val handle = G2KeyboardProtocol.u16(r.data, i)
+                if (handle < start || attrs.size >= 512) throw ClientException("Invalid or excessive GATT handles")
+                attrs.add(Attribute(handle, attributeUuid(r.data.copyOfRange(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.
+     */
+    suspend fun configure(): Configuration {
+        val attrs = attributes()
+        val reports = ArrayList<Report>()
+        fun descriptorsFor(handle: Int): List<Attribute> {
+            val end = attrs.firstOrNull { it.handle > handle && it.uuid in listOf(0x2800, 0x2801, 0x2803) }?.handle ?: 65536
+            return attrs.filter { it.handle > handle && it.handle < end }
+        }
+        suspend fun addReport(service: Int, a: Attribute, map: ByteArray, parsed: Map<Int, G2KeyboardHid.Report>) {
+            val descriptors = descriptorsFor(a.handle)
+            val ref = descriptors.firstOrNull { it.uuid == 0x2908 }
+            val decl = attrs.filter { it.handle < a.handle }.lastOrNull { it.uuid == 0x2803 }
+            if (ref == null || decl == null) throw ClientException("HID Report has no declaration/reference")
+            val reference = shortRead(ref.handle)
+            val declaration = shortRead(decl.handle)
+            if (reference.size != 2 || (declaration.size != 5 && declaration.size != 19) ||
+                G2KeyboardProtocol.u16(declaration, 1) != a.handle ||
+                attributeUuid(declaration.copyOfRange(3, declaration.size)) != a.uuid
+            ) {
+                throw ClientException("Invalid HID Report metadata")
+            }
+            val id = reference[0].toInt() and 0xFF
+            val type = reference[1].toInt() and 0xFF
+            val properties = declaration[0].toInt() and 0xFF
+            if (type !in 1..3) throw ClientException("Invalid Report Reference type")
+            val ccc = descriptors.firstOrNull { it.uuid == 0x2902 }?.handle
+            if (type == 1 && (!parsed.containsKey(id) || ccc == null || (properties and 0x10) == 0)) {
+                throw ClientException("Input Report lacks map/notify/CCC")
+            }
+            if (reports.any { it.handle == a.handle }) throw ClientException("Ambiguous report shared by multiple HID services")
+            reports.add(Report(service, a.handle, id, type, ccc, properties, map))
+        }
+        for ((i, service) in attrs.withIndex()) {
+            if (service.uuid != 0x2800) continue
+            if (attributeUuid(shortRead(service.handle)) != 0x1812) continue
+            val end = attrs.drop(i + 1).firstOrNull { it.uuid == 0x2800 || it.uuid == 0x2801 }?.handle ?: 65536
+            val members = attrs.filter { it.handle > service.handle && it.handle < end }
+            val mapAttr = members.firstOrNull { it.uuid == 0x2A4B } ?: throw ClientException("HID service has no Report Map")
+            val map = read(mapAttr.handle)
+            val parsed = G2KeyboardHid.parseReportMap(map)
+            for (mode in members.filter { it.uuid == 0x2A4E }) write(mode.handle, byteArrayOf(1), withoutResponse = true)
+            for (a in members.filter { it.uuid == 0x2A4D }) addReport(service.handle, a, map, parsed)
+            // HOGP can refer to input reports in other services (commonly Battery).
+            for (ext in descriptorsFor(mapAttr.handle).filter { it.uuid == 0x2907 }) {
+                val uuid = attributeUuid(shortRead(ext.handle))
+                val matches = attrs.filter { it.uuid == uuid && (it.handle < service.handle || it.handle >= end) }
+                if (matches.isEmpty()) throw ClientException("External HID report characteristic missing")
+                for (a in matches) addReport(service.handle, a, map, parsed)
+            }
+        }
+        val inputReports = reports.filter { it.type == 1 }
+        if (inputReports.isEmpty() || inputReports.size > 16) throw ClientException("Keyboard requires 1..16 input reports")
+        val changed = attrs.firstOrNull { it.uuid == 0x2A05 }
+        val changedCcc = changed?.let { c -> descriptorsFor(c.handle).firstOrNull { it.uuid == 0x2902 } }
+        val watches = inputReports.map { it.handle }.toMutableList()
+        if (changed != null && changedCcc != null) watches.add(changed.handle)
+        if (watches.size > 16) throw ClientException("More than 16 subscribed report/Service Changed handles")
+        val config = Configuration(epoch, reports, if (changedCcc != null) changed?.handle else null)
+        restore(config)
+        try {
+            command(
+                G2KeyboardProtocol.Op.WATCH,
+                byteArrayOf(watches.size.toByte()) + watches.fold(ByteArray(0)) { acc, h -> acc + G2KeyboardProtocol.le16(h) },
+            )
+            if (changedCcc != null) write(changedCcc.handle, byteArrayOf(2, 0))
+            for (r in inputReports) write(r.ccc!!, byteArrayOf(1, 0))
+        } catch (e: Exception) {
+            inputs.clear()
+            configuration = null
+            release()
+            throw e
+        }
+        return config
+    }
+
+    /**
+     * Install a discovered mapping. Valid only for the same connection epoch:
+     * a fresh firmware boot needs enable/connect/configure again.
+     */
+    fun restore(config: Configuration) {
+        if (config.reports.isEmpty() || config.reports.size > 64) throw ClientException("Invalid keyboard configuration")
+        val next = LinkedHashMap<Int, Input>()
+        for (r in config.reports) {
+            if (r.type != 1) continue
+            if (r.handle < 1 || r.handle > 65535 || next.containsKey(r.handle)) throw ClientException("Invalid restored Report handle")
+            if (r.map.isEmpty() || r.map.size > 512) throw ClientException("Invalid restored Report Map")
+            val report = G2KeyboardHid.parseReportMap(r.map)[r.id] ?: throw ClientException("Restored Report ID missing")
+            next[r.handle] = Input(report, r.id, r.service)
+        }
+        if (next.isEmpty() || next.size > 16) throw ClientException("Invalid restored input count")
+        release()
+        inputs = next
+        configuration = config
+    }
+}