Our 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
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!
The first thing you'll want to do is download the most recent version of CircuitPython.
As of April, 2019, there are two sites to download the appropriate .bin file. Adafruit is migrating files to CircuitPython.org. It is suggested to look for the .bin file for your compatible board there first by searching for the board. Only compatible boards that have a pull request for the appropriate pin definition files will be listed on that site, developers should submit their materials to be included if they have a new CircuitPython board they would like to see listed.
Click the green button below to search for your board to find the appropriate file.
Alternatively, use GitHub
For now, CircuitPython board files are also in the Adafruit CircuitPython GitHub repo, although they may migrate to a dedicated CircuitPython repo in the future. If you have issues with CircuitPython.org, look to download from GitHub using this second green button below.
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 (we cover it on this page) so you have access to the COM port.
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
Open a terminal and navigate to the folder with the
bossac tool. Then check the tool runs by running it with the
Open a terminal and navigate to the folder with the
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
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.
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.
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. Remember to change the option for
--port to match the port on your Mac.
Replace the filename below with the name of your downloaded
.bin: it will vary based on your board!
Using bossac Versions 1.7.0, 1.8
There is no
--offset parameter available. Use a command line like this:
bossac -p=/dev/cu.usbmodem14301 -e -w -v -R adafruit-circuitpython-boardname-version.bin
bossac -p=/dev/cu.usbmodem14301 -e -w -v -R adafruit-circuitpython-feather_m0_express-3.0.0.bin
Using bossac Versions 1.9 or Later
For M0 boards, which have an 8kB bootloader, you must specify
-offset=0x2000, for example:
bossac -p=/dev/cu.usbmodem14301 -e -w -v -R --offset=0x2000 adafruit-circuitpython-feather_m0_express-3.0.0.bin
For M4 boards, which have a 16kB bootloader, you must specify
-offset=0x4000, for example:
bossac -p=/dev/cu.usbmodem14301 -e -w -v -R --offset=0x4000 adafruit-circuitpython-feather_m4_express-3.0.0.bin
erase the chip,
write the given file,
verify the write and
Reset 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 BOSSA 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!