Are you new to using CircuitPython? No worries, there is a full getting started guide here.

Adafruit suggests using the Mu editor to edit your code and have an interactive REPL in CircuitPython. You can learn about Mu and installation in this tutorial.

Preparing your SD card

If you bought an SD card, chances are it's already pre-formatted with a FAT filesystem. However you may have problems with how the factory formats the card, or if it's an old card it needs to be reformatted. CircuitPython supports both FAT16 and FAT32 filesystems.

It's always good idea to format the card before using, even if it's new! Note that formatting will erase the card, so save anything you want first.

The official SD formatter is available from https://www.sdcard.org/downloads/formatter/

Download it and run it on your computer, there's also a manual linked from that page for additional instructions.

General Steps for Accessing SD Cards

The following pages will show all the steps to set up an SD card, including wiring information if applicable. They all follow the same general structure:

1. If necessary, create an SPI bus object connecting to the card (cards attached by SDIO do not have a separate bus object)
2. Construct an SDCard object
3. Create a vfs (virtual filesystem) object
4. "Mount" the vfs object to make the SD card's files appear so they can be accessed by functions like open()

Tip: Create a mount_sd.py file

If you put the exact lines necessary to mount the sd card in a separate Python file in CIRCUITPY as mount_sd.py, you can easily call it from the REPL or from code.py with import:

In the examples, we'll assume you have already created a mount_sd.py file.

sdcardio: For SD cards on SPI interfaces

sdcardio is the module for SD cards that use an SPI interface. Unless otherwise noted, it's a good bet that a microcontroller SD card interface uses SPI. SPI uses 4 signal wires and can function at rates from 400kHz up to multiple MHz. Under some circumstances, multiple SPI devices can share 3 out of the 4 pins.

sdioio: For SD cards on SDIO interfaces

sdioio is the module for SD cards that use an SDIO interface. A few specific boards have SDIO interfaces available. SDIO uses at least 3 signal wires (CMD, CLK, and DATA0), but can use additional data wires (DATA1, DATA2, DATA3). SDIO operates at 25MHz or 50MHz, and it can transfer 1 or 4 bits at a time. However, in practice, it offers around 1.5 to 2x the speed of SPI when reading from an SD card.

The built in micro SD slot on the STM32F405 Feather is connected using SDIO. The Grand Central M4 can connect the SD card using SDIO or SPI, depending which pins are used.

adafruit_sdcard.py: For legacy uses

adafruit_sdcard is covered in its own guide. There are still some cases where you should use adafruit_sdcard:

• You're not ready to upgrade to CircuitPython 6
• Some boards without much capacity omit sdcardio, but you can put adafruit_sdcard in CIRCUITPY. This applies to all boards with the SAM D21 microcontroller.