Device dashboard on NUCLEO and Discovery boards - baremetal

Overview

This tutorial shows how to implement a Web device dashboard using Mongoose Library on STM32 development boards. Check supported boards below.

Features of this implementation include:

• Bare metal - uses no external frameworks / middlewares
• Uses ARM CMSIS Core and STM32 CMSIS Device headers
• Uses Mongoose's built-in TCP/IP stack, which includes an STM32 Ethernet driver
• Does NOT use an external network stack like lwIP, or RTOS like 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.

Though we specifically link to the files for a NUCLEO-F746ZG implementation, most references in this tutorial are valid for any supported board:

• 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
• link.ld - a GNU linker script file, used for building the firmware binary
• Makefile - a GNU Makefile for building, flashing and testing the project
• 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
• 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 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 make build command. The project directory for each board is listed in the table above

  git clone https://github.com/cesanta/mongoose
  cd mongoose/examples/stm32/nucleo-f746zg-make-baremetal-builtin
  make build
  

• In order to flash this recently built firmware to your board, plug it in a USB port and execute:

  make flash
  

  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 /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
  0      2 main.c:59:main                 Starting, CPU freq 216 MHz
  6      2 main.c:75:main                 MAC: 02:33:47:5b:3e:32. Waiting for IP...
  ...
  808    2 mongoose.c:7349:onstatechange  READY, IP: 192.168.0.137
  80d    2 mongoose.c:7350:onstatechange         GW: 192.168.0.1
  813    2 mongoose.c:7352:onstatechange         Lease: 86188 sec
  819    2 main.c:80:main                 Initialising application...
  81f    3 mongoose.c:3421:mg_listen      1 0x0 http://0.0.0.0
  824    2 main.c:84:main                 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_NEWLIB - configures Mongoose to work with the Newlib runtime library
• MG_ENABLE_CUSTOM_MILLIS = 1 - lets the firmware code override mg_millis()
• MG_ENABLE_CUSTOM_RANDOM = 1 - lets the firmware code override mg_random() to use the device hardware RNG
• MG_ENABLE_TCPIP = 1 - enables the built-in TCP/IP stack
• MG_ENABLE_PACKED_FS = 1 - enables the embedded filesystem support
• To enable the proper built-in driver for your board:

  Board	Compilation option
  NUCLEO-F429ZI	MG_ENABLE_DRIVER_STM32F = 1
  NUCLEO-F746ZG	MG_ENABLE_DRIVER_STM32F = 1
  NUCLEO-H563ZI	MG_ENABLE_DRIVER_STM32H = 1
  NUCLEO-H723ZG	MG_ENABLE_DRIVER_STM32H = 1
  NUCLEO-H743ZI	MG_ENABLE_DRIVER_STM32H = 1
  NUCLEO-H743ZI2	MG_ENABLE_DRIVER_STM32H = 1
  STM32H573I-DK	MG_ENABLE_DRIVER_STM32H = 1
  STM32H747I-DISCO	MG_ENABLE_DRIVER_STM32H = 1

We define these in mongoose_config.h

main.c overview

This example can be divided in the following blocks:

1. Provide a time base in milliseconds and take advantage of the true RNG in the microcontroller
2. Initialize the microcontroller for this particular board
3. Initialize the Ethernet controller
4. Initialize Mongoose
5. Initialize the networking stack
6. Run Mongoose

Custom mg_millis()

Network operations need a time base to calculate timeouts. 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. The necessary actions are:

1. Define MG_ENABLE_CUSTOM_MILLIS=1. We do this in mongoose_config.h.
2. Provide a custom uint64_t mg_millis(void) function:

In this example, this function is based on ARM's SysTick:

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:

1. Define MG_ENABLE_CUSTOM_RANDOM=1. We do this in mongoose_config.h.
2. 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 hal.h

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:

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:

Mongoose initialization

Then we initialize Mongoose, this is no different from what we always do in any example.

There is also a timer that we use to blink the blue LED and output some status information:

For more information on timers, check the timers tutorial.

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:

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

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.

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.

Build with TLS support

To build with Mongoose built-in TLS support, just do

make build CFLAGS_EXTRA="-DMG_TLS=MG_TLS_BUILTIN"

In order to build with mbedTLS support (at this time, this is not available for the F429 example), just run:

make TLS=mbedtls

This sets the following compilation options:

• MG_TLS=MG_TLS_MBED

and uses the following additional configuration files:

• mbedtls_config.h

Check the "How to build" section of the TLS tutorial for more information

Firmware Update

This is a list of microcontrollers for which firmware update via an internal flash is supported:

To this, of course, you need to add #define MG_OTA MG_OTA_FLASH

We describe how to use these features on the UI in the Firmware Update tutorial