ESP32 MicroPython and SD Card: A Comprehensive Guide

The ESP32 is a powerful and popular microcontroller known for its Wi - Fi and Bluetooth capabilities, along with its relatively high processing power and memory. MicroPython is a lean and efficient implementation of the Python 3 programming language that runs on microcontrollers, enabling developers to write code in a high - level language for the ESP32. An SD card is a widely used storage medium that can provide large amounts of non - volatile storage for the ESP32. By integrating an SD card with the ESP32 using MicroPython, developers can store data such as sensor readings, logs, or even media files directly on the card. This article will guide you through the fundamental concepts, usage methods, common practices, and best practices of using an SD card with the ESP32 in MicroPython.

Table of Contents#

  1. Fundamental Concepts
  2. Hardware Connection
  3. Installation and Setup
  4. Usage Methods
  5. Common Practices
  6. Best Practices
  7. Conclusion
  8. References

Fundamental Concepts#

ESP32#

The ESP32 is a series of low - cost, low - power system - on - a - chip microcontrollers with integrated Wi - Fi and dual - mode Bluetooth. It has a dual - core Tensilica Xtensa LX6 microprocessor and comes with a variety of input/output pins, making it suitable for a wide range of IoT and embedded applications.

MicroPython#

MicroPython is a lightweight version of Python designed to run on microcontrollers. It provides a high - level programming interface, allowing developers to write code quickly without having to deal with the low - level details of the hardware.

SD Card#

An SD card is a flash - based memory card used for data storage in various devices. It uses the Secure Digital (SD) protocol for communication. The ESP32 can communicate with an SD card using the Serial Peripheral Interface (SPI) protocol, which is a synchronous serial communication protocol.

Hardware Connection#

To connect an SD card module to the ESP32, you need to make the following connections:

ESP32 PinSD Card Module Pin
GPIO 18SCK (Clock)
GPIO 23MOSI (Master Out Slave In)
GPIO 19MISO (Master In Slave Out)
GPIO 5CS (Chip Select)
3.3VVCC
GNDGND

Installation and Setup#

  1. Install MicroPython on ESP32:
    • First, you need to install the MicroPython firmware on your ESP32. You can use the esptool.py tool to flash the firmware.
    • Download the latest MicroPython firmware for the ESP32 from the official MicroPython website.
    • Connect your ESP32 to your computer via USB.
    • Use the following command to flash the firmware:
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 erase_flash
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x1000 esp32 - 20230426 - v1.20.0.bin
  1. Connect to the ESP32:
    • You can use a serial terminal program like PuTTY or Thonny to connect to the ESP32. Set the baud rate to 115200.

Usage Methods#

Initializing the SD Card#

import machine
import os
 
# Configure SPI
spi = machine.SPI(2, baudrate=4000000, polarity=0, phase=0, sck=machine.Pin(18), mosi=machine.Pin(23), miso=machine.Pin(19))
sd = machine.SDCard(slot=2, spi=spi, cs=machine.Pin(5))
 
# Mount the SD card
os.mount(sd, "/sd")

Writing to the SD Card#

# Open a file for writing
with open("/sd/test.txt", "w") as f:
    f.write("Hello, SD Card!")

Reading from the SD Card#

# Open a file for reading
with open("/sd/test.txt", "r") as f:
    data = f.read()
    print(data)

Listing Files on the SD Card#

# List files in the root directory of the SD card
files = os.listdir("/sd")
for file in files:
    print(file)

Common Practices#

Error Handling#

When working with the SD card, it's important to handle errors properly. For example, if the SD card is not inserted or there is a communication error, the code should be able to handle it gracefully.

try:
    spi = machine.SPI(2, baudrate=4000000, polarity=0, phase=0, sck=machine.Pin(18), mosi=machine.Pin(23), miso=machine.Pin(19))
    sd = machine.SDCard(slot=2, spi=spi, cs=machine.Pin(5))
    os.mount(sd, "/sd")
except OSError as e:
    print("Error mounting SD card:", e)

Data Logging#

One common use case is to log sensor data to the SD card.

import machine
import os
import time
 
# Configure SPI and mount SD card
spi = machine.SPI(2, baudrate=4000000, polarity=0, phase=0, sck=machine.Pin(18), mosi=machine.Pin(23), miso=machine.Pin(19))
sd = machine.SDCard(slot=2, spi=spi, cs=machine.Pin(5))
os.mount(sd, "/sd")
 
# Simulate sensor data
sensor = machine.ADC(machine.Pin(34))
 
while True:
    value = sensor.read()
    with open("/sd/sensor_log.txt", "a") as f:
        f.write(f"{time.time()},{value}\n")
    time.sleep(1)

Best Practices#

Power Management#

The SD card can consume a significant amount of power. To save power, you can unmount the SD card when it's not in use.

# Unmount the SD card
os.umount("/sd")

File Naming and Organization#

Use meaningful file names and organize your files in directories. For example, you can create separate directories for different types of data.

# Create a directory
os.mkdir("/sd/sensor_data")
# Write data to a file in the directory
with open("/sd/sensor_data/sensor_1.txt", "w") as f:
    f.write("Sensor 1 data")

Buffer Management#

When writing large amounts of data, use buffers to reduce the number of write operations.

buffer = []
for i in range(100):
    buffer.append(str(i))
data = "\n".join(buffer)
with open("/sd/large_data.txt", "w") as f:
    f.write(data)

Conclusion#

Using an SD card with the ESP32 in MicroPython provides a convenient way to store data. By understanding the fundamental concepts, hardware connections, and usage methods, you can easily integrate an SD card into your projects. Additionally, following common and best practices such as error handling, power management, and proper file organization will help you build more robust and efficient applications.

References#

2025-10