SoftAP 热点#
WS53 作为 SoftAP 创建无线热点,并通过静态 IPv4 地址和 DHCP Server 为接入终端提供局域网连接。
学习目标#
配置并启动 WS53 Wi-Fi SoftAP。
为 AP 接口设置静态 IPv4 地址并启动 DHCP Server。
通过事件或查询接口管理已接入的 STA。
案例说明#
源码位于 src/application/samples/wifi/softap_sample/。案例等待 Wi-Fi 初始化完成后,配置 SoftAP 基本参数和扩展参数,创建 ap0 接口,再为该接口设置 192.168.43.1/24 静态地址并启动 DHCP Server。
sequenceDiagram
participant A as SoftAP Sample
participant W as WS53 Wi-Fi
participant L as LwIP
participant D as 手机或 PC
A->>W: wifi_set_softap_config_advance()
A->>W: wifi_softap_enable(&hapd_conf)
A->>L: netif_find("ap0")
A->>L: netifapi_netif_set_addr()
A->>L: netifapi_dhcps_start()
D->>W: 搜索、认证并关联
D->>L: DHCP 请求
L-->>D: 分配 IPv4 地址
SoftAP 无线接口、IPv4 地址和 DHCP Server 是三个独立环节。wifi_softap_enable() 返回成功只表示热点接口启动成功;如果没有正确设置 ap0 地址并启动 DHCP Server,终端可能已经关联,但无法自动获得 IP 地址。
关键配置#
启用
ENABLE_WIFI_SAMPLE和SAMPLE_SUPPORT_SOFTAP_SAMPLE。在
softap_sample.c的example_softap_function()中修改 SSID、密码、信道、安全类型、扩展参数和网络地址。信道必须符合当前国家码、区域法规和测试终端能力。案例默认使用信道 13,部分终端或区域配置可能不支持。
默认参数如下,仅用于案例联调:
参数 |
默认值 |
修改位置 |
|---|---|---|
SSID |
|
|
密码 |
|
|
安全类型 |
WPA/WPA2-PSK 混合模式 |
|
信道 |
13 |
|
Beacon 周期 |
100 ms |
|
DTIM 周期 |
2 |
|
组密钥更新周期 |
86400 秒 |
|
协议模式 |
802.11b/g/n/ax |
|
SSID 广播 |
不隐藏 |
|
AP 接口 |
|
|
AP 地址和网关 |
|
|
子网掩码 |
|
|
产品代码建议使用 WIFI_SEC_TYPE_WPA2_WPA_PSK_MIX、WIFI_MODE_11B_G_N_AX 等枚举名代替数字常量。修改 AP 接口名或网段时,必须同步修改 LwIP 网络接口、静态地址和 DHCP Server 配置;下游网段还应避免与可能存在的 STA 上游网段冲突。
代码详解#
1. 等待 Wi-Fi 初始化#
SoftAP Sample 由独立任务运行。任务首先等待系统完成 Wi-Fi 初始化,再进入热点配置流程:
while (wifi_is_wifi_inited() == 0) {
osDelay(10);
}
if (example_softap_function() != 0) {
PRINT("[WIFI_SOFTAP_SAMPLE]::example_softap_function fail.\r\n");
return -1;
}
这里的等待只确认 Wi-Fi 模块已经初始化,不代表 SoftAP 接口已经创建。实际产品可以由系统就绪事件触发热点任务,避免永久轮询。
2. 配置 SoftAP 基本参数#
softap_config_stru 保存 SSID、预共享密钥、安全类型和信道。下面使用枚举名表示当前 Sample 中的数字配置:
int8_t ssid[WIFI_MAX_SSID_LEN] = "my_softAP";
int8_t pre_shared_key[WIFI_MAX_KEY_LEN] = "my_password";
softap_config_stru hapd_conf = {0};
memcpy_s(hapd_conf.ssid, sizeof(hapd_conf.ssid),
ssid, sizeof(ssid));
memcpy_s(hapd_conf.pre_shared_key, sizeof(hapd_conf.pre_shared_key),
pre_shared_key, sizeof(pre_shared_key));
hapd_conf.security_type = WIFI_SEC_TYPE_WPA2_WPA_PSK_MIX;
hapd_conf.channel_num = 13;
hapd_conf.wifi_psk_type = 0;
ssid 和 pre_shared_key 缓冲区在复制前已经清零,因此短字符串后仍保留结束符。产品代码必须检查 memcpy_s() 返回值,并校验 SSID、密码长度、安全类型和信道是否合法。不要在日志中打印明文密码。
3. 配置 SoftAP 扩展参数#
扩展配置需要在 wifi_softap_enable() 之前设置:
softap_config_advance_stru config = {0};
config.beacon_interval = 100;
config.dtim_period = 2;
config.gi = 0;
config.group_rekey = 86400;
config.protocol_mode = WIFI_MODE_11B_G_N_AX;
config.hidden_ssid_flag = 1;
if (wifi_set_softap_config_advance(&config) != ERRCODE_SUCC) {
return -1;
}
hidden_ssid_flag = 1 表示不隐藏 SSID;gi = 0 表示不配置该项。Beacon、DTIM 和组密钥更新周期都有有效范围,产品应使用 Wi-Fi Hotspot API 中定义的约束,不要直接照搬其他芯片参数。
4. 启动热点并配置 DHCP Server#
基本参数和扩展参数就绪后启动 SoftAP:
if (wifi_softap_enable(&hapd_conf) != ERRCODE_SUCC) {
return -1;
}
热点启动后,查找自动创建的 ap0 接口并设置静态网络参数:
ip4_addr_t ipaddr;
ip4_addr_t netmask;
ip4_addr_t gateway;
IP4_ADDR(&ipaddr, 192, 168, 43, 1);
IP4_ADDR(&netmask, 255, 255, 255, 0);
IP4_ADDR(&gateway, 192, 168, 43, 1);
struct netif *netif_p = netif_find("ap0");
if (netif_p == NULL) {
wifi_softap_disable();
return -1;
}
if (netifapi_netif_set_addr(netif_p, &ipaddr, &netmask, &gateway) != ERR_OK) {
wifi_softap_disable();
return -1;
}
最后启动 DHCP Server:
if (netifapi_dhcps_start(netif_p, NULL, 0) != ERR_OK) {
wifi_softap_disable();
return -1;
}
PRINT("[WIFI_SOFTAP_SAMPLE]::SoftAp start success.\r\n");
netifapi_dhcps_start() 的第二、三个参数为 NULL 和 0 时使用协议栈默认地址池。产品需要固定地址范围、租约或 DNS 策略时,应按当前 LwIP 配置补充参数。任何网络配置步骤失败后都要关闭已经启动的 SoftAP,避免留下“能被发现但不能正常分配地址”的半初始化状态。
客户端状态与服务管理#
当前案例只启动 SoftAP 和 DHCP Server,没有注册客户端上下线事件。产品需要管理接入终端时,可通过 wifi_register_event_cb() 注册以下回调:
static void softap_sta_join(const wifi_sta_info_stru *info)
{
/* 记录 MAC 或向业务任务投递上线消息。 */
(void)info;
}
static void softap_sta_leave(const wifi_sta_info_stru *info)
{
/* 清理该终端关联的业务状态。 */
(void)info;
}
static wifi_event_stru g_softap_event = {
.wifi_event_softap_sta_join = softap_sta_join,
.wifi_event_softap_sta_leave = softap_sta_leave,
};
wifi_register_event_cb(&g_softap_event);
事件回调中只更新状态或投递消息,不要执行延时、阻塞式网络操作或复杂业务。还可以使用 wifi_softap_get_sta_list() 查询当前客户端,或使用 wifi_softap_deauth_sta() 断开指定 MAC 地址的终端。接口参数和返回值见 Wi-Fi Hotspot API。
停止 SoftAP 时应按照依赖关系释放资源:
停止依赖下游连接的业务。
调用
netifapi_dhcps_stop()停止ap0上的 DHCP Server。调用
wifi_softap_disable()关闭 SoftAP。清理客户端列表、地址租约映射和业务状态。
STA 与 SoftAP 并发时,两者共享射频资源,应根据当前固件的并发和信道策略设计状态机。启动两个无线接口并不会自动提供路由或 NAT。
案例操作指导#
根据测试环境修改 SSID、密码、信道和 AP 网段,然后构建并烧录 WS53。
确认日志依次出现
wifi init succ和SoftAp start success。使用手机或 PC 搜索
my_softAP,输入my_password并连接。确认终端获得
192.168.43.0/24网段地址,默认网关为192.168.43.1。从终端访问
192.168.43.1,验证终端到 WS53 的局域网链路。
构建方法参见快速入门。若需要让 SoftAP 客户端访问 STA 上游网络,还必须实现路由、转发及必要的 NAT。