系统架构

架构概述

蓝牙设备控制系统采用分层架构，支持广播 (Broadcast) 和点对点 (Point-to-Point) 两种通信方式。系统通过适配器模式自动检测运行环境（Web 或 Native），并使用单例模式管理核心服务实例。

┌──────────────────────────────────────────────────────────────────┐
│                        应用层 (App Layer)                         │
│                                                                  │
│   ┌────────────────┐    ┌───────────────────────────────────┐   │
│   │  React 组件     │    │  业务逻辑                          │   │
│   │  useBluetooth  │    │  视频互动 / 远程控制 / 游戏联动     │   │
│   └───────┬────────┘    └──────────────┬────────────────────┘   │
│           │                            │                         │
│           └──────────┬─────────────────┘                         │
│                      ▼                                           │
│   ┌──────────────────────────────────────────────────────────┐  │
│   │               CommandQueueManager                         │  │
│   │               命令队列管理（300ms 节流）                    │  │
│   └──────────────────────┬───────────────────────────────────┘  │
│                          │                                       │
│              ┌───────────┴───────────┐                           │
│              ▼                       ▼                           │
│   ┌──────────────────┐    ┌──────────────────────────────┐      │
│   │ BluetoothService │    │ UnifiedBluetoothManager      │      │
│   │ 广播服务（单例）   │    │ 点对点管理器（单例）           │      │
│   │                  │    │                              │      │
│   │ BLE Advertiser   │    │  ┌─ WebBleManager (Web)     │      │
│   │                  │    │  └─ NativeBleManager (Native)│      │
│   └────────┬─────────┘    └──────────────┬───────────────┘      │
│            │                             │                       │
└────────────┼─────────────────────────────┼───────────────────────┘
             │                             │
      ┌──────▼──────┐              ┌───────▼───────┐
      │  广播设备    │              │  点对点设备    │
      │ (无需配对)   │              │ (需要配对)     │
      └─────────────┘              └───────────────┘

核心组件

BluetoothService（广播服务）

广播设备的核心管理模块，采用单例模式。通过 BLE Advertising 向设备发送控制指令，无需建立连接。

负责 BLE Advertiser 的初始化和生命周期管理
将十六进制命令编码为广播数据包（Manufacturer Data 或 Service UUID）
广播持续 800ms 后自动停止
短广播命令在设备端 2 秒后自动停止；经典模式命令持续执行直到收到显式停止指令

// 单例获取
const bluetoothService = BluetoothService.getInstance()

// 初始化广播服务
await bluetoothService.initialize()

// 发送广播命令
await bluetoothService.broadcastCommand('6db643ce97fe427cf41d7c')

UnifiedBluetoothManager（点对点管理器）

点对点设备的统一蓝牙管理器，采用单例模式和适配器模式。根据运行环境自动选择底层实现。

通过 Capacitor.isNativePlatform() 自动检测环境
Web 环境使用 WebBleManager（基于 Web Bluetooth API）
Native 环境使用 NativeBleManager（基于 Capacitor BLE 插件）
管理设备扫描、连接、鉴权、数据读写的完整生命周期
支持设备重连：将最近连接的设备信息持久化到 localStorage

// 单例获取
const manager = UnifiedBluetoothManager.getInstance()

// 扫描并连接设备
await manager.startScanCallbackByCode(
  modelName,
  { isPrivate, isAuth },
  onDeviceFound,
  onScanComplete
)

// 发送命令
await manager.sendCommand('6db643ce97fe427cf41d7c')

CommandQueueManager（命令队列管理器）

命令发送的节流控制模块，确保蓝牙命令按序发送且不会过载设备。

300ms 节流：相邻命令之间至少间隔 300ms
命令入队后依次发送，避免蓝牙通道拥塞
广播策略管理器（BroadcastStrategyManager）使用 100-200ms 间隔，根据业务模式（滑动、音乐、视频、语音）动态调整

数据流

系统的命令数据流从用户操作到设备执行，经过以下环节：

用户操作（点击按钮 / 滑动滑块）
     │
     ▼
指令生成器（Command Generator）
├── function-command-generator  ← func 功能指令
└── mode-command-generator      ← modes 模式指令
     │
     ▼
CommandQueueManager（300ms 节流）
     │
     ├─── connectionType === 1 ──→ BluetoothService
     │                              └─→ BLE Advertising → 广播设备
     │
     └─── connectionType === 0 ──→ UnifiedBluetoothManager
                                    ├─→ WebBleManager → BLE GATT → 点对点设备
                                    └─→ NativeBleManager → BLE GATT → 点对点设备

设计模式

单例模式 (Singleton)

核心服务均采用单例模式，确保全局唯一实例：

组件	获取方式
`BluetoothService`	`BluetoothService.getInstance()`
`UnifiedBluetoothManager`	`UnifiedBluetoothManager.getInstance()`
`commandQueueManager`	模块级导出的单例实例

适配器模式 (Adapter)

UnifiedBluetoothManager 作为统一接口，内部根据运行环境自动委托给不同的实现：

class UnifiedBluetoothManager {
  private isNative: boolean
  private webManager: typeof webBleManager
  private nativeManager: typeof nativeBleManager

  private constructor() {
    // 自动检测运行环境
    this.isNative = Capacitor.isNativePlatform()
    this.webManager = webBleManager
    this.nativeManager = nativeBleManager
  }

  // 所有公开方法根据环境委托
  public async write(data: Uint8Array, connectedDevice: any): Promise<boolean> {
    if (this.isNative) {
      return this.nativeManager.writeData(data, modelName, isPrivate)
    } else {
      return this.webManager.write(data)
    }
  }
}

通信方式对比

特性	广播 (Broadcast)	点对点 (P2P)
连接方式	BLE Advertising	BLE GATT
是否配对	否	是
通信方向	单向（App -> 设备）	双向
数据量	小（31 字节以内）	大
延迟	低	中
设备反馈	无	有（状态上报、电量等）
认证	无	可选（CRC8 握手）
蓝牙搜索	不需要	需要
核心组件	`BluetoothService`	`UnifiedBluetoothManager`

支持的协议

广播协议

广播设备通过 BLE Advertising 数据包发送控制指令，根据设备型号名称（modelName）自动选择对应协议：

协议	适用设备	命令前缀	命令长度
Default 协议	通用设备	`6db643ce97fe427c`	22 字符
NNG/NONO 协议	型号含 `NNG` 或 `NONO`	`6DB64324F89D427C`	22 字符
MY 协议	型号含 `MY`	`AA0B`	10 字符

点对点协议

协议	Service UUID	适用设备
PrivateProtocol	`0000ff00-0000-1000-8000-00805f9b34fb`	私有协议设备
VxMi Protocol	`6e400001-b5a3-f393-e0a9-e50e24dcca9e`	Vx / Mi / Amorlinkvex
EasyLive Protocol	`fff0`	Easy 系列

On this page