Espressif Boards without UF2 Bootloaders
See this page for how to load a .bin file on an ESP32 or ESP32-C3 board.
STM Boards
See this page for how to upload a .bin file using the built-in STM bootloader.
The older Feather M0 boards don't come with UF2, instead they come with a simpler bootloader called bossa. This is also what is installed on Arduino Zero's and other CircuitPython compatible boards that use the ATSAMDx1 or nRF52840. It is the only method you can use if your CircuitPython installation file is a .bin rather than a .uf2
Command-Line ahoy!
Flashing with bossac requires the use of your computer's command line interface. On Windows, that's the cmd or powershell tool. On Mac and Linux, use Terminal!
Download Latest CircuitPython Firmware
The first thing you'll want to do is download the most recent version of CircuitPython.
Compatible boards have .bin files available for download on circuitpython.org.
Click the green button below to search for your board to find the appropriate file.
Once downloaded, save the .bin file onto your desktop, you'll need it soon!
If you are running Windows 7, you must install the driver set (it is covered on this page) so you have access to the COM port.
Download BOSSA
Once you have a firmware image you'll need to download the BOSSA tool, which that can load firmware on SAMD21/51 boards. This tool is actually used internally by the Arduino IDE when it programs these boards, however you can use it yourself to load custom firmware
Be aware you must use 1.7.0 or higher version of bossac to program SAMD21 and SAMD51 boards! Versions of BOSSA before version 1.7.0 won't work because it doesn't support the SAMD21/51 chips. Also note that bossac versions 1.9.0 and newer have incompatibly changed their command-line parameters, and can erase your bootloader if it is not protected. (Adafruit boards ship with protected bootloaders.) Follow the directions below carefully, depending on which version you have.
To flash with bossac
(BOSSA's command line tool) first download the latest version from here. The ming32
version is for Windows, apple-darwin
for Mac OSX and various linux
options for Linux.
bossac
works with .bin files only, it will not work with .uf2 files!
Test bossac
Open a terminal and navigate to the folder with the bossac
tool. Then check the tool runs by running it with the --help
option:
Open a terminal and navigate to the folder with the bossac
tool. Then check the tool runs by running it with the --help option with bossac --help
Or if you're using Linux or Mac OSX you'll need to add a ./ to specify that bossac is run from the current directory like ./bossac --help
Make sure you see BOSSA version 1.7.0 or higher! And see the warning below about version 1.9.0 and higher. If you see a lower version then you accidentally downloaded an older version of the tool and it won't work to flash SAMD21 chips. Go back and grab the latest release from this BOSSA GitHub repository as mentioned above.
Port Selection for Mac OS
You'll need to know what port to use if you're on a Mac.
In your same terminal window, run the command ls /dev/cu.*
. Note the ports listed, then plug in your board and run the command again. The device may be listed something like /dev/cu.usbmodem14301. Make note of the port name for the bossac
section below.
Get Into the Bootloader
You'll have to 'kick' the board into the bootloader manually. Do so by double-clicking the reset button. The red "#13" LED should pulse on and off. If you are using an Arduino Zero, make sure you are connected to the native USB port not the debugging/programming port.
One special note, if you're using the Arduino M0 from Arduino.org you'll need to replace its bootloader with the Arduino Zero bootloader so it can work with BOSSA. To do this install the Arduino/Genuino Zero board in the Arduino IDE board manager and then follow these steps to burn the Arduino Zero bootloader (using the programming port on the board). Once you've loaded the Arduino Zero bootloader you should be able to use the M0 with bossac as described below.
Run the bossac Command
With your board plugged in and running the bootloader you're ready to flash CircuitPython firmware onto the board. Copy the firmware .bin file to the same directory as the bossac
tool, then in a terminal navigate to that location and run one ofthe following commands, depending on which version of bossac
you have.
With bossac version 1.9 or later, you must give an --offset
parameter on the command line to specify where to start writing the firmware in flash memory. This parameter was added in bossac 1.8.0 with a default of 0x2000
, but starting in 1.9, the default offset was changed to 0x0000
, which is not what you want in most cases. If you omit the argument for bossac 1.9 or later, you will probably see a "Verify Failed" error from bossac, and you will damage the fuse settings on your board, rendering the bootloader inoperable. Remember to change the option for -p
or --port
to match the port on your machine.
Replace the filename below with the name of your downloaded .bin
: it will vary based on your board!
Using bossac Version 1.7.0
There is no --offset
parameter available. Use a command line like this:
MacOS
bossac -p /dev/cu.usbmodemxxx -e -w -v -R adafruit-circuitpython-boardname-version.bin
Linux
The port to use will vary, but will probably be /dev/ttyACM0
.
bossac -p /dev/ttyACMx -e -w -v -R adafruit-circuitpython-boardname-version.bin
Windows
The COM port you use will vary. Choose the one the for the board (see the Device Manager if necessary).
bossac -p COMx -e -w -v -R adafruit-circuitpython-boardname-version.bin
For example,
bossac -p /dev/cu.usbmodem14301 -e -w -v -R adafruit-circuitpython-feather_m0_express-3.0.0.bin
Using bossac Versions 1.8, and 1.9 or Later
For M0 (SAMD21) boards, which have an 8kB bootloader, you must specify --offset=0x2000
. Do not omit the --offset
parameter; you will brick your board if you omit it.
MacOS
bossac -p /dev/cu.usbmodemxxx -e -w -v -R --offset=0x2000 adafruit-circuitpython-boardname-version.bin
Linux
The port to use will vary, but will probably be /dev/ttyACM0
.
bossac -p /dev/ttyACMx -e -w -v -R --offset=0x2000 adafruit-circuitpython-boardname-version.bin
Windows
The COM port you use will vary. Choose the one the for the board (see the Device Manager if necessary).
bossac -p COMx -e -w -v -R --offset=0x2000 adafruit-circuitpython-boardname-version.bin
For example, on MacOS:
bossac -p /dev/cu.usbmodem14301 -e -w -v -R --offset=0x2000 adafruit-circuitpython-feather_m0_express-3.0.0.bin
For M4 (SAMD51) boards, which have a 16kB bootloader, you must specify -offset=0x4000
. Do not omit the
--offset
parameter; you will brick your board if you omit it.
MacOS
bossac -p /dev/cu.usbmodemxxx -e -w -v -R --offset=0x4000 adafruit-circuitpython-boardname-version.bin
Linux
The port to use will vary, but will probably be /dev/ttyACM0
.
bossac -p /dev/ttyACMx -e -w -v -R --offset=0x4000 adafruit-circuitpython-boardname-version.bin
Windows
The COM port you use will vary. Choose the one the for the board (see the Device Manager if necessary).
bossac -p COM5 -e -w -v -R --offset=0x4000 adafruit-circuitpython-boardname-version.bin
For example, on MacOS:
bossac -p /dev/cu.usbmodem14301 -e -w -v -R --offset=0x4000 adafruit-circuitpython-feather_m4_express-3.0.0.bin
This will e
rase the chip, w
rite the given file, v
erify the write and R
eset the board. On Linux or MacOS you may need to run this command with sudo ./bossac ...
, or add yourself to the dialout group first.
After bossac loads the firmware you should see output similar to the following:
After reset, CircuitPython should be running and the CIRCUITPY drive will appear. You can always manually reset the board by clicking the reset button, sometimes that is needed to get it to 'wake up'. Express boards may cause a warning of an early eject of a USB drive but just ignore it. Nothing important was being written to the drive!
Page last edited June 21, 2024
Text editor powered by tinymce.