Non-UF2 Installation

This installation page is only required if you do not have UF2 bootloader installed (e.g. boardBOOT drag-n-drop)! This page is for non-Express Feather M0's, Arduino Zero's & M0's, and other custom ATSAMD21 boards.

Flashing with Bossac - For Non-Express Feather M0's & Arduino Zero

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 Zero-compatible boards that use the ATSAMD21. 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.

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.

Download BOSSA

Once you have a firmware image you'll need to download the BOSSA tool, which that can load firmware on SAMD21 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.

 

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 versions 1.9 or later, you need to use --offset parameter on the command line.

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.

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 -e -w -v -R adafruit-circuitpython-boardname-version.bin

For example,

bossac -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 -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 -e -w -v -R --offset=0x4000 adafruit-circuitpython-feather_m4_express-3.0.0.bin

This will 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!

This guide was first published on Dec 19, 2017. It was last updated on Nov 14, 2018. This page (Non-UF2 Installation) was last updated on Sep 12, 2018.