Download FreeRTOS
 

Quality RTOS & Embedded Software

KERNEL
WHAT'S NEW
Simplifying Authenticated Cloud Connectivity for Any Device.
Designing an energy efficient and cloud-connected IoT solution with CoAP.
Introducing FreeRTOS Kernel version 11.0.0:
FreeRTOS Roadmap and Code Contribution process.
OPC-UA over TSN with FreeRTOS.

uIP Embedded Web Server Demo
using the FreeRTOS SAM7X ARM port
[Embedded Ethernet Examples]



Studio Cadrage
This page describes one of the FreeRTOS SAM7X embedded Ethernet TCP/IP sample applications. The demo uses the FreeRTOS IAR SAM7 ARM port and Adam Dunkels open source uIP stack to create an embedded web server on an AT91SAM7X-EK development board (instructions are provided should you wish to use an alternative development board). An alternative project is also available to demonstrate the use of the more feature rich lwIP TCP/IP stack using the GCC compiler.

FreeRTOS has made some modifications to the uIP stack since this demo was created. See the Embedded Ethernet Examples List page for more information.

This demo -

  • Consists entirely of open source software.
  • Includes a basic driver for the SAM7X integrated EMAC (Ethernet Media Access Controller) peripheral.
  • Demonstrates the integration of uIP with FreeRTOS.
  • Demonstrates the creation of dynamic data with a simple CGI scripting language (written by Adam Dunkels).
  • Creates 31 of the standard demo tasks in addition to the web server task and the idle task.
The uIP TCP/IP stack is licensed separately from FreeRTOS. Users must familiarise themselves with the uIP license.

Note: If this project fails to build then it is likely the version of IAR Embedded Workbench being used is too old. If this is the case, then it is also likely that the project file has been (silently) corrupted and will need to be restored to its original state before it can be built even with an updated IAR version.


IMPORTANT! Notes on using the SAM7X Web Server Demo

Please read all the following points before using this RTOS port.

  1. Source Code Organisation
  2. The Demo Application
  3. Configuration and Usage Details
See also the FAQ My application does not run, what could be wrong?

Source Code Organisation

The FreeRTOS download contains the source code for all the FreeRTOS ports, so contains more files than used by this demo. See the Source Code Organization section for a description of the downloaded files and information on creating a new project.

This SAM7X Web Server demo uses the standard FreeRTOS IAR SAM7 port. The uIP IAR demo project workspace rtosdemo.eww can be found in the Demo/uIP_Demo_IAR_ARM7 directory and should be opened from within the Embedded Workbench IDE.

The Demo/uIP_Demo_IAR_ARM7/SrcIAR and the Demo/uIP_Demo_IAR_ARM7/resource directories contain support files for the Atmel libraries and build environment.

Adam Dunkels uIP code is located in the Demo/uIP_Demo_IAR_ARM7/uIP directory. The HTML files used with the demo can be found in the Demo/uIP_Demo_IAR_ARM7/uIP/fs directory.

Finally the Demo/uIP_Demo_IAR_ARM7/EMAC directory contains the EMAC driver.


The Demo Application

Demo application setup

Connect the AT91SAM7X-EK prototyping board to a computer running a web browser either directly using a point to point (crossover) cable, or via a hub/router using a standard Ethernet cable. The prototyping board should also allow the use of a standard Ethernet cable when connecting point to point, but I have not tested this configuration.

The IP address used by the demo is set by the constants UIP_IPADDR0 to UIP_IPADDR3 within the file Demo/uIP_Demo_IAR_ARM7/uIP/uipopts.h. The IP addresses used by the web browser computer and the prototyping board must be compatible. This can be ensured by making the first three octets of both IP addresses identical. For example, if the web browser computer uses IP address 192.168.100.1, then the prototyping board can be given any address in the range 192.168.100.2 to 192.168.100.254 (barring any addresses already present on the network).

The MAC address used by the demo is set by the constants UIP_ETHADDR0 to UIP_ETHADDR5, also within uipopts.h. You must ensure that the configured MAC address is unique on the network to which the prototyping board is being connected.

Demo/uIP_Demo_IAR_ARM7/EMAC/SAM7_EMAC.c contains the definition USE_RMII_INTERFACE. This must be set appropriately for your hardware. Setting USE_RMII_INTERFACE to 1 configures the MAC to operate in RMII mode. Setting USE_RMII_INTERFACE to 0 configures the MAC to operate in MII mode.

The demo application uses the LEDs built into the prototyping board so no other hardware setup is required.


Building the demo application for debug

Two project configurations are provided. "Flash Debug" uses minimal optimisation and can easily be used with the J-Link JTAG debug interface. "Flash Release" has full optimisation (minus static clustering).

Simply open the rtosdemo.eww workspace file from within the IAR Embedded Workbench IDE, ensure flash debug is the selected configuration (see picture below), then select 'Built Target' from the IDE 'Project' menu.

ewprojselect.jpg
Selecting the flash debug configuration


Running the demo application

The IAR port cannot be executed using the IAR simulator so must be executed on the target hardware.

  1. Ensure the J-Link JTAG debug interface is connected and that the prototype board is power up.
  2. Ensure an Ethernet cable is connected as described above.
  3. Select 'Debug' from the IDE 'Project' menu.
  4. The embedded microcontroller Flash memory will automatically get programmed with the demo application, and the debugger will break at the reset vector (address 0). Select 'Go' from the IDE 'Debug' menu to start the application executing.


Functionality

The demo application creates 33 tasks - consisting predominantly of the standard demo application tasks (see the demo application section for details of the individual tasks). In addition there is a uIP task that implements the embedded web server, a 'Check' task and the idle task.

When executing correctly the demo application will behave as follows:

  • The target hardware will serve web pages to a standard web browser. To connect to the target:

    1. Open a web browser on the connected computer.
    2. Type "HTTP://" followed by the target IP address into the browsers address bar.


      Entering the IP address into the web browser
      (obviously use the correct IP address for your system)

  • LEDs DS1, DS2 and DS3 are under control of the 'flash' tasks. Each will flash at a constant frequency, with LED DS1 being the fastest and LED DS3 being the slowest.

  • Not all the tasks update an LED so have no visible indication that they are operating correctly. Therefore a 'Check' task is created whose job it is to ensure that no errors have been detected in any of the other tasks.

    LED DS4 is under control of the 'Check' task. Every three seconds the 'Check' task examines all the tasks in the system to ensure they are executing without error. It then toggles LED DS4. If LED DS4 is toggling every three seconds then no errors have ever been detected. The toggle rate increasing to 500ms indicates that the 'Check' task has discovered at least one error.


Configuration and Usage Details

HTML Pages

The HTML pages are converted to constant C structures that are built into the flash image. The Perl script Demo/uIP_Demo_IAR_ARM7/uIP/makdefsdata can be used for this purpose. The perl script requires Linux or, as I use, a Cygwin shell.


CGI Scripts

Each of the served web pages includes some dynamic data to demonstrate the use of the uIP CGI scripting facility. See the uIP documentation for further information.

The RTOS CGI file generates a table containing information on each task executing within the demo. This table is interesting for demonstration purposes, but as it is necessary to leave interrupts disabled for an extended period during its creation it is not recommended for use in applications with strict real time requirements.


Web Server and EMAC Operation

The web server functionality is contained within the file Demo/uIP_Demo_IAR_ARM7/uIP_Task.c.

The EMAC DMA operation makes the interaction between the EMAC peripheral and the web server task very simple. The interaction is further simplified by the single buffer memory management of uIP. The lwIP stack implements a more flexible (complex) memory management scheme, therefore the lwIP demo application contains a more comprehensive EMAC driver.

Data received by the EMAC is buffered under control of the DMA. When a buffer is available for processing an EMAC interrupt is generated. All the interrupt service routine does is signal to the uIP task via a semaphore that data is available for processing. The semaphore immediately unblocks the uIP task, which processes the data and if necessary generates a response.

The uIP task blocks on the semaphore with a timeout. Therefore should no data become available for processing, the uIP task will periodically unblock to carry out the periodic processing required by the TCP/IP stack.

The number of receive buffers available to the EMAC is set by the constant NB_RX_BUFFERS within the file Demo/uIP_Demo_IAR_ARM7/SrcIAR/emac.h. Each receive buffer is 128 bytes.

The number of transmit buffers available to the EMAC is set by the constant NB_TX_BUFFERS also within emac.h. The size of each transmit buffer is equal to the uIP buffer size.

The driver included in the download uses the EMAC in its most basic configuration.


EMAC Driver Re-entrancy

The uIP task is the only task that accesses the uIP buffers, and therefore explicit re-entrancy is not required for this demo. This is in contrast to the lwIP demo, where mutual exclusion is explicitly handled by use of a semaphore at the network interface level.


Performance

The uIP stack only permits one packet to be unacknowledged at any one time. It waits for each packet to be acknowledged individually. Performance is therefore greatly improved by transmitting dynamically generated data as one large packet, rather than multiple small packets. This is demonstrated by the sample CGI scripts included in the source code download. The CGI script used to generate the table of tasks transmits the entire table in one packet and therefore loads quickly. The CGI scripts used to generate the table of files and the table of TCP/IP statistics both transmit each line within the respective tables individually, and therefore the pages take longer to load.


Modifications to the uIP Code

The only modification to the standard uIP source code has been made in the function next_scriptstate() within httpd.c. The type of the variable i has been changed from u8_t to long to allow the maximum line length of CGI scripts to extend past 255 bytes.


RTOS Configuration

The SAM7X demo uses the standard SAM7 RTOS port. Please refer to the SAM7S demo documentation for more detailed information.

NOTE! : The processor MUST be in supervisor mode when the RTOS scheduler is started (vTaskStartScheduler is called). The demo applications included in the FreeRTOS download switch to supervisor mode prior to main being called. If you are not using one of these demo application projects then ensure Supervisor mode is entered before calling vTaskStartScheduler().


MAC Interface

Ensure USE_RMII_INTERFACE is configured appropriately for your hardware. See the Demo Application Hardware Setup notes above.




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