微信小程序蓝牙 SDK
小程序 SDK 由深圳维亿魄科技有限公司(以下简称"本公司")开发,专门为本公司智能穿戴类产品提供微信小程序蓝牙控制开发平台,覆盖设备扫描、连接、健康数据读取与设备控制等能力。
本仓库为公版 SDK,使用范围限于本公司智能穿戴产品;设备兼容性确认及定制需求,请联系本公司商务对接。
| 类别 | 范围 | 备注 |
|---|---|---|
| 微信客户端 | Android,iOS,HarmonyOS 4.0,HarmonyOS Next | 支持 BLE 功能 |
| 开发平台 | 微信开发者工具 | 建议使用最新版本开发 |
注意:SDK 基于小程序原生开发,支持在原生 + TypeScript 项目中使用。由于 mpvue、uni-app、Taro 等框架会对代码进行二次编译与运行时改写,可能破坏 SDK 原有的模块结构与执行上下文,因此不推荐在此类框架中接入 SDK。SDK 仅支持真机调试,微信开发者工具模拟器不支持蓝牙。
| 模块 | 职责 |
|---|---|
libs/vp_sdk |
核心 SDK:扫描、连接、订阅监听、协议解析、健康数据与设备控制 |
libs/jieli_sdk |
杰理(Jieli)能力:OTA 升级、表盘传输等 |
表盘传输、OTA 等功能目前只支持杰里类型设备,其他设备暂不支持。
- 手机系统蓝牙已开启;
- Android 扫描设备需开启系统定位服务,并授予微信蓝牙/位置权限。
重要提示: 小程序正式版如需使用「网络表盘」或 SDK 中的付费功能,必须在微信公众平台后台配置域名
https://www.vphband.com,否则相关功能不可用。
同一组织下提供两套蓝牙 SDK,均可用于开发微信小程序;此外还可选择小程序插件方式接入(见 1.5 节)。
| 能力 | 当前仓库(小程序 SDK) | UniApp SDK |
|---|---|---|
| 微信小程序 | 支持,适用于原生小程序或微信官方 Donut 跨端方案 | 支持,通过 uni-app 编译到微信小程序 |
| Android App | 不支持 | 支持,uni-app 原生打包,性能接近原生 |
| iOS App | 不支持 | 支持,uni-app 原生打包,性能接近原生 |
| 开发方式 | 微信小程序原生 + TypeScript | Vue / uni-app(HBuilderX) |
| 适用场景 | 项目仅面向微信小程序 | 一套代码同时覆盖小程序、Android、iOS |
如何选择:
- 只开发微信小程序,或采用微信官方 Donut 跨端方案:选择当前小程序 SDK,接入路径更直接。
- 需要同时交付 Android/iOS App,或已有 uni-app 技术栈:选择 UniApp SDK,一套代码覆盖多端。
- 不希望自行维护 SDK 源码、希望多个小程序共用同一套蓝牙能力:可选择小程序插件方式接入(见 1.5 节)。
- 不要在当前小程序 SDK 项目中混用 uni-app、Taro、mpvue 等框架,否则可能破坏 SDK 模块结构(见 1.1 节)。
除直接引入 SDK 源码外,本公司同时提供微信小程序插件(veepoo-plugin)。客户可在自己的原生小程序中以插件方式接入,无需拷贝 SDK 源码,便于多项目复用与统一升级。
| 能力 | 小程序插件 |
|---|---|
| 接入方式 | 微信公众平台添加插件后,通过 requirePlugin 引入 |
| 能力范围 | 与当前小程序 SDK 一致:扫描、连接、订阅监听、协议解析、健康数据与设备控制 |
| 源码维护 | 无需维护 SDK 源码,插件版本统一升级 |
| 适用场景 | 多个小程序共用同一套蓝牙能力,或希望降低 SDK 维护成本 |
const { veepooBle, veepooFeature, veepooLogger, veepooDataCollect } = requirePlugin('veepoo-plugin')
veepooBle.veepooWeiXinSDKStartScanDeviceAndReceiveScanningDevice(res => {
console.log('扫描到设备:', res)
})调用方式与当前小程序 SDK 一致,接口说明请参阅《Veepoo微信插件使用文档》。
插件接入需先完成插件申请、授权与 AppID 绑定等流程。如需接入插件开发,请联系本公司商务对接。
将 libs/vp_sdk 下的 index.js、index.d.ts 放入小程序项目(demo 中对应 code/demo/WeiXinSDKTSDemo/miniprogram/miniprogram_dist/),然后引入:
import { veepooBle, veepooFeature, veepooLogger, veepooDataCollect } from './miniprogram_dist/index'引入路径按 SDK 文件在项目中的实际位置调整。
标准顺序为:扫描设备 >> 连接设备 >> 注册全局监听 >> 密钥认证 >> 调用功能接口。下面是从扫描到读取电量的最小示例(具体实现请参考demo):
import { veepooBle, veepooFeature } from './miniprogram_dist/index'
Page({
onUnload() {
// 离开页面时停止扫描,释放资源
veepooBle.veepooWeiXinSDKStopSearchBleManager(() => {})
},
start() {
// 1. 注册全局监听(必须在认证前注册)
veepooBle.veepooWeiXinSDKNotifyMonitorValueChange(res => {
switch (res.type) {
case 1: // 密钥认证结果
if (res.content?.VPDevicepassword === 'successfulVerification') {
this.readBattery() // 认证通过后再调用功能接口
}
break
case 2: // 电池电量
console.log('电量:', res.content)
break
}
})
// 2. 扫描设备(每发现一个设备回调一次)
veepooBle.veepooWeiXinSDKStartScanDeviceAndReceiveScanningDevice(res => {
console.log('扫描到设备:', res)
// 选中目标设备后调用 connect(res.deviceId)
})
},
// 3. 连接设备(deviceId 为扫描到的设备标识)
connect(deviceId) {
veepooBle.veepooWeiXinSDKStopSearchBleManager(() => {})
veepooBle.veepooWeiXinSDKBleConnectionServicesCharacteristicsNotifyManager({ deviceId }, () => {
// 4. 连接成功后进行密钥认证
veepooFeature.veepooBlePasswordCheckManager()
})
},
// 5. 认证通过后读取电量,结果仍从全局监听 type=2 返回
readBattery() {
veepooFeature.veepooReadElectricQuantityManager()
},
})- 功能接口采用「发指令 + 全局监听」模式:接口调用本身不返回业务数据,结果统一从
veepooWeiXinSDKNotifyMonitorValueChange回调,通过res.type区分功能。 - 全局监听必须在密钥认证前注册,且认证通过后才能调用数据类、控制类功能接口。
- 默认流程无需调用
init;仅在自定义蓝牙传输或复用已有连接时需要,详见使用文档第 6 节。 - 使用 OTA、表盘传输时,还需按使用文档 9.24 节引入
libs/jieli_sdk。
完整初始化、接口参数与回调结构,请阅读 VeepooWeiXinSDK使用文档。其中第 3 节「数据接收模型」为对接必读。
| 分类 | 主要能力 | 参考章节 |
|---|---|---|
| 设备连接 | 扫描、连接、重连、断开、连接状态监听、获取已连接设备 | 文档第 7 章 |
| 基础信息 | 密钥认证、电池电量、个人信息同步、时间同步、单位/语言设置 | 9.1 ~ 9.3、9.9、9.22、9.29 |
| 健康数据 | 精准睡眠、日常数据、体温、计步、心率、血氧、血压、血糖、血液成分、身体成分、ECG、HRV/洛伦兹、压力、微体检、手动测量、B3 自动测量、女性经期 | 9.4 ~ 9.7、9.15 ~ 9.18、9.20 ~ 9.21、9.27 ~ 9.28、9.30 ~ 9.34 |
| 提醒与通知 | 天气、联系人/SOS、文字闹钟、消息推送(ANCS/Android 编码)、久坐/健康提醒、拍照、抬手亮屏、屏幕亮度 | 9.8、9.10 ~ 9.12、9.19、9.25 |
| 运动 | 运动模式、运动数据、运动控制、世界时钟 | 9.13、9.35、9.36 |
| 表盘与 OTA | 自定义/网络表盘、UI 风格、杰理 OTA 与表盘传输(仅杰理设备) | 9.24、9.26 |
| 定制项目 | JH58、ZT163、YM28PRO、4G 服务等 | 文档附录 A |
| 日志 | 控制 SDK 内部日志输出,便于调试 | 文档第 8 章、11章 |
各功能的调用方式、参数与返回结构见使用文档对应章节,demo 中也提供了主要功能的示例页面。
使用微信开发者工具导入 code/demo/WeiXinSDKTSDemo,填入 AppID 后使用真机预览调试。主要功能均提供示例页面,开发具体功能前建议先参考 demo。
├── code
│ └── demo
│ └── WeiXinSDKTSDemo # 演示小程序
│ └── miniprogram
│ └── miniprogram_dist # 可直接运行的 SDK 产物
├── docs
│ ├── txt # hrv、睡眠、相似度文本
│ │ ├── hrv_font_tips.js
│ │ ├── similarity_tips.js
│ │ └── sleep_text.txt
│ ├── VeepooWeiXinSDK使用文档.md
│ └── 照片表盘传输简易流程图.pdf
├── libs # 核心库
│ ├── jieli_sdk # 杰理 OTA/表盘 TS 源码
│ └── vp_sdk # SDK (index.js)
├── LICENSE # Apache-2.0
└── README.md
| 问题 | 排查方向 |
|---|---|
| 搜不到设备 | 确认使用真机、蓝牙已开启;Android 需开启系统定位并授予微信位置权限 |
| 密钥认证不通过 | 确认全局监听在认证前注册,且设备已成功连接 |
| 调用接口后没有数据 | 功能结果从全局监听 res.type 返回,不是接口返回值 |
| 网络表盘或付费功能不可用 | 正式版需配置域名 https://www.vphband.com |
| OTA、表盘传输不可用 | 该能力仅支持杰理类型设备,且需引入 libs/jieli_sdk |
| 页面退出后仍占用蓝牙资源 | 离开页面时调用 veepooWeiXinSDKStopSearchBleManager,必要时断开连接 |
| 项目 | 版本 | 发布日期 |
|---|---|---|
| WeiXin_SDK | V1.3.0 | 2026/11/17 |
| VeepooWeiXinSDK 使用文档 | V2.2.0 | 2026/11/17 |
WeiXin_SDK:
| SDK版本 | 日期 | 编辑 | 修改内容 |
|---|---|---|---|
| V1.1.7 | 2025/03/22 | 陈显文 | 1. 修复已知问题 |
| V1.1.8 | 2025/07/10 | 陈显文 | 1. 新增部分接口 |
| V1.1.9 | 2025/10/22 | 陈显文 | 1. 新增部分接口;2. 修复蓝牙扫描问题 |
| V1.1.11 | 2025/11/19 | 陈显文 | 1. 兼容部分设备 ECG 波形问题 |
| V1.1.12 | 2025/12/05 | 陈显文 | 1. 日常数据、血糖测量兼容风险等级解析 |
| V1.1.13 | 2025/12/16 | 陈显文 | 1. 新增 JH58 定制项目动态血压接口;2. 血液成分接口修改 |
| V1.1.14 | 2025/12/29 | 陈显文 | 1. 新增 ZT163 常灭屏功能接口 |
| V1.1.15 | 2026/01/04 | 陈显文 | 1. 修复已知问题 |
| V1.1.16 | 2026/01/09 | 陈显文 | 1. 新增配置 4G 服务信息接口 |
| V1.1.17 | 2026/01/30 | 陈显文 | 1. 新增压力测量接口 |
| V1.1.18 | 2026/04/01 | Veepoo | 1. 优化心率和血氧手动测量接口及配套文档输出 |
| V1.1.19 | 2026/07/28 | Veepoo | 1. 新增 JH58 自动测量与模式 3 原始数据读取;2. 新增 YM28PROSendCommand 指令页;3. 新增 ZT163 灭屏/4GService 等功能页;4. 修复鸿蒙 OTA 回连与接管问题;5. 适配鸿蒙 MTU 协商与配对参数;6. 更新 veepoo SDK |
| V1.1.20 | 2026/08/18 | 孙晓武 | 1. 优化扫描接口在 iOS 平台获取配对设备信息;2. 优化 SDK 体积,由 400KB 左右降低至 255KB;3. 修复 SDK 中 type 值重复问题 |
| V1.1.21 | 2026/08/27 | 孙晓武 | 1. 优化电池电量读取接口及配套文档输出 |
| V1.1.22 | 2026/09/08 | 孙晓武 | 1. 新增运动控制功能;2. 新增世界时钟功能;3. 修复精准睡眠数据读取无法获取多段睡眠的异常 |
| V1.1.23 | 2026/09/20 | 孙晓武 | 1. 修复微体检功能回调数据获取异常问题 |
| V1.1.24 | 2026/10/11 | 孙晓武 | 1. 优化付费授权相关功能逻辑 |
| V1.1.25 | 2026/10/15 | 孙晓武 | 1. 调整付费相关功能的返回字段数据 |
| V1.1.26 | 2026/10/29 | 孙晓武 | 1. 调整血液成分测量和压力测量相关内容 |
| V1.1.27 | 2026/11/3 | 孙晓武 | 1.修复已知问题 |
| V1.1.28 | 2026/11/9 | 孙晓武 | 1.修复已知问题 |
| V1.2.0 | 2026/11/13 | 孙晓武 | 1.新增自定数据下发接口 |
| V1.2.1 | 2026/11/13 | 孙晓武 | 1.血液成分校准读取异常问题修复 |
| V1.3.0 | 2026/11/17 | 孙晓武 | 1.新增蓝牙日志导出模块 |
VeepooWeiXinSDK使用文档:
| 文档版本 | 日期 | 编辑 | 修改内容 |
|---|---|---|---|
| V2.0.0 | 2026/08/18 | 孙晓武 | 1. VeepooWeiXinSDK 使用文档优化版本发布 |
| V2.0.1 | 2026/08/27 | 孙晓武 | 1. 电池电量读取接口内容补充 |
| V2.0.2 | 2026/09/08 | 孙晓武 | 1. 新增运动控制功能和世界时钟功能文档补充 |
| V2.0.3 | 2026/09/20 | 孙晓武 | 1. 微体检功能接口文档调整 |
| V2.0.4 | 2026/10/15 | 孙晓武 | 1. 付费相关功能接口文档内容调整 |
| V2.0.5 | 2026/10/29 | 孙晓武 | 1. 血液成分测量和压力测量相关内容调整 |
| V2.0.6 | 2026/11/3 | 孙晓武 | 1.章节顺序调整 |
| V2.1.0 | 2026/11/13 | 孙晓武 | 1.自定义数据下发接口、获取单包上限接口内容补充 |
| V2.2.0 | 2026/11/17 | 孙晓武 | 1.蓝牙日志收集与导出模块内容补充 |
本项目基于 Apache-2.0 许可证开源。