闪电配网

更新时间:2024-06-25 06:09:57下载pdf

涂鸦 闪电配网 是基于 IEEE 802.11 标准中 Beacon、Probe Request、Probe Respone 帧实现的一机一密配网方案。闪电配网由云端动态生成密钥和配网数据,安全接入云端。涂鸦闪电配网同时支持未配网设备配网、已配网设备无感更换路由器。

功能描述

  • 首次配网:指通过设备已经配网成功的设备,将 Wi-Fi 信息发送给另一台待配网的设备,从而达到免密配网。此时,无须用户输入配网信息,对于已经拥有涂鸦设备的用户,体验较好。

  • 二次配网:指设备已经激活成功,但路由器修改了密码,导致设备掉线。常规设备只有重新配网,才能上线。然而,集成涂鸦闪电二次配网接口的路由器 允许设备不需要重新配网,即可自动连接路由器。

名词解释

名词 解释
闪电配网
(Pegasus)
也称无感配网,采用一机一密云端动态生成配网密钥,安全性高。
已配网者
(Server)
已连接云端并具有闪电配网服务提供能力的智能设备。例如路由器、Wi-Fi 网关、Wi-Fi 音箱及 Wi-Fi 智能 智能设备。
待配网者
(Client)
待连接云端并具有闪电配网能力的智能设备。例如 Wi-Fi 网关、Wi-Fi 音箱及 Wi-Fi 智能 智能设备。
首次配网 待配网者获取路由器 SSID、密码和配网 Token 后连接至云端激活成已配网者的过程。
二次配网 路由器修改密码后,主动重连掉线的设备,至设备重新激活的过程。

配网流程

首次闪电配网

App云端已配网者待配网者在 App 上添加设备发送闪电配网命令通知设备开启闪电配网开启闪电配网,发送闪电配网信标搜索闪电配网信标,锁定信道发送设备信息设备信息接收确认将设备信息推送给云端,获取加密密钥返回加密密钥发送密钥交换请求发送密钥交换确认响应计算密钥发送加密后的 Wi-Fi 信息和 Token解密消息,开始连接路由器连云激活查询激活的设备返回激活成功的设备App云端已配网者待配网者

二次闪电配网

已配网者待配网者App云端用户修改了 SSID 和密码,路由器发送闪电配网信标设备与路由器断开且重连 1 分钟超时后,触发设备闪电二次配网显示设备离线搜索闪电配网信标,锁定信道,发送设备信息设备信息接收确认将设备信息推送给云端,获取加密密钥发送密钥交换请求发送密钥交换确认响应计算密钥发送加密后的 SSID 和密码解密消息,开始连接路由器MQTT 上线查询设备上线返回设备上线信息显示设备上线已配网者待配网者App云端

开发指导

运行环境

由于每个模组上的资源不一样,并不会打开所有配网方式,您需要检查 tuya_iot_config.h 确认如下宏定义是否定义:

#define ENABLE_WIFI_PEGASUS 1

对接开发

  • 闪电首次配网:属于 TuyaOS 开发框架内部集成的功能,无须您二次开发。请确认框架是否支持该功能。您可以在 设备初始化 时传入 WF_START_SMART_AP_CONCURRENT 参数,以此触发设备首次闪电配网。

  • 闪电二次配网:需要您对路由器设备进行对接开发。

API 说明

以下均为二次配网功能接口的描述。

获取本设备路由 SSID 和密码

/**
* @brief get ssid and password
*
* @param[in] : slen   外部为存放 SSID 申请的内存长度
* @param[in] : plen   外部为存放 PASSWORD 申请的内存长度
* @param[out] : ssid   存放 SSID 内存地址
* @param[out] : passwd 存放 PASSWORD 内存地址
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_get_ssid_passwd(uint8_t *ssid, int32_t slen, uint8_t *passwd, int32_t plen);

获取本机 Mac 地址

/* tuya sdk definition of MAC info */
typedef struct
{
    uint8_t mac[6]; /* mac address */
}NW_MAC_S;

/**
* @brief get mac address
*
* @param[out] : mac: mac address
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_get_mac(NW_MAC_S *mac);

注册 Wi-Fi 管理帧回调

typedef void (*PEGASUS_REV_MGNT_CB)(uint8_t *vsie, uint32_t vsie_len, NW_MAC_S *src_mac, NW_MAC_S *dst_mac);

/**
* @brief register callback function for receive management frame
*
* @param[in] : enable   是否使能管理帧回调 TRUE: 开启接收管理帧回调 FALSE: 关闭接收管理帧回调
* @param[in] : recv_cb 管理帧回调
* @param[in] : tuya_oui 涂鸦 OUI 字段(根据这个字段把带有涂鸦 OUI 的 VSIE 上报)
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_register_recv_mgnt_callback(bool enable, PEGASUS_REV_MGNT_CB recv_cb, uint8_t *tuya_oui);

控制路由器发送 VSIE 的 Beacon

该接口能控制路由器发送带特定 VSIE(vendor-specific information element,厂商特定信元)的 Beacon。若不配置,路由器按原方式发送正常的 Beacon。

/**
* @brief   config Beacon frame
*
* @param[in] : start    配置开始发送带特定 vsie 的 Beacon
* @param[in] : vsie     管理帧 vsie 内容
* @param[in] : vsie_len 管理帧 vsie 内容长度
* @param[in] : timeout 发送特定 Beacon 的超时时间
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_beacon_config(bool start, uint8_t *vsie, uint32_t vsie_len, uint32_t timeout);

发送 VSIE 的 Probe Response 帧

/**
* @brief send probe response management frame
*
* @param[in] : vsie     管理帧 vsie 内容
* @param[in] : vsie_len 管理帧 vsie 内容长度
* @param[in] : ssid     管理帧 SSID
* @param[in] : srcmac   管理帧源 MAC
* @param[in] : srcmac   管理帧目的 MAC
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_send_probe_response_mgnt(const uint8_t *vsie, const uint32_t vsie_len, const uint8_t* ssid, NW_MAC_S *srcmac, NW_MAC_S *dstmac);

开发平台限制

  • 待配网设备必须具有发送 IEEE 802.11 协议中的 Probe Request、接收 Probe Respone 帧和 Beacon 帧的能力,并能处理 VSIE 中的 OUI(Organizationally unique identifier,特定组织唯一标识符)。

  • 已配网设备具有接收 IEEE 802.11 协议中的 Probe Request、发送 Probe Respone 帧和 Beacon 帧的能力,并能处理 VSIE 中的 OUI。

常见问题

如何确认设备首次闪电配网成功?

如果在 App(例如 智能生活)上添加设备时候,无用户输入 SSID 和密码的过程,设备添加成功,即表示闪电配网成功。

必须是路由器才能集成二次配网吗?

是的。

因为二次配网的触发条件是用户修改了 SSID 和密码,导致设备断开与路由器连接,所以需要路由器集成了 SDK 后才支持该功能。