Wi-Fi R-NAPT

支持的芯片[ RTL8721F ]

Wi-Fi R-NAPT 使用指南

本章基于 example_rnapt.c 介绍 R-NAPT 的配置方法与使用流程。方案原理请参考 Wi-Fi R-NAPT。

备注

参考基于 CLI 的编译与下载进行编译与烧录。

支持的网络接口

R-NAPT 支持以下四种物理接口，可按需配置为 WAN（上行）或 LAN（下行）角色。

Wi-Fi STA（仅 WAN）

连接上游路由器，获取 IP 后作为 WAN 上行接入点。需在 Wi-Fi 开发者配置中关闭 Fast Reconnect：

wifi_user_config.fast_reconnect_en = 0;

Wi-Fi SoftAP（仅 LAN）

以热点模式运行，供下游无线客户端接入，作为 LAN 下行接口。

Ethernet（WAN / LAN）

作为 WAN：连接至上游路由器/交换机（需提供 DHCP 服务）
作为 LAN：连接 PC 或其他设备（由 Ameba 提供 DHCP 服务）

配置请参考以太网。

USB ECM（WAN / LAN）

支持 USB Host 和 USB Device 两种工作模式。

作为 WAN：通过 USB 接入上游网络
作为 LAN：通过 USB 为下游设备提供网络接入

配置请参考 USB CDC ECM 。

接口配置

所有接口的配置通过 rnapt_netif.h 中定义的 rnapt_netif_config_t 结构体描述，在 example_rnapt.c 中以全局变量形式声明。

rnapt_netif_config_t 字段说明

字段	类型	说明
`role`	`rnapt_role_t`	接口角色： `RNAPT_ROLE_WAN` 或 `RNAPT_ROLE_LAN`
`ip_method`	`rnapt_ip_method_t`	IP 获取方式： `RNAPT_IP_METHOD_DHCP_CLIENT` / `RNAPT_IP_METHOD_DHCP_SERVER` / `RNAPT_IP_METHOD_STATIC`
`priority`	`int`	路由优先级，数值越大越优先成为默认网关
`ip_info`	`const rnapt_ip_info_t *`	自定义 IP 配置指针， `NULL` 时系统自动分配
`if_desc`	`const char *`	接口描述字符串（如 `"STA"` 、 `"AP"` ）
`status_callback`	函数指针	link 状态变化时的用户回调函数， `NULL` 表示不注册
`callback_user_data`	`void *`	传递给回调函数的用户数据指针

WAN/LAN 角色与 IP 模式约束

role 与 ip_method 的组合有如下约束：

角色	允许的 ip_method	说明
`RNAPT_ROLE_WAN`	`DHCP_CLIENT` 、 `STATIC`	WAN 接口不允许使用 `DHCP_SERVER` 模式
`RNAPT_ROLE_LAN`	`DHCP_SERVER` 、 `STATIC`	LAN 接口不允许使用 `DHCP_CLIENT` 模式

优先级配置

priority 字段决定多 WAN 场景下默认网关的选择顺序，数值越大优先级越高。 example_rnapt.h 中预定义了以下推荐值：

宏定义	值	适用场景
`RNAPT_ROUTE_PRIO_WAN_ETH`	103	以太网作为 WAN
`RNAPT_ROUTE_PRIO_WAN_STA`	102	Wi-Fi STA 作为 WAN
`RNAPT_ROUTE_PRIO_WAN_USB`	101	USB-ETH 作为 WAN
`RNAPT_ROUTE_PRIO_LAN`	0	LAN 接口（固定最低优先级）

IP 地址配置

方式 A：自定义 IP

定义 rnapt_ip_info_t 结构体并赋值给 ip_info 字段：

static const rnapt_ip_info_t g_ap_custom_ip = {
    .ip      = { .addr = PP_HTONL(LWIP_MAKEU32(192, 168, 39, 1)) },
    .gw      = { .addr = PP_HTONL(LWIP_MAKEU32(192, 168, 39, 1)) },
    .netmask = { .addr = PP_HTONL(LWIP_MAKEU32(255, 255, 255, 0)) }
};

const rnapt_netif_config_t g_rnapt_ap_netif_config = {
    .role      = RNAPT_ROLE_LAN,
    .ip_method = RNAPT_IP_METHOD_DHCP_SERVER,
    .priority  = RNAPT_ROUTE_PRIO_LAN,
    .ip_info   = &g_ap_custom_ip,
    .if_desc   = "AP",
    /* ... */
};

备注

若指定的自定义 IP 与已有接口存在网段冲突，系统会自动从地址池（192.168.43.x ~ 192.168.254.x）中重新分配一个不冲突的 IP，并打印以下警告：

[R-NAPT-W] [AP] Custom IP subnet conflicts, auto-allocating...
Netif 1 alloc IP: 192.168.43.1

方式 B：自动分配 IP

将 ip_info 设为 NULL，系统自动处理：LAN 接口从地址池中分配不冲突的 IP，WAN 接口通过 DHCP 从上游路由器获取 IP。

const rnapt_netif_config_t g_rnapt_eth_netif_config = {
    .role      = RNAPT_ROLE_LAN,
    .ip_method = RNAPT_IP_METHOD_DHCP_SERVER,
    .priority  = RNAPT_ROUTE_PRIO_LAN,
    .ip_info   = NULL,   /* 自动分配 */
    .if_desc   = "ETH",
    /* ... */
};

Wi-Fi 配置

Wi-Fi 接口（STA 和 SoftAP）通过 rnapt_wifi_config_t 结构体传递 Wi-Fi 参数，在调用 rnapt_netif_start() 时作为第二个参数传入。以太网和 USB-ETH 接口该参数传 NULL。

/* STA：连接上游路由器 */
static const rnapt_wifi_config_t g_sta_wifi_config = {
    .ssid     = "AmebaWiFi",
    .password = "12345678",
    .channel  = 0          /* 0 表示自动扫描信道 */
};
rnapt_netif_start(sta_netif, (void *)&g_sta_wifi_config);

/* SoftAP：创建热点 */
static const rnapt_wifi_config_t g_ap_wifi_config = {
    .ssid     = "AmebaRouter",
    .password = "12345678",
    .channel  = 0          /* 0 表示自动选择信道 */
};
rnapt_netif_start(ap_netif, (void *)&g_ap_wifi_config);

Status Callback

每个接口支持注册用户回调函数，当接口 link 状态发生变化（up/down）时触发。

回调函数原型：

void user_netif_status_cb(rnapt_netif_t *netif, bool is_active, void *user_data);

netif：发生状态变化的接口对象
is_active：true 表示 link up，false 表示 link down
user_data：注册时传入的用户自定义数据指针

注册方式一：在配置结构体中注册

const rnapt_netif_config_t g_rnapt_sta_netif_config = {
    /* ... */
    .status_callback    = user_netif_status_cb,
    .callback_user_data = NULL
};

注册方式二：动态设置

rnapt_netif_set_status_callback(netif, user_netif_status_cb, user_data);

预期运行结果

以下日志以 STA 作为 WAN、AP 和 ETH 均作为 LAN 的典型配置为例。

1. 系统初始化

[R-NAPT-APP-A] ========================================
[R-NAPT-APP-A]             R-NAPT Example
[R-NAPT-APP-A] ========================================

2. STA 连接上游路由器（WAN）

[R-NAPT-I] [STA] Created (role=WAN, ip_method=0, prio=102)
[R-NAPT-I] [STA] Connecting to 'AmebaWiFi'...
[R-NAPT-I] [STA] LINK UP - ACTIVE
[R-NAPT-APP-A] [USER-CB] STA Link UP
[R-NAPT-I] [STA] WAN got new IP, reinitializing NAPT
[R-NAPT-I] Default GW changed to: 192.168.39.9 (STA, prio=102)
[$]wifi got ip:"192.168.39.9"

3. AP 启动（含 IP 冲突自动处理）

[R-NAPT-W] [AP] Custom IP subnet conflicts, auto-allocating...
Netif 1 alloc IP: 192.168.43.1
[R-NAPT-I] [AP] Created (role=LAN, ip_method=1, prio=0)
[R-NAPT-I] [AP] LINK UP - ACTIVE
[R-NAPT-APP-A] [USER-CB] AP Link UP

AP 的自定义 IP 192.168.39.1 与 STA 获得的 192.168.39.9 同属 192.168.39.x 网段，系统自动检测到冲突并重新分配为 192.168.43.1。

4. ETH 插线后

[R-NAPT-I] [ETH] LINK UP - ACTIVE
[R-NAPT-APP-A] [USER-CB] ETH Link UP
[R-NAPT-I] [ETH] DHCP Server started: 192.168.44.1
[$]assign client ip:"192.168.44.100",hwaddr:"00:e0:4c:b7:23:66"

5. 最终状态汇总

[R-NAPT-A] ========== R-NAPT Status ==========
[R-NAPT-A] [STA] UP: IP=192.168.39.9  GW=192.168.39.1  Role=WAN  Method=DHCP-Client  Prio=102  [DEFAULT GW]
[R-NAPT-A] [AP]  UP: IP=192.168.43.1  GW=192.168.43.1  Role=LAN  Method=DHCP-Server  Prio=0
[R-NAPT-A] [ETH] UP: IP=192.168.44.1  GW=192.168.44.1  Role=LAN  Method=DHCP-Server  Prio=0
[R-NAPT-A] ====================================

此时 LAN 侧设备可通过 Ameba 的 NAT 转发访问互联网：

Wi-Fi 客户端 (192.168.43.100) → AP  → NAT → STA (192.168.39.9) → 互联网
有线客户端   (192.168.44.100) → ETH → NAT → STA (192.168.39.9) → 互联网