picowota/README.md

picowota - Raspberry Pi Pico W OTA bootloader

picowota, kinda sounds like you’re speaking Belter

This project implements a bootloader for the Raspberry Pi Pico W which allows upload of program code over WiFi (“Over The Air”).

The easiest way to use it is to include this repository as a submodule in the application which you want to be able to update over WiFi.

There’s an example project using picowota at https://github.com/usedbytes/picowota_blink

Using in your project

First add picowota as a submodule to your project:

git submodule add https://github.com/usedbytes/picowota
git submodule update --init picowota
git commit -m "Add picowota submodule"

Then modifiy your project’s CMakeLists.txt to include the picowota directory:

add_subdirectory(picowota)

picowota either connects to an existing WiFi network (by default) or creates one, in both cases with the given SSID and password.

You can either provide the following as environment variables, or set them as CMake variables:

PICOWOTA_WIFI_SSID # The WiFi network SSID
PICOWOTA_WIFI_PASS # The WiFi network password
PICOWOTA_WIFI_AP # Optional; 0 = connect to the network, 1 = create it

Then, you can either build just your standalone app binary (suitable for updating via picowota when it’s already on the Pico), or a combined binary which contains the bootloader and the app (suitable for flashing the first time):

picowota_build_standalone(my_executable_name)
picowota_build_combined(my_executable_name)

Note: The combined target will also build the standalone binary.

To be able to update your app, you must provide a way to return to the bootloader. By default, if GPIO15 is pulled low at boot time, then picowota will stay in bootloader mode, ready to receive new app code.

You can also return to the bootloader from your app code - for example when a button is pressed, or in response to some network request. The picowota_reboot library provides a picowota_reboot(bool to_bootloader) function, which your app can call to get back in to the bootloader.

CMakeLists.txt:

target_link_libraries(my_executable_name picowota_reboot)

your_c_code.c:

#include "picowota/reboot.h"

...

{

	...

	if (should_reboot_to_bootloader) {
		picowota_reboot(true);
	}

	...

}

Uploading code via picowota

Once you’ve got the picowota bootloader installed on your Pico, you can use the https://github.com/usedbytes/serial-flash tool to upload code to it.

As long as the Pico is “in” the picowota bootloader (i.e. because there’s no valid app code uploaded yet, or your app called picowota_reboot(true);), you can upload an app .elf file which was built by picowota_build_standalone():

If using the AP mode, the Pico’s IP address will be (at the time of writing) 192.168.4.1/24, and the connected device’s something in the same subnet. Otherwise it depends on your network settings.

(Assuming your Pico’s IP address is 192.168.1.123):

serial-flash tcp:192.168.1.123:4242 my_executable_name.elf

After uploading the code, if successful, the Pico will jump to the newly uploaded app.

How it works

This is derived from my Pico non-W bootloader, https://github.com/usedbytes/rp2040-serial-bootloader, which I wrote about in a blog post: https://blog.usedbytes.com/2021/12/pico-serial-bootloader/

The bootloader code attempts to avoid “bricking” by storing a CRC of the app code which gets uploaded. If the CRC doesn’t match, then the app won’t get run and the Pico will stay in picowota bootloader mode. This should make it fairly robust against errors in transfers etc.

Known issues

Bootloader/app size and cyw43 firmware

The WiFi chip on a Pico W needs firmware, which gets built in to any program you build with the Pico SDK. This is relatively large - 300-400 kB, which is why this bootloader is so large.

This gets duplicated in the picowota bootloader binary and also the app binary, which obviously uses up a significant chunk of the Pico’s 2 MB flash.

It would be nice to be able to avoid this duplication, but the Pico SDK libraries don’t give a mechanism to do so.

I’ve raised https://github.com/raspberrypi/pico-sdk/issues/928 for consideration.