Device dashboard on a TI EK-TM4C1294XL baremetal
This tutorial shows how to implement a Web device dashboard using Mongoose Library on a TI EK-TM4C1294XL development board.
Features of this implementation include:
- Bare metal - uses no external frameworks / middlewares
- Uses ARM CMSIS Core and TM4C CMSIS headers
- Uses Mongoose's built-in TCP/IP stack, which includes a TM4C Ethernet driver
- Does NOT use an external network stack like lwIP, or RTOS like FreeRTOS
- The device keeps a connection to an external MQTT server
- 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 and communicate to the MQTT server
- 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.
This example is a plain GCC make-based project with the following files:
- 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
- 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
- startup.c - used for startup code and IRQ vector table, following CMSIS guidelines
- 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.h- Mongoose Library
net.c- part of the device dashboard example, contains the Web and MQTT functionality
packed_fs.c- part of device dashboard example, embeds the Web UI used by the dashboard
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 an LED
- Once LED1 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
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 board
- Then we need to tell it which board it is that we have
- and confirm by pressing
- Then we browse to where we've built this example, and select
- Finally, we load the code
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:63:main Starting, CPU freq 120 MHz a 2 main.c:86:main MAC: 08:00:28:5a:95:bd. Waiting for IP... ... 907 2 mongoose.c:7356:onstatechange READY, IP: 192.168.69.236 90d 2 mongoose.c:7357:onstatechange GW: 192.168.69.1 913 2 mongoose.c:7359:onstatechange Lease: 21600 sec 918 2 main.c:91:main Initialising application... 91e 3 mongoose.c:3423:mg_listen 1 0x0 http://0.0.0.0 924 2 main.c:95:main Starting event loop
Now start a browser on
IP_ADDRESSis 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.
-DMG_ARCH=MG_ARCH_NEWLIB- configures Mongoose to work with the Newlib runtime library
-DMG_ENABLE_CUSTOM_MILLIS=1- lets the firmware code override
-DMG_ENABLE_TCPIP=1- enables the built-in TCP/IP stack
-DMG_ENABLE_DRIVER_TM4C=1- enables the built-in TM4C Ethernet driver
-DMG_ENABLE_PACKED_FS=1- enables the embedded filesystem support
This example can be divided in the following blocks:
- Provide a time base in milliseconds
- Initialize the microcontroller for this particular board
- Initialize the Ethernet controller
- Initialize Mongoose
- Initialize the networking stack
- Run Mongoose
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:
MG_ENABLE_CUSTOM_MILLIS=1which is done in the Makefile
- Provide a custom
In this example, this function is based on ARM's SysTick:
MCU and board initialization
Microcontroller support is provided by CMSIS, and the
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. 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:
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.
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 the Makefile by defining
MG_ENABLE_TCPIP=1; we also enable there the driver code we are going to use, by defining
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_driverand any extra data that it could need
- For DHCP: set
- For a static configuration, specify
gwin network byte order
In this example, we use DHCP:
Note that, we also need to specify a unique MAC 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 so this example provides a macro to read it.
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.
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 TM4C implementation, for the details on the application and the UI, please see the device dashboard tutorial.