Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for a specific release, use the drop-down menu on the left.

IPv4 NAT User Guide

Description

RT-Smart provides stateful IPv4 NAPT based on lwIP, allowing clients on internal interfaces to access external networks through the uplink interface selected by the system. TCP, UDP, and ICMP Echo are currently supported. A typical scenario has a Wi-Fi STA connected to an upstream router while a Wi-Fi SoftAP provides DHCP and network sharing for terminals:

SoftAP client
    |
    | 192.168.169.0/24 (default)
    v
K230 SoftAP (internal interface) -> IPv4 NAPT -> default uplink (WLAN STA or LAN)

NAT uses the actual routing result to select the external interface and rewrites the source address to the IPv4 address of that external interface. Therefore, the uplink interface must have acquired a non-zero IP address, gateway, and default route. After the default route changes, new sessions may use the new uplink interface; existing sessions remain bound to the original external interface, and applications should be allowed to reconnect when switching networks.

Build Configuration

Load the target board configuration in the SDK root directory and run:

make <board>_defconfig
make menuconfig

Confirm the following configurations under light weight TCP/IP stack:

CONFIG_RT_USING_LWIP=y
CONFIG_RT_USING_WIFI=y
CONFIG_RT_LWIP_TCP=y
CONFIG_RT_LWIP_UDP=y
CONFIG_RT_LWIP_ICMP=y
CONFIG_LWIP_USING_DHCPD=y
CONFIG_DHCPD_USING_ROUTER=y
CONFIG_LWIP_USING_NAT=y

LWIP_USING_NAT depends on TCP and UDP; the ICMP option is used to support Echo translation and ping verification. When Wi-Fi and the DHCP server are enabled, the NAT option is enabled by default, but it should still be confirmed in the final .config after upgrading an existing configuration. DHCPD_USING_ROUTER makes the DHCP server deliver the gateway address to SoftAP clients; the default server address is 192.168.169.1, and the subnet mask is 255.255.255.0.

NAT can be used with lwIP 2.1.2 or 2.2.1. For information on selecting and verifying the network stack version, see the lwIP 2.2.1 User Guide.

Capacity and Timeouts

The parameters under LWIP_USING_NAT are determined at build time:

Kconfig Option	Default	Description
LWIP_NAT_TABLE_SIZE	256	Maximum number of NAT sessions
LWIP_NAT_MAX_INTERFACES	2	Number of internal interfaces on which NAT can be enabled
LWIP_NAT_PORT_MIN	40000	Starting value of the translated source port
LWIP_NAT_PORT_MAX	45000	Ending value of the translated source port
LWIP_NAT_TCP_TIMEOUT_SECONDS	1800	Idle timeout for established TCP sessions
LWIP_NAT_TCP_CLOSE_SECONDS	30	Timeout for closing TCP sessions
LWIP_NAT_UDP_TIMEOUT_SECONDS	120	Idle timeout for UDP sessions
LWIP_NAT_ICMP_TIMEOUT_SECONDS	30	Idle timeout for ICMP Echo sessions

The session table is statically allocated. When the table is full, the least recently active entry is reused; when there are many concurrent connections, the number of entries should be increased according to available memory while ensuring that the port range is sufficient.

SoftAP Automatic Start/Stop

After compiling LWIP_USING_NAT, the RT-Thread WLAN layer automatically registers its lwIP netif as an internal interface when SoftAP enters the connected state, and disables NAT and cleans up sessions involving that interface when SoftAP stops or the device is deregistered. The DHCP server also starts and stops with SoftAP.

First, allow STA or the LAN uplink to obtain an address and default route, and then start SoftAP. For example:

wifi devices
wifi join <uplink-ssid> <uplink-password>
wifi ap <ap-ssid> <ap-password>
ifconfig
nat

When multiple Wi-Fi devices are present, use wifi devices to find the target management device, and then use wifi -i <管理设备或 netdev> ... to select the interface. The uplink and SoftAP can come from the same radio supporting concurrent STA/AP operation, or from different network devices.

The nat command only displays status and does not modify the configuration. Typical output is similar to:

internal interface: wlan0ap
NAT: enabled, sessions: 3/256 (TCP 2, UDP 1, ICMP 0)

NAT sessions belong to the forwarding state rather than local sockets, so they do not appear in the local TCP or UDP PCB lists in netstat.

Enabling NAT for Other Internal Interfaces

The WLAN SoftAP automatically manages the NAT lifecycle. Other internal interfaces can call the thread-safe interface in a non-lwIP core thread:

#include <ipv4_nat.h>

err_t result;

result = ip_nat_set_enabled(internal_netif, 1);
if (result != ERR_OK) {
    /* Invalid argument or no internal interface slots remaining. */
}

/* Disable NAT before the interface stops or is deregistered, and clean up related sessions. */
ip_nat_set_enabled(internal_netif, 0);

internal_netif must be a valid struct netif *, and its lifetime must cover the enabled period. This interface only declares the “internal side”; the external side is still selected by the lwIP routing table. Do not register the uplink interface as an internal interface as well.

Limitations

• Only IPv4 is supported; IPv6 NAT and NAT64 are not provided;

• Only TCP, UDP, and ICMP Echo are translated; other IP protocols are not translated;

• IPv4 fragmentation, port forwarding, and ICMP error payload conversion are not supported;

• External inbound connections without a matching existing session are not accepted;

• NAT is not an application-layer proxy and does not correct IP addresses or ports carried in protocol payloads;

• NAT is not equivalent to a full firewall, and products still need to implement security policies in service listening, access control, and the uplink network side.

Troubleshooting

1. nat shows disabled: Confirm that the final configuration contains CONFIG_LWIP_USING_NAT=y, and confirm that SoftAP has started successfully rather than merely having the AP device registered.

2. The client cannot obtain an address or gateway: Confirm that LWIP_USING_DHCPD and DHCPD_USING_ROUTER are enabled, and check the 192.168.169.1/24 address of the SoftAP netif.

3. The client has an address but cannot access the Internet: First check the uplink IP, gateway, DNS, and default route on the K230 itself, and then confirm that the uplink interface is not a NAT internal interface.

4. ping works, but TCP/UDP is unstable: Run nat to check table entry usage, and verify that the port ranges and per-protocol timeouts are suitable for the concurrency level.

5. Large packets or some protocols fail: Capture packets to check for IPv4 fragmentation or addresses embedded in payloads; these scenarios are outside the current NAT support scope.

Source Locations

• src/rtsmart/rtsmart/kernel/rt-thread/components/net/lwip_nat/

• src/rtsmart/rtsmart/kernel/rt-thread/components/drivers/wlan/wlan_lwip.c

• src/rtsmart/rtsmart/kernel/rt-thread/components/net/lwip_dhcpd/