About CircuitPython Libraries

Part of what makes CircuitPython so awesome is its ability to store code separately from the firmware itself. Storing code separately from the firmware makes it easier to update both the code you write and the libraries you depend. So, instead of compiling libraries in, you simply place them into your lib directory on the CIRCUITPY drive.

Your board may ship with a lib folder already, its in the base directory of the drive. If not, simply create the folder yourself.

CircuitPython libraries work in the same was as regular Python modules so the Python docs are a great reference for how it all should work. In Python terms, we can place our library files in the lib directory because its part of the Python path by default.

One downside of this approach of separate libraries is that they are not built in. To use them, one needs to copy them to the CIRCUITPY drive before they can be used. Fortunately, we provide a bundle full of our libraries.

Our bundle and releases also feature optimized versions of the libraries with the .mpy file extension. These files take less space on the drive and have a smaller memory footprint as they are loaded.

Installing the bundle

We're constantly updating and improving our libraries, so we don't (at this time) ship our CircuitPython boards with the full library bundle. Instead, you may find example code that depends on (import) libraries. Some of these libraries may be available from us at Adafruit, some may be written by community members!

Either way, once you get past the most basic blink scripts, you'll want to know how to get libraries on board. So, lets take a look at this silly example below which uses a SI7021 I2C temperature sensor.

import adafruit_si7021
import busio
import board

i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_si7021.SI7021(i2c)
print("Temperature:", sensor.temperature)
print("Humidity:", sensor.relative_humidity)

After saving that as code.py on the drive we see the status NeoPixel flashes that an error has occurred. Opening up the serial console we see that an ImportError has occurred.

It says that no module exists named adafruit_si7021. Thats the library we need to download! Since we bought the sensor from Adafruit its likely there is a library for in the official Adafruit bundle. If its not an Adafruit part or its missing, we can also check the Community bundle which has libraries contributed by the community.

Visiting the bundle release page will show us information on the latest release including a list of all the versions of the included drivers. Scrolling to the bottom of the page will reveal the downloads. We'll download the first zip file which starts with adafruit-circuitpython-bundle.

After downloading the zip, extract its contents. This is usually done by double clicking on the zip. On Mac OSX as I'm using, it places the file in the same directory as the zip. I usually sort my Downloads by file data so the lib directory that was contained in the zip ends up next to the zip file.

Express Boards

If you are using a Feather M0 Express, Metro M0 Express or Circuit Playground Express (e.g. "Express" board) your CircuitPython board comes with 2 MB of Flash storage. This is plenty of space for all of our library files so we recommend you just install them all! (If you have a Gemma M0 or Trinket M0 or other non-Express board, skip down to the next section)

On Express boards, the lib directory can be copied directly to the CIRCUITPY drive.

Just drag the entire lib folder into the CIRCUITPY drive, and 'replace' any old files if your operating system prompts you

You're done! You can go back to coding your project :) The rest of this page is for non-Express boards

Non-Express Boards

If you have a Gemma M0 or Trinket M0, your internal storage is from the chip itself. So, this board doesn't have enough space for all of the libraries. If you try to copy over the entire lib folder you'll overwhelm your store.

Instead, we'll copy over just what we need as we need it. In the lib folder there is an adafruit_si7021.mpy file. That matches the missing module! Python imports modules based on the filename so they will always match up. Lets drag it over. If this works, skip to the next section. Keep reading if you have an error.

Non-Express boards - Out of space?

The file system on the board is very tiny. (Smaller than an ancient floppy disk.) So, its likely you'll run out of space but don't panic! There are a couple ways to free up space.

The board ships with the Windows 7 serial driver too! Feel free to delete that if you don't need it or have already installed it. Its ~12KiB or so.

Delete something!

The simplest way of freeing up space is to delete files from the drive. Perhaps there are libraries in the lib that you aren't using anymore or test code that isn't in use.

Use tabs

One unique feature of Python is that the indentation of code matters. Usually the recommendation is to indent code with four spaces for every indent. In general, we recommend that too. However, one trick to storing more human-readable code is to use a single tab character for indentation. This approach uses 1/4 of the space for indentation and can be significant when we're counting bytes.

Mac OSX loves to add extra files.

Luckily you can disable some of the extra hidden files that Mac OSX adds by running a few commands to disable search indexing and create zero byte placeholders. Follow the steps below to maximize the amount of space available on OSX:

Prevent & Remove Mac OSX Hidden Files

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

ls -l /Volumes

Look for a volume with a name like CIRCUITPY (the default for CircuitPython).  The full path to the volume is the /Volumes/CIRCUITPY path.

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

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

Replace /Volumes/CIRCUITPY in the commands above with the full path to your board's volume if it's different.  At this point all the hidden files should be cleared from the board and some hidden files will be prevented from being created.

However there are still some cases where hidden files will be created by Mac OSX.  In particular if you copy a file that was downloaded from the internet it will have special metadata that Mac OSX stores as a hidden file.  Luckily you can run a copy command from the terminal to copy files without this hidden metadata file.  See the steps below:

Copy Files on Mac OSX Without Creating Hidden Files

Once you've disabled and removed hidden files with the above commands on Mac OSX you need to be careful to copy files to the board with a special command that prevents future hidden files from being created.  Unfortunately you cannot use drag and drop copy in Finder because it will still create these 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 in a terminal.  For example to copy a foo.mpy file to the board use a command like:

cp -X foo.mpy /Volumes/CIRCUITPY

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

cp -rX folder_to_copy /Volumes/CIRCUITPY

Other Mac OSX Tips

If you'd like to see the amount of space used on the drive and manually delete hidden files here's how to do so.  First list the amount of space used on the CIRCUITPY drive with the df command:

Lets remove the ._ files first.

Whoa! We have 13Ki more than before! Lets continue!

Continuing after copy

Woohoo! Everything copied over just fine. Lets check the serial terminal to see how things are going.

Oops! Another ImportError! Libraries can depend on other libraries so copying one file over may not be enough. Looking in the bundle, there is an adafruit_bus_device directory. In Python terms this is a package. It contains module files. Lets copy the folder over to make sure we get everything.

If that fails due to out of space, see above. If not, continue on.

Lets check the serial connection again. Looks like it worked! We don't have any more ImportErrors and we can see the temperature (in Celsius) and the relative humidity.

Last updated on 2017-12-11 at 06.24.47 PM Published on 2017-08-23 at 05.57.02 PM