Using an SD Card reader breakout board

Updated Nov 24

The ESP32 comes in various configurations depending on the board you choose.
The ones I use have 8Mb of flash memory which is more than enough for my needs, however some projects might require something above that limit.

As my project requires the units in the field to be running un-interupted for months, I started uploading system logs every time they connected to the web but the increased overhead in data usage and power consumption made this less than ideal. I rely on these units drawing as little power as possible in order for the solar panel to keep the battery charged even after several dull days in mid-winter.

The answer to this was to keep the logs on and SD card.

The advantage here is the card can be removed to read the logs without the need to upload the logs, or to stop the units and connect them up to a computer to read them. I have tried 3 different SD breakout boards, two from Adafruit and one from Pololu and they all work without the need for any external libraries if only basic functionality is required, ie Create, Delete, List, Read and Write. All these are available from the native uPython module "os".

There is a driver, SDCard, in the machine module, but I have found it problematic. I have found this library works well.
sdcard.py from micropython-lib on github

# Simple ESP32 interface to MicroSD Card Adapter
import sys
from machine import Pin, SPI, SoftSPI
import os 
import sdcard

#Initialise the SPI bus
spi=SoftSPI(1,sck=Pin(5),mosi=Pin(32),miso=Pin(14))
cd = Pin(33, Pin.IN, Pin.PULL_UP)

# Initialize the SD card
try:
    sd=sdcard.SDCard(spi,Pin(27))
except Exception as e:
    print(str(e))
    
# Create a instance of MicroPython Virtual File System (VFS),
try:
    if cd.value() == 1: 
        vfs=os.VfsFat(sd)
    else:
        print('No SD Card detected')
except:
    print('Unable to create VFS')
    sys.exit()

# Mount the SD card
try:
    if cd.value() == 1: os.mount(sd,'/sd')
except Exception as e:
    print(str(e))
    sys.exit(0)

#Print SD card directory and files
if cd.value() == 1:
    print('List SD files')
    print(os.listdir('/sd'))
    print()

#Create / Open a file in write mode. Write mode creates a new file.
#If  file allready exists, it overwrites the file.
    file = open("/sd/example.txt","w")

#Write some text and Close the file
    file.write('Here is a line of text\n')    
    file.close()

#Open the file again in append mode to add 3 more lines
    for x in range (3):
        file = open('/sd/example.txt','a')
        file.write('Write another line to file \n')
        file.close()

#Open file in read mode, read and print the number of lines and content
    file = open('/sd/example.txt','r')
    print('Read example.txt from SD Card')
    data = file.readlines()
    lines = len(data)
    print('Example.txt has ' + str(lines) + ' lines.\n')
    for x in range(lines):
        print(data[x], end="")
    file.close()

#Delete the file
    print()
    print('Deleting example.txt')
    os.remove('sd/example.txt')

#List files on card
    print('List files\n')
    print()
    filelist = os.listdir('/sd')
    if (len(filelist)==1):
        print('No files on card')
    else:
        for x in filelist:
            print(x)

You need to set up the pins you are going to use for the SPI interface, and power. Ground needs to be connected to the ESP GND pin. You can power the card reader either by permanent connection to the ESP 3v pin, or any GPIO output pin. EDIT. I've since found that the current from a GPIO is not enought to power some breakouts. An option is to use an NPN transistor as a switch. Connect Vin on your breakout to +3v, GND to the emitter of the transistor. Connect the collector to GND and base via a 220R resistor to the GPIO pin.

SD breakout boards label their input/output as either DO or SO, and DI or SI. These need to go to whatever you choose for mosi and miso, in my case I chose pin 32 for mosi, wired to DI on my breakout, and pin 14 for mosi, to DO on the breakout.

The breakouts have a clock pin, SCK or SCK and I chose pin 5 on the ESP, which is actually the SCK pin. The CS pin I chose to connect to use pin 27 on the ESP but you can use another pin if you need to. The CD pin is "Card Detect", and on most (not all though) breakouts this is shorted to ground when a card is not inserted.

This line initialises the SPI bus (use SoftSPI and not SPI) "spi=SoftSPI(1,sck=Pin(5),mosi=Pin(32),miso=Pin(14))"

After that we can create an SDCard object called "sd" and use it with the uPython inbuilt functions for file manipulation.
Creating this object will not throw an error if there is not a card inserted, so it is wise to check for this each time we access any of the filesystem functions. That way, if there is a card error we can bypass that code without interupting the rest of the programme.

If the files written to the SD card are mission critical, you could always write code to write to the internal file system if the SD card is not available.

Links

IDE editors for programming ESP boards.
Micropython editors

Micropython functionality and libraries.
Micropython.org

Find the uPython firmware for your board.
uPython firmware for development boards.

ESP32 uPython modules and function examples.
Quick reference for the ESP32

Finding the MAC address

Scanning and connecting to multiple SSIDs

Using an SD card reader breakout board

ESP32 Real Time Clock

The Deepsleep function

Storing variables in the RTC

RTC Tuning

OTA Updating running software without interuption

Future articles

Communication between ESPs

Using an Adafruit GPS module

Hassle free web communication with urequests.py.