Overview

This tutorial shows how to use Mongoose Library at the bare metal level, using MIP (a bare-metal embedded TCP/IP stack designed specifically for Mongoose), and running on a TI EK-TM4C1294XL development board.

This tutorial covers a hardware example based on the device dashboard tutorial. You might want to read and follow that tutorial for the inner workings of the dashboard itself. All files in the example belong to the particular hardware implementation; Mongoose itself and all Mongoose-related functions are pulled by the Makefile from their location in the repository. The full source code is at https://github.com/cesanta/mongoose/tree/master/examples/ti/ek-tm4c1294xl-baremetal

This example is a plain gcc make-based project. The relevant files are:

  • mcu.h: provides all necessary MCU support, as this project is not CMSIS-based
  • boot.c: provides the MCU low-level initialization, vector table and default exception handlers
  • syscalls.c: provides an abstraction layer for those system functions Mongoose expects
  • main.c: here we do our main job, initializing the MCU, Mongoose, the network, and calling the event manager
  • Makefile: a standard make file that performs the compilation and linking process

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

  • It is assumed you're using Linux or Mac as a workstation, you have Docker installed, and your user is able to run it. If in doubt, check

    $ docker ps
    
  • We will also use the Uniflash flash utility

  • Start a terminal in the project directory; clone the Mongoose Library repo, and run the make build command:

    $ git clone https://github.com/cesanta/mongoose
    $ cd mongoose/examples/ti/ek-tm4c1294xl-baremetal
    $ make build
    
  • In order to flash this recently built firmware to your board, plug it in a USB port and run Uniflash.

    • It will find the debug adapter in your boardpic
    • Then we need to tell it which board it is that we havepic
    • and confirm by pressing Startpic
    • Then we browse to where we've built this example, and select firmware.binpic
    • Finally, we load the codepic
  • When the firmware is flashed, the board should signal its state by blinking LED1; while LED4 and LED3 will work as "link" and "activity" for the network. 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 and to add a carriage return. Use the proper serial device.

    $ picocom /dev/ttyACM0 -i -b 115200 --imap=lfcrlf
    picocom v2.2
    ...
    Terminal ready
    0 2 main.c:76:main                      Init done, starting main loop
    6 3 mongoose.c:3488:mg_listen           1 0x0 http://0.0.0.0
    ...
    b4e 2 mongoose.c:6382:onstatechange     READY, IP: 192.168.69.232
    
  • 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.

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

How it works

This example can be divided in the following blocks:

  1. Provide a time base in milliseconds
  2. Initialize the microcontroller for this particular board
  3. Initialize the Ethernet controller
  4. Initialize Mongoose
  5. Initialize the networking stack
  6. Run Mongoose
  7. Additional support handlers like the HardFault handler and the EXTI handler for reading a button

Time base

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 in the Makefile
  2. Provide a custom uint64_t mg_millis(void) function:

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

MCU and board initialization

This example, and the MIP stack itself, don't use CMSIS nor any other third-party libraries. Microcontroller support is provided by the mcu.h and boot.c files. In our main function, we call these functions to initialize the MCU and those peripherals we are going to use:

Ethernet controller initialization

The Ethernet controller initialization follows. This chip has a built-in PHY, so we just need to configure the GPIO pins for the LEDs, configure the clocks, and reset the MAC controller and the PHY:

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 LED1

For more information on timers, check the timers tutorial.

MIP initialization

MIP has to be enabled to be compiled in, and so Mongoose will work in association with it. This is done in the Makefile by defining MG_ENABLE_MIP=1; we also enable there the driver code we are going to use, by defining MG_ENABLE_DRIVER_TM4C=1

Then this networking stack has to be configured and initialized. This is done by calling mip_init() and passing it a pointer to a struct mip_if. Inside this structure:

  • have pointers to a struct mip_driver and any extra data that it could need
  • For DHCP: set use_dhcp
  • For a static configuration, specify ip, mask, and gw in network byte order

In this example, we use DHCP:

Note that, we also need to specify a unique MAC address. For this example we chose a fancy 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. However, in these evaluation boards, TI provides a MAC address in the microcontroller flash.

Some drivers, as you have probably noticed, require extra data. In this case the TM4C driver can accept the setting for the divider that generates the internal 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.

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 on port 80, and fall into an infinite event loop:

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.

HardFault and button handlers

Finally, a brief look at those exception handlers that will take care of handling the button and telling us of possible initialization errors once we embark ourselves on crafting our own custom application.

If you press the board button, LED2 will light:

If your code triggers an exception that is not handled, it will escalate to a HardFault and both LED1 and LED2 will blink alternately:

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 example includes an important set of drivers. As we've seen in previous sections, there are functions to read and write to GPIOs and to handle interrupts.

  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, or you'd rather use CMSIS and/or your preferred IDE), you can do the following:

    • Add these project files to your project
    • Add mongoose.c and .h files to your project
    • Add Mongoose-specific configuration flags, see the Makefile
    • Add the required preprocessor symbols:
      • MG_ARCH=MG_ARCH_NEWLIB, MG_ENABLE_CUSTOM_MILLIS=1, MG_ENABLE_MIP=1, MG_ENABLE_DRIVER_TM4C=1
    • Provide a suitable time base for Mongoose and MIP
    • Since the PHY uses the external clock, make sure you design in a 25 MHz clock; then follow the example main() function from the Ethernet controller initialization
    • Now write code similar to that in main.c; for that you can read Mongoose documentation and follow our examples and tutorials