Device dashboard with CubeIDE and FreeRTOS
Overview
This tutorial shows how to implement a Web device dashboard using Mongoose Library over FreeRTOS on STM32 Nucleo development boards, using the STM32CubeIDE development environment. We provide instructions for NUCLEO-F746ZG, NUCLEO-F429ZI, and NUCLEO-H743ZI2.
Features of this implementation include:
- Uses FreeRTOS, ARM CMSIS Core and device headers through STM32Cube packages
- 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 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 STM32Cube environment.
Though we specifically link to the files for a NUCLEO-F746ZG implementation, most references in this tutorial are valid for any supported board:
Board | Files |
---|---|
NUCLEO-F429ZI | examples/stm32/nucleo-f429zi-cube-freertos-builtin |
NUCLEO-F746ZG | examples/stm32/nucleo-f746zg-cube-freertos-builtin |
NUCLEO-H743ZI2 | examples/stm32/nucleo-h743zi-cube-freertos-builtin |
This example is a plain STM32Cube-based project with the following files of interest:
- Core/Src/main.c - provides the
main()
entry point with hardware init, LED blinking and network init. It is generated by Cube and we add our logic in it. - Core/Inc/hal.h - provides an abstraction for MAC generation
- Core/Src/syscalls.c - provides low level functions expected by the ARM GCC C library. It is generated by Cube and we've modified the _write() function to redirect debug output to a UART.
Core/Src/mongoose.c
,Core/Inc/mongoose.h
- Mongoose LibraryCore/Src/net.c
,Core/Inc/net.h
- part of the device dashboard example, contains the Web functionalityCore/Src/packed_fs.c
- part of the device dashboard example, embeds the Web UI used by the dashboardnucleo-f746zg-cube-freertos-builtin.ioc
- the device configuration file. This file is used as the recipe to generate the code for drivers, FreeRTOS, and device initialization
For all auto-generated files, we've used those places designated for USER_CODE, so all files can be re-generated by STM32CubeIDE or STM32CubeMX for newer versions of the STM32Cube firmware packages.
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, 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.
Clone the Mongoose Library repository using git
Start STM32CubeIDE and import the project into your workspace; if you need a quick start on Cube itself, follow this step by step tutorial. This project is at
examples/stm32/nucleo-f746zg-cube-freertos-builtin
In order to build and flash this firmware to your board, plug it in a USB port and click on the green arrow icon. You should soon see the blue LED start blinking. As long as there is only one board plugged in, Cube 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
/dev/ttyACM0
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 8 2 main.c:144:main Starting, CPU freq 216 MHz e 2 main.c:160:main MAC: 02:35:42:56:22:2e. Waiting for IP.. ... 17cf 2 mongoose.c:7366:onstatechange READY, IP: 192.168.100.21 17d5 2 mongoose.c:7367:onstatechange GW: 192.168.100.1 17db 2 mongoose.c:7369:onstatechange Lease: 60 sec 17e1 2 main.c:492:server Initialising application... 17e7 3 mongoose.c:3356:mg_listen 1 0x0 http://0.0.0.0 17ed 2 main.c:496:server Starting event loop
Now start a browser on
http://IP_ADDRESS
, whereIP_ADDRESS
is the board's IP address printed on the serial console. You should see a login screen as in the image aboveFrom 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_CMSIS_RTOS_2
- configures Mongoose to work with a CMSIS-RTOS2 API. We might also useMG_ARCH_FREERTOS
to work with the native FreeRTOS API, see belowMG_ENABLE_CUSTOM_RANDOM=1
- lets the firmware code overridemg_random()
to use the device hardware RNGMG_ENABLE_TCPIP=1
- enables the built-in TCP/IP stackMG_ENABLE_PACKED_FS=1
- enables the embedded filesystem supportMG_ENABLE_POSIX_FS=0
- disables filesystem usage not provided in syscalls.c
These are grouped in the file Core/Inc/mongoose_config.h as preprocessor macros.
- To enable the proper built-in driver for your board, set the following in the preprocessor symbols:
Board | Compilation option |
---|---|
NUCLEO-F429ZI | MG_ENABLE_DRIVER_STM32F=1 |
NUCLEO-F746ZG | MG_ENABLE_DRIVER_STM32F=1 |
NUCLEO-H743ZI | MG_ENABLE_DRIVER_STM32H=1 |
NUCLEO-H743ZI2 | MG_ENABLE_DRIVER_STM32H=1 |
main.c overview
This example can be divided in the following blocks:
- FreeRTOS 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 Mongoose
- Initialize the networking stack
- Run Mongoose
FreeRTOS integration
Mongoose supports a number of well-known architectures, among them FreeRTOS and CMSIS-RTOS2. 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
. Cube provides both CMSIS-RTOS abstraction APIs, we'll configure it for version 2. In principle we might use FreeRTOS native interface, but since Cube somehow suggests to use the CMSIS API, we'll follow that path. We also need to set the amount of memory we'll use for the main heap. Task memory allocation defaults to dynamic. This means that memory for the stack of each new task will be allocated from the FreeRTOS heap, so we need to provide a suitable amount of memory.
Network operations need a time base to calculate timeouts; this will be provided by FreeRTOS and Mongoose now knows how to call it. We need a 1000 Hz rate to provide a 1ms time base, and that is the default for Cube.
Note we also create the necessary tasks at configuration time, we'll have a Server task, where we initialize and run Mongoose, and a Blinker task to blink an LED. We provide ample stack space for the Mongoose task;complex interfaces need plenty of room in the stack.
- At the device configuration wizard, select the
Pinout & Configuration
tab. Click onMiddleware and Software Packs
, then onFREERTOS
, and finally selectCMSIS_V2
as interface: - In the Config Parameters section configure the
TOTAL_HEAP_SIZE
- In the Tasks and Queues section, rename the default task to "Blinker" (change its handler function name also) and create a "Server" task with a stack of 2048 32-bit words and osPriorityNormal:
- Now click on the Advanced settings section, then, on
Newlib settings
, enableUSE_NEWLIB_REENTRANT
:
As you can see, we take advantage of the Cube packages.
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 inmongoose_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
MCU and board initialization
Microcontroller support is provided by STM32Cube firmware packages. The microcontroller, its clock, and all peripherals we use are initialized by HAL functions according to the configuration, code like this can be generated by either the Device Configuration Tool
in STM32CubeIDE or by STM32CubeMX. In fact, to reproduce all the configuration steps, follow the step by step tutorial up to and including step 5.
Since this is a FreeRTOS project, task memory allocation will be done through it. We've left the initial stack and heap allocation at default values as selected by Cube.
Create tasks and start scheduler
The auto-generated code creates the tasks and calls the function that starts the scheduler. Then, FreeRTOS takes over and will call the tasks we configured above
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.
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 in mongoose_config.h
by defining MG_ENABLE_TCPIP=1
(for the STM32H driver, also MG_ENABLE_DRIVER_STM32H=1
) as preprocessor macros.
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
, andgw
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; 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 Core/Src/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.
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 LED2 (blue in Nucleo-F429ZI and F746ZG, yellow in Nucleo-H743ZI2)
On the Nucleo-H743ZI2 board, the LED is connected to GPIO PE1.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.