Create a custom UF2 file for Easy CircuitPython Flashing – Embedded Computing Design

June 23, 2023

Blogs

CircuitPython is a programming language used on a wide variety of development boards and microcontrollers. This includes the Raspberry Pi Pico, which I use extensively for demos in the Developing with Pi webinar series. While the RP2040-based Pico can be used with Arduino C and the Arduino IDE, what’s interesting about CircuitPython in this context isn’t so much the language itself as the programming process.

Arduino C is a compiled language, which means that the compiler on your computer takes your instructions and transforms them into a format that the microcontroller/development board can use. CircuitPython is an interpreted language, which means that the processor running things takes your written code and translates it line-by-line into usable information without any initial compilation process. Partly as a consequence of this paradigm, you can open code on a CircuitPython board with a regular text editor, save it, and it will simply start executing the new code.

An important caveat to doing things this way is that a CircuitPython board must first be configured to run such code by copying the appropriate UF2 file to it. This UF2 (aka USB Flashing Format) file will typically configure the IO pins for a given development board, so a UF2 made for one device probably won’t work for another (e.g. a Raspberry Pi Pico UF2, most likely won’t work with a Adafruit KB2040 Kee Boar). If you need to access external libraries and/or support files, such as images or sounds, they must be loaded separately.

This works well enough for prototyping, but quickly becomes unwieldy if you need to create multiple X widgets. Fortunately, you can create a custom UF2 file for your board and its current configuration can be copied/pasted into your development board in one step . Compiled would be the wrong term here, though perhaps “bundled” would be appropriate.

To create a custom UF2, install the picotool software tool. The setup process varies from computer to computer, and the following is based on a macOS installation. I used the previously installed Homebrew package manager to add picotool to my computer following these instructions, which worked perfectly.

Set up your development board exactly as you would like it to be duplicated, including any additional libraries and/or files. Restart your RP2040 in BOOTSEL mode; for Pico, hold the button while you plug it in. Enter the following on the command line:

picotool save –all full_duplicated_board.uf2

This will save your board as a UF2 file in your home directory as “full_duplicated_board.uf2”. This can then be copied to a new device plugged into your computer. Copy, paste and wait for the process to complete. Your new card will have all the software properties of the original.

Caption: Flash code found on Adafruit

Image credit: Jeremy Cook

If you’re making 100 x widgets, you’ll want an automatic guarantee that the copy/paste process worked correctly. You could hop into the file system to check, but a better method might be to flash it one or more times to let you know it’s being scheduled.

To speed things up even more, it’s likely that you can flash CircuitPython to a Pico or other RP2040-based board using the SWD pins. However, this Xenon board setup is the only example of CircuitPython SWD flashing that I’ve seen. In addition to showing the process, he also illustrated that the CircuitPython and UF2 files aren’t just for RP2040; the Xenon used the Nordic nRF52840 SOC for processing.

Once the UF2 has been updated, a text editor will nominally work for making code changes to code.py or other files. Support files can be dragged and dropped as needed. On the other hand, an IDE like Mu is good for debugging code and provides a serial monitor, hence You may prefer to use it or other tools. However, if your target end user is comfortable copying files and/or opening a text editor but prefers not to install a new IDE to make a simple change or two, CircuitPython may be a good fit for this scenario.

Custom UF2 flashing significantly speeds up RP2040 setup time compared to performing several single copy/paste/flash passes. While you may not want to plug and flash a few thousand individual boards, if you need to make a handful of copies, a custom UF2 plug-and-drag process may be the perfect solution.