Adafruit SD Cards User Manual

CircuitPython Hardware: SD Cards

Created by Tony DiCola

Last updated on 2021-02-09 11:24:42 AM EST

2 3 4 4 5 7 7 7

8 9

10 12 14 15

16

18

18 18

18

19

Guide Contents

Guide Contents Overview Hardware Parts Wiring CircuitPython Adafruit CircuitPython Module Install Usage

Initialize & Mount SD Card Filesystem Reading & Writing Data

List Files Logging Temperature Python Docs Code Storage on SD Card

hello.py Example

MicroPython

pyboard WiPy

MicroPython ESP8266 SD Card Setup

Mount SD Card

Overview

 Note the video above was made showing the MicroPython version of this library. Follow the guide to

see both CircuitPython and MicroPython versions of using the SD card library.

Secure Digital (https://adafru.it/rye), or SD, cards and tiny microSD cards are inexpensive and ubiquituous

means of adding lots of storage to devices. For a few dollars you can have gigabytes of storage at your

fingertips (smaller than your fingertips actually!). With small CircuitPython and MicroPython boards you

typically have a very limited amount of flash memory to store code and data. Wouldn't it be nice if you

could connect a microSD card to a Python board and expand its storage? It turns you can use microSD

cards with CircuitPython and MicroPython! In fact some boards like the pyboard (https://adafru.it/pFb)

come with microSD card support built-in, and for other boards like the ESP8266 or M0 / SAMD21 family

they can easily be connected to a microSD card that expands their storage.

This guide explores how to use a microSD card to store files for a CircuitPython MicroPython board.

Specifically adding a microSD card to CircuitPython boards like Feather M0

adalogger, pyboard (https://adafru.it/pFb), WiPy (https://adafru.it/pFf), and

ESP8266 (https://adafru.it/n6A) will be covered in this guide. You'll learn how to connect a microSD card

to the board and mount it as a new filesystem that store code & data.

Hardware Parts

You'll need the following parts to follow this guide:

CircuitPython board. This guide focuses on

the ESP8266 (https://adafru.it/n6A) and Feather M0/SAMD21-

based boards (http://adafru.it/2772), but any CircuitPython

board that supports I2C should work. You'll find a board with

a SD card holder built-in, like the Feather M0

Adalogger (https://adafru.it/weP), the most simple and direct

way to use an SD card.

If your board doesn't come with CircuitPython running on it

already then check out your board's guide for how to load

CircuitPython firmware. For example the Feather M0 express

guide (https://adafru.it/wbv) is a good reference.

If you're using a Feather board and FeatherWing you

probably want a Feather female header

set (http://adafru.it/2886) or Feather stacking female header

set (http://adafru.it/2830).

MicroSD card holder. If your board doesn't have one already

you'll need to get a microSD card holder that exposes the

card as a SPI device. For Feathers the Adalogger

FeatherWing (https://adafru.it/weP) is an easy plug-in adapter

that adds microSD card (and more) to your board. For other

boards a microSD breakout (https://adafru.it/qyF) is what you

want.

MicroSD card. (https://adafru.it/e4Z) You'll need a card to use

to store data. Any microSD card should work, but be aware

the very cheap / generic cards can sometimes be more

unreliable or cause problems compared to known-good

cards. If a card works well for Raspberry Pi and other boards

it should work well for CircuitPython and MicroPython.

Be careful to avoid extremely large (128+ gigabyte) cards as

they require special filesystems and block sizes that might not

be compatible with the code in this guide. Stick with a typical

4 - 16 gigabyte card.

Breadboard (http://adafru.it/64)and jumper

wires (http://adafru.it/153). If you aren't using a Feather and

FeatherWing you'll need a breadboard and jumper wires to

connect the components.

Soldering tools (http://adafru.it/136). You'll need to solder

headers to the boards Check out the guide to excellent

soldering (https://adafru.it/dxy) if you're new to soldering.

Wiring

If you're using a Feather and FeatherWing just plug the FeatherWing into your board and be sure to note

which pin on the FeatherWing is used for the microSD card chip select line (for the Adalogger

FeatherWing this is GPIO 10 on M0 boards and GPIO 15 on the ESP8266).

If you're wiring up a microSD card breakout you'll need to connect it to your board's hardware SPI bus, for

example with the ESP8266 you might wire it as follows:

https://adafru.it/zwB

Board ground (GND) to microSD breakout ground (GND) .

Board 3.3V power to microSD breakout 3.3V power.

Board SPI CLK (ESP8266 GPIO 14) to microSD breakout clock (CLK).

Board SPI MOSI (ESP8266 GPIO 13) to microSD breakout data input (DI).

Board SPI MISO (ESP8266 GPIO 12) to microSD breakout data output (DO).

Board GPIO 15 (or any other free digital IO pin) to microSD breakout chip select (CS) .

Finally make sure your microSD card is formatted with the FAT or FAT32 filesystem. Most cards come

pre-formatted with this filesystem, but if yours does not or you'd like to erase it look for a disk utility in

your operating system. On macOS the Disk Utility program can format cards, and on Windows right-click

the drive and select Format.

https://adafru.it/zwB

CircuitPython Adafruit CircuitPython Module Install

To use a microSD card with your Adafruit CircuitPython board you'll need to install

the Adafruit_CircuitPython_SD (https://adafru.it/zwC) module on your board.

First make sure you are running the latest version of Adafruit CircuitPython (https://adafru.it/Amd) for your

board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find

and install these libraries from Adafruit's CircuitPython library bundle (https://adafru.it/zdx). Our

introduction guide has a great page on how to install the library bundle (https://adafru.it/ABU) for both

express and non-express boards. Be sure to use the latest CircuitPython Bundle as it includes an

updated version of the SD card module with a few necessary fixes!

Remember for non-express boards like the, you'll need to manually install the necessary libraries from the

bundle:

adafruit_sdcard.mpy

adafruit_bus_device

If your board doesn't support USB mass storage, like the ESP8266, then use a tool like ampy to copy the

file to the board (https://adafru.it/s1f). You can use the latest version of ampy and its new directory copy

command (https://adafru.it/q2A) to easily move module directories to the board.

Before continuing make sure your board's lib folder or root filesystem has the adafruit_sdcard.mpy and

adafruit_bus_device modules copied over.

Usage

The following section will show how to initialize the SD card and read & write data to it from the board's

Python prompt / REPL.

Adafruit SD Cards User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual