Add bluetooth keyboard support

G2 only: You can pair the glasses with a bluetooth keyboard. It will
relay key events, and you can use it to type in some apps and to
navigate the UI.
This commit is contained in:
James Babcock committed 2026-11-15 01:54:54 -08:00
1 parent 9372b2742c
commit fd3c26333f
46 files changed
+3867 -41

No files matched your search

@@ -0,0 +1,10 @@
package com.faceclaw.app
interface FaceclawKeyboardEventListener {
/**
* One CFW keyboard-bridge record (settings field 131) from the glasses: the raw
* ['K','B',ver,kind,...] bytes, possibly one fragment of a longer record. Decoded and
* reassembled on the TS side (app/g2/keyboard/protocol.ts). Delivered in arrival order.
*/
fun onKeyboardEvent(body: ByteArray?): Unit
}
@@ -119,6 +119,19 @@ class BleProtocol {
*/
const val FACECLAW_ALS_REPORT_FIELD: Int = 105
/**
* CFW keyboard bridge (Faceclaw/39): the master temple hosts one BLE HID keyboard. The
* host writes ['K','B',ver,op,request,epoch,...] controls as settings field 130; results,
* pairing prompts and the keyboard's raw input reports come back as commandId=3 pushes
* carrying field 131 (['K','B',ver,kind,...], decoded in app/g2/keyboard/protocol.ts).
*/
const val FACECLAW_KEYBOARD_CONTROL_FIELD: Int = 130
const val FACECLAW_KEYBOARD_EVENT_FIELD: Int = 131
/** Fixed header of a field-131 record; fragments follow it. */
const val FACECLAW_KEYBOARD_EVENT_HEADER: Int = 24
const val FACECLAW_WAKE_OP_ACQUIRE: Int = 1
const val FACECLAW_WAKE_OP_RELEASE: Int = 2
@@ -724,6 +737,42 @@ class BleProtocol {
return body
}
/**
* Wrap an already-encoded ['K','B',ver,op,...] keyboard control as a settings write
* carrying CFW field 130. Magic zero, like the other private controls: the answer is a
* field-131 record naming the control's request id, not the settings ACK.
*/
@JvmStatic
fun buildFaceclawKeyboardControl(record: ByteArray): ByteArray {
return concat(
CollectionUtils.listOf(
encodeVarintField(1, 1),
encodeVarintField(2, 0),
encodeBytesField(FACECLAW_KEYBOARD_CONTROL_FIELD, record),
)
)
}
/**
* Extract a CFW keyboard record (field 131) from a settings frame, or null when the frame
* carries none. Only the ['K','B'] prelude and the fixed header's length are checked
* here; the TS side validates the version and decodes the rest.
*/
@JvmStatic
fun parseFaceclawKeyboardEvent(pb: ByteArray?): ByteArray? {
if (pb == null) {
return null
}
val body = readFieldBytes(stripTrailingCrc(pb), FACECLAW_KEYBOARD_EVENT_FIELD)
if (
body == null || body.size < FACECLAW_KEYBOARD_EVENT_HEADER ||
body[0].toInt() != 75 || body[1].toInt() != 66
) {
return null
}
return body
}
/**
* Return the raw CFW ambient-light report from a sid-0x09 frame, or null when this is an
* ordinary settings frame. Only the 65.toByte(),76.toByte(),version prelude is validated
@@ -321,6 +321,24 @@ class MessageBuilder {
)
}
/**
* CFW keyboard control (settings field 130). Always the right arm: only the master temple
* acts on it, and a copy sent down each arm would run the control twice.
*/
fun faceclawKeyboardControl(record: ByteArray, label: String): OutboundMessage {
return OutboundMessage(
"keyboard-control",
"keyboard control $label",
BleProtocol.SID_UI_SETTING,
BleProtocol.FLAG_REQUEST,
0,
BleProtocol.buildFaceclawKeyboardControl(record),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun faceclawWearQuery(leftArm: Boolean): OutboundMessage {
return OutboundMessage(
"wear-query-control",
@@ -583,6 +583,22 @@ internal fun GlassesSessionCore.emitMicStatus(body: ByteArray, address: String)
}
}
internal fun GlassesSessionCore.emitKeyboardEvent(body: ByteArray) {
if (keyboardEventListeners.isEmpty()) {
return
}
val copy = body.copyOf()
host.postToMain {
for (keyboardListener in keyboardEventListeners) {
try {
keyboardListener.onKeyboardEvent(copy)
} catch (t: Throwable) {
logWarn("keyboard event listener failed", t)
}
}
}
}
internal fun GlassesSessionCore.emitAudioMonitorPacket(data: ByteArray, arm: String, arrivalMs: Long) {
if (audioMonitorListeners.isEmpty()) {
return
@@ -131,6 +131,7 @@ class GlassesSessionCore(
internal val compassSubscriptions = CopyOnWriteList<CompassSubscription>(platform)
internal val ambientLightListeners = CopyOnWriteList<FaceclawAmbientLightListener>(platform)
internal val micStatusListeners = CopyOnWriteList<FaceclawMicStatusListener>(platform)
internal val keyboardEventListeners = CopyOnWriteList<FaceclawKeyboardEventListener>(platform)
internal val audioMonitorListeners = CopyOnWriteList<FaceclawAudioPacketListener>(platform)
@Volatile internal var running = false
@Volatile internal var userDisconnectRequested = false
@@ -1388,6 +1389,39 @@ class GlassesSessionCore(
return true
}
fun addKeyboardEventListener(listener: FaceclawKeyboardEventListener?) {
if (listener != null) {
keyboardEventListeners.add(listener)
}
}
fun removeKeyboardEventListener(listener: FaceclawKeyboardEventListener?) {
if (listener != null) {
keyboardEventListeners.remove(listener)
}
}
/**
* Queue a CFW keyboard-bridge control (['K','B',ver,op,request,epoch,...]) as a settings
* field-130 write to the right temple. Fire-and-forget: the firmware answers with field-131
* records, which arrive through addKeyboardEventListener. Returns false when nothing was
* queued (not a G2, no session, or a malformed record).
*/
fun sendFaceclawKeyboardControl(record: ByteArray?, label: String): Boolean {
if (!isG2 || record == null || record.size < 8) {
return false
}
monitor.withLock {
if (!running || !sessionReady) {
logLine("skip keyboard control ($label); session not ready")
return false
}
pendingMessages.addLast(messageBuilder.faceclawKeyboardControl(record, label))
}
interruptibleSleep.interrupt()
return true
}
/**
* Forward render-characteristic audio packets to the listener WITHOUT
* sending the stock EvenHub audio-control enable. Used for the CFW
@@ -1894,6 +1928,18 @@ class GlassesSessionCore(
}
logDebug("onNotification: address=" + address + " characteristicUuid=" + characteristicUuid + " data.length=" + data.size)
val frame = BleProtocol.parseFrame(data)
if (frame.ok && frame.sid == BleProtocol.SID_UI_SETTING) {
// CFW keyboard-bridge records (field 131) come from whichever temple hosts the
// keyboard. They are their own stream: neither an ACK nor glasses input, and the
// once-a-second status record among them must not count as user activity (which
// would hold off battery polling).
val keyboardEvent = BleProtocol.parseFaceclawKeyboardEvent(frame.pb)
if (keyboardEvent != null) {
monitor.withLock { lastIncomingAtMs = now() }
emitKeyboardEvent(keyboardEvent)
return
}
}
val decodedWearState = BleProtocol.parseWearState(frame)
val compassEvent = if (address.equals(rightAddress, ignoreCase = true))
BleProtocol.parseCompassEvent(frame)
@@ -34,6 +34,11 @@ interface IosMicStatusListener {
fun onNsDataMicStatus(body: NSData, arm: String)
}
/** CFW keyboard-bridge records (the raw field-131 record) as NSData. Main queue. */
interface IosKeyboardEventListener {
fun onNsDataKeyboardEvent(body: NSData)
}
/**
* ObjC-facing facade over the shared [GlassesSessionCore] for the NativeScript app: the iOS
* counterpart of Android's FaceclawBleCommunicator with the same method names. GATT goes
@@ -230,6 +235,20 @@ class IosGlassesSession internal constructor(
return adapter
}
fun addKeyboardEventListenerNsData(listener: IosKeyboardEventListener): FaceclawKeyboardEventListener {
val adapter = object : FaceclawKeyboardEventListener {
override fun onKeyboardEvent(body: ByteArray?) =
listener.onNsDataKeyboardEvent((body ?: ByteArray(0)).data())
}
core.addKeyboardEventListener(adapter)
return adapter
}
fun removeKeyboardEventListener(listener: FaceclawKeyboardEventListener?) = core.removeKeyboardEventListener(listener)
fun sendFaceclawKeyboardControl(record: NSData?, label: String): Boolean =
core.sendFaceclawKeyboardControl(record?.byteArray(), label)
/** Every audio-characteristic packet, whether or not a capture is active (passive; sends nothing). */
fun addAudioMonitorListenerNsData(listener: IosAudioPacketListener): FaceclawAudioPacketListener {
val adapter = object : FaceclawAudioPacketListener {