USB Mass Storage

This guide is no longer up to date - please check out https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython for the introduction guide to installing CircuitPython on ATSAMD21 boards (and more!)

One great feature of the SAMD21 MicroPython port is that it exposes its internal filesystem as a USB mass storage device.  This means when you plug the board into a computer you should see a MICROPYTHON drive created, and inside you'll find all the files on the board's file system.  You can edit boot.py, main.py, and even read or write other files.

For reference the SAMD21 MicroPython port currently reserves 64 kilobytes of space total for the internal filesystem.  This is great for storing source code, frozen modules, and other small assets

Don't write files to the internal filesystem with Python's open & write functions while you are also accessing files with USB mass storage! There is currently the potential to corrupt the entire filesystem.

Mac OSX File Copy Issues

On Mac OSX you might run into issues copying files with simple drag and drop or even terminal cp commands.  The issue is that Mac OSX creates hidden files to store extended attributes, recycle bin files, etc. and those files can take up a significant amount of space--even filling the entire board's filesystem!  Luckily you can work around this issue by following these steps

First install the latest firmware on your board and ensure its filesystem is completely erased and in a basic starting point.

Next find the volume name for your board.  With the board plugged in run this command in a terminal to list all the volumes:

Download: file
ls -l /Volumes

Look for a volume with a name like MICROPYTHON (the default for SAMD21 MicroPython).  The full path to the volume is the /Volumes/MICROPYTHON path.

Now follow the steps from this question to run these terminal commands that stop hidden files from being created on the board:

Download: file
mdutil -i off /Volumes/MICROPYTHON
cd /Volumes/MICROPYTHON
rm -rf .{,_.}{fseventsd,Spotlight-V*,Trashes}
mkdir .fseventsd
touch .fseventsd/no_log .metadata_never_index .Trashes
cd -

Replace /Volumes/MICROPYTHON in the commands above with the full path to your board's volume if it's different.

Finally when you copy files or directories to the board you must use a special terminal command to do so.  Unfortunately you cannot use drag and drop copy in Finder because it will still create hidden extended attribute files in some cases (for files downloaded from the internet, like Adafruit's modules).  

To copy a file or folder use the -X option for the cp command.  For example to copy a foo.mpy file to the board use a command like:

Download: file
cp -X foo.mpy /Volumes/MICROPYTHON

Or to copy a folder and all of its child files/folders use a command like:

Download: file
cp -rX folder_to_copy /Volumes/MICROPYTHON
This guide was first published on Oct 17, 2016. It was last updated on Oct 17, 2016. This page (USB Mass Storage) was last updated on Oct 21, 2019.