CircuitPython libraries work in the same was.
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? that you aren't using anymore or test code that isn't in use.:
ls -l /Volumes
ls :
cp -X foo.mpy /Volumes/CIRCUITPY
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
cp -rX folder_to_copy /Volumes/CIRCUITPY
Other Mac OSX! Lets continue!
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.