Hotspot#
Hotspot 提供 Wi-Fi SoftAP(Software Access Point)功能,支持开启/关闭热点、配置基本与扩展参数、查询已连接 STA(Station)信息以及断开指定 STA 连接。
模块公共头文件
#include "middleware/services/wifi/wifi_hotspot.h"
#include "middleware/services/wifi/wifi_hotspot_config.h"
接口清单#
接口名称 |
功能简述 |
|---|---|
启动 SoftAP |
|
关闭 SoftAP |
|
获取 SoftAP 使能状态 |
|
设置 SoftAP 扩展配置 |
|
获取 SoftAP 基本配置 |
|
获取 SoftAP 扩展配置 |
|
获取已连接的 STA 信息列表 |
|
断开指定 MAC 地址的 STA 连接 |
Functions#
wifi_softap_enable #
errcode_t wifi_softap_enable(const softap_config_stru *config)
声明头文件
#include "middleware/services/wifi/wifi_hotspot.h"
功能说明
启动 SoftAP 接口,使设备以热点模式工作。
根据 config 参数中的 SSID、密码、安全类型和信道号配置热点。
前置条件
调用时序约束:当前接口必须在 Wi-Fi 初始化完成(wifi_init 成功返回)后调用。
依赖关系:当前接口依赖 SoftAP 未处于使能状态,且 P2P 未使能。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
config |
const softap_config_stru* |
SoftAP 基本配置参数 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
配置合法且 SoftAP 启动成功 |
Other |
其他错误码,参考errcode_t |
配置无效或 SoftAP 启动失败 |
参考案例
src/application/samples/wifi/softap_sample/softap_sample.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_OWE |
特性宏 |
支持增强开放(OWE)安全模式分支(分支级,Kconfig 未声明、构建系统注入,实际不可启用) |
- |
wifi_softap_disable #
errcode_t wifi_softap_disable(void)
声明头文件
#include "middleware/services/wifi/wifi_hotspot.h"
功能说明
关闭 SoftAP 接口,停止热点模式。
关闭时自动停止 DHCP 服务器(如果已启动)。
关闭后清除热点接口名与配置信息。
前置条件
调用时序约束:当前接口必须在 Wi-Fi 初始化完成且 SoftAP 已使能后调用。
依赖关系:当前接口依赖 SoftAP 处于使能状态。
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
SoftAP 正常关闭 |
Other |
其他错误码,参考errcode_t |
Wi-Fi 未初始化或 SoftAP 未使能 |
参考案例
src/application/samples/wifi/softap_sample/softap_sample.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
LWIP_DHCPS |
特性宏 |
支持 DHCP 服务器资源清理分支(分支级,无前缀注入宏) |
由构建目标决定 |
wifi_is_softap_enabled #
int32_t wifi_is_softap_enabled(void)
声明头文件
#include "middleware/services/wifi/wifi_hotspot.h"
功能说明
查询 SoftAP 是否已使能。
返回值 1 表示已使能,0 表示未使能。
Wi-Fi 未初始化时返回 0。
返回值
返回类型:int32_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
1 |
SoftAP 已使能 |
SoftAP 已启动成功 |
0 |
SoftAP 未使能 |
SoftAP 未启动或 Wi-Fi 未初始化 |
wifi_set_softap_config_advance #
errcode_t wifi_set_softap_config_advance(const softap_config_advance_stru *config)
声明头文件
#include "middleware/services/wifi/wifi_hotspot.h"
功能说明
设置 SoftAP 的扩展配置参数,包括信标间隔、DTIM(Delivery Traffic Indication Message)周期、组播密钥更新时间、SSID 隐藏标志、GI 和协议模式。
配置中 protocol_mode 为 0 表示不配置,按芯片最大协议能力设置。
前置条件
调用时序约束:当前接口必须在 Wi-Fi 初始化完成且 SoftAP 未使能时调用。
依赖关系:当前接口依赖 SoftAP 处于未使能状态。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
config |
const softap_config_advance_stru* |
SoftAP 扩展配置参数 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
配置合法且设置成功 |
Other |
其他错误码,参考errcode_t |
配置无效或 SoftAP 已使能 |
参考案例
src/application/samples/wifi/softap_sample/softap_sample.c
wifi_get_softap_config #
errcode_t wifi_get_softap_config(softap_config_stru *result)
声明头文件
#include "middleware/services/wifi/wifi_hotspot.h"
功能说明
获取 SoftAP 的基本配置信息。
返回当前 SoftAP 的 SSID、预共享密钥、安全类型、信道号和 PSK 类型。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
result |
softap_config_stru* |
SoftAP 基本配置信息,由调用方分配内存、函数填充 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
获取配置成功 |
Other |
其他错误码,参考errcode_t |
内存拷贝失败 |
参考案例
src/middleware/utils/at/at_wifi_cmd/at/at_wifi.c
wifi_get_softap_config_advance #
errcode_t wifi_get_softap_config_advance(softap_config_advance_stru *result)
声明头文件
#include "middleware/services/wifi/wifi_hotspot.h"
功能说明
获取 SoftAP 的扩展配置信息。
返回当前 SoftAP 的信标间隔、DTIM 周期、组播密钥更新时间、SSID 隐藏标志、GI 和协议模式。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
result |
softap_config_advance_stru* |
SoftAP 扩展配置信息,由调用方分配内存、函数填充 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
获取配置成功 |
Other |
其他错误码,参考errcode_t |
内存拷贝失败 |
参考案例
src/middleware/utils/at/at_wifi_cmd/at/at_wifi.c
wifi_softap_get_sta_list #
errcode_t wifi_softap_get_sta_list(wifi_sta_info_stru *result, uint32_t *size)
声明头文件
#include "middleware/services/wifi/wifi_hotspot.h"
功能说明
获取当前连接到 SoftAP 的所有 STA 信息。
返回每个 STA 的 MAC 地址、RSSI(Received Signal Strength Indicator)和最佳发送速率。
size 参数输入时表示缓冲区可容纳的 STA 数量,输出时为实际 STA 数量。
前置条件
调用时序约束:当前接口必须在 Wi-Fi 初始化完成且 SoftAP 已使能后调用。
依赖关系:当前接口依赖 SoftAP 处于使能状态。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
size |
uint32_t* |
输入时为缓冲区可容纳 STA 数量,输出时为实际 STA 数量 |
不为 NULL,*size > 0 |
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
result |
wifi_sta_info_stru* |
已连接 STA 的信息列表 |
size |
uint32_t* |
实际连接的 STA 数量 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
获取成功 STA 列表 |
Other |
其他错误码,参考errcode_t |
Wi-Fi 未初始化、SoftAP 未使能或参数无效 |
参考案例
src/middleware/utils/at/at_wifi_cmd/at/at_wifi.c
wifi_softap_deauth_sta #
errcode_t wifi_softap_deauth_sta(const uint8_t *mac, int32_t mac_len)
声明头文件
#include "middleware/services/wifi/wifi_hotspot.h"
功能说明
断开指定 MAC 地址的 STA 与 SoftAP 的连接。
向目标 STA 发送 deauth 报文。
前置条件
调用时序约束:当前接口必须在 Wi-Fi 初始化完成且 SoftAP 已使能后调用。
依赖关系:当前接口依赖 SoftAP 处于使能状态。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
mac |
const uint8_t* |
目标 STA 的 MAC 地址 |
不为 NULL,长度为 WIFI_MAC_LEN:6 |
mac_len |
int32_t |
MAC 地址长度 |
6 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
成功断开指定 STA |
Other |
其他错误码,参考errcode_t |
Wi-Fi 未初始化、SoftAP 未使能、MAC 地址无效或断开失败 |
参考案例
src/middleware/utils/at/at_wifi_cmd/at/at_wifi.c
Type definitions#
errcode_t #
typedef uint32_t errcode_t;
使用说明
SDK 公共基础类型,本模块对外接口的返回值类型。
Enumerations#
wifi_security_enum #
typedef enum wifi_security_enum {
WIFI_SEC_TYPE_INVALID = -1,
WIFI_SEC_TYPE_OPEN,
WIFI_SEC_TYPE_WEP,
WIFI_SEC_TYPE_WPA2PSK,
WIFI_SEC_TYPE_WPA2_WPA_PSK_MIX,
WIFI_SEC_TYPE_WPAPSK,
WIFI_SEC_TYPE_WPA,
WIFI_SEC_TYPE_WPA2,
WIFI_SEC_TYPE_SAE,
WIFI_SEC_TYPE_WPA3_WPA2_PSK_MIX,
WIFI_SEC_TYPE_WPA3,
WIFI_SEC_TYPE_OWE,
WIFI_SEC_TYPE_WAPI_PSK,
WIFI_SEC_TYPE_WAPI_CERT,
WIFI_SEC_TYPE_WPA3_WPA2_MIX,
WIFI_SEC_TYPE_WEP_OPEN,
WIFI_SEC_TYPE_UNKNOWN
} wifi_security_enum;
枚举成员 |
取值 |
描述 |
|---|---|---|
WIFI_SEC_TYPE_INVALID |
-1 |
无效安全类型 |
WIFI_SEC_TYPE_OPEN |
0 |
Open |
WIFI_SEC_TYPE_WEP |
1 |
WEP(Wired Equivalent Privacy) SHARED |
WIFI_SEC_TYPE_WPA2PSK |
2 |
WPA2-Personal |
WIFI_SEC_TYPE_WPA2_WPA_PSK_MIX |
3 |
WPA-Personal 和 WPA2-Personal 混合 |
WIFI_SEC_TYPE_WPAPSK |
4 |
WPA-Personal |
WIFI_SEC_TYPE_WPA |
5 |
WPA-Enterprise |
WIFI_SEC_TYPE_WPA2 |
6 |
WPA2-Enterprise |
WIFI_SEC_TYPE_SAE |
7 |
SAE(Simultaneous Authentication of Equals,WPA3 个人级) |
WIFI_SEC_TYPE_WPA3_WPA2_PSK_MIX |
8 |
WPA2-Personal 和 WPA3-Personal 混合 |
WIFI_SEC_TYPE_WPA3 |
9 |
WPA3-Enterprise |
WIFI_SEC_TYPE_OWE |
10 |
OWE(Opportunistic Wireless Encryption) |
WIFI_SEC_TYPE_WAPI_PSK |
11 |
WAPI 个人级 |
WIFI_SEC_TYPE_WAPI_CERT |
12 |
WAPI 企业级 |
WIFI_SEC_TYPE_WPA3_WPA2_MIX |
13 |
WPA2-Enterprise 和 WPA3-Enterprise 混合 |
WIFI_SEC_TYPE_WEP_OPEN |
14 |
WEP OPEN |
WIFI_SEC_TYPE_UNKNOWN |
15 |
其它认证类型 |
protocol_mode_enum #
typedef enum {
WIFI_MODE_UNDEFINE,
WIFI_MODE_11B,
WIFI_MODE_11B_G,
WIFI_MODE_11B_G_N,
WIFI_MODE_11B_G_N_AX,
} protocol_mode_enum;
枚举成员 |
取值 |
描述 |
|---|---|---|
WIFI_MODE_UNDEFINE |
0 |
未配置 |
WIFI_MODE_11B |
1 |
802.11b |
WIFI_MODE_11B_G |
2 |
802.11b/g |
WIFI_MODE_11B_G_N |
3 |
802.11b/g/n |
WIFI_MODE_11B_G_N_AX |
4 |
802.11b/g/n/ax |
Structures#
softap_config_stru #
typedef struct {
int8_t ssid[WIFI_MAX_SSID_LEN];
int8_t pre_shared_key[WIFI_MAX_KEY_LEN];
int8_t reserved[2];
wifi_security_enum security_type;
int32_t channel_num;
int32_t wifi_psk_type;
} softap_config_stru;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
ssid |
int8_t[WIFI_MAX_SSID_LEN] |
SSID(Service Set Identifier) |
pre_shared_key |
int8_t[WIFI_MAX_KEY_LEN] |
预共享密钥(PSK) |
reserved |
int8_t[2] |
保留字段 |
security_type |
wifi_security_enum |
安全类型 |
channel_num |
int32_t |
信道号,取值范围 0 ~ 14 |
wifi_psk_type |
int32_t |
PSK 类型,0 表示不提前计算 PSK,1 表示提前计算 PSK |
softap_config_advance_stru #
typedef struct {
uint32_t beacon_interval;
uint32_t dtim_period;
uint32_t group_rekey;
uint32_t hidden_ssid_flag;
uint32_t gi;
protocol_mode_enum protocol_mode;
} softap_config_advance_stru;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
beacon_interval |
uint32_t |
信标间隔,范围 25ms ~ 1000ms,默认 100ms,0 表示未配置 |
dtim_period |
uint32_t |
DTIM 周期,范围 1 ~ 30,默认 2,0 表示未配置 |
group_rekey |
uint32_t |
组播密钥更新时间,范围 30s ~ 86400s,默认 86400s,0 表示未配置 |
hidden_ssid_flag |
uint32_t |
SSID 隐藏标志,1 表示不隐藏,2 表示隐藏,0 表示未配置 |
gi |
uint32_t |
GI(Guard Interval)配置,默认 auto_GI,0 表示未配置;配置非 0 有效值时需同时配置有效的协议模式 |
protocol_mode |
protocol_mode_enum |
协议模式,默认按芯片最大协议能力配置,0 表示未配置 |
wifi_sta_info_stru #
typedef struct {
uint8_t mac_addr[WIFI_MAC_LEN];
int8_t rssi;
int8_t rsv;
uint32_t best_rate;
} wifi_sta_info_stru;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
mac_addr |
uint8_t[WIFI_MAC_LEN] |
MAC 地址 |
rssi |
int8_t |
接收信号强度指示(RSSI) |
rsv |
int8_t |
保留字段 |
best_rate |
uint32_t |
最佳发送速率,单位 kbps |
Macros#
WIFI_MAX_SSID_LEN #
#define WIFI_MAX_SSID_LEN 33 // 32 + \0
WIFI_MAX_KEY_LEN #
#define WIFI_MAX_KEY_LEN 65 // 64 + \0
WIFI_MAC_LEN #
#define WIFI_MAC_LEN 6
ERRCODE_SUCC #
#define ERRCODE_SUCC 0UL
ERRCODE_FAIL #
#define ERRCODE_FAIL 0xFFFFFFFF