蓝牙连接生命周期管理

本文档详解 JLOTA 微信小程序中蓝牙连接从创建、MTU 协商、服务发现、断开到异常断连的完整生命周期管理机制，核心实现位于 BTConnect.ConnectImpl 连接管理器。

Purpose and Scope

本页覆盖蓝牙连接生命周期管理的完整端到端机制，包括：

• BTConnect.ConnectImpl 连接管理器的状态机（connecting / connected / disconnected）与内部数据结构
• 连接建立流程：wx.createBLEConnection → MTU 协商 → 服务发现 → notify 使能校验
• 断开与异常断连处理（wx.onBLEConnectionStateChange 监听）
• 连接相关配置（ConnectSettingConfigure：超时、MTU、notify 服务列表）与错误码体系（BluetoothErrorConstant）
• 与连接生命周期联动的数据通道（BleDataHandler 接收、BleSendDataHandler 发送）

以下内容属于其他页面，本页只做交叉引用：

• 扫描与发现设备（wx.startBluetoothDevicesDiscovery 等）——见「设备扫描与发现」相关页面
• OTA 固件升级流程本身（基于已建立连接之上的业务逻辑）——见 OTA 升级相关页面
• 蓝牙适配器初始化与鉴权（jl_auth_2.0.0.js / 适配器状态管理）——见适配器管理相关页面

概述

在微信小程序环境中，BLE（低功耗蓝牙）通信必须严格遵循「初始化适配器 → 扫描设备 → 创建连接 → 发现服务 → 使能通知 → 数据收发 → 断开连接」的生命周期顺序。JLOTA 将这一过程封装在 bluetooth.ts 的 BTConnect 命名空间中，向 OTA 业务层提供统一、幂等、可回调的连接管理接口。

该封装的设计意图（WHY）：

1. 状态收敛：wx.createBLEConnection 是异步、无状态的原生 API，调用方很难判断设备处于「未连接 / 连接中 / 已连接」的哪个阶段。ConnectImpl 用 _connectingDeviceArray 与 _connectedDeviceArray 两个数组显式维护状态，并提供 isConnecting() / isConnected() 查询方法，避免重复连接或误操作。
2. 连接即就绪：对 OTA 业务而言，「连接成功」不应只代表 BLE 链路建立，还应代表 MTU 已协商、目标服务与特征已发现、必需的 notify 特征已使能。ConnectImpl 把这一系列初始化步骤收敛进 connect() 的 success 回调，业务方拿到回调即可安全收发数据。
3. 统一错误语义：微信原生 API 的错误码分散且语义不统一，BluetoothErrorConstant 将其归一为 0~20000 区间的统一错误码（10000 段为微信 API 错误，20000 段为自定义错误），并区分「可重试」与「不可重试」场景。
4. 多回调广播：通过 addConnectCallback / removeConnectCallback 支持多个业务模块（页面、服务层）同时订阅连接状态变化，实现观察者模式。

架构

flowchart TD
    subgraph sg_Business["业务层 (OTA/页面)"]
        OTA["OTA 业务模块"]
        Page["页面 / 自定义组件"]
    end

    subgraph sg_BTConnect["BTConnect 连接管理器 (bluetooth.ts)"]
        IConnect["IConnect 接口"]
        ConnectImpl["ConnectImpl"]
        Config["ConnectSettingConfigure<br/>timeout / mtu / notifyServiceArray"]
        Callbacks["ConnectImplCallback[]<br/>onConnectSuccess / onConnectFailed<br/>onConnectDisconnect / onMTUChange"]
        StateArrays["_connectingDeviceArray<br/>_connectedDeviceArray"]
        InfoMap["_bluetoothDeviceInfoMap<br/>deviceId → BluetoothDeviceInfo(mtu, services)"]
        ConnectImpl --> IConnect
        ConnectImpl --> Config
        ConnectImpl --> Callbacks
        ConnectImpl --> StateArrays
        ConnectImpl --> InfoMap
    end

    subgraph sg_DataChannel["数据通道"]
        BleDataHandler["BleDataHandler<br/>onBLECharacteristicValueChange 分发"]
        BleSendDataHandler["BleSendDataHandler<br/>分包队列发送 + 重试"]
    end

    subgraph sg_WxAPI["微信原生 BLE API"]
        CreateConn["wx.createBLEConnection"]
        CloseConn["wx.closeBLEConnection"]
        StateListener["wx.onBLEConnectionStateChange"]
        MTUListener["wx.onBLEMTUChange"]
        GetServices["wx.getBLEDeviceServices"]
        GetChars["wx.getBLEDeviceCharacteristics"]
        Notify["wx.notifyBLECharacteristicValueChange"]
        WriteValue["wx.writeBLECharacteristicValue"]
    end

    OTA -->|"connect / disconnect / isConnected"| ConnectImpl
    Page -->|"addConnectCallback"| ConnectImpl
    ConnectImpl -->|"状态回调"| OTA
    ConnectImpl --> CreateConn
    ConnectImpl --> CloseConn
    ConnectImpl --> StateListener
    ConnectImpl --> MTUListener
    ConnectImpl --> GetServices
    ConnectImpl --> GetChars
    ConnectImpl --> Notify
    ConnectImpl -->|"BleDataHandler 注册接收回调"| BleDataHandler
    OTA -->|"sendData 分包发送"| BleSendDataHandler
    BleSendDataHandler --> WriteValue
    BleDataHandler -->|"onReceiveData"| OTA

架构说明：

• BTConnect.ConnectImpl（bluetooth.ts#L145）是整个连接生命周期的中枢。构造时立即注册两个全局监听器：_registerConnStatusListener()（连接状态变化）与 _registerMTUChangeListener()（MTU 变化），保证从创建起就不会漏掉系统级断连事件。
• 状态容器是三个私有成员：_connectingDeviceArray（连接中）、_connectedDeviceArray（已连接）、_bluetoothDeviceInfoMap（设备 ID → 服务与 MTU 信息缓存）。isConnecting / isConnected 均按 deviceId 小写不敏感匹配，这是为了避免不同 API 返回的 deviceId 大小写不一致导致误判。
• 数据通道与连接状态解耦但联动：BleDataHandler.init() 注册 wx.onBLECharacteristicValueChange 接收数据；BleSendDataHandler 依赖 ConnectImpl 协商出的 MTU 值（通过 setMtu(deviceId, mtu) 写入 mtuMap）进行分包发送，发送失败自动重试 3 次。

状态模型与生命周期

连接生命周期可抽象为以下状态机。ConnectImpl 的所有方法都以该状态机为前提做幂等保护：

stateDiagram-v2
    [*] --> Idle: 设备被发现
    Idle --> Connecting: connect() 通过幂等检查
    Connecting --> Connected: createBLEConnection 成功<br/>+ MTU 协商成功<br/>+ 服务发现 & notify 使能成功
    Connecting --> Idle: 连接失败 / 超时<br/>onConnectFailed
    Connecting --> Connected: setBLEMTU 失败降级 getBLEMTU<br/>成功仍进入 Connected
    Connected --> Idle: disconnect() / closeBLEConnection<br/>onConnectDisconnect
    Connected --> Idle: 系统级异常断连<br/>onBLEConnectionStateChange(connected=false)
    Connected --> Idle: 初始化阶段失败(MTU/服务)<br/>主动 disconnect + onConnectFailed

三个状态容器

设计要点：连接中状态必须显式记录。wx.createBLEConnection 是异步的，若用户快速重复点击连接按钮，第二次 connect() 调用若不做检查会向微信发送重复连接请求。ConnectImpl 在 connect() 入口依次做两次幂等检查（bluetooth.ts#L180-L191）：

if (this.isConnected(device)) {//已连接
    option.success?.(this.getConnectedDeviceInfo(device))
    return
}
if (this.isConnecting(device)) {//正在连接
    const error: BTBean.BluetoothError = {
        errCode: BTBean.BluetoothErrorConstant.ERROR_IS_CONNECTING,
        errMsg: 'is connecting'
    }
    option.fail?.(error)
    return
}
this._addConnectingDeviceId(device)

设计意图：已连接时直接回放缓存信息（getConnectedDeviceInfo）实现幂等；连接中时以 ERROR_IS_CONNECTING（20003）快速失败，把「重复点击」变成可预期的业务错误而非底层竞态。

回调广播机制

ConnectImplCallback（bluetooth.ts#L125-L136）定义了四个生命周期事件：

• onMTUChange(device, mtu)：MTU 协商完成或运行中变化
• onConnectSuccess(device)：完整初始化链路（链路 + MTU + 服务）成功
• onConnectFailed(device, error)：任一环节失败（携带 BluetoothError）
• onConnectDisconnect(device)：主动断开或异常断连

addConnectCallback / removeConnectCallback 维护回调数组（按引用去重、按引用移除），多个业务模块可独立订阅而不互相干扰。这是典型的观察者模式：连接管理器不关心谁在听，只负责在状态转移点广播事件。

连接核心流程

connect() 的完整控制流如下（对应 bluetooth.ts#L174-L261）：

sequenceDiagram
    participant Biz as OTA 业务层
    participant CI as ConnectImpl
    participant Wx as 微信原生 BLE API
    participant Dev as 蓝牙设备

    Biz->>CI: connect(device, {success, fail})
    CI->>CI: isConnected? / isConnecting? 幂等检查
    CI->>CI: _addConnectingDeviceId(device)
    CI->>Wx: wx.createBLEConnection(deviceId, timeout?)
    alt Android
        Wx-->>CI: success
        CI->>Wx: wx.setBLEMTU(mtu=512)
        alt setBLEMTU 成功
            Wx-->>CI: res.mtu
        else setBLEMTU 失败
            CI->>Wx: wx.getBLEMTU(writeType=undefined)
            Wx-->>CI: res.mtu
        end
    else iOS
        Wx-->>CI: success
        CI->>CI: setTimeout 100ms
        CI->>Wx: wx.getBLEMTU(writeType="writeNoResponse")
        Wx-->>CI: res.mtu
    end
    CI->>CI: _updateDeviceIdMtu + _onMTUChange
    CI->>Wx: wx.getBLEDeviceServices(deviceId)
    Wx-->>CI: services[]
    loop 每个 service
        CI->>Wx: wx.getBLEDeviceCharacteristics(serviceId)
        CI->>Wx: wx.notifyBLECharacteristicValueChange(必需特征)
    end
    CI->>CI: 校验 must-notify 特征全部使能
    CI-->>Biz: success(BluetoothDeviceInfo) + onConnectSuccess
    Note over CI,Dev: 链路就绪，可开始 OTA 数据收发
    CI->>Wx: wx.closeBLEConnection (disconnect)
    Wx-->>CI: onBLEConnectionStateChange(connected=false)
    CI-->>Biz: onConnectDisconnect(device)

流程关键点逐段解析

1. 连接参数构造（L192-L198）：CreateBLEConnectionOption 只设置 deviceId，若 ConnectSettingConfigure.timeout 已配置则附加 timeout 字段（单位毫秒，微信侧用于连接超时控制）。

2. 平台差异化 MTU 协商（L234-L252）：这是全流程中平台兼容性最集中的地方。

• Android：连接建立后先尝试 wx.setBLEMTU({mtu: 512}) 主动协商大 MTU；失败时降级调用 wx.getBLEMTU() 读取系统实际 MTU。
• iOS：微信 iOS 端不支持 setBLEMTU，因此 setTimeout(100ms) 延迟后直接 getBLEMTU()，并设置 writeType: "writeNoResponse"——iOS 的 MTU 查询需要配合无响应写类型才能返回有效值。

3. initBluetooth（L199-L212）：MTU 获取成功后先 _updateDeviceIdMtu 更新缓存并触发 _onMTUChange，然后进入 _getBLEDeviceServices 服务发现。服务发现失败（如设备未实现预期服务）时调用 this.disconnect(device) 回滚连接，并依次触发 option.fail 与 _onConnectFailed——失败路径必须主动断开，否则会出现「链路已建、初始化未完成」的悬挂状态。

4. 服务发现与 notify 使能（L343-L401）：_getBLEDeviceServices 遍历设备所有服务，只对 _connectConfigure.notifyServiceArray 中配置了 UUID 的服务调用 _getBLEDeviceCharacteristics 获取特征，并对配置匹配的特征执行 _notifyBLECharacteristicValueChange 使能 notify。之后做一次必须特征校验：配置中标记 isNecessary == true 的特征若未成功使能，整个连接判定失败（ERROR_NOTIFY_NECESSRY_CHARATERISTIC_FAIL，20002）。这保证了 OTA 依赖的升级特征（通常必须 notify）在连接成功时一定可用。

5. 连接失败监听（L253-L259）：wx.createBLEConnection 的 fail 回调中，只有 isConnecting(device) 为真时才上报失败——因为连接成功后、初始化阶段的失败由 initBluetooth 的 catch 分支处理，二者不能重复上报。

使用示例

以下示例均提取自仓库实际源码，展示连接生命周期 API 的典型用法。

示例一：配置连接参数并订阅生命周期回调

业务层在使用前需要设置 ConnectSettingConfigure（超时、MTU、需要使能 notify 的服务/特征清单），并通过 addConnectCallback 订阅状态事件：

const connectConfig = new BTConnect.ConnectSettingConfigure()
connectConfig.timeout = 5000                       // 连接超时 5 秒
connectConfig.mtu = 512                            // 目标 MTU（23~512）
connectConfig.notifyServiceArray = [otaService]    // 需要使能 notify 的服务

connectImpl.setConnectSettingConfigure(connectConfig)
connectImpl.addConnectCallback({
    onConnectSuccess: (device) => { /* 链路就绪，开始 OTA */ },
    onConnectFailed: (device, error) => { /* 按 error.errCode 分类提示 */ },
    onConnectDisconnect: (device) => { /* 提示用户重新连接 */ },
    onMTUChange: (device, mtu) => { /* 更新发送分包大小 */ }
})

（类型与配置结构定义见 bluetooth.ts#L86-L136）

示例二：发起连接（幂等 + 错误分类）

connectImpl.connect({
    device: device,                                // 扫描得到的 BluetoothDevice
    success: (info) => {
        // info.mtu 与 info.bluetoothServices 已就绪，可安全收发
        BleSendDataHandler.setMtu(device.deviceId, info.mtu)
    },
    fail: (e) => {
        switch (e.errCode) {
            case BTBean.BluetoothErrorConstant.ERROR_IS_CONNECTING:
                // 20003 正在连接，忽略或提示"连接中"
                break
            case BTBean.BluetoothErrorConstant.ERROR_INIT_MTU_FAIL:
                // 20000 MTU 协商失败
                break
            case BTBean.BluetoothErrorConstant.ERROR_NOTIFY_NECESSRY_CHARATERISTIC_FAIL:
                // 20002 必需 notify 特征使能失败
                break
            default:
                // 10000 段微信 API 错误
                break
        }
    }
})

（connect 幂等检查与失败回调实现见 bluetooth.ts#L174-L191、bluetooth.ts#L253-L260）

示例三：断开连接与异常断连处理

// 主动断开
connectImpl.disconnect(device)   // 内部调用 wx.closeBLEConnection({deviceId})

// 异常断连由构造时注册的全局监听兜底：
// _registerConnStatusListener 监听 wx.onBLEConnectionStateChange，
// 当 connected == false 且设备在已连接列表中时触发 onConnectDisconnect

（实现见 bluetooth.ts#L262-L271 与 bluetooth.ts#L312-L328）

示例四：数据通道与 MTU 联动（发送分包）

连接建立后，BleSendDataHandler 依据 ConnectImpl 协商的 MTU 自动分包发送，失败自动重试 3 次：

// 依据 MTU 计算真实负载长度：>512 时取 509，否则取 mtu-3（默认 20）
const mtu = this.mtuMap.get(deviceId)
let realMTU = 20;
if (mtu != undefined && mtu > 512) {
    realMTU = 509
} else {
    if (mtu != undefined) realMTU = mtu - 3
}
// 按 realMTU 切块后依次入队发送，失败重发三次
wx.writeBLECharacteristicValue({
    deviceId: sendDataTask.deviceId,
    serviceId: sendDataTask.serviceId.toLocaleUpperCase(),
    characteristicId: sendDataTask.characteristicId.toLocaleUpperCase(),
    value: sendDataTask.data.buffer,
    fail: (err) => { /* retryNum <= 3 时重发 */ }
})

（分包与重试实现见 ble-data-handler.ts#L57-L120）

配置选项

配置入口为 setConnectSettingConfigure(config)（bluetooth.ts#L157-L160），配置类定义见 bluetooth.ts#L86-L120。

API 参考

connect(option): void

发起连接，幂等。成功回调携带已就绪的设备信息（MTU + 服务）。

参数： option.device（BluetoothDevice，必需）；option.success?: (info: BluetoothDeviceInfo | undefined) => void；option.fail?: (e: BluetoothError) => void

行为：

• 已连接 → 直接 success(getConnectedDeviceInfo(device))，不重复连接
• 连接中 → fail(ERROR_IS_CONNECTING)（20003）
• 链路成功但 MTU/服务初始化失败 → 先 disconnect(device) 再 fail

disconnect(device): void

调用 wx.closeBLEConnection({deviceId}) 主动断开。断开事件经 _registerConnStatusListener 统一转换为 onConnectDisconnect 回调。

isConnecting(device): boolean / isConnected(device): boolean

按 deviceId（小写不敏感）在 _connectingDeviceArray / _connectedDeviceArray 中线性查找。用于幂等判断与 UI 状态展示。

getConnectedDevice(): Array<BluetoothDevice> | null

返回当前已连接设备数组（_connectedDeviceArray）。

getMTU(device): number | undefined

仅当设备已连接时从 _bluetoothDeviceInfoMap 返回缓存 MTU，否则返回 undefined。

setConnectSettingConfigure(config): void

整体替换连接配置对象（引用赋值），下次 connect() 生效。

addConnectCallback(callback) / removeConnectCallback(callback)

按引用维护 ConnectImplCallback 数组：添加前去重，移除时按 index 删除。

BleDataHandler / BleSendDataHandler

• BleDataHandler.init()：注册 wx.onBLECharacteristicValueChange，将收到的数据广播给所有 BleDataCallback.onReceiveData
• BleSendDataHandler.setMtu(deviceId, mtu)：由连接层写入协商后的 MTU
• BleSendDataHandler.sendData(deviceId, serviceId, characteristicId, data): boolean：按 MTU 分包入队、串行发送、失败重试 3 次

失败模式、边界情况与并发

错误码体系

BluetoothErrorConstant（bluetooth.ts#L37-L58）将错误归为三段：

连接建立阶段的失败路径

1. wx.createBLEConnection 直接失败（L253-L259）：仅当 isConnecting(device) 为真时上报 option.fail + _onConnectFailed，防止与初始化阶段失败重复上报。
2. MTU 协商失败（L218-L227）：getBLEMTU 失败 → 主动 disconnect(device) 回滚 → 上报 ERROR_INIT_MTU_FAIL（20000）。Android 的 setBLEMTU 失败会静默降级到 getBLEMTU，不会直接判失败——因为部分 Android 设备协商失败但默认 MTU 仍可用。
3. 服务发现失败（L207-L211）：_getBLEDeviceServices 抛错（无服务 ERROR_NO_SERVICE、获取失败 ERROR_GET_SERVICE_FAIL、必需特征未使能 ERROR_NOTIFY_NECESSRY_CHARATERISTIC_FAIL）→ disconnect(device) 回滚 → option.fail + _onConnectFailed。
4. 必要特征校验（L380-L392）：配置中 isNecessary 特征必须全部出现在已使能 notify 的集合中，否则连接失败。这是防止「连接成功但 OTA 无法工作」的关键防线。

异常断连（运行期）

_registerConnStatusListener（L312-L328）监听 wx.onBLEConnectionStateChange：当 connected == false 且设备确实在 _connectedDeviceArray 中时触发 onConnectDisconnect。先查 isConnected 再广播的设计避免了对「从未连上的设备」产生误报。

源码注释指出了两个已知边界：

• 三星部分机型主动断开时可能不回调 onBLEConnectionStateChange（L264 注释），因此 disconnect() 不依赖回调做状态清理，业务层应自行处理 UI 状态。
• BleDataHandler.onConnectStateChange 回调已标记为废弃（ble-data-handler.ts#L51-L52），连接状态事件统一走 ConnectImplCallback。

并发与竞态

• 重复 connect 竞态：通过「已连接回放 + 连接中快速失败」双保险消除，_connectingDeviceArray 是唯一权威的连接中判定来源。
• deviceId 大小写不一致：isConnecting / isConnected / 服务匹配均做 toLowerCase() 归一（L291、L304、L363、L422），规避不同 API 返回 UUID 大小写不一致导致的状态误判。
• 回调广播遍历：BleDataHandler._doAction 与回调数组的增删不在同一临界区内，若业务回调中同步增删回调可能影响遍历结果——这是观察者模式的经典注意点，业务侧应避免在回调中直接修改订阅。
• 发送队列：BleSendDataHandler 以 sendInfoArray 队列串行发送（队首任务完成后回调出队），天然避免 writeBLECharacteristicValue 并发写冲突；重试计数 retryNum 为模块级变量，源码注释亦标记「todo 后续优化：阻塞式发送、区分设备」，多设备并发发送时重试计数会互相影响。

性能与运维注意事项

• MTU 是性能核心：默认 20 字节（未协商）与协商后 509 字节（mtu > 512 时取 509）相差约 25 倍吞吐。OTA 大数据包依赖 Android setBLEMTU(512) 与 iOS getBLEMTU 成功，建议上线前在目标机型上验证 MTU 协商结果。
• 分包发送串行化：每次 wx.writeBLECharacteristicValue 携带一包（≤ realMTU），写完才发下一包，避免微信侧写缓冲区溢出；失败重试 3 次。
• 日志分级：logv/logd/logi/logw/loge 贯穿连接流程（如「蓝牙连接状态变化」「收到数据 serviceId uuid:」），线上问题排查可直接按 bluetooth.ts / ble-data-handler.ts 前缀过滤日志。
• 超时配置：ConnectSettingConfigure.timeout 未设置时使用微信默认值；对弱网/远距离场景建议显式设置超时并配合 onConnectFailed 提示用户重试。
• 断连恢复：onConnectDisconnect 是业务侧重新走「扫描 → 连接」流程的唯一信号，页面应在此回调中清理 OTA 会话并引导用户重连（源码中该回调仅做广播，不自动重连——重连策略留给业务层，避免在弱信号下无限重连消耗电量）。

扩展点

1. 新增业务服务/特征：在 ConnectSettingConfigure.notifyServiceArray 中添加 BluetoothService（UUID + BluetoothCharacteristic[]），连接初始化阶段会自动发现并使能 notify；需要强保证的特征置 isNecessary = true，使能失败即连接失败。无需修改 ConnectImpl 核心代码——配置驱动是主要扩展方式。
2. 订阅更多生命周期事件：实现 ConnectImplCallback 的四个可选回调（onMTUChange / onConnectSuccess / onConnectFailed / onConnectDisconnect），通过 addConnectCallback 挂载；不用的回调可省略（全部可选）。
3. 自定义错误处理策略：BluetoothError 携带统一 errCode，业务层可在 fail 回调中按错误码实现重试、降级或提示逻辑；例如 ERROR_IS_CONNECTING 可忽略、ERROR_CONNECTION_FAIL 可自动重试、ERROR_NO_SERVICE 需提示固件不匹配。
4. 平台差异化逻辑：ConnectImpl 构造时接收 platform 参数（'android' / 其他），MTU 协商与 writeType 已按平台分流；未来若需适配新的平台差异（如鸿蒙），可在此分支扩展。

测试

仓库中与连接生命周期直接对应的测试用例主要体现为微信原生 API 的类型契约（typings/types/wx/lib.wx.api.d.ts 中 CreateBLEConnectionOption、CloseBLEConnectionOption、OnBLEConnectionStateChangeCallbackResult 等接口定义），以及 BleSendDataHandler 分包计算逻辑的可验证单元（realMTU 分支：未设置 → 20、>512 → 509、否则 mtu - 3）。连接流程为微信运行时行为，建议通过真机 + 微信开发者工具 BLE 调试面板验证以下场景：首次连接成功、重复连接幂等、连接超时、断连后重连、MTU 协商失败降级、必需特征缺失导致连接失败。

相关链接

• 连接管理器核心实现：bluetooth.ts
• 数据接收分发与分包发送：ble-data-handler.ts
• 微信 BLE API 类型定义：lib.wx.api.d.ts
• 工具函数（ab2hex 等）：util.ts
• OTA 升级协议（基于已建立连接之上）：libs/jl_ota_2.1.1.js、libs/jl_rcsp_ota_2.1.1.js
• 鉴权与适配器初始化：libs/jl_auth_2.0.0.js