Skip to content

CircuitPython 11 Alpha Tutorial: Install and Test the New Firmware

CircuitPython 11.0.0-alpha.1 adds new cryptography, RP2350 alarm, USB, import, and firmware changes. Learn how to install and test it safely on a supported board.

CircuitPython 11 Alpha Tutorial: Install and Test the New Firmware

On this page

CircuitPython 11.0.0-alpha.1 arrived on September 24, 2026, and it changes enough under the hood to make testing worthwhile for developers working with supported microcontroller boards. The release adds architecture-specific .mpy imports, new hmac and hardwarekey modules, isochronous USB input support, RP2350 alarms, firmware-size reductions, and Zephyr dynamic pin assignment. This tutorial shows how to install the alpha safely, check that it is running, and test one of the changes without treating an unfinished release like a production firmware. 

Check whether CircuitPython 11 is appropriate for your board

CircuitPython 11.0.0-alpha.1 is a development release, so the first step is to identify the exact board rather than simply downloading the newest file. CircuitPython publishes board-specific firmware, and the download pages identify whether a particular board has a UF2 or BIN build and which release is available. The current release supports stable ports including Raspberry Pi RP2040 and RP2350, Nordic nRF52840 and nRF52833, several Espressif chips, SAMD families, and STM32F4, while several other ports remain alpha.

There is another reason to check first: CircuitPython 11 removes the broadcom, litex, and renode ports. If your existing project depends on one of those ports, upgrading is not simply a firmware refresh. The project notes explicitly list those removals as incompatibilities when moving from the 10.x series to 11.0.0. 

Use a test board if possible. Alpha releases are unfinished and can contain bugs or behavior that changes before the final release. Keep a known-working stable firmware file so you can restore the board if your existing program stops behaving as expected. Board-specific CircuitPython pages also distinguish development releases from stable releases for this reason. 

Download the correct CircuitPython 11 firmware

Open the CircuitPython downloads list and search for your exact board model. The important detail is not just the board family but the actual board entry, because two boards using similar microcontrollers can have different firmware builds, bootloaders, peripherals, or memory layouts. The CircuitPython download system currently lists hundreds of supported boards and provides the appropriate release files from each board page. 

Once you have opened your board's page, select CircuitPython 11.0.0-alpha.1 rather than assuming that the first download shown is the development build. Some boards provide a .uf2 file, while others provide a .bin file or both. The installation method depends on that file type, so keep the downloaded file available before connecting the board. 

Put a UF2 board into its bootloader

For boards using UF2, the normal installation process is deliberately simple. CircuitPython's installation guide explains that most compatible boards ship with a UF2 bootloader, which is the small piece of firmware that lets the computer receive a new firmware image through USB. Connect the board with a known-good USB data cable, put it into bootloader mode using its reset control or the board-specific procedure, and wait for the bootloader drive to appear on your computer.

With the bootloader drive visible, copy the downloaded CircuitPython 11 .uf2 file to it. The board normally resets and returns as a CircuitPython device after the firmware is written. If the drive never appears, do not keep copying the file repeatedly; check the board's specific bootloader instructions first, because the reset sequence differs between hardware families. 

Use the board-specific method when the firmware is a BIN file

Not every CircuitPython board uses UF2. Some boards expose a different bootloader and require a binary firmware image to be flashed with a board-specific tool. CircuitPython's installation documentation separates these non-UF2 procedures from the normal drag-and-drop workflow, and warns that tools and offsets differ between microcontroller families. For example, the documentation describes BOSSA-based installation for certain older SAMD boards and explicitly warns that incompatible BOSSA versions can cause problems.

This is why converting a BIN installation into a generic UF2 procedure is a bad shortcut. Follow the installation method attached to your board rather than a guide written for another model. Once the board has rebooted, continue with verification before copying your application files back onto it.

Verify that CircuitPython 11 is actually running

After the firmware installation, connect to the board's serial connection and open the CircuitPython read-eval-print loop, commonly called the REPL. The official release instructions recommend using the CircuitPython web editor or Mu editor for creating and editing programs and accessing the serial connection. A working REPL gives you the first useful confirmation that the firmware booted and that your computer can communicate with the board. 

You can also inspect the running version from the REPL with sys.implementation. For example, enter:

import sys
print(sys.implementation)

The exact representation can vary by release, but it should identify the CircuitPython implementation and version information. You can then check that the modules you intend to test are present. This is more useful than checking only the filename you downloaded because it confirms the board actually booted the new firmware.

Test the new architecture-specific import behavior

One of the changes in CircuitPython 11 affects how Python modules compiled into .mpy files are selected. An .mpy file can contain precompiled MicroPython or CircuitPython bytecode, and the new import behavior can now look for an architecture-specific filename between the ordinary Python file and the generic .mpy file. The release notes give the order as the normal .py file, then the architecture-specific .mpy, then the generic .mpy. 

You do not need to rewrite an existing application just to benefit from this behavior. It matters most when you distribute compiled modules that contain native machine code tied to a particular processor architecture. CircuitPython 11 also exposes the detailed processor architecture through microcontroller.cpu.architecture, which gives code a way to identify the architecture it is running on. 

import microcontroller

print(microcontroller.cpu.architecture)

Run that on your board and record the returned architecture string. This is a small test, but it demonstrates the underlying reason for the new import behavior: compiled code can be selected according to the processor architecture instead of relying entirely on one generic binary representation.

Test the new HMAC support on a supported board

CircuitPython 11 adds an hmac module backed by PSA cryptography, but the release notes currently identify its implementation as available on Espressif hardware. HMAC, or keyed-hash message authentication code, lets software calculate a cryptographic authentication value from a message and a secret key. It is useful when a device needs to verify that data came from a party holding the same secret without exposing that secret in the message itself. ([Adafruit][1])

If your board exposes the new module, you can perform a basic functional check from the REPL:

import hmac
print(hmac)

A successful import confirms that the module is present in that particular firmware build. Do not interpret that test as a complete security validation, however. The alpha release is introducing the module and its hardware-backed key functionality, but a real application still needs an appropriate key-management design, message format, replay protection where necessary, and careful handling of secrets.

Check the hardwarekey module separately

The companion hardwarekey module is designed for situations where cryptographic key material can be used without exposing the underlying value directly to application code. CircuitPython's release notes say it is currently implemented on Espressif, alongside the new HMAC support. That makes it particularly relevant to developers experimenting with device authentication rather than simply adding another general-purpose Python module. ([Adafruit][1])

For an initial test, check whether the module can be imported on your supported board. If it is present, move on to the board-specific documentation before building an application around it. Hardware-backed cryptography depends on the capabilities and configuration of the underlying microcontroller, so the presence of a module alone does not mean every board offers identical protection.

Test RP2350 alarms if you have a Raspberry Pi Pico 2-class board

CircuitPython 11 adds an alarm implementation for the RP2350, including time and pin alarms as well as light and deep sleep support. The practical difference is that a compatible RP2350 project can use the firmware's alarm mechanisms to wake from a low-power state or respond to an external event rather than continuously running application code. The release notes also identify an update to Pico SDK 2.3.1 as part of the RP2xxx changes. ([Adafruit][1])

This is a feature worth testing independently from the rest of an application. Start with the simplest supported alarm example from the CircuitPython documentation for your board, confirm that the board enters the intended sleep state, and then verify that it wakes on the selected event. If you are measuring battery life, compare the behavior with your existing CircuitPython 10 firmware rather than assuming that a successful wake automatically represents a power-consumption improvement.

Check whether your libraries still work

The CircuitPython 11 alpha release says that libraries from the 10.x bundles remain compatible with CircuitPython 11. That is useful for existing projects because you do not necessarily need to replace an entire library collection before trying the new firmware. Compatibility does not remove the need to test, though, particularly when a library depends on a board-specific module, native machine-code file, or behavior that changed between releases. ([Adafruit][1])

A sensible migration test is to copy your application's library folder to a separate test board or backup directory, start with the smallest program that imports the libraries, and then restore the full application. If an import fails, test the missing module independently before changing several dependencies at once. This makes it much easier to tell whether the problem comes from CircuitPython 11 itself, a library version, or board-specific support.

Know what changed before moving a real project

The biggest mistake with an alpha firmware is treating every successful boot as evidence that an existing project is ready to migrate. CircuitPython 11 is planned to become the next stable release after the 10.3.x series, but the current build is explicitly an alpha and further features, fixes, and changes are expected before the final release. The project also says that additional 10.3.x releases may still be produced for critical fixes if necessary. ([Adafruit][1])

For a useful test, record three things: whether your board boots, whether your existing application runs, and whether the new feature you care about behaves as documented. If all three pass, keep the test environment separate and continue testing after each alpha update. That gives you a clean comparison point when CircuitPython 11 moves toward beta and eventually a stable release.

Copy this post

0 Comments

No comments yet. Be the first to share your thoughts.

Join the conversation

Log in or create a free account to leave a comment. You can edit or delete your own comments any time.