feat: 重写 SDK 支持 iOS 12.2，移除 async/await 和 Combine

- 所有公开 API 改为 completion handler (Result<T, Error>) - 状态通知改为 DuooomiBleSDKDelegate 协议 - 移除 Sendable、@MainActor、AsyncStream、CheckedContinuation - 网络请求改为 URLSession.dataTask 回调 - BLE 通信改为 delegate + 闭包模式 - deployment target 降至 iOS 12.2 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-16 16:59:39 +08:00
parent 79af43cdef
commit 1a7bbdc625
26 changed files with 3211 additions and 944 deletions
--- a/Sources/DuooomiBleSDK/Core/BleClient.swift
+++ b/Sources/DuooomiBleSDK/Core/BleClient.swift
@@ -1,198 +1,116 @@
 import CoreBluetooth
 import Foundation

-/// CoreBluetooth 封装，提供 async API
-final class BleClient: NSObject, @unchecked Sendable {
-    private var centralManager: CBCentralManager!
-    private let queue = DispatchQueue(label: "com.duooomi.ble.client")
+/// BLE 客户端内部回调协议
+protocol BleClientDelegate: AnyObject {
+    func bleClient(_ client: BleClient, didDiscoverDevice device: DiscoveredDevice)
+    func bleClient(_ client: BleClient, didReceiveData data: Data)
+}

-    private(set) var connectedPeripheral: CBPeripheral?
-    private(set) var writeCharacteristic: CBCharacteristic?
-    private(set) var readCharacteristic: CBCharacteristic?
-
-    /// 已发现但尚未连接的外设缓存 (scan 时填充)
-    private var discoveredPeripherals: [UUID: CBPeripheral] = [:]
-
-    // MARK: - Continuations
-
-    private var connectContinuation: CheckedContinuation<CBPeripheral, Error>?
-    private var disconnectContinuation: CheckedContinuation<Void, Error>?
-
-    // MARK: - Streams
-
-    private var scanContinuation: AsyncStream<DiscoveredDevice>.Continuation?
-    private var notificationContinuation: AsyncStream<Data>.Continuation?
-
-    // MARK: - Callbacks
+final class BleClient: NSObject {

+    weak var delegate: BleClientDelegate?
    var onConnectionStateChange: ((ConnectionState) -> Void)?
    var onDisconnected: (() -> Void)?

-    // MARK: - Init
+    private let queue = DispatchQueue(label: "com.duooomi.ble.client", qos: .userInitiated)
+    private var centralManager: CBCentralManager!
+    private var connectedPeripheral: CBPeripheral?
+    private var writeCharacteristic: CBCharacteristic?
+    private var readCharacteristic: CBCharacteristic?

-    override init() {
-        super.init()
-        centralManager = CBCentralManager(delegate: self, queue: queue)
-        BleLog.i("BleClient initialized", "BLE")
-    }
+    // Connect/Disconnect callbacks
+    private var connectCompletion: ((Result<CBPeripheral, Error>) -> Void)?
+    private var disconnectCompletion: ((Result<Void, Error>) -> Void)?
+    private var connectTimeoutWork: DispatchWorkItem?

-    // MARK: - Public API
-
-    /// 当前蓝牙状态。
    var bluetoothState: CBManagerState {
        centralManager.state
    }

-    /// 当前连接在 `.withoutResponse` 模式下允许写入的最大长度。
    var maximumWriteLength: Int {
-        connectedPeripheral?.maximumWriteValueLength(for: .withoutResponse) ?? 20
+        connectedPeripheral?.maximumWriteValueLength(for: .withoutResponse) ?? 182
    }

-    /// 扫描包含目标 Service 的外设。
-    /// - Parameter serviceUUIDs: 需要匹配的 Service UUID 列表，默认使用 SDK 预设服务。
-    /// - Returns: 异步设备流；终止时自动停止底层扫描。
-    func scan(serviceUUIDs: [CBUUID] = [BleUUIDs.service]) -> AsyncStream<DiscoveredDevice> {
-        stopScan()
-        discoveredPeripherals.removeAll()
-
-        return AsyncStream { continuation in
-            self.scanContinuation = continuation
-            continuation.onTermination = { [weak self] _ in
-                self?.queue.async {
-                    self?.centralManager.stopScan()
-                    self?.scanContinuation = nil
-                }
-            }
-            self.queue.async {
-                guard self.centralManager.state == .poweredOn else { return }
-                BleLog.i("CBCentral startScan", "BLE")
-                self.centralManager.scanForPeripherals(
-                    withServices: serviceUUIDs,
-                    options: [CBCentralManagerScanOptionAllowDuplicatesKey: false]
-                )
-            }
-        }
+    override init() {
+        super.init()
+        centralManager = CBCentralManager(delegate: self, queue: queue)
    }

-    /// 停止扫描。
-    func stopScan() {
-        queue.async { [weak self] in
-            self?.centralManager.stopScan()
-            BleLog.i("CBCentral stopScan", "BLE")
-        }
-        scanContinuation?.finish()
-        scanContinuation = nil
-    }
+    // MARK: - Scan

-    /// 连接已发现的外设。
-    /// - Parameters:
-    ///   - deviceId: 目标外设的 UUID 字符串（来源于扫描阶段）。
-    ///   - timeout: 连接超时，默认 30 秒。
-    /// - Returns: 成功连接的 `CBPeripheral`。
-    /// - Throws: 蓝牙未开启、找不到设备、超时或连接失败等错误。
-    func connect(deviceId: String, timeout: TimeInterval = 30) async throws -> CBPeripheral {
+    func scan(serviceUUIDs: [CBUUID] = [BleUUIDs.service]) {
        guard centralManager.state == .poweredOn else {
-            throw DuooomiBleError.bluetoothNotPoweredOn(String(describing: centralManager.state))
-        }
-
-        guard let uuid = UUID(uuidString: deviceId),
-              let peripheral = discoveredPeripherals[uuid] else {
-            throw DuooomiBleError.connectionFailed("Device not found: \(deviceId)")
-        }
-
-        return try await withCheckedThrowingContinuation { continuation in
-            self.connectContinuation = continuation
-            self.queue.async {
-                BleLog.i("Connecting to peripheral: \(peripheral.identifier.uuidString)", "BLE")
-                self.centralManager.connect(peripheral, options: nil)
-            }
-
-            // Timeout
-            self.queue.asyncAfter(deadline: .now() + timeout) { [weak self] in
-                if let cont = self?.connectContinuation {
-                    self?.connectContinuation = nil
-                    self?.centralManager.cancelPeripheralConnection(peripheral)
-                    BleLog.w("Connection timeout: \(peripheral.identifier.uuidString)", "BLE")
-                    cont.resume(throwing: DuooomiBleError.connectionFailed("Connection timeout after \(Int(timeout))s"))
-                }
-            }
+            BleLog.w("Bluetooth not powered on", "BLE")
+            return
        }
+        centralManager.scanForPeripherals(
+            withServices: serviceUUIDs,
+            options: [CBCentralManagerScanOptionAllowDuplicatesKey: false]
+        )
    }

-    /// 断开当前连接。
-    /// - Throws: 如在超时后强制清理，仍会完成回调，不抛错；异常流程可能抛底层错误。
-    func disconnect() async throws {
-        guard let peripheral = connectedPeripheral else { return }
-
-        try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
-            self.disconnectContinuation = continuation
-            self.queue.async {
-                BleLog.i("Cancel connection: \(peripheral.identifier.uuidString)", "BLE")
-                self.centralManager.cancelPeripheralConnection(peripheral)
-            }
-
-            // Timeout for disconnect
-            self.queue.asyncAfter(deadline: .now() + 5) { [weak self] in
-                if let cont = self?.disconnectContinuation {
-                    self?.disconnectContinuation = nil
-                    BleLog.w("Force-finish disconnect after timeout", "BLE")
-                    self?.cleanup()
-                    cont.resume()
-                }
-            }
-        }
+    func stopScan() {
+        centralManager.stopScan()
    }

-    /// 无响应写入（GATT Write Without Response）。
-    /// - Parameter data: 要写入的二进制数据。
-    /// - Throws: 未连接等错误。
+    // MARK: - Connect
+
+    func connect(deviceId: String, timeout: TimeInterval = 30, completion: @escaping (Result<CBPeripheral, Error>) -> Void) {
+        guard centralManager.state == .poweredOn else {
+            completion(.failure(DuooomiBleError.bluetoothNotPoweredOn("Bluetooth not powered on")))
+            return
+        }
+
+        let peripherals = centralManager.retrievePeripherals(withIdentifiers: [UUID(uuidString: deviceId)!])
+        guard let peripheral = peripherals.first else {
+            completion(.failure(DuooomiBleError.connectionFailed("Device not found: \(deviceId)")))
+            return
+        }
+
+        self.connectCompletion = completion
+        peripheral.delegate = self
+        centralManager.connect(peripheral, options: nil)
+
+        // Timeout
+        let work = DispatchWorkItem { [weak self] in
+            guard let self = self, self.connectCompletion != nil else { return }
+            self.centralManager.cancelPeripheralConnection(peripheral)
+            let cb = self.connectCompletion
+            self.connectCompletion = nil
+            cb?(.failure(DuooomiBleError.connectionFailed("Connection timeout")))
+        }
+        connectTimeoutWork = work
+        queue.asyncAfter(deadline: .now() + timeout, execute: work)
+    }
+
+    // MARK: - Disconnect
+
+    func disconnect(completion: @escaping (Result<Void, Error>) -> Void) {
+        guard let peripheral = connectedPeripheral else {
+            completion(.success(()))
+            return
+        }
+        disconnectCompletion = completion
+        centralManager.cancelPeripheralConnection(peripheral)
+    }
+
+    // MARK: - Write
+
    func writeWithoutResponse(_ data: Data) throws {
-        guard let peripheral = connectedPeripheral,
-              let characteristic = writeCharacteristic else {
+        guard let peripheral = connectedPeripheral, let char = writeCharacteristic else {
            throw DuooomiBleError.notConnected
        }
-        BleLog.d("Write w/o response, len=\(data.count)", "BLE")
-        peripheral.writeValue(data, for: characteristic, type: .withoutResponse)
+        peripheral.writeValue(data, for: char, type: .withoutResponse)
    }

-    /// 查询系统层面已连接、且具备目标 Service 的外设。
-    /// - Returns: 已连接外设的精简信息列表。
+    // MARK: - Retrieve Connected
+
    func retrieveConnectedDevices() -> [DiscoveredDevice] {
-        let peripherals = centralManager.retrieveConnectedPeripherals(withServices: [BleUUIDs.service])
-        return peripherals.map { peripheral in
-            DiscoveredDevice(
-                id: peripheral.identifier.uuidString,
-                name: peripheral.name,
-                rssi: 0
-            )
+        centralManager.retrieveConnectedPeripherals(withServices: [BleUUIDs.service]).map {
+            DiscoveredDevice(id: $0.identifier.uuidString, name: $0.name, rssi: 0)
        }
    }
-
-    /// 订阅并接收通知特征的原始二进制数据流。
-    /// - Returns: 通知数据的异步流。
-    func notifications() -> AsyncStream<Data> {
-        AsyncStream { continuation in
-            self.notificationContinuation = continuation
-            continuation.onTermination = { [weak self] _ in
-                self?.notificationContinuation = nil
-            }
-            BleLog.i("Notifications stream attached", "BLE")
-        }
-    }
-
-    // MARK: - Private
-
-    private func cleanup() {
-        if let readChar = readCharacteristic, let peripheral = connectedPeripheral {
-            peripheral.setNotifyValue(false, for: readChar)
-        }
-        connectedPeripheral = nil
-        writeCharacteristic = nil
-        readCharacteristic = nil
-        notificationContinuation?.finish()
-        notificationContinuation = nil
-        BleLog.i("Client state cleaned up", "BLE")
-    }
 }

 // MARK: - CBCentralManagerDelegate
@@ -200,67 +118,51 @@ final class BleClient: NSObject, @unchecked Sendable {
 extension BleClient: CBCentralManagerDelegate {

    func centralManagerDidUpdateState(_ central: CBCentralManager) {
-        // If scanning was requested before poweredOn, start now
-        if central.state == .poweredOn, scanContinuation != nil {
-            BleLog.d("State poweredOn; resume scan", "BLE")
-            central.scanForPeripherals(
-                withServices: [BleUUIDs.service],
-                options: [CBCentralManagerScanOptionAllowDuplicatesKey: false]
-            )
-        }
-        BleLog.d("Central state=\(central.state.rawValue)", "BLE")
+        BleLog.i("Bluetooth state: \(central.state.rawValue)", "BLE")
    }

-    func centralManager(
-        _ central: CBCentralManager,
-        didDiscover peripheral: CBPeripheral,
-        advertisementData: [String: Any],
-        rssi RSSI: NSNumber
-    ) {
-        discoveredPeripherals[peripheral.identifier] = peripheral
-
+    func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral,
+                         advertisementData: [String: Any], rssi RSSI: NSNumber) {
        let device = DiscoveredDevice(
            id: peripheral.identifier.uuidString,
-            name: peripheral.name ?? advertisementData[CBAdvertisementDataLocalNameKey] as? String,
+            name: peripheral.name,
            rssi: RSSI.intValue
        )
-        BleLog.d("Did discover: id=\(device.id), rssi=\(device.rssi)", "BLE")
-        scanContinuation?.yield(device)
+        delegate?.bleClient(self, didDiscoverDevice: device)
    }

    func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
+        connectTimeoutWork?.cancel()
+        connectTimeoutWork = nil
        connectedPeripheral = peripheral
        peripheral.delegate = self
-        BleLog.i("Did connect: \(peripheral.identifier.uuidString)", "BLE")
        peripheral.discoverServices([BleUUIDs.service])
    }

    func centralManager(_ central: CBCentralManager, didFailToConnect peripheral: CBPeripheral, error: Error?) {
-        let cont = connectContinuation
-        connectContinuation = nil
-        BleLog.e("Fail to connect: \(peripheral.identifier.uuidString), error=\(error?.localizedDescription ?? "-")", "BLE")
-        cont?.resume(throwing: DuooomiBleError.connectionFailed(error?.localizedDescription ?? "Unknown error"))
+        connectTimeoutWork?.cancel()
+        connectTimeoutWork = nil
+        let cb = connectCompletion
+        connectCompletion = nil
+        cb?(.failure(error ?? DuooomiBleError.connectionFailed("Unknown")))
    }

    func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?) {
-        // If disconnect happens mid-setup (after didConnect but before discoverCharacteristics
-        // completes), the connect continuation must be resolved or the caller hangs forever.
-        if let connectCont = connectContinuation {
-            connectContinuation = nil
-            connectCont.resume(throwing: DuooomiBleError.connectionFailed(
-                error?.localizedDescription ?? "Disconnected during setup"
-            ))
+        connectedPeripheral = nil
+        writeCharacteristic = nil
+        readCharacteristic = nil
+
+        if let cb = disconnectCompletion {
+            disconnectCompletion = nil
+            if let error = error {
+                cb(.failure(error))
+            } else {
+                cb(.success(()))
+            }
        }
-
-        cleanup()
-
-        if let cont = disconnectContinuation {
-            disconnectContinuation = nil
-            cont.resume()
+        DispatchQueue.main.async { [weak self] in
+            self?.onDisconnected?()
        }
-
-        BleLog.w("Did disconnect: \(peripheral.identifier.uuidString), error=\(error?.localizedDescription ?? "-")", "BLE")
-        onDisconnected?()
    }
 }

@@ -270,22 +172,17 @@ extension BleClient: CBPeripheralDelegate {

    func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
        if let error = error {
-            let cont = connectContinuation
-            connectContinuation = nil
-            BleLog.e("Discover services error: \(error.localizedDescription)", "BLE")
-            cont?.resume(throwing: DuooomiBleError.connectionFailed(error.localizedDescription))
+            let cb = connectCompletion
+            connectCompletion = nil
+            cb?(.failure(error))
            return
        }
-
        guard let service = peripheral.services?.first(where: { $0.uuid == BleUUIDs.service }) else {
-            let cont = connectContinuation
-            connectContinuation = nil
-            BleLog.e("Service not found", "BLE")
-            cont?.resume(throwing: DuooomiBleError.serviceNotFound)
+            let cb = connectCompletion
+            connectCompletion = nil
+            cb?(.failure(DuooomiBleError.serviceNotFound))
            return
        }
-
-        BleLog.d("Service found: \(service.uuid.uuidString)", "BLE")
        peripheral.discoverCharacteristics(
            [BleUUIDs.writeCharacteristic, BleUUIDs.readCharacteristic],
            for: service
@@ -294,17 +191,15 @@ extension BleClient: CBPeripheralDelegate {

    func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
        if let error = error {
-            let cont = connectContinuation
-            connectContinuation = nil
-            BleLog.e("Discover characteristics error: \(error.localizedDescription)", "BLE")
-            cont?.resume(throwing: DuooomiBleError.connectionFailed(error.localizedDescription))
+            let cb = connectCompletion
+            connectCompletion = nil
+            cb?(.failure(error))
            return
        }
-
        guard let characteristics = service.characteristics else {
-            let cont = connectContinuation
-            connectContinuation = nil
-            cont?.resume(throwing: DuooomiBleError.characteristicNotFound)
+            let cb = connectCompletion
+            connectCompletion = nil
+            cb?(.failure(DuooomiBleError.characteristicNotFound))
            return
        }

@@ -318,24 +213,19 @@ extension BleClient: CBPeripheralDelegate {
        }

        guard writeCharacteristic != nil, readCharacteristic != nil else {
-            let cont = connectContinuation
-            connectContinuation = nil
-            BleLog.e("Required characteristics missing", "BLE")
-            cont?.resume(throwing: DuooomiBleError.characteristicNotFound)
+            let cb = connectCompletion
+            connectCompletion = nil
+            cb?(.failure(DuooomiBleError.characteristicNotFound))
            return
        }

-        // Connection fully ready
-        let cont = connectContinuation
-        connectContinuation = nil
-        BleLog.i("Characteristics ready; connection established", "BLE")
-        cont?.resume(returning: peripheral)
+        let cb = connectCompletion
+        connectCompletion = nil
+        cb?(.success(peripheral))
    }

    func peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic, error: Error?) {
-        guard error == nil, characteristic.uuid == BleUUIDs.readCharacteristic,
-              let value = characteristic.value else { return }
-        BleLog.d("Notification received, len=\(value.count)", "BLE")
-        notificationContinuation?.yield(value)
+        guard error == nil, let data = characteristic.value else { return }
+        delegate?.bleClient(self, didReceiveData: data)
    }
 }
--- a/Sources/DuooomiBleSDK/Core/BleTypes.swift
+++ b/Sources/DuooomiBleSDK/Core/BleTypes.swift
@@ -1,6 +1,6 @@
 import Foundation

-public enum ConnectionState: String, Sendable {
+public enum ConnectionState: String {
    case idle
    case scanning
    case connecting
@@ -9,7 +9,7 @@ public enum ConnectionState: String, Sendable {
    case disconnected
 }

-public struct DiscoveredDevice: Identifiable, Sendable, Equatable {
+public struct DiscoveredDevice: Identifiable, Equatable {
    public let id: String
    public let name: String?
    public let rssi: Int
@@ -21,7 +21,7 @@ public struct DiscoveredDevice: Identifiable, Sendable, Equatable {
    }
 }

-public enum DuooomiBleError: LocalizedError, Sendable {
+public enum DuooomiBleError: LocalizedError {
    case bluetoothNotPoweredOn(String)
    case notConnected
    case timeout(command: CommandType)
--- a/Sources/DuooomiBleSDK/DuooomiBleConfig.swift
+++ b/Sources/DuooomiBleSDK/DuooomiBleConfig.swift
@@ -1,7 +1,7 @@
 import Foundation

 /// SDK 全局配置，在初始化时一次性传入。
-public struct DuooomiBleConfig: Sendable {
+public struct DuooomiBleConfig {
    /// API 服务地址
    public let apiHost: URL
    /// API 鉴权 key
--- a/Sources/DuooomiBleSDK/DuooomiBleSDK.swift
+++ b/Sources/DuooomiBleSDK/DuooomiBleSDK.swift
--- a/Sources/DuooomiBleSDK/DuooomiBleSDKDelegate.swift
+++ b/Sources/DuooomiBleSDK/DuooomiBleSDKDelegate.swift
@@ -0,0 +1,34 @@
+import Foundation
+
+/// SDK 状态变化回调协议，替代 Combine @Published 观察。
+/// 所有方法在主线程调用。
+public protocol DuooomiBleSDKDelegate: AnyObject {
+    /// 蓝牙连接状态变化
+    func sdk(_ sdk: DuooomiBleSDK, didChangeState state: ConnectionState)
+    /// 扫描到的设备列表更新
+    func sdk(_ sdk: DuooomiBleSDK, didUpdateDevices devices: [DiscoveredDevice])
+    /// 已连接设备变化
+    func sdk(_ sdk: DuooomiBleSDK, didConnectDevice device: DiscoveredDevice?)
+    /// 设备信息更新
+    func sdk(_ sdk: DuooomiBleSDK, didUpdateDeviceInfo info: DeviceInfo?)
+    /// 固件版本更新
+    func sdk(_ sdk: DuooomiBleSDK, didUpdateVersion version: String)
+    /// 激活状态变化
+    func sdk(_ sdk: DuooomiBleSDK, didChangeActivation isActivated: Bool)
+    /// 传输进度更新 (0-100)
+    func sdk(_ sdk: DuooomiBleSDK, didUpdateProgress progress: Int)
+    /// 错误发生
+    func sdk(_ sdk: DuooomiBleSDK, didEncounterError error: String?)
+}
+
+/// 所有 delegate 方法提供默认空实现，调用方只需实现关心的方法。
+public extension DuooomiBleSDKDelegate {
+    func sdk(_ sdk: DuooomiBleSDK, didChangeState state: ConnectionState) {}
+    func sdk(_ sdk: DuooomiBleSDK, didUpdateDevices devices: [DiscoveredDevice]) {}
+    func sdk(_ sdk: DuooomiBleSDK, didConnectDevice device: DiscoveredDevice?) {}
+    func sdk(_ sdk: DuooomiBleSDK, didUpdateDeviceInfo info: DeviceInfo?) {}
+    func sdk(_ sdk: DuooomiBleSDK, didUpdateVersion version: String) {}
+    func sdk(_ sdk: DuooomiBleSDK, didChangeActivation isActivated: Bool) {}
+    func sdk(_ sdk: DuooomiBleSDK, didUpdateProgress progress: Int) {}
+    func sdk(_ sdk: DuooomiBleSDK, didEncounterError error: String?) {}
+}
--- a/Sources/DuooomiBleSDK/Models/BindingResponse.swift
+++ b/Sources/DuooomiBleSDK/Models/BindingResponse.swift
@@ -1,6 +1,6 @@
 import Foundation

-public struct BindingResponse: Codable, Sendable, Equatable {
+public struct BindingResponse: Codable, Equatable {
    public let type: Int
    /// 设备 SN 码 (14 位)
    public let sn: String
--- a/Sources/DuooomiBleSDK/Models/DeleteFileResponse.swift
+++ b/Sources/DuooomiBleSDK/Models/DeleteFileResponse.swift
@@ -1,6 +1,6 @@
 import Foundation

-public struct DeleteFileResponse: Codable, Sendable, Equatable {
+public struct DeleteFileResponse: Codable, Equatable {
    public let type: Int
    /// 0 = 成功, 1 = 失败, 2 = 文件不存在
    public let success: Int
--- a/Sources/DuooomiBleSDK/Models/DeviceInfo.swift
+++ b/Sources/DuooomiBleSDK/Models/DeviceInfo.swift
@@ -1,6 +1,6 @@
 import Foundation

-public struct DeviceInfo: Sendable, Equatable {
+public struct DeviceInfo: Equatable {
    public let allspace: UInt64
    public let freespace: UInt64
    public let name: String
--- a/Sources/DuooomiBleSDK/Models/PrepareTransferResponse.swift
+++ b/Sources/DuooomiBleSDK/Models/PrepareTransferResponse.swift
@@ -1,6 +1,6 @@
 import Foundation

-public struct PrepareTransferResponse: Codable, Sendable, Equatable {
+public struct PrepareTransferResponse: Codable, Equatable {
    public let type: Int
    public let key: String
    /// "ready" | "no_space" | "duplicated"
--- a/Sources/DuooomiBleSDK/Models/UnbindResponse.swift
+++ b/Sources/DuooomiBleSDK/Models/UnbindResponse.swift
@@ -1,6 +1,6 @@
 import Foundation

-public struct UnbindResponse: Codable, Sendable, Equatable {
+public struct UnbindResponse: Codable, Equatable {
    /// 1 = 成功, 0 = 失败
    public let success: Int
 }
--- a/Sources/DuooomiBleSDK/Models/VersionInfo.swift
+++ b/Sources/DuooomiBleSDK/Models/VersionInfo.swift
@@ -1,6 +1,6 @@
 import Foundation

-public struct VersionInfo: Sendable, Equatable {
+public struct VersionInfo: Equatable {
    public let version: String
    /// 命令类型标识，设备可能返回 Int (如 7) 或 String (如 "0x07")
    public let type: String
--- a/Sources/DuooomiBleSDK/Protocol/ProtocolConstants.swift
+++ b/Sources/DuooomiBleSDK/Protocol/ProtocolConstants.swift
@@ -21,7 +21,7 @@ public enum FrameConstants {
    public static let screenSize = 360
 }

-public enum CommandType: UInt8, Sendable {
+public enum CommandType: UInt8 {
    case otaPackage = 0x02
    case transferBootAnimation = 0x03
    case transferAniVideo = 0x05
--- a/Sources/DuooomiBleSDK/Protocol/ProtocolFrame.swift
+++ b/Sources/DuooomiBleSDK/Protocol/ProtocolFrame.swift
@@ -2,7 +2,7 @@ import Foundation

 /// BLE 协议帧结构
 /// 格式: [head:1][type:1][subpageTotal:2][curPage:2][dataLen:2][data:N][checksum:1]
-public struct ProtocolFrame: Sendable {
+public struct ProtocolFrame {
    /// 传输方向标识 (0xC7 = APP→Device, 0xB0 = Device→APP)
    public let head: UInt8
    /// 命令类型，对应 CommandType
--- a/Sources/DuooomiBleSDK/Services/AniConverter.swift
+++ b/Sources/DuooomiBleSDK/Services/AniConverter.swift
@@ -10,7 +10,7 @@ final class AniConverter {
    private let config: DuooomiBleConfig

    private var endpoint: URL {
-        config.apiHost.appendingPathComponent("api/auth/loomart/file/convert-to-ani")
+        URL(string: "\(config.apiHost)/api/auth/loomart/file/convert-to-ani")!
    }

    private let session: URLSession = {
@@ -26,15 +26,23 @@ final class AniConverter {
    }

    /// 调用 ANI 转换接口，返回 ani 文件的 CDN URL。
-    func convert(fileUrl: String) async throws -> String {
-        do {
-            return try await performConvert(fileUrl: fileUrl)
-        } catch let error as NSError where error.code == NSURLErrorNetworkConnectionLost {
-            return try await performConvert(fileUrl: fileUrl)
+    func convert(fileUrl: String, completion: @escaping (Result<String, Error>) -> Void) {
+        performConvert(fileUrl: fileUrl) { result in
+            switch result {
+            case .success:
+                completion(result)
+            case .failure(let error):
+                // Retry once on connection lost
+                if (error as NSError).code == NSURLErrorNetworkConnectionLost {
+                    self.performConvert(fileUrl: fileUrl, completion: completion)
+                } else {
+                    completion(.failure(error))
+                }
+            }
        }
    }

-    private func performConvert(fileUrl: String) async throws -> String {
+    private func performConvert(fileUrl: String, completion: @escaping (Result<String, Error>) -> Void) {
        var request = URLRequest(url: endpoint)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "content-type")
@@ -47,32 +55,49 @@ final class AniConverter {
            "height": config.aniHeight,
            "fps": config.aniFps,
        ]
-        request.httpBody = try JSONSerialization.data(withJSONObject: body)

-        let (data, response) = try await session.data(for: request)
-
-        if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
-            throw AniConverterError(message: "HTTP \(http.statusCode)")
+        do {
+            request.httpBody = try JSONSerialization.data(withJSONObject: body)
+        } catch {
+            completion(.failure(error))
+            return
        }

-        guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
-            throw AniConverterError(message: "Invalid JSON response")
-        }
+        session.dataTask(with: request) { data, response, error in
+            if let error = error {
+                completion(.failure(error))
+                return
+            }

-        guard (json["success"] as? Bool) == true,
-              let outer = json["data"] as? [String: Any] else {
-            throw AniConverterError(message: "ANI API reported failure")
-        }
+            if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
+                completion(.failure(AniConverterError(message: "HTTP \(http.statusCode)")))
+                return
+            }

-        if (outer["status"] as? Bool) != true {
-            let msg = (outer["msg"] as? String) ?? "ANI conversion failed"
-            throw AniConverterError(message: msg)
-        }
+            guard let data = data,
+                  let json = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else {
+                completion(.failure(AniConverterError(message: "Invalid JSON response")))
+                return
+            }

-        guard let aniUrl = outer["data"] as? String, !aniUrl.isEmpty else {
-            throw AniConverterError(message: "Missing ani url in response")
-        }
+            guard (json["success"] as? Bool) == true,
+                  let outer = json["data"] as? [String: Any] else {
+                completion(.failure(AniConverterError(message: "ANI API reported failure")))
+                return
+            }

-        return aniUrl
+            if (outer["status"] as? Bool) != true {
+                let msg = (outer["msg"] as? String) ?? "ANI conversion failed"
+                completion(.failure(AniConverterError(message: msg)))
+                return
+            }
+
+            guard let aniUrl = outer["data"] as? String, !aniUrl.isEmpty else {
+                completion(.failure(AniConverterError(message: "Missing ani url in response")))
+                return
+            }
+
+            completion(.success(aniUrl))
+        }.resume()
    }
 }
--- a/Sources/DuooomiBleSDK/Services/BleProtocolService.swift
+++ b/Sources/DuooomiBleSDK/Services/BleProtocolService.swift
@@ -1,8 +1,16 @@
 import Foundation

+/// 协议服务内部回调
+protocol BleProtocolServiceDelegate: AnyObject {
+    func protocolService(_ service: BleProtocolService, didReceiveMessage commandType: UInt8, data: Data)
+}
+
 /// 协议通信服务：帧收发、分包重组
-final class BleProtocolService: @unchecked Sendable {
+final class BleProtocolService: BleClientDelegate {
+
+    weak var delegate: BleProtocolServiceDelegate?
    private let client: BleClient
+    private var isListening = false

    /// 分包重组会话
    private struct FragmentSession {
@@ -11,63 +19,36 @@ final class BleProtocolService: @unchecked Sendable {
    }

    private var fragments: [String: FragmentSession] = [:]
-    private var listenerTask: Task<Void, Never>?
-
-    private var messageContinuation: AsyncStream<(commandType: UInt8, data: Data)>.Continuation?
-    private(set) var incomingMessages: AsyncStream<(commandType: UInt8, data: Data)>!

    init(client: BleClient) {
        self.client = client
-        incomingMessages = AsyncStream { continuation in
-            self.messageContinuation = continuation
-        }
        BleLog.i("Protocol service created", "Protocol")
    }

    // MARK: - Start/Stop Listening

-    /// 开始监听底层通知并进行帧解析与重组。
-    /// - Note: 重新创建消息流并清空历史分片缓存。
    func startListening() {
-        // Recreate the stream in case it was previously finished
-        incomingMessages = AsyncStream { continuation in
-            self.messageContinuation = continuation
-        }
-
+        isListening = true
+        client.delegate = self
        fragments.removeAll()
-
-        listenerTask = Task { [weak self] in
-            guard let self else { return }
-            BleLog.i("Start listening for notifications", "Protocol")
-            for await data in self.client.notifications() {
-                self.handleRawData(data)
-            }
-        }
+        BleLog.i("Start listening for notifications", "Protocol")
    }

-    /// 停止监听，结束消息流并清理缓存。
    func stopListening() {
-        listenerTask?.cancel()
-        listenerTask = nil
-        messageContinuation?.finish()
-        messageContinuation = nil
+        isListening = false
        fragments.removeAll()
        BleLog.i("Stop listening; fragments cleared", "Protocol")
    }

    // MARK: - Send

-    /// 发送二进制数据（自动拆分为协议帧）。
-    /// - Parameters:
-    ///   - type: 命令类型值。
-    ///   - data: 需要发送的原始负载。
-    ///   - onProgress: 发送进度回调（0.0~1.0）。
-    /// - Throws: 写入失败或负载过大等错误。
+    /// 发送二进制数据（自动拆分为协议帧），使用回调。
    func send(
        type: UInt8,
        data: Data,
-        onProgress: ((Double) -> Void)? = nil
-    ) async throws {
+        onProgress: ((Double) -> Void)? = nil,
+        completion: @escaping (Result<Void, Error>) -> Void
+    ) {
        let maxWriteLen = client.maximumWriteLength
        let maxDataSize = min(
            maxWriteLen - FrameConstants.headerSize - FrameConstants.footerSize,
@@ -84,27 +65,84 @@ final class BleProtocolService: @unchecked Sendable {

        guard !frames.isEmpty else {
            BleLog.e("Payload too large; frames empty", "Protocol")
-            throw DuooomiBleError.transferFailed("Payload too large: exceeds 65535-page limit")
+            completion(.failure(DuooomiBleError.transferFailed("Payload too large: exceeds 65535-page limit")))
+            return
        }

        let total = frames.count
        BleLog.d("Sending frames: total=\(total), maxChunk=\(safeMaxDataSize)", "Protocol")
-        for (index, frame) in frames.enumerated() {
-            try client.writeWithoutResponse(frame)
-            try await Task.sleep(nanoseconds: FrameConstants.frameIntervalNanos)
+
+        func sendFrame(at index: Int) {
+            guard index < total else {
+                onProgress?(1.0)
+                BleLog.i("Frames sent: total=\(total)", "Protocol")
+                completion(.success(()))
+                return
+            }
+
+            do {
+                try self.client.writeWithoutResponse(frames[index])
+            } catch {
+                completion(.failure(error))
+                return
+            }
+
            onProgress?(Double(index + 1) / Double(total))
+
+            if index + 1 < total {
+                // Inter-frame delay 35ms
+                DispatchQueue.global(qos: .userInitiated).asyncAfter(deadline: .now() + 0.035) {
+                    sendFrame(at: index + 1)
+                }
+            } else {
+                onProgress?(1.0)
+                BleLog.i("Frames sent: total=\(total)", "Protocol")
+                completion(.success(()))
+            }
        }
-        BleLog.i("Frames sent: total=\(total)", "Protocol")
+
+        sendFrame(at: 0)
    }

-    /// 发送 JSON 命令，内部完成编码与帧拆分。
-    /// - Parameters:
-    ///   - type: 命令类型。
-    ///   - payload: 可编码的命令体。
-    /// - Throws: 编码/发送失败时抛出。
-    func sendJSON<T: Encodable>(type: CommandType, payload: T) async throws {
+    /// 发送 JSON 命令（带回调）
+    func sendJSON<T: Encodable>(type: CommandType, payload: T, completion: @escaping (Result<Void, Error>) -> Void) {
+        do {
+            let data = try JSONEncoder().encode(payload)
+            send(type: type.rawValue, data: data, completion: completion)
+        } catch {
+            completion(.failure(error))
+        }
+    }
+
+    /// 发送 JSON 命令（同步，fire-and-forget，仅发第一帧，用于简单命令）
+    func sendJSON<T: Encodable>(type: CommandType, payload: T) throws {
        let jsonData = try JSONEncoder().encode(payload)
-        try await send(type: type.rawValue, data: jsonData)
+        let maxWriteLen = client.maximumWriteLength
+        let maxDataSize = min(
+            maxWriteLen - FrameConstants.headerSize - FrameConstants.footerSize,
+            FrameConstants.maxDataSize
+        )
+        let safeMaxDataSize = max(1, maxDataSize)
+        let frames = ProtocolManager.createFrames(
+            type: type.rawValue,
+            data: jsonData,
+            head: .appToDevice,
+            maxDataSize: safeMaxDataSize
+        )
+        for frame in frames {
+            try client.writeWithoutResponse(frame)
+        }
+    }
+
+    // MARK: - BleClientDelegate
+
+    func bleClient(_ client: BleClient, didDiscoverDevice device: DiscoveredDevice) {
+        // Not handled here — scan results forwarded by SDK
+    }
+
+    func bleClient(_ client: BleClient, didReceiveData data: Data) {
+        guard isListening else { return }
+        handleRawData(data)
    }

    // MARK: - Receive & Reassemble
@@ -119,15 +157,12 @@ final class BleProtocolService: @unchecked Sendable {
            handleFragment(frame)
        } else {
            BleLog.d("Single frame received: type=\(frame.type), len=\(frame.data.count)", "Protocol")
-            messageContinuation?.yield((commandType: frame.type, data: frame.data))
+            delegate?.protocolService(self, didReceiveMessage: frame.type, data: frame.data)
        }
    }

    private func handleFragment(_ frame: ProtocolFrame) {
-        // Match TS reference behavior: scope reassembly per peripheral so concurrent transfers
-        // (or stale fragments from a previous device after reconnect) cannot pollute each other.
-        let deviceKey = client.connectedPeripheral?.identifier.uuidString ?? "unknown"
-        let key = "\(deviceKey)_\(frame.type)"
+        let key = "\(frame.type)"

        if fragments[key] == nil {
            fragments[key] = FragmentSession(total: Int(frame.subpageTotal), frames: [:])
@@ -153,6 +188,6 @@ final class BleProtocolService: @unchecked Sendable {

        fragments.removeValue(forKey: key)
        BleLog.i("Fragment reassembled: key=\(key), size=\(combined.count)", "Protocol")
-        messageContinuation?.yield((commandType: frame.type, data: combined))
+        delegate?.protocolService(self, didReceiveMessage: frame.type, data: combined)
    }
 }
--- a/Sources/DuooomiBleSDK/Services/DeviceInfoService.swift
+++ b/Sources/DuooomiBleSDK/Services/DeviceInfoService.swift
@@ -1,6 +1,6 @@
 import Foundation

-/// 设备命令服务：发送 JSON 命令，等待协议响应
+/// 设备命令服务：发送 JSON 命令（fire-and-forget，响应由协议层回调处理）
 final class DeviceInfoService {
    private let protocolService: BleProtocolService

@@ -10,61 +10,43 @@ final class DeviceInfoService {

    // MARK: - Commands

-    /// 发送获取设备信息命令。
-    /// - Throws: 发送失败时抛出。
-    func getDeviceInfo() async throws {
-        try await protocolService.sendJSON(
+    func getDeviceInfo() throws {
+        try protocolService.sendJSON(
            type: .getDeviceInfo,
            payload: CommandPayload(type: CommandType.getDeviceInfo.rawValue)
        )
    }

-    /// 发送获取设备版本命令。
-    /// - Throws: 发送失败时抛出。
-    func getDeviceVersion() async throws {
-        try await protocolService.sendJSON(
+    func getDeviceVersion() throws {
+        try protocolService.sendJSON(
            type: .getDeviceVersion,
            payload: CommandPayload(type: CommandType.getDeviceVersion.rawValue)
        )
    }

-    /// 发送绑定命令。
-    /// - Parameter userId: 用户唯一标识。
-    /// - Throws: 发送失败时抛出。
-    func bindDevice(userId: String) async throws {
-        try await protocolService.sendJSON(
+    func bindDevice(userId: String) throws {
+        try protocolService.sendJSON(
            type: .bindDevice,
            payload: BindPayload(type: CommandType.bindDevice.rawValue, userId: userId)
        )
    }

-    /// 发送解绑命令。
-    /// - Parameter userId: 用户唯一标识。
-    /// - Throws: 发送失败时抛出。
-    func unbindDevice(userId: String) async throws {
-        try await protocolService.sendJSON(
+    func unbindDevice(userId: String) throws {
+        try protocolService.sendJSON(
            type: .unbindDevice,
            payload: BindPayload(type: CommandType.unbindDevice.rawValue, userId: userId)
        )
    }

-    /// 发送删除文件命令。
-    /// - Parameter key: 文件 key 或完整 URL。
-    /// - Throws: 发送失败时抛出。
-    func deleteFile(key: String) async throws {
-        try await protocolService.sendJSON(
+    func deleteFile(key: String) throws {
+        try protocolService.sendJSON(
            type: .deleteFile,
            payload: FileKeyPayload(type: CommandType.deleteFile.rawValue, key: key)
        )
    }

-    /// 发送传输准备命令。
-    /// - Parameters:
-    ///   - key: 文件标识 key。
-    ///   - size: 文件大小（字节）。
-    /// - Throws: 发送失败时抛出。
-    func prepareTransfer(key: String, size: Int) async throws {
-        try await protocolService.sendJSON(
+    func prepareTransfer(key: String, size: Int) throws {
+        try protocolService.sendJSON(
            type: .prepareTransfer,
            payload: PrepareTransferPayload(
                type: CommandType.prepareTransfer.rawValue,
--- a/Sources/DuooomiBleSDK/Services/FileTransferService.swift
+++ b/Sources/DuooomiBleSDK/Services/FileTransferService.swift
@@ -9,40 +9,60 @@ final class FileTransferService {
    }

    /// 传输文件到设备
-    /// - Parameters:
-    ///   - fileUri: 本地 file:// URL 或远程 https:// URL
-    ///   - commandType: 传输命令类型
-    ///   - onProgress: 进度回调 0.0 ~ 1.0
    func transferFile(
        fileUri: String,
        commandType: CommandType,
-        onProgress: ((Double) -> Void)? = nil
-    ) async throws {
+        onProgress: ((Double) -> Void)? = nil,
+        completion: @escaping (Result<Void, Error>) -> Void
+    ) {
        BleLog.i("Load file: \(fileUri)", "Transfer")
-        let data = try await loadFileData(from: fileUri)
-        BleLog.d("File loaded: size=\(data.count) bytes", "Transfer")
-
-        try await protocolService.send(
-            type: commandType.rawValue,
-            data: data,
-            onProgress: onProgress
-        )
+        loadFileData(from: fileUri) { [weak self] result in
+            switch result {
+            case .failure(let error):
+                completion(.failure(error))
+            case .success(let data):
+                BleLog.d("File loaded: size=\(data.count) bytes", "Transfer")
+                self?.protocolService.send(
+                    type: commandType.rawValue,
+                    data: data,
+                    onProgress: onProgress,
+                    completion: completion
+                )
+            }
+        }
    }

-    private func loadFileData(from uri: String) async throws -> Data {
+    private func loadFileData(from uri: String, completion: @escaping (Result<Data, Error>) -> Void) {
        guard let url = URL(string: uri) else {
-            throw DuooomiBleError.transferFailed("Invalid URL: \(uri)")
+            completion(.failure(DuooomiBleError.transferFailed("Invalid URL: \(uri)")))
+            return
        }

        if url.isFileURL {
-            return try Data(contentsOf: url)
-        } else {
-            let (data, response) = try await URLSession.shared.data(from: url)
+            do {
+                let data = try Data(contentsOf: url)
+                completion(.success(data))
+            } catch {
+                completion(.failure(DuooomiBleError.transferFailed("Failed to read local file: \(error.localizedDescription)")))
+            }
+            return
+        }
+
+        URLSession.shared.dataTask(with: url) { data, response, error in
+            if let error = error {
+                completion(.failure(DuooomiBleError.transferFailed("Download failed: \(error.localizedDescription)")))
+                return
+            }
            guard let httpResponse = response as? HTTPURLResponse,
                  (200...299).contains(httpResponse.statusCode) else {
-                throw DuooomiBleError.transferFailed("Failed to download file: \(uri)")
+                completion(.failure(DuooomiBleError.transferFailed("Failed to download file: \(uri)")))
+                return
            }
-            return data
-        }
+            guard let data = data, !data.isEmpty else {
+                completion(.failure(DuooomiBleError.transferFailed("Empty download response")))
+                return
+            }
+            completion(.success(data))
+        }.resume()
    }
 }
--- a/Sources/DuooomiBleSDK/Services/FirmwareService.swift
+++ b/Sources/DuooomiBleSDK/Services/FirmwareService.swift
@@ -1,7 +1,7 @@
 import Foundation

 /// 固件信息
-public struct FirmwareInfo: Codable, Equatable, Sendable {
+public struct FirmwareInfo: Codable, Equatable {
    public let version: String
    public let fileUrl: String
    public let description: String?
@@ -25,20 +25,30 @@ final class FirmwareService {
        self.config = config
    }

-    func fetchLatest(identifier: String? = nil, status: String? = nil) async throws -> FirmwareInfo? {
+    func fetchLatest(
+        identifier: String? = nil,
+        status: String? = nil,
+        completion: @escaping (Result<FirmwareInfo?, Error>) -> Void
+    ) {
        let id = (identifier ?? config.firmwareIdentifier).trimmingCharacters(in: .whitespacesAndNewlines)
        let st = status ?? config.firmwareStatus
        guard !id.isEmpty else {
-            throw DuooomiBleError.transferFailed("Invalid firmware identifier")
+            completion(.failure(DuooomiBleError.transferFailed("Invalid firmware identifier")))
+            return
        }

-        var comps = URLComponents(url: config.apiHost.appendingPathComponent(latestPath), resolvingAgainstBaseURL: false)!
+        let urlString = "\(config.apiHost)/\(latestPath)"
+        guard var comps = URLComponents(string: urlString) else {
+            completion(.failure(DuooomiBleError.transferFailed("Invalid firmware URL")))
+            return
+        }
        comps.queryItems = [
            URLQueryItem(name: "identifier", value: id),
            URLQueryItem(name: "status", value: st)
        ]
        guard let url = comps.url else {
-            throw DuooomiBleError.transferFailed("Invalid firmware URL")
+            completion(.failure(DuooomiBleError.transferFailed("Invalid firmware URL")))
+            return
        }

        var req = URLRequest(url: url)
@@ -46,15 +56,30 @@ final class FirmwareService {
        req.setValue(config.apiKey, forHTTPHeaderField: "x-api-key")
        req.setValue("application/json", forHTTPHeaderField: "accept")

-        let (data, resp) = try await URLSession.shared.data(for: req)
-        guard let http = resp as? HTTPURLResponse else {
-            throw DuooomiBleError.transferFailed("Invalid response")
-        }
-        guard (200...299).contains(http.statusCode) else {
-            throw DuooomiBleError.transferFailed("HTTP \(http.statusCode)")
-        }
+        URLSession.shared.dataTask(with: req) { data, resp, error in
+            if let error = error {
+                completion(.failure(error))
+                return
+            }
+            guard let http = resp as? HTTPURLResponse else {
+                completion(.failure(DuooomiBleError.transferFailed("Invalid response")))
+                return
+            }
+            guard (200...299).contains(http.statusCode) else {
+                completion(.failure(DuooomiBleError.transferFailed("HTTP \(http.statusCode)")))
+                return
+            }
+            guard let data = data else {
+                completion(.failure(DuooomiBleError.transferFailed("Empty response")))
+                return
+            }

-        let decoded = try JSONDecoder().decode(FirmwareResponse.self, from: data)
-        return decoded.data
+            do {
+                let decoded = try JSONDecoder().decode(FirmwareResponse.self, from: data)
+                completion(.success(decoded.data))
+            } catch {
+                completion(.failure(error))
+            }
+        }.resume()
    }
 }