简介

Wio Terminal 主 MCU 是 Microchip SAMD51，但 Wi-Fi/蓝牙无线部分用的是 Realtek RTL8720 协处理器。这俩芯片是分开运行的——你的 Arduino 程序跑在 SAMD51 上，但 Wi-Fi 收发是由 RTL8720 独立完成的，两者之间用一套基于串口的 eRPC 协议通信。所以"让 Wio Terminal 连上 WiFi"这件事至少要做两件事：

1. 给 RTL8720 烧入能用的固件（很多板子出厂的旧固件要更新）；

2. 在 SAMD51 这一侧把 Seeed 官方封装好的 Wi-Fi / Socket / HTTPClient / MQTT 库装齐，通过 RPC 调用协处理器。

这篇文章主要记录这两步的实际操作顺序和我从 Seeed 官方 Wiki 整理出来的注意事项。具体到 WiFi.begin() 怎么传 SSID、socket.connect() 怎么用、怎么订阅 MQTT topic 这一层 API 用法，Seeed 的概览页里没有列出代码，下文会指出需要去看哪些子页。

准备工作

下面是真正动手之前需要凑齐的东西：

实现思路

整个系统的物理链路是这样的：

[Arduino 程序（跑在 SAMD51）]  -> eRPC（基于 UART 的远程过程调用）-> [ RTL8720 协处理器 ] ->Wi-Fi 射频 - >[ 路由器 / 云 ]

Wiki 上有一句概括这个架构的英文原文挺重要的："We have moved the Wi-Fi Software to the new eRPC Structure which is more stable and can work with Bluetooth at the same time."

意思是 RTL8720 上跑着一个 RTOS（Ameba D），Wi-Fi 和 BT 都在它上面；SAMD51 这一侧的所有 "WiFi.* / SOCKET / HTTPClient" 调用都是通过 eRPC 转发过去、由 RTL8720 执行——这也是为什么库名都带 rpc 前缀。不能绕过 SAMD51 直接用 AT 命令和 RTL8720 对话，这点 Wiki 上明确说了："you cannot directly communicate with RTL8720"。

这套架构带来的实际含义：

• 你在 Arduino 里写的 WiFi.begin() 看起来像本地调用，但实际执行发生在另一颗芯片；

• 串口被 SAMD51 自己占用做 USB-CDC 输出给电脑，无法同时做和 RTL8720 的通信——所以硬件上 RTL8720 走的是另一组 UART（具体引脚 Wiki 未给出，需要看原理图）；

• 任何 Wi-Fi 操作有"跨芯片往返"的开销，但几百毫秒级，对一般应用无感。

核心代码：先把版本跑出来 (可以先烧录这个代码判断固件是否烧录)

Wiki 上唯一贴出的、能直接验证整条链路是否通的例子是「打印 RTL8720 固件版本」。我建议任何 Wio Terminal Wi-Fi 项目第一步都跑这个，因为它能在不依赖网络的前提下验证三件事：库装对了、SAMD51↔RTL8720 通信通了、固件烧入成功。

#include "rpcWiFi.h"
#include <erpc/erpc_port.h>
 
void setup() {
    Serial.begin(115200);
    while(!Serial); // Wait to open Serial Monitor
    char* version = rpc_system_version();
    Serial.print("RTL8720 Firmware Version: ");
    Serial.println(version);
    erpc_free(version);
}
 
void loop() {
}

三处要注意：

1. rpcWiFi.h 来自 Seeed_Arduino_rpcWiFi 库；

2. rpc_system_version() 返回的是 const char*，直接 Serial.println 打印；

3. erpc_free() 释放 eRPC 启动后占用的资源，避免下一次 setup() 重复初始化时报错。

Wiki 在 setup() 起始还加了一句说明："Wait to open Serial Monitor"——意思是 SAMD51 默认会等 USB-CDC 串口打开再继续，这也是为什么先跑版本检查就能验证 USB CDC 这条链路。

如果串口能正常打出版本号，说明 SAMD51→RTL8720 的 eRPC 通道已经正常工作，下一步就可以做实际连接了。

烧录 RTL8720 固件（ambd_flash_tool）

Wiki 给的烧录流程分两步：第一次先用 erase 清出厂固件，之后用 flash 写入新固件。

Windows PowerShell：

cd ~
git clone https://github.com/Seeed-Studio/ambd_flash_tool
cd ambd_flash_tool


.\ambd_flash_tool.exe flash
.\ambd_flash_tool.exe flash -d [RTL8720-firmware-path]

macOS / Linux Terminal：

cd ~
git clone https://github.com/Seeed-Studio/ambd_flash_tool
cd ambd_flash_tool
python3 ambd_flash_tool.py erase
python3 ambd_flash_tool.py flash
python3 ambd_flash_tool.py flash -d [RTL8720-firmware-path]

下图为下载好的烧录工具

执行清除命令，擦除原本固件

烧录固件

烧录过程中屏幕如下所示

特别提醒的点：

• 第一次必须先 erase——"The initial erase process may take a while. Please be patient and do not close the window"；

• erase 只用一次——"You only need to erase the factory firmware for the very first time. Afterwards, you can flash new firmware to overwrite the existing firmware"，之后直接 flash 覆盖；

• 串口是自动检测的——"The connected serial port of the Wio Terminal will be automatically detected!"；

• 老固件目录里必须包含三个文件：km0_boot_all.bin、km0_km4_image2.bin、km4_boot_all.bin，新固件不一定还保留这个目录结构；

• 不知道命令怎么用就 .\ambd_flash_tool.exe 或 python3 ambd_flash_tool.py 不带参数跑出 help。

测试过程与结果

固件版本信息如下所示

看到这一行说明：USB-CDC 串口正常、Seeed_Arduino_rpcWiFi 等库安装正确、SAMD51 ↔ RTL8720 通信链路正常、SAMD51 ↔ RTL8720 通信链路正常、RTL8720 上有可用固件。

如果打不出来：

到这一步通过之后， 来使用下述代码连接WiFi

#include "rpcWiFi.h"

const char* ssid = "ImmortalWrt";
const char* password =  "xxxxxxx";

void setup() {
    Serial.begin(115200);
    while(!Serial); // Wait for Serial to be ready

    // Set WiFi to station mode and disconnect from an AP if it was previously connected
    WiFi.mode(WIFI_STA);
    WiFi.disconnect();

    Serial.println("Connecting to WiFi..");
    WiFi.begin(ssid, password);

    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.println("Connecting to WiFi..");
        WiFi.begin(ssid, password);
    }
    Serial.println("Connected to the WiFi network");
    Serial.print("IP Address: ");
    Serial.println (WiFi.localIP()); // prints out the device's IP address
    }

void loop() {

}

成功获取到IP效果如下

踩坑记录

Wiki 里提到、值得提前注意的几个坑：

1. RTL8720 固件必须先更新：固件旧了 Wi-Fi 行为不可预期，不要在没烧固件的情况下直接调 WiFi.begin()；

2. erase 只用一次：搞反顺序（先 flash 再 erase）反而容易把固件区搞乱；

3. erase 第一次要等：大概几分钟，期间不要断电；

4. 不要绕过 SAMD51 直接对 RTL8720 发 AT 命令：RTL8720 的串口是内部连到 SAMD51 的，没有引出到 USB，外部上位机看不到；从 Arduino IDE 的串口监视器发出 AT 命令是没用的；

5. eRPC 同时支持蓝牙：如果你 BLE，建议用新版固件，旧版可能和 BT 冲突。

总结

把 Wio Terminal 接上 WiFi 的前置工作集中在两步：

1. 烧 RTL8720 固件（ambd_flash_tool erase + flash），并装齐 Seeed_Arduino_rpcWiFi / rpcUnified / mbedtls / FS / SFUD 五个库；

2. 跑通 rpc_system_version() 这个最简示例，确认 SAMD51↔RTL8720 的 eRPC 通道是通的。

之后就是测一下MQTT的连通性了。目前的话WIki并没有看很多，所以暂时不清楚MQTT是否兼容