FreeRTOS+TCP and FreeRTOS+FAT Examples
Using the FreeRTOS Windows Port
IntroductionTwo projects are provided that allow both FreeRTOS+TCP and FreeRTOS+FAT to be built and executed using free tools and in a Windows environment, so without the need to purchase any special hardware:
FreeRTOS+TCP Starter Project
The FreeRTOS+TCP starter project only includes two of the examples listed at the bottom of this page. It does not include FreeRTOS+FAT, FreeRTOS+CLI, or any tracing capability.
The comprehensive project includes all the examples listed at the bottom of this page. FreeRTOS+FAT provides the file storage for the FTP and HTTP examples, and FreeRTOS+CLI provides the command line interface.
PrerequisitesThe following are required to build and run the Win32 RTOS port examples:
A windows host computer with a connected Ethernet network port (see the
section below). The projects have
been tested with Windows XP, Windows 7 and Windows 10.
If you do not have a wired Ethernet port then:
- It may be possible to install a virtual network card, and then bridge the virtual network card to a Wi-Fi interface – if that works for you then please describe your configuration in a support forum post!
- We have successfully used an Ethernet to Wi-Fi bridge, although I’m afraid we cannot provide technical support the use of such a device.
An installed version of Visual Studio C/C++. The
free community edition
is adequate. See the note at the top of the page that
page that described the FreeRTOS Windows port regarding Visual Studio for C/C++ versions.
An installed version of WinPCap (NPCap may also work). If
you have Wireshark installed then this step might not be necessary.
The main FreeRTOS download if you want to run the starter project, or the
FreeRTOS Labs source code download
if you want to run the comprehensive project. Note the source code in the Labs download is much older
and not recommended for production use.
- Finally, Although not strictly a prerequisite, it is also highly recommended to install a tool such as Wireshark so you can view network traffic.
For this setup to work the host PC must be physically connected to a network, even though no other nodes on the network are used, otherwise, as far as Windows is concerned, the Ethernet port is disconnected and no communication can take place. The network need not be a real network though – simply connecting the host Windows machine to an MCU development board that has an Ethernet port is enough provided Windows see the Ethernet as connected.
The real and virtual nodes are connected to the same network so can talk to each other
Opening a ProjectIt is necessary to open the project before completing the software setup.
FreeRTOS+TCP Only Starter Project
The Visual Studio workspace for the FreeRTOS+TCP starter example is called FreeRTOS_Plus_TCP_Minimal.sln, and is located in the FreeRTOS-Plus/Demo/FreeRTOS_Plus_TCP_Minimal_Windows_Simulator directory of the main FreeRTOS download.
The Visual Studio workspace for the comprehensive example is called FreeRTOS_Plus_TCP_and_FAT.sln, and is located in the FreeRTOS-Plus/Demo/FreeRTOS_Plus_TCP_and_FAT_Windows_Simulator directory of the FreeRTOS labs download.
Software Setup #1: Setting a Static or Dynamic IP Address
Network address settings in FreeRTOSConfig.h
If a DHCP server is present on the network to which the host computer is connected then set ipconfigUSE_DHCP to 1 in FreeRTOSIPConfig.h, and no further IP address configuration is necessary. It is not necessary to know the IP address allocated to the demo by the DHCP server if a hostname is configured, because the demo can be located by its name directly. The IP address can however be viewed, as it is output using the logging facility.
If there is no DHCP server connected to the network then set ipconfigUSE_DHCP to 0 in FreeRTOSIPConfig.h, then configure the IP address and netmask manually. The IP address and netmask are set using the configIP_ADDR0/3 and configNET_MASK0/3 constants respectively in FreeRTOSConfig.h. Note the IP address setting is in FreeRTOSConfig.h rather than FreeRTOSIPConfig.h because it is related to the application, rather than being a TCP/IP stack configuration option.
When manually setting the IP address it is necessary to ensure the chosen IP address is compatible with the netmask. In most cases a compatible IP address will be one that uses the same first three octets as the host computer. For example, if the IP address of the host computer is 192.168.0.100 then any 192.168.0.nnn address (other than when nnn is 0 or 255, and any other address already present on the network) will be compatible.
It is also necessary to set a gateway address that is also compatible with the netmask. This step is necessary even if the gateway does not actually exist on the network (otherwise an internal sanity check will trigger a configASSERT() failure). The gateway address is set using the configGATEWAY_ADDR0/3 constants in FreeRTOSConfig.h.
Software Setup #2: Selecting the (virtual) MAC AddressIf only one computer that is running the example is connected to the network then it will not be necessary to modify the [virtual] MAC address.
If multiple computers that are running the example are connected to the same network then it will be necessary to ensure each computer has a unique [virtual] MAC address.
The MAC address is set using the configMAC_ADDR0/5 constants in FreeRTOSConfig.h.
If only one computer that is running the example is connected to the network then it will not be necessary to modify the default hostname, which is “RTOSDemo”. If multiple computers that are running the example are connected to the same network then it will be necessary to assign a different hostname to each computer.
The hostname is set by the mainHOST_NAME constant at the top of the main.c source file. Depending on the network topology, it may also be possible to use a second hostname set by the mainDEVICE_NICK_NAME constant, which is also defined at the top of main.c.
Logging configuration in FreeRTOSIPConfig.h
Log output can be sent to:
A UDP port:
If mainLOG_TO_UDP is set to pdTRUE in main.c then log output will be sent using UDP. The UDP data will be sent to the IP address set by the configECHO_SERVER_ADDR0 to configECHO_SERVER_ADDR3 constants defined in FreeRTOSConfig.h (which is the address of the echo server when the echo server demo example is used) and the port number set by the configPRINT_PORT constant, also in FreeRTOSConfig.h.
A disk file:
If mainLOG_TO_DISK_FILE is set to pdTRUE in main.c then log output will be written to a file called RTOSDemo.log. When the file reaches 40M bytes in size it is renamed RTOSDemo.ful, and a new log file is started.
If mainLOG_TO_STDOUT is set to pdTRUE in main.c then log output will be sent to stdout.
Software Setup #5: Selecting the Network InterfaceMost computers have multiple network interfaces, and it is necessary to tell the application which interface to use.
Compile (press F7 in Visual Studio) then run (press F5 in Visual Studio) the application. A console screen will display the available network interfaces. Set the configNETWORK_INTERFACE_TO_USE constant in FreeRTOSConfig.h to the number that appears next to the interface being used. It will then be necessary to re-compile the program.
If the network interfaces are not displayed then it is
likely Windows is not running the NPF service. To correct this
type “sc start npf” into a command console (administrator privilages are
required), then re-start the application.
If you cannot establish communication, or if you cannot see
any network traffic in Wireshark, then try using a wired network
rather than a wireless network. If that is not possible try
connecting to (or pinging) the project from a different computer
on the same network.
Ensure your firewall or Windows settings are not blocking the
The available network interfaces displayed when the example starts running
Running ExamplesNow the hardware and software are configured the examples can be executed.
Basic Connectivity TestBefore experimenting with the examples below it is advised to test basic connectivity by starting the application running, then pinging the target. If ping replies are received then the application is both running and connected to the network correctly.
To ping the device, open a command prompt and type “ping aaa.bbb.ccc.ddd”, where aaa.bbb.ccc.ddd is the IP address displayed on the console when the network connected. Alternatively, if enabled in the configuration file, type “ping RTOSDemo”, assuming the hostname has not be changed from the default of “RTOSDemo”.
If a ping reply is not received then turn DHCP off, assign the target a static IP address, and try again using the assigned IP address in place of the host name.
Instructions describing how to set a static IP address, and how to set a hostname, are provided in the setup instructions on this page.
Pinging the target, and receiving ping responses
Selecting the Examples to RunThe comprehensive projects contain multiple examples that can be selectively included in the build using the #define constants at the top of main.c. A description of each example, along with instructions for including the example in the build, are provided on the links below.
All the examples are available for use in the comprehensive project. Only the “Basic UDP clients communicating with basic UDP servers” and the “TCP echo clients (Rx and Tx performed in the same RTOS task)” examples are available for use in the simpler FreeRTOS+TCP starter project.
FreeRTOS+TCP UDP sockets examples
- Command line interface using a UDP socket for input and output
- Basic UDP clients communicating with basic UDP servers (standard and zero copy)
- Using FreeRTOS_select()
- UDP echo clients
FreeRTOS+TCP TCP sockets examples
- Command line interface using a TCP socket for input and output
- TCP echo clients (Rx and Tx performed in the same RTOS task)
- TCP echo clients (Rx and Tx performed in separate RTOS tasks)
- TCP echo server
- FreeRTOS+TCP and FreeRTOS+FAT web (HTTP) and FTP examples