BlueLock 蓝牙插件使用流程

本文档描述 BlueLock 蓝牙模块通信插件（bluelock-plugin）在小程序中的完整接入与使用流程。插件负责 BLE 扫描、连接、指令组包/解包；账号鉴权、门锁绑定、密钥管理需配合 BlueLock 开放平台 HTTP 接口完成。

一、前置准备

1.1 环境要求

项目	要求
小程序主体	企业账号（插件一般仅支持企业主体）
插件 AppID	`wx8564070a5117797d`
插件别名	`bluelock-plugin`
建议微信基础库	≥ 2.21.4
建议微信客户端	≥ 8.0.2

1.2 申请插件权限

登录微信公众平台小程序后台

左下角头像 → 账号设置 → 第三方设置 → 插件管理

添加插件 → 搜索 AppID wx8564070a5117797d → 提交申请

等待审核通过

1.3 在宿主小程序中引入插件

审核通过后，在 app.json 中配置：

{
  "plugins": {
    "bluelock-plugin": {
      "version": "dev",
      "provider": "wx8564070a5117797d"
    }
  },
  "permission": {
    "scope.bluetooth": {
      "desc": "用于扫描和连接智能门锁、网关设备"
    },
    "scope.userLocation": {
      "desc": "Android 扫描蓝牙设备需要位置权限"
    }
  }
}

正式发布时将 version 改为插件后台申请的正式版本号。

1.4 在页面中引用插件

TypeScript 类型声明见仓库 typings/exports/index.d.ts。

二、整体架构

┌─────────────────┐     HTTP API      ┌──────────────────┐
│   小程序页面     │ ◄──────────────► │  BlueLock 开放平台  │
│  (业务逻辑)      │   登录/绑定/上报 │       
└────────┬────────┘                   └──────────────────┘
         │ requirePlugin
         ▼
┌─────────────────┐     BLE GATT      ┌──────────────────┐
│  bluelock-plugin   │ ◄──────────────► │   智能门锁        │
│  (蓝牙通信层)    │   扫描/连接/指令│                │
└─────────────────┘                   └──────────────────┘

职责划分：

插件：蓝牙适配器管理、设备扫描、GATT 连接、指令组包/解包、多包回传会话

后端：用户登录、门锁绑定/解绑、密钥下发（serverKeys / lockKeys）、操作记录上报

小程序页面：串联登录 → 初始化 → 蓝牙操作 → 结果上报

三、标准使用流程（总览）

登录账号
   │
   ├─► 【新锁】扫描 → 蓝牙绑定 → HTTP 绑定 → initLock
   │
   └─► 【已绑锁】HTTP 获取门锁详情 → initLock
              │
              ├─► 开锁 / 关锁 / 常开
              ├─► 用户管理（密码/卡/指纹/人脸/掌纹）
              ├─► 读取/下发门锁设置
              ├─► 读取操作记录
              ├─► 解绑
              └─► 离线密码生成

四、详细流程

4.1 用户登录（业务层，插件不涉及）

调用开放平台登录接口，获取 token、user.id、user.virtualId

将登录态缓存到本地（Demo 使用 authSession）

后续所有蓝牙操作都需要 userId 和 host（即 virtualId）。

4.2 绑定新门锁

适用场景：用户首次添加一把未绑定的门锁。

步骤 1：扫描门锁

扫描默认超时 15 秒。iOS 上 deviceId 为 UUID，业务侧请用 deviceAddress（MAC）标识设备。

扫描结果关键字段：

字段	说明
`deviceId`	Android 通常为 MAC；iOS 为微信分配的 UUID
`deviceAddress`	门锁 MAC 地址
`bindStatus`	是否已绑定
`rssi`	信号强度

步骤 3：查询设备 SN（后端）

选中未绑定设备后，通过 MAC 调用后端接口查询 SN 码（Demo：getByMacAddress）。

步骤 4：蓝牙绑定

绑定成功后，response 包含：

key → 即 serverKeys

timesTamp → 时间戳

responseHex → 完整回包 hex，需上报后端

步骤 5：HTTP 绑定（后端）

将蓝牙回包提交后端完成云端绑定：

步骤 6：初始化门锁会话

4.3 已绑定门锁 — 初始化

适用场景：用户从门锁列表进入详情页，准备进行开锁等操作。

步骤 1：获取门锁详情（后端）

步骤 2：initLock

字段	说明
`host` / `slave` / `userId` / `deviceKey`	鉴权必填
`deviceId`	可选，已知微信 deviceId 时缓存
`disconnectAfterCommand`	可选，默认 `true`；设为 `false` 时指令完成后不断开 BLE

步骤 3：页面销毁时清理

4.4 开锁 / 关锁 / 常开

前提：已完成 initLock。

扫描、连接、发指令时插件会在内部自动打开蓝牙适配器，无需手动调用会话方法。
默认每条指令结束后会断开 BLE 连接（不关适配器）；需连续操作时可在 initLock 设 disconnectAfterCommand: false，离开页面时再 disconnectBleDevice。

步骤 1：注册门锁上报监听

开锁后自动回锁的 0300 可能在指令 Promise 结束后才上报，需通过此监听捕获。

步骤 2：执行操作

步骤 3：上报操作结果（后端）

回包说明

commandType	含义
`0301`	开锁成功
`0400`	关锁 / 操作关锁应答
`0300`	门锁状态上报：已关锁

4.5 用户管理

前提：已完成 initLock。

操作	插件接口	说明
添加用户	`addLockUserBleDevice`	密码(05)/卡(08)/指纹(02)/人脸(f1)/掌纹(f7)
修改用户	`updateLockUserBleDevice`	修改有效期、权限等
删除用户	`deleteLockUserBleDevice`	按用户类型 + 编号删除
读取用户列表	`getLockUserListBleDevice`	多包 session，结束包 `1703`

录入类用户（指纹/卡/人脸/掌纹）

自动进入 session 模式：

0005 → 录入中（可通过 onProgress / onUserStatus 获取进度）

0000 → 录入完成

蓝牙操作完成后，需将回包上报后端同步云端用户数据。

4.6 门锁设置

操作	插件接口	指令
读取设置	`getLockSettingBleDevice`	`12`
下发设置	`sendLockSettingBleDevice`	`13`

4.7 读取操作记录

读取完成后，将每条记录上报后端（Demo：receiveLockDoorRecord）。

4.8 解绑门锁

4.9 离线密码

五、页面生命周期最佳实践

门锁详情页额外处理：

扫描页额外处理：

六、错误处理

插件提供错误类型判断工具：

七、组包调试

八、常见问题

BLE 超时默认值

场景	默认超时	配置方式
扫描设备列表	15 秒	`startScanBleDevice({ timeout })`
iOS 按 MAC 解析 UUID	5 秒	`connectBleDevice` / 指令参数中的 `scanTimeout`
BLE 连接（含重试）	10 秒	`connectTimeout` 或 `connectOptions.timeout`
等待单次回包	8 秒	`responseTimeout`
多包 session 总时长	120 秒	`sessionTimeout`

网关在线时小程序蓝牙连不上门锁

现象：能扫到门锁，但 connectBleDevice / unlockBleDevice 连接超时或反复失败；重启微信、重启小程序无效；网关断电后恢复正常。

原因：多数智能门锁 BLE 同一时间只接受一个 Central 连接。网关为远程开锁、状态同步等会长期保持与门锁的 GATT 连接，此时微信小程序无法再直连同一把锁。这与「小程序内多个插件抢蓝牙 API」无关，也与「强杀微信后连接未释放」是不同问题——本质是锁端连接名额被网关占用。

验证：临时断开或关闭网关，等待 3～10 秒后再用小程序连接。

建议：

场景	做法
网关在线、需远程能力	走云端 / 网关 HTTP 接口，勿与小程序 BLE 直连抢锁
必须小程序蓝牙操作（绑定、录入指纹等）	先让网关释放连接，或临时下线/断电网关
产品长期方案	网关按需连接；或云端协调「小程序 BLE 前通知网关断开」

九、Demo 页面索引

本仓库即为参考 Demo，主要页面与功能对应关系：

页面路径	功能
`pages/login/login`	用户登录
`pages/scan/scan`	扫描门锁、蓝牙绑定
`pages/lockDetail/lockDetail`	加载详情、`initLock`
`pages/unlockTest/unlockTest`	各 BLE 能力入口
`pages/lockBle/operation/operation`	开锁/关锁/常开
`pages/lockBle/unbind/unbind`	解绑
`pages/lockBle/user/user`	用户管理入口
`pages/lockBle/addUser/addUser`	添加用户
`pages/lockBle/settingView/settingView`	读设置 + 显示服务端设置
`pages/lockBle/sendSetting/sendSetting`	下发设置
`pages/lockBle/operationRecord/operationRecord`	读取操作记录
`pages/offlinePassword/offlinePassword`	离线密码生成

微信小程序插件

BlueLock 蓝牙插件使用流程#

一、前置准备#

1.1 环境要求#

1.2 申请插件权限#

1.3 在宿主小程序中引入插件#

1.4 在页面中引用插件#

二、整体架构#

三、标准使用流程（总览）#

四、详细流程#

4.1 用户登录（业务层，插件不涉及）#

4.2 绑定新门锁#

步骤 1：扫描门锁#

步骤 3：查询设备 SN（后端）#

步骤 4：蓝牙绑定#

步骤 5：HTTP 绑定（后端）#

步骤 6：初始化门锁会话#

4.3 已绑定门锁 — 初始化#

步骤 1：获取门锁详情（后端）#

步骤 2：initLock#

步骤 3：页面销毁时清理#

4.4 开锁 / 关锁 / 常开#

步骤 1：注册门锁上报监听#

步骤 2：执行操作#

步骤 3：上报操作结果（后端）#

回包说明#

4.5 用户管理#

录入类用户（指纹/卡/人脸/掌纹）#

4.6 门锁设置#

4.7 读取操作记录#

4.8 解绑门锁#

4.9 离线密码#

五、页面生命周期最佳实践#

六、错误处理#

七、组包调试#

八、常见问题#

BLE 超时默认值#

网关在线时小程序蓝牙连不上门锁#

九、Demo 页面索引#