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"

接口清单

接口名称	功能简述
wifi_softap_enable	启动 SoftAP
wifi_softap_disable	关闭 SoftAP
wifi_is_softap_enabled	获取 SoftAP 使能状态
wifi_set_softap_config_advance	设置 SoftAP 扩展配置
wifi_get_softap_config	获取 SoftAP 基本配置
wifi_get_softap_config_advance	获取 SoftAP 扩展配置
wifi_softap_get_sta_list	获取已连接的 STA 信息列表
wifi_softap_deauth_sta	断开指定 MAC 地址的 STA 连接

Functions

wifi_softap_enable

softap_enable wifi softap enable 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

softap_disable wifi softap disable 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

is_softap_enabled wifi is softap enabled 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

set_softap_config_advance wifi set softap config advance 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

get_softap_config wifi get softap config 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

get_softap_config_advance wifi get softap config advance 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

softap_get_sta_list wifi softap get sta list 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

softap_deauth_sta wifi softap deauth sta 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

errcode t errcode_t

typedef uint32_t errcode_t;

使用说明

SDK 公共基础类型，本模块对外接口的返回值类型。

Enumerations

wifi_security_enum

security_enum wifi security enum 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

sta_info_stru wifi sta info stru 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

max_ssid_len wifi max ssid len wifi_max_ssid_len

#define WIFI_MAX_SSID_LEN 33 // 32 + \0

WIFI_MAX_KEY_LEN

max_key_len wifi max key len wifi_max_key_len

#define WIFI_MAX_KEY_LEN 65 // 64 + \0

WIFI_MAC_LEN

mac_len wifi mac len wifi_mac_len

#define WIFI_MAC_LEN 6

ERRCODE_SUCC

errcode succ errcode_succ

#define ERRCODE_SUCC 0UL

ERRCODE_FAIL

errcode fail errcode_fail

#define ERRCODE_FAIL 0xFFFFFFFF