The FreeRTOS Ecosystem Showcase . . .
A Selection of Add-on and Complementary Products

 Real time embedded FreeRTOS RSS feed 
Homepage FreeRTOS+ Products FreeRTOS Labs Support Forum Contact / Enquiries

 FreeRTOS+POSIX:
 POSIX API for FreeRTOS
 FreeRTOS+FAT:
 Thread aware file system

FreeRTOS+TCP and FreeRTOS+FAT Examples
Using the FreeRTOS Windows Port

[Buildable TCP/IP and FAT FS Examples]

Introduction

Two 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:
  1. Comprehensive Project

    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.

  2. 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.

Both projects are preconfigured to build with the free version of Visual Studio C/C++, and use the FreeRTOS Win32 port.


Instructions

Prerequisites

The following are required to build and run the Win32 RTOS port examples:
  • A windows host computer with a connected network port (see the hardware setup section below). The projects have been tested with Windows XP and Windows 7.

  • An installed version of Visual Studio C/C++. The free Express edition is adequate. The project was created with Visual Studio 2010.

  • The FreeRTOS Labs source code download.


Hardware Setup

The Win32 example uses WinPCap to read and write raw Ethernet packets in order to create a virtual node on the network. The virtual node has its own MAC address and IP address. In the examples the host computer uses its real MAC and IP addresses to communicate with the virtual MAC and IP address as if they were two separate computers on the network - whereas in reality both nodes are running on the same PC.

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 port is disconnected and no communication can take place.

TCP/IP in the RTOS simulator
The real and virtual nodes are connected to the same network so can talk to each other


Opening a Project

It is necessary to open the project before completing the software setup.

  1. Comprehensive Project

    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.

  2. 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.


Software Setup #1: Setting a Static or Dynamic IP Address

Allocating an IP address to the RTOS node
Network address settings in FreeRTOSConfig.h
The FreeRTOSIPConfig.h and FreeRTOSConfig.h header files are the FreeRTOS+TCP and FreeRTOS configuration files respectively. Both can be opened from within Visual Studio.

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 Address

If 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.


Software Setup #3: Setting the Hostname

It is often more convenient to identify a node on the network using a name, rather than an IP address. This is especially the case when the IP address is not known. For example, rather than sending a ping request to an IP address, such as "ping 192.168.0.200", a ping request can instead be sent to a hostname, such as "ping MyHostName" (where MyHostName is the name assigned to the network node).

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.


Software Setup #4: Print and Logging Messages

Directing RTOS debug output
Logging configuration in FreeRTOSIPConfig.h
FreeRTOSIPConfig.h is provided with FreeRTOS_debug_printf() disabled, and FreeRTOS_printf() set to call a Windows simulator specific utility file called vLoggingPrintf().

Log output can be sent to:

  1. 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.

  2. 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.

  3. Standard out:

    If mainLOG_TO_STDOUT is set to pdTRUE in main.c then log output will be sent to stdout.

Note: Output related Windows system calls should not be made from RTOS tasks. Therefore standard out and disk file log data is passed to a standard Windows thread for output. UDP logging is sent directly from the RTOS task as it uses FreeRTOS+TCP, not the Windows TCP/IP stack.


Software Setup #5: Selecting the Network Interface

Most 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.

Trouble shooting:

  • 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 network traffic.

RTOS network interfaces
The available network interfaces displayed when the example starts running


Running Examples

Now the hardware and software are configured the examples can be executed.


Basic Connectivity Test

Before 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 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 TCP target
Pinging the target, and receiving ping responses


Selecting the Examples to Run

The 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.

Available examples


[ Back to the top ]    [ About FreeRTOS ]    [ Privacy ]    [ FreeRTOS Labs Sitemap ]    [ Main FreeRTOS Sitemap ]    [ ]




Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.