Partial support for Rayneo iO

This commit is contained in:
James Babcock committed 2026-11-01 17:19:55 -08:00
1 parent 742a5a3f81
commit 4d101eefe1
23 files changed
+1954 -69

No files matched your search

@@ -28,7 +28,18 @@ class CfwTransport(private val platform: ProtocolPlatform) {
fun encode(message: ByteArray?, streamId: Int, lenses: Int, mtu: Int): List<ByteArray> =
lock.withLock {
validate(message, streamId, lenses, mtu)
val input = message!!
g2Packets(encodeRecord(message!!, lenses), streamId, mtu)
}
/**
* One record, `[flags][wire length u16][decoded CRC u16][body]`, compressed with this
* transport's persistent context. The packet envelope is the caller's: [encode] wraps it
* in G2 TPL packets, [RayNeoIoProtocol.cfwPackets] in RayNeo iO business-0xF0 packets.
*/
fun encodeRecord(message: ByteArray, lenses: Int): ByteArray =
lock.withLock {
require(message.size <= MAX_MESSAGE && lenses in 1..BOTH) { "invalid CFW record parameters" }
val input = message
if (previousLenses != lenses) reset()
val reset = resetPending
val encoder = deflater ?: platform.createDeflater().also { deflater = it }
@@ -44,7 +55,7 @@ class CfwTransport(private val platform: ProtocolPlatform) {
resetPending = false
previousLenses = lenses
}
frameRecord(body, crc(input), streamId, flags, mtu)
record(body, crc(input), flags)
}
companion object {
@@ -71,18 +82,12 @@ class CfwTransport(private val platform: ProtocolPlatform) {
@JvmStatic
fun frame(message: ByteArray?, streamId: Int, lenses: Int, mtu: Int): List<ByteArray> {
validate(message, streamId, lenses, mtu)
return frameRecord(message!!, crc(message), streamId, lenses or RESET_CONTEXT, mtu)
return g2Packets(record(message!!, crc(message), lenses or RESET_CONTEXT), streamId, mtu)
}
private fun frameRecord(
body: ByteArray,
checksum: Int,
streamId: Int,
flags: Int,
mtu: Int,
): List<ByteArray> {
val lenses = flags and BOTH
val capacity = minOf(252, mtu - 14)
/** `[flags][wire length u16][decoded CRC u16][body]`, shared by every packet envelope. */
@JvmStatic
fun record(body: ByteArray, checksum: Int, flags: Int): ByteArray {
val stream = ByteArray(body.size + 5)
stream[0] = flags.toByte()
stream[1] = body.size.toByte()
@@ -90,6 +95,13 @@ class CfwTransport(private val platform: ProtocolPlatform) {
stream[3] = checksum.toByte()
stream[4] = (checksum ushr 8).toByte()
body.copyInto(stream, 5)
return stream
}
/** G2 TPL packets (SID 0xf0) carrying one record: options byte = lenses | RESET | END. */
private fun g2Packets(stream: ByteArray, streamId: Int, mtu: Int): List<ByteArray> {
val lenses = stream[0].toInt() and BOTH
val capacity = minOf(252, mtu - 14)
val packets = mutableListOf<ByteArray>()
for (offset in stream.indices step capacity) {
val count = minOf(capacity, stream.size - offset)
@@ -4,6 +4,11 @@ package com.faceclaw.app
* queued state and sensor freshness do not. Private commands are ordered with
* frames, so wake starts on the intended PRESENT, never on an older black frame. */
internal fun GlassesSessionCore.enqueueBrightnessLocked(frameVisible: Boolean? = null) {
if (isIo) {
// The iO has no CFW brightness; ioMaintain drives the launcher's (and the screen) instead.
ioNoteFrameVisibleLocked(frameVisible)
return
}
if (!customFirmwareDetected || !sessionReady || !fixedLayoutCreated || shutdownRequested) return
val visible = frameVisible ?: brightnessSentVisible ?: return
val target = brightnessPolicy.target
@@ -345,6 +345,8 @@ internal fun GlassesSessionCore.releaseFaceclawFramebufferLease(): Boolean {
/** The address of a configured arm the OS no longer holds a bond for, or null. */
internal fun GlassesSessionCore.firstUnpairedArm(): String? {
// The iO identifies the phone by its protocol id, not an OS bond.
if (isIo) return null
if (!link.isBonded(rightAddress)) return rightAddress
if (!link.isBonded(leftAddress)) return leftAddress
return null
@@ -107,6 +107,11 @@ class GlassesSessionCore(
@Volatile internal var listener: FaceclawBleCommunicatorListener? = null
/** G2 unless [useRayNeoIo] was called before [start]. */
@Volatile internal var glassesType = GlassesType.G2
/** RayNeo iO link state (GlassesSessionIo.kt); guarded by [monitor]. */
internal val io = IoSessionState()
/**
* Optional tap for relay frames the session does not interpret: notifications on the
* right arm's data characteristic whose first two bytes are 'A','N' (the iOS ANCS
@@ -543,6 +548,28 @@ class GlassesSessionCore(
requiredFirmwareRevision = revision
}
/**
* Drive a RayNeo iO instead of a G2: one BLE link (pass its address as both arms; no
* ring), the iO handshake and page lease, and the Faceclaw display lists of the
* faceclaw-rayneo-cfw firmware. [phoneId] is this phone's stable 6-byte protocol identity:
* the glasses bind to the first one that authenticates and refuse others until they are
* put in pairing mode. Call before [start].
*/
fun useRayNeoIo(phoneId: ByteArray, phoneName: String, manufacturer: String, model: String) {
require(phoneId.size == 6) { "RayNeo iO phone id must be 6 bytes" }
require(rightAddress.equals(leftAddress, ignoreCase = true)) { "RayNeo iO uses one address for both arms" }
monitor.withLock {
glassesType = GlassesType.RAYNEO_IO
io.phoneId = phoneId.copyOf()
io.phoneName = phoneName.ifEmpty { "Faceclaw" }
io.manufacturer = manufacturer.ifEmpty { "Android" }
io.model = model.ifEmpty { "Android" }
}
}
/** True when this session drives a RayNeo iO. */
fun isRayNeoIo(): Boolean = isIo
/** Start the worker (through the host); false when it was already running. */
fun start(): Boolean {
monitor.withLock {
@@ -575,7 +602,7 @@ class GlassesSessionCore(
* quiescing its producers. Also cover direct/early close callers here;
* a successful cleanup must remain the final BLE message. Older CFWs
* fall back to the standalone framebuffer-lease release. */
if (!cfwCleanupDelivered && !sendCfwCleanup()) {
if (!cfwCleanupDelivered && !sendCfwCleanup() && !isIo) {
releaseFaceclawFramebufferLease()
}
monitor.withLock {
@@ -594,6 +621,14 @@ class GlassesSessionCore(
host.joinWorker(5_000)
ringDone?.await(5_000)
ringWorkerDone = null
if (isIo && link.isConnected(rightAddress)) {
// Otherwise the blank page stays up until the firmware's 120 s lease runs out.
try {
ioWriteControl(RayNeoIoProtocol.CTRL_PAGE_CLOSE)
} catch (t: Throwable) {
logLine("RayNeo iO page close failed: " + safeMessage(t))
}
}
monitor.withLock {
resetSessionStateLocked()
clearAllMessagesLocked("disconnect")
@@ -1533,6 +1568,7 @@ class GlassesSessionCore(
// EvenHub page lifecycle
fun sendShutdown(exitMode: Int): Boolean {
if (isIo) return ioSuspend()
return sendShutdownInternal(exitMode, true)
}
@@ -1624,6 +1660,7 @@ class GlassesSessionCore(
* reconnecting Bluetooth here would defeat the power-saving mode.
*/
fun suspendEvenHubSession(): Boolean {
if (isIo) return ioSuspend()
// Ending the plugin task releases the fb lease, which frees the
// on-glasses resource cache; forget it phone-side either way (a lost
// ack may still have taken effect).
@@ -1647,6 +1684,7 @@ class GlassesSessionCore(
* the desired frame.
*/
fun resumeEvenHubSession(): Boolean {
if (isIo) return ioResume()
var claimGeneration = 0
monitor.withLock {
if (!running || !sessionReady || chargingMode) {
@@ -1727,7 +1765,7 @@ class GlassesSessionCore(
continue
}
logWarn("Attempting to connect")
connectLoopOnce()
if (isIo) ioConnectLoopOnce() else connectLoopOnce()
continue
}
@@ -1754,6 +1792,10 @@ class GlassesSessionCore(
return
}
val uuid = characteristicUuid.lowercase()
if (isIo) {
ioOnNotification(address, uuid, data)
return
}
if (isDirectRingNotification(address, uuid)) {
handleDirectRingNotification(uuid, data)
return
@@ -1768,28 +1810,7 @@ class GlassesSessionCore(
if (data.size >= 7 && (data[6].toInt() and 255) == CfwTransport.SID) {
val acks = CfwTransport.parseAcks(data) ?: return
monitor.withLock {
lastIncomingAtMs = now()
val arm = armIndex(address)
if (arm >= 0) lastArmCfwAckAtMs[arm] = lastIncomingAtMs
for (ack in acks) {
for (message in inFlightMessages) {
val ingress = if (message.isLeftArmMessage) leftAddress else rightAddress
if (message.sid == CfwTransport.SID && address.equals(ingress, ignoreCase = true) && message.magic == ack.streamId) {
message.acceptCfwAck(ack)
if (ack.nack) ConnectionCounters.increment("g2.cfw-nack")
logLine("CFW " + (if (ack.nack) "NACK" else "ACK") + " id=" + ack.streamId
+ " ordinal=" + ack.messageId + " lens=" + ack.lens + " txseq=" + (data[2].toInt() and 255)
+ " redundant=" + (ack !== acks[0])
+ " size=" + ack.size + " crc=" + ack.checksum
+ " expected=" + message.message.size + "/" + message.cfwChecksum
+ " ackedLenses=" + message.cfwAckLenses
+ " ageMs=" + (lastIncomingAtMs - message.sentAtMs))
message.ackPayload = data.copyOf()
break
}
}
}
drainCfwAcknowledgementsLocked()
acceptCfwAcksLocked(address, acks, data[2].toInt() and 255, data)
}
interruptibleSleep.interrupt()
return
@@ -2106,6 +2127,35 @@ class GlassesSessionCore(
}
}
/**
* Apply CFW ACKs/NACKs from [address] (the G2's `aa 12` frames, or the iO's 9-byte bodies)
* to the in-flight messages they name, then complete what they finished.
*/
internal fun acceptCfwAcksLocked(address: String, acks: Array<CfwTransport.Ack>, txSeq: Int, payload: ByteArray) {
lastIncomingAtMs = now()
val arm = armIndex(address)
if (arm >= 0) lastArmCfwAckAtMs[arm] = lastIncomingAtMs
for (ack in acks) {
for (message in inFlightMessages) {
val ingress = if (message.isLeftArmMessage) leftAddress else rightAddress
if (message.sid == CfwTransport.SID && address.equals(ingress, ignoreCase = true) && message.magic == ack.streamId) {
message.acceptCfwAck(ack)
if (ack.nack) ConnectionCounters.increment("g2.cfw-nack")
logLine("CFW " + (if (ack.nack) "NACK" else "ACK") + " id=" + ack.streamId
+ " ordinal=" + ack.messageId + " lens=" + ack.lens + " txseq=" + txSeq
+ " redundant=" + (ack !== acks[0])
+ " size=" + ack.size + " crc=" + ack.checksum
+ " expected=" + message.message.size + "/" + message.cfwChecksum
+ " ackedLenses=" + message.cfwAckLenses
+ " ageMs=" + (lastIncomingAtMs - message.sentAtMs))
message.ackPayload = payload.copyOf()
break
}
}
}
drainCfwAcknowledgementsLocked()
}
override fun onConnectionStateChange(address: String?, connected: Boolean) {
if (address == null) {
return
@@ -2141,11 +2191,14 @@ class GlassesSessionCore(
monitor.withLock {
if (address.equals(rightAddress, ignoreCase = true)) {
rightConnected = connected
// The iO's one link stands for both arms.
if (isIo) leftConnected = connected
} else if (address.equals(leftAddress, ignoreCase = true)) {
leftConnected = connected
} else {
return
}
if (!connected && isIo) io.reassembler.reset()
if (!connected) {
// Before the session is ready, this is an attempt failing (or an arm
// dropping mid-setup): the connect sequence notices on its own and
@@ -0,0 +1,544 @@
package com.faceclaw.app
import com.faceclaw.app.GlassesSessionCore.Companion.hex
import com.faceclaw.app.GlassesSessionCore.Companion.safeMessage
import kotlin.random.Random
/** Which glasses a session drives. Set before [GlassesSessionCore.start]; see [GlassesSessionCore.useRayNeoIo]. */
enum class GlassesType { G2, RAYNEO_IO }
/**
* RayNeo iO session state ([GlassesSessionCore.io]); guarded by the core's monitor.
*
* The iO is one SoC on ONE BLE link that drives both eyes, so the core runs it with the same
* address in both arm slots: CFW messages keep going to the "left" arm, per-arm bookkeeping
* resolves to index 0, and the firmware ACKs each lens of a record separately, exactly what
* the existing window expects. What differs lives here: the AA55 envelope, the TLV handshake
* and guest authentication, IDENT-based capability detection, and the page lease
* (PAGE_OPEN + KEEPALIVE) that stands in for the G2's EvenHub page and framebuffer lease.
* Wire codecs: [RayNeoIoProtocol]; firmware: faceclaw-rayneo-cfw (docs/FACECLAW.md).
*/
internal class IoSessionState {
var phoneId = ByteArray(6)
var phoneName = "Faceclaw"
var manufacturer = "Android"
var model = "Android"
val reassembler = RayNeoIoProtocol.FrameReassembler()
var messageNumber = Random.nextInt(0, 0x10000)
var launcherSequence = 0
var versionReply: RayNeoIoProtocol.VersionReply? = null
var authReply: ByteArray? = null
var ident: RayNeoIoProtocol.Ident? = null
var osVersion = ""
var maxChunk = RayNeoIoProtocol.DEFAULT_MAX_CHUNK
/** Last PAGE state the glasses reported: 1 open, 0 closed, -1 none yet this link. */
var pageState = -1
var pageReason = 0
var pageReplies = 0
/** Whether the phone wants the page open (false while suspended or after the wearer closed it). */
var pageWanted = true
var pageRequestSentAtMs = 0L
var lastKeepaliveAtMs = 0L
var lastStatusAtMs = 0L
var refusals = 0
/** Whether Faceclaw's latest frame is meant to be seen (false for its blanked frames). */
var displayVisible = false
var brightnessSentLevel = -1
var lastBrightnessAtMs = 0L
/** Last `screen_status` push: 1 on, 0 off, -1 unknown. */
var screenStatus = -1
fun resetLink() {
reassembler.reset()
versionReply = null
authReply = null
ident = null
pageState = -1
pageReason = 0
pageRequestSentAtMs = 0
lastKeepaliveAtMs = 0
lastStatusAtMs = 0
brightnessSentLevel = -1
lastBrightnessAtMs = 0
screenStatus = -1
}
}
internal object IoTimings {
const val VERSION_REPLY_MS = 4_000L
const val AUTH_REPLY_MS = 4_000L
const val OS_VERSION_MS = 1_500L
const val IDENT_MS = 3_000L
const val PAGE_REPLY_MS = 4_000L
/** Well inside the firmware's 120 s page lease. */
const val KEEPALIVE_MS = 30_000L
const val STATUS_MS = 60_000L
const val PAGE_RETRY_MS = 3_000L
/** Retry cadence while the glasses refuse this phone id (waiting for pairing mode). */
const val PAIRING_RETRY_MS = 2_000L
const val PAGE_REASON_USER = 4
/** While Faceclaw shows content, re-assert the screen this often (the stock auto-off is short). */
const val SCREEN_REFRESH_MS = 5_000L
}
/** The glasses hung up at the version request: bound to another phone id, or not in pairing mode. */
internal class IoPairingRefusedException : IllegalStateException("glasses hung up at the version request")
/** CFW message types the iO firmware implements (fc_glue.c + raster cleanup). */
internal fun ioSupportsCfwType(type: Int): Boolean =
type == CFW_MSG_CLEANUP || type == CFW_MSG_UPLOAD_RESOURCE || type == CFW_MSG_EVICT_RESOURCE ||
type == CFW_MSG_DRAW_CALLS || type == CFW_MSG_SET_ROOT_DISPLAY_LIST ||
type == CFW_MSG_PRESENT || type == CFW_MSG_CREATE_SURFACE
internal val GlassesSessionCore.isIo: Boolean get() = glassesType == GlassesType.RAYNEO_IO
/** Messages the iO cannot take (stock EvenHub/settings traffic, the G2's hardware CFW modes). */
internal fun GlassesSessionCore.ioSupportsMessage(message: OutboundMessage): Boolean =
message.sid == CfwTransport.SID && message.message.isNotEmpty() && ioSupportsCfwType(message.message[0].toInt() and 255)
// ---------------------------------------------------------------------------------------------
// Writes
private fun GlassesSessionCore.ioNextMessageNumberLocked(): Int {
val n = io.messageNumber and 0xffff
io.messageNumber = (io.messageNumber + 1) and 0xffff
return n
}
/** One AA55 frame on the iO write characteristic; worker thread, outside the monitor. */
internal fun GlassesSessionCore.ioWriteFrame(business: Int, payload: ByteArray): Boolean {
val frame = monitor.withLock { RayNeoIoProtocol.encodeFrame(ioNextMessageNumberLocked(), business, payload) }
return link.writeFrames(
rightAddress, RayNeoIoBle.WRITE_CHAR_UUID,
RayNeoIoProtocol.writes(frame, link.negotiatedMtu(rightAddress)),
GattWriteMode.WITHOUT_RESPONSE, ConnectionOptions.WRITE_TIMEOUT_MS,
)
}
internal fun GlassesSessionCore.ioWriteControl(ctrl: Int): Boolean =
ioWriteFrame(RayNeoIoProtocol.BUSINESS_CFW, RayNeoIoProtocol.controlPacket(ctrl))
private fun GlassesSessionCore.ioWriteLauncher(type: Int, json: String): Boolean {
val sequence = monitor.withLock {
io.launcherSequence = if (io.launcherSequence >= 0xffff) 1 else io.launcherSequence + 1
io.launcherSequence
}
val envelope = RayNeoIoProtocol.Envelope(type, json, sequence = sequence, mode = RayNeoIoProtocol.MODE_REQUEST)
return ioWriteFrame(RayNeoIoProtocol.BUSINESS_LAUNCHER, RayNeoIoProtocol.encodeEnvelope(envelope))
}
internal fun GlassesSessionCore.ioRequestStatus(): Boolean =
ioWriteLauncher(RayNeoIoProtocol.LAUNCHER_GENERAL_STATUS, RayNeoIoProtocol.GENERAL_STATUS_REQUEST)
/** From the image path (enqueueBrightnessLocked): a visible frame wakes the screen at once. */
internal fun GlassesSessionCore.ioNoteFrameVisibleLocked(frameVisible: Boolean?) {
if (frameVisible == null) return
if (frameVisible && !io.displayVisible) io.lastBrightnessAtMs = 0
io.displayVisible = frameVisible
}
/**
* The writes for one queued CFW message: the shared record (persistent deflate context, as
* on the G2) in `[opt][stream][chunk]` packets, each its own AA55 frame. The stream byte is
* the message's magic, which the firmware echoes in its per-lens ACKs.
*/
internal fun GlassesSessionCore.ioCfwWrites(message: OutboundMessage, mtu: Int): List<ByteArray> {
val transport = cfwTransports[0]
if (message.cfwRetries > 0) transport.reset()
val record = transport.encodeRecord(message.message, CfwTransport.BOTH)
return monitor.withLock {
RayNeoIoProtocol.cfwPackets(record, message.magic, io.maxChunk).flatMap { packet ->
RayNeoIoProtocol.writes(RayNeoIoProtocol.encodeFrame(ioNextMessageNumberLocked(), RayNeoIoProtocol.BUSINESS_CFW, packet), mtu)
}
}
}
/** A message the iO can't run (see [ioSupportsMessage]): never sent, never waited on. */
internal fun GlassesSessionCore.ioDropUnsupported(message: OutboundMessage) {
monitor.withLock {
inFlightMessages.remove(message)
if (message.magic != 0) magicPool.release(message.sid, message.magic, message.label, "unsupported on RayNeo iO")
}
logDebug("RayNeo iO: dropped unsupported message " + message.label + " sid=" + message.sid)
}
// ---------------------------------------------------------------------------------------------
// Connect (worker thread)
private fun GlassesSessionCore.ioAwait(timeoutMs: Long, what: String, ready: () -> Boolean) {
val deadline = now() + timeoutMs
monitor.withLock {
while (true) {
if (ready()) return
if (!running || userDisconnectRequested) throw IllegalStateException("stopped while waiting for $what")
if (!rightConnected) throw IoLinkLostException(what)
val remaining = deadline - now()
if (remaining <= 0) throw IllegalStateException("$what timed out")
monitor.awaitMs(minOf(remaining, 100L))
}
}
}
private class IoLinkLostException(what: String) : IllegalStateException("link lost while waiting for $what")
internal fun GlassesSessionCore.ioConnectLoopOnce() {
monitor.withLock {
wearState = -1
io.resetLink()
}
setStateDisplay("connecting", "Connecting to the glasses...")
ConnectionCounters.increment("io.connect-attempt")
val address = rightAddress
try {
if (!link.connect(address, ConnectionOptions.ARM_CONNECT_WINDOW_MS)) {
handleTransportFailure("glasses not found", "Can't find the glasses. They may be off, in their case, or out of range.")
return
}
link.requestHighPriority(address)
link.requestMtu(address, RayNeoIoBle.REQUESTED_MTU, ConnectionOptions.CONNECT_TIMEOUT_MS)
if (!link.discoverServices(address, ConnectionOptions.SERVICES_TIMEOUT_MS)) throw IllegalStateException("discoverServices failed: $address")
if (!link.enableNotifications(address, RayNeoIoBle.NOTIFY_CHAR_UUID, true, ConnectionOptions.DESCRIPTOR_TIMEOUT_MS)) {
throw IllegalStateException("enableNotifications failed: $address")
}
link.requestLe2mPhy(address)
monitor.withLock {
rightConnected = true
leftConnected = true
}
// Version exchange. Glasses bound to another phone id (or not in pairing mode)
// hang up ~100 ms after this request instead of answering.
val phone = monitor.withLock { io.phoneId.copyOf() }
logDebug("RayNeo iO: phone id " + hex(phone))
if (!ioWriteFrame(RayNeoIoProtocol.BUSINESS_HANDSHAKE,
RayNeoIoProtocol.versionRequest(phone, io.phoneName, io.manufacturer, io.model))) {
throw IllegalStateException("version request write failed")
}
try {
ioAwait(IoTimings.VERSION_REPLY_MS, "version reply") { io.versionReply != null }
} catch (lost: IoLinkLostException) {
throw IoPairingRefusedException()
}
val reply = monitor.withLock { io.versionReply!! }
if (reply.accountBound) throw IoPairingRefusedException()
logLine("RayNeo iO: glasses " + hex(reply.glassesId) + " serial " + reply.serial + " protocol " + reply.protocolVersion)
val random = Random.nextBytes(4)
if (!ioWriteFrame(RayNeoIoProtocol.BUSINESS_HANDSHAKE, RayNeoIoProtocol.guestAuthRequest(random, phone, reply.glassesId))) {
throw IllegalStateException("guest auth write failed")
}
ioAwait(IoTimings.AUTH_REPLY_MS, "guest auth reply") { io.authReply != null }
val authReply = monitor.withLock { io.authReply!! }
if (!RayNeoIoProtocol.verifyGuestAuthReply(authReply, phone, reply.glassesId)) {
throw IllegalStateException("guest auth proof mismatch")
}
monitor.withLock { io.refusals = 0 }
// Battery and the OS version: answers arrive asynchronously; the version only labels
// the firmware info, so a missing one is not fatal.
ioRequestStatus()
ioWriteFrame(RayNeoIoProtocol.BUSINESS_OTA,
RayNeoIoProtocol.encodeEnvelope(RayNeoIoProtocol.Envelope(RayNeoIoProtocol.OTA_VERSION, "{}")))
try {
ioAwait(IoTimings.OS_VERSION_MS, "OS version") { io.osVersion.isNotEmpty() }
} catch (e: IoLinkLostException) {
throw e
} catch (_: IllegalStateException) {
}
// Capability: the custom firmware answers QUERY with IDENT; stock firmware stays silent.
ioWriteControl(RayNeoIoProtocol.CTRL_QUERY)
val ident = try {
ioAwait(IoTimings.IDENT_MS, "IDENT") { io.ident != null }
monitor.withLock { io.ident }
} catch (e: IoLinkLostException) {
throw e
} catch (_: IllegalStateException) {
null
}
val os = monitor.withLock { io.osVersion.ifEmpty { "RayNeo iO" } }
val info = BleProtocol.FirmwareInfo(os, os,
if (ident != null && ident.faceclaw) "Faceclaw/" + ident.faceclawRevision else "")
logLine("RayNeo iO: " + os + ", " + (if (ident == null) "no IDENT (stock firmware)"
else ident.name + " " + ident.width + "x" + ident.height + " chunk " + ident.maxChunk
+ " flags 0x" + ident.flags.toString(16) + " faceclaw " + ident.faceclawRevision))
emitFirmwareInfo(info)
if (!info.isCompatible(requiredFirmwareRevision)) {
monitor.withLock {
// The worker loop halts on this and explains it (handleIncompatibleFirmware).
incompatibleFirmware = info
}
return
}
monitor.withLock {
io.maxChunk = ident!!.maxChunk.coerceIn(16, 4000)
io.pageWanted = true
io.pageRequestSentAtMs = now()
}
ioWriteControl(RayNeoIoProtocol.CTRL_PAGE_OPEN)
try {
ioAwait(IoTimings.PAGE_REPLY_MS, "page open") { io.pageReplies > 0 }
} catch (e: IoLinkLostException) {
throw e
} catch (_: IllegalStateException) {
// The launcher may be busy; ioMaintain keeps asking.
}
monitor.withLock {
sessionReady = true
shutdownRequested = false
customFirmwareDetected = true
clearAllMessagesLocked("session ready")
fixedLayoutCreated = io.pageState == 1
displayedFingerprint = ""
lastAckAtMs = now()
lastIncomingAtMs = lastAckAtMs
lastConnectionOrInputAtMs = lastAckAtMs
lastSessionReadyAtMs = lastAckAtMs
imageRetryAfterMs = 0
consecutiveAckTimeouts = 0
cfwCleanupDelivered = false
lastCfwCleanupAckMagic = 0
for (transport in cfwTransports) transport.reset()
io.lastKeepaliveAtMs = lastAckAtMs
io.lastStatusAtMs = lastAckAtMs
}
setStateDisplay("connected", "Connected.")
ConnectionCounters.increment("io.session-ready")
logLine("RayNeo iO session ready (page " + (if (fixedLayoutCreated) "open" else "pending") + ")")
} catch (refused: IoPairingRefusedException) {
val count = monitor.withLock {
io.refusals++
reconnectAfterMs = now() + IoTimings.PAIRING_RETRY_MS
io.refusals
}
ConnectionCounters.increment("io.pairing-refused")
logLine("RayNeo iO refused this phone (" + count + "); waiting for pairing mode")
link.disconnect(address)
monitor.withLock {
rightConnected = false
leftConnected = false
}
setStateDisplay("retrying",
"The glasses aren't accepting this phone yet. Put them in pairing mode: on the charger, "
+ "hold the button about 5 seconds until the light blinks blue.")
} catch (t: Throwable) {
logLine("RayNeo iO connect failed: " + safeMessage(t))
handleTransportFailure("connect failed")
}
}
// ---------------------------------------------------------------------------------------------
// Session upkeep (worker thread, from driveSession, outside the monitor)
/** Page open/close requests, keepalives, status polls and the screen (launcher brightness). */
internal fun GlassesSessionCore.ioMaintain() {
var ctrl = -1
var status = false
var brightness = -1
monitor.withLock {
if (!sessionReady) return
val now = now()
if (io.pageWanted && !fixedLayoutCreated && now - io.pageRequestSentAtMs >= IoTimings.PAGE_RETRY_MS) {
ctrl = RayNeoIoProtocol.CTRL_PAGE_OPEN
io.pageRequestSentAtMs = now
} else if (!io.pageWanted && io.pageState == 1 && now - io.pageRequestSentAtMs >= IoTimings.PAGE_RETRY_MS) {
ctrl = RayNeoIoProtocol.CTRL_PAGE_CLOSE
io.pageRequestSentAtMs = now
} else if (io.pageWanted && fixedLayoutCreated && now - io.lastKeepaliveAtMs >= IoTimings.KEEPALIVE_MS) {
ctrl = RayNeoIoProtocol.CTRL_KEEPALIVE
io.lastKeepaliveAtMs = now
}
if (now - io.lastStatusAtMs >= IoTimings.STATUS_MS) {
status = true
io.lastStatusAtMs = now
}
// Faceclaw decides when the display is dark (blanked frames); while it shows
// content, keep the iO's screen on and at Faceclaw's brightness.
val level = RayNeoIoProtocol.brightnessLevel(brightnessPolicy.target)
if (fixedLayoutCreated && io.pageWanted && io.displayVisible && !shutdownRequested
&& (level != io.brightnessSentLevel || now - io.lastBrightnessAtMs >= IoTimings.SCREEN_REFRESH_MS)) {
brightness = level
io.brightnessSentLevel = level
io.lastBrightnessAtMs = now
}
}
if (ctrl >= 0) {
logDebug("RayNeo iO: control $ctrl")
ioWriteControl(ctrl)
}
if (status) ioRequestStatus()
if (brightness > 0) ioWriteLauncher(RayNeoIoProtocol.LAUNCHER_BRIGHTNESS, RayNeoIoProtocol.launcherBrightness(brightness))
}
/** Stop drawing and close the page, keeping the BLE link (the EvenHub suspend analogue). */
internal fun GlassesSessionCore.ioSuspend(): Boolean {
monitor.withLock {
if (!running || !sessionReady) return false
shutdownRequested = true
io.pageWanted = false
io.pageRequestSentAtMs = 0
clearAllMessagesLocked("RayNeo iO suspend")
displayedFingerprint = ""
}
interruptibleSleep.interrupt()
return true
}
/** Reopen the page; the drive loop resends the desired frame once it is open. */
internal fun GlassesSessionCore.ioResume(): Boolean {
monitor.withLock {
if (!running || !sessionReady) return false
shutdownRequested = false
io.pageWanted = true
io.pageRequestSentAtMs = 0
fixedLayoutCreated = false
clearAllMessagesLocked("RayNeo iO resume")
displayedFingerprint = ""
imageRetryAfterMs = 0
}
interruptibleSleep.interrupt()
return true
}
// ---------------------------------------------------------------------------------------------
// Inbound (BLE callback thread)
internal fun GlassesSessionCore.ioOnNotification(address: String, characteristicUuid: String, data: ByteArray) {
if (RayNeoIoBle.NOTIFY_CHAR_UUID != characteristicUuid || !address.equals(rightAddress, ignoreCase = true)) return
val frames = monitor.withLock { io.reassembler.ingest(data) }
for (frame in frames) {
when (frame.business) {
RayNeoIoProtocol.BUSINESS_HANDSHAKE -> monitor.withLock {
val version = RayNeoIoProtocol.parseVersionReply(frame.payload)
if (version != null) io.versionReply = version
else if (RayNeoIoProtocol.isGuestAuthReply(frame.payload)) io.authReply = frame.payload
monitor.signalAll()
}
RayNeoIoProtocol.BUSINESS_LAUNCHER -> ioHandleLauncher(frame.payload)
RayNeoIoProtocol.BUSINESS_OTA -> {
val envelope = RayNeoIoProtocol.decodeEnvelope(frame.payload) ?: continue
if (envelope.type != RayNeoIoProtocol.OTA_VERSION) continue
val os = try { Json.parse(envelope.json).asObject()?.get("OsVersion").asString() } catch (_: Exception) { null }
if (os != null) monitor.withLock {
io.osVersion = os
monitor.signalAll()
}
}
RayNeoIoProtocol.BUSINESS_CFW -> ioHandleCfw(address, frame)
}
}
}
private fun GlassesSessionCore.ioHandleLauncher(payload: ByteArray) {
val envelope = RayNeoIoProtocol.decodeEnvelope(payload) ?: return
val screen = RayNeoIoProtocol.screenStatusFromLauncherJson(envelope.json)
if (screen >= 0) {
val changed = monitor.withLock {
val was = io.screenStatus
io.screenStatus = screen
// Woken by the wearer (or the timeout ran out): re-assert promptly if Faceclaw is showing.
if (screen == 0) io.lastBrightnessAtMs = 0
was != screen
}
if (changed) logLine("RayNeo iO screen " + (if (screen == 1) "on" else "off"))
return
}
val battery = RayNeoIoProtocol.batteryFromLauncherJson(envelope.json)
if (battery < 0) return
val charging = if (envelope.json.contains("\"isCharging\":true")) 1 else if (envelope.json.contains("\"isCharging\":false")) 0 else -1
var changed = false
monitor.withLock {
lastIncomingAtMs = now()
if (battery != headsetBattery || (charging >= 0 && charging != headsetCharging)) {
headsetBattery = battery
if (charging >= 0) headsetCharging = charging
changed = true
}
}
if (changed) emitBatteryState(headsetBattery, headsetCharging)
}
private fun GlassesSessionCore.ioHandleCfw(address: String, frame: RayNeoIoProtocol.Frame) {
val payload = frame.payload
if (payload.isEmpty()) return
when (payload[0].toInt() and 255) {
RayNeoIoProtocol.KIND_ACK, RayNeoIoProtocol.KIND_NACK -> {
val ack = RayNeoIoProtocol.parseCfwAck(payload) ?: return
monitor.withLock {
acceptCfwAcksLocked(address, arrayOf(ack), frame.messageNumber and 255, payload)
}
interruptibleSleep.interrupt()
}
RayNeoIoProtocol.KIND_IDENT -> monitor.withLock {
io.ident = RayNeoIoProtocol.parseIdent(payload)
monitor.signalAll()
}
RayNeoIoProtocol.KIND_PAGE -> ioHandlePage(payload)
RayNeoIoProtocol.KIND_GESTURE -> ioHandleGesture(RayNeoIoProtocol.parseGesture(payload) ?: return)
else -> logDebug("RayNeo iO: CFW reply kind " + (payload[0].toInt() and 255) + " " + hex(payload.copyOf(minOf(payload.size, 24))))
}
}
private fun GlassesSessionCore.ioHandlePage(payload: ByteArray) {
val state = RayNeoIoProtocol.parsePageState(payload)
val reason = if (payload.size >= 3) payload[2].toInt() and 255 else 0
var lost = false
monitor.withLock {
io.pageState = state
io.pageReason = reason
io.pageReplies++
lastIncomingAtMs = now()
if (state == 1) {
if (io.pageWanted && !fixedLayoutCreated && sessionReady) {
// (Re)opened: the drive loop resends the desired frame from scratch.
fixedLayoutCreated = true
displayedFingerprint = ""
imageRetryAfterMs = 0
io.lastKeepaliveAtMs = now()
io.lastBrightnessAtMs = 0
}
} else if (state == 0 && fixedLayoutCreated) {
// The page closed under us (lease, the wearer's long press): the firmware freed
// this session's resources, so start over once it reopens.
lost = true
fixedLayoutCreated = false
clearAllMessagesLocked("RayNeo iO page closed (reason $reason)")
displayedFingerprint = ""
if (reason == IoTimings.PAGE_REASON_USER) io.pageWanted = false
io.pageRequestSentAtMs = now()
}
monitor.signalAll()
}
if (lost) logLine("RayNeo iO page closed by the glasses (reason $reason)")
interruptibleSleep.interrupt()
}
private fun GlassesSessionCore.ioHandleGesture(gesture: RayNeoIoProtocol.Gesture) {
val event: G2Event? = when (gesture.eventType) {
// Same numbering as the G2's OsEventTypeList; head up wakes like the G2 CFW's forward.
BleProtocol.EVENT_HEAD_UP -> G2Event("display-wake", "", BleProtocol.EVENT_HEAD_UP, BleProtocol.EVENT_SOURCE_GLASSES_R, 0)
BleProtocol.EVENT_HEAD_DOWN -> null
else -> G2Event("sys-event", "", gesture.eventType, BleProtocol.EVENT_SOURCE_GLASSES_R, 0)
}
monitor.withLock {
lastIncomingAtMs = now()
if (event != null) lastConnectionOrInputAtMs = lastIncomingAtMs
if (event != null && "sys-event" == event.kind && !io.pageWanted && sessionReady) {
// The wearer touched the glasses after closing our page: take it back.
io.pageWanted = true
shutdownRequested = false
io.pageRequestSentAtMs = 0
}
}
logLine("RayNeo iO gesture type=" + gesture.eventType + " source=" + gesture.source + (if (event == null) " (ignored)" else ""))
if (event == null) return
val frameId = frameTimings.startFrame("input:" + event.kind + " type=" + event.eventType + " src=" + event.eventSource)
frameTimings.log(frameId, "input event decoded from RayNeo iO notification")
emitRingEvent(event, frameId)
}
@@ -44,6 +44,7 @@ internal fun GlassesSessionCore.driveSession(): Long {
benchmarkReadyAtMs = now() + 1_000
}
}
if (isIo) ioMaintain()
var messageToWrite: OutboundMessage? = null
var messageToPrewrite: OutboundMessage? = null
var heartbeatToWrite: OutboundMessage? = null
@@ -64,7 +65,7 @@ internal fun GlassesSessionCore.driveSession(): Long {
clearPendingMessagesLocked("after CFW cleanup")
return 250
}
if (sessionReady
if (sessionReady && !isIo
&& now - lastFaceclawFramebufferLeaseQueuedAtMs >= FACECLAW_WAKE_LEASE_RENEW_MS
&& !hasPendingOrInflightKindLocked("framebuffer-lease-control")) {
enqueueFaceclawFramebufferControlLocked(
@@ -73,7 +74,7 @@ internal fun GlassesSessionCore.driveSession(): Long {
)
}
if (faceclawWakeLeaseEnabled
&& sessionReady
&& sessionReady && !isIo
&& now - lastFaceclawWakeLeaseQueuedAtMs >= FACECLAW_WAKE_LEASE_RENEW_MS
&& !hasPendingOrInflightKindLocked("wake-lease-control")) {
enqueueFaceclawWakeControlLocked(
@@ -148,6 +149,7 @@ internal fun GlassesSessionCore.driveSession(): Long {
}
} else {
if (messageToPrewrite == null
&& !isIo // the iO's page lease is ioMaintain's
&& !shutdownRequested
&& !fixedLayoutCreated
&& pendingMessages.isEmpty()
@@ -158,14 +160,14 @@ internal fun GlassesSessionCore.driveSession(): Long {
// Prewrite outside the lock; the logical message remains pending until
// its final BLE frame is sent after the current protocol ACK.
}
if (messageToPrewrite == null && !shutdownRequested && fixedLayoutCreated
if (messageToPrewrite == null && !isIo && !shutdownRequested && fixedLayoutCreated
&& (if (firmwareDebugFlagsEnabled) 2 else 1) != firmwareDebugFlagsLastSent
&& pendingMessages.isEmpty() && inFlightMessages.isEmpty()) {
logLine("enqueueing firmware debug flags " + (if (firmwareDebugFlagsEnabled) "show" else "hide"))
enqueueFirmwareDebugFlagsLocked()
}
if (messageToPrewrite == null && !shutdownRequested && fixedLayoutCreated
if (messageToPrewrite == null && !isIo && !shutdownRequested && fixedLayoutCreated
&& (if (compassOwners.isEmpty()) 0 else 1) != compassControlLastSent
&& pendingMessages.isEmpty() && inFlightMessages.isEmpty()) {
val wanted = compassOwners.isNotEmpty()
@@ -176,7 +178,7 @@ internal fun GlassesSessionCore.driveSession(): Long {
if (benchmarkActive) {
maintainBenchmarkLocked(now)
}
if (!benchmarkActive) maintainBrightnessLocked(now)
if (!benchmarkActive && !isIo) maintainBrightnessLocked(now)
// Up to WINDOW_SIZE messages may be in flight at once (full
// pipelining); a slot frees when an ack arrives. An active
@@ -319,6 +321,7 @@ internal enum class HeartbeatStep {
}
internal fun GlassesSessionCore.heartbeatStepLocked(imageWaiting: Boolean): HeartbeatStep {
if (isIo) return HeartbeatStep.NONE
val now = now()
val heartbeatEligible = !shutdownRequested && fixedLayoutCreated
val heartbeatPending = heartbeatEligible && hasPendingOrInflightKindLocked("heartbeat")
@@ -369,6 +372,12 @@ internal fun GlassesSessionCore.createHeartbeatMessage(): OutboundMessage {
}
internal fun GlassesSessionCore.writeMessage(message: OutboundMessage): Boolean {
if (isIo && !ioSupportsMessage(message)) {
// G2-only traffic (EvenHub/settings frames, the G2 hardware CFW modes) that a feature
// queued anyway: the iO would NACK it into the replay limit, so it never goes out.
ioDropUnsupported(message)
return true
}
val now = now()
message.writeStartedAtMs = now
message.sentAtMs = now
@@ -398,6 +407,8 @@ internal fun GlassesSessionCore.writeMessage(message: OutboundMessage): Boolean
frames = listOf(prewrittenFrames[prewrittenFrames.size - 1])
prewrittenMessage = null
prewrittenFrames = emptyList()
} else if (isIo) {
frames = ioCfwWrites(message, link.negotiatedMtu(writeAddress))
} else if (message.sid == CfwTransport.SID) {
if (message.cfwRetries > 0) cfwTransports[if (message.isLeftArmMessage) 0 else 1].reset()
frames = cfwTransports[if (message.isLeftArmMessage) 0 else 1].encode(
@@ -413,9 +424,9 @@ internal fun GlassesSessionCore.writeMessage(message: OutboundMessage): Boolean
}
val result = link.writeFrames(
writeAddress,
BleProtocol.WRITE_CHAR_UUID,
if (isIo) RayNeoIoBle.WRITE_CHAR_UUID else BleProtocol.WRITE_CHAR_UUID,
frames,
ConnectionOptions.WRITE_MODE,
if (isIo) GattWriteMode.WITHOUT_RESPONSE else ConnectionOptions.WRITE_MODE,
ConnectionOptions.WRITE_TIMEOUT_MS
)
@@ -1019,7 +1030,8 @@ internal fun GlassesSessionCore.createAudioControlMessageLocked(enable: Boolean)
}
internal fun GlassesSessionCore.shouldPollBatteryLocked(now: Long): Boolean {
return !shutdownRequested
return !isIo // the iO's status polls are ioMaintain's
&& !shutdownRequested
&& sessionReady
&& pendingMessages.isEmpty()
&& inFlightMessages.isEmpty()
@@ -0,0 +1,469 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/**
* RayNeo iO wire codecs (stock link plus the Faceclaw custom-firmware link). Pure functions
* and small value types; no I/O, threads or platform APIs.
*
* The iO is one SoC driving both eyes over ONE BLE connection. Everything travels in AA55
* frames on one write characteristic and one notify characteristic; the frame's "business"
* byte selects the subsystem: 0x10 handshake (TLV), 9 OTA and 13..22 apps (protobuf-style
* envelope + JSON), 0xF0 the custom-firmware link. The CFW link carries Faceclaw's G2 records
* unchanged (see [CfwTransport.encodeRecord]) inside `[opt][stream][chunk]` packets, and the
* firmware answers with the G2's 9-byte ACK body, one ACK per targeted lens.
*
* Protocol knowledge from the MIT-licensed Glassly SDK and CFW (tetramo-labs/glassly,
* tetramo-labs/glassly-rayneo-cfw); the Faceclaw firmware fork documents its additions in
* faceclaw-rayneo-cfw/docs/FACECLAW.md.
*/
object RayNeoIoBle {
const val SERVICE_UUID = "0000b81d-0000-1000-8000-00805f9b34fb"
/** Phone -> glasses, write without response. */
const val WRITE_CHAR_UUID = "ea8b70d5-2bd3-49ab-9c31-9c38b2c3c4f9"
/** Glasses -> phone, notifications. */
const val NOTIFY_CHAR_UUID = "7db3e235-3608-41f3-a03c-955fcbd2ea4b"
const val REQUESTED_MTU = 512
/** Advertised manufacturer data company id; the payload is `[07][MAC x6]...` (not in pairing mode). */
const val MANUFACTURER_ID = 0x5716
@JvmStatic fun matchesName(name: String?): Boolean = name != null && name.contains("rayneo", ignoreCase = true)
/** The glasses' MAC ("00:6A:5E:5F:33:C2") from manufacturer data, or null. */
@JvmStatic
fun macFromManufacturerData(data: ByteArray?): String? {
if (data == null || data.size < 7 || data[0].toInt() != 7) return null
return (1..6).joinToString(":") { i -> (data[i].toInt() and 255).toString(16).padStart(2, '0').uppercase() }
}
}
object RayNeoIoProtocol {
const val BUSINESS_OTA = 9
const val BUSINESS_LAUNCHER = 15
const val BUSINESS_HANDSHAKE = 0x10
const val BUSINESS_CFW = 0xf0
const val FRAME_OVERHEAD = 10
const val MIN_FRAME_BYTES = 10
/** Program constant of the stock app's guest authentication (not a secret). */
private val SALT = byteArrayOf(
0x07, 0x12, 0xc8.toByte(), 0xad.toByte(), 0x27, 0x74, 0x41, 0x95.toByte(),
0xde.toByte(), 0x5f, 0xa1.toByte(), 0xea.toByte(), 0x6d, 0x02, 0x5f, 0xb8.toByte(),
)
// ---- CRC-16/XMODEM (poly 0x1021, init 0) -----------------------------------------------
@JvmStatic
fun crc16Xmodem(bytes: ByteArray, from: Int = 0, to: Int = bytes.size): Int {
var crc = 0
for (i in from until to) {
crc = crc xor ((bytes[i].toInt() and 255) shl 8)
repeat(8) { crc = if (crc and 0x8000 != 0) ((crc shl 1) xor 0x1021) and 0xffff else (crc shl 1) and 0xffff }
}
return crc
}
// ---- AA55 frames --------------------------------------------------------------------------
class Frame(
@JvmField val messageNumber: Int,
@JvmField val packetType: Int,
@JvmField val business: Int,
@JvmField val payload: ByteArray,
)
/** `AA 55 [len u16 BE = total-6] [msg u16 BE] [packetType] [business] payload [crc16 BE of bytes 4..end-2]`. */
@JvmStatic
fun encodeFrame(messageNumber: Int, business: Int, payload: ByteArray, packetType: Int = 0): ByteArray {
val frame = ByteArray(FRAME_OVERHEAD + payload.size)
val length = frame.size - 6
frame[0] = 0xaa.toByte()
frame[1] = 0x55
frame[2] = (length ushr 8).toByte()
frame[3] = length.toByte()
frame[4] = (messageNumber ushr 8).toByte()
frame[5] = messageNumber.toByte()
frame[6] = packetType.toByte()
frame[7] = business.toByte()
payload.copyInto(frame, 8)
val crc = crc16Xmodem(frame, 4, frame.size - 2)
frame[frame.size - 2] = (crc ushr 8).toByte()
frame[frame.size - 1] = crc.toByte()
return frame
}
/** Split a frame into ATT writes of at most `mtu - 3` bytes. */
@JvmStatic
fun writes(frame: ByteArray, mtu: Int): List<ByteArray> {
val chunk = (mtu - 3).coerceAtLeast(20)
return (frame.indices step chunk).map { frame.copyOfRange(it, minOf(it + chunk, frame.size)) }
}
@JvmStatic
fun decodeFrame(bytes: ByteArray): Frame? {
if (bytes.size < MIN_FRAME_BYTES || bytes[0] != 0xaa.toByte() || bytes[1] != 0x55.toByte()) return null
val total = (((bytes[2].toInt() and 255) shl 8) or (bytes[3].toInt() and 255)) + 6
if (total != bytes.size) return null
val crc = ((bytes[total - 2].toInt() and 255) shl 8) or (bytes[total - 1].toInt() and 255)
if (crc != crc16Xmodem(bytes, 4, total - 2)) return null
val number = ((bytes[4].toInt() and 255) shl 8) or (bytes[5].toInt() and 255)
return Frame(number, bytes[6].toInt() and 255, bytes[7].toInt() and 255, bytes.copyOfRange(8, total - 2))
}
/**
* Frames from notification chunks: a frame may span several notifications. Bytes before a
* frame head are skipped; a head whose CRC fails is skipped past its magic.
*/
class FrameReassembler {
private var buffer = ByteArray(0)
fun reset() {
buffer = ByteArray(0)
}
fun ingest(chunk: ByteArray): List<Frame> {
buffer += chunk
val out = ArrayList<Frame>()
var offset = 0
while (true) {
while (offset + 1 < buffer.size && !(buffer[offset] == 0xaa.toByte() && buffer[offset + 1] == 0x55.toByte())) offset++
if (buffer.size - offset < 4) break
val total = (((buffer[offset + 2].toInt() and 255) shl 8) or (buffer[offset + 3].toInt() and 255)) + 6
if (total < MIN_FRAME_BYTES) { offset += 2; continue }
if (buffer.size - offset < total) break
val frame = decodeFrame(buffer.copyOfRange(offset, offset + total))
if (frame == null) { offset += 2; continue }
out.add(frame)
offset += total
}
buffer = buffer.copyOfRange(minOf(offset, buffer.size), buffer.size)
return out
}
val pendingBytes: Int get() = buffer.size
}
// ---- TLV (tag u8, length u16 BE) ------------------------------------------------------------
class Tlv(@JvmField val tag: Int, @JvmField val value: ByteArray)
@JvmStatic
fun tlv(tag: Int, value: ByteArray): ByteArray {
val out = ByteArray(3 + value.size)
out[0] = tag.toByte()
out[1] = (value.size ushr 8).toByte()
out[2] = value.size.toByte()
value.copyInto(out, 3)
return out
}
@JvmStatic
fun decodeTlvs(bytes: ByteArray): List<Tlv>? {
val out = ArrayList<Tlv>()
var i = 0
while (i < bytes.size) {
if (bytes.size - i < 3) return null
val len = ((bytes[i + 1].toInt() and 255) shl 8) or (bytes[i + 2].toInt() and 255)
if (bytes.size - i - 3 < len) return null
out.add(Tlv(bytes[i].toInt() and 255, bytes.copyOfRange(i + 3, i + 3 + len)))
i += 3 + len
}
return out
}
private fun List<Tlv>.value(tag: Int): ByteArray? = firstOrNull { it.tag == tag }?.value
// ---- Handshake (business 0x10) ----------------------------------------------------------------
const val PLATFORM_IOS = 1
const val PLATFORM_ANDROID = 2
/** Version request. `phoneId` is a stable 6-byte protocol identity the glasses bind to. */
@JvmStatic
fun versionRequest(phoneId: ByteArray, phoneName: String, manufacturer: String, model: String, platform: Int = PLATFORM_ANDROID): ByteArray {
require(phoneId.size == 6)
val inner = tlv(0x10, byteArrayOf(1)) + tlv(0x11, phoneId) + tlv(0x12, phoneName.encodeToByteArray()) +
tlv(0x13, byteArrayOf(platform.toByte())) + tlv(0x16, manufacturer.encodeToByteArray()) +
tlv(0x17, model.encodeToByteArray())
return tlv(0x11, inner)
}
class VersionReply(
@JvmField val protocolVersion: Int,
/** The glasses' Bluetooth MAC, which the auth proof covers. */
@JvmField val glassesId: ByteArray,
@JvmField val serial: String?,
/** Tags 0x19/0x1a: bound to another phone's account; guest auth will not work. */
@JvmField val accountBound: Boolean,
)
@JvmStatic
fun parseVersionReply(payload: ByteArray): VersionReply? {
val body = decodeTlvs(payload)?.value(0x11) ?: return null
val fields = decodeTlvs(body) ?: return null
val id = fields.value(0x11)?.takeIf { it.size == 6 } ?: return null
return VersionReply(
fields.value(0x10)?.firstOrNull()?.toInt()?.and(255) ?: 0,
id,
fields.value(0x14)?.decodeToString()?.trimEnd('\u0000'),
fields.value(0x19) != null || fields.value(0x1a) != null,
)
}
/** `SHA-256(random4 ‖ phoneId6 ‖ glassesId6 ‖ SALT)`, both directions. */
@JvmStatic
fun authProof(random: ByteArray, phoneId: ByteArray, glassesId: ByteArray): ByteArray {
val digest = Sha256Digest()
digest.update(random)
digest.update(phoneId)
digest.update(glassesId)
digest.update(SALT)
return digest.digest()
}
@JvmStatic
fun guestAuthRequest(random: ByteArray, phoneId: ByteArray, glassesId: ByteArray): ByteArray {
require(random.size == 4 && phoneId.size == 6 && glassesId.size == 6)
return tlv(0x18, tlv(0x10, random) + tlv(0x11, authProof(random, phoneId, glassesId)))
}
/** The glasses' answer proves they know the same phone and glasses ids. */
@JvmStatic
fun verifyGuestAuthReply(payload: ByteArray, phoneId: ByteArray, glassesId: ByteArray): Boolean {
val body = decodeTlvs(payload)?.value(0x19) ?: return false
val fields = decodeTlvs(body) ?: return false
val random = fields.value(0x10)?.takeIf { it.size == 4 } ?: return false
val proof = fields.value(0x11)?.takeIf { it.size == 32 } ?: return false
return proof.contentEquals(authProof(random, phoneId, glassesId))
}
/** True for a guest-auth reply (outer tag 0x19), valid or not. */
@JvmStatic fun isGuestAuthReply(payload: ByteArray): Boolean = decodeTlvs(payload)?.value(0x19) != null
// ---- Business envelope (9, 13..22): 08 version, 10 type, 1A json, 22 bytes, 28 seq, 30 mode ----
const val MODE_REQUEST = 1
const val MODE_REPLY = 2
const val LAUNCHER_GENERAL_STATUS = 1
const val LAUNCHER_BRIGHTNESS = 2
const val OTA_VERSION = 1
const val GENERAL_STATUS_REQUEST = """{"cmd":"request_general_status","payload":{"data":"","mode":0,"value":0}}"""
class Envelope(
@JvmField val type: Int,
@JvmField val json: String,
@JvmField val binary: ByteArray? = null,
@JvmField val sequence: Int? = null,
@JvmField val mode: Int? = null,
)
private fun varint(out: MutableList<Byte>, value: Long) {
var v = value
while (v and 0x7fL.inv() != 0L) { out.add(((v and 0x7f) or 0x80).toByte()); v = v ushr 7 }
out.add(v.toByte())
}
@JvmStatic
fun encodeEnvelope(e: Envelope): ByteArray {
val out = ArrayList<Byte>()
out.add(0x08); varint(out, 1)
out.add(0x10); varint(out, e.type.toLong())
val json = e.json.encodeToByteArray()
out.add(0x1a); varint(out, json.size.toLong()); json.forEach { out.add(it) }
e.binary?.let { b -> out.add(0x22); varint(out, b.size.toLong()); b.forEach { out.add(it) } }
e.sequence?.let { out.add(0x28); varint(out, it.toLong()) }
e.mode?.let { out.add(0x30); varint(out, it.toLong()) }
return out.toByteArray()
}
@JvmStatic
fun decodeEnvelope(bytes: ByteArray): Envelope? {
var pos = 0
fun readVarint(): Long? {
var shift = 0
var result = 0L
while (pos < bytes.size && shift <= 63) {
val b = bytes[pos++].toInt() and 255
result = result or ((b and 0x7f).toLong() shl shift)
if (b and 0x80 == 0) return result
shift += 7
}
return null
}
var type: Int? = null
var json = ""
var binary: ByteArray? = null
var sequence: Int? = null
var mode: Int? = null
while (pos < bytes.size) {
val key = readVarint() ?: return null
when ((key and 7).toInt()) {
0 -> {
val v = readVarint() ?: return null
when ((key ushr 3).toInt()) { 2 -> type = v.toInt(); 5 -> sequence = v.toInt(); 6 -> mode = v.toInt() }
}
2 -> {
val len = readVarint() ?: return null
if (len < 0 || len > bytes.size - pos) return null
val v = bytes.copyOfRange(pos, pos + len.toInt())
pos += len.toInt()
when ((key ushr 3).toInt()) { 3 -> json = v.decodeToString(); 4 -> binary = v }
}
1 -> pos += 8
5 -> pos += 4
else -> return null
}
}
return Envelope(type ?: return null, json, binary, sequence, mode)
}
/**
* Set the launcher's brightness (1..8). The stock handler also turns the screen on
* (BrightnessMonitor::setBrightness -> turnOnScreenForSetting), which is how the phone
* wakes the iO's display and keeps the stock auto-off from blanking a static page.
*/
@JvmStatic
fun launcherBrightness(level: Int): String =
"""{"cmd":"brightness_change","payload":{"value":${level.coerceIn(1, 8)},"mode":0,"data":""}}"""
/** Faceclaw's 0..100 brightness target on the launcher's 1..8 scale. */
@JvmStatic fun brightnessLevel(target: Int): Int = maxOf(1, (target.coerceIn(0, 100) * 8 + 50) / 100)
/** `screen_status` push value (1 on, 0 off), or -1 for anything else. */
@JvmStatic
fun screenStatusFromLauncherJson(json: String): Int {
val root = try { Json.parse(json).asObject() } catch (_: Exception) { null } ?: return -1
if (root["cmd"].asString() != "screen_status") return -1
return root["payload"].asObject()?.get("value").asInt() ?: -1
}
/** `generalStatus.battery` from a launcher reply or push, or -1. */
@JvmStatic
fun batteryFromLauncherJson(json: String): Int {
val root = try { Json.parse(json).asObject() } catch (_: Exception) { null } ?: return -1
val status = root["generalStatus"].asObject() ?: root["payload"].asObject()?.get("generalStatus").asObject()
status?.get("battery").asInt()?.let { return it }
// pushes: {"cmd":"battery_change","payload":{"value":N,...}}
if (root["cmd"].asString() == "battery_change") return root["payload"].asObject()?.get("value").asInt() ?: -1
return -1
}
// ---- Custom-firmware link (business 0xF0) -----------------------------------------------------
const val OPT_LENS = 0x01
const val OPT_CONTROL = 0x10
const val OPT_END = 0x40
const val OPT_RESET = 0x80
const val CTRL_QUERY = 1
const val CTRL_PAGE_OPEN = 2
const val CTRL_PAGE_CLOSE = 3
const val CTRL_KEEPALIVE = 4
/** Records up to this many bytes per packet (IDENT reports the firmware's maxChunk). */
const val DEFAULT_MAX_CHUNK = 240
/** The page closes this long after the last PAGE_OPEN/KEEPALIVE. */
const val PAGE_LEASE_MS = 120_000L
@JvmStatic
fun controlPacket(ctrl: Int, arg: Int? = null): ByteArray =
if (arg == null) byteArrayOf(OPT_CONTROL.toByte(), 0, ctrl.toByte())
else byteArrayOf(OPT_CONTROL.toByte(), 0, ctrl.toByte(), arg.toByte())
/**
* One record (from [CfwTransport.encodeRecord]) as business-0xF0 payloads
* `[opt][stream][chunk]`. `stream` is echoed in the ACKs, so it plays the G2 stream id's role.
*/
@JvmStatic
fun cfwPackets(record: ByteArray, streamId: Int, maxChunk: Int = DEFAULT_MAX_CHUNK): List<ByteArray> {
require(streamId in 0..255 && maxChunk > 0)
val out = ArrayList<ByteArray>()
var offset = 0
do {
val end = minOf(offset + maxChunk, record.size)
var opt = OPT_LENS
if (offset == 0) opt = opt or OPT_RESET
if (end >= record.size) opt = opt or OPT_END
val p = ByteArray(2 + end - offset)
p[0] = opt.toByte()
p[1] = streamId.toByte()
record.copyInto(p, 2, offset, end)
out.add(p)
offset = end
} while (offset < record.size)
return out
}
const val KIND_ACK = 1
const val KIND_NACK = 3
const val KIND_REPLY = 5
const val KIND_GESTURE = 7
const val KIND_IDENT = 0x11
const val KIND_PAGE = 0x13
const val KIND_DIAG = 0x15
/** `[01|03][stream][ordinal u16][lens][size u16][crc u16]`: the G2 ACK body, one per lens. */
@JvmStatic
fun parseCfwAck(payload: ByteArray): CfwTransport.Ack? {
if (payload.size != 9) return null
val kind = payload[0].toInt() and 255
val lens = payload[4].toInt() and 255
if ((kind != KIND_ACK && kind != KIND_NACK) || (lens != 1 && lens != 2)) return null
fun u16(o: Int) = (payload[o].toInt() and 255) or ((payload[o + 1].toInt() and 255) shl 8)
return CfwTransport.Ack(kind == KIND_NACK, payload[1].toInt() and 255, u16(2), lens, u16(5), u16(7))
}
const val IDENT_FLAG_ZLIB = 0x01
const val IDENT_FLAG_STEREO = 0x08
const val IDENT_FLAG_FACECLAW = 0x80
class Ident(
@JvmField val width: Int,
@JvmField val height: Int,
@JvmField val maxChunk: Int,
@JvmField val revision: Int,
@JvmField val flags: Int,
@JvmField val name: String,
/** "Faceclaw/<n>" -> n when the firmware runs the Faceclaw display lists, else -1. */
@JvmField val faceclawRevision: Int,
) {
val acceptsCompressed: Boolean get() = flags and IDENT_FLAG_ZLIB != 0
val faceclaw: Boolean get() = flags and IDENT_FLAG_FACECLAW != 0 && faceclawRevision > 0
}
/** `[11][ver][w u16][h u16][maxChunk u16][storeKiB u16][rev u16][flags]name\0[lineHeight]["Faceclaw/n"\0]`. */
@JvmStatic
fun parseIdent(payload: ByteArray): Ident? {
if (payload.size < 13 || payload[0].toInt() != KIND_IDENT) return null
fun u16(o: Int) = (payload[o].toInt() and 255) or ((payload[o + 1].toInt() and 255) shl 8)
var end = 13
while (end < payload.size && payload[end].toInt() != 0) end++
val name = payload.copyOfRange(13, end).decodeToString()
var faceclaw = -1
val extra = end + 2 // NUL, line height
if (extra < payload.size) {
var e = extra
while (e < payload.size && payload[e].toInt() != 0) e++
val text = payload.copyOfRange(extra, e).decodeToString()
if (text.startsWith("Faceclaw/")) faceclaw = text.removePrefix("Faceclaw/").toIntOrNull() ?: -1
}
return Ident(u16(2), u16(4), u16(6), u16(10), payload[12].toInt() and 255, name, faceclaw)
}
/** PAGE `[13][state][reason]`: state 1 open. */
@JvmStatic fun parsePageState(payload: ByteArray): Int = if (payload.size >= 2 && payload[0].toInt() == KIND_PAGE) payload[1].toInt() and 255 else -1
class Gesture(@JvmField val eventType: Int, @JvmField val source: Int, @JvmField val tick: Long)
/**
* GESTURE `[07][eventType][source][tick u32]`. Event types use the G2's OsEventTypeList numbering:
* 0 single tap, 1 swipe up, 2 swipe down, 3 double tap, 11 tap-then-hold, 12 head up, 15 head down.
*/
@JvmStatic
fun parseGesture(payload: ByteArray): Gesture? {
if (payload.size < 7 || payload[0].toInt() != KIND_GESTURE) return null
val tick = (payload[3].toLong() and 255) or ((payload[4].toLong() and 255) shl 8) or
((payload[5].toLong() and 255) shl 16) or ((payload[6].toLong() and 255) shl 24)
return Gesture(payload[1].toInt() and 255, payload[2].toInt() and 255, tick)
}
}