# DuooomiBleSDK (iOS)

纯原生 Swift BLE SDK，零第三方依赖。

## 集成

```swift
// Package.swift
dependencies: [
    .package(path: "../duooomi-ios-sdk")
]
```

## 初始化

```swift
let sdk = DuooomiBleSDK(config: .init(
    apiKey: "your-api-key"                      // 必填
    // apiHost: URL(...)!,                      // 默认 https://api.mixvideo.bowong.cc
    // cdnHost: "https://cdn.bowong.cc/",       // 默认
    // firmwareIdentifier: "duomi",             // 默认
    // firmwareStatus: "DRAFT"                  // 默认
))
```

## API

### 扫描

| 方法 | 返回 | 说明 |
|------|------|------|
| `scan()` | `Void` | 开始扫描，结果通过 `discoveredDevices` 观察 |
| `stopScan()` | `Void` | 停止扫描 |

### 连接

| 方法 | 返回 | 说明 |
|------|------|------|
| `connect(deviceId: String)` | `DiscoveredDevice` | 连接设备 |
| `disconnect()` | `Void` | 断开连接 |
| `getConnectedDevices()` | `[DiscoveredDevice]` | 获取系统已连接设备 |

### 设备命令

| 方法 | 返回 | 说明 |
|------|------|------|
| `getDeviceInfo()` | `DeviceInfo` | 品牌、容量、电量、型号 |
| `getVersion()` | `VersionInfo` | 固件版本 |
| `bind(userId: String)` | `BindingResponse` | 绑定设备，返回 sn + 文件列表。**绑定后才能查看设备文件** |
| `unbind(userId: String)` | `UnbindResponse` | 解绑设备。**解绑后该账号的设备文件将被删除** |
| `deleteFile(key: String)` | `DeleteFileResponse` | 删除设备上的单个文件 |

### 文件传输

| 方法 | 返回 | 说明 |
|------|------|------|
| `transferMedia(fileUrl: String)` | `Void` | 输入文件 URL（mp4/jpg/png），内部自动完成 ANI 转换 → prepare → 传输。进度通过 `transferProgress` 观察 |

### 固件升级

| 方法 | 返回 | 说明 |
|------|------|------|
| `fetchLatestFirmware(identifier:status:)` | `FirmwareInfo?` | 查询最新固件，nil 表示无可用版本 |
| `upgradeFirmware(fileUrl: String)` | `Void` | OTA 传输固件包到设备 |

```swift
// 1. 查询最新固件
let info = try await sdk.fetchLatestFirmware()
// 2. OTA 升级
if let info {
    try await sdk.upgradeFirmware(fileUrl: info.fileUrl)
}
```

### 可观察状态

| 属性 | 类型 | 说明 |
|------|------|------|
| `btState` | `ConnectionState` | idle / scanning / connecting / connected / disconnecting / disconnected |
| `discoveredDevices` | `[DiscoveredDevice]` | 扫描到的设备列表 |
| `connectedDevice` | `DiscoveredDevice?` | 当前连接设备 |
| `deviceInfo` | `DeviceInfo?` | 设备信息 |
| `version` | `String` | 固件版本 |
| `isActivated` | `Bool` | 是否已绑定 |
| `transferProgress` | `Int` | 传输进度 0-100 |
| `error` | `String?` | 最近错误 |

### 数据类型

```swift
// FirmwareInfo — fetchLatestFirmware 返回
public struct FirmwareInfo {
    let version: String      // 版本号
    let fileUrl: String      // 固件下载地址
    let description: String? // 描述
    let fileSize: String?    // 文件大小（字节字符串）
    let fileMd5: String?     // MD5 校验
    let identifier: String?  // 设备标识
    let status: String?      // DRAFT / PUBLISHED
}

// DeviceInfo — getDeviceInfo 返回
public struct DeviceInfo {
    let name: String         // 设备名
    let brand: String        // 品牌
    let size: String         // 屏幕尺寸
    let powerlevel: Int      // 电量百分比
    let allspace: Int        // 总存储（字节）
    let freespace: Int       // 可用存储（字节）
}

// BindingResponse — bind 返回
public struct BindingResponse {
    let success: Int         // 1=成功
    let sn: String           // 设备序列号
    let contents: [String]   // 设备文件 key 列表
}
```

## Info.plist

```xml
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app needs Bluetooth to communicate with your device</string>
```

## 技术规格

- iOS 16.0+ / Swift 5.9+ / 零依赖
- 公开 API @MainActor，BLE 操作专用串行队列