Device dashboard with CubeIDE

Overview

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

Features of this implementation include:

• Bare metal - uses no external frameworks / middlewares, except for the STM32Cube HAL, used for peripheral initialization
• Uses 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 RTOS like FreeRTOS
• 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:

• 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. Note we've added a modified [_write() function](https://github.com/cesanta/mongoose/blob/6a2fa10/examples/stm32/ nucleo-f746zg-cube-baremetal-builtin/Core/Src/syscalls.c#L81-L94) to redirect debug output to a UART.
• mongoose/mongoose.c, mongoose/mongoose.h - Mongoose Library
• mongoose/mongoose_config.h - Mongoose configuration file; also provides an abstraction for MAC generation
• nucleo-f746zg-cube-baremetal-builtin.ioc - the device configuration file. This file is used as the recipe to generate the code for drivers 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.

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.

• 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. The project directory for each board is listed in the table above

• 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..
  ...
  adb    2 mongoose.c:7366:onstatechange  READY, IP: 192.168.69.235               
  ae2    2 mongoose.c:7367:onstatechange         GW: 192.168.69.1                 
  ae7    2 mongoose.c:7369:onstatechange         Lease: 21600 sec                 
  aed    2 main.c:165:main                Initialising application...             
  af4    3 mongoose.c:3356:mg_listen      1 0x0 http://0.0.0.0                    
  af9    2 main.c:169: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_CUBE - configures Mongoose to work with ST's HAL and the Cube environment
• MG_ENABLE_PACKED_FS=1 - enables the embedded filesystem support
• MG_ENABLE_POSIX_FS=0 - disables filesystem usage not provided in syscalls.c

These are grouped in the file mongoose/mongoose_config.h as preprocessor macros.

To see more detail on what happens behind the scenes, see here

main.c overview

This example can be divided in the following blocks:

1. Initialize the microcontroller for this particular board
2. Initialize Mongoose
3. Initialize the networking stack
4. Run Mongoose

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 baremetal project but we do not control everything, to be on the safe side we've setup some room for the stack and some for the heap. This is done at project generation using the tools mentioned above, and can be seen by opening the ioc file with them. This setting affects the generated linker file(s).

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

Network settings are configured via macros inside mongoose_config.h:

• For static IP configuration, define MG_TCPIP_IP, MG_TCPIP_MASK, MG_TCPIP_GW. By default, those are set to zero, meaning that DHCP is used

  #define MG_TCPIP_IP MG_IPV4(192, 168, 0, 10)
  #define MG_TCPIP_GW MG_IPV4(192, 168, 0, 1)
  #define MG_TCPIP_MASK MG_IPV4(255, 255, 255, 0)
  

• Most ST boards use address 0 for the PHY, which is the default, but some of them require setting it manually to the proper value. This we do at mongoose_config.h, only if necessary, for example for an STM32H745I-Disco:

  #define MG_TCPIP_PHY_ADDR 1  // PHY address for an STM32H745I-Disco
  

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.

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.

Firmware Update

Check the Firmware Update tutorial for information on how to generate a binary file

A1. Behind the scenes

Let's see how MG_ARCH_CUBE sets some traditional Mongoose config stuff for us. Please note that you don't actually need to do anything, things explained here let you have a fine control on some of the settings; they are shown here so you can have a clearer picture of what is configured, how, and where.

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 automagically by setting MG_ARCH = MG_ARCH_CUBE. Internally, this defines MG_ENABLE_TCPIP=1 and the corresponding driver for the particular Ethernet controller. Network settings are configured via macros inside mongoose_config.h; the main macro is executed if MG_ENABLE_TCPIP_DRIVER_INIT == 1, which is its default value:

Internally, 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.

A custom initialization could set MG_ENABLE_TCPIP_DRIVER_INIT = 0 and do the following in Core/Src/main.c, inside the main() function:

struct mg_mgr mgr;
mg_mgr_init(&mgr);
struct mg_tcpip_if mif = {
    .mac = {2, 0, 1, 2, 3, 4},
    .driver = &mg_tcpip_driver_stm32f,
};
mg_tcpip_init(&mgr, &mif);
for (;;) mg_mgr_poll(&mgr, 100);

For the STM32H driver, use .driver = &mg_tcpip_driver_stm32h

In general, to enable the proper built-in driver for your microcontroller:

Then, depending on the chip, you need to pay attention to clock speed and the value of the MDC clock divider:

#define MG_DRIVER_MDC_CR 4   // RMII MDC clock divider, from 0 to 4

• Set a custom MAC address. By default, it is randomly generated; for STM32 parts we try to generate one based on the MCU unique ID.
  • Using a build-time constant:

    #define MG_SET_MAC_ADDRESS(mac) do { uint8_t buf_[6] = {2,3,4,5,6,7}; memmove(mac, buf_, sizeof(buf_)); } while (0)
    

    • E.g.: Construct a MAC address from the MCU unique ID, for an F746, it is defined in the ST CMSIS header as UID_BASE

      #define MGUID ((uint32_t *) 0x1ff0f420)
      #define MG_SET_MAC_ADDRESS(mac)      \
        do {                               \
          mac[0] = 2;                      \
          mac[1] = MGUID[0] & 255;         \
          mac[2] = (MGUID[0] >> 10) & 255; \
          mac[3] = (MGUID[0] >> 19) & 255; \
          mac[4] = MGUID[1] & 255;         \
          mac[5] = MGUID[2] & 255;         \
        } while (0)
      

  • Using a custom function:

    extern void my_function(unsigned char *mac);
    #define MG_SET_MAC_ADDRESS(mac) my_function(mac)
    

For more information on how to configure Mongoose for your own board, follow the Hardware tutorial

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, which is done automagically by setting MG_ARCH = MG_ARCH_CUBE
2. Provide a custom uint64_t mg_millis(void) function:

As you can see, we take advantage of the Cube HAL and just call its timing function

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, which is done automagically by setting MG_ARCH = MG_ARCH_CUBE
2. Provide a custom void mg_random(void *buf, size_t len) function:

This function uses the microcontroller's built-in RNG through the STM32Cube HAL

Firmware Update

Set the proper value for MG_OTA, which is done automagically by setting MG_ARCH = MG_ARCH_CUBE

Check the Firmware Update tutorial for more information

Build with TLS support

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

1. Define MG_TLS=MG_TLS_BUILTIN, which is done automagically by setting MG_ARCH = MG_ARCH_CUBE

You can also pass that when building:

make build CFLAGS_EXTRA="-DMG_TLS=MG_TLS_BUILTIN"

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