该内容对您有帮助吗?
是否更新时间:2022-03-28 08:46:56下载pdf
本文介绍了涂鸦 IoT 微信小程序蓝牙 SDK,该 SDK 提供了一些蓝牙功能的封装,方便小程序开发者更加快速地连接涂鸦生态中的智能硬件产品。您可以基于该 SDK 快速地实现小程序蓝牙交互功能的开发,实现对智能蓝牙设备的连接、控制、固件升级等操作。
该 SDK 根据涂鸦蓝牙协议提供高度封装的 API,方便小程序开发者快速实现小程序蓝牙功能。
需要在 .npmrc
文件中配置对应的 registry:
@tuya-wx:registry=https://registry-out-npm.tuya-inc.top/
使用 NPM 包管理器下载 SDK。
npm install @tuya-wx/wx-bluetooth-sdk
@tuya-wx/wx-bluetooth-sdk
与 @tuya-wx/ble-sdk
的区别:
@tuya-wx/ble-sdk
的职责是根据涂鸦蓝牙协议提供处理数据的方法和配置。@tuya-wx/ble-sdk
使用文档请参考 蓝牙门锁微信小程序 SDK。@tuya-wx/wx-bluetooth-sdk
则是基于 @tuya-wx/ble-sdk
的更高层级封装。若使用 @tuya-wx/wx-bluetooth-sdk
,小程序开发者只需要简单地调用该 SDK 提供的 API
,即可完成蓝牙连接、控制等操作。若您已安装小程序开发者工具,点此打开微信官方代码片段,即可查看完整示例,若按如下步骤操作,还可生成小程序二维码进行真机体验。
project.config.json
文件中的 appid
字段为您在涂鸦 IoT 平台授权过的小程序 AppID
。npm install
命令安装 NPM 包。pages/home_center/common_panel/index.js
下。若您未安装小程序开发者工具,也可参考以下示例代码:
import BleService from '@tuya-wx/wx-bluetooth-sdk'
BleService.initParams({ access_token, uid });
// 小程序生命周期钩子
onLoad: async function () {
// 抽象的蓝牙设备实例
const instance = BleService.setNewInstance(device_id, home_id)
// 蓝牙连接
instance.connectBlue()
// 监听蓝牙通信
instance.onReceivePackage((parseReceiveData) => {
const { type, status, dpState, deviceId } = parseReceiveData
if (type === 'connect' && status === 'fail') {
if (deviceId) {
return { msg: '连接失败 或 连接后又断开' }
} else {
return { msg: '未发现当前蓝牙设备' }
}
} else if (type === 'connect' && status === 'connected') {
// 连接成功
wx.showToast({
title: '蓝牙连接成功',
icon: 'success',
duration: 2000
})
// 如果连接成功后需要下发 DP
instance.sendDp({ dpCode: 'code', dpValue: 123 })
} else if (!(deviceId in parseReceiveData) && dpState) {
// 一般为 DP 上报事件,可在此处处理数据 or 走业务逻辑
this.handleData(dpState)
}
})
},
handleData(dpState) {
// todo....
}
import BleService from '@tuya-wx/wx-bluetooth-sdk'
BleService
是一个实例对象,该实例维护了下文所提到的设备实例列表,以及创建设备实例、销毁设备实例等 API。
BleService.initParams({ access_token, uid });
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
access_token | String | 登录凭证 |
uid | String | 用户 ID |
返回值:无
在蓝牙连接认证流程中,需要通过 云函数
接口拉取部分蓝牙连接所需要的数据(具体数据可点此查看蓝牙通信建立流程图的示意)。为方便开发者使用,SDK 已内部封装通信流程所涉及的接口请求,但由于 用户 ID
、access_token
为云函数接口鉴权必需参数,因此需要调用方传入该参数以便 SDK 顺利发起请求。用户 ID
、access_token
的获取请 点此查看。
const instance = BleService.setNewInstance(device_id, home_id)
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
device_id | String | 蓝牙设备配网后生成的虚拟 ID |
home_id | Number | 蓝牙设备所在家庭 ID |
返回值:设备实例
通过调用该方法,将生成一个设备实例。每个蓝牙设备对应一个实例。该设备的连接状态等数据都将维护在该实例中。同时,设备连接、设备指令下发、OTA 升级等相关 API 也维护在该设备实例中。
涂鸦小程序家庭、设备相关云函数,请参考 全屋管理。
若当前设备 ID 对应的实例已经被创建过,则会销毁原有实例,并创建新的实例返回。
const instance = BleService.instance[device_id]
if(!instance) reutrn false
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
device_id | String | 蓝牙设备配网后生成的虚拟 ID |
返回值:设备实例
也可通过该方式获取已生成的设备实例。BleService.instance
为 BleService
维护的设备实例列表。
BleService.destroyInstance(device_id)
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
device_id | String | 蓝牙设备配网后生成的虚拟 ID |
返回值:无
const res = await instance.connectBlue()
返回值:Promise
该方法为异步函数,设备连接结果需要等待 Promise 对象处理完成。
Promise 对象处理结果
字段 | 数据类型 | 说明 |
---|---|---|
success | Boolean | 蓝牙是否成功连接 |
errMsg | String | 蓝牙连接失败时的错误信息 |
蓝牙连接过程中的连接状态变化,会通过下文提到的回调事件进行回调,建议监听该事件回调,以便监控连接过程。
instance.connectionBreak()
返回值:Promise
该方法为异步函数,执行结果需要等待 Promise 对象处理完成。
Promise 对象处理结果
字段 | 数据类型 | 说明 |
---|---|---|
success | Boolean | 蓝牙是否成功断开连接 |
errMsg | String | 蓝牙断开连接失败时的错误信息 |
// 发送标准 DP
const res = instance.sendDp({ dpCode, dpValue })
// 发送自定义 DP( v1.0.4 以上 )
const res = instance.sendDp({ dpId, dpType, dpValue })
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
dpValue | any | 要下发的数据 |
dpCode | string | dpcode,发送标准 DP 时,传入 dpCode 与 dpValue 即可 |
dpId | number | dpid,发送自定义 dp( v1.0.4 以上 )时,必传此项 |
dpType | string | dpValue 所对应的数据类型,发送自定义 dp( v1.0.4 以上 )时,必传此项 |
参数举例
// 发送标准 dp,假设 DP 为: dpcode: 'welcome_words', dpType: 'string', dpId: 18
instance.sendDp({ dpCode: 'welcome_words', dpValue: 'hello world' })
// 发送自定义 dp,假设 DP 为:dpcode: 'switch_1', dpType: 'boolean', dpid: 101
instance.sendDp({ dpId: 101, dpType: 'Boolean', dpValue: true })
返回值:Promise
Promise 对象处理结果
字段 | 数据类型 | 说明 |
---|---|---|
success | Boolean | 数据下发是否成功 |
errMsg | String | 蓝牙数据下发失败时的错误信息 |
处理结果为 true
仅代表数据单方面下发成功,不代表蓝牙设备正确接收到了数据并校验成功,因此,在遇到数据下发成功但设备无反应时,请先自查所下发数据是否有效。
instance.onReceivePackage(parseReceiveData => {
const { type, status, dpState, deviceId } = parseReceiveData;
if (type === 'connect' && status === 'fail') {
// 连接失败 或 连接后又断开
} else if (type === 'connect' && status === 'connected') {
// 连接成功
wx.showToast({
title: '蓝牙连接成功',
icon: 'success',
duration: 2000
})
} else if (!(deviceId in parseReceiveData)) {
// 一般为 DP 上报事件,可在此处处理数据 or 走业务逻辑
// 上报的数据会被处理成 dpState 对象,dpState 对象下面有举例
// todo...
}
});
回调参数说明
字段 | 数据类型 | 说明 |
---|---|---|
type | string | 状态类型:
|
status | string | 状态值 |
deviceId | string | 蓝牙设备 ID,安卓下为 mac 地址 |
dpState | Object | 当前蓝牙设备的功能状态集 |
回调参数 status
数值说明
type | status 数值 | 说明 |
---|---|---|
connect | ready | SDK 准备进行蓝牙连接,进入此状态后,请勿再重复调用 connectBlue 进行连接,否则可能会导致连接失败 |
– | connecting | 连接中 |
– | connected | 蓝牙连接成功 |
– | fail | 蓝牙连接失败 |
otaStatus | updating | OTA 中 |
– | updated | OTA 成功 |
– | fail | OTA 失败 |
– | ready | 准备开始 OTA,此阶段将先进行设备状态校验( v1.1.0 以上) |
– | check | 向设备发送 OTA 请求,等待设备同意( v1.1.0 以上) |
send | sending | 数据发送中 |
– | sended | 数据发送完毕 |
回调参数 dpState 举例
dpState: {
[dpcode1]: true,
[dpcode2]: 100
}
instance.offReceivePackage(cb);
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
cb | Function | 注册监听时传入的回调函数 |
instance.onError(cb);
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
cb | function | 回调函数 |
回调参数举例
{
errCode: 1000,
errMsg: 'error'
}
蓝牙交互时出现的异常情况都将在此处进行回调。
instance.offError(cb);
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
cb | Function | 注册监听时传入的回调函数 |
instance.getBlueStatus()
返回值:Promise
Promise 对象处理结果
字段 | 数据类型 | 说明 |
---|---|---|
success | Boolean | 设备本地状态查询请求下发是否成功 |
errMsg | String | 设备本地状态查询请求下发失败时的错误信息 |
建议在蓝牙连接成功之后,调用该 API 查询设备本地最新状态,如:设备电量信息等。
设备上报的最新状态也将会通过上文提到的 onReceivePackage
进行回调。
此 API 原理不能简单等同为“调接口拿数据”。
它只是向设备发出一个本地状态上报请求,设备收到这个请求之后,是否要上报本地状态,上报哪些本地状态,由设备决定。但无论上报哪些状态,最终这些数据都将由 SDK 的 onReceivePackage
进行回调。
instance.sendOtaRequestOrder(url, version);
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
url | String | OTA 升级文件 URL 地址 |
version | String | OTA 升级文件版本号 |
OTA 升级过程复杂,涉及多个蓝牙指令下发,请务必通过 onReceivePackage
监听 OTA 升级过程的状态变化。
instance.unboundBlue(type);
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
type | String | 共有两种解绑类型,分别对应不同的 type 数值:
|
返回值:Promise
Promise 对象处理结果
字段 | 数据类型 | 说明 |
---|---|---|
success | Boolean | 蓝牙解绑命令是否下发成功 |
errMsg | String | 蓝牙解绑失败时的错误信息 |
// 数据下发前,对 Raw 类型数据加密
BleService.encryptRawData(raw_data)
// 数据上报后,对回调数据进行解密
BleService.decryptRawData(value)
参数说明
字段 | 数据类型 | 说明 |
---|---|---|
raw_data | String | Raw 类型数据 |
value | String | 通过 onReceivePackage 回调监听到的 Raw 类型数据 |
Raw 表示透传类型数据。对某些设备来说,Raw 类型数据可能会包含密码等较为敏感的信息,在数据下发及上报云端时,应对其进行安全加密处理。因此,SDK 要求 Raw 类型数据应加密下发,同时 SDK 自身也会对设备上报的 Raw 类型数据进行加密后返回。
errCode | 说明 |
---|---|
1001 | 蓝牙连接过程中,调用微信 API 失败 |
1002 | 未授予地理位置权限(安卓特有) |
1003 | 未搜索到蓝牙设备 |
1004 | 设备信息获取失败 |
1005 | 获取蓝牙 services 列表失败 |
1006 | 获取 characteristics 列表失败 |
1007 | write characteristic uuid 获取失败 |
1008 | 当前设备具有 SDK 不支持的蓝牙特性 |
1009 | 获取云端实时时间失败 |
1010 | 蓝牙连接过程中,下发命令失败 |
1011 | 云端随机数获取失败 |
1012 | 初始化蓝牙适配器失败 |
1013 | 未授予蓝牙权限 |
1014 | 蓝牙 LE + Beacon 设备连接时,获取 BeaconKey 失败 |
2001 | 蓝牙下发 DP 数据时,下发命令失败 |
2003 | 蓝牙 DP 上报云端时,调用接口失败 |
2004 | 设备解绑、重置时,下发命令失败 |
2005 | 获取设备本地状态信息时,下发命令失败 |
3001 | 发送 OTA 升级请求时,下发命令失败 |
3002 | 蓝牙拒绝 OTA 升级 |
3003 | 不支持 OTA 升级的蓝牙协议版本 |
3004 | 不支持的 OTA 升级类型 |
3005 | 发送 OTA 升级文件信息时,下发命令失败 |
3006 | 发送 OTA 升级文件偏移请求时,下发命令失败 |
3007 | 分包发送 OTA 升级数据包时,下发命令失败 |
3008 | 发送 OTA 升级停止指令时,下发命令失败 |
涉及微信原生 API 的错误码,都将以 wxErrCode
与 wxErrMsg
这两个字段透传微信侧提供的错误信息,方便错误排查。
版本号 | 更新说明 |
---|---|
1.1.0 | 支持 蓝牙 LE + Beacon 设备通过蓝牙 LE 通道进行本地蓝牙控制 |
1.0.4 | 支持设备自定义 DP 下发 |
1.0.1 | 支持 蓝牙 LE 3/.* 与 4/.* 协议版本的设备的本地控制能力 |
该内容对您有帮助吗?
是否该内容对您有帮助吗?
是否