Raspberry Pi Pico

Overview

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 a Raspberry Pico 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 linked to their location in the repository. The full source code for this project is at https://github.com/cesanta/mongoose/tree/master/examples/rp2040/pico-rndis-dashboard

This example uses the Pico-SDK and compiles with its standard toolchain:

  • main.c: here we do our main job, initializing Mongoose, providing an interface with TinyUSB, initializing the network, and calling the event manager
  • mongoose.c - a symlink to repo's mongose.c, the Mongoose Library source code
  • mongoose.h - a symlink to repo's mongose.h, the Mongoose Library header file
  • net.c - a symlink to the common code for this example, net.c
  • packed_fs.c - a symlink to the packed filesystem in the common code section, containing the web files to be served, packed_fs.c
  • CMakeLists.txt - A cmake file that selects the source files and compilation options
  • Makefile - mainly pulls the SDK from its Github repo and calls cmake

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 and copy it to the Pico board (see below)
  • The firmware initializes the USB stack
  • After initialization, the application starts Mongoose's event loop and blinks the LED
  • Once the LED starts blinking, the example is ready
  • 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: 192.168.3.2
  • Open your web browser and connect to the board IP address (192.168.3.1), you should see a nice device dashboard

Build and run

  • It is assumed you're using Linux or Mac as a workstation and you have cmake and make installed

  • 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/rp2040/pico-rndis-dashboard
    $ make build
    
  • Once the build succeeds, boot your Pico in USB Mass Storage Mode by holding down the BOOTSEL button while you plug it into the USB port. Once it is connected, then release the BOOTSEL button. It should automatically mount as a new USB disk in your machine. Now either manually copy or drag and drop the generated build/firmware.uf2 file into this new USB disk device.

  • The Pico will flash this code and reboot, unmounting this disk and running the flashed code.

    • On a Linux host, you'll see something like this in the system log (dmesg -w):
      [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:pic
    • On Windows, RNDIS:pic
  • Now start a browser on 192.168.3.1. You should see a login screen.

  • NOTE: USB stdio in the Pico-SDK is done in background with TinyUSB and an interrupt to hide it from the user and periodically call tusb_task(). When we use TinyUSB, that code is removed from the compilation list; so this example uses UART stdio (UART 0) to keep things simple and focused on the RNDIS example. If you want to see the console output, connect an USB-to-UART or a low-voltage-TTL-to-RS-232 adapter to GPIO0

  • 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

Mongoose detects it is being compiled for an RP2040 architecture, so it will configure itself to call the proper SDK functions it needs, for example for its time base in milliseconds.

This example can be divided in the following blocks:

  1. TinyUSB integration for this environment
  2. Initialize the microcontroller for this particular board
  3. Initialize the USB controller and stack
  4. Initialize Mongoose
  5. Initialize the networking stack
  6. Run Mongoose and TinyUSB
  7. Under the hood: interfacing MIP to TinyUSB, driver internals

TinyUSB integration

In the Makefile, we clone the Pico-SDK repository at a stable branch, and TinyUSB is a submodule in it; in fact, it has been already integrated, though not for this particular application.

Then we set the proper paths for include files and required code:

  • pico-sdk/lib/tinyusb/lib/networking: headers and code. We cherry picked the necessary files from this subtree, see CMakeLists.txt
  • usb_descriptors.c: definitions and code to present the required descriptors for the classes in use
  • tusb_config.h: enable the required classes, the rest of the job has been done inside the SDK

USB controller interrupts are already routed to the TinyUSB handler by the SDK. But, 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

We call SDK functions to initialize the MCU, stdio, and those peripherals we are going to use:

USB controller and stack initialization

The USB controller will be initialized by the SDK. We just need to call the TinyUSB initialization function:

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 LED

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 CMakeLists.txt file by defining MG_ENABLE_MIP=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. 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 ip and mask in 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.

We have covered those aspects that are specific to the RP2040 implementation, for the details on the application and the UI, please see the device dashboard tutorial.

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.

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

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.

  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 your preferred IDE), you can do the following:

    • Add relevant 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_ENABLE_MIP=1
    • Now write code similar to that in main.c; for that you can read Mongoose documentation and follow our examples and tutorials