How to Integrate an lwIP TCP/IP Stack into Embedded Applications

Abstract

The use of a TCP/IP stack is widespread in Ethernet communication interfaces for local and wide area networks. Lightweight TCP/IP (lwIP) is a scaled down implementation of the TCP/IP protocol focused on reducing RAM usage. This article provides guidance on integrating the lwIP TCP/IP stack into an embedded application, ultimately streamlining the development process and saving time and effort.

Introduction

The lightweight TCP/IP (lwIP) stack is a compact implementation of the TCP/IP protocol suite tailored to minimize RAM usage, making it well-suited for embedded systems. It provides three distinct application programming interfaces (APIs):

Low level raw APIs
Higher level netconn APIs
BSD style socket APIs

This article will focus exclusively on examples using the raw API interface. The raw API is event-driven and is designed to operate without an underlying operating system. Applications employing the raw API implement callback functions that are triggered by core events.

Despite being more intricate than the socket API, the raw API offers significantly higher throughput due to its lower overhead.

Various demo examples built on the lwIP TCP/IP stack will be discussed utilizing Analog Devices’ MAX32570 microcontroller. The initial section delves into a ping demo, demonstrating how to ping the device from a PC. The subsequent section provides insights into a TCP Echo server example, which serves as a rudimentary server demo, useful for testing TCP connections.

ADI’s MaximSDK software development kit contains the necessary software and tools to develop firmware for ADI’s MSX32xxx microcontrollers. It includes an lwIP stack library file, “MaximSDK\Libraries\lwIP”. Figure 1 shows the lwIP library files in the MaximSDK folder structure.

Figure 1. ADI’s MaximSDK lwIP library files.

The lwIP folder contains different subfolders:

API folder (netconn and socket APIs)
Core folder (lwIP core files including “tcp.c”, “ip.c,” etc.)
Netif folder (network interface files)
Include folder (all lwIP include files)
Maxim folder (customized mac driver for ADI’s microcontroller)

The lwIP architecture follows a TCP/IP model structure. The TCP/IP protocol is a combination of different protocols at various layers. TCP/IP is normally considered to be a 4-layer system as shown in Figure 2.

An lwIP project always contains a configuration file named “lwipopts.h” and a default configuration file called “opt.h”. The “opt.h” file contains all the default stack configurations and its module configurations, whereas the “lwipopts.h” allows the user to fully configure the stack and its modules. Note that this file does not include all the possible lwIP options. So, if a configuration is not defined in the “lwipopts.h” file, the default configuration defined in the “opt.h” will be considered.

Similarly, the lwIP library has one application specific header file called “lwipcfg.h”. The controller’s IP address, gateway address, netmask address, and MAC address should be defined in the “lwipcfg.h” file as shown in Figure 3.

To establish a connection between lwIP and the underlying hardware drivers, a platform-specific adaptation layer is necessary. For instance, when implementing the lwIP stack for a microcontroller, a tailored driver is required to bridge the lwIP stack and the microcontroller’s Ethernet MAC drivers. This custom driver should encompass the following functionalities:

Initialization function: This function is responsible for initializing the MAC driver specific to the microcontroller.
Send function: It facilitates the transfer of data received from the TCP stack to the Ethernet MAC driver for subsequent transmission.
Receive function: This handles the forwarding of packets received from the Ethernet MAC driver to the TCP stack.

For the ADI microcontroller, a pre-existing customized driver can be found in the MaximSDK at the path “MaximSDK\Libraries\lwIP\Maxim\mxc_eth.c.” This driver serves as a wrapper around the microcontroller’s own Ethernet MAC (EMAC) peripheral library, which is located in the peripheral drivers at “C:\MaximSDK\Libraries\PeriphDrivers\Source\EMAC.”

Ping Example

The “ping” command is a simple tool used for network troubleshooting. It performs an Internet Control Message Protocol (ICMP) echo request by sending a signal to a specific IP address and waits for a reply. When the destination receives this request, it replies with an echo reply packet. This section will explain how to perform a basic ping test from a Windows PC to a microcontroller to check their connectivity. It will also cover how to use the microcontrollers’ ping module to communicate with a PC.

Here’s how the Windows ping utility works:

It sends four data packets to the microcontroller and waits for a response.
The microcontroller sends these data packets back to the PC as a reply known as echo reply requests.

To run the ping test:

Connect microcontroller EVKIT to a PC using an Ethernet cable.
Open the command prompt and type “ping <IP address of microcontroller>” and press enter.

A reply in the command prompt such as that depicted in Figure 4 implies proper connectivity between the PC and the microcontroller.

Figure 4. Ping output in command prompt.

To Test Ping from the Microcontroller

The “lwIP_Ping” file is the ping example for the ADI’s MAX32570 microcontroller included within the MaximSDK. It can be found at “C:\MaximSDK\Examples\MAX32570\lwIP_Ping” and the following guidance is provided:

The IP address of the microcontroller is set using “lwipcfg.h” file. The IP address of the microcontroller and the PC should be in the same series.
The IP address of the PC should be provided as the gateway address in the microcontroller “lwipcfg.h” file.
Connect the PC and MAX32570 EVKIT using an Ethernet cable.
Run the ping example code.
Open the serial terminal in eclipse (Window-> Show view -> Terminal). The terminal will show a ping result if the ping is successful as shown in Figure 5.

Figure 5. Ping output in serial terminal.

The command prompt shows only ping statistics. To view the actual data sent, a tool called Wireshark is needed. Wireshark captures packets from a network connection. After opening Wireshark, the Ethernet option should be selected. Details will be shown such as source and destination MAC addresses, source and destination IP addresses, communication protocol, and additional data sent. This information is displayed in Wireshark as depicted in Figure 6.

Figure 6. Ping data packet in Wireshark.

As shown in the example, the data sent is 0x00, 0x01… to 0x1F. However, what if the user wants to change the data sent?

Modify Data Sent from Microcontroller Ping

The data to be sent with ping is set in the “ping. c” file. The “Ping.c” file is the ping sender module. The size of the data to be sent is set using “PING_DATA_SIZE” in the “ping.c” file. The data size is set as 32 bytes as shown in Figure 7.

The data to be sent is also defined in “ping.c” file. The additional data buffer is filled with some data as shown in Figure 8 “0x00, 0x01, 0x02…to 0x1F.”

Depending on the application, if the user wants to change the data, the data buffer can be modified in the “ping .c” file. For example, changing all 32 bytes of data to “0x01, 0x01…0x01” is shown in Figure 9.

The modified “ping .c” file provides results in Wireshark as shown in Figure 10. The data is then updated with the new parameters.

Figure 10. Modified ping data packet in Wireshark.

TCP Echo Server

The ping examples utilize ICMP to determine the responsiveness of a target system. It sends the intended recipient an echo request through the network using default data. When the destination address gets this request, it replies with an echo reply packet.

If a user wants to send customized data from one device to another, they use the TCP protocol for data transmission. The Echo service is a standard TCP functional mainly used to check reachability and identify routing problems. In this service, a server and client are established using TCP. When the server gets a message from a client, it sends that same message back.

In the MaximSDK, the “lwIP TCP” source file demonstrates how to use TCP functions within the lwIP library. In this scenario, the microcontroller acts as a TCP server and waits for a client request. The data sent from the client is echoed back. The “tcpecho_raw.c” application source files should be used within the TCP Echo server example. Follow the steps below to assign the TCP Echo server.

To set up the TCP Echo server:

Create a socket
Bind the socket to the advertised port number
Once bound, it starts listening for incoming connections
When a connection is requested, it accepts the request from the client machine
The server then receives data from the client
Lastly, it sends back the same data

Figure 11 shows a snippet of code giving an overview of the firmware structure, which is part of the main function. The config_emac function initializes the EMAC and the MXC_ETH_Init initializes the lwIP stack.

Figure 11. A snippet of code giving an overview of the firmware structure.

After the EMAC and lwIP stack initialization, the TCP Echo server is initialized using tcpecho_raw_init. The Echo server initialization structure is shown in Figure 12.

Figure 12. The Echo server initialization structure.

Echo server initialization will create a new socket. It will then bind the assigned IP address and port number to the new socket. After binding, it will listen for a connection from the remote client.

To test the TCP server example, use echotool.exe PC client utility. The echotool.exe file should be saved in the C drive and the command prompt should be opened from the C drive. In client mode, it sends data to the server and checks whether it came back as shown in Figure 13. Be sure to use the echo tool in client mode to test the server demo.

How to Test the TECP Server Example:

Ensure all connections are working properly.
Build the example code using eclipse.
Run the code in debug mode.
Open the command prompt window on the remote PC.

Enter the following in the command prompt:

“C:\>echotool IP_address /p tcp /r 7 /n 15 /t 2 /d LwIP TCP echo server 
Example”
    IP_address is the actual board IP address. The static IP address is 
    192.168.100.200 
    /p tcp is the protocol (TCP protocol) 
    /r is the actual remote port on the echo server (echo port) 
    /n is the number of the echo requests  
    /t is the connection timeout in seconds 
    /d is the message to be sent for echo (for example, “LwIP TCP echo server 
    Example”)

The TCP protocol and data sent through the network can be verified using the Wireshark software. Packets sent through the network will be available in Wireshark as shown in Figure 14. The data sent through the command prompt is “LwIP TCP echo server Example”. The same data is seen in the Wireshark software.

Figure 14. TCP Echo server output in Wireshark.

Conclusion

Understanding and effectively utilizing the capabilities of the lwIP stack along with the ICMP-based ping tool and the TCP protocol opens up a wide array of possibilities for network diagnostics and data transmission. ADI’s MAX32570 microcontroller and MaximSDK provide a robust foundation for implementing the lwIP stack and building reliable communication systems. By following the outlined examples in this article, network issues can be troubleshooted, creating seamless connections and data integrity assurance.