G1 support: Flashing within the Android app

This commit is contained in:
James Babcock committed 2026-11-06 12:55:24 -08:00
1 parent 345ba36c33
commit 38c52ebc31
37 files changed
+2819 -32

No files matched your search

@@ -0,0 +1,551 @@
package com.faceclaw.app
import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertFalse
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
private const val ARM = "F4:27:E9:CA:E8:3F"
private fun hex(text: String): ByteArray = ByteArray(text.length / 2) { text.substring(it * 2, it * 2 + 2).toInt(16).toByte() }
/** An image the way MCUboot lays one out: header, payload, then a TLV area with its SHA-256. */
private fun testImage(version: Triple<Int, Int, Int> = Triple(0, 5, 64), payloadSize: Int = 5000): ByteArray {
val headerSize = 512
val hash = ByteArray(32) { (it * 3 + version.third).toByte() }
val image = ByteArray(headerSize + payloadSize + 4 + 4 + 32)
fun put16(at: Int, value: Int) {
image[at] = value.toByte()
image[at + 1] = (value ushr 8).toByte()
}
fun put32(at: Int, value: Int) {
put16(at, value and 0xffff)
put16(at + 2, value ushr 16)
}
put32(0, 0x96f3b83d.toInt())
put16(8, headerSize)
put32(12, payloadSize)
image[20] = version.first.toByte()
image[21] = version.second.toByte()
put16(22, version.third)
for (i in 0 until payloadSize) image[headerSize + i] = (i * 7).toByte()
val tlv = headerSize + payloadSize
put16(tlv, 0x6907)
put16(tlv + 2, 4 + 4 + 32)
put16(tlv + 4, 0x10)
put16(tlv + 6, 32)
hash.copyInto(image, tlv + 8)
return image
}
/**
* One arm behind the StockLink port: MCUmgr's image and OS groups as flash.py meets them on real arms, and g1v0's HELLO
* and PROPS. Requests are answered synchronously, from the write.
*/
private class FakeArm(private val image: ByteArray, var stock: Boolean = false) : StockLink {
var inbound: StockLinkListener? = null
var connected = false
var bond = BondState.BONDED
var bondRequests = 0
var bondResult = BondState.BONDED
val subscribed = ArrayList<String>()
val heartbeats = ArrayList<ByteArray>()
val calls = ArrayList<String>()
var runningVersion = "0.5.63"
var safeMode = false
var battery = 80
var slot1Hash: ByteArray? = null
var uploaded = ByteArray(0)
var uploadOffset = 0
var uploadRefusal = 0
/** After the upload the list shows this instead of the image's hash. */
var corruptAfterUpload = false
var confirmRefusal = 0
var dropAtOffset = -1
var silentRequests = 0
/** The chunk at this offset gets no answer, once. */
var silentAtOffset = -1
var onChunk: (() -> Unit)? = null
var connects = 0
val wantHash = G1Smp.imageHash(image)
override fun setListener(listener: StockLinkListener?) { inbound = listener }
override fun connect(address: String, timeoutMs: Int): Boolean {
connects++
connected = true
return true
}
override fun prepareLink(address: String, desiredMtu: Int, timeoutMs: Int) {}
override fun discoverServices(address: String, timeoutMs: Int): Boolean = connected
override fun enableNotifications(address: String, characteristicUuid: String, timeoutMs: Int): Boolean {
if (!connected) return false
if (stock && characteristicUuid == G1Ble.EVT_CHAR_UUID) return false
if (!stock && characteristicUuid == G1Smp.NUS_TX_UUID) return false
subscribed.add(characteristicUuid)
return true
}
override fun isConnected(address: String): Boolean = connected
override fun bondState(address: String): BondState = bond
override fun requestBond(address: String) {
bondRequests++
bond = bondResult
}
override fun negotiatedMtu(address: String): Int = 100
override fun disconnect(address: String) { connected = false }
override fun close() { connected = false }
fun drop() {
connected = false
inbound?.onConnectionStateChange(ARM, false)
}
override fun writeFrames(address: String, characteristicUuid: String, frames: List<ByteArray>, mode: GattWriteMode, timeoutMs: Int): Boolean {
if (!connected) throw IllegalStateException("Not connected")
when (characteristicUuid) {
G1Smp.NUS_RX_UUID -> heartbeats.add(frames.single())
G1Ble.PAIR_CHAR_UUID -> return bond == BondState.BONDED
G1Ble.CTRL_CHAR_UUID -> control(frames.single())
G1Smp.SMP_CHAR_UUID -> {
for (frame in frames) assertTrue(frame.size <= 97, "a write longer than the MTU allows")
smp(frames.reduce { a, b -> a + b })
}
else -> throw IllegalStateException("write to $characteristicUuid")
}
return true
}
private fun control(request: ByteArray) {
val op = request[0].toInt() and 0xff
val tag = request[1]
val body = when (op) {
G1Protocol.OP_HELLO -> {
val parts = runningVersion.split(".").map { it.toInt().toByte() }
val flags = (if (safeMode) 1 else 0) or 2 or 64
byteArrayOf(5, parts[0], parts[1], parts[2], 1, flags.toByte(), 0)
}
G1Protocol.OP_PROPS -> byteArrayOf(battery.toByte(), 0, 0, 0)
else -> ByteArray(0)
}
val event = ByteArray(9) + byteArrayOf(tag, 0) + body
event[0] = (0x80 or op).toByte()
inbound?.onNotification(ARM, G1Ble.EVT_CHAR_UUID, event)
}
private fun smp(frame: ByteArray) {
val op = frame[0].toInt()
val group = frame[5].toInt()
val seq = frame[6].toInt() and 0xff
val cmd = frame[7].toInt()
val body = G1Cbor.decode(frame, 8) as Map<*, *>
if (silentRequests > 0) {
silentRequests--
return
}
when {
group == 1 && cmd == 1 -> {
calls.add("upload")
val off = (body["off"] as Long).toInt()
onChunk?.invoke()
if (off == silentAtOffset) {
silentAtOffset = -1
return
}
if (uploadRefusal != 0) return reply(op, group, seq, cmd, mapOf("rc" to uploadRefusal))
if (off == uploadOffset) {
val data = body["data"] as ByteArray
if (off == 0) {
assertEquals(image.size.toLong(), body["len"])
assertContentEquals(sha256(image), body["sha"] as ByteArray)
assertEquals(0L, body["image"])
uploaded = ByteArray(0)
}
uploaded += data
uploadOffset += data.size
if (uploadOffset == image.size) slot1Hash = if (corruptAfterUpload) ByteArray(32) else G1Smp.imageHash(uploaded)
}
if (uploadOffset >= dropAtOffset && dropAtOffset >= 0) {
dropAtOffset = -1
drop()
return
}
reply(op, group, seq, cmd, mapOf("rc" to 0, "off" to uploadOffset))
}
group == 1 && cmd == 0 && op == G1Smp.OP_READ -> {
calls.add("list")
val images = ArrayList<Map<String, Any?>>()
images.add(mapOf("image" to 0, "slot" to 0, "version" to runningVersion, "hash" to ByteArray(32), "active" to true, "confirmed" to true, "bootable" to true))
slot1Hash?.let { images.add(mapOf("image" to 0, "slot" to 1, "version" to "0.5.64", "hash" to it, "bootable" to true)) }
reply(op, group, seq, cmd, mapOf("images" to images))
}
group == 1 && cmd == 0 -> {
calls.add("confirm")
assertEquals(true, body["confirm"])
assertContentEquals(wantHash, body["hash"] as ByteArray)
reply(op, group, seq, cmd, mapOf("rc" to confirmRefusal))
}
group == 0 && cmd == 5 -> {
calls.add("reset")
reply(op, group, seq, cmd, emptyMap())
drop()
}
else -> throw IllegalStateException("SMP $group/$cmd")
}
}
/** The reply comes in pieces, as notifications do. */
private fun reply(op: Int, group: Int, seq: Int, cmd: Int, body: Map<String, Any?>) {
val frame = G1Smp.frame(op or 1, group, seq, cmd, body)
for (piece in G1Smp.split(frame, 23)) inbound?.onNotification(ARM, G1Smp.SMP_CHAR_UUID, piece)
}
}
private class Recorder : FaceclawFirmwareFlasherListener {
val states = ArrayList<String>()
val logs = ArrayList<String>()
var progress = 0L
var total = 0L
var success: Boolean? = null
var detail = ""
override fun onLog(line: String?) { logs.add(line ?: "") }
override fun onProgress(lens: String?, componentIndex: Int, componentCount: Int, blockIndex: Int, blockCount: Int, bytesSent: Long, bytesTotal: Long) {
progress = bytesSent
total = bytesTotal
}
override fun onState(state: String?, detail: String?) { states.add(state ?: "") }
override fun onComplete(success: Boolean, detail: String?) {
this.success = success
this.detail = detail ?: ""
}
}
private val FAST = G1FlashTimings(
connectTimeoutMs = 50, servicesTimeoutMs = 50, descriptorTimeoutMs = 50, writeTimeoutMs = 50, pairingMs = 200, retryDelayMs = 1,
controlReplyMs = 20, controlTries = 2, uploadReplyMs = 150, smpReplyMs = 150, resetReplyMs = 50, heartbeatMs = 30, pollMs = 5, uploadRetries = 5,
)
class G1SmpTest {
private val sha = ByteArray(32) { it.toByte() }
/** The expected bytes come from scouter_kit's tools/g1host.py, whose requests were proven on real arms. */
@Test
fun requestsMatchTheProvenPythonTool() {
val image = ByteArray(574408)
image[0] = 1
image[1] = 2
image[2] = 3
val first = G1Smp.uploadRequest(image, 0, sha).toMutableMap()
first["data"] = byteArrayOf(1, 2, 3)
assertEquals(
"0200004e00010001a665696d61676500636c656e1a0008c3c8636f666600637368615820000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f6464617461430102036775706772616465f4",
BinaryEncoding.bytesToHex(G1Smp.frame(G1Smp.OP_WRITE, G1Smp.GROUP_IMAGE, 0, G1Smp.CMD_IMAGE_UPLOAD, first)),
)
assertEquals(
"0200001100010101a2636f6666190800646461746143010203",
BinaryEncoding.bytesToHex(G1Smp.frame(G1Smp.OP_WRITE, G1Smp.GROUP_IMAGE, 1, G1Smp.CMD_IMAGE_UPLOAD, mapOf("off" to 2048, "data" to byteArrayOf(1, 2, 3)))),
)
assertEquals(
"0200003100010500a264686173685820000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f67636f6e6669726df5",
BinaryEncoding.bytesToHex(G1Smp.frame(G1Smp.OP_WRITE, G1Smp.GROUP_IMAGE, 5, G1Smp.CMD_IMAGE_STATE, G1Smp.confirmRequest(sha))),
)
assertEquals("0000000100010700a0", BinaryEncoding.bytesToHex(G1Smp.frame(G1Smp.OP_READ, G1Smp.GROUP_IMAGE, 7, G1Smp.CMD_IMAGE_STATE, emptyMap())))
assertEquals("020000010000ff05a0", BinaryEncoding.bytesToHex(G1Smp.frame(G1Smp.OP_WRITE, G1Smp.GROUP_OS, 255, G1Smp.CMD_OS_RESET, emptyMap())))
}
@Test
fun cborMatchesPythonAndRoundTrips() {
val value = mapOf("n" to -5, "big" to 70000, "huge" to 5000000000L, "t" to true, "s" to "ab")
val encoded = G1Cbor.encode(value)
assertEquals("a5616e24636269671a0001117064687567651b000000012a05f2006174f56173626162", BinaryEncoding.bytesToHex(encoded))
val decoded = G1Cbor.decode(encoded) as Map<*, *>
assertEquals(-5L, decoded["n"])
assertEquals(70000L, decoded["big"])
assertEquals(5000000000L, decoded["huge"])
assertEquals(true, decoded["t"])
assertEquals("ab", decoded["s"])
}
@Test
fun cborReadsTheIndefiniteLengthsOfAnImageList() {
// {"images": [{"slot": 1, "active": true}]}, each container of indefinite length.
val data = hex("bf66696d616765739fbf64736c6f74016661637469766" + "5f5ffffff")
val slots = (G1Cbor.decode(data) as Map<*, *>)["images"] as List<*>
val slot = slots.single() as Map<*, *>
assertEquals(1L, slot["slot"])
assertEquals(true, slot["active"])
}
@Test
fun malformedCborIsAnErrorNotAWrongValue() {
assertFailsWith<IllegalArgumentException> { G1Cbor.decode(hex("5820")) }
assertFailsWith<IllegalArgumentException> { G1Cbor.decode(hex("bf")) }
assertFailsWith<IllegalArgumentException> { G1Cbor.decode(ByteArray(0)) }
}
@Test
fun repliesAreJoinedAcrossNotifications() {
val assembler = G1Smp.Assembler()
val one = G1Smp.frame(3, 1, 7, 1, mapOf("off" to 2048, "rc" to 0))
val two = G1Smp.frame(3, 1, 8, 0, emptyMap())
val all = one + two
val replies = ArrayList<Pair<Int, Map<*, *>>>()
for (start in all.indices step 5) replies += assembler.feed(all.copyOfRange(start, minOf(start + 5, all.size)))
assertEquals(listOf(7, 8), replies.map { it.first })
assertEquals(2048, G1Smp.replyOffset(replies[0].second))
assertEquals(0, G1Smp.replyCode(replies[1].second))
}
@Test
fun anImageSaysWhatItIs() {
val image = testImage(Triple(0, 5, 300))
assertEquals("0.5.300", G1Smp.imageVersion(image))
assertContentEquals(ByteArray(32) { (it * 3 + 300).toByte() }, G1Smp.imageHash(image))
assertFailsWith<IllegalArgumentException> { G1Smp.imageVersion(ByteArray(100)) }
val cut = image.copyOf(image.size - 20)
assertFailsWith<IllegalArgumentException> { G1Smp.imageHash(cut) }
}
@Test
fun writesFitTheMtu() {
val pieces = G1Smp.split(ByteArray(1000), 247)
assertTrue(pieces.all { it.size <= 244 })
assertEquals(1000, pieces.sumOf { it.size })
}
}
class G1ArmFlashFlowTest {
private val image = testImage()
private fun flow(arm: FakeArm, listener: Recorder, mode: G1ArmFlashFlow.Mode, window: Int = 100) =
G1ArmFlashFlow(arm, ARM, "left", "image.bin", mode, window, listener, FAST, testPlatform(), { image })
private fun run(arm: FakeArm, mode: G1ArmFlashFlow.Mode, window: Int = 100): Recorder {
val listener = Recorder()
flow(arm, listener, mode, window).run()
assertNotNull(listener.success, "the flow must always finish")
return listener
}
private fun confirmIsLast(arm: FakeArm) {
assertEquals(listOf("confirm", "reset"), arm.calls.takeLast(2))
assertEquals(1, arm.calls.count { it == "confirm" })
}
@Test
fun anUpdateUploadsChecksThenConfirmsAndResets() {
val arm = FakeArm(image)
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(true, result.success, result.detail)
assertEquals("""{"flashed":true,"version":"0.5.64"}""", result.detail)
assertContentEquals(image, arm.uploaded)
assertEquals(image.size.toLong(), result.progress)
assertEquals(image.size.toLong(), result.total)
confirmIsLast(arm)
// The list before the confirm is what proves the slot holds this image.
assertEquals("list", arm.calls[arm.calls.indexOf("confirm") - 1])
assertTrue(arm.heartbeats.isEmpty(), "g1v0 has no heartbeat")
assertTrue("rebooting" in result.states)
}
@Test
fun anArmAlreadyOnThisVersionIsLeftAlone() {
val arm = FakeArm(image)
arm.runningVersion = "0.5.64"
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(true, result.success)
assertEquals("""{"flashed":false,"version":"0.5.64"}""", result.detail)
assertTrue(arm.calls.isEmpty(), "nothing goes to the update service")
}
@Test
fun anArmInSafeModeOnThisVersionIsInstalledAgain() {
val arm = FakeArm(image)
arm.runningVersion = "0.5.64"
arm.safeMode = true
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals("""{"flashed":true,"version":"0.5.64"}""", result.detail)
confirmIsLast(arm)
}
@Test
fun aSlotThatDoesNotHoldTheImageIsNeverConfirmed() {
val arm = FakeArm(image)
arm.corruptAfterUpload = true
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(false, result.success)
assertFalse("confirm" in arm.calls)
assertFalse("reset" in arm.calls)
assertTrue("Nothing was installed" in result.detail, result.detail)
}
@Test
fun aRefusedUploadIsNeverConfirmed() {
val arm = FakeArm(image)
arm.uploadRefusal = 9
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(false, result.success)
assertFalse("confirm" in arm.calls)
assertTrue("error 9" in result.detail, result.detail)
}
@Test
fun aRefusedConfirmIsNotAReset() {
val arm = FakeArm(image)
arm.confirmRefusal = 2
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(false, result.success)
assertFalse("reset" in arm.calls)
}
@Test
fun aLowBatteryStopsAnUpdateBeforeAnyUpload() {
val arm = FakeArm(image)
arm.battery = 12
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(false, result.success)
assertTrue("12%" in result.detail, result.detail)
assertTrue(arm.calls.isEmpty())
}
@Test
fun aDamagedImageFailsBeforeTheLinkIsTouched() {
val listener = Recorder()
val arm = FakeArm(image)
G1ArmFlashFlow(arm, ARM, "left", "image.bin", G1ArmFlashFlow.Mode.UPDATE, 100, listener, FAST, testPlatform(), { ByteArray(100) }).run()
assertEquals(false, listener.success)
assertEquals(0, arm.connects)
}
@Test
fun anUnreadableImageIsAClearFailure() {
val listener = Recorder()
val arm = FakeArm(image)
G1ArmFlashFlow(arm, ARM, "left", "image.bin", G1ArmFlashFlow.Mode.STOCK, 100, listener, FAST, testPlatform(), { throw IllegalStateException("gone") }).run()
assertEquals(false, listener.success)
assertTrue("could not read the firmware" in listener.detail, listener.detail)
}
@Test
fun aLostLinkResumesTheUpload() {
val arm = FakeArm(image)
arm.dropAtOffset = 2048
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(true, result.success, result.detail)
assertContentEquals(image, arm.uploaded)
assertTrue(arm.connects >= 2, "it connected again")
confirmIsLast(arm)
}
@Test
fun aChunkThatGetsNoAnswerIsSentAgain() {
val arm = FakeArm(image)
arm.silentAtOffset = 2048
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(true, result.success, result.detail)
assertContentEquals(image, arm.uploaded)
confirmIsLast(arm)
}
@Test
fun anUploadThatNeverGetsAnswersGivesUpWithoutConfirming() {
val arm = FakeArm(image)
arm.silentRequests = 1000
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(false, result.success)
assertFalse("confirm" in arm.calls)
}
@Test
fun aSlotAlreadyHoldingTheImageSkipsTheUpload() {
val arm = FakeArm(image)
arm.slot1Hash = arm.wantHash
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE)
assertEquals(true, result.success, result.detail)
assertFalse("upload" in arm.calls)
confirmIsLast(arm)
}
@Test
fun stockGetsAHeartbeatEvenWhileAChunkWaits() {
val arm = FakeArm(image, stock = true)
// A chunk can wait a long time, as the first does while the arm erases its slot: the heartbeat has to keep going.
arm.silentAtOffset = 2048
val result = run(arm, G1ArmFlashFlow.Mode.STOCK)
assertEquals(true, result.success, result.detail)
assertTrue(arm.heartbeats.size >= 3, "heartbeats: ${arm.heartbeats.size}")
assertTrue(G1Smp.NUS_TX_UUID in arm.subscribed)
assertEquals(0x25, arm.heartbeats[0][0].toInt())
assertEquals(arm.heartbeats[1][3], 1.toByte())
assertEquals(arm.heartbeats[1][5], 1.toByte())
confirmIsLast(arm)
}
@Test
fun stockIsPairedWithFirst() {
val arm = FakeArm(image, stock = true)
arm.bond = BondState.NONE
val result = run(arm, G1ArmFlashFlow.Mode.STOCK)
assertEquals(true, result.success, result.detail)
assertEquals(1, arm.bondRequests)
assertTrue("pairing" in result.states)
}
@Test
fun aRefusedBondIsRetriedThenReported() {
val arm = FakeArm(image)
arm.bond = BondState.NONE
arm.bondResult = BondState.NONE
val result = run(arm, G1ArmFlashFlow.Mode.UPDATE, window = 1)
assertEquals(false, result.success)
assertTrue(arm.calls.isEmpty())
assertTrue("Couldn't reach the left arm" in result.detail, result.detail)
}
@Test
fun aPlatformThatCannotSeeBondsReliesOnTheEncryptedWrite() {
val arm = FakeArm(image)
arm.bond = BondState.UNKNOWN
val listener = Recorder()
// The write to PAIR fails on an unknown bond in this fake, as on an arm out of the case: no encrypted link.
flow(arm, listener, G1ArmFlashFlow.Mode.PROBE, 1).run()
assertEquals(false, listener.success)
assertEquals(0, arm.bondRequests)
assertTrue("an arm pairs only in its case" in listener.detail, listener.detail)
}
@Test
fun aProbeSaysWhatAnArmRuns() {
val arm = FakeArm(image)
val result = run(arm, G1ArmFlashFlow.Mode.PROBE)
assertEquals(true, result.success, result.detail)
assertEquals("""{"firmware":"g1v0","version":"0.5.63","safeMode":false,"inCase":false,"battery":80}""", result.detail)
assertTrue(arm.calls.isEmpty())
}
@Test
fun aProbeOfEvensFirmwareNeedsNoPairing() {
val arm = FakeArm(image, stock = true)
arm.bond = BondState.NONE
val result = run(arm, G1ArmFlashFlow.Mode.PROBE)
assertEquals("""{"firmware":"stock"}""", result.detail)
assertEquals(0, arm.bondRequests)
}
@Test
fun cancellingDuringTheUploadStopsBeforeTheConfirm() {
val arm = FakeArm(image)
val listener = Recorder()
val flow = flow(arm, listener, G1ArmFlashFlow.Mode.UPDATE)
arm.onChunk = { flow.cancel() }
flow.run()
assertEquals(false, listener.success)
assertEquals("Cancelled.", listener.detail)
assertFalse("confirm" in arm.calls)
}
}
@@ -217,7 +217,7 @@ private class FakeG1Glasses(platform: ProtocolPlatform) : SessionLink {
body[0] = 5
body[1] = 0
body[2] = 5
body[3] = 62
body[3] = 63
body[4] = (if (a.left) 1 else 0).toByte()
body[5] = (2 or 64).toByte()
body[6] = (if (a.left) 0 else 4).toByte()
@@ -472,7 +472,7 @@ class G1SessionTest {
assertEquals(G1Protocol.EVENTS_MASK, s.glasses.leftArm.eventsMask)
assertEquals(G1Protocol.EVENTS_MASK, s.glasses.rightArm.eventsMask)
assertEquals(1, s.glasses.leftArm.healthOk, "the boot is confirmed healthy")
assertTrue(s.listener.firmware.single().startsWith("g1v0 0.5.62|g1v0 0.5.62|Faceclaw/"), s.listener.firmware.toString())
assertTrue(s.listener.firmware.single().startsWith("g1v0 0.5.63|g1v0 0.5.63|Faceclaw/"), s.listener.firmware.toString())
s.submit(1, 1)
assertTrue(awaitTrue(5_000) { s.displayedMatchesDesired() }, "frame never displayed:\n" + s.tail())