Device dashboard on a TI EK-TM4C1294XL - FreeRTOS

Overview

This tutorial shows how to implement a Web device dashboard using Mongoose Library over FreeRTOS on a TI EK-TM4C1294XL development board.

Features of this implementation include:

Bare metal - uses no external frameworks / middlewares
Uses ARM CMSIS Core and TM4C CMSIS headers
Uses FreeRTOS-Kernel headers and sources
Uses Mongoose's built-in TCP/IP stack, which includes a TM4C Ethernet driver
Does NOT use an external network stack like lwIP or FreeRTOS TCP
The whole example, including Mongoose Library, runs as a single thread on FreeRTOS
The Web dashboard provides:
- User Authentication: login protection with multiple permission levels
- The web UI is optimised for size and for TLS usage
- Logged users can view/change device settings
- The web UI is fully embedded into the firmware binary, and does not need a filesystem to serve it, making it resilient

This example is a hardware adaptation of the Device Dashboard that can run on Mac/Linux/Windows. Mongoose Library, being cross-platform, allows to develop and run the same code on different platforms. That means: all functionality related to networking can be developed and debugged on a workstation, and then run as-is on an embedded device - and this example is a demonstration of that.

Take your time to navigate and study the Device Dashboard tutorial. Here, we concentrate on the features specific to this embedded platform.

This example is a plain GCC make-based project with the following files:

main.c - provides the main() entry point with hardware init, LED blinking and network init
hal.h - provides a simple API on top of the CMSIS API, like gpio_write(), uart_init(), etc
sysinit.c - provides the SystemInit() function with system clock setup, SysTick setup, etc
syscalls.c - provides low level functions expected by the ARM GCC C library
startup.c - used for startup code and IRQ vector table, following CMSIS guidelines
link.ld - a GNU linker script file, used for building the firmware binary
Makefile - a GNU Makefile for building, flashing and testing the project
FreeRTOSConfig.h: provides FreeRTOS integration
mongoose.c, mongoose.h - Mongoose Library
net.c, net.h - part of the device dashboard example, contains the Web functionality
packed_fs.c - part of device dashboard example, embeds the Web UI used by the dashboard

Below is a general process outline:

The board IP addressing will be provided by a DHCP server. If you want to set a static configuration, set IP address, network mask and gateway in main.c; see below
Build the example (see below) and run it on a development board
The firmware initializes FreeRTOS; see FreeRTOS integration below
The firmware initializes the network
After initialization, the application starts Mongoose's event loop and blinks an LED
Once LED1 starts blinking, the example is ready
Open your web browser and navigate to the board IP address, you should see a nice device dashboard

Build and run

Follow the Build Tools tutorial to setup your development environment.

Start a terminal in the project directory; clone the Mongoose Library repo, and run the make build command:

git clone https://github.com/cesanta/mongoose
cd mongoose/examples/ti/ek-tm4c1294xl-make-freertos-builtin
make build

In order to flash this recently built firmware to your board, plug it in a USB port and run Uniflash. It will find the debug adapter in your board, then we need to tell it which board it is that we have and load firmware.bin; see this tutorial on how to use it.
When the firmware is flashed, the board should signal its state by blinking LED1; while LED4 and LED3 will work as "link" and "activity" for the network. We now need to know the IP address of the board to connect to it. If we used DHCP, as it is the default, we can check our DHCP server logs or see the device logs. Let's do this.

To connect to the board, in this example we'll be using picocom; we configure it for 115200bps. Use the proper serial device.

picocom /dev/ttyACM0 -i -b 115200
picocom v2.2
...
Terminal ready
3      2 main.c:70:server               MAC: 08:00:28:5a:95:bd. Waiting for IP...
...
944    2 mongoose.c:7356:onstatechange  READY, IP: 192.168.69.236
949    2 mongoose.c:7357:onstatechange         GW: 192.168.69.1
94f    2 mongoose.c:7359:onstatechange         Lease: 21600 sec
955    2 main.c:75:server               Initialising application...
95b    3 mongoose.c:3423:mg_listen      1 0x0 http://0.0.0.0
960    2 main.c:79:server               Starting event loop

Now start a browser on http://IP_ADDRESS, where IP_ADDRESS is the board's IP address printed on the serial console. You should see a login screen as in the image above.
From here on, if you want to try the dashboard features please go to the device dashboard tutorial and follow some of the steps depicted there.

Compilation options

MG_ARCH=MG_ARCH_FREERTOS - configures Mongoose to work with FreeRTOS
MG_ENABLE_TCPIP=1 - enables the built-in TCP/IP stack
MG_ENABLE_DRIVER_TM4C=1 - enables the built-in TM4C Ethernet driver
MG_ENABLE_PACKED_FS=1 - enables the embedded filesystem support

We define these in mongoose_config.h

main.c overview

This example can be divided in the following blocks:

FreeRTOS integration for this microcontroller
Initialize the microcontroller for this particular board
Start the FreeRTOS scheduler to run the desired tasks
Initialize the Ethernet controller
Initialize Mongoose
Initialize the networking stack
Run Mongoose

FreeRTOS integration

Mongoose supports a number of well-known architectures, among them FreeRTOS. To tell Mongoose in which architecture it is running, we need to define the macro MG_ARCH; and when this symbol is not defined and there is no other clue, Mongoose will default to try to include mongoose_config.h. In that file, we add the proper definition:

Network operations need a time base to calculate timeouts; this will be provided by FreeRTOS and Mongoose now knows how to link to it. We'll configure it at a 1000 Hz rate, to provide a 1ms time base.

In the Makefile, we clone the FreeRTOS-Kernel repository at a stable branch; then we set the proper paths for include files and required code:

FreeRTOS-Kernel/include/: headers with FreeRTOS-Kernel API definitions
FreeRTOS-Kernel/portable/GCC/ARM_CM4F: headers specific for the GCC compiler and the ARM Cortex-M4F core
FreeRTOS-Kernel/*.c: the generic kernel code
FreeRTOS-Kernel/portable/GCC/ARM_CM4F/port.c: the specific kernel code for the GCC compiler and the ARM Cortex-M4F core
FreeRTOS-Kernel/portable/MemMang/heap_4.c: the memory management strategy we chose
FreeRTOSConfig.h: here we do our main integration job, defining the number of priority bits in the NVIC for this particular MCU; and the required exception handlers, preferences, and stack and heap sizes

MCU and board initialization

Microcontroller support is provided by CMSIS, and the hal.h and sysinit.c files. The microcontroller and its clock are initialized in sysinit.c by a standard function called by the CMSIS startup procedure. In our main() function, we call other functions to initialize those peripherals we are going to use:

Create tasks and start scheduler

We create the necessary tasks and call the function that starts the scheduler. Then, FreeRTOS takes over and we have a server task, where we initialize and run Mongoose, and a blinker task to blink an LED

Note we provide ample stack space for the Mongoose task. It doesn't actually need to be that big for such a simple example, but more complex interfaces will need plenty of room.

Ethernet controller initialization

The Ethernet controller initialization follows. This chip has a built-in PHY, so we just need to configure the GPIO pins for the LEDs, configure the clocks, and reset the MAC controller and the PHY:

Mongoose initialization

Then we initialize Mongoose, this is no different from what we always do in any example; we are a task in FreeRTOS and we can run an infinite loop.

TCP/IP initialization

The built-in TCP/IP stack has to be enabled to be compiled in, and so Mongoose will work in association with it. This is done by defining MG_ENABLE_TCPIP=1. We do this in mongoose_config.h. In that file, we add the proper definition:

We also enable there the driver code we are going to use, by defining MG_ENABLE_DRIVER_TM4C=1

Then this networking stack has to be configured and initialized. This is done by calling mg_tcpip_init() and passing it a pointer to a struct mg_tcpip_if. Inside this structure:

have pointers to a struct mg_tcpip_driver and any extra data that it could need
For DHCP: set ip as zero
For a static configuration, specify ip, mask, and gw in network byte order

In this example we use DHCP, but you can remove the comments and set a static configuration if you want:

Note that, we also need to specify a unique MAC address. For production runs you'll have to consider among several options, from adding a MAC address chip in your hardware design to registering with the IEEE Registration Authority. However, in these evaluation boards, TI provides a MAC address in the microcontroller flash so this example provides a macro to read it.

Some drivers, as you have probably noticed, require extra data. In this case the TM4C driver can accept the setting for the divider that generates the internal MDIO clock. You can pass a null pointer in the driver data or a negative value for this parameter and the driver will calculate it for you, based on the clock configuration.

As you can see, there are no multi-threading issues to worry about, just follow Mongoose documentation as usual and call all mg_* API functions from the same FreeRTOS task where Mongoose is running.

Run Mongoose

Then we run Mongoose. This is no different from what we always do in any example, though note that it should be run after network initialization. The logic is standard: initialize the event manager (as we already did), start a listener, and fall into an infinite event loop:

In this case, the listener is started by web_init(), the device dashboard initialization function. The URL is configured by the macro HTTP_URL, which we set in the Makefile.

Blinker task

There is a simple FreeRTOS task that initializes the GPIO and loops to blink the blue LED

We have covered those aspects that are specific to the TM4C implementation, for the details on the application and the UI, please see the Device Dashboard tutorial.