FreeRTOS-Plus-TCP and FreeRTOS-Plus-FAT Examples
Using the FreeRTOS Windows Port
[Buildable TCP/IP and FAT FS Examples]
Introduction
Two projects are provided that allow both FreeRTOS-Plus-TCP and FreeRTOS-Plus-FAT
to be built and executed using free tools and in a Windows environment, so without
the need to purchase any special hardware:
-
FreeRTOS-Plus-TCP Starter Project
The FreeRTOS-Plus-TCP starter project only
includes two of the examples listed at
the bottom of this page. It does not include FreeRTOS-Plus-FAT,
FreeRTOS-Plus-CLI, or any tracing capability.
-
Comprehensive Project
The comprehensive project includes all the examples
listed at the bottom of this page.
FreeRTOS-Plus-FAT
provides the file storage for the FTP and HTTP
examples, and FreeRTOS-Plus-CLI
provides the command line interface.
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:
The Win32 example uses WinPCap to read and write raw Ethernet packets in
order to create a virtual node on the Ethernet 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 same network - whereas
in reality both nodes are running on the same host 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 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 Project
It is necessary to open the project before completing the software setup.
-
FreeRTOS-Plus-TCP Only Starter Project
The Visual Studio workspace for the FreeRTOS-Plus-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.
-
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 of the FreeRTOS labs download.
Software Setup #1: Setting a Static or Dynamic IP Address
Network address settings in FreeRTOSConfig.h
The
FreeRTOSIPConfig.h
and
FreeRTOSConfig.h header files are the
FreeRTOS-Plus-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.
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.
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:
-
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.
-
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-Plus-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.
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 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 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-Plus-TCP starter project.
Available examples
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.