物联网开发平台
视频服务与安全产品捉虫活动邀您参加！> HOT
文档中心>物联网开发平台>应用端开发指南>自主品牌小程序开发>应用端 SDK>设备配网 SDK

设备配网 SDK

最近更新时间：2024-10-08 18:37:11

我的收藏

本页目录：

配网概述

SDK 目前支持 SoftAP、SmartConfig、simpleConfig、AirKiss、BLE-Combo 这五种方式进行设备配网。
这五种配网方式的 SDK 都是以插件的方式按需引入的，为了方便大家理解，下图可以看出这五个 SDK 的依赖关系。




基本使用

通过四步可以运行配网插件，以 SoftAp 配网为例，其余配网方式步骤相同，后面关于配网步骤和参数说明会有具体阐述。

1. 安装依赖

npm install qcloud-iotexplorer-appdev-plugin-wificonf-softap

2. 注册插件

调用插件上 install 方法来注册插件，调用时需要传入实例化的小程序 SDK。
插件注册时的名称分别为：wifiConfSoftAp、wifiConfSmartConfig、wifiConfSimpleConfig、wifiConfBleCombo、wifiConfAirKiss，之后可通过插件名称来获取插件实例。
const SoftApPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-softap');
SoftApPlug.install(appDevSdk);

3. 生成配网 Token

调用应用端 API 生成 Wi-Fi 设备配网 Token 来获取 Wi-Fi 设备配网 Token。
sdk.requestApi('AppCreateDeviceBindToken')
  .then((data) => {
    const bindDeviceToken = data.Token;
    console.log('wifi设备配网Token=', bindDeviceToken);
  });

4. 使用配网插件

从 appDevSdk 实例的 plugins 中获取已注册的插件实例，调用配网插件实例的 start 方法开始配网流程。
示例代码
sdk.plugins['wifiConfSoftAp'].start({
  wifiConfToken: bindDeviceToken,
  targetWifiInfo: wifiInfo,
  onProgress,
  onComplete,
  onError,
  autoRetry: true, // 自动处理故障流程
});

SoftAP 配网

关于 softAP 方式配网的流程，请参见 softAP 配网开发。各端交互的流程如下：

SoftAPFlows


腾讯连连中 SoftAP 配网页面如下，供开发者参考。



SoftAP 配网参数

参数名
参数描述
类型
必填
wifiConfToken
Wi-Fi 设备配网 Token，从后台接口 生成 Wi-Fi 设备配网 Token 获取。
string
是
targetWifiInfo
目标 Wi-Fi 信息，需要设备去连接的 Wi-Fi 的信息。
WifiInfo
是
softAPInfo
设备热点信息，如果传该配置，则首先会调用 wx.connectWifi 去连接设备热点；如果不传，则需要自行引导用户去连接设备热点。
WifiInfo
否
onProgress
配网过程执行到每个步骤时触发的回调，回调函数入参如下：
code：步骤代码，详见 配网步骤 小节
msg：步骤描述，自行从WifiConfStepDesp用 code 取描述内容。
detail：步骤详情，根据每个步骤不同而不同。
function
是
onError
配网失败时触发，回调函数入参如下：
code：错误代码，详见 错误码 小节。
msg：错误描述，自行从 WifiConfErrorMsg 拿 code 取描述内容。
detail：错误详情。
function
是
onComplete
配网完成后触发，回调函数入参如下：
deviceInfo：设备信息。
function
是
familyId
家庭 ID，默认为：'default'，即用户默认家庭 ID。
string
否
roomId
房间 ID，默认为：''，即用户默认房间 ID。
string
否
udpAddress
连接上设备热点后，小程序发起 UDP 通信的地址，默认为：'192.168.4.1'，一般无需更改。
string
否
udpPort
连接上设备热点后，小程序发起 UDP 通信的端口，默认为：8266，一般无需更改。
number
否
stepInterval
配网过程中，每一步中间等待的间隔，单位毫秒，默认为：1000，一般无需更改。
number
否
autoRetry
配网失败之后是否要启动自动错误处理后直接重试，自动错误处理 章节，默认为：false。
boolean
否

WifiInfo 数据结构

属性名
属性描述
类型
必填
SSID
Wi-Fi 的 SSID
string
是
password
Wi-Fi 的 密码
string
是

示例代码

import { constants as WifiConfConstants } from 'qcloud-iotexplorer-appdev-plugin-wificonf-core';

const {
  // 步骤code
  WifiConfStepCode,
  // 步骤code的中文描述
  WifiConfStepDesp,
  // 错误的中文描述
  WifiConfErrorMsg,
} = WifiConfConstants;

/**
 * softap配网
 */
function SoftApConfigure({
  token,
  wifiInfo = {
    SSID: '',
    password: '',
  },
  familyId = 'default',
  roomId,
  /* 更新配网步骤 */
  onStepChange,
  /* 更新配网状态(success/error) */
  onStatusChange,
}) {
  const onProgress = ({ code, detail }) => {
    const msg = WifiConfStepDesp[code];
    console.log('配网步骤更新(onProgress)', code, msg, detail);
    switch (code) {
      case WifiConfStepCode.CREATE_UDP_CONNECTION_SUCCESS:
        onStepChange(1);
        break;
      case WifiConfStepCode.PROTOCOL_SUCCESS:
        onStepChange(2);
        break;
      case WifiConfStepCode.SOFTAP_GET_DEVICE_SIGNATURE_SUCCESS:
      case WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_SUCCESS:
        onStepChange(3);
        break;
      case WifiConfStepCode.WIFI_CONF_SUCCESS:
        onStepChange(4);
        break;
    }
  };

  const onComplete = (deviceInfo) => {
    console.log('配网完成(onComplete):', deviceInfo);
    onStatusChange({
      status: 'success',
      productId: deviceInfo.productId,
      deviceName: deviceInfo.deviceName,
    });
  };

  const onError = async ({ code, detail }) => {
    const msg = WifiConfErrorMsg[code];
    console.log('配网错误(onError)', code, msg, detail);
    onStatusChange({ status: 'error' });
  };

  sdk.plugins['wifiConfSoftAp'].start({
    wifiConfToken: token,
    targetWifiInfo: wifiInfo,
    autoRetry: true, // 自动处理故障流程
    familyId,
    roomId,
    onProgress,
    onComplete,
    onError,
  });
}

module.exports = SoftApConfigure;

配网步骤v1.0（已废弃，不建议使用）

步骤
描述
WifiConfStepCode.WIFI_CONF_START
开始配网。
WifiConfStepCode.PROTOCOL_START
配网协议开始。
WifiConfStepCode.CONNECT_SOFTAP_START
开始连接设备热点。
WifiConfStepCode.CONNECT_SOFTAP_SUCCESS
连接设备热点成功。
WifiConfStepCode.CREATE_UDP_CONNECTION_START
开始与设备建立 UDP 连接。
WifiConfStepCode.CREATE_UDP_CONNECTION_SUCCESS
与设备建立 UDP 连接成功。
WifiConfStepCode.SOFTAP_SEND_TARGET_WIFIINFO_START
开始发送目标 Wi-Fi 信息。
WifiConfStepCode.SOFTAP_SEND_TARGET_WIFIINFO_SUCCESS
发送目标 Wi-Fi 信息成功。
detail: { response }，收到设备的具体响应。
WifiConfStepCode.SOFTAP_GET_DEVICE_SIGNATURE_START
开始获取设备签名。
WifiConfStepCode.SOFTAP_GET_DEVICE_SIGNATURE_SUCCESS
获取设备签名成功。
detail: { signature }
WifiConfStepCode.SOFTAP_RECONNECT_TARGET_WIFI_START
开始手机连接目标 Wi-Fi。
WifiConfStepCode.SOFTAP_RECONNECT_TARGET_WIFI_SUCCESS
手机连接目标 Wi-Fi 成功。
WifiConfStepCode.PROTOCOL_SUCCESS
配网协议成功。
WifiConfStepCode.BUSINESS_START
业务流程开始。
WifiConfStepCode.BUSINESS_ADD_DEVICE_START
开始添加设备。
WifiConfStepCode.BUSINESS_ADD_DEVICE_SUCCESS
添加设备成功。
WifiConfStepCode.BUSINESS_SUCCESS
业务流程成功。
detail: { productId, deviceName}，请求参数。
WifiConfStepCode.WIFI_CONF_SUCCESS
配网成功。

配网步骤v2.0

步骤
描述
WifiConfStepCode.WIFI_CONF_START
开始配网。
WifiConfStepCode.PROTOCOL_START
配网协议开始。
WifiConfStepCode.CONNECT_SOFTAP_START
开始连接设备热点。
WifiConfStepCode.CONNECT_SOFTAP_SUCCESS
连接设备热点成功。
WifiConfStepCode.CREATE_UDP_CONNECTION_START
开始与设备建立 UDP 连接。
WifiConfStepCode.CREATE_UDP_CONNECTION_SUCCESS
与设备建立 UDP 连接成功。
WifiConfStepCode.SOFTAP_SEND_TARGET_WIFIINFO_START
开始发送目标 Wi-Fi 信息。
WifiConfStepCode.SOFTAP_SEND_TARGET_WIFIINFO_SUCCESS
发送目标 Wi-Fi 信息成功。
detail: { response }，收到设备的具体响应。
WifiConfStepCode.SOFTAP_RECONNECT_TARGET_WIFI_START
开始手机连接目标 Wi-Fi。
WifiConfStepCode.SOFTAP_RECONNECT_TARGET_WIFI_SUCCESS
手机连接目标 Wi-Fi 成功。
WifiConfStepCode.PROTOCOL_SUCCESS
配网协议成功。
WifiConfStepCode.BUSINESS_START
业务流程开始。
WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_START
开始查询配网TOKEN状态。
WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_SUCCESS
查询配网TOKEN状态成功。
WifiConfStepCode.BUSINESS_ADD_DEVICE_START
开始添加设备。
WifiConfStepCode.BUSINESS_ADD_DEVICE_SUCCESS
添加设备成功。
WifiConfStepCode.BUSINESS_SUCCESS
业务流程成功。
detail: { productId, deviceName}，请求参数。
WifiConfStepCode.WIFI_CONF_SUCCESS
配网成功。

SmartConfig 配网

关于 SmartConfig 方式配网的流程，请参见 SmartConfig 配网开发。一键配网的配网流程图文版本如下：

oneKeyConfigure


腾讯连连中 SmartConfig 配网页面如下，供开发者参考。



SmartConfig 配网参数

参数名
参数描述
类型
必填
wifiConfToken
Wi-Fi 设备配网 Token，从后台接口 生成 Wi-Fi 设备配网 Token 获取。
string
是
targetWifiInfo
目标 Wi-Fi 信息，需要设备去连接的 Wi-Fi 的信息。
WifiInfo
是
onProgress
配网过程执行到每个步骤时触发的回调，回调函数入参如下：
code：步骤代码，详见 配网步骤 小节。
msg：步骤描述，自行从 WifiConfStepDesp 用code取描述内容。
detail：步骤详情，根据每个步骤不同而不同。
function
是
onError
配网失败时触发，回调函数入参如下：
code：错误代码，详见 错误码 小节。
msg：错误描述，自行从 WifiConfErrorMsg 拿code取描述内容。
detail：错误详情。
function
是
onComplete
配网完成后触发，回调函数入参如下：
deviceInfo：设备信息。
function
是
familyId
家庭 ID，默认为：'default'，即用户默认家庭 ID。
'default' | string
否
roomId
房间 ID，默认为：''，即用户默认房间 ID。
'' | string
否
udpPort
小程序和设备连上同一个局域网之后，小程序发起 UDP 通信的端口，默认为：8266，一般无需更改。
number
否
stepInterval
配网过程中，每一步中间等待的间隔，单位毫秒，默认为：1000，一般无需更改。
number
否
autoRetry
配网失败之后是否要启动自动错误处理后直接重试，自动错误处理 章节，默认为：false。
boolean
否

WifiInfo 数据结构

属性名
属性描述
类型
必填
SSID
Wi-Fi 的 SSID。
string
是
BSSID
Wi-Fi 的 BSSID。
string
是
password
Wi-Fi 的 密码。
string
是

示例代码

import { constants as WifiConfConstants } from 'qcloud-iotexplorer-appdev-plugin-wificonf-core';

const {
  // 步骤code
  WifiConfStepCode,
  // 步骤code的中文描述
  WifiConfStepDesp,
  // 错误的中文描述
  WifiConfErrorMsg,
} = WifiConfConstants;

/**
 * smartconfig一键配网
 */
function SmartConfigConfigure({
  token,
  wifiInfo = {
    SSID: '',
    password: '',
    BSSID: '',
  },
  familyId = 'default',
  roomId,
  /* 更新配网步骤 */
  onStepChange,
  /* 更新配网状态 */
  onStatusChange,
}) {
  const onProgress = ({ code, detail }) => {
    const msg = WifiConfStepDesp[code];
    console.log('配网步骤更新(onProgress)', code, msg, detail);
    switch (code) {
      case WifiConfStepCode.PROTOCOL_SUCCESS:
        onStepChange(1);
        break;
      case WifiConfStepCode.CREATE_UDP_CONNECTION_SUCCESS:
        onStepChange(2);
        break;
      case WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_SUCCESS:
        onStepChange(3);
        break;
      case WifiConfStepCode.WIFI_CONF_SUCCESS:
        onStepChange(4);
        break;
    }
  };

  const onComplete = (deviceInfo) => {
    console.log('配网完成(onComplete):', deviceInfo);
    onStatusChange({
      status: 'success',
      productId: deviceInfo.productId,
      deviceName: deviceInfo.deviceName,
    });
  };

  const onError = async ({ code, detail }) => {
    const msg = WifiConfErrorMsg[code];
    console.log('配网错误(onError)', code, msg, detail);

    onStatusChange({ status: 'error' });
  };

  sdk.plugins['wifiConfSmartConfig'].start({
    wifiConfToken: token,
    targetWifiInfo: wifiInfo,
    autoRetry: true, // 自动处理故障流程
    familyId,
    roomId,
    onProgress,
    onComplete,
    onError,
  });
}

module.exports = SmartConfigConfigure;

配网步骤

sdk.plugins['wifiConfSmartConfig'].start() 配网过程中，每执行完一个步骤就会触发一次 onProgress 回调，入参为：{ code, detail } 形式。
步骤
描述
WifiConfStepCode.WIFI_CONF_START
开始配网。
WifiConfStepCode.PROTOCOL_START
配网协议开始。
WifiConfStepCode.PROTOCOL_DETAIL
配网协议的细节，详细日志。
WifiConfStepCode.PROTOCOL_SUCCESS
配网协议成功，获取到设备地址detail: { data: { address } }，收到设备局域网地址，用于给设备发送信息。
WifiConfStepCode.BUSINESS_START
业务流程开始。
WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_START
开始查询配网 TOKEN 状态。
WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_SUCCESS
查询配网 TOKEN 状态成功。
WifiConfStepCode.BUSINESS_ADD_DEVICE_START
开始添加设备。
WifiConfStepCode.BUSINESS_ADD_DEVICE_SUCCESS
添加设备成功。
WifiConfStepCode.BUSINESS_SUCCESS
业务流程成功。
detail: { productId, deviceName}，请求参数。
WifiConfStepCode.WIFI_CONF_SUCCESS
配网成功。

SimpleConfig 配网

关于 simpleConfig 方式配网的流程，请参见 simpleConfig 配网开发。一键配网的配网流程图文版本如下：

oneKeyConfigure


腾讯连连中 SimpleConfig 配网页面如下，供开发者参考。



SimpleConfig 配网参数

参数名
参数描述
类型
必填
wifiConfToken
Wi-Fi 设备配网 Token，从后台接口 生成 Wi-Fi 设备配网 Token 获取。
string
是
targetWifiInfo
目标 Wi-Fi 信息，需要设备去连接的 Wi-Fi 的信息。
WifiInfo
是
onProgress
配网过程执行到每个步骤时触发的回调，回调函数入参如下：
code：步骤代码，详见 配网步骤 小节。
msg：步骤描述，自行从 WifiConfStepDesp 用code取描述内容。
detail：步骤详情，根据每个步骤不同而不同。
function
是
onError
配网失败时触发，回调函数入参如下：
code：错误代码，详见 错误码 小节。
msg：错误描述，自行从 WifiConfErrorMsg 拿code取描述内容。
detail：错误详情。
function
是
onComplete
配网完成后触发，回调函数入参如下：
deviceInfo：设备信息。
function
是
familyId
家庭 ID，默认为：'default'，即用户默认家庭 ID。
string
否
roomId
房间 ID，默认为：''，即用户默认房间 ID。
string
否
udpPort
小程序和设备连上同一个局域网之后，小程序发起 UDP 通信的端口，默认为：8266，一般无需更改。
number
否
stepInterval
配网过程中，每一步中间等待的间隔，单位毫秒，默认为：1000，一般无需更改。
number
否
autoRetry
配网失败之后是否要启动自动错误处理后直接重试，自动错误处理章节，默认为：false。
boolean
否

WifiInfo 数据结构

属性名
属性描述
类型
必填
SSID
Wi-Fi 的 SSID。
string
是
password
Wi-Fi 的 密码。
string
是

示例代码

import { constants as WifiConfConstants } from 'qcloud-iotexplorer-appdev-plugin-wificonf-core';

const {
  // 步骤code
  WifiConfStepCode,
  // 步骤code的中文描述
  WifiConfStepDesp,
  // 错误的中文描述
  WifiConfErrorMsg,
} = WifiConfConstants;

/**
 * simpleConfig一键配网
 */
function SimpleConfigConfigure({
  token,
  wifiInfo = {
    SSID: '',
    password: '',
  },
  familyId = 'default',
  roomId,
  onStepChange,
  onStatusChange,
}) {
  const onProgress = ({ code, detail }) => {
    const msg = WifiConfStepDesp[code];
    console.log('配网步骤更新(onProgress)', code, msg, detail);

    switch (code) {
      case WifiConfStepCode.PROTOCOL_SUCCESS:
        onStepChange(1);
        break;
      case WifiConfStepCode.CREATE_UDP_CONNECTION_SUCCESS:
        onStepChange(2);
        break;
      case WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_SUCCESS:
        onStepChange(3);
        break;
      case WifiConfStepCode.WIFI_CONF_SUCCESS:
        onStepChange(4);
        break;
    }
  };

  const onComplete = (deviceInfo) => {
    console.log('配网完成(onComplete):', deviceInfo);

    onStatusChange({
      status: 'success',
      productId: deviceInfo.productId,
      deviceName: deviceInfo.deviceName,
    });
  };

  const onError = async ({ code, detail }) => {
    const msg = WifiConfErrorMsg[code];
    console.log('配网错误(onError)', code, msg, detail);

    onStatusChange({ status: 'error' });
  };

  sdk.plugins.wifiConfSimpleConfig.start({
    wifiConfToken: token,
    targetWifiInfo: wifiInfo,
    autoRetry: true, // 自动处理故障流程
    familyId,
    roomId,
    onProgress,
    onComplete,
    onError,
  });
}

module.exports = SimpleConfigConfigure;

配网步骤

sdk.plugins['wifiConfSimpleConfig'].start() 配网过程中，每执行完一个步骤就会触发一次 onProgress 回调，入参为：{ code, detail } 形式。
步骤
描述
WifiConfStepCode.WIFI_CONF_START
开始配网。
WifiConfStepCode.PROTOCOL_START
配网协议开始。
WifiConfStepCode.PROTOCOL_DETAIL
配网协议的细节，详细日志。
WifiConfStepCode.PROTOCOL_SUCCESS
配网协议成功，获取到设备地址detail: { data: { address } }，收到设备局域网地址，用于给设备发送信息。
WifiConfStepCode.BUSINESS_START
业务流程开始。
WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_START
开始查询配网 TOKEN 状态。
WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_SUCCESS
查询配网 TOKEN 状态成功。
WifiConfStepCode.BUSINESS_ADD_DEVICE_START
开始添加设备。
WifiConfStepCode.BUSINESS_ADD_DEVICE_SUCCESS
添加设备成功。
WifiConfStepCode.BUSINESS_SUCCESS
业务流程成功。
detail: { productId, deviceName}，请求参数。
WifiConfStepCode.WIFI_CONF_SUCCESS
配网成功。

AirKiss 配网

关于 AirKiss 方式配网的流程，请参见 AirKiss 配网开发。一键配网的配网流程图文版本如下：

oneKeyConfigure


腾讯连连中 AirKiss 配网页面如下，供开发者参考。



AirKiss 配网参数

参数名
参数描述
类型
必填
wifiConfToken
Wi-Fi 设备配网 Token，从后台接口 生成 Wi-Fi 设备配网 Token 获取。
string
是
targetWifiInfo
目标 Wi-Fi 信息，需要设备去连接的 Wi-Fi 的信息。
WifiInfo
是
onProgress
配网过程执行到每个步骤时触发的回调，回调函数入参如下：
code：步骤代码，详见 配网步骤 小节。
msg：步骤描述，自行从 WifiConfStepDesp 用code取描述内容。
detail：步骤详情，根据每个步骤不同而不同。
function
是
onError
配网失败时触发，回调函数入参如下：
code：错误代码，详见 错误码 小节。
msg：错误描述，自行从 WifiConfErrorMsg 拿code取描述内容。
detail：错误详情。
function
是
onComplete
配网完成后触发，回调函数入参如下：
deviceInfo：设备信息。
function
是
familyId
家庭 ID，默认为：'default'，即用户默认家庭 ID。
string
否
roomId
房间 ID，默认为：''，即用户默认房间 ID。
string
否
udpPort
小程序和设备连上同一个局域网之后，小程序发起 UDP 通信的端口，默认为：8266，一般无需更改。
number
否
stepInterval
配网过程中，每一步中间等待的间隔，单位毫秒，默认为：1000，一般无需更改。
number
否
autoRetry
配网失败之后是否要启动自动错误处理后直接重试，自动错误处理章节，默认为：false。
boolean
否

WifiInfo 数据结构

属性名
属性描述
类型
必填
SSID
Wi-Fi 的 SSID。
string
是
password
Wi-Fi 的 密码。
string
是

示例代码

import { constants as WifiConfConstants } from 'qcloud-iotexplorer-appdev-plugin-wificonf-core';

const {
  // 步骤code
  WifiConfStepCode,
  // 步骤code的中文描述
  WifiConfStepDesp,
  // 错误的中文描述
  WifiConfErrorMsg,
} = WifiConfConstants;

/**
 * AirKiss一键配网
 */
function AirKissConfigure({
  token,
  wifiInfo = {
    SSID: '',
    password: '',
  },
  familyId = 'default',
  roomId,
  reporter,
  onStepChange,
  onStatusChange,
}) {
  const onProgress = ({ code, detail }) => {
    const msg = WifiConfStepDesp[code];
    console.log('配网步骤更新(onProgress)', code, msg, detail);

    switch (code) {
      case WifiConfStepCode.PROTOCOL_SUCCESS:
        onStepChange(1);
        break;
      case WifiConfStepCode.CREATE_UDP_CONNECTION_SUCCESS:
        onStepChange(2);
        break;
      case WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_SUCCESS:
        onStepChange(3);
        break;
      case WifiConfStepCode.WIFI_CONF_SUCCESS:
        onStepChange(4);
        break;
    }
  };

  const onComplete = (deviceInfo) => {
    console.log('配网完成(onComplete):', deviceInfo);

    onStatusChange({
      status: 'success',
      productId: deviceInfo.productId,
      deviceName: deviceInfo.deviceName,
    });
  };

  const onError = async ({ code, detail }) => {
    const msg = WifiConfErrorMsg[code];
    console.log('配网错误(onError)', code, msg, detail);

    onStatusChange({ status: 'error' });
  };

  sdk.plugins.wifiConfAirKiss.start({
    wifiConfToken: token,
    targetWifiInfo: wifiInfo,
    autoRetry: true, // 自动处理故障流程
    familyId,
    roomId,
    onProgress,
    onComplete,
    onError,
  });
}

配网步骤

sdk.plugins['wifiConfAirKiss'].start() 配网过程中，每执行完一个步骤就会触发一次 onProgress 回调，入参为：{ code, detail } 形式。
步骤
描述
WifiConfStepCode.WIFI_CONF_START
开始配网。
WifiConfStepCode.PROTOCOL_START
配网协议开始。
WifiConfStepCode.PROTOCOL_DETAIL
配网协议的细节，详细日志。
WifiConfStepCode.PROTOCOL_SUCCESS
配网协议成功，获取到设备地址detail: { data: { address } }，收到设备局域网地址，用于给设备发送信息。
WifiConfStepCode.BUSINESS_START
业务流程开始。
WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_START
开始查询配网 TOKEN 状态。
WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_SUCCESS
查询配网 TOKEN 状态成功。
WifiConfStepCode.BUSINESS_ADD_DEVICE_START
开始添加设备。
WifiConfStepCode.BUSINESS_ADD_DEVICE_SUCCESS
添加设备成功。
WifiConfStepCode.BUSINESS_SUCCESS
业务流程成功。
detail: { productId, deviceName}，请求参数。
WifiConfStepCode.WIFI_CONF_SUCCESS
配网成功。

BleCombo 蓝牙辅助配网

关于 蓝牙辅助方式配网的流程，请参见 蓝牙辅助配网开发。一键配网的配网流程图文版本如下：



腾讯连连中 AirKiss 配网页面如下，供开发者参考。



获取设备适配器

在配网之前，我们需要先发现设备，然后与设备建立蓝牙连接，并获得一个 DeviceAdapter 实例，用于蓝牙设备的通信。
这个过程可以通过蓝牙适配器 (BlueToothAdapter) 完成。流程如下：
1. 创建一个蓝牙适配器
蓝牙适配器 (bluetoothAdapter) 主要用于搜索设备、连接设备。示例代码如下：
import { BlueToothAdapter } from 'qcloud-iotexplorer-bluetooth-adapter';
import {
  BleComboEspDeviceAdapter,
  BleComboLLSyncDeviceAdapter,
} from 'qcloud-iotexplorer-appdev-plugin-wificonf-blecombo';

export const bluetoothAdapter = new BlueToothAdapter({
  deviceAdapters: [
    BleComboEspDeviceAdapter,
    BleComboLLSyncDeviceAdapter,
  ],
});
在实例化 blueToothAdapter时，我们需要传入想要支持设备的 DeviceAdapter。目前插件内置了两种DeviceAdapter：
BleComboEspDeviceAdapter：支持通过 BluFi 协议 进行蓝牙辅助配网。
BleComboLLSyncDeviceAdapter：支持通过 LLSync 协议 进行蓝牙辅助配网。
2. 获取蓝牙设备列表
通过 bluetoothAdapter.startSearch 方法，我们可以发现设备，获得设备列表。
await bluetoothAdapter.startSearch({
  ignoreDeviceIds,
  serviceIds,
  ignoreServiceIds,
  onError: (error) => {
    console.log('搜索设备出错', error);
    bluetoothAdapter.stopSearch();
  },
  onSearch: (devices) => {
    if (devices.length > 0) {
      // 可以在页面上展示搜索到的设备
      console.log('搜索到设备', devices);
    }
  },
  timeout: 1.4 * 15 * 1000,
});
在 onSearch 回调函数中，我们可以获得搜寻到的设备列表，这时可以将设备列表展示到页面上，供用户选择要连接的设备。
3. 连接设备
用户点击要连接的蓝牙设备后，可以调用 bluetoothAdapter.connectDevice() 方法进行连接，并调用 bluetoothAdapter.stopSearch() 结束搜索蓝牙设备。
连接成功后会返回一个 deviceAdapter，可以用来向连接的设备发送 Wi-Fi、token 等数据。
try {
  // device参数是上一步获取的devices中的某一项
  const deviceAdapter = await bluetoothAdapter.connectDevice(device);

  if (!deviceAdapter) {
    throw {
      code: 'CONNECT_ERROR',
    };
  }
} catch (err) {
  console.error('连接设备出错');
}
在上面三步完成之后，我们已经通过蓝牙连接到了设备，并获得了可以与设备通信的 deviceAdapter，接下来就可以正式进行配网了。

BleCombo 配网参数

参数名
参数描述
类型
必填
wifiConfToken
Wi-Fi 设备配网 Token，从后台接口 生成 Wi-Fi 设备配网 Token 获取。
string
是
targetWifiInfo
目标 Wi-Fi 信息，需要设备去连接的 Wi-Fi 的信息。
WifiInfo
是
onProgress
配网过程执行到每个步骤时触发的回调，回调函数入参如下：
code：步骤代码，详见 配网步骤 小节。
msg：步骤描述，自行从 WifiConfStepDesp 用code取描述内容。
detail：步骤详情，根据每个步骤不同而不同。
function
是
onError
配网失败时触发，回调函数入参如下：
code：错误代码，详见 错误码 小节。
msg：错误描述，自行从 WifiConfErrorMsg 拿code取描述内容。
detail：错误详情。
function
是
onComplete
配网完成后触发，回调函数入参如下：
deviceInfo：设备信息。
function
是
deviceAdapter
用于和设备进行蓝牙通信的设备适配器实例，连接蓝牙之后获得，详见DeviceAdapter。
DeviceAdapter
是
familyId
家庭 ID，默认为：'default'，即用户默认家庭 ID。
string
否
roomId
房间 ID，默认为：''，即用户默认房间 ID。
string
否
bleComboProto
使用的蓝牙配网协议，目前支持 ESP 官方和 LLsync 两种协议。
'BLE_COMBO_ESP' / 'BLE_COMBO_LLSYNC'
否

WifiInfo 数据结构

属性名
属性描述
类型
必填
SSID
Wi-Fi 的 SSID。
string
是
password
Wi-Fi 的 密码。
string
是

示例代码

function BleComboConfigure({
  // 用于设备连接云端的token
  token,
  wifiInfo,
  familyId = 'default',
  roomId,
  // 连接设备之后获得
  deviceAdapter,
}) {
  /**
   * 这里可以进行一些UI进度更新操作
   */
  const onStepChange = (progress) => {
    console.log(progress);
  };

  // 这里是配网进行过程中的回调函数
  const onProgress = (data) => {
    console.info(data.code, data.detail);
    switch (data.code) {
      case WifiConfStepCode.PROTOCOL_START: // 开始配网
        onStepChange(1);
        break;
      case WifiConfStepCode.PROTOCOL_SUCCESS: // 设备联网成功，设备可以访问互联网
        onStepChange(2);
        break;
      case WifiConfStepCode.BUSINESS_QUERY_TOKEN_STATE_SUCCESS: // 发送token到设备成功，设备开始连接云端
        onStepChange(3);
        break;
      case WifiConfStepCode.WIFI_CONF_SUCCESS: // 配网成功
        onStepChange(4);
        break;
    }
  };

  const onComplete = ({ productId, deviceName }) => {
    // 配网成功后，可以拿到设备的 productId 和 设备名称
    console.log('配网成功', productId, deviceName);
  };

  const onError = async ({ code, detail }) => {
    console.error('配网出错', code, detail);
  };

  // 开始执行配网逻辑
  sdk.plugins.wifiConfBleCombo.start({
    wifiConfToken: token,
    targetWifiInfo: wifiInfo,
    deviceAdapter,
    familyId,
    roomId,
    onProgress,
    onError,
    onComplete,
  });
}

配网步骤

sdk.plugins['wifiConfBleCombo'].start(bleComboOpts) 配网过程中，每执行完一个步骤就会触发一次 onProgress 回调，入参为：{ code, detail } 形式。
步骤
描述
WifiConfStepCode.PROTOCOL_START
开始配网。
WifiConfStepCode.PROTOCOL_SUCCESS
设备联网成功，设备可以访问互联网。
WifiConfStepCode.BLE_SEND_TOKEN_START
开始发送 token 到设备，用于连接云端。
WifiConfStepCode.BLE_SEND_TOKEN_SUCCESS
发送 token 到设备成功，设备开始连接云端。
WifiConfStepCode.WIFI_CONF_SUCCESS
配网成功。

蓝牙辅助配网错误码

在 onError回调函数中，我们可以拿到配网失败的错误码。
CODE
描述
PROTOCOL_FAIL
设备连接失败。
BLE_SEND_TOKEN_ERROR
发送 token 到设备失败。
WIFI_CONF_FAIL
配网失败。

配网错误码

错误码
描述
UDP_NOT_RESPONSED
超时未收到设备响应。
UDP_CLOSED
设备连接中断。
UDP_ERROR
配网过程中触发 udp.onError 事件。
detail: { errMsg }，错误信息。
UDP_SEND_MSG_FAIL
与设备 UDP 通信时，发送消息失败。
CONNECT_SOFTAP_FAIL
手机连接设备热点失败。
detail: { errMsg }，错误信息。
BUSINESS_WIFI_RECONNECT_FAIL
手机连接 Wi-Fi 路由器失败。
detail: { errMsg }，错误信息。
BUSINESS_DEVICE_ERROR
收到设备响应的错误。
detail: { errMsg }，错误信息。
BUSINESS_INVALID_RESPONSE
收到非法的设备响应。
detail: { response }，具体的设备端响应。
BUSINESS_DEVICE_CONNECT_MQTT_FAIL
设备连接 MQTT 服务失败。
BUSINESS_DEVICE_CONNECT_WIFI_FAIL
设备连接目标 Wi-Fi 失败。
BUSINESS_QUERY_BIND_TOKEN_TIMEOUT
设备连接云端超时。
WIFI_CONF_FAIL
配网流程失败。
detail: { errMsg }，错误信息。
PROTOCOL_FAIL
配网协议失败。
detail: { errMsg }，错误信息。
PROTOCOL_TIMEOUT
配网协议超时。
PROTOCOL_INVALID_RESPONSE
配网协议收到非法响应。
detail: { errMsg }，错误信息。

自动错误处理

配网流程中会出现一些错误，在成功率不断优化的实践当中，总结一些可以自动处理的错误类型，处理成功后自动重试，全程用户无感知。
错误码
错误处理方式
PROTOCOL_TIMEOUT
超时未收到设备响应，其原因可能是中途网络被切走，导致设备和手机无法通信造成超时；自动处理方式：检查当前网络是不是目标网络，否则切到目标网络，重新配网。
UDP_ERROR
UDP 通道发生错误，可能的原因其一如上（中途网络被切走，导致设备和手机无法通信造成超时），其二是 Wi-Fi 切换之后，底层 UDP 还未切换，会发包失败；自动处理方式：延迟2s之后重新配网。
UDP_SEND_MSG_FAIL
同上两种处理方式。

模组日志收集

当发生错误的时候，只看 onProgress 或者 onError 里面打印出来的信息并不能准确定位到问题，需要结合设备端日志查看，我们制定了跟设备端的日志交互协议，原理如下：




示例代码

const { collectModuleLog } =  require('qcloud-iotexplorer-appdev-plugin-wificonf-core').utils;

collectModuleLog({
   // 用于上报的对象
   reporter: console,
   sdk: sdk,
})

日志上报打印详情

日志收集的过程以及结果会通过reporter.info(code, detail)的回调打印出来，可以通过这个方法来收集信息以及日志的上报。
步骤
描述
WifiConfStepCode.MODULE_REPORT_START
开始配网日志收集
WifiConfStepCode.MODULE_REPORT_CONNECT_WIFI_START
日志收集开始连接设备热点
WifiConfStepCode.MODULE_REPORT_CONNECT_WIFI_SUCCESS
日志收集连接设备热点成功
WifiConfStepCode.MODULE_REPORT_COMMUNICATE_AP_START
开始收集设备端日志
WifiConfStepCode.MODULE_REPORT_COMMUNICATE_AP_SUCCESS
收集成功。
detail: { moudleDetail}，日志详情。

错误码

错误码
描述
MODULE_REPORT_COMMUNICATE_AP_ERROR
和设备端通信失败。
MODULE_REPORT_TIMEOUT
收集日志超时

中国站
文档反馈
文档活动
message-icon联系我们
目录