小程序配网插件

最近更新时间:2023-11-01 10:00:51

我的收藏

基础介绍

说明:
小程序基础库版本默认要求 >= 2.15.0,但如果需要使用"标准蓝牙广播协议",基础库版本要求 >= 2.22.1。
使用前建议先阅读小程序 插件介绍 的内容。
目前插件功能主要分为两部分。
插件 SDK (pluginSdk):全局单例,提供登录态管理、应用端接口调用、蓝牙等能力。
设备绑定组件:目前支持 Wi-Fi 类设备配网以及蓝牙设备绑定。

使用指南

1. 申请使用

在小程序管理后台的设置 > 第三方服务 > 插件管理中搜索"腾讯连连小程序插件"并添加。待腾讯云物联网开发平台相关工作人员审批通过相关申请后即可使用。更多使用说明参见 小程序使用插件 介绍。

2. 引入插件

使用插件前,使用者要在 app.json 中声明需要使用的插件。如需使用 "设备绑定组件" ,请在 app.json 上额外声明位置信息权限。
{
"permission": {
"scope.userLocation": {
"desc": "您的位置信息将用于小程序位置接口的效果展示"
}
},
"plugins": {
"iotexplorer-weapp-plugin": {
"version": "插件最新的版本号",
"provider": "wxb711dd9e4296e7f6"
}
}
}

3. 初始化插件

在使用插件任意功能前,请务必调用 pluginSdk.init 进行初始化,详见 pluginSdk API 参考
使用建议
对于 OEM 小程序,如需使用"设备绑定组件",建议:
先在app.js上实例化 AppDevSdk,详情参见 SDK 初始化文档
在分包上引用并初始化插件时传入 AppDevSdk 实例(小程序规定每个包大小不能超过2M,插件大小目前为1M左右,所以建议不要占用主包的空间)。
需要等待 pluginSdk.init 初始化完成后,再渲染配网组件 <DeviceConfiguraiton>
示例代码
// device-configuration-plugin.json
{
"usingComponents": {
"device-configuration": "plugin://iotexplorer-weapp-plugin/DeviceConfiguration"
}
}

// device-configuration-plugin.wxml
<device-configuration wx:if="{{pluginInitFinish}}" props="{{deviceConfProps}}" />
<view wx:else>插件未初始化</view>

// device-configuration-plugin.js
const app = getApp();

Page({
data: {
deviceConfProps: { /* ... */ },
pluginInitFinish: false,
},
async onLoad() {
await pluginSdk.init({
appDevSdk: app.sdk,
});
this.setData({
pluginInitFinish: true,
});
},
});

4. 适配插件

因为小程序插件无法调用 wx.onAppHidewx.onAppShow 接口,所以需要依赖引用方主动通知,当对应事件触发时,调用 pluginSdk 对应的方法来通知插件。
示例代码
wx.onAppShow(function () {
pluginSdk.onAppShow();
});

wx.onAppHide(function () {
pluginSdk.onAppHide();
});

pluginSdk API 参考

基本属性

参数
类型
说明
appDevSdk
AppDevSdk 实例
uin
string
获取当前已登录用户的 userId
userInfo
object
获取当前已登录用户的信息
userInfo.Avatar
string
头像
userInfo.Email
string
邮箱(用户已绑定邮箱才能获取)
userInfo.NickName
string
昵称
userInfo.PhoneNumber
string
昵称(用户已绑定手机才能获取)
userInfo.UserID
string
用户 ID

初始化

1. 接口定义
pluginSdk.init(options: Object);
2. 输入参数
参数名称
参数描述
类型
必填
appDevSdk
AppDevSdk 实例
Object
getLoginAccessToken
获取登录 Token
() => Promise<{ Token: string; ExpireAt: number }>
wifiConfProtocolList
按需注入 WiFi 配网插件,支持的协议类型查看下文
Array<WiFi配网插件>
bluetoothAdapter
蓝牙适配器 BluetoothAdapter 实例
Object
-
bluetoothDeviceAdapterList
按需注入蓝牙协议 DeviceAdapte,支持的协议类型查看下文
Array<蓝牙设备适配器>
注意:
appDevSdk、getLoginAccessToken 两个参数为互斥关系,初始化时必须传入其中一个。
wifiConfProtocolList 参数说明
按需注入 WiFi 配网插件,目前支持的插件如下:
AirKiss
SoftAp
BleCombo
bluetoothDeviceAdapterList 参数说明
按需注入蓝牙设备适配器,目前支持的蓝牙 DeviceAdapter 如下:
注意:
使用蓝牙辅助配网时请注意,除了注入 WiFi 配网插件外,还要注入相应协议的蓝牙 DeviceAdapter。
3. 示例代码
const { pluginSdk } = requirePlugin('iotexplorer-weapp-plugin');

/*
* WiFi设备相关
*/
const SimpleConfigPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-simpleconfig').default;
const AirKissPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-airkiss').default;
const SmartConfigPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-smartconfig').default;
const SoftApPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-softap').default;
const BleComboPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-blecombo').default;
const QrcodePlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-qrcode').default;
const {
// 适用于使用BleCombo乐鑫协议的设备
BleComboEspDeviceAdapter,
// 适用于使用标准蓝牙辅助协议的设备
BleComboLLSyncDeviceAdapter,
// 适用于使用双路通讯协议的设备
BleComboDualModeDeviceAdapter,
} = require('qcloud-iotexplorer-appdev-plugin-wificonf-blecombo');

/**
* 蓝牙设备相关
*/
// 标准蓝牙协议
const { StandardDeviceAdapter4Mp: StandardDeviceAdapter } = require('qcloud-iotexplorer-bluetooth-adapter-llsync');
// 标准蓝牙广播协议
const StandardAdvertDeviceAdapter = require('qcloud-iotexplorer-bluetooth-adapter-llsync-advert');

Page({
async onLoad() {
console.log('设备适配器', [
StandardDeviceAdapter,
StandardAdvertDeviceAdapter,
BleComboEspDeviceAdapter,
BleComboLLSyncDeviceAdapter,
BleComboDualModeDeviceAdapter,
]);
try {
// Todo 这里需要补充appDevSdk初始化的代码
await pluginSdk.init({
// 注意:appDevSdk、getLoginAccessToken、getLoginTicket 三个为互斥关系,初始化时只需传入一个即可
appDevSdk: getApp().appDevSdk, // 对于OEM小程序,建议先在app.js上初始化,然后调用plugin.init时注入

// 当使用getLoginAccessToken时,需要传入appKey
// appKey: 'xxx',
// getLoginAccessToken: async () => {
// // ...await some asynchronous 异步请求Token
// return {
// Token: 'xxx',
// ExpireAt: 't',
// };
// },

// getLoginTicket: async () => {
// // ...await some asynchronous 异步请求Ticket
// return {
// Ticket: 'xxx'
// };
// },

// 往插件里按需注入WiFi设备配网协议
wifiConfProtocolList: [
AirKissPlug,
SimpleConfigPlug,
SmartConfigPlug,
BleComboPlug,
SoftApPlug,
QrcodePlug,
],
// 往插件里按需注入蓝牙DeviceAdapter
// 注意:BleCombo比较特殊,除了需要注入"BleComboPlug"外,因为涉及到蓝牙,也要注入对应协议的"DeviceAdapter"
bluetoothDeviceAdapterList: [
StandardDeviceAdapter,
StandardAdvertDeviceAdapter,
BleComboEspDeviceAdapter,
BleComboLLSyncDeviceAdapter,
BleComboDualModeDeviceAdapter,
],
});
} catch (err) {
/* 调用方自行处理出错后的逻辑 */
console.error('插件初始化失败', err);
}

// 因为小程序插件无法使用onAppShow、onAppHide 所以需要依赖调用方来实现,当对应事件触发时,调用pluginSdk对应的方法
// 请务必实现
wx.onAppShow(this.onAppShow);
wx.onAppHide(this.onAppHide);
},
onUnload() {
wx.offAppShow(this.onAppShow);
wx.offAppHide(this.onAppHide);
},
onAppShow() {
pluginSdk.onAppShow();
},
onAppHide() {
pluginSdk.onAppHide();
}
});

设备绑定组件

目前插件使用 Taro 开发,基于 Taro 的限制,需要将参数都放入 props 属性上 ,如下示例代码:
示例代码
<device-configuration
props="{{deviceConfProps}}"
/>
Page({
data: {
deviceConfProps: {
productId: 'xxx',
familyId: 'xxx',
wifiConfProps: {
extraInfo: {}
},
onSuccess() {},
onError() {},
onComplete() {},
navigateBack: () => wx.navigateBack(),
}
},
})
组件参数
参数名称
参数描述
类型
必填
productId
产品 ID
string
navigateBack
因为小程序插件无法调用 wx.navigateBack 接口,需要依赖引用方主动通知
function
familyId
如不传入,组件会先让用户选择家庭
string
onSuccess
配网成功时回调,回调参数{ deviceId: string; familyId: string }
function
onError
配网失败时回调
function
onComplete
配网完成时回调;仅在配网成功时,用户单击 完成 按钮时才触发
回调参数{ deviceId: string; familyId: string }
function