设备配网

概述

智能生活 App SDK 提供了把智能设备配置上路由器或网关的能力。以常见的 Wi-Fi 快连为例，SDK 从云端获取配网 Token，再经由 App 来广播配网信息（路由 ID、密码、配网 Token）。智能设备接收到后，开始快速激活，同时连接到 App 和云端，开启设备上云的第一步。

功能说明

鸿蒙 SDK 设备配网支撑的具体能力包括：

• Wi-Fi 设备配网
  • Wi-Fi 快连模式（又称 EZ 模式）
  • 热点模式（又称 AP 模式）
• 蓝牙设备配网
  • 低功耗蓝牙配网
  • 蓝牙 Wi-Fi 双模配网
• 有线设备配网
• 子设备配网
• 摄像头二维码配网
• 扫描设备二维码配网

使用说明

引入模块

import {
  ITSmartActivator,
  ITSmartActivatorListener,
  TSmartActivator,
  TSmartActivatorBuilder,
  TSmartActivatorStep,
  TSmartDeviceType,
  TSmartScanMode,
  TSmartScannerBuilder,
  TSmartScannerListener,
  TSmartScannerResult
} from '@thingsmart/activator';

名词解释

本文介绍设备配网过程中涉及到的部分名词，有关更多名词的说明，请参考 名词解释。

名词	说明
Wi-Fi 设备	采用涂鸦 Wi-Fi 模组连接路由器，和 App 以及云端进行数据交互的智能设备
Wi-Fi 快连配网	又称快连模式。大致流程如下： 1. App 把配网数据包打包到 802.11 数据包的指定区域中，发送到周围环境 2. 智能设备的 Wi-Fi 模组处于混杂模式下，监听捕获网络中的所有报文 3. Wi-Fi 模组按照约定的协议数据格式，解析出 App 发出配网信息包
热点配网	又称热点模式，手机作为 STA（STAtion）连接智能设备的热点，双方建立一个 Socket 连接，通过约定端口交互数据
摄像头扫码配网	摄像头设备通过扫描 App 上的二维码，来获取配网数据信息
有线设备	通过有线网络连接路由器的设备，例如 Zigbee 有线网关、有线摄像头等
子设备	通过网关来跟 App 以及云端数据交互的设备，例如 Zigbee 子设备
Zigbee	Zigbee 技术是一种近距离、低复杂度、低功耗、低速率、低成本的双向无线通讯技术。主要用于距离短、功耗低且传输速率不高的各种电子设备之间进行数据传输，以及典型的有周期性数据、间歇性数据和低反应时间数据传输的应用
Zigbee 网关	融合 Zigbee 网络中协调器和 Wi-Fi 功能的设备，负责 Zigbee 网络的组建及数据信息存储
Zigbee 子设备	Zigbee 网络中的路由或者终端设备，负责数据转发或者终端控制响应

API 介绍

TSmartActivatorRequester

配网相关请求类

getActivatorToken

获取配网 Token。

getActivatorToken(homeId: number): Promise<TSmartActivatorToken | null | undefined>

参数：

参数名	类型	是否必填	说明
homeId	number	是	家庭 ID

返回值：

类型	说明
Promise	返回结果为 TSmartActivatorToken | null | undefined 类型的 Promise

parseQRCode

解析二维码，用于扫设备二维码配网时，解析设备上的二维码数据。

parseQRCode(content: string): Promise<Record<string, Object>>

参数：

参数名	类型	是否必填	说明
content	string	是	摄像头扫码后获取的二维码的文本内容

返回值：

类型	说明
Promise	返回结果为 Record<string, Object> 类型的 Promise

getMQTTDirectlyActivatorToken

用于扫描设备二维码配网时获取 Token。

getMQTTDirectlyActivatorToken(homeId: number, uuid: string): Promise<TSmartActivatorToken>

参数：

参数名	类型	是否必填	说明
homeId	number	是	家庭 ID
uuid	string	是	从二维码中解析得到的设备 UUID

返回值：

类型	说明
Promise	返回结果为 TSmartActivatorToken 类型的 Promise

TSmartScannerBuilder

设备扫描类

constructor

constructor(scanListener: TSmartScannerListener)

参数：

参数名	类型	是否必填	说明
scanListener	TSmartScannerListener	是	扫描监听器，扫到设备会调用监听器内部的方法

setScanTimeout

需要在开始扫描之前调用才有效果。

setScanTimeout(scanTimeout: number): TSmartScannerBuilder

参数：

参数名	类型	是否必填	说明
scanTimeout	number	是	超时时间，单位毫秒，默认值 120 秒。到设定的时间会停止扫描

返回值：

类型	说明
TSmartScannerBuilder	返回结果为设备扫描类的实例，方便链式调用其它设置方法

addScanMode

添加指定的扫描方式，主要包含蓝牙类的扫描和局域网扫描。

addScanMode(scanMode: TSmartScanMode): TSmartScannerBuilder

参数：

参数名	类型	是否必填	说明
scanMode	TSmartScanMode	是	扫描模式

返回值：

类型	说明
TSmartScannerBuilder	返回结果为设备扫描类的实例，方便链式调用其它设置方法

startScan

开始扫描，扫描结果通过扫描监听器回调。

startScan(): void

stopScan

停止所有的扫描模式

stopScan(): void

stopScanMode

停止指定的扫描模式

stopScanMode(model: TSmartScanMode): void

TSmartScannerListener

名称	类型	是否必填	说明
onDeviceFound	(scanResult: TSmartScannerResult) => void	是	设备发现监听方法，当发现设备时会调用
onStop	(error: Error) => void	否	设备发现停止回调方法：当发现设备超时时会调用，主动停止后不会再有此回调

TSmartScannerResult

名称	类型	是否必填	说明
uniqueId	string	是	设备唯一标记
productId	string	是	产品 ID
deviceType	TSmartDeviceType	是	设备类型
name	string	是	设备名称。通过网络请求获取，请求失败时会默认为 New Device
icon	string	是	设备图标的 URL。通过网络请求获取，请求失败时默认空字符串
scannedBleDevice	Device	否	当设备类型是蓝牙或双模设备时有值

TSmartScanMode

export enum TSmartScanMode {
  SCAN_MODE_BLE = 1 << 0,       // 蓝牙扫描
  SCAN_MODE_LAN = 1 << 1,       // 局域网扫描
}

TSmartDeviceType

export enum TSmartDeviceType {
  BLE,              // 蓝牙设备
  WIFI_BLE,         // 双模设备
  WIRED             // 有线设备
}

TSmartActivator

设备配网类

createActivator

createActivator(builder: TSmartActivatorBuilder): ITSmartActivator

参数：

参数名	类型	是否必填	说明
builder	TSmartActivatorBuilder	是	通过 builder，创建遵循 ITSmartActivator 接口的实例

返回值：

类型	说明
ITSmartActivator	返回值为遵循 ITSmartActivator 接口类型的实例

buildApActivatorBuilder

AP 配网时，调用此方法创建 builder。

buildApActivatorBuilder(
    ssid: string,
    password: string,
    timeout: number = 120000,
    token: TSmartActivatorToken,
    listener: ITSmartActivatorListener,
    homeId: number,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

参数：

参数名	类型	是否必填	说明
ssid	string	是	Wi-Fi 名称
password	string	是	Wi-Fi 密码
timeout	number	否	超时时间，单位毫秒，默认 120 秒
token	TSmartActivatorToken	是	Token，通过 getActivatorToken 获取
listener	ITSmartActivatorListener	是	配网监听器，配网结果会在监听器中回调
homeId	number	是	家庭 ID
extraParameters	Record<string, Object>	否	预留额外参数

返回值：

类型	说明
TSmartActivatorBuilder	返回类型为 TSmartActivatorBuilder 的 builder

buildEzActivatorBuilder

EZ 配网时，调用此方法创建 builder。

buildEzActivatorBuilder(
    ssid: string,
    password: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    homeId: number,
    token?: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

参数：

参数名	类型	是否必填	说明
ssid	string	是	Wi-Fi 名称
password	string	是	Wi-Fi 密码
timeout	number	否	超时时间，单位毫秒，默认 120 秒
listener	ITSmartActivatorListener	是	配网监听器，配网结果会在监听器中回调
homeId	number	是	家庭 ID
token	TSmartActivatorToken	否	通过 getActivatorToken 获取，如果不传，则内部会通过 homeId 获取
extraParameters	Record<string, Object>	否	预留额外参数

返回值：

类型	说明
TSmartActivatorBuilder	返回类型为 TSmartActivatorBuilder 的 builder

buildWiredActivatorBuilder

局域网有线设备配网时，调用此方法创建 builder。

buildWiredActivatorBuilder(
    homeId: number,
    gwId: string,
    productId: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    token?: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

参数：

参数名	类型	是否必填	说明
homeId	number	是	家庭 ID
gwId	string	是	对应 TSmartScannerResult 中的 uniqueId
productId	string	是	对应 TSmartScannerResult 中的 productId
timeout	number	否	超时时间，单位毫秒，默认 120 秒
listener	ITSmartActivatorListener	是	配网监听器，配网结果会在监听器中回调
token	TSmartActivatorToken	否	通过 getActivatorToken 获取，如果不传，则内部会通过 homeId 获取
extraParameters	Record<string, Object>	否	预留额外参数

返回值：

类型	说明
TSmartActivatorBuilder	返回类型为 TSmartActivatorBuilder 的 builder

buildSubDeviceActivatorBuilder

网关子设备配网时，调用此方法创建 builder。

buildSubDeviceActivatorBuilder(gwId: string, timeout: number = 120000, listener: ITSmartActivatorListener, extraParameters?: Record<string, Object>): TSmartActivatorBuilder

参数：

参数名	类型	是否必填	说明
gwId	string	是	网关设备的虚拟 ID
timeout	number	否	超时时间，单位毫秒，默认 120 秒
listener	ITSmartActivatorListener	是	配网监听器，配网结果会在监听器中回调
extraParameters	Record<string, Object>	否	预留额外参数

返回值：

类型	说明
TSmartActivatorBuilder	返回类型为 TSmartActivatorBuilder 的 builder

buildBleActivatorBuilder

蓝牙单点设备配网时，调用此方法创建 builder。

buildBleActivatorBuilder(
    homeId: number,
    timeout: number = 60000,
    listener: ITSmartActivatorListener,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

参数：

参数名	类型	是否必填	说明
homeId	number	是	家庭 ID
timeout	number	否	超时时间，单位毫秒，默认 60 秒
listener	ITSmartActivatorListener	是	配网监听器，配网结果会在监听器中回调
extraParameters	Record<string, Object>	否	预留额外参数

返回值：

类型	说明
TSmartActivatorBuilder	返回类型为 TSmartActivatorBuilder 的 builder

buildBleWifiActivatorBuilder

蓝牙双模设备配网时，调用此方法创建 builder。

buildBleWifiActivatorBuilder(
    homeId: number,
    ssid: string,
    password: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    token?: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

参数：

参数名	类型	是否必填	说明
homeId	number	是	家庭 ID
ssid	string	是	Wi-Fi 名称
password	string	是	Wi-Fi 密码
timeout	number	否	超时时间，单位毫秒，默认 120 秒
token	TSmartActivatorToken	否	通过 getActivatorToken 获取，如果不传，则内部会通过 homeId 获取
listener	ITSmartActivatorListener	是	配网监听器，配网结果会在监听器中回调
extraParameters	Record<string, Object>	否	预留额外参数

返回值：

类型	说明
TSmartActivatorBuilder	返回类型为 TSmartActivatorBuilder 的 builder

buildQRCodeActivatorBuilder

IPC 类设备扫 App 上的二维码配网时，调用此方法创建 builder。二维码字符串通过 getQRCodeString 方法获得。

buildQRCodeActivatorBuilder(
    homeId: number,
    ssid: string,
    password: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    token: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

参数：

参数名	类型	是否必填	说明
homeId	number	是	家庭 ID
ssid	string	是	Wi-Fi 名称
password	string	是	Wi-Fi 密码
timeout	number	否	超时时间，单位毫秒，默认 120 秒
listener	ITSmartActivatorListener	是	配网监听器，配网结果会在监听器中回调
token	TSmartActivatorToken	是	通过 getActivatorToken 获取，注意要与 getQRCodeString 方法中的 Token 保持一致
extraParameters	Record<string, Object>	否	预留额外参数

返回值：

类型	说明
TSmartActivatorBuilder	返回类型为 TSmartActivatorBuilder 的 builder

getQRCodeString

将 ssid、password、token 组装成一个字符串，用于生成二维码供 IPC 类设备扫码配网。

getQRCodeString(ssid: string, password: string, token: TSmartActivatorToken): string

参数：

参数名	类型	是否必填	说明
ssid	string	是	Wi-Fi 名称
password	string	是	Wi-Fi 密码
token	TSmartActivatorToken	是	通过 getActivatorToken 获取，注意要与 buildQRCodeActivatorBuilder 方法中的 Token 保持一致

返回值：

类型	说明
string	返回的字符串用于生成二维码

buildMQTTDirectlyActivatorBuilder

App 扫设备二维码配网时，调用此方法创建 builder。其中的参数 UUID 是通过二维码解析得到的，调用 parseQRCode 方法解析。参数 Token 是通过调用 getMQTTDirectlyActivatorToken 方法获取的。

buildMQTTDirectlyActivatorBuilder(
    homeId: number,
    uuid: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    token?: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

参数：

参数名	类型	是否必填	说明
homeId	number	是	家庭 ID
uuid	string	是	设备 UUID，通过调用 parseQRCode 方法解析得到
timeout	number	否	超时时间，单位毫秒，默认 120 秒
listener	ITSmartActivatorListener	是	配网监听器，配网结果会在监听器中回调
token	TSmartActivatorToken	是	通过 getMQTTDirectlyActivatorToken 获取
extraParameters	Record<string, Object>	否	预留额外参数

返回值：

类型	说明
TSmartActivatorBuilder	返回类型为 TSmartActivatorBuilder 的 builder

ITSmartActivatorListener

配网监听器

名称	类型	是否必填	说明
onActiveSetpAndError	(step: TSmartActivatorStep, error?: Error, device?: TSmartDeviceModel) => void	否	配网过程监听方法，当配网过程中有变化或者错误时会回调
onActiveSuccess	(deviceModel: TSmartDeviceModel) => void	是	配网成功时会回调

TSmartActivatorStep

enum TSmartActivatorStep {
  Start,        // 配网开始
  Found,        // 轮询到设备
  Registered,   // 设备注册
  Initialized,  // 设备激活完成
  TimeOut,      // 配网超时
}

TSmartActivatorError

配网相关错误码，可以根据 Error 的 name 判断对应的错误码。

enum TSmartActivatorError {
  //   未定义错误
  Unknown = 'UNKNOWN',
  //   参数错误
  ParameterError = 'PARAM_ERROR',
  //   超时
  Timeout = 'TIMEOUT',
  //   配网token错误，没有获取到token
  TokenError = 'TOKEN_ERROR',
  //   蓝牙配网失败
  BleActiveError = 'BLE_ACTIVE_ERROR',
  //   强绑定设备，设备已被绑定
  DeviceAlreadyBind = 'DEVICE_ALREADY_BIND',// 这个值不要动，与云端的错误码对应的
  //   双模配网失败
  BleWifiActiveError = 'BLE_WIFI_ACTIVE_ERROR'
}

appendDevice

添加配网设备，对于蓝牙和双模类型的设备，需要先调用此方法添加待配网设备，再开始配网。

appendDevice(...device: Device[]): void

startActive

开始配网

startActive(): void

stopActive

停止配网

stopActive(): void