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.
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.
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:
- If necessary, create an
SPIbus object connecting to the card (cards attached by SDIO do not have a separate bus object)
- Construct an
- Create a
vfs(virtual filesystem) object
- "Mount" the
vfsobject to make the SD card's files appear so they can be accessed by functions like
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
In the examples, we'll assume you have already created a mount_sd.py file.
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 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 is covered in its own guide. There are still some cases where you should use
- You're not ready to upgrade to CircuitPython 6
- Some boards without much capacity omit
sdcardio, but you can put
adafruit_sdcardin CIRCUITPY. This applies to all boards with the SAM D21 microcontroller.