@glassly/bluetooth-sdk 0.1.0-dev.26

package/ios/Source/sgcs/G2Flasher.swift

@@ -0,0 +1,773 @@
+@preconcurrency import CoreBluetooth
+import CryptoKit
+import Foundation
+
+struct G2FirmwareArtifact {
+    let id: String
+    let displayName: String
+    let version: String
+    let fileName: String
+    let sha256: String
+    let size: Int
+
+    var dictionary: [String: Any] {
+        [
+            "id": id,
+            "displayName": displayName,
+            "version": version,
+            "fileName": fileName,
+            "sha256": sha256,
+            "size": size,
+        ]
+    }
+}
+
+enum G2FirmwareCatalog {
+    static let artifacts = [
+        G2FirmwareArtifact(
+            id: "stock",
+            displayName: "Stock firmware",
+            version: "2.2.6.10",
+            fileName: "g2-stock-2.2.6.10.evenota.bin",
+            sha256: "f4dfb0b49ad3de3c2daf17f8a27a157c3dc98411d6a0d3ab2cfd0918f41b9afa",
+            size: 4_301_227
+        ),
+        G2FirmwareArtifact(
+            id: "glassly-cfw",
+            displayName: "Glassly CFW",
+            version: "2.2.6.10 CFW",
+            fileName: "g2-glassly-cfw-2.2.6.10.evenota.bin",
+            sha256: "82726bbe4d1d82f06a3d345ba3e5a4a39161077e5d26dcd7af24c4677df87fd1",
+            size: 4_336_071
+        ),
+    ]
+
+    static func artifact(id: String) throws -> G2FirmwareArtifact {
+        guard let artifact = artifacts.first(where: { $0.id == id }) else {
+            throw G2FirmwareFlashError.invalidArtifact("Unknown G2 firmware target: \(id)")
+        }
+        return artifact
+    }
+
+    static func load(_ artifact: G2FirmwareArtifact) throws -> Data {
+        guard let url = resourceURL(fileName: artifact.fileName) else {
+            throw G2FirmwareFlashError.invalidArtifact(
+                "Bundled firmware \(artifact.fileName) is missing from the app."
+            )
+        }
+        let data = try Data(contentsOf: url, options: .mappedIfSafe)
+        guard data.count == artifact.size else {
+            throw G2FirmwareFlashError.invalidArtifact(
+                "\(artifact.displayName) size mismatch: expected \(artifact.size), got \(data.count)"
+            )
+        }
+        let digest = SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
+        guard digest == artifact.sha256 else {
+            throw G2FirmwareFlashError.invalidArtifact(
+                "\(artifact.displayName) SHA-256 mismatch; refusing to flash"
+            )
+        }
+        return data
+    }
+
+    private static func resourceURL(fileName: String) -> URL? {
+        let name = fileName as NSString
+        let base = name.deletingPathExtension
+        let ext = name.pathExtension
+        #if SWIFT_PACKAGE
+            return Bundle.module.url(forResource: base, withExtension: ext, subdirectory: "G2Firmware")
+                ?? Bundle.module.url(forResource: base, withExtension: ext)
+        #else
+            let candidates = Bundle.allBundles + Bundle.allFrameworks + [Bundle.main]
+            for bundle in candidates {
+                if let url = bundle.url(forResource: base, withExtension: ext, subdirectory: "G2Firmware") {
+                    return url
+                }
+                if let resourceBundleURL = bundle.url(forResource: "BluetoothSDKG2Firmware", withExtension: "bundle"),
+                   let resourceBundle = Bundle(url: resourceBundleURL),
+                   let url = resourceBundle.url(forResource: base, withExtension: ext)
+                {
+                    return url
+                }
+            }
+            return nil
+        #endif
+    }
+}
+
+enum G2FirmwareFlashError: Error, LocalizedError {
+    case busy
+    case invalidArtifact(String)
+    case notConnected
+    case channelsMissing(String)
+    case transport(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .busy:
+            "A G2 firmware flash is already in progress."
+        case let .invalidArtifact(message), let .channelsMissing(message), let .transport(message):
+            message
+        case .notConnected:
+            "Both G2 lenses must be connected before flashing."
+        }
+    }
+}
+
+/// Shared stock/CFW OTA state machine. It owns no rendering policy and can be
+/// used by the unified `G2` controller with either firmware artifact.
+final class G2Flasher: @unchecked Sendable {
+    private static let dataWriteUUID = CBUUID(string: "00002760-08C2-11E1-9073-0E8AC72E0001")
+    static let dataNotifyUUID = CBUUID(string: "00002760-08C2-11E1-9073-0E8AC72E0002")
+    private static let controlWriteUUID = CBUUID(string: "00002760-08C2-11E1-9073-0E8AC72E5401")
+    static let controlNotifyUUID = CBUUID(string: "00002760-08C2-11E1-9073-0E8AC72E5402")
+    private static let blockNakRetries = 3
+    private static let componentRetries = 3
+    private static let reconnectAttempts = 3
+    private static let reconnectDelay: TimeInterval = 10
+
+    private struct ReceivedFrame {
+        let peripheralID: UUID
+        let characteristicUUID: CBUUID
+        let bytes: [UInt8]
+    }
+
+    private struct LensSession {
+        let peripheral: CBPeripheral
+        let dataWrite: CBCharacteristic
+        let dataNotify: CBCharacteristic
+        let controlWrite: CBCharacteristic
+        let controlNotify: CBCharacteristic
+    }
+
+    private enum SessionError: LocalizedError {
+        case acknowledgementTimeout(String)
+
+        var errorDescription: String? {
+            switch self {
+            case let .acknowledgementTimeout(message): message
+            }
+        }
+    }
+
+    private let queue = DispatchQueue(label: "com.glassly.g2.flash", qos: .userInitiated)
+    private let stateLock = NSLock()
+    private let receiveSemaphore = DispatchSemaphore(value: 0)
+    private var receiveFrames: [ReceivedFrame] = []
+    private var active = false
+    private var sequence: UInt8 = 0
+
+    var isActive: Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return active
+    }
+
+    func receive(_ data: Data, from characteristicUUID: CBUUID, peripheralID: UUID) {
+        stateLock.lock()
+        guard active else {
+            stateLock.unlock()
+            return
+        }
+        receiveFrames.append(
+            ReceivedFrame(
+                peripheralID: peripheralID,
+                characteristicUUID: characteristicUUID,
+                bytes: [UInt8](data)
+            )
+        )
+        stateLock.unlock()
+        receiveSemaphore.signal()
+    }
+
+    func flash(
+        artifact: G2FirmwareArtifact,
+        left: CBPeripheral,
+        right: CBPeripheral,
+        central: CBCentralManager
+    ) async throws -> [String: Any] {
+        try begin()
+        return try await withCheckedThrowingContinuation { continuation in
+            queue.async { [weak self] in
+                guard let self else {
+                    continuation.resume(throwing: G2FirmwareFlashError.transport("G2 flasher was released"))
+                    return
+                }
+                defer { self.finish() }
+                do {
+                    let result = try self.run(
+                        artifact: artifact,
+                        left: left,
+                        right: right,
+                        central: central
+                    )
+                    continuation.resume(returning: result)
+                } catch {
+                    self.progress(error.localizedDescription, 0, done: true, ok: false)
+                    continuation.resume(throwing: error)
+                }
+            }
+        }
+    }
+
+    private func begin() throws {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        guard !active else { throw G2FirmwareFlashError.busy }
+        active = true
+        sequence = 0
+        receiveFrames.removeAll()
+        while receiveSemaphore.wait(timeout: .now()) == .success {}
+    }
+
+    private func finish() {
+        stateLock.lock()
+        active = false
+        receiveFrames.removeAll()
+        stateLock.unlock()
+    }
+
+    private func run(
+        artifact: G2FirmwareArtifact,
+        left: CBPeripheral,
+        right: CBPeripheral,
+        central: CBCentralManager
+    ) throws -> [String: Any] {
+        progress("Validating bundled \(artifact.displayName)…", 0.02)
+        let imageData = try G2FirmwareCatalog.load(artifact)
+        let image = [UInt8](imageData)
+        let validated: G2FlashProtocol.ValidatedImage
+        do {
+            validated = try Self.preflight(image)
+        } catch {
+            throw G2FirmwareFlashError.invalidArtifact("EVENOTA validation failed: \(error)")
+        }
+        let segments = validated.segments
+        let guardResult = validated.guardResult
+
+        // Re-run the implementation self-test against the bundled byte-identical
+        // stock reference before every flash, including CFW flashes.
+        let stock = try G2FirmwareCatalog.load(G2FirmwareCatalog.artifacts[0])
+        if let failure = G2FlashProtocol.selfTestGuard(
+            [UInt8](stock), expect: G2FlashProtocol.goldenStock
+        ) {
+            throw G2FirmwareFlashError.invalidArtifact("Brick-guard self-test failed: \(failure)")
+        }
+        progress(
+            String(format: "Image verified; program end 0x%08x", guardResult.progEnd),
+            0.10
+        )
+
+        let lenses = [("Left", left), ("Right", right)]
+        for (label, peripheral) in lenses {
+            try requireChannels(peripheral, label: label)
+        }
+
+        for (index, entry) in lenses.enumerated() {
+            progress("Flashing \(entry.0) lens…", 0.12 + Double(index) * 0.43)
+            resetSequence()
+            try flashLens(
+                entry.1,
+                image: image,
+                segments: segments,
+                side: entry.0,
+                lensIndex: index,
+                central: central
+            )
+        }
+        progress("Flash complete.", 1, done: true, ok: true)
+        return [
+            "ok": true,
+            "target": artifact.id,
+            "version": artifact.version,
+            "sha256": artifact.sha256,
+        ]
+    }
+
+    /// Pure preflight seam used by the production flasher and native tests.
+    /// Keeping it here makes it impossible for a future image source to enter
+    /// the BLE state machine without component CRC and MRAM validation.
+    static func preflight(_ image: [UInt8]) throws -> G2FlashProtocol.ValidatedImage {
+        try G2FlashProtocol.validateFirmware(image)
+    }
+
+    private func requireChannels(_ peripheral: CBPeripheral, label: String) throws {
+        guard findCharacteristic(peripheral, Self.dataWriteUUID) != nil,
+              findCharacteristic(peripheral, Self.dataNotifyUUID) != nil,
+              findCharacteristic(peripheral, Self.controlWriteUUID) != nil,
+              findCharacteristic(peripheral, Self.controlNotifyUUID) != nil
+        else {
+            throw G2FirmwareFlashError.channelsMissing(
+                "\(label) lens OTA/authentication characteristics are unavailable. Reconnect both lenses and try again."
+            )
+        }
+    }
+
+    private func flashLens(
+        _ peripheral: CBPeripheral,
+        image: [UInt8],
+        segments: [G2FlashProtocol.Segment],
+        side: String,
+        lensIndex: Int,
+        central: CBCentralManager
+    ) throws {
+        var session = try prepareSession(peripheral, side: side)
+        resetSequence()
+        try beginOtaSession(session, side: side)
+
+        for (index, segment) in segments.enumerated() {
+            try flashComponent(
+                segment,
+                index: index,
+                total: segments.count,
+                image: image,
+                session: &session,
+                side: side,
+                lensIndex: lensIndex,
+                central: central
+            )
+        }
+    }
+
+    private func prepareSession(_ peripheral: CBPeripheral, side: String) throws -> LensSession {
+        guard peripheral.state == .connected else {
+            throw G2FirmwareFlashError.transport("\(side) lens is not connected")
+        }
+        let session = try lensSession(peripheral, side: side)
+        onMain {
+            peripheral.setNotifyValue(true, for: session.dataNotify)
+            peripheral.setNotifyValue(true, for: session.controlNotify)
+        }
+        Thread.sleep(forTimeInterval: 2.5)
+        guard session.dataNotify.isNotifying, session.controlNotify.isNotifying else {
+            throw G2FirmwareFlashError.transport(
+                "\(side) lens did not confirm OTA and authentication notifications"
+            )
+        }
+        drainReceiveQueue()
+        try authenticate(session, side: side)
+        return session
+    }
+
+    private func lensSession(_ peripheral: CBPeripheral, side: String) throws -> LensSession {
+        guard let dataWrite = findCharacteristic(peripheral, Self.dataWriteUUID),
+              let dataNotify = findCharacteristic(peripheral, Self.dataNotifyUUID),
+              let controlWrite = findCharacteristic(peripheral, Self.controlWriteUUID),
+              let controlNotify = findCharacteristic(peripheral, Self.controlNotifyUUID)
+        else {
+            throw G2FirmwareFlashError.channelsMissing("\(side) lens OTA/authentication channels disappeared")
+        }
+        return LensSession(
+            peripheral: peripheral,
+            dataWrite: dataWrite,
+            dataNotify: dataNotify,
+            controlWrite: controlWrite,
+            controlNotify: controlNotify
+        )
+    }
+
+    private func authenticate(_ session: LensSession, side: String) throws {
+        let magic = nextSequence()
+        drainReceiveQueue()
+        try writeFrames(
+            G2FlashProtocol.authenticationFrames(magic: magic),
+            characteristic: session.controlWrite,
+            peripheral: session.peripheral
+        )
+        try waitForAuthentication(
+            peripheralID: session.peripheral.identifier,
+            magic: magic,
+            timeoutMs: 4000,
+            side: side
+        )
+    }
+
+    private func beginOtaSession(_ session: LensSession, side: String) throws {
+        let beginStatus = try sendAndWait(
+            G2FlashProtocol.ctrlFrames(0x00, seq: nextSequence()),
+            opcode: 0x00,
+            characteristic: session.dataWrite,
+            peripheral: session.peripheral
+        )
+        guard beginStatus == 0 || beginStatus == 8 || beginStatus == 9 else {
+            throw G2FirmwareFlashError.transport("\(side) lens rejected OTA begin (status \(beginStatus))")
+        }
+    }
+
+    private func flashComponent(
+        _ segment: G2FlashProtocol.Segment,
+        index: Int,
+        total: Int,
+        image: [UInt8],
+        session: inout LensSession,
+        side: String,
+        lensIndex: Int,
+        central: CBCentralManager
+    ) throws {
+        let offset = Int(segment.off) + 128
+        let payloadSize = Int(segment.ps)
+        guard offset >= 128, payloadSize > 0, offset + payloadSize <= image.count else {
+            throw G2FirmwareFlashError.invalidArtifact("\(segment.fn) payload extends past EOF")
+        }
+        let payload = Array(image[offset ..< offset + payloadSize])
+        let blockCount = (payload.count + 4095) / 4096
+
+        var lastFailure = "unknown error"
+        for attempt in 1 ... Self.componentRetries {
+            if attempt > 1 {
+                progress("\(side): retrying \(segment.fn) (\(attempt)/\(Self.componentRetries))", 0)
+                drainReceiveQueue()
+            }
+            do {
+                let fileStatus = try sendAndWait(
+                    G2FlashProtocol.ctrlFrames(0x01, segment.sub, seq: nextSequence()),
+                    opcode: 0x01,
+                    characteristic: session.dataWrite,
+                    peripheral: session.peripheral
+                )
+                guard fileStatus == 0 else {
+                    throw G2FirmwareFlashError.transport("FILE_CHECK status \(fileStatus)")
+                }
+
+                for blockIndex in 0 ..< blockCount {
+                    let start = blockIndex * 4096
+                    let block = Array(payload[start ..< min(start + 4096, payload.count)])
+                    var acknowledged = false
+                    for retry in 0 ..< Self.blockNakRetries {
+                        let sequence = nextSequence()
+                        drainReceiveQueue()
+                        try writeFrames(
+                            G2FlashProtocol.ctrlFrames(0x02, seq: sequence),
+                            characteristic: session.dataWrite,
+                            peripheral: session.peripheral
+                        )
+                        try writeFrames(
+                            G2FlashProtocol.dataFrames(block, seq: sequence),
+                            characteristic: session.dataWrite,
+                            peripheral: session.peripheral
+                        )
+                        let status: UInt8
+                        do {
+                            status = try waitForAck(
+                                opcode: 0x02,
+                                peripheralID: session.peripheral.identifier,
+                                timeoutMs: 5000
+                            )
+                        } catch {
+                            // A timeout is ambiguous: the block may have been committed and
+                            // only its ACK lost. Never resend it in place because OTA has no
+                            // block index/deduplication; restart from FILE_CHECK instead.
+                            throw SessionError.acknowledgementTimeout(
+                                "\(segment.fn) block \(blockIndex + 1)/\(blockCount): \(error.localizedDescription)"
+                            )
+                        }
+                        if status == 0 {
+                            acknowledged = true
+                            break
+                        }
+                        progress(
+                            "\(side): \(segment.fn) block \(blockIndex + 1)/\(blockCount) NAK \(status), retry \(retry + 1)/\(Self.blockNakRetries)",
+                            0
+                        )
+                    }
+                    guard acknowledged else {
+                        throw G2FirmwareFlashError.transport(
+                            "\(segment.fn) block \(blockIndex + 1)/\(blockCount) was not acknowledged"
+                        )
+                    }
+                    let componentFraction =
+                        (Double(index) + Double(blockIndex + 1) / Double(blockCount)) / Double(total)
+                    let fraction = 0.12 + Double(lensIndex) * 0.43 + componentFraction * 0.43
+                    progress("\(side): \(segment.fn) \(blockIndex + 1)/\(blockCount)", fraction)
+                }
+
+                let endStatus = try sendAndWait(
+                    G2FlashProtocol.ctrlFrames(0x03, seq: nextSequence()),
+                    opcode: 0x03,
+                    characteristic: session.dataWrite,
+                    peripheral: session.peripheral,
+                    timeoutMs: 15000
+                )
+                guard endStatus == 0 || endStatus == 8 || endStatus == 9 else {
+                    throw G2FirmwareFlashError.transport("END status \(endStatus)")
+                }
+                return
+            } catch {
+                lastFailure = error.localizedDescription
+                guard attempt < Self.componentRetries else { break }
+                if error is SessionError || session.peripheral.state != .connected {
+                    session = try recoverSession(
+                        session.peripheral,
+                        side: side,
+                        central: central
+                    )
+                } else {
+                    drainReceiveQueue()
+                    Thread.sleep(forTimeInterval: 1.5)
+                }
+            }
+        }
+        throw G2FirmwareFlashError.transport(
+            "\(side): \(segment.fn) failed after \(Self.componentRetries) attempts: \(lastFailure)"
+        )
+    }
+
+    private func sendAndWait(
+        _ frames: [[UInt8]],
+        opcode: UInt8,
+        characteristic: CBCharacteristic,
+        peripheral: CBPeripheral,
+        timeoutMs: Int = 5000
+    ) throws -> UInt8 {
+        guard !frames.isEmpty else {
+            throw G2FirmwareFlashError.transport("Cannot send an empty OTA frame set")
+        }
+        drainReceiveQueue()
+        try writeFrames(frames, characteristic: characteristic, peripheral: peripheral)
+        return try waitForAck(
+            opcode: opcode,
+            peripheralID: peripheral.identifier,
+            timeoutMs: timeoutMs
+        )
+    }
+
+    private func waitForAck(opcode: UInt8, peripheralID: UUID, timeoutMs: Int) throws -> UInt8 {
+        let deadline = Date().addingTimeInterval(Double(timeoutMs) / 1000)
+        var observed: [String] = []
+        while Date() < deadline {
+            stateLock.lock()
+            let frames = receiveFrames
+            receiveFrames.removeAll()
+            stateLock.unlock()
+            let matching = frames.filter {
+                $0.peripheralID == peripheralID && $0.characteristicUUID == Self.dataNotifyUUID
+            }
+            if let status = G2FlashProtocol.otaAckStatus(
+                in: matching.map(\.bytes),
+                opcode: opcode
+            ) {
+                return status
+            }
+            for received in matching.prefix(4) {
+                let frame = received.bytes
+                if let decoded = G2FlashProtocol.parseRx(frame) {
+                    observed.append(
+                        String(
+                            format: "seq=%u sid=0x%02x pb=%@",
+                            decoded.sequence, decoded.sid,
+                            decoded.pb.map { String(format: "%02x", $0) }.joined()
+                        )
+                    )
+                } else {
+                    observed.append(frame.prefix(16).map { String(format: "%02x", $0) }.joined())
+                }
+            }
+            _ = receiveSemaphore.wait(timeout: .now() + 0.2)
+        }
+        let detail = observed.isEmpty ? "no OTA notifications received" : observed.suffix(4).joined(separator: "; ")
+        throw SessionError.acknowledgementTimeout(
+            String(format: "Timed out waiting for OTA acknowledgement 0x%02x (%@)", opcode, detail)
+        )
+    }
+
+    private func waitForAuthentication(
+        peripheralID: UUID,
+        magic: UInt8,
+        timeoutMs: Int,
+        side: String
+    ) throws {
+        let deadline = Date().addingTimeInterval(Double(timeoutMs) / 1000)
+        var observed: [String] = []
+        while Date() < deadline {
+            stateLock.lock()
+            let frames = receiveFrames
+            receiveFrames.removeAll()
+            stateLock.unlock()
+            let matching = frames.filter {
+                $0.peripheralID == peripheralID && $0.characteristicUUID == Self.controlNotifyUUID
+            }
+            if matching.contains(where: {
+                G2FlashProtocol.isAuthenticationSuccess($0.bytes, magic: magic)
+            }) {
+                return
+            }
+            observed.append(contentsOf: matching.prefix(4).map {
+                $0.bytes.prefix(16).map { String(format: "%02x", $0) }.joined()
+            })
+            _ = receiveSemaphore.wait(timeout: .now() + 0.2)
+        }
+        let detail = observed.isEmpty ? "no authentication notifications received" : observed.suffix(4).joined(separator: "; ")
+        throw G2FirmwareFlashError.transport(
+            "\(side) lens did not authenticate before OTA (\(detail))"
+        )
+    }
+
+    private func recoverSession(
+        _ peripheral: CBPeripheral,
+        side: String,
+        central: CBCentralManager
+    ) throws -> LensSession {
+        var lastFailure = "unknown error"
+        for attempt in 1 ... Self.reconnectAttempts {
+            progress(
+                "\(side): reconnecting OTA session (\(attempt)/\(Self.reconnectAttempts))",
+                0
+            )
+            do {
+                onMain {
+                    if peripheral.state != .disconnected {
+                        central.cancelPeripheralConnection(peripheral)
+                    }
+                }
+                try waitForPeripheral(
+                    peripheral,
+                    state: .disconnected,
+                    timeout: 8,
+                    context: "disconnect before OTA recovery"
+                )
+                Thread.sleep(forTimeInterval: Self.reconnectDelay)
+                drainReceiveQueue()
+
+                onMain {
+                    central.connect(
+                        peripheral,
+                        options: [
+                            CBConnectPeripheralOptionNotifyOnConnectionKey: true,
+                            CBConnectPeripheralOptionNotifyOnDisconnectionKey: true,
+                        ]
+                    )
+                }
+                try waitForPeripheral(
+                    peripheral,
+                    state: .connected,
+                    timeout: 25,
+                    context: "OTA recovery reconnect"
+                )
+                onMain { peripheral.discoverServices(nil) }
+                _ = try waitForChannels(peripheral, side: side, timeout: 20)
+
+                let recovered = try prepareSession(peripheral, side: side)
+                resetSequence()
+                try beginOtaSession(recovered, side: side)
+                progress("\(side): OTA session restored", 0)
+                return recovered
+            } catch {
+                lastFailure = error.localizedDescription
+                progress("\(side): OTA reconnect attempt failed: \(lastFailure)", 0)
+            }
+        }
+        throw G2FirmwareFlashError.transport(
+            "\(side): could not restore OTA session after \(Self.reconnectAttempts) attempts: \(lastFailure)"
+        )
+    }
+
+    private func waitForChannels(
+        _ peripheral: CBPeripheral,
+        side: String,
+        timeout: TimeInterval
+    ) throws -> LensSession {
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            if let session = try? lensSession(peripheral, side: side) {
+                return session
+            }
+            Thread.sleep(forTimeInterval: 0.1)
+        }
+        throw G2FirmwareFlashError.channelsMissing(
+            "\(side) lens OTA/authentication channels did not return after reconnect"
+        )
+    }
+
+    private func waitForPeripheral(
+        _ peripheral: CBPeripheral,
+        state expected: CBPeripheralState,
+        timeout: TimeInterval,
+        context: String
+    ) throws {
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            if peripheral.state == expected {
+                return
+            }
+            Thread.sleep(forTimeInterval: 0.1)
+        }
+        throw G2FirmwareFlashError.transport(
+            "Timed out waiting for \(context) (state \(peripheral.state.rawValue))"
+        )
+    }
+
+    private func writeFrames(
+        _ frames: [[UInt8]],
+        characteristic: CBCharacteristic,
+        peripheral: CBPeripheral
+    ) throws {
+        for frame in frames {
+            let deadline = Date().addingTimeInterval(5)
+            while !peripheral.canSendWriteWithoutResponse && Date() < deadline {
+                usleep(1000)
+            }
+            guard peripheral.canSendWriteWithoutResponse else {
+                throw G2FirmwareFlashError.transport("BLE write backpressure did not clear")
+            }
+            onMain {
+                peripheral.writeValue(Data(frame), for: characteristic, type: .withoutResponse)
+            }
+        }
+    }
+
+    private func findCharacteristic(_ peripheral: CBPeripheral, _ uuid: CBUUID) -> CBCharacteristic? {
+        for service in peripheral.services ?? [] {
+            if let match = service.characteristics?.first(where: { $0.uuid == uuid }) {
+                return match
+            }
+        }
+        return nil
+    }
+
+    private func nextSequence() -> UInt8 {
+        stateLock.lock()
+        sequence &+= 1
+        let next = sequence
+        stateLock.unlock()
+        return next
+    }
+
+    private func resetSequence() {
+        stateLock.lock()
+        sequence = 0
+        stateLock.unlock()
+    }
+
+    private func drainReceiveQueue() {
+        stateLock.lock()
+        receiveFrames.removeAll()
+        stateLock.unlock()
+        while receiveSemaphore.wait(timeout: .now()) == .success {}
+    }
+
+    private func onMain(_ action: @escaping () -> Void) {
+        if Thread.isMainThread {
+            action()
+        } else {
+            DispatchQueue.main.sync(execute: action)
+        }
+    }
+
+    private func progress(
+        _ message: String,
+        _ progress: Double,
+        done: Bool = false,
+        ok: Bool = true
+    ) {
+        Bridge.log("G2 flash: \(message)")
+        Bridge.sendTypedMessage(
+            "g2_firmware_flash_progress",
+            body: [
+                "message": message,
+                "progress": max(0, min(1, progress)),
+                "done": done,
+                "ok": ok,
+            ]
+        )
+    }
+}