Wi-Fi

更新时间：2025-04-29 10:48:12下载pdf

概述

封装了 Wi-Fi 协议的相关功能。

API 描述

tkl_wifi_init

OPERATE_RET tkl_wifi_init(WIFI_EVENT_CB cb)

函数描述
- 设置 Wi-Fi 工作状态
参数

输入/输出参数名描述

[in] cb Wi-Fi 工作状态回调
返回值
- OPRT_OK：成功
- Others：失败

输入/输出	参数名	描述
[in]	cb	Wi-Fi 工作状态回调

tkl_wifi_scan_ap

OPERATE_RET tkl_wifi_scan_ap(CONST SCHAR_T *ssid, AP_IF_S **ap_ary, UINT_T *num)

函数描述
- 扫描当前环境，获取当前环境中的热点信息
参数

输入/输出参数名描述

[in] ssid 如果 ssid = NULL 则扫描所有热点，其他则扫描指定热点

[out] ap_ary 扫描结果信息

[out] num 扫描热点个数
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_AP_SCAN_FAILED：扫描失败

输入/输出	参数名	描述
[in]	ssid	如果 `ssid` = `NULL` 则扫描所有热点，其他则扫描指定热点
[out]	ap_ary	扫描结果信息
[out]	num	扫描热点个数

阻塞函数。
只能扫描到当前国家码信道列表里的热点。
当环境存在指定 SSID 的热点，扫描到该 SSID 的成功率要超过 98%。
热点需要在该 API 内分配内存（扫描到多个热点，需要分配连续的内存空间）。
释放该内存由 TuyaOS 主动调用 tkl_wifi_release_ap 释放。

tkl_wifi_release_ap

OPERATE_RET tkl_wifi_release_ap(AP_IF_S *ap)

函数描述
- 释放热点信息资源
参数

输入/输出参数名描述

[in] ap 释放 tkl_wifi_scan_ap 获取到的热点信息
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_AP_RELEASE_FAILED：失败

输入/输出	参数名	描述
[in]	ap	释放 `tkl_wifi_scan_ap` 获取到的热点信息

tkl_wifi_start_ap

OPERATE_RET tkl_wifi_start_ap(CONST WF_AP_CFG_IF_S *cfg)

函数描述
- 启动热点模式
参数

输入/输出参数名描述

[in] cfg 热点配置参数
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_AP_START_FAILED：失败

输入/输出	参数名	描述
[in]	cfg	热点配置参数

需要根据 max_conn 来设置热点模式下最多允许多少个 STA 能连接成功。
需要根据 IP 信息来设置热点模式下的 IP 信息。
Station AP 模式下，如果接入点（Access point port，AP port）有连接，客户端（Station port）连接路由器，但连接失败后，AP port 不可以有断连情况，可以收发广播包。
配网 EZ + 热点共存：
- Soft AP 或者 Station AP 模式下可以使能 Sniffer 功能以及可以切换信道。
- 使能 Sniffer 功能之后，扔给回调的数据要包括 AP port 的设备连接请求包。

tkl_wifi_stop_ap

OPERATE_RET tkl_wifi_stop_ap(VOID_T)

函数描述
- 停止热点模式
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_AP_STOP_FAILED：失败

需要针对设备当前所处模式 Soft AP 或 Station AP 做不同的关闭逻辑。
Station AP 模式下，如果 Station port 端有连接，关闭 AP port 过程 Station port 不能有断连情况。

tkl_wifi_set_cur_channel

OPERATE_RET tkl_wifi_set_cur_channel(CONST UCHAR_T chan)

函数描述
- 设置信道
参数

输入/输出参数名描述

[in] chan 信道
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_CHAN_SET_FAILED：失败

输入/输出	参数名	描述
[in]	chan	信道

设置当前国家码信道范围之外的信道报失败。
支持在 Sniffer 回调里设置信道。

tkl_wifi_get_cur_channel

OPERATE_RET tkl_wifi_get_cur_channel(UCHAR_T *chan);

函数描述
- 获取当前信道
参数

输入/输出参数名描述

[out] chan 信道
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_CHAN_GET_FAILED：失败

输入/输出	参数名	描述
[out]	chan	信道

tkl_wifi_set_sniffer

OPERATE_RET tkl_wifi_set_sniffer(CONST BOOL_T en, CONST SNIFFER_CALLBACK cb)

函数描述
- 设置 Sniffer 功能开关
参数

输入/输出参数名描述

[in] en 开或关 Sniffer 功能

[in] cb 抓包数据回调
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_SNIFFER_SET_FAILED：失败

输入/输出	参数名	描述
[in]	en	开或关 Sniffer 功能
[in]	cb	抓包数据回调

返给应用的数据要包括管理包数据。

tkl_wifi_get_ip

OPERATE_RET tkl_wifi_get_ip(CONST WF_IF_E wf, NW_IP_S *ip)

函数描述
- 获取 Wi-Fi 的 IP 信息（IP 地址、网关地址、地址掩码）
参数
输入/输出参数名描述
[in]

wf
Wi-Fi 模式：
WF_STATION
WF_AP
[out] ip IP 信息
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_IP_GET_FAILED：失败

输入/输出	参数名	描述
[in]	wf	Wi-Fi 模式： WF_STATION WF_AP
[out]	ip	IP 信息

需要区分不同模式（依据传参 Wi-Fi）下的 IP 信息。

tkl_wifi_set_ip

OPERATE_RET tkl_wifi_set_ip(CONST WF_IF_E wf, NW_IP_S *ip)

函数描述
- 设置 Wi-Fi 的静态 IP 信息（IP 地址、网关地址、地址掩码）
参数
输入/输出参数名描述
[in]

wf
Wi-Fi 模式：
WF_STATION
WF_AP
[in] ip IP 信息
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_IP_GET_FAILED：失败

输入/输出	参数名	描述
[in]	wf	Wi-Fi 模式： WF_STATION WF_AP
[in]	ip	IP 信息

需要区分不同模式（依据传参 Wi-Fi）下的 IP 信息。

tkl_wifi_set_mac

OPERATE_RET tkl_wifi_set_mac(CONST WF_IF_E wf, CONST NW_MAC_S *mac)

函数描述
- 设置 MAC 地址
参数
输入/输出参数名描述
[in]

wf
Wi-Fi 模式：
WF_STATION
WF_AP
[in] mac MAC 地址
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_MAC_SET_FAILED：失败

输入/输出	参数名	描述
[in]	wf	Wi-Fi 模式： WF_STATION WF_AP
[in]	mac	MAC 地址

永久生效，断电不丢失。

tkl_wifi_get_mac

OPERATE_RET tkl_wifi_get_mac(CONST WF_IF_E wf, NW_MAC_S *mac);

函数描述
- 获取 MAC 地址。
参数
输入/输出参数名描述
[in]

wf
Wi-Fi 模式：
WF_STATION
WF_AP
[out] mac MAC 地址
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_MAC_GET_FAILED：失败

输入/输出	参数名	描述
[in]	wf	Wi-Fi 模式： WF_STATION WF_AP
[out]	mac	MAC 地址

Station AP 模式下的 MAC 地址需要区分工作模式（依据传参 Wi-Fi）。

tkl_wifi_set_work_mode

OPERATE_RET tkl_wifi_set_work_mode(CONST WF_WK_MD_E mode)

函数描述
- 设置 Wi-Fi 工作模式。
参数
输入/输出参数名描述
[in]

mode
Wi-Fi 工作模式：
WWM_LOWPOWER ：关闭 Wi-Fi 模块
WWM_SNIFFER
WWM_STATION
WWM_SOFTAP
WWM_STATIONAP
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_WORKMODE_SET_FAILED：失败

输入/输出	参数名	描述
[in]	mode	Wi-Fi 工作模式： WWM_LOWPOWER ：关闭 Wi-Fi 模块 WWM_SNIFFER WWM_STATION WWM_SOFTAP WWM_STATIONAP

从设备上电到调用涂鸦入口函数 void tuya_app_main(void) 要求在 200ms 以内。
如果设备初始化时间超过 200ms，底层可以做一些必要的初始化之后就调用涂鸦入口函数，将耗时间的 Wi-Fi 初始化放在另一个线程执行。
tuya_hal_wifi_set_work_mode 是涂鸦业务使用 Wi-Fi 调用的第一个 API，在这个 Wi-Fi 需要判断 Wi-Fi 初始化是否结束。如果没结束，要在这里等到结束才开始往下执行（只需要判断一次）。
如果设备从上电到调用涂鸦入口函数少于 200ms，无需考虑这点。

tkl_wifi_get_work_mode

OPERATE_RET tkl_wifi_get_work_mode(WF_WK_MD_E *mode)

函数描述
- 获取 Wi-Fi 工作模式
参数
输入/输出参数名描述
[out]

mode
Wi-Fi 工作模式：
WWM_LOWPOWER ：关闭 Wi-Fi 模块
WWM_SNIFFER
WWM_STATION
WWM_SOFTAP
WWM_STATIONAP
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_WORKMODE_GET_FAILED：失败

输入/输出	参数名	描述
[out]	mode	Wi-Fi 工作模式： WWM_LOWPOWER ：关闭 Wi-Fi 模块 WWM_SNIFFER WWM_STATION WWM_SOFTAP WWM_STATIONAP

tkl_wifi_get_connected_ap_info

OPERATE_RET tkl_wifi_get_connected_ap_info(FAST_WF_CONNECTED_AP_INFO_T **fast_ap_info)

函数描述
- 获取所连热点信息，用于快连功能
参数

输入/输出参数名描述

[out] fast_ap_info 所连热点信息
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_APINFO_GET_FAILED：失败

输入/输出	参数名	描述
[out]	fast_ap_info	所连热点信息

fast_ap_info 需要在该 API 内动态申请内存。
每次重连路由器成功都会获取一次路由器信息，如有更新会同步到 Flash。

tkl_wifi_get_bssid

OPERATE_RET tkl_wifi_get_bssid(UCHAR_T *mac)

函数描述
- 获取所连热点的 MAC 地址。
参数

输入/输出参数名描述

[out] mac MAC 地址
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_BSSID_GET_FAILED：失败

输入/输出	参数名	描述
[out]	mac	MAC 地址

tkl_wifi_set_country_code

OPERATE_RET tkl_wifi_set_country_code(CONST COUNTRY_CODE_E ccode)

函数描述
- 设置国家码

参数

输入/输出	参数名	描述
[in]	ccode	国家码： COUNTRY_CODE_CN ：中国区信道 1-13 COUNTRY_CODE_US：美国区信道 1-11 COUNTRY_CODE_JP ：日本区信道1-14 COUNTRY_CODE_EU：欧洲区信道 1-13

返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_CCODE_SET_FAILED：失败

国家码暂时只需要支持中国区（CN 1-13）、美国区（US 1-11）、日本区（JP 1-14）、欧洲区（EU 1-13）。
针对不同的国家码，需要达到的要求如下：
- 扫描路由器时，只能扫到国家码对应信道列表的热点。
- 欧洲区需要实现欧洲自适应功能。
- 设置信道时，设置的信道不在当前国家码的信道列表范围之内，设置信道返回 Error。

tkl_wifi_set_rf_calibrated

OPERATE_RET tkl_wifi_set_rf_calibrated(VOID_T);

函数描述
- 检查 RF 是否校准过
返回值
true：已校准
false：未校准

tkl_wifi_set_lp_mode

OPERATE_RET tkl_wifi_set_lp_mode(CONST BOOL_T enable, CONST UCHAR_T dtim)

函数描述
- Wi-Fi 低功耗设置
参数

输入/输出参数名描述

[in] enable 是否开启 Wi-Fi 低功耗模式

[in] dtim DTIM 参数
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_WF_LPMODE_SET_FAILED：失败

输入/输出	参数名	描述
[in]	enable	是否开启 Wi-Fi 低功耗模式
[in]	dtim	DTIM 参数

tkl_wifi_station_fast_connect

OPERATE_RET tkl_wifi_station_fast_connect(CONST FAST_WF_CONNECTED_AP_INFO_T *fast_ap_info)

函数描述
- 快速连接路由器
参数

输入/输出参数名描述

[in] fast_ap_info 快连所需的热点信息
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_FAST_CONN_FAILED：失败

输入/输出	参数名	描述
[in]	fast_ap_info	快连所需的热点信息

配过网且重启之后第一次连接才会调用这个函数。

tkl_wifi_station_connect

OPERATE_RET tkl_wifi_station_connect(CONST SCHAR_T *ssid, CONST SCHAR_T *passwd)

函数描述
- 连接路由器
参数

输入/输出参数名描述

[in] ssid SSID

[in] passwd Password
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_CONN_FAILED：失败

输入/输出	参数名	描述
[in]	ssid	SSID
[in]	passwd	Password

非阻塞，启动连接流程成功后，上层会每隔 1s 钟调用 tuya_hal_wifi_station_get_status 查询 Wi-Fi 连接状态。
需要使能自动重连功能，重连时间在 1min 以内即可，上层断连情况下会每隔 1min 发起一次重连。

tkl_wifi_station_disconnect

OPERATE_RET tkl_wifi_station_disconnect(VOID_T)

函数描述
- 断开路由器
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_DISCONN_FAILED：失败

tkl_wifi_station_get_conn_ap_rssi

OPERATE_RET tkl_wifi_station_get_conn_ap_rssi(SCHAR_T *rssi)

函数描述

获取所连热点的信号强度
参数

输入/输出参数名描述

[out] rssi 信号强度
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_RSSI_GET_FAILED：失败

输入/输出	参数名	描述
[out]	rssi	信号强度

不移动设备和路由器的位置，多次获取 RSSI 只能出现小范围的波动。
移动设备和路由器的位置，获取 RSSI 会有对应的变化。

tkl_wifi_station_get_status

OPERATE_RET tkl_wifi_station_get_status(WF_STATION_STAT_E *stat)

函数描述
- 获取 Wi-Fi 当前的连接状态
参数
输入/输出参数名描述
[out]

stat
连接状态：
WSS_IDLE
WSS_CONNECTING
WSS_PASSWD_WRONG
WSS_CONN_FAIL
WSS_CONN_SUCCESS
WSS_GOT_IP
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_STAT_GET_FAILED：失败

输入/输出	参数名	描述
[out]	stat	连接状态： WSS_IDLE WSS_CONNECTING WSS_PASSWD_WRONG WSS_CONN_FAIL WSS_CONN_SUCCESS WSS_GOT_IP

tkl_wifi_send_mgnt

OPERATE_RET tkl_wifi_send_mgnt(CONST UCHAR_T *buf, CONST UINT_T len)

函数描述
- 发送管理包数据
参数

输入/输出参数名描述

[in] buf 管理包数据缓冲区（Buffer)

[in] len 管理包数据长度
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_MGNT_SEND_FAILED：失败

输入/输出	参数名	描述
[in]	buf	管理包数据缓冲区（Buffer)
[in]	len	管理包数据长度

tkl_wifi_register_recv_mgnt_callback

OPERATE_RET tkl_wifi_register_recv_mgnt_callback(CONST BOOL_T enable, CONST WIFI_REV_MGNT_CB recv_cb)

函数描述
- 设置应用层是否接收管理包数据
参数

输入/输出参数名描述

[in] enable 是否开启接收管理包数据

[in] recv_cb 接收管理包数据回调
返回值
- OPRT_OS_ADAPTER_OK：成功
- OPRT_OS_ADAPTER_MGNT_REG_FAILED：失败

输入/输出	参数名	描述
[in]	enable	是否开启接收管理包数据
[in]	recv_cb	接收管理包数据回调

上一篇GPIO

下一篇类型开发包