TI EK-TM4C1294XL MIP FreeRTOS

Overview

This tutorial shows how to use Mongoose Library over FreeRTOS, using MIP (a bare-metal embedded TCP/IP stack designed specifically for Mongoose), and running on a TI EK-TM4C1294XL development board.

We implement a very basic web server that responds "hi" to any URL and provides a minimal example of a REST API to change the debug level. The full source code for this project is at https://github.com/cesanta/mongoose/tree/master/examples/ti/ek-tm4c1294xl-freertos-mip

This example is a plain gcc make-based project. The relevant files are:

FreeRTOS-Kernel/: provides the RTOS functionality and memory management functions; see FreeRTOS integration below
mcu.h: provides all necessary MCU support, as this project is not CMSIS-based
boot.c: provides the MCU low-level initialization, vector table and default exception handlers
syscalls.c: provides an abstraction layer for those system functions Mongoose expects
main.c: here we do our main job, initializing the MCU, the FreeRTOS scheduler, Mongoose, the network, and calling the event manager
Makefile: a standard make file that performs the compilation and linking process

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 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 greeting

Build and run

It is assumed you're using Linux or Mac as a workstation, you have Docker installed, and your user is able to run it. If in doubt, check
```
$ docker ps
```
We will also use the Uniflash flash utility

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-freertos-mip
$ 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 and to add a carriage return. Use the proper serial device.

$ picocom /dev/ttyACM0 -i -b 115200 --imap=lfcrlf
picocom v2.2
...
Terminal ready
0 2 main.c:48:server                    Initializing Ethernet driver
6 2 main.c:59:server                    Starting Mongoose v7.8
c 3 mongoose.c:3496:mg_listen           1 0x0 http://0.0.0.0
2ef 2 main.c:72:blinker                 blink :),  RAM: 101800
...
11e0 2 mongoose.c:6815:onstatechange    READY, IP: 192.168.69.232

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

How it works

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

This example, and the MIP stack itself, don't use CMSIS. Microcontroller support is provided by the mcu.h and boot.c files. In our main function, we call these functions to initialize the MCU and 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 with MIP, 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.

MIP initialization

MIP has to be enabled to be compiled in, and so Mongoose will work in association with it. We do this in mongoose_custom.h. In that file, we add MG_ENABLE_MIP=1:

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 mip_init() and passing it a pointer to a struct mip_if. Inside this structure:

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

In this example, we use DHCP:

Note that, we also need to specify a unique MAC address. For this example we chose a fancy unicast locally administered 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.

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.

MIP will run as part of Mongoose, it is a part of it. The Ethernet controller will interrupt when it has received a frame and the IRQ handler will push it to a queue, from where MIP will pick it up later; 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 on port 80, and fall into an infinite event loop:

The listener will call this function when it receives an HTTP request:

There we check the requested URL and either parse a JSON message or just reply "hi"

Blinker task

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

Custom application

In order to create your own Mongoose-enabled application you have several ways:

The obvious way, is to add the required functionality to this example. The example includes an important set of drivers. As we've seen in previous sections, there are functions to read and write to GPIOs, but check similar baremetal examples in our site.
If, for some reason, you can't use this example as a base (e.g.: you have your own big project to which you need to add Mongoose, or you'd rather use CMSIS and/or your preferred IDE), you can do the following:
- Add relevant project files to your project
- Add mongoose.c and .h files to your project
- Add Mongoose-specific configuration flags, see the Makefile
- Add the required preprocessor symbols:
  - MG_ARCH=MG_ARCH_FREERTOS, MG_ENABLE_MIP=1, MG_ENABLE_DRIVER_TM4C=1
- Since the PHY uses the external clock, make sure you design in a 25 MHz clock; then follow the example server() task and the Ethernet controller initialization
- Now write code similar to that in main.c; for that you can read Mongoose documentation and follow our examples and tutorials