Overview

This example shows how to build an HTTP server using Mongoose Library and run it on an STM32 Nucleo-F429Z development board with FreeRTOS and lwIP.

The source code for this tutorial is located at https://github.com/mongoose-examples/stm32-nucleo-f429z

A big part of this example is a regular STM32CubeIDE project (a lot of generated files, FreeRTOS and lwIP sources, etc.). Mongoose-related functions are located in files Src/web_server.c and Inc/web_server.h. Below is a general process outline:

  • Set IP address, network mask and gateway in Inc/main.h
  • Build the example (see below) and run it on a development board
  • The firmware initializes the network, and turns on a green LED if the initialization was successful, a red one otherwise
  • If you see a red LED turned on, make sure that your Ethernet cable is properly connected to the board
  • After initialization, the application starts Mongoose's event loop and blinks a blue LED
  • Once the blue LED starts blinking - the web server is ready
  • Open your web browser and navigate to the board IP address, you should see a "Hello, world" page

Build options

There are (at least) two options to build the example:

  1. Using the make command
  2. Using the STM32CubeIDE IDE

Option 1: make

  • Install Docker
  • Install the stlink flash utility
  • Start a terminal, navigate to the project folder, and from there run
    $ make build
    
  • When build finishes, run
    $ make flash
    

Done! Now the firmware is flashed and the board should signal its state via an LED indicator (green or red).

Option 2: STM32CubeIDE

STM32CubeIDE is an IDE software provided by STMicroelectronics.

  • Start STM32CubeIDE
  • Choose File -> Import... and then select Existing Projects into Workspace:pic
  • Pick a project directory as Root directory, make sure that NUCLEO-F429Zx-simple-web-server is checked and click Finish:pic
  • After import, choose Run As -> STM32 Application:pic
  • Done! The firmware should light the LEDs

Debug output

During execution, Mongoose can print debug information. There are several ways to receive this information. This example re-routes stdout to the SWV ITM Console. This allows us to see the output of printf() and similar functions directly in STM32CubeIDE. For this, you need to do following:

  1. Choose Run -> Debug configuration:
  2. Under STM32 Application select the NUCLEO-F429Zx-simple-web-server configuration. Note: if you don't see this configuration, close the dialog and start the debug session via Debug as -> STM Application to create it:
  3. Go to the Debugger tab
  4. Check Enabled in the Serial Wire Viewer section
  5. Update the Core clock setting, set it to 180MHz
  6. Click Apply and then click Debug to start the debug session.
  7. Once the application stops at the beginning of the main function, open the SWV Console (Window->Show View->SWV->SWV ITM Data Console)
  8. Click Add port and add port 0
  9. Click Configure trace and enable port 0
  10. Click Start trace
  11. Resume program execution
  12. You should see something like this in the console window:
    1970-01-01 00:00:00  I web_server.c:30:server    Starting Mongoose v7.4
    1970-01-01 00:00:00  I mongoose.c:3297:mg_listen 1 accepting on http://0.0.0.0:80 (port 80)
    
  13. Done! Now you can use the printf() function or the LOG() macro to output required information

Custom application

In order to create your own Mongoose-enabled application you have several ways:

  1. The obvious way, is to add the required functionality to this example. The sample includes all standard HAL Drivers. As you can see in the Src/web_server.c file, the BSP_LED_On() function is used to turn on an LED. In the same way, you can have access to all the HAL functions.

  2. If, for some reason, you can't use this example as a base (e.g.: you have your own big project to which you need to add Mongoose), you can do the following:

    • Add FreeRTOS and lwIP to your project (via Device Configuration tool or manually, depending on your project type)
    • Initialize FreeRTOS and lwIP. Read this STM article.
    • Add the mongoose.c (and .h if you want) file(s) to your project
    • Add Mongoose-specific configuration flags
    • Add the following defines in the lwipopts.h file:
      #define LWIP_SOCKET                     1
      #define LWIP_POSIX_SOCKETS_IO_NAMES     0
      #define SO_REUSE                        0
      
    • Add MG_ARCH=MG_ARCH_FREERTOS_LWIP to the preprocessor symbols (Properties->C/C++ Build->Settings->Preprocessor)
    • Enable float usage for printf (Properties->C/C++ Build->Settings->MCU Settings->Use float with printf)
    • Done! Now write code similar to that in Src/web_server.c (read Mongoose documentation) and let the magic begin
  3. If you want to evaluate STM and Mongoose as fast and simple as possible, but you have a board that is not covered by any of our examples and tutorials, try to use the LwIP_HTTP_Server_Netconn_RTOS example: it supports a lot of boards.

    • Copy the example to your workspace
    • Add mongoose.c and web_server.c to your project
    • Add the same Mongoose-specific configuration flags as in point 2
    • Comment out netconn initialization (probably in the StartThread() function) and call start_mongoose() instead
    • That's it! Your application should build and run Mongoose.