@mentra/bluetooth-sdk 3.2.1-dev.314 → 3.2.1

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/NimoMicReconnectTest.kt

@@ -0,0 +1,93 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.bluetooth.BluetoothGattCharacteristic
+import androidx.test.core.app.ApplicationProvider
+import com.mentra.bluetoothsdk.Bridge
+import com.mentra.bluetoothsdk.DeviceManager
+import com.mentra.bluetoothsdk.DeviceStore
+import org.junit.Assert.*
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.LooperMode
+import java.util.UUID
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@LooperMode(LooperMode.Mode.PAUSED)
+class NimoMicReconnectTest {
+    private val requests = listOf("should_send_lc3", "should_send_pcm", "should_send_transcript", "local_stt_fallback_active")
+
+    @Test fun sameAdapterReconnectRestartsTheStoppedAudioClientForRetainedConsumers() {
+        for (request in requests) withNimo { manager, device ->
+            DeviceStore.apply("bluetooth", request, true)
+            assertTrue(audioStarted(device))
+            repeat(3) {
+                resetLink(device)
+                assertFalse(audioStarted(device))
+                assertEquals(true, DeviceStore.get("bluetooth", request))
+                // This is the same adapter, not the replacement fake used by the manager tests.
+                DeviceStore.apply("glasses", "fullyBooted", true)
+                assertSame(device, manager.sgc)
+                assertTrue("Readiness must restart Nimo decoding without waiting for the watchdog", audioStarted(device))
+            }
+        }
+    }
+
+    @Test fun consumerStoppingDuringLinkLossDoesNotRestartAudio() = withNimo { _, device ->
+        DeviceStore.apply("bluetooth", "should_send_pcm", true)
+        assertTrue(audioStarted(device))
+        resetLink(device)
+        DeviceStore.apply("bluetooth", "should_send_pcm", false)
+        DeviceStore.apply("glasses", "fullyBooted", true)
+        assertFalse(audioStarted(device))
+        assertEquals(false, DeviceStore.get("glasses", "micEnabled"))
+    }
+
+    private fun resetLink(device: Nimo) {
+        // Exercise the production reset called by the GATT disconnect callback.
+        Nimo::class.java.getDeclaredMethod("resetSessionState").apply { isAccessible = true }.invoke(device)
+        DeviceStore.apply("glasses", "fullyBooted", false)
+    }
+
+    private fun audioStarted(device: Nimo): Boolean {
+        val audio = Nimo::class.java.getDeclaredField("audioClient").apply { isAccessible = true }.get(device)
+        return audio.javaClass.getDeclaredField("started").apply { isAccessible = true }.getBoolean(audio)
+    }
+
+    private fun withNimo(block: (DeviceManager, Nimo) -> Unit) {
+        Bridge.initialize(ApplicationProvider.getApplicationContext())
+        val singleton = DeviceManager::class.java.getDeclaredField("_instance").apply { isAccessible = true }
+        val previous = singleton.get(null)
+        val saved = listOf("bluetooth", "glasses").associateWith { DeviceStore.store.getCategory(it) }
+        val manager = DeviceManager(initializeHardware = false)
+        singleton.set(null, manager)
+        val device = Nimo()
+        manager.sgc = device
+        // No radio/firmware: supply the discovered mic characteristic and inspect the real
+        // audio-client lifecycle. Codec output and BLE delivery still require a device test.
+        Nimo::class.java.getDeclaredField("micChar").apply { isAccessible = true }.set(
+            device, BluetoothGattCharacteristic(UUID.randomUUID(), BluetoothGattCharacteristic.PROPERTY_WRITE, 0)
+        )
+        requests.forEach { DeviceStore.set("bluetooth", it, false) }
+        DeviceStore.set("bluetooth", "micEnabled", false)
+        DeviceStore.set("bluetooth", "micRanking", listOf("glasses"))
+        DeviceStore.set("glasses", "micEnabled", false)
+        DeviceStore.set("glasses", "fullyBooted", false)
+        try {
+            block(manager, device)
+        } finally {
+            device.cleanup()
+            manager.sgc = null
+            manager.cleanup()
+            singleton.set(null, previous)
+            saved.forEach { (category, values) ->
+                DeviceStore.store.getCategory(category).keys.filter { it !in values }.forEach {
+                    DeviceStore.store.remove(category, it)
+                }
+                values.forEach { (key, value) -> DeviceStore.set(category, key, value) }
+            }
+        }
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/NimoProtocolTest.kt

@@ -19,6 +19,17 @@ class NimoCrc16Test {
 }
 
 class NimoFrameCodecTest {
+    @Test
+    fun `system English and factory reset match firmware wire commands`() {
+        fun hex(bytes: ByteArray) = bytes.joinToString("") { "%02X".format(it.toInt() and 255) }
+        assertThat(hex(NimoFrameCodec.encodeFrame(NimoProtocol.CMD_SET_PARAMETER,
+            NimoProtocol.SET_SYSTEM_LANGUAGE, byteArrayOf(NimoProtocol.LANGUAGE_ENGLISH.toByte()))))
+            .isEqualTo("BF020500702500000324010001")
+        assertThat(hex(NimoFrameCodec.encodeFrame(NimoProtocol.CMD_CONTROL_FACTORY,
+            NimoProtocol.FACTORY_RECOVER, byteArrayOf())))
+            .isEqualTo("BF0204005358000008030000")
+    }
+
 
     @Test
     fun `transport header layout`() {

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/SelectedDeviceAddressTest.kt

@@ -0,0 +1,27 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class SelectedDeviceAddressTest {
+    @Test fun `selected pending address wins over saved address`() {
+        assertEquals("new", SelectedDeviceAddress.resolve("LIVE_2", "LIVE_2", "new", "LIVE_1", "old"))
+    }
+
+    @Test fun `a name-only selection cannot use another device's saved address`() {
+        assertNull(SelectedDeviceAddress.resolve("LIVE_2", "LIVE_2", "", "LIVE_1", "old"))
+        assertNull(SelectedDeviceAddress.resolve("Nex1-2", "Nex1-2", null, "Nex1-1", "old"))
+        assertNull(SelectedDeviceAddress.resolve("Nex1-2", null, null, "Simulated Glasses", ""))
+    }
+
+    @Test fun `saved reconnect keeps its address even with an unrelated pending selection`() {
+        assertEquals("old", SelectedDeviceAddress.resolve("LIVE_1", "LIVE_2", "new", "LIVE_1", "old"))
+        assertEquals("old", SelectedDeviceAddress.resolve("Nex1-1", null, null, "Nex1-1", "old"))
+    }
+
+    @Test fun `empty or mismatched identities never supply an address`() {
+        assertNull(SelectedDeviceAddress.resolve("", "", "new", "", "old"))
+        assertNull(SelectedDeviceAddress.resolve("LIVE_2", "LIVE_1", "new", "LIVE_1", "old"))
+    }
+}

package/android/src/testDebug/java/com/mentra/bluetoothsdk/sgcs/NimoDiagnosticsTest.kt

@@ -0,0 +1,287 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import androidx.test.core.app.ApplicationProvider
+import java.io.File
+import java.util.concurrent.TimeUnit
+import org.json.JSONObject
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.LooperMode
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@LooperMode(LooperMode.Mode.PAUSED)
+class NimoDiagnosticsTest {
+  private data class Write(val packet: ByteArray, val completed: () -> Unit)
+  private val writes = mutableListOf<Write>()
+  private var heldReady: (() -> Unit)? = null
+  private val holdReleases = mutableListOf<Boolean>()
+  private lateinit var diagnostics: NimoDiagnostics
+  private lateinit var root: File
+  private lateinit var previousDirectories: Set<String>
+
+  @Before fun setup() {
+    val context = ApplicationProvider.getApplicationContext<Context>()
+    root = File(context.filesDir, "nimo-framebuffer")
+    previousDirectories = root.listFiles()?.map { it.name }?.toSet() ?: emptySet()
+    diagnostics = NimoDiagnostics(
+      context,
+      Handler(Looper.getMainLooper()),
+      { frame, complete -> writes.add(Write(frame.copyOf(), complete)); true },
+      { ready -> heldReady = ready },
+      { resume -> holdReleases += resume },
+    )
+    diagnostics.connected(512)
+  }
+
+  @After fun dispose() { diagnostics.close() }
+
+  @Test fun probePreservesNotReadyAndAcceptsResponsesBeforeWriteCallbacks() {
+    start("probe")
+    driveToPageGate()
+    assertTrue(diagnostics.onPacket(fbpReply(writes[3].packet, ByteArray(240))))
+    val result = receipt()
+    assertTrue(result.getBoolean("probe_ok"))
+    assertFalse(result.getBoolean("ok"))
+    assertTrue(result.isNull("error"))
+    assertEquals(0, result.getJSONObject("readiness").getInt("ready"))
+    assertEquals(1, result.getJSONObject("readiness").getInt("tws"))
+    assertEquals(NimoFramebufferProtocol.EXPECTED_VERSION, result.getString("runtime_version"))
+    assertEquals(8, result.getInt("wire_events"))
+    assertEquals(8, File(captureDirectory(), "wire.jsonl").readLines().size)
+    writes.toList().forEach { it.completed() }
+    idle(4_000)
+    assertEquals(4, writes.size)
+    assertTrue(receipt().getBoolean("probe_ok"))
+    assertTrue(writes.all { it.packet[8] == 2.toByte() && (it.packet[9].toInt() and 255) in listOf(0x0B, 0x19, 0x15) })
+  }
+
+  @Test fun duplicateTriggerDoesNotStartAnotherRead() {
+    start("capture")
+    start("probe")
+    assertEquals(1, writes.size)
+    assertEquals(1, newDirectories().size)
+  }
+
+  @Test fun disconnectCancelsPendingTimeoutAndIgnoresLateWriteCompletion() {
+    start("capture")
+    writes.single().completed()
+    diagnostics.disconnected()
+    val error = receipt().getString("error")
+    assertTrue(error.contains("disconnected"))
+    diagnostics.connected(512)
+    writes.single().completed()
+    idle(4_000)
+    assertEquals(error, receipt().getString("error"))
+    assertEquals(1, writes.size)
+    assertFalse(diagnostics.onPacket(versionReply()))
+    assertFalse(receipt().getBoolean("ok"))
+  }
+
+  @Test fun timeoutStartsAtWriteCompletionAndDoesNotRetry() {
+    start("probe")
+    idle(5_000)
+    assertFalse(File(captureDirectory(), "session.json").exists())
+    writes.single().completed()
+    idle(2_900)
+    assertFalse(File(captureDirectory(), "session.json").exists())
+    idle(200)
+    assertTrue(receipt().getString("error").contains("response timeout"))
+    assertEquals(1, writes.size)
+  }
+
+  @Test fun captureRejectsCrcBeforeRequestingBulkPages() {
+    start("capture")
+    driveToPageGate()
+    val corrupted = fbpReply(writes[3].packet, ByteArray(240)).also { it[4] = (it[4].toInt() xor 1).toByte() }
+    assertTrue(diagnostics.onPacket(corrupted))
+    assertFalse(receipt().getBoolean("ok"))
+    assertFalse(receipt().getBoolean("probe_ok"))
+    assertTrue(receipt().getString("error").contains("CRC mismatch"))
+    assertEquals(4, writes.size)
+    assertEquals(0, receipt().getJSONArray("banks").length())
+  }
+
+  @Test fun totalDeadlineBoundsAWriteThatNeverCompletes() {
+    start("capture")
+    idle(600_001)
+    assertTrue(receipt().getString("error").contains("10-minute budget"))
+    writes.single().completed()
+    idle(4_000)
+    assertEquals(1, writes.size)
+  }
+
+  @Test fun heldSampleBudgetIncludesCanvasDrainAndStaleReadyCannotStartCapture() {
+    start("held-sample")
+    assertTrue(writes.isEmpty())
+    assertNotNull(heldReady)
+
+    idle(15_001)
+
+    assertEquals(listOf(true), holdReleases)
+    assertTrue(receipt().getString("error").contains("15-second budget"))
+    heldReady?.invoke()
+    assertTrue(writes.isEmpty())
+    assertEquals(listOf(true), holdReleases)
+  }
+
+  @Test fun disconnectBeforeHeldCaptureIsReadyReleasesWithoutResumingCanvas() {
+    start("held-capture")
+
+    diagnostics.disconnected()
+
+    assertEquals(listOf(false), holdReleases)
+    assertTrue(receipt().getString("error").contains("disconnected"))
+    heldReady?.invoke()
+    assertTrue(writes.isEmpty())
+    assertEquals(listOf(false), holdReleases)
+  }
+
+  @Test fun duplicateHeldCaptureDoesNotReplaceHoldOrDeadline() {
+    start("held-sample")
+    val firstReady = heldReady
+
+    start("held-capture")
+
+    assertSame(firstReady, heldReady)
+    assertEquals(1, newDirectories().size)
+    idle(15_001)
+    assertEquals(listOf(true), holdReleases)
+  }
+
+  @Test fun insufficientCapacityFailsWithoutSendingDiagnosticCommands() {
+    diagnostics.connected(20)
+    start("capture")
+    assertEquals(0, writes.size)
+    assertTrue(receipt().getString("error").contains("Write capacity"))
+  }
+
+  @Test fun samplePinsPreparedBankAndNeverClaimsStaticPairVerification() {
+    assertSample(1)
+  }
+
+  @Test fun sampleAlsoPinsPreparedBankZero() {
+    assertSample(0)
+  }
+
+  @Test fun heldSampleStartsOnlyAfterDrainAndReleasesOnSuccess() {
+    assertSample(1, "held-sample")
+    assertEquals(listOf(true), holdReleases)
+  }
+
+  private fun assertSample(bank: Int, mode: String = "sample") {
+    val state = byteArrayOf((1 - bank).toByte(), bank.toByte(), 0, 0)
+    start(mode)
+    if (mode == "held-sample") {
+      assertTrue(writes.isEmpty())
+      requireNotNull(heldReady).invoke()
+    }
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240), state))
+    // The gate always probes bank0/page0; the sample follows its prepared selector.
+    repeat(315) { page ->
+      val request = writes.last().packet
+      assertEquals(bank, request[21].toInt())
+      assertEquals(page, (request[22].toInt() and 255) or ((request[23].toInt() and 255) shl 8))
+      diagnostics.onPacket(fbpReply(request, ByteArray(240) { page.toByte() }, state))
+    }
+    val result = receipt()
+    assertTrue(result.getBoolean("sample_ok"))
+    assertFalse(result.getBoolean("ok"))
+    assertFalse(result.getBoolean("atomic"))
+    assertFalse(result.getBoolean("optical"))
+    assertEquals("non_atomic_single_pass", result.getString("evidence_kind"))
+    assertEquals(0, result.getInt("static_pairs_verified"))
+    assertEquals(1, result.getJSONArray("banks").length())
+    assertEquals(319, writes.size)
+    assertEquals(638, result.getInt("wire_events"))
+    assertFalse(result.getBoolean("pixel_stability_verified"))
+    assertEquals(mode, result.getString("mode"))
+    assertEquals(75_600, File(captureDirectory(), "bank$bank-pass1.bin").length().toInt())
+  }
+
+  @Test fun sampleRejectsSelectorChangeBetweenGateAndFirstPageWithoutRetrying() {
+    start("sample")
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240)))
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240), byteArrayOf(1, 0, 0, 0)))
+    val result = receipt()
+    assertFalse(result.getBoolean("sample_ok"))
+    assertFalse(result.getBoolean("ok"))
+    assertTrue(result.getString("error").contains("Sample metadata differs from page gate"))
+    assertEquals(5, writes.size)
+    assertEquals(0, result.getJSONArray("banks").length())
+  }
+
+  @Test fun sampleTimeoutCannotProduceSuccessOrStartASecondPass() {
+    start("sample")
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240)))
+    writes.last().completed()
+    idle(3_001)
+    assertFalse(receipt().getBoolean("sample_ok"))
+    assertFalse(receipt().getBoolean("ok"))
+    assertEquals(5, writes.size)
+  }
+
+  @Test fun fullCaptureStillRequiresFourCompleteReadsAndTwoStaticPairs() {
+    start("capture")
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240)))
+    repeat(4) { pass ->
+      repeat(315) { page ->
+        val request = writes.last().packet
+        assertEquals(pass / 2, request[21].toInt())
+        diagnostics.onPacket(fbpReply(request, ByteArray(240) { page.toByte() }))
+      }
+      if (pass < 3) assertFalse(File(captureDirectory(), "session.json").exists())
+    }
+    assertTrue(receipt().getBoolean("ok"))
+    assertEquals(2, receipt().getInt("static_pairs_verified"))
+    assertEquals(4, receipt().getJSONArray("banks").length())
+    assertEquals(1264, writes.size)
+  }
+
+  private fun driveToPageGate() {
+    assertEquals(1, writes.size)
+    assertFalse(diagnostics.onPacket(versionReply()))
+    assertEquals(2, writes.size)
+    assertFalse(diagnostics.onPacket(frame(0x19, byteArrayOf(0, 0, 1, 0))))
+    assertEquals(3, writes.size)
+    assertTrue(diagnostics.onPacket(fbpReply(writes[2].packet, "537cf1p1".toByteArray())))
+    assertEquals(4, writes.size)
+  }
+
+  // Exercise the production coordinator without pretending Robolectric proves Android's
+  // signature-permission enforcement for the ADB receiver. That boundary needs a device test.
+  private fun start(mode: String) {
+    NimoDiagnostics::class.java.getDeclaredMethod("start", String::class.java).apply { isAccessible = true }
+      .invoke(diagnostics, mode)
+  }
+  private fun idle(milliseconds: Long) = Shadows.shadowOf(Looper.getMainLooper()).idleFor(milliseconds, TimeUnit.MILLISECONDS)
+  private fun newDirectories() = root.listFiles()?.filter { it.name !in previousDirectories } ?: emptyList()
+  private fun captureDirectory() = newDirectories().single()
+  private fun receipt() = JSONObject(File(captureDirectory(), "session.json").readText())
+  private fun versionReply() = frame(0x0B, byteArrayOf(0) + NimoFramebufferProtocol.EXPECTED_VERSION.toByteArray())
+
+  private fun fbpReply(request: ByteArray, data: ByteArray, state: ByteArray = byteArrayOf(0, 1, 0, 0)): ByteArray {
+    val payload = byteArrayOf(0) + "FBP1".toByteArray() + request.copyOfRange(16, 24) + state + state +
+      byteArrayOf(data.size.toByte(), (data.size shr 8).toByte()) + data
+    return frame(0x15, payload)
+  }
+  private fun frame(key: Int, payload: ByteArray): ByteArray {
+    val body = byteArrayOf(2, key.toByte(), payload.size.toByte(), (payload.size shr 8).toByte()) + payload
+    val crc = NimoCanvasCodec.crc16(body)
+    return byteArrayOf(0xBF.toByte(), 0, body.size.toByte(), (body.size shr 8).toByte(),
+      crc.toByte(), (crc shr 8).toByte(), 0, 0) + body
+  }
+}

package/android/src/testDebug/java/com/mentra/bluetoothsdk/sgcs/NimoFramebufferProtocolTest.kt

@@ -0,0 +1,127 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class NimoFramebufferProtocolTest {
+  @Test fun hexPreservesEveryByteAndEmptyEvidence() {
+    val bytes = ByteArray(256) { it.toByte() }
+    assertEquals(bytes.joinToString("") { "%02x".format(it.toInt() and 255) }, NimoFramebufferProtocol.hex(bytes))
+    assertEquals("", NimoFramebufferProtocol.hex(byteArrayOf()))
+  }
+  private val pingRequest = NimoFramebufferProtocol.Request(0x01020304L, 0, 0, 0)
+  // Fixed vectors produced independently by the existing Python FBP1 codec.
+  private val ping = hex("bf0023008234000002151f0000464250310403020100000000000100000001000008003533376366317031")
+  private val page = hex("bf000b0175e500000215070100464250310403020101013a010001000000010000f000") +
+    ByteArray(240) { it.toByte() }
+
+  @Test fun requestAndReplyMatchIndependentGoldenVectors() {
+    assertArrayEquals(hex("bf001000227a000002150c00464250310403020100000000"),
+      NimoFramebufferProtocol.requestFrame(pingRequest))
+    val reply = NimoFramebufferProtocol.reply(ping, pingRequest)
+    assertArrayEquals("537cf1p1".toByteArray(), reply.data)
+    assertEquals(NimoFramebufferProtocol.State(0, 1, 0, 0), reply.before)
+    val expectedPage = NimoFramebufferProtocol.Request(0x01020304L, 1, 1, 314)
+    assertArrayEquals(ByteArray(240) { it.toByte() }, NimoFramebufferProtocol.reply(page, expectedPage).data)
+  }
+
+  @Test fun rejectsCrcLengthsDirectionIndexAndCommand() {
+    for (offset in listOf(0, 1, 2, 4, 6, 8, 9, 10)) {
+      val invalid = ping.copyOf().also { it[offset] = (it[offset].toInt() xor 1).toByte() }
+      rejects { NimoFramebufferProtocol.reply(invalid, pingRequest) }
+    }
+    rejects { NimoFramebufferProtocol.reply(ping + 0, pingRequest) }
+    rejects { NimoFramebufferProtocol.reply(ping.copyOf(ping.size - 1), pingRequest) }
+  }
+
+  @Test fun rejectsWrongTagMagicNonceOperationBankAndPage() {
+    for (offset in listOf(13, 17, 21, 22, 23, 33, 35)) {
+      val invalid = changeAndRecrc(ping, offset, ping[offset].toInt() xor 1)
+      rejects { NimoFramebufferProtocol.reply(invalid, pingRequest) }
+    }
+    rejects { NimoFramebufferProtocol.reply(ping, pingRequest.copy(nonce = 9)) }
+    rejects { NimoFramebufferProtocol.reply(ping, pingRequest.copy(op = 1)) }
+  }
+
+  @Test fun rejectsStatusErrorsEvenWithValidCorrelation() {
+    for (status in listOf(1, 6, 7, 255)) {
+      val payload = ping.copyOfRange(12, 35).also { it[0] = status.toByte(); it[21] = 0; it[22] = 0 }
+      rejects { NimoFramebufferProtocol.reply(frame(0x15, payload), pingRequest) }
+    }
+    rejects { NimoFramebufferProtocol.reply(changeAndRecrc(ping, 12, 6), pingRequest) }
+  }
+
+  @Test fun rejectsMetadataChangedWithinAndAcrossPagesAndOutOfOrder() {
+    val request = NimoFramebufferProtocol.Request(0x01020304L, 1, 1, 0)
+    val first = NimoFramebufferProtocol.reply(pageAt(0), request)
+    val read = NimoFramebufferProtocol.BankRead(request.nonce, request.bank)
+    read.add(first)
+    rejects { read.add(first) }
+    rejects { NimoFramebufferProtocol.BankRead(request.nonce, request.bank).add(first.copy(page = 1)) }
+    rejects { NimoFramebufferProtocol.reply(changeAndRecrc(pageAt(0), 29, 1), request) }
+    val changed = first.copy(page = 1, before = first.before.copy(dirty = 1), after = first.after.copy(dirty = 1))
+    val changedRead = NimoFramebufferProtocol.BankRead(request.nonce, request.bank)
+    changedRead.add(first)
+    rejects { changedRead.add(changed) }
+  }
+
+  @Test fun bankRequiresEveryPageAndIndependentEqualSecondPass() {
+    val first = completeBank(10)
+    val second = completeBank(11)
+    NimoFramebufferProtocol.verifyPair(first, second)
+    assertEquals(75600, first.bytes().size)
+    rejects { NimoFramebufferProtocol.verifyPair(first, first) }
+    rejects { NimoFramebufferProtocol.verifyPair(first, completeBank(12, changedLastPixel = true)) }
+    rejects { NimoFramebufferProtocol.BankRead(20, 1).bytes() }
+  }
+
+  @Test fun requestLimitsPreventArbitraryCommandsOrAddresses() {
+    for (request in listOf(pingRequest.copy(nonce = -1), pingRequest.copy(nonce = 0x100000000L),
+      pingRequest.copy(op = 2), pingRequest.copy(bank = 2), pingRequest.copy(page = 1),
+      pingRequest.copy(op = 1, page = 315))) {
+      rejects { NimoFramebufferProtocol.requestFrame(request) }
+    }
+    rejects { NimoFramebufferProtocol.queryFrame(0x0A) }
+  }
+
+  @Test fun basicResponsesRequireExactVersionAndReadinessShape() {
+    val version = byteArrayOf(0) + NimoFramebufferProtocol.EXPECTED_VERSION.toByteArray()
+    assertEquals(NimoFramebufferProtocol.EXPECTED_VERSION,
+      NimoFramebufferProtocol.version(frame(0x0B, version)))
+    rejects { NimoFramebufferProtocol.version(frame(0x0B, version + 0)) }
+    rejects { NimoFramebufferProtocol.version(frame(0x0B, version.copyOf().also { it[0] = 7 })) }
+    assertEquals(listOf(0, 0, 1, 0), NimoFramebufferProtocol.readiness(frame(0x19, byteArrayOf(0, 0, 1, 0))))
+    rejects { NimoFramebufferProtocol.readiness(frame(0x19, byteArrayOf(0, 1, 1))) }
+  }
+
+  private fun completeBank(nonce: Long, changedLastPixel: Boolean = false): NimoFramebufferProtocol.BankRead {
+    val read = NimoFramebufferProtocol.BankRead(nonce, 1)
+    repeat(315) { index ->
+      val original = NimoFramebufferProtocol.reply(pageAt(index),
+        NimoFramebufferProtocol.Request(0x01020304L, 1, 1, index))
+      val data = original.data.copyOf()
+      if (changedLastPixel && index == 314) data[239] = 0
+      read.add(original.copy(nonce = nonce, data = data))
+    }
+    return read
+  }
+
+  private fun pageAt(index: Int): ByteArray {
+    val result = page.copyOf()
+    result[23] = index.toByte(); result[24] = (index shr 8).toByte()
+    return recrc(result)
+  }
+  private fun changeAndRecrc(value: ByteArray, index: Int, byte: Int) =
+    recrc(value.copyOf().also { it[index] = byte.toByte() })
+  private fun recrc(value: ByteArray): ByteArray {
+    val crc = NimoCanvasCodec.crc16(value.copyOfRange(8, value.size))
+    value[4] = crc.toByte(); value[5] = (crc shr 8).toByte()
+    return value
+  }
+  private fun frame(key: Int, payload: ByteArray): ByteArray {
+    val body = byteArrayOf(2, key.toByte(), payload.size.toByte(), (payload.size shr 8).toByte()) + payload
+    return recrc(byteArrayOf(0xBF.toByte(), 0, body.size.toByte(), (body.size shr 8).toByte(), 0, 0, 0, 0) + body)
+  }
+  private fun rejects(block: () -> Unit) { assertThrows(IllegalArgumentException::class.java, block) }
+  private fun hex(value: String) = value.chunked(2).map { it.toInt(16).toByte() }.toByteArray()
+}