Published February 9, 2022 © GPL3+

Getting Started with lwIP on the SP701

See how to setup a Vitis software platform to utilize the lightweight IP (lwIP) stack for the Spartan-7 SP701 FPGA development board.

IntermediateFull instructions provided1 hour3,540

Things used in this project

Hardware components

AMD Spartan-7 SP701 FPGA Evaluation Kit

Software apps and online services

AMD Vitis Unified Software Platform

Story

In my last project post, I covered how to create a base hardware design in Vivado 2021.2 for the SP701 Spartan-7 based development FPGA board. This project is the continuation of that covering how to create an lightweight IP (lwIP) echo server in embedded C to run on the SP701 using Xilinx's embedded software IDE, Vitis.

If you're not already familiar, both Vitis and its predecessor Xilinx SDK have a template lwIP echo server project that can be utilized as a starting point and customized into a user's specific application needs. I find it super handy as a baseline to get network communication established for my FPGA designs and saves a lot of time so I'm not reinventing the wheel every time I need to control my FPGA over an Ethernet connection.

As a high-level overview I'll be creating a new application project using the lwIP echo server project template, connecting the SP701 to my local network directly to my router, then creating a simple Python3 script on my host PC using sockets to send some test packets to the server on the SP701 to see if they are successfully echoed back.

Launch Vitis

Vitis can be launched directly from Vivado or standalone from the command line.

To launch from Vivado select Tools > Launch Vitis IDE (this can be done with or without a project open in Vivado):

To launch from command line, first source the environment then run Vitis:

~$ source /tools/Xilinx/Vitis/2021.2/settings64.sh
~$ vitis

Select a directory for the workspace of this instance of Vitis to work from, I personally like to create a folder in the top level of the Vivado project that I created the hardware in the software in the Vitis workspace will be based on. It's just my way of keeping everything organized.

1 / 3

Vitis will launch into a completely blank workspace initially. Unlike it's predecessor Xilinx SDK which would automatically pull in the exported hardware platform from Vivado.

The over all project flow can be broken down into the following steps:

Create a Platform Project using the hardware platform design exported from Vivado for the target.
Create an Application Project containing the actual C code to run on the processing system of the target hardware.
Debug the application using a debugger such as the System Debugger on Hardware.
Program the flash memory of the target device.

I'll be covering the first three steps in this project.

Platform Project

Create new platform project based on the hardware platform (with bitstream) exported from Vivado by selecting Create Platform Project from the blank workspace window.

A pop-up window will guide you through the parameter selections for naming the platform project and point to where the exported hardware platform is for the target board (.xsa file).

Since this is a bare-metal application that is not using an OS such as Linux or RTOS, the Operating system is set to standalone.

The target Processor is the instantiation of the MicroBlaze processor from the Vivado block design, microblaze_0.

1 / 2

Click Finish and Vitis will generate the platform project in the blank workspace.

Before the application project is created in this particular instance, the BSP generated in the platform project needs to be modified to include the lwIP library, as that particular library is not enabled by default in a new platform project

To modify the BSP to add the lwIP library select Modify BSP Settings...

Then in the pop-up window, check the box to enable lwip211 and click OK.

Notice that the platform project shows as out-of-date. This is because the platform project has not been built at this point so no output file exist. Run the initial build of the platform project so that it no longer shows as out-of-date using either the build icon from the menu bar or pressing ctrl+B.

1 / 2

Application Project

With the platform project configured and built, create a new application project based on it. Select New > Application Project...

In the pop-up window, you can skip over the first slide (it is an outline of the steps you'll we walking through to generate the application project). Select the platform project created in the last step to base the application on and click Next.

Name the application project as desired, and Vitis will automatically generate the system project for it as well as associate it with the MicroBlaze soft processor (given its the only target available to run on). Click Next.

Again, since there is no OS, the domain will be standalone. And the final step in creating a new application project in Vitis is selecting a project template to take some of the base leg work out of the initial bringup. Like I mentioned previously, this project is utilizing the lwIP echo server application template. Select it and click Finish.

Note: if you forgot to modify the BSP to enable the lwip211 library, the Finish button would be greyed out and a warning message would appear at the top of the window telling you the library was missing.

1 / 5

Again, Vitis will generate the application project and base code for the design.

The default code is pretty well commented, so feel free to open /src/main.c to read through it and add any custom code desired.

Run a build for the application project.

Application Debugging

Set up the SP701 development board by connection it to your router with an Ethernet cable, connect the USB to UART port J5 to your host PC and plug the wall adapter in to power the SP701 board. Power on the board by setting SW11 to the ON position.

Launch a debug run of the lwIP server application in Vitis by right-clicking on the application name from the Explorer window then selecting Debug As > Launch Hardware (Single Application Debug).

Vitis will then switch from the development view to the debugging view, program the bitstream onto the FPGA, boot the MicroBlaze, then set a breakpoint such that it stops right after entering the main function of the lwIP application.

At this point you have the option to step through/over/out as you normally would in any other debugger, or you can click run/resume/F8 (all of these are located in the menu bar) to let the application run normally with the option for pause and step through at any time.

You will also want to connect to the UART serial output from the SP701. You can do this with any serial terminal application of your choice, or use the built in one in Vitis. The debugging view has set of tabs along the bottom including Console, Vitis Serial Terminal, Executables, Debug Shell, Vitis Log, Problems, and Debugger Console.

Switch to the Vitis Serial Terminal tab and click the + button. There will be three enumerated serial ports, select the first of the three (for example, if there is ttyUSB0, ttyUSB1, and ttyUSB2 select ttyUSB0). And connect to it with a baud rate of 9600 and default UART settings.

Now clicking run will start the echo server listening to the port it established on port number 7 as evidenced by the serial output over the UART interface. This will tell you the local IP of the SP701 board and status of the link.

Host PC Echo Client

To test the lwIP echo server on the SP701, I threw together a simple echo client script in Python3 that I ran from my PC on the same local network as the SP701.

This script opens a socket as a client at the local IP of the SP701 (192.168.1.10 by default) on port 7, then sends a packet of bytes to the echo server.

After sending the packet, the echo server waits until it receives the same number of bytes back as it sent out and prints out the received packets. Once the expected number of bytes is received, the echo client closes the socket. It's important to close the socket because if you don't and try to run the script again, it will hang since the socket resource was never released.

As a further test of the connection, you can also ping the SP701 from the command line of you PC:

I figured this would be a good stopping point for getting the lwIP up and running initially (I'm trying to keep my project posts at easily consumable lengths). I'll be expanding on this in future projects with the addition of custom functions in the echo server, so keep this bookmarked.

Code

echo_client.py

import socket
import sys

print('Create a socket on the host PC client.')
lwIP_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

print('Connect to the socket of the lwIP server listening on the SP701.')
lwIP_server_address = ('192.168.1.10', 7)
lwIP_socket.connect(lwIP_server_address)

try:
	message = 'Hello lwIP on the SP701!'
	message_byte = message.encode()
	
	lwIP_socket.sendall(message_byte)
	
	bytes_buffer_size = 32	
	bytes_received = 0
	bytes_total = len(message)
	
	while bytes_received < bytes_total:
		message_recvd = lwIP_socket.recv(bytes_buffer_size)
		bytes_received += len(message_recvd)
		print(message_recvd)
		
finally: 
	print('Closing the socket from the host PC client side...')
	lwIP_socket.close()

Credits

Whitney Knitter

169 projects • 1726 followers

All thoughts/opinions are my own and do not reflect those of any company/entity I currently/previously associate with.

Getting Started with lwIP on the SP701

Things used in this project

Hardware components

Software apps and online services

Story

Launch Vitis

Platform Project

Application Project

Application Debugging

Host PC Echo Client

Schematics

UG1319 SP701 Evaluation Board User Guide

Code

echo_client.py

Credits

Whitney Knitter

Comments

Embed the widget on your own site

Getting Started with lwIP on the SP701

Getting Started with lwIP on the SP701

Things used in this project

Hardware components

Software apps and online services

Story

Launch Vitis

Platform Project

Application Project

Application Debugging

Host PC Echo Client

Schematics

UG1319 SP701 Evaluation Board User Guide

Code

echo_client.py

Credits

Whitney Knitter

Comments

Related channels and tags