This guide is no longer up to date - please check out for the introduction guide to CircuitPython on ATSAMD21 boards (and more!)
There's newer information about building CircuitPython in the Building CircuitPython Learn Guide:

If you'd like to build the SAMD21 MicroPython firmware yourself you can use a special Vagrant-based virtual machine to simplify the build process.  Note that you don't have to build the firmware yourself, you can download a prebuilt image and flash it as mentioned on the previous page.  Building the firmware yourself is useful for modifying and working on the firmware code.

This isnt required if you're just using our release binaries! It's for people who want to build their very own releases.

For some background information skim the ESP8266 MicroPython firmware build guide to see more details on Vagrant and VirtualBox usage.  The SAMD21 MicroPython build VM is very similar to the ESP8266 build VM.

First install VirtualBox on your computer.  If you already have VirtualBox installed it can't hurt to upgrade to the latest version.  Virtualbox is an open source and no cost virtualization tool that can run a guest operating system 'inside' your host operating system.

Next install Vagrant on your computer.  Again if you already have Vagrant installed be sure to upgrade to the latest version.  In most cases Vagrant needs the latest version of VirtualBox installed so if you install one tool be sure to install or upgrade the other too.  Vagrant is an open source and no cost tool that simplifies using VirtualBox with a simple command line interface.

Now you'll need git installed on your computer, then open a command terminal (on Windows run the Git Bash terminal to make sure you can run git commands) and clone the SAMD21 MicroPython Vagrant configuration repository by running:

git clone

Then change into the atmel-samd-micropython-vagrant directory by running:

cd atmel-samd-micropython-vagrant

Inside this directory is a text file called Vagrantfile.  This file is the configuration for the virtual machine and also is the location where all vagrant commands should be run.  In the following sections you'll see how to start up, stop, and enter the virtual machine.  Make sure you're inside this atmel-samd-micropython-vagrant directory with the Vagrantfile before running vagrant commands.

Start Virtual Machine

To start the virtual machine you'll use the vagrant up command:

vagrant up

The very first time this command runs it will provision the virtual machine by downloading a Linux operating system image and install tools & SAMD21 MicroPython firmware inside it.  This process can take some time, perhaps 30 minutes or more, during the first run.  Luckily the operating system image is saved on your computer so future starts of the VM will be very quick (a few seconds).

Once the virtual machine is running you should see output like the following that tells you to run vagrant ssh to enter the machine:

Enter Virtual Machine

With the virtual machine running use the vagrant ssh command to enter its command line terminal:

vagrant ssh

You should see an Ubuntu Linux prompt after a few moments:

Inside the VM you can build SAMD21 MicroPython firmware and even use BOSSA to flash it to a board.  For the next sections you'll want to be inside the VM as shown above.

If you'd like to leave the VM run the exit command at the Linux terminal.  This will exit from the VM's ssh session but note the VM will continue to run in the background!  Skip down to the stop virtual machine section to see how to stop the VM from running.

If you need to enter the running VM again just use the vagrant ssh command again.

Build Firmware

To build the SAMD21 MicroPython firmware you just need to go its source directory and use the make command.  First change to the SAMD21 MicroPython source directory by running this command in the VM:

cd ~/source/circuitpython/

Next you'll need to build the mpy-cross tool by running this command:

make -C mpy-cross/

You should see the mpy-cross tool successfully build and finish with output like:

You only need to build the mpy-cross tool once, then you can just focus on building the SAMD21 MicroPython firmware.

Now to build the SAMD21 MicroPython firmware first change to its directory (the atmel-samd directory) by running:

cd ~/source/circuitpython/atmel-samd

Before you can build the firmware you need to pick the right board that you're using.  You can list the supported boards by listing all the subdirectories of the boards directory:

ls -l boards

Each of the subdirectory names (in blue) are supported boards, like arduino_zero or feather_m0_basic:

Note that the feather_m0_basic board can be used with any Feather M0 board, including the Feather M0 AdaLogger, Feather M0 Bluefruit, etc.  Not all of the extra peripherals on these boards, like Bluetooth LE radios, etc., have MicroPython support however!

Now to build the firmware for a board use the make command like:

make BOARD=feather_m0_basic

The BOARD=... parameter is what tells the build system which board's firmware you want to build.  Make sure to specify the board name (subdirectory of the boards folder) exactly!

The firmware should build without error and finish with output similar to the following:

If you do see the build fail with an error you might check the GitHub issues for the code to see if there's a known issue with the build.

Once the firmware is built it will be placed in a build-BOARD_NAME directory, where BOARD_NAME Is the name of the board that was built.  For example the feather_m0_basic board will have its firmware in the build-feather_m0_basic directory.  Inside the build directory will be temporary files used during the compilation, and most importantly a firmware.bin file which contains the compiled firmware.

To load this firmware.bin on a board you can copy it out of the Vagrant VM and use BOSSA as described on the previous page.  To copy out the file from the VM simply copy it to the /vagrant folder.  This will place the file on your host PC (i.e. the machine running the VM) so that you can access it from BOSSA and other tools.  For example run the following command to copy out the built Feather M0 firmware:

cp build-feather_m0_basic/firmware.bin /vagrant

Now exit the VM (using the exit command) and you'll find the firmware.bin file in the vagrant subdirectory (under the directory with the Vagrantfile--note this is slightly different than the default Vagrant behavior to copy files into the same directory as the Vagrantfile).

If you're using a Feather M0 board you can actually flash the firmware using BOSSA directly inside the VM.  Back inside the VM and with the board connected to your host computer 'double click' the reset button to force the bootloader to run (pin #13 red LED starts fading up and down).  Once a Feather M0 is running its bootloader the Vagrant VM should 'capture' it and make it available to the VM instead of the host computer.  You should see a /dev/ttyACM0 device if you run the following command:

ls -l /dev/ttyACM*

BOSSA is already built and installed in the path of the VM so it can be run from anywhere.  To flash the newly built firmware simply run:

sudo bossac -e -w -v -R -p ttyACM0 build-feather_m0_basic/firmware.bin

Change the build-BOARD_NAME directory to the right name for the firmware you built.

You should see BOSSA flash the firmware successfully:

However if you run into trouble try copying the firmware out of the VM and using BOSSA from your host machine.

Remember when the VM is running it will 'capture' any Feather M0 it sees running the bootloader!  This means your host PC won't see Feather M0 boards and you can't run BOSSA against them.  Simply stop the VM (see section below) and try connecting the board again to prevent this capture.

Stop Virtual Machine

To shut down the virtual machine first run the exit command to leave it if you're still inside.  Then from the same directory as the Vagrantfile run the following command:

vagrant halt

After a moment you should see the VM is shutdown:

To start the VM again once it's stopped just use the vagrant up command again.

Sync & Edit Source

If you'd like to edit the source code inside the VM you might want to enable a syncronization of source files between the VM and host machine.  By syncing the source files you can use any text editor on your host machine to edit them instead of using a basic text editor inside the VM.  This sync feature is disabled by default because it depends on what operating system you're using on the host machine (the default sync system Vagrant uses tends to cause slowdowns with many files like in the MicroPython source so a more optimized but platform-specific sync is necessary).

If you're using Linux or Mac OSX you can use NFS to sync source files between the machines.  First read the Vagrant NFS documentation and make sure you system supports NFS (you might need to install some depenedencies depending on your distribution).  Exit and stop the VM, then edit the Vagrantfile and find this commented line:

# Optionally share the /home/vagrant/source directory with NFS (only for Mac
# and Linux host machines, for Windows try SMB below).
#config.vm.synced_folder "./source", "/home/vagrant/source", type: "nfs", create: true

Uncomment the last line which defines a synced folder using NFS.  The lines should look like:

# Optionally share the /home/vagrant/source directory with NFS (only for Mac
# and Linux host machines, for Windows try SMB below).
config.vm.synced_folder "./source", "/home/vagrant/source", type: "nfs", create: true

Save the file and skip past the Windows instructions below to continue.

If you're using Windows you'll instead need to use SMB shares to sync source between the machines.  First read the Vagrant SMB documentation and note that you must run vagrant commands from inside a terminal that has administrator privileges.  Exit and stop the VM, then edit the Vagrantfile and find this commented line:

# Optionally share the /home/vagrant/source directory with SMB (only for Windows
# host machines, for Mac OSX or Linux try NFS above).
#config.vm.synced_folder "./source", "/home/vagrant/source", type: "smb", create: true

Uncomment the last line which defines a synced folder using SMB.  The lines should look like:

# Optionally share the /home/vagrant/source directory with SMB (only for Windows
# host machines, for Mac OSX or Linux try NFS above).
config.vm.synced_folder "./source", "/home/vagrant/source", type: "smb", create: true

Save the file to continue setting up the synchronization.

After editing the Vagrantfile start the VM again (vagrant up).  During the startup you might need to enter your administrator password so Vagrant can configure the NFS shares on Mac OSX or Linux.  On Windows remember you'll need to be running in an administrator terminal to use SMB shares!  If you run into issues check the Vagrant NFS share or Vagrant SMB share documentation.

Once the VM is running it will syncronize the SAMD21 MicroPython source code between the /home/vagrant/source/ folder inside the VM and the source subdirectory under the Vagrantfile location on the host machine.  You can use a text editor to modify the files in the source directory and they'll be changed inside the VM.  Build the firmware in the VM and load it on your board to have a quick and easy development process!

This guide was first published on Oct 17, 2016. It was last updated on Mar 08, 2024.

This page (Build Firmware) was last updated on Mar 08, 2024.

Text editor powered by tinymce.