STM32 Nucleo-F746ZG MIP USB RNDIS
This tutorial shows how to use Mongoose Library over RNDIS through a USB connection, using MIP (a bare-metal embedded TCP/IP stack designed specifically for Mongoose), and running on an STM32 Nucleo-F746ZG development board.
We implement a very basic web server that responds "hi" to any URL and provides a minimal example of a REST API to change the debug level. The full source code for this project is at https://github.com/cesanta/mongoose/tree/master/examples/stm32/nucleo-f746zg-usb-rndis
This example is a plain gcc make-based project. The relevant files are:
include/: provides all necessary MCU support, this project is CMSIS-based
tinyusb/: provides the USB functionality through TinyUSB; see TinyUSB integration below
mcu.h: provides a minimal HAL to perform the most common activities in a uniform way
startup.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 and Mongoose, providing an interface with TinyUSB, initializing 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 static:
192.168.3.1. If this conflicts with your network, change IP address and network mask in
main.c; see below
- Build the example (see below) and run it on a development board connected to the debugging port (CN1) as usual.
- The firmware initializes the USB stack
- After initialization, the application starts Mongoose's event loop and blinks a blue LED
- Once the blue LED starts blinking, the example is ready
- Connect the other USB connector (CN13), which connects to the MCU, to another USB port in your computer.
- The board will enumerate as a USB Communication Device Class (CDC) Ethernet Control Model (ECM) device, and also as a Remote Network Driver Interface Specification (RNDIS) device. This allows us to work with different host operating systems.
- The host will then add a new networking interface and will ask for an IP address. Our device will respond assigning it an address corresponding to its own address +1:
- Open your web browser and connect to the board IP address (
192.168.3.1), you should see a greeting
Build and run
It is assumed you're using Linux or Mac as a workstation, and you have ARM GCC installed. For Windows, install make, the build procedure is the same, though your serial port name will be different and you won't have picocom
We will also use the stlink flash utility
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/stm32/nucleo-f746zg-usb-rndis $ 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. It is probably
When the firmware is flashed, the board should signal its state by blinking the blue LED. We now need to see the device logs.
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:86:main Init TCP/IP stack ... 5 3 mongoose.c:3493:mg_listen 1 0x0 tcp://0.0.0.0:80 b 2 main.c:98:main Init USB ... f 2 main.c:112:main Init done, starting main loop ...
Now plug your board's MCU USB connector (CN13), you should see something like this in your log:
1775 2 mongoose.c:6749:onstatechange READY, IP: 192.168.3.1 177a 2 mongoose.c:6750:onstatechange GW: 0.0.0.0 177f 3 mongoose.c:6723:arp_cache_add ARP cache: added 192.168.3.2 @ 5e:11:1d:d8:a6:b2
- On a Linux host, you'll see something like this in the system log (
[30922.493149] usb 5-4: new full-speed USB device number 2 using ohci-pci [30922.663197] usb 5-4: New USB device found, idVendor=cafe, idProduct=4020, bcdDevice= 1.01 [30922.663207] usb 5-4: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [30922.663213] usb 5-4: Product: TinyUSB Device [30922.663218] usb 5-4: Manufacturer: TinyUSB [30922.663222] usb 5-4: SerialNumber: 123456 [30923.230334] usbcore: registered new interface driver cdc_ether [30923.254926] rndis_host 5-4:1.0 usb0: register 'rndis_host' at usb-0000:00:13.0-4, RNDIS device, 5e:11:1d:d8:a6:b2 [30923.255926] usbcore: registered new interface driver rndis_host
- On MacOS, CDC-ECM will be picked:
- On Windows, RNDIS:
- On a Linux host, you'll see something like this in the system log (
Now start a browser on
192.168.3.1. You should see a greeting. You can also use curl:
$ curl 192.168.3.1 hi
How it works
This example can be divided in the following blocks:
- Provide a time base in milliseconds
- TinyUSB integration for this microcontroller
- Initialize the microcontroller for this particular board
- Initialize the USB controller and stack
- Initialize Mongoose
- Initialize the networking stack
- Run Mongoose and TinyUSB
- Under the hood: interfacing MIP to TinyUSB, driver internals
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:
In the Makefile, we clone the TinyUSB repository at a stable branch; then we set the proper paths for include files and required code:
tinyusb/src/: headers and code, including class code. We cherry picked the necessary files from this subtree, see the Makefile
tinyusb/lib/networking: headers and code. We cherry picked the necessary files from this subtree, see the Makefile
tinyusb/src/portable/synopsys/dwc2/dcd_dwc2.c: the specific code for the USB controller in this MCU
usb_descriptors.c: definitions and code to present the required descriptors for the classes in use
tusb_config.h: here we do our main integration job, defining the specific microcontroller, baremetal operation, no debugging, device mode, and device type
We need to route USB controller interrupts to the TinyUSB handler:
Then, as we'll see below, as this is bare-metal code, we'll periodically call its main handler
Then TinyUSB will call us back when it has finished initializing the network, when it has received a frame, and when it can send a frame:
void tud_network_init_cb(void); bool tud_network_recv_cb(const uint8_t *buf, uint16_t len); uint16_t tud_network_xmit_cb(uint8_t *dst, void *ref, uint16_t arg);
We will ask TinyUSB if we can transmit and to do it, using these function calls:
tud_network_can_xmit(len); tud_network_xmit(buf, len);
MCU and board initialization
This example uses CMSIS (though the MIP stack itself does not). To keep things easier we provided a thin HAL layer in the
mcu.h file; while the
startup.c file handles the reset vector and calls our main function. There, we call these HAL functions to initialize the MCU and those peripherals we are going to use:
In this particular case, we've set the CPU operating frequency as a function of the USB bus frequency.
USB controller and stack initialization
The USB controller initialization follows. We need to enable the USB GPIO pins, peripheral clock, and VBUS configuration for this board; we finally call TinyUSB 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
For more information on timers, check the timers tutorial.
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
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_driverand any extra data that it could need. This structure is usually provided by the driver and we just reference it; in this case, we'll see the internals later
- As we use a static IP address, specify
maskin network order. We don't provide a gateway as this interface is intended to only connect our device and the host
- Since we need to provide an IP address to the host, we enable our internal DHCP server.
Note that, we also need to specify a unique MAC address. For this example we chose a fancy unicast locally administered address.
MIP will run as part of Mongoose, it is a part of it. The USB controller will be handled by TinyUSB, providing callback functions to be called when it has received a frame; then we will push it to a queue, from where MIP will pick it up later.
Run Mongoose and TinyUSB
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:In this case we also call TinyUSB's handler.
The listener will call this function when it receives an HTTP request:
There we check the requested URL and either parse a JSON message or just reply "hi"
Under the hood
This subsection is only for those with enough curiosity or interested in writing their own driver for MIP. Feel free to skip ahead if this does not apply to you.
struct mip_driver provides pointers to driver functionality.
tx points to a function to be called when MIP needs to send a frame,
rx points to a function to be called when MIP is able to process a received frame, and
up points to a function returning the state of the interface:
To know whether the interface is up or not, MIP calls the function we configured, and we ask TinyUSB:
To send a frame, MIP calls the function we configured and we need to handle it to TinyUSB. If it can't be sent, we call its handler until it allows us to place a transmit request.
Due to the nature of USB and the way TinyUSB is written, the former is a blocking request for transmission; we'll be called back and instructed where to copy the data to be sent:
If a driver has to be polled for data, then it will also implement an
rx() function. Otherwise, if received data is asynchronous to MIP, Mongoose provides an internal lock-free queue and we can take advantage of it. Either the user (as in this example) or the driver code has to set the queue length to the required size, MIP will allocate the necessary memory for us.
The USB controller will be handled by TinyUSB, providing callback functions to be called when it has received a frame; then we will push it to the MIP queue by calling
mip_qwrite(). As MIP is a part of Mongoose, MIP will run on the next call to the event manager and then call the function pointed to by the
rx element in the driver structure. As can be seen, we set that to
mip_driver_rx, which is a conveniency function that calls
mip_qread() to get a frame from the queue and return it to MIP to be processed.
If you want to use multi-threading, just follow Mongoose documentation as usual and call all
mg_* API functions from the same RTOS task where Mongoose is running. The function
mip_qwrite(), however, can be called from any other context, so you could run TinyUSB in its own RTOS task if properly configured.
In order to create your own Mongoose-enabled application you have several ways:
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.
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 your preferred IDE), you can do the following:
- Add relevant project files to your project
.hfiles to your project
- Add Mongoose-specific configuration flags, see the Makefile
- Add the required preprocessor symbols:
- Provide a suitable time base for Mongoose and MIP
- Now write code similar to that in
main.c; for that you can read Mongoose documentation and follow our examples and tutorials