Wi-Fi 指南

概述

ameba_wifi 是 RTL8721F 的 Rust Wi-Fi 协议栈。AP 核(KM4TZ,运行本 crate)通过 WHC(Wi-Fi Host Controller)IPC 与 NP 核上的 Wi-Fi 固件通信,分为两个通道:通道 7(API,控制面 —— wifi_on/wifi_connect/wifi_start_ap 等)和通道 6(TRX,数据面 —— 收发数据包)。ameba_wifi::net::WhcDevice 将通道 6 同时封装为原始的 smoltcp::Device 和 embassy_net_driver::Driver,应用代码可以在其上搭建手写的 smoltcp 接口,也可以搭建 embassy-net 的 Stack。

适用范围与限制

  • STA 连接:仅支持开放网络和 WPA2-PSK。 wifi_connect 支持 SecurityType::Open 和 SecurityType::Wpa2AesPsk (4-way handshake、PBKDF2-SHA1-4096 PMK 推导、密钥安装,参见 STA 连接(WPA2-PSK))。WPA3/SAE 尚未实现,断线后也没有自动重连。

  • 无法获取扫描结果。 wifi_scan()/wifi_scan_abort() 可以触发或中止扫描,但 NP 的扫描结果回调(API_D2H_SCAN_USER_CALLBACK)在 run_blk_api() 中没有对应的处理分支,会落入未知事件分支——目前 Rust 侧没有办法读回扫描结果列表。

  • 不支持 DNS 和 TLS。 embassy-net 协议栈未启用 DNS 解析,远端主机只能通过 IPv4 字面量访问,也没有提供 TLS 层。

  • 没有省电开关、漫游、监管域或 CSI 采集相关的 API。 ips_enable/lps_enable 是在 wifi_on 发送的 wifi_user_conf 数据块中启动时固定写死的,没有运行时可调用的接口,漫游、监管域、CSI 采集目前完全没有对应的代码路径。

架构

AP 核 (KM4TZ, ameba-wifi crate)
     │
     ├── 通道 7 API(控制面)      wifi_on / wifi_connect / wifi_start_ap / wifi_scan / ...
     │                              —— send_api_req() 阻塞直到 NP 应答
     │                              —— NP→AP 事件(WifiEvent)通过 run_blk_api() 到达
     │
     └── 通道 6 TRX(数据面)      WhcDevice —— smoltcp::Device + embassy_net_driver::Driver
          │
          ▼
NP 核(Wi-Fi 固件)

快速入门

无论最终是作为 STA 还是 SoftAP,每个 Wi-Fi 程序都以相同的初始化流程开始:

#[embassy_executor::task]
async fn whc_task() {
    ameba_wifi::run_blk_api().await;
}

// 1. HAL 初始化:sys_timer (embassy-time) + IPC_CPU0_IRQ。
ameba_hal::init(ameba_hal::Config::default());

// 2. 注册 WHC IPC 通道处理函数(通道 6 TRX + 通道 7 API)。
ameba_wifi::init();

// 3. 启动处理 NP→AP 请求的后台任务。
spawner.spawn(whc_task()).unwrap();

// 4. 启动 NP 上的 Wi-Fi。`wifi_on` 启动 STA 接口,...
let rc = ameba_wifi::wifi::wifi_on().await;

接下来可以参考下文的 SoftAP 小节启动一个接入点,参考 STA 连接小节加入一个现有网络,参考 MQTT 客户端小节在得到的 embassy-net 协议栈上运行 MQTT 会话,或参考 Wi-Fi 事件模型小节了解 WifiEvent 是如何投递的。

SoftAP

wifi_start_ap/wifi_stop_ap 用于启动和停止一个基础的接入点。这是 v1.0 的范围:单客户端组、只广播 SSID,安全方式仅支持开放或 WPA2-AES-PSK——暂不支持多客户端管理、隐藏 SSID、WPA3-AP 或 STA+AP 并发。

pub async fn wifi_start_ap(
    ssid: &str,
    password: &str,
    security: SecurityType,
    channel: u8,
) -> i32
  • security 必须是 SecurityType::Open 或 SecurityType::Wpa2AesPsk。

  • ssid 长度必须在 1..=32 字节。

  • password 在 Open 下必须为空,在 Wpa2AesPsk 下长度必须在 8..=64 字节。

  • 返回值为 NP 写入的 ret (0 表示成功)。

wifi_stop_ap() 会拆除 AP 接口,NP 内部会自行处理 _wifi_off_ap,因此不需要单独调用去初始化。

应用示例

Rust SDK 提供了一个示例 wifi-ap:启动一个开放 SoftAP,观察 30 秒内的站点关联事件,然后停止该 AP。

const AP_SSID: &str = "ameba-rust-ap";
const AP_PASSWORD: &str = "";
const AP_CHANNEL: u8 = 1;

// ... 在 ameba_hal::init / ameba_wifi::init / whc_task 启动 / wifi_on 之后 ...

let rc = ameba_wifi::wifi::wifi_start_ap(
    AP_SSID,
    AP_PASSWORD,
    SecurityType::Open,
    AP_CHANNEL,
)
.await;

// 6. Observe station associate/disassociate events for a fixed window.
// `with_timeout` wraps the whole loop: it cancels the loop (dropping
// whichever `receive().await` is in flight) once the window elapses,
// regardless of how many events were handled inside.
println!("[ap] observing for {}s ...", AP_OBSERVE_WINDOW.as_secs());
let _ = embassy_time::with_timeout(AP_OBSERVE_WINDOW, async {
    loop {
        let evt: WifiEvent = ameba_wifi::EVENT_CHAN.receive().await;

        match evt.event_code {
            event_code::AP_STA_ASSOC => {
                let mac = if evt.evt_info != 0 {
                    Some(unsafe { read_ap_sta_mac(evt.evt_info) })
                } else {
                    None
                };
                // ...
            }
            event_code::AP_STA_DISASSOC => {
                // ...
            }
            other => println!("[ap] event: code={} (other)", other),
        }
    }
})
.await;

let rc = ameba_wifi::wifi::wifi_stop_ap().await;

预期串口输出:

[build] <build timestamp>
[wifi] init
[wifi] on: 0
[ap] starting SSID="ameba-rust-ap" channel=1 ...
[ap] start_ap returned: 0
[PASS] softap: start_ap accepted
[ap] observing for 30s ...
[ap] event: code=0 (STA_ASSOC) mac=xx:xx:xx:xx:xx:xx
[ap] stop_ap returned: 0
[PASS] softap: stop_ap accepted

只有在观察窗口内有站点加入时,才会出现 [ap] event: 行。上面的输出之间还会夹杂 Wi-Fi 核打印的 [blk_api]、[WLAN-A] 等调试行。

备注

使用 cargo xtask run example --name wifi-ap --port <串口> 编译并烧录该示例。

STA 连接(WPA2-PSK)

wifi_connect 将 STA 接口关联到一个 AP。

pub async fn wifi_connect(
    ssid: &str,
    password: &str,
    security: SecurityType,
) -> i32
  • ssid 长度必须 ≤ 32 字节;password 长度必须 ≤ 63 字节。

  • 只有 SecurityType::Open 和 SecurityType::Wpa2AesPsk 能完整走通。跟 wifi_start_ap 不同,wifi_connect 不会提前拒绝其他 SecurityType 值——传 Wpa3AesPsk/Wpa2Wpa3Mix 依然会发给 NP,但下文的 PMK 推导步骤只识别 WPA/WPA2-PSK 那组安全位组合,PMK 永远不会被推导出来,连接会卡住或失败;SAE(WPA3)尚未实现。

  • 返回 0 只表示 NP 接受了这次请求,不代表 连接结果。真正的结果(成功/失败/断开)会作为 JOIN_STATUS 的 WifiEvent 异步到达(参见下文 Wi-Fi 事件模型)。

WPA2-PSK 握手流程

对于 Wpa2AesPsk 连接,NP 会通过三个事件码(108、104、106)驱动一次 PMK 请求和完整的 4-way handshake,STA 才算真正上线。这些事件全部在 run_blk_api() 内部同步处理,且在该事件被 ACK 给 NP 之前就完成——应用代码不会在 EVENT_CHAN 上看到它们:

API_D2H_WIFI_EVENT => {
    let event_code = params[0];
    let evt_info = params[1]; // pointer to extra event info (may be 0)
    ...
    if event_code == crate::wifi::events::event_code::WPA_SET_PSK_INFO {
        crate::wifi::psk::handle_set_psk_info(evt_info).await;
    } else if event_code == crate::wifi::events::event_code::WPA_STA_4WAY_START {
        crate::wifi::handshake::handle_4way_start(evt_info, true).await;
    } else if event_code == crate::wifi::events::event_code::WPA_STA_4WAY_RECV {
        crate::wifi::handshake::handle_4way_recv(evt_info).await;
    } else {
        // ... 非握手事件走 EVENT_CHAN ...
    }
}
  • 108(PMK 请求):NP 把 SSID/密码对送回 AP 核,psk::handle_set_psk_info 用 pbkdf2_hmac::<Sha1>(passphrase, ssid, 4096, ..) 推导 PMK(实测 240MHz 下约耗时 361ms——这是每次连接一次性的开销,不是逐包开销),完成后无条件发送 WHC_API_WIFI_START_JOIN_CMD,让 NP 继续 802.11 关联。

  • 104/106(4-way handshake):关联完成后,handshake::handle_4way_start/handle_4way_recv 完成 PTK 推导(对 PMK、AP/STA MAC 及 nonce 做 PRF-384)、校验每一帧的 MIC、从 M3 的 AES-Key-Wrap 加密 Key Data 中解出 GTK、通过 WHC_API_WIFI_ADD_KEY 安装两组密钥,并通过 WHC_API_WIFI_SEND_EAPOL 回发 M2/M4。

对外唯一可见的影响是:在此过程中 join_status 会多经过两个状态:104 之后是 HANDSHAKING``(7),106 中发出 M4 之后紧接着是 ``HANDSHAKE_DONE``(8)和 ``SUCCESS``(9)。一次完整连接的状态序列是 ``SCANNING → AUTHENTICATING → AUTHENTICATED → ASSOCIATED → HANDSHAKING → HANDSHAKE_DONE → SUCCESS。如果 AP 拒绝第一次认证,Wi-Fi 核会重试,AUTHENTICATING 会出现两次;实际运行中不会上报 STARTING。

备注

目前只接通了 STA 侧的握手事件(104/106/108)。SoftAP 侧对应的事件(105/107,即 WPA_AP_4WAY_START/WPA_AP_4WAY_RECV)只定义了常量, run_blk_api() 中没有对应的处理分支。 wifi_start_ap 接受 Wpa2AesPsk,但 wifi-ap 示例只验证了开放网络,参见上文 SoftAP。

无自动重连

整个协议栈都没有断线自动重连行为:Wi-Fi 核固件和 ameba_wifi 都不会自动重连。收到 join_status::DISCONNECT 或 FAIL 事件后,应用代码必须自己再调用一次 wifi_connect——参见下方示例中的重试分支。

应用示例

Rust SDK 提供了一个示例 wifi-connect:连接一个 Wpa2AesPsk 网络,等待 JOIN_STATUS 到达 ASSOCIATED/SUCCESS``(``FAIL 时重试),然后在建立 DHCP 之前把 EVENT_CHAN 交给一个长期运行的消费任务。

const WIFI_SSID: &str = "your-ssid";
const WIFI_PASSWORD: &str = "your-password";

/// TCP port probed on the DHCP gateway; the check passes only if it is open.
const TCP_PORT: u16 = 8080;

// ... 在 ameba_hal::init / ameba_wifi::init / whc_task 启动 / wifi_on 之后 ...

// 5. 连接 —— WPA2-AES-PSK。
println!("[wifi] connecting to \"{}\" ...", WIFI_SSID);
let rc =
    ameba_wifi::wifi::wifi_connect(WIFI_SSID, WIFI_PASSWORD, SecurityType::Wpa2AesPsk).await;
println!("[wifi] connect returned: {}", rc);

// 6. 等待 JOIN_STATUS 事件(event_code 2 = RTW_EVENT_JOIN_STATUS)。
//    NP 会在每次状态变化时都发出该事件,这里循环直到看到
//    ASSOCIATED/SUCCESS、FAIL(重试)或 DISCONNECT。
loop {
    let evt: WifiEvent = ameba_wifi::EVENT_CHAN.receive().await;
    println!("[wifi] event: code={}", evt.event_code);

    if evt.event_code == event_code::JOIN_STATUS {
        let status = if evt.evt_info != 0 {
            unsafe { read_join_status(evt.evt_info) }
        } else {
            join_status::UNKNOWN
        };
        println!("[wifi] join_status={}", status as u32);

        match status {
            join_status::ASSOCIATED | join_status::SUCCESS => {
                ameba_wifi::net::set_link_up(true);
                println!("[NET] WiFi connected");
                break;
            }
            join_status::FAIL => {
                println!("[wifi] connect failed, retrying in 3s ...");
                Timer::after(Duration::from_secs(3)).await;
                let rc = ameba_wifi::wifi::wifi_connect(
                    WIFI_SSID,
                    WIFI_PASSWORD,
                    SecurityType::Wpa2AesPsk,
                )
                .await;
                println!("[wifi] connect returned: {}", rc);
            }
            join_status::DISCONNECT => {
                ameba_wifi::net::set_link_up(false);
                println!("[FAIL] embassy-net: WiFi disconnected before association");
                return;
            }
            _ => {} // 中间状态(SCANNING、ASSOCIATING 等)
        }
    }
}

// 6b. 把 EVENT_CHAN 交给一个长期运行的消费任务,这样之后的断线
// (或任何其他 WIFI_EVENT)都不会卡住 run_blk_api 对 NP 的 ACK。
spawner.spawn(event_task()).unwrap();
// ... 7-10: 查询 MAC、搭建 embassy-net Stack、DHCP、TCP 连接测试 ...

第 6b 步交接的长期事件消费任务:

#[embassy_executor::task]
async fn event_task() -> ! {
    loop {
        let evt: WifiEvent = ameba_wifi::EVENT_CHAN.receive().await;
        if evt.event_code == event_code::JOIN_STATUS {
            let status = if evt.evt_info != 0 {
                unsafe { read_join_status(evt.evt_info) }
            } else {
                join_status::UNKNOWN
            };
            println!("[wifi] event: code={} join_status={}", evt.event_code, status as u32);
            match status {
                join_status::ASSOCIATED | join_status::SUCCESS => {
                    ameba_wifi::net::set_link_up(true);
                    println!("[NET] WiFi (re)connected");
                }
                join_status::DISCONNECT => {
                    ameba_wifi::net::set_link_up(false);
                    println!("[NET] WiFi disconnected");
                }
                _ => {}
            }
        } else {
            println!("[wifi] event: code={}", evt.event_code);
        }
    }
}

预期串口输出:

[build] <build timestamp>
[wifi] init
[wifi] on: 0
[wifi] connecting to "<ssid>" ...
[wifi] connect returned: 0
[wifi] join_status=6
[NET] WiFi connected
[NET] MAC: xx:xx:xx:xx:xx:xx
[PASS] noused keep-list: wifi_get_mac_address matches
[PASS] noused keep-list: wifi_scan_abort returned <n> (not stubbed)
[NET] DHCP: IP=192.168.x.x
[NET] TCP: connecting to 192.168.x.1:8080 ...
[NET] TCP: connected
[PASS] embassy-net: TCP connected

连接过程中还会出现若干 [wifi] event: code=... 和 [wifi] join_status=... 行,并夹杂 Wi-Fi 核和 ameba_wifi 驱动打印的 [api]、[blk_api]、[WLAN-A] 等调试行。TCP 这一步只有在网关上有服务监听 TCP_PORT``(``src/main.rs 中,默认 8080)时才会成功,例如网关设备上运行的 HTTP 服务。如果该端口没有服务监听,最后一行会变为 [FAIL] embassy-net: TCP connect failed: ConnectionReset;网关不应答时则是 [FAIL] embassy-net: TCP connect timed out after 10s。此时 DHCP 已经成功,说明 Wi-Fi 链路和 IP 协议栈都工作正常。

备注

先在 src/main.rs 顶部设置 WIFI_SSID 和 WIFI_PASSWORD,然后用 cargo xtask run example --name wifi-connect --port <串口> 编译并烧录该示例。

MQTT 客户端

ameba_wifi 本身不包含 MQTT 客户端。由于 WhcDevice 实现了 embassy_net_driver::Driver,应用可以直接创建普通的 embassy_net::tcp::TcpSocket,并在其上运行任意 no_std 的 MQTT 客户端 crate。SDK 示例使用的是 rust-mqtt (MQTT v5)。

示例的适用范围与限制:

  • 仅支持明文 TCP。 不支持 TLS,broker 必须在 1883 端口接受未加密连接。

  • broker 地址须为 IPv4 字面量。 未启用 DNS 解析,因此 BROKER_IP 必须是 IPv4 地址;为 None 时使用 DHCP 网关作为 broker。

  • QoS 0。 订阅和发布均使用 QualityOfService::QoS0。

  • 不会重连。 Wi-Fi 链路、TCP 连接或 MQTT 会话断开后,示例会打印一行 [FAIL] 并停止,需复位开发板重新开始。

应用示例

Rust SDK 提供了一个示例 mqtt:连接 WPA2-PSK 网络,通过 DHCP 获取地址后连接 broker,订阅 ameba/cmd,向同一主题发布 hello from ameba 并等待它经 broker 回传,之后每 2 秒向 ameba/status 发布一个计数值,同时打印 ameba/cmd 上收到的消息。

Wi-Fi 连接与 DHCP 步骤与 wifi-connect 示例相同(见 STA 连接(WPA2-PSK))。协议栈拿到地址后,示例与 broker 建立 TCP 连接:

const WIFI_SSID: &str = "your-ssid";
const WIFI_PASSWORD: &str = "your-password";

/// Broker address. `None` = use the DHCP gateway.
const BROKER_IP: Option<[u8; 4]> = None;
const BROKER_PORT: u16 = 1883;

const TOPIC_CMD: &str = "ameba/cmd";
const TOPIC_STATUS: &str = "ameba/status";
const CLIENT_ID: &str = "ameba-rtl8721f";

// ... Wi-Fi join, embassy-net stack and DHCP, as in wifi-connect ...

let broker = match BROKER_IP {
    Some(b) => Ipv4Address::new(b[0], b[1], b[2], b[3]),
    None => match cfg.and_then(|c| c.gateway) {
        Some(gw) => gw,
        None => {
            println!("[FAIL] mqtt: no gateway from DHCP and BROKER_IP unset");
            return;
        }
    },
};

// TCP.
let mut rx_buf = [0u8; 1024];
let mut tx_buf = [0u8; 1024];
let mut socket = TcpSocket::new(stack, &mut rx_buf, &mut tx_buf);
socket.set_timeout(Some(Duration::from_secs(30)));

println!("[MQTT] connecting to {}:{} ...", broker, BROKER_PORT);
match embassy_time::with_timeout(
    Duration::from_secs(10),
    socket.connect((broker, BROKER_PORT)),
)
.await
{
    // ...
}

随后将已连接的 socket 交给 MQTT 客户端:

// MQTT session.
const KEEP_ALIVE_S: u16 = 20;
let mut config = ClientConfig::<'_, 5, _>::new(MqttVersion::MQTTv5, PacketIds(seed & 0x7fff));
config.add_client_id(CLIENT_ID);
config.add_max_subscribe_qos(QualityOfService::QoS0);
config.keep_alive = KEEP_ALIVE_S;
config.max_packet_size = 256;

let mut write_buf = [0u8; 256];
let mut recv_buf = [0u8; 256];
let mut client =
    MqttClient::<_, 5, _>::new(socket, &mut write_buf, 256, &mut recv_buf, 256, config);

if let Err(e) = client.connect_to_broker().await {
    println!("[FAIL] mqtt: broker CONNECT rejected: {:?}", e);
    return;
}
println!("[MQTT] connected");

if let Err(e) = client.subscribe_to_topic(TOPIC_CMD).await {
    println!("[FAIL] mqtt: subscribe failed: {:?}", e);
    return;
}
println!("[MQTT] subscribed: {}", TOPIC_CMD);

rust-mqtt 的随机数源只用于生成报文标识符,因此示例传入的是一个以 TRNG 为种子的简单计数器类型 PacketIds,而不是密码学安全的随机数发生器。

进入稳定状态后,循环先非阻塞地检查是否有新消息,再发布计数值:

// Steady state: publish a counter, echo incoming commands.
let mut count: u32 = 0;
loop {
    match client.receive_message_if_ready().await {
        Ok(Some((topic, payload))) => {
            println!(
                "[MQTT] received: {} = \"{}\"",
                topic,
                core::str::from_utf8(payload).unwrap_or("<binary>")
            );
        }
        Ok(None) => {}
        Err(e) => {
            println!("[FAIL] mqtt: receive failed: {:?}", e);
            return;
        }
    }

    let mut msg = String::<24>::new();
    let _ = core::fmt::Write::write_fmt(&mut msg, format_args!("count={}", count));
    if let Err(e) = client
        .send_message(TOPIC_STATUS, msg.as_bytes(), QualityOfService::QoS0, false)
        .await
    {
        println!("[FAIL] mqtt: publish failed: {:?}", e);
        return;
    }
    println!("[MQTT] published: {} = \"{}\"", TOPIC_STATUS, msg.as_str());
    count = count.wrapping_add(1);

    Timer::after(Duration::from_secs(2)).await;
}

每 2 秒才检查一次新消息,因此一条命令最长可能要 2 秒才会显示。

broker 配置:示例已在 Mosquitto 2.1 上测试通过。允许匿名明文 TCP 连接的最小配置如下:

listener 1883 0.0.0.0
allow_anonymous true

在同一网络中的其他 MQTT 客户端上,可以观察开发板的消息并向其发送命令:

$ mosquitto_sub -h <broker-ip> -t 'ameba/#' -v
$ mosquitto_pub -h <broker-ip> -t ameba/cmd -m hi

预期串口输出:

[build] <build timestamp>
[wifi] on: 0
[wifi] connecting to "<ssid>" ...
[wifi] connect returned: 0
[wifi] join_status=6
[NET] WiFi connected
[NET] DHCP: IP=192.168.x.x
[MQTT] connecting to 192.168.x.x:1883 ...
[MQTT] connected
[MQTT] subscribed: ameba/cmd
[MQTT] published: ameba/cmd = "hello from ameba"
[MQTT] received: ameba/cmd = "hello from ameba"
[PASS] mqtt: loopback
[MQTT] published: ameba/status = "count=0"
[MQTT] published: ameba/status = "count=1"
...

输出之间还会夹杂 Wi-Fi 核和驱动打印的 [api]、[blk_api]、[WLAN-A] 等调试行,链路建立后还会再打印一次 [NET] WiFi (re)connected。

执行 mosquitto_pub -t ameba/cmd -m hi 后,会出现一行 [MQTT] received: ameba/cmd = "hi"。如果无法连接 broker(地址错误、broker 未运行,或 broker 所在主机的防火墙拦截了 1883 入站端口),最后一行为 [FAIL] mqtt: TCP connect timed out after 10s。

备注

先在 src/main.rs 顶部设置 WIFI_SSID 和 WIFI_PASSWORD (broker 不在 DHCP 网关上时还需设置 BROKER_IP ),然后用 cargo xtask run example --name mqtt --port <串口> 编译并烧录。

Wi-Fi 事件模型

NP 通过通道 7 API 将 Wi-Fi 事件转发给 AP 核,run_blk_api() 解析这些事件后,将 WifiEvent 推入 ameba_wifi::EVENT_CHAN——一个深度为 4 的 embassy_sync::channel::Channel。应用代码通过 ameba_wifi::EVENT_CHAN.receive().await 来消费事件。

pub struct WifiEvent {
    pub event_code: u32,
    pub evt_info:   u32, // *const u8 in NP SRAM; 0 if unused
}

该通道深度为 4,且是由 run_blk_api() 任务通过 try_send 投递的——如果应用没有及时消费事件,新事件会被直接丢弃,而不会阻塞 NP。

已接通的事件码

以下三个 event_code 常量(0-8 范围内)有真实的产生方,会经由 EVENT_CHAN 到达;其余(CSI_DONE/WPS_START/WPS_FINISH/EAPOL_START/EAPOL_RECVD/DHCP_STATUS)目前仅是已定义的常量,还没有任何 Rust 侧的处理逻辑。STA 侧的 WPA2-PSK 握手事件码 104/106/108 也已接通,但是在 run_blk_api() 内部同步处理的,不会经由 EVENT_CHAN 投递——参见下文 STA 连接(WPA2-PSK)。它们在 SoftAP 侧对应的 105/107 仍未接通。

event_code::JOIN_STATUS (STA 连接状态变化)

evt_info 指向 NP SRAM,通过 read_join_status(evt_info) 读取状态字节,返回值是 join_status::* 常量之一(STARTING、SCANNING、AUTHENTICATING、AUTHENTICATED、ASSOCIATING、ASSOCIATED、HANDSHAKING、HANDSHAKE_DONE、SUCCESS、FAIL、DISCONNECT 或 UNKNOWN)。

loop {
    let evt: WifiEvent = ameba_wifi::EVENT_CHAN.receive().await;

    if evt.event_code == event_code::JOIN_STATUS {
        let status = if evt.evt_info != 0 {
            unsafe { read_join_status(evt.evt_info) }
        } else {
            join_status::UNKNOWN
        };

        match status {
            join_status::ASSOCIATED | join_status::SUCCESS => {
                ameba_wifi::net::set_link_up(true);
                break;
            }
            join_status::FAIL => {
                // ... 重试 wifi_connect() ...
            }
            join_status::DISCONNECT => {
                ameba_wifi::net::set_link_up(false);
                return;
            }
            _ => {} // 中间状态(SCANNING、ASSOCIATING 等)
        }
    }
}
event_code::AP_STA_ASSOC / event_code::AP_STA_DISASSOC (SoftAP 站点加入/离开)

evt_info 指向该站点 MAC 地址的 6 个字节(两个事件结构体的偏移 0 处都是一段 u8 sta_mac[ETH_ALEN])。通过 read_ap_sta_mac(evt_info) 读取。

match evt.event_code {
    event_code::AP_STA_ASSOC => {
        let mac = if evt.evt_info != 0 {
            Some(unsafe { read_ap_sta_mac(evt.evt_info) })
        } else {
            None
        };
        // ...
    }
    event_code::AP_STA_DISASSOC => {
        // 结构相同
    }
    other => println!("[ap] event: code={} (other)", other),
}

read_join_status 和 read_ap_sta_mac 都是 unsafe 的:调用者必须保证 evt_info 是一个对应字节数的合法 NP SRAM 指针——只要它直接来自对应事件码接收到的 WifiEvent,这个前提就一直成立。

API 参考

快速用法

use ameba_wifi::WifiEvent;
use ameba_wifi::wifi::SecurityType;
use ameba_wifi::wifi::events::{event_code, join_status, read_join_status};

ameba_hal::init(ameba_hal::Config::default());
ameba_wifi::init();
spawner.spawn(whc_task()).unwrap(); // async fn whc_task() { ameba_wifi::run_blk_api().await; }

ameba_wifi::wifi::wifi_on().await;
ameba_wifi::wifi::wifi_connect("MySSID", "", SecurityType::Open).await;

let evt: WifiEvent = ameba_wifi::EVENT_CHAN.receive().await;
if evt.event_code == event_code::JOIN_STATUS {
    let status = unsafe { read_join_status(evt.evt_info) };
    // ...
}

let mac = ameba_wifi::wifi::netif_mac(); // Option<[u8; 6]>,在 wifi_on 的 SET_NETIF_INFO 到达后才会有值