Implementing and Applying a Lightweight Network Protocol Stack on STM32

For network communication on resource-constrained microcontrollers, lwIP (lightweight IP) is an ideal choice. lwIP is a lightweight TCP/IP protocol stack designed specifically for embedded systems.

Basics of lwIP

What is a Network Protocol Stack?

Imagine the process of sending a package:

• Application Layer: The item you want to send (data)
• Transport Layer: Choosing a courier service (TCP/UDP)
• Network Layer: Filling in the address (IP address)
• Link Layer: Actual transportation (Ethernet)

lwIP is like this “courier system” that helps you package, address, and transport data in a standard format.

Architecture of lwIP

The lwIP protocol stack mainly consists of the following modules:

┌─────────────────────────────────────┐
│  Application Layer (HTTP/MQTT/Custom Protocol)      │
├─────────────────────────────────────┤
│  Transport Layer (TCP/UDP)                   │
├─────────────────────────────────────┤
│  Network Layer (IP/ICMP)                   │
├─────────────────────────────────────┤
│  Link Layer (ARP/Ethernet Driver)            │
├─────────────────────────────────────┤
│  Hardware Abstraction Layer (PHY/MAC Driver)           │
└─────────────────────────────────────┘

Description of Core Components:

1. Memory Management: lwIP manages memory using both memory pools (memp) and heap memory.
2. Network Interface (netif): Each network interface corresponds to a physical network connection.
3. Protocol Implementations: TCP, UDP, IP, ICMP, ARP, etc.
4. Application Interfaces: Three programming interfaces: Raw API, Netconn API, Socket API.

Three Programming Interfaces of lwIP

1. Raw API

• Lowest level, highest performance
• Requires understanding of protocol details
• Suitable for scenarios with extremely high performance requirements

2. Netconn API

• Medium level of abstraction
• Thread-safe, suitable for multi-threaded environments
• Commonly used with STM32 HAL library

3. Socket API

• Closest to standard BSD Socket
• Easy to port PC-side code
• Requires operating system support

Porting lwIP on STM32

Hardware Requirements

To implement network communication on STM32, the following hardware is required:

1. STM32 Chip: Models that support Ethernet peripherals (e.g., STM32F407, STM32H743, etc.)
2. PHY Chip: Physical layer chip (e.g., LAN8742A, LAN8720A, etc.)
3. Network Transformer: RJ45 interface module (usually integrated on the development board)
4. External Clock: 25MHz crystal oscillator (required by PHY chip)

Software Architecture

The typical architecture for using lwIP on STM32 is as follows:

┌─────────────────────────────────────┐
│  User Application Code                        │
├─────────────────────────────────────┤
│  lwIP Protocol Stack (lwip.c/h)              │
├─────────────────────────────────────┤
│  STM32 HAL Ethernet Driver                │
│  (stm32f4xx_hal_eth.c)              │
├─────────────────────────────────────┤
│  PHY Driver (lan8742.c)                │
├─────────────────────────────────────┤
│  Hardware Layer (MAC + PHY)                 │
└─────────────────────────────────────┘

Key Steps for Porting

Configure lwIP Parameters

Configure key parameters in lwipopts.h:

• LWIP_TCP: Enable TCP (usually required)
• LWIP_UDP: Enable UDP
• TCP_MSS: Maximum segment size for TCP (default 536 bytes)
• TCP_WND: TCP window size
• MEM_SIZE: Memory pool size (adjust according to RAM)
• PBUF_POOL_SIZE: Size of PBUF pool (affects the number of concurrent connections)

Implement Network Interface Initialization

The following functions need to be implemented:

• low_level_init(): Initialize MAC and PHY
• low_level_output(): Send data packets
• ethernetif_input(): Handle received data packets

Configure Clocks and Interrupts

• Configure system clock (usually requires above 168MHz)
• Configure Ethernet MAC clock
• Enable Ethernet receive interrupts

Start lwIP Task

Create lwIP tasks in FreeRTOS and periodically call sys_check_timeouts() to handle timeouts.

Basic Network Communication

TCP Server Example

The basic process for implementing a TCP server is as follows:

1. Create Connection: Use netconn_new() to create a TCP connection
2. Bind Port: Use netconn_bind() to bind the local port
3. Listen for Connections: Use netconn_listen() to start listening
4. Accept Connection: Use netconn_accept() to accept client connections
5. Send and Receive Data: Use netconn_recv() and <code>netconn_write() to transmit data
6. Close Connection: Use netconn_close() to close the connection

Key Points:

• TCP is connection-oriented and requires establishing a connection first
• The server needs to continuously listen, usually placed in a separate task
• It is recommended to create a separate task for each client connection

UDP Communication Example

UDP communication is simpler:

1. Create Connection: Create a UDP type netconn
2. Bind Port: Bind the local port
3. Send Data: Use netconn_sendto() to send to a specified address
4. Receive Data: Use netconn_recvfrom() to receive data

Key Points:

• UDP is connectionless and does not require establishing a connection
• Suitable for scenarios with high real-time requirements and allowed packet loss
• The application layer needs to handle packet loss and out-of-order delivery

DHCP Automatic IP Acquisition

The steps to automatically acquire an IP address using DHCP are:

1. Enable LWIP_DHCP in lwipopts.h
2. Call dhcp_start() after initializing the network interface
3. Periodically call dhcp_fine_tmr() and dhcp_coarse_tmr()
4. Check the status of netif_is_up() and netif_is_link_up()

Advantages: No manual IP configuration is required, and the device can automatically connect to the network.

Troubleshooting

Network Cannot Connect, Ping Fails

Possible Causes and Solutions:

1. PHY Chip Not Initialized

• Check the reset and configuration of the PHY chip
• Confirm if the PHY address is correct (usually 0 or 1)
• Use an oscilloscope to check if the 25MHz clock is normal

2. MAC Address Not Set

• Ensure a unique MAC address is set during initialization
• MAC address format: 6 bytes, e.g., {0x02, 0x00, 0x00, 0x00, 0x00, 0x01}

3. Network Interface Not Started

• Check if netif_add() was successful
• Confirm that netif_set_up() and netif_set_link_up() have been called
• Check the status bits of netif->flags

4. Incorrect IP Address Configuration

• Static IP: Check if IP, subnet mask, and gateway are correct
• DHCP: Confirm if the DHCP server is reachable, check the return value of dhcp_supplied_address()

Debugging Tips:

• Use netif_list to traverse all network interfaces and check their status
• Print netif->ip_addr to view the current IP address
• Use Wireshark to capture and analyze network traffic

TCP Connection Frequently Drops

Possible Causes and Solutions:

1. Insufficient Memory

• Increase MEM_SIZE and PBUF_POOL_SIZE
• Check for memory leaks (unreleased netbuf)
• Use mem_malloc() and mem_free() to track memory usage

2. Timeout Settings Too Short

• Adjust TCP_MSL (maximum segment lifetime)
• Increase TCP_KEEPALIVE related parameters
• Check the application layer heartbeat mechanism

3. Receive Buffer Overflow

• Increase TCP_WND (receive window)
• Call netconn_recv() promptly to read data
• Use netconn_set_recvtimeout() to set receive timeout

4. Network Congestion

• Check network quality (packet loss rate, latency)
• Adjust TCP_MSS to reduce packet size
• Implement application layer retransmission mechanism

Debugging Tips:

• Enable LWIP_STATS to track TCP connection status
• Use tcp_debug_print_pcbs() to print all TCP connection information
• Monitor the length of tcp_active_pcbs linked list

Slow Data Transfer Speed

Possible Causes and Solutions:

1. TCP Window Too Small

• Increase TCP_WND (recommended to be 4-8 times TCP_MSS)
• Enable TCP_WND_UPDATE_THRESHOLD to optimize window updates

2. Insufficient Send Buffer

• Increase TCP_SND_BUF (send buffer size)
• Check the write size limit of netconn_write()

3. Task Priority Too Low

• Increase the priority of the lwIP task
• Ensure the Ethernet interrupt priority is high enough
• Avoid performing time-consuming operations in interrupts

4. Improper PHY Configuration

• Check if full-duplex mode is enabled
• Confirm PHY working rate (10M/100M)
• Check if auto-negotiation was successful

Performance Optimization Suggestions:

• Use Raw API instead of Netconn API (20-30% performance improvement)
• Enable LWIP_TCP_FAST_OPEN (if supported)
• Batch send data to reduce system call frequency

DHCP IP Acquisition Failure

Possible Causes and Solutions:

1. DHCP Server Unreachable

• Confirm that the device and router are on the same subnet (initial state)
• Check cable connections and network interface status
• Test network connectivity using a static IP

2. DHCP Timeout Setting Too Short

• Increase DHCP_TIMEOUT and DHCP_T1, DHCP_T2
• Check the calling frequency of dhcp_fine_tmr()

3. Insufficient Memory

• DHCP requires additional memory space
• Ensure MEM_SIZE is large enough

4. Multiple Network Card Conflicts

• Ensure DHCP is enabled on only one network interface
• Check the number of interfaces in netif_list

Debugging Tips:

• Enable LWIP_DEBUG and DHCP_DEBUG
• Print the DHCP state machine status (dhcp->state)
• Use Wireshark to capture and view the DHCP interaction process

Memory Leak Causing System Crash

Possible Causes and Solutions:

1. netbuf Not Released

• Must call netbuf_delete() after each netconn_recv()
• Use the return value of netconn_recv() to check for data

2. netconn Not Closed

• Must call netconn_delete() after the connection is closed
• Close the connection after the server has processed the client

3. PBUF Leak

• Check for unreleased PBUF in custom code
• Use pbuf_free() to release PBUF

4. Memory Pool Exhaustion

• Monitor MEMP_STATS statistics
• Increase the corresponding memory pool size

Preventive Measures:

• Regularly check using memory statistics features
• Implement memory usage monitoring and alerts
• Focus on resource release during code reviews

Race Conditions in Multi-threaded Environments

Possible Causes and Solutions:

1. lwIP Core Functions Not Thread-Safe

• Use sys_mutex to protect critical sections
• Alternatively, use tcpip_callback() to submit operations to the lwIP thread

2. Network Interface Operation Conflicts

• Avoid operating the network interface simultaneously in interrupts and tasks
• Use message queues to pass network events

3. Shared Data Structure Access

• Use mutexes to protect shared netconn structures
• Avoid performing time-consuming operations in callback functions

Solutions:

• All lwIP API calls should be made within the lwIP task
• Use tcpip_callback() to safely call lwIP functions from other threads
• Notify the application layer of network events through message queues

Debugging Tips and Tools

Using Wireshark for Packet Analysis

Steps:

1. Install Wireshark on your PC
2. Connect the STM32 device to the same network as the PC
3. Select the network interface in Wireshark to start capturing packets
4. Filter specific IPs or protocols for analysis

Common Filter Conditions:

• ip.addr == 192.168.1.100: Filter specific IP
• tcp.port == 80: Filter TCP port 80
• dhcp: Show only DHCP packets

Enable lwIP Debug Information

Enable debugging in lwipopts.h:

#define LWIP_DEBUG 1
#define TCP_DEBUG LWIP_DBG_ON
#define NETIF_DEBUG LWIP_DBG_ON
#define DHCP_DEBUG LWIP_DBG_ON

Note: Debug information will significantly increase code size and runtime; it should be disabled in release versions.

Using Ping to Test Connectivity

Basic Usage:

• ping 192.168.1.100: Test if the device is reachable
• ping -t 192.168.1.100: Continuous ping (Windows)
• ping -c 10 192.168.1.100: Send 10 packets (Linux)

Analysis Metrics:

• Response time: Should normally be less than 10ms (LAN)
• Packet loss rate: Should be 0%
• TTL value: Check the number of routing hops

Memory Usage Monitoring

After enabling statistics features, you can print memory usage:

// Print memory statistics
printf("MEM: used=%d, max=%d, err=%d\n", 
       lwip_stats.mem.used, 
       lwip_stats.mem.max, 
       lwip_stats.mem.err);

// Print PBUF statistics
printf("PBUF: used=%d, max=%d\n", 
       lwip_stats.pbuf.used, 
       lwip_stats.pbuf.max);

Basics of lwIP

What is a Network Protocol Stack?

Architecture of lwIP

Three Programming Interfaces of lwIP

Porting lwIP on STM32

Hardware Requirements

Software Architecture

Key Steps for Porting

Basic Network Communication

TCP Server Example

UDP Communication Example

DHCP Automatic IP Acquisition

Troubleshooting

Network Cannot Connect, Ping Fails

TCP Connection Frequently Drops

Slow Data Transfer Speed

DHCP IP Acquisition Failure

Memory Leak Causing System Crash

Race Conditions in Multi-threaded Environments

Debugging Tips and Tools

Using Wireshark for Packet Analysis

Enable lwIP Debug Information

Using Ping to Test Connectivity

Memory Usage Monitoring

Related posts

Leave a Comment Cancel reply