Device dashboard on NUCLEO-F746ZG - FreeRTOS-Plus-TCP, using Keil MDK

Overview

This tutorial shows how to implement a Web device dashboard using Mongoose Library over FreeRTOS-Plus-TCP on an STM32 Nucleo-F746ZG development board, using the ARM Keil MDK development environment.

Features of this implementation include:

Uses FreeRTOS, FreeRTOS-Plus-TCP, ARM CMSIS Core, ARM CMSIS Driver, and device headers through Software Packs
The Web dashboard provides:
- User Authentication: login protection with multiple permission levels
- The web UI is optimized 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 in the Keil MDK environment.

This example is a plain Keil MDK-based project with the following files of interest:

main.c - provides the main() entry point with hardware init, LED blinking and network init.
hal.h - provides an abstraction for MAC generation
syscalls.c - provides a low level function to redirect debug output to a UART.
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 the device dashboard example, embeds the Web UI used by the dashboard
FreeRTOSIPConfig.h - network stack configuration
phyHandling.h - copied from here
phyHandling.c - copied from here

All these files have been grouped in Source Group 1 in the Project Explorer. Keil MDK can integrate with STM32CubeMX, and we use it. The device configuration file, used as the recipe to generate the code for device initialization, is handled by the IDE, we access it through the Run-Time Environment manager. For all auto-generated files, we've used those places designated for USER_CODE, so all files can be re-generated by STM32CubeMX for newer versions of the firmware packs.

References in this tutorial are for a Nucleo-F746ZG board

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, 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; see FreeRTOS-Plus-TCP integration below
After initialization, the application starts Mongoose's event loop and blinks a blue LED
Once the blue LED 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.
In your project directory, clone the Mongoose Library repository using git
Start μVision and open the project; if you need a quick start on the ARM Keil MDK and μVision, follow this step by step tutorial. This project is at examples/stm32/nucleo-f746zg-keil-freertos-tcp.
To be able to build this project, you need to have the proper Software Packs to support it. If you don't have already installed the ARM::CMSIS-FreeRTOS and AWS::FreeRTOS-Plus-TCP packs, you'll see a requester asking you permission to do so. The Pack Installer will open and install the packs.
In order to build this project, click the Build icon. To flash this firmware to your board, plug it in a USB port and click on the Load icon. When finished, you have to reset your board pressing its reset button. You should soon see the blue LED start blinking. As long as there is only one board plugged in, μVision will find it; though we need to know the serial port device to be able to get the log information. You'll need to dig for it in your computer.
When the firmware starts, the board should signal its state by blinking the blue LED. 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 PuTTY; we configure it for 115200bps.

0      2 main.c:76:main                 MAC: 02:35:42:56:22:2e. Waiting for IP...
b57    2 main.c:53:vApplicationIPNetwor FreeRTOS-Plus-TCP net event: 0
b5d    2 main.c:56:vApplicationIPNetwor READY, IP: 192.168.69.234
b64    2 main.c:33:server               Initialising application...
b6a    3 mongoose.c:3609:mg_listen      1 0x20028908 http://0.0.0.0
b70    2 main.c:37: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_FREERTOS_TCP = 1 - enables FreeRTOS-Plus-TCP network stack
MG_ENABLE_CUSTOM_RANDOM =1 - lets the firmware code override mg_random() to use the device hardware RNG
MG_ENABLE_PACKED_FS = 1 - enables the embedded filesystem support

These are grouped in the file mongoose_config.h. This file has been written using scripting extensions, so you can just select the Configuration Wizard tab at the bottom of the editor to see the file contents in a friendly way. Keil MDK configure Mongoose

main.c overview

This example can be divided in the following blocks:

FreeRTOS integration
FreeRTOS-Plus-TCP integration
Initialize the microcontroller for this particular board and take advantage of the true RNG in the microcontroller
Start the FreeRTOS scheduler to run the desired tasks
Initialize the networking stack
Initialize Mongoose
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 as we've seen above; we do this in mongoose_config.h.

Follow our basic FreeRTOS integration guidelines, as these still apply.
Though not listed as a dependency, event groups are required by FreeRTOS-Plus-TCP, so we enable RTOS -> Event Groups too

FreeRTOS-Plus-TCP integration

Mongoose supports a number of well-known TCP/IP stacks, among them FreeRTOS-Plus-TCP. To tell Mongoose which stack to use, we need to define a macro as we've seen above; we do this in mongoose_config.h.

Use only 3.x versions or newer (pack 5.0 contains 3.1) as prior versions do not implement FREERTOS_SOCK_DEPENDENT_PROTO and some functions don't handle arguments in a strictly POSIX-compliant way

Add the proper libraries to the Run-Time Environment configuration; in the Run-Time Environment management window:
- select FreeRTOS -> FreeRTOS+ TCP -> Buffer Allocation and its Variant as Buffer Allocation 2
- select FreeRTOS -> FreeRTOS+ TCP -> Compiler Port and its Variant as Keil
- select FreeRTOS -> FreeRTOS+ TCP -> Core Library
- select FreeRTOS -> FreeRTOS+ TCP -> Network Interface and its Variant as STM32Fxx (valid for Nucleo STM32F7 and F4 boards, set the correct driver for your board)
Then, we need a config file, FreeRTOSIPConfig.h, as current packs do not include one. We added one to the project folder, added it to "Source Group 1", and then added this directory to the include paths so FreeRTOS-Plus-TCP could see it. You can also copy and edit FreeRTOSIPConfigDefaults.h present in the package source. Feel free to modify this file to meet your application needs; follow the comments in that file and then complement with the guidelines here or browse for the one relevant to your hardware
In the current package, two files seem to be missing or require specific user coding: phyHandling.c and phyHandling.h. For this example we copied those from the Github repo
In the project configuration (Project -> Options for Target 'Target 1'), in the C/C++ (AC6) tab:
- add to Preprocessor Symbols -> Define: STM32F7xx=1 - This is needed by the driver code
- add to Include Paths: . - this is needed for the code to find the config and missing files we added
- add to Misc Controls: -Wno-pragma-pack, -Wno-sign-compare and -Wno-uninitialized - to silence many warnings
- remove from Misc Controls: -Wundef and -Wshadow - the code uses many undefined macros and otherwise the ETH HAL won't compile

We didn't change any other default parameters, this is just an approach; for serious work and performance, a tuning operation might be needed.

FreeRTOS-Plus-TCP has a built-in driver based on the STM32 HAL. We need to avoid this driver and its dependencies clashing with the HAL own, but at the same time provide a driver; see the board initialization section below.
- In the Project explorer, right-click on FreeRTOS, make sure Show include File Dependencies is checked in the pop-up menu
- Expand the dependency tree under FreeRTOS/stm32fxx_hal_eth.c (this may require that you try to build and fail so the dependencies list is actually built), and open stm32fxx_hal_conf.h; then we need to
  - uncomment #define HAL_ETH_MODULE_ENABLED
  - config ETH_RX_BUF_SIZE to our needs, we used the max frame size
  - do ignore the rest (don't get confused by the PHY configuration section, it won't be used, the driver has its own PHY management)
- This file is automatically generated by STM32CubeMX, so don't touch anything else and be ready to do this (again) if you change something in the device configuration
Finally, FreeRTOS-Plus-TCP has some hooks that need to be filled. It asks the application/user every time it needs to generate a sequence number or a random number; we forward that request to the HAL random number generator:

Custom mg_random()

Some network operations require the generation of random numbers, from simple port numbers that should be different on every reset to complex TLS operations. Mongoose supports a number of well-known architectures, but since here we are working at the bare-metal level, we need to provide our own custom function or default to the standard pseudo-random number generator. The necessary actions are:

Define MG_ENABLE_CUSTOM_RANDOM=1 which is done in mongoose_config.h
Provide a custom void mg_random(void *buf, size_t len) function:

In this example, this function uses the microcontroller's built-in RNG through the STM32Cube HAL provided in the Keil packs

MCU and board initialization

Microcontroller support is provided by Keil firmware packs, which are based on STM32Cube firmware packages. The microcontroller, its clock, and all peripherals we use (except for the Ethernet controller) are initialized by HAL functions according to the configuration, code like this is generated by STM32CubeMX. In fact, to reproduce all the configuration steps, follow the step by step tutorial up to and including step 4. In particular, step 1 describes the additions we need to do to a Cube-generated main file to call the generated initialization functions, this mx_init() function we call at the start of our main() function. When creating the project, leave Device -> STM32Cube HAL package -> ETH unchecked.

We do not configure the Ethernet Controller in STM32CubeMX, but we do need to properly configure all RMII pins, so it initializes them for us.

Finally, we need to mimic the HAL initialization function for the NVIC and the Ethernet MAC clock:

Since this is a FreeRTOS project, task memory allocation will be done through it. We've left the initial stack and heap allocation at small values (2KB each) at project creation; that can be seen/modified by opening the assembly startup file (Device/startup_<devicefamilyname>.s) in μVision and then use the Configuration Wizard. This setting affects the linker process.

TCP/IP initialization

Once FreeRTOS-Plus-TCP initializes the network (after the scheduler has been started), it will call vApplicationIPNetworkEventHook(); here we check for the expected event (the DHCP server assigns us an address) and then create the server task to run Mongoose.

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.

Create tasks and start scheduler

The call to FreeRTOS_IPInit() above created all necessary tasks for the network stack. We then create other necessary tasks and call the function that starts the scheduler. Then, FreeRTOS takes over and we have a blinker task to blink an LED and the network stack tasks that will call our hook in due time to start our server.

Mongoose initialization

In the server task 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.

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 defined as a preprocessor symbol.

Blinker task

This is a simple FreeRTOS task that toggles the GPIO and loops, to blink the blue LED

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