Device dashboard on NUCLEO boards - FreeRTOS
This tutorial shows how to implement a Web device dashboard using Mongoose Library over FreeRTOS on STM32 development boards. We provide instructions for NUCLEO-F746ZG, NUCLEO-F429ZI, NUCLEO-H563ZI, and NUCLEO-H743ZI2.
Features of this implementation include:
- Uses ARM CMSIS Core headers and STM32 CMSIS device headers
- Uses FreeRTOS-Kernel headers and sources
- Uses Mongoose's built-in TCP/IP stack, which includes an STM32 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, FreeRTOS and network initialization
- hal.h - provides a simple API on top of the CMSIS API, like
- 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
- 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.h- Mongoose Library
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
startup_stm32f746xx.s- part of STM32 CMSIS, used for startup code and IRQ vector table
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 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.
Start a terminal in the project directory; clone the Mongoose Library repo, and run the
git clone https://github.com/cesanta/mongoose cd mongoose/examples/stm32/nucleo-f746zg-make-freertos-builtin make build
In order to flash this recently built firmware to your board, plug it in a USB port and execute:
As long as there is only one board plugged in, stlink will find it; though we need to know the serial port device to be able to get the log information. In Linux it is probably
When the firmware is flashed, 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 picocom; we configure it for 115200bps. Use the proper serial device.
picocom /dev/ttyACM0 -i -b 115200 picocom v2.2 ... Terminal ready 0 2 main.c:62:server MAC: 02:33:47:5b:3e:32. Waiting for IP... ... 809 2 mongoose.c:7349:onstatechange READY, IP: 192.168.0.137 80f 2 mongoose.c:7350:onstatechange GW: 192.168.0.1 814 2 mongoose.c:7352:onstatechange Lease: 63262 sec 81a 2 main.c:67:server Initialising application... 820 3 mongoose.c:3421:mg_listen 1 0x0 http://0.0.0.0 824 2 main.c:71:server Starting event loop
Now start a browser on
IP_ADDRESSis 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.
-DMG_ARCH=MG_ARCH_FREERTOS- configures Mongoose to work with FreeRTOS
-DMG_ENABLE_CUSTOM_RANDOM=1- lets the firmware code override
mg_random()to use the device hardware RNG
-DMG_ENABLE_TCPIP=1- enables the built-in TCP/IP stack
-DMG_ENABLE_PACKED_FS=1- enables the embedded filesystem support
- To enable the proper built-in driver for your board:
Board Compilation option NUCLEO-F429ZI
This example can be divided in the following blocks:
- FreeRTOS integration for this microcontroller
- 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 Ethernet controller
- Initialize Mongoose
- Initialize the networking stack
- Run Mongoose
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_CM7/r0p1: headers specific for the GCC compiler and the ARM Cortex-M7 r0p1 core, see table below
FreeRTOS-Kernel/*.c: the generic kernel code
FreeRTOS-Kernel/portable/GCC/ARM_CM7/r0p1/port.c: the specific kernel code for the GCC compiler and the ARM Cortex-M7 r0p1 core, see table below
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 (see table below); and the required exception handlers, preferences, and stack and heap sizes
|Board||Device (Rev)||Core||Priority bits||Recommended FreeRTOS-Kernel code|
|NUCLEO-H743ZI||STM32H743ZIT6 (Y)||Cortex-M7 r1p0||4||ARM_CM4F|
|NUCLEO-H743ZI2||STM32H743ZIT6 (V)||Cortex-M7 r1p0||4||ARM_CM4F|
* The ARM_CM33 port has built-in handlers and does not require defining them as we did ago. It also does not allow to easily take over the SysTick handler. According to your application needs, use either the full version or the one that disables Trustzone (_NTZ). If neither TrustZone nor the MPU are needed, the ARM_CM4F port can be used instead.
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:
MG_ENABLE_CUSTOM_RANDOM=1. We do this in
- 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 function
rng_read() defined in
MCU and board initialization
Microcontroller support is provided by CMSIS, and the
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:
|Board||Device (Rev)||Max CPU Clock Frequency||Max HCLK Frequency|
|NUCLEO-F429ZI||STM32F429ZIT6||180 MHz||180 MHz|
|NUCLEO-F746ZG||STM32F746ZGT6||216 MHz||216 MHz|
|NUCLEO-H563ZI||STM32H563ZIT6||250 MHz||250 MHz|
|NUCLEO-H743ZI||STM32H743ZIT6 (Y)||400 MHz||200 MHz|
|NUCLEO-H743ZI2||STM32H743ZIT6 (V)||480 MHz||240 MHz|
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. We need to enable the MAC GPIO pins to connect to the dev board PHY using RMII, and configure the clocks:
|Board||Device (Rev)||Initialization code|
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.
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_custom.h. In that file, we add the proper definition:
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_driverand any extra data that it could need
- For DHCP: set
- For a static configuration, specify
gwin 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; this example provides a macro to transform the chip built-in unique ID into a 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.
Some drivers, as you have probably noticed, require extra data. In this case the STM32 driver can accept the setting for the divider that generates the 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.
For the STM32H driver, use
.driver = &mg_tcpip_driver_stm32h and also
driver_data will be a
struct mg_tcpip_driver_stm32h_data, check the corresponding main.c file.
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.
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.
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 STM32 implementation, for the details on the application and the UI, please see the Device Dashboard tutorial.