Files

km2023 40538da06d docs: spec & plan for play-mode toggle feature

2026-05-06 10:27:38 +08:00

9.4 KiB

Raw Blame History

播放模式切换功能 — iOS SDK 同步方案

目标：把 expo-duooomi-app(commit ac1520f) 的播放模式切换功能完整同步到 duooomi-ios-sdk，保持协议层一致，让 SDK 调用方用 Swift 风格 API 完成"单播 ⇄ 循环播放"切换。

1. 参考实现（Expo 端）

提交 ac1520f 改动 5 个文件，核心机制：

层	文件	改动
协议类型	`ble/protocol/types.ts`	`DeviceInfoZod` 增 `loop: 0\|1\|undefined`；`BindingRequestZod` 增可选 `loop`
服务层	`ble/services/DeviceInfoService.ts`	新增 `setPlayMode(deviceId, userId, loop)` —— 复用 `BIND_DEVICE`(0x0F) 命令字，带上 `loop` 字段
管理层	`ble/managers/bleManager.ts`	新增 `setPlayMode(loop): Promise<BindingResponse>` —— 复用 `bindDevice` 的 waitable 机制
UI	`app/device.tsx`	设备信息卡片中显示当前模式 + 切换按钮 + loading；切换后调 `getDeviceInfo` 刷新

关键协议事实：

复用 0x0F(BIND_DEVICE) 作命令字，请求 payload 中 loop 字段为可选
响应仍是 BindingResponse（含 type/sn/success/contents）
设备返回的 DeviceInfo 中新增 loop(0=单播 / 1=循环)，旧固件可能没这字段
设备能区分"绑定" vs "切播放模式"是因为 payload 里有无 loop，SDK 必须严格按"无 loop 时省略字段（不能传 null）"编码
必须先 bind 成功才能 setPlayMode：固件设计上设置播放模式的前置条件是设备已和该 userId 完成绑定（success=1）。SDK 通过 isActivated == true 反映此状态；调用 setPlayMode 前必须确保已绑定，否则设备会回 success=0

2. iOS SDK 当前状态

Swift 对应位置
`Sources/DuooomiBleSDK/Models/DeviceInfo.swift`
`Sources/DuooomiBleSDK/Services/DeviceInfoService.swift`（私有 `BindPayload`）
`Sources/DuooomiBleSDK/DuooomiBleSDK.swift`（公开 `bind/unbind`）
`demo/Sources/WrapperTestView.swift`（Device Commands 区）

DuooomiBleSDK.sendAndWait 已支持基于 commandType.rawValue 的请求-响应配对，新增能力可直接复用。

3. 设计

3.1 类型与协议

新增枚举 Sources/DuooomiBleSDK/Models/PlayMode.swift：

public enum PlayMode: Int, Codable {
    case single = 0   // 单播
    case loop = 1     // 循环播放
}

理由：暴露给业务层的 API 用强类型枚举，比 raw Int / UInt8 更安全；rawValue 直接对接协议层的 0/1 整数。

修改 Models/DeviceInfo.swift：

增字段 public let loop: PlayMode?（可选，兼容旧固件）
init(from:) 容错：缺字段或值非 0/1 时返回 nil，不抛错

3.2 协议层

修改 Services/DeviceInfoService.swift：

将私有 BindPayload 替换为可选 loop 字段，并自定义 encode(to:)：

private struct BindPayload: Encodable {
    let type: UInt8
    let userId: String
    let loop: UInt8?  // nil 时编码省略

    enum CodingKeys: String, CodingKey { case type, userId, loop }

    func encode(to encoder: Encoder) throws {
        var c = encoder.container(keyedBy: CodingKeys.self)
        try c.encode(type, forKey: .type)
        try c.encode(userId, forKey: .userId)
        if let loop = loop { try c.encode(loop, forKey: .loop) }
    }
}

关键约束：默认 JSONEncoder 会把 nil 编成 "loop": null，与 Expo 端的 zod.optional() "省略" 行为不一致 —— 设备固件可能据 key 是否存在区分动作，必须用自定义 encode 严格省略 nil。bindDevice / unbindDevice 现有调用因 loop=nil 走相同路径，报文与改动前完全一致。

新增方法：

func setPlayMode(userId: String, loop: PlayMode) throws {
    try protocolService.sendJSON(
        type: .bindDevice,
        payload: BindPayload(
            type: CommandType.bindDevice.rawValue,
            userId: userId,
            loop: UInt8(loop.rawValue)
        )
    )
}

unbindDevice 用独立 UnbindPayload(已有 BindPayload 复用，可保留，或拆出对应 UnbindPayload 二选一 —— 当前选择继续复用 BindPayload(loop:nil)，最小改动)。

3.3 SDK 公开 API

修改 DuooomiBleSDK.swift，在 bind/unbind 之间新增：

/// 切换播放模式（0=单播 / 1=循环播放）
/// 复用 BIND_DEVICE 命令通道；响应类型为 BindingResponse。
/// 成功后自动刷新一次 deviceInfo（与 expo 端行为对齐）。
public func setPlayMode(
    _ mode: PlayMode,
    userId: String,
    completion: @escaping (Result<BindingResponse, Error>) -> Void
) {
    guard ensureConnected(completion: completion) else { return }
    guard isActivated else {
        BleLog.w("setPlayMode called before bind", "Command")
        completion(.failure(DuooomiBleError.bindingFailed("Device not bound; call bind(userId:) first")))
        return
    }
    BleLog.d("Sending setPlayMode (mode=\(mode), userId=\(userId))", "Command")

    sendAndWait(commandType: .bindDevice, completion: { [weak self] result in
        guard let self = self else { return }
        switch result {
        case .failure(let error):
            completion(.failure(error))
        case .success(let data):
            do {
                let resp = try self.decodeResponse(BindingResponse.self, from: data)
                if resp.success != 1 {
                    BleLog.w("setPlayMode failed", "Command")
                    completion(.failure(DuooomiBleError.bindingFailed("Set play mode failed")))
                    return
                }
                BleLog.i("setPlayMode success: mode=\(mode)", "Command")
                // 自动刷新 deviceInfo（含最新 loop 字段）
                self.getDeviceInfo { _ in
                    completion(.success(resp))
                }
            } catch {
                completion(.failure(error))
            }
        }
    }, send: {
        try self.deviceInfoService.setPlayMode(userId: userId, loop: mode)
    })
}

重要约束 — 命令字冲突：bind / unbind / setPlayMode 三者不可并发执行（前两者已有此约束，因都用 sendAndWait 的 opId = "15" / "18"；新方法用 "15"，与 bind 互斥）。这是与 expo 端一致的协议级限制；后续如需并发，须在协议帧 / opId 维度引入区分维度，超出本次同步范围。在 API 文档注释中明确说明。

3.4 Demo 应用

修改 demo/Sources/WrapperTestView.swift，在 bind / unbind 按钮行下加一行：

HStack {
    Button("Single (0)") { runSetPlayMode(.single) }
    Button("Loop (1)")   { runSetPlayMode(.loop) }
    if let mode = viewModel.deviceInfo?.loop {
        Text("now: \(mode == .loop ? "循环" : "单播")")
            .font(.caption)
            .foregroundColor(.secondary)
    }
}
.buttonStyle(.bordered)
.disabled(viewModel.connectedDevice == nil || isBusy)