LCD y microSD: explorador de archivos
En este ejemplo leemos la tarjeta microSD y mostramos sus archivos en la pantalla, con el nombre y el tamaño de cada uno. Si la lista no cabe, se reparte en varias páginas. La misma información sale también por el monitor serie.
Es la base para cualquier proyecto que use la tarjeta: reproducir audios, guardar grabaciones, mostrar imágenes o leer configuraciones.
Qué vas a aprender:
- Usar dos buses SPI a la vez: uno para la pantalla y otro para la microSD.
- Montar la tarjeta y consultar su tipo y capacidad.
- Recorrer los archivos de una carpeta con
openNextFile(). - Organizar el dibujo en funciones y paginar una lista larga.
Antes de empezar
Este ejemplo parte de LCD 240x240. Si aún no probaste la pantalla sola, empieza por ahí.
1. Mapa de pines
La pantalla y la microSD usan buses SPI separados, cada uno con sus propios pines.
Pantalla ST7789 (bus FSPI)
| Pin de la pantalla | GPIO | Constante | Función |
|---|---|---|---|
| SDA | 11 | TFT_MOSI |
Datos del ESP32 hacia la pantalla |
| SCL / SCK | 12 | TFT_SCLK |
Reloj del bus SPI |
| CS | 10 | TFT_CS |
Selecciona la pantalla |
| DC | 15 | TFT_DC |
Indica si se envía un comando (LOW) o datos (HIGH) |
| RES / RST | 9 | TFT_RST |
Reinicia la pantalla al arrancar |
Módulo microSD (bus HSPI)
| Pin del módulo | GPIO | Constante | Función |
|---|---|---|---|
| MISO | 1 | SD_MISO |
Datos de la tarjeta hacia el ESP32 |
| MOSI | 2 | SD_MOSI |
Datos del ESP32 hacia la tarjeta |
| CS | 41 | SD_CS |
Selecciona la tarjeta |
| SCK / CLK | 42 | SD_SCLK |
Reloj del bus SPI |
¿Por qué dos buses?
La pantalla solo recibe datos, pero la microSD también los envía de vuelta por MISO. Con un bus para cada una, las dos funcionan de forma independiente y no hay que compartir pines ni preocuparse de que una interfiera con la otra.
2. Preparar el entorno
Tarjeta microSD
- Formato FAT32. Las tarjetas de 64 GB o más vienen en exFAT y hay que reformatearlas.
- Copia algunos archivos en la raíz para tener algo que listar: por ejemplo, un
.txt, un.wavy un.jpg.
Librerías
| Librería | Para qué sirve |
|---|---|
| Adafruit ST7735 and ST7789 | Controlador de la pantalla |
| Adafruit GFX Library | Funciones de dibujo y texto |
SPI.h y SD.h |
Vienen incluidas con el soporte del ESP32 |
Usa la misma configuración de placa que en LCD 240x240.
3. Código
#include <SPI.h>
#include <SD.h>
#include <Adafruit_GFX.h>
#include <Adafruit_ST7789.h>
// =====================================================
// Pantalla ST7789 (bus FSPI)
// =====================================================
#define TFT_MOSI 11
#define TFT_SCLK 12
#define TFT_CS 10
#define TFT_DC 15
#define TFT_RST 9
Adafruit_ST7789 tft(TFT_CS, TFT_DC, TFT_RST);
// =====================================================
// microSD (bus HSPI)
// =====================================================
#define SD_MISO 1
#define SD_MOSI 2
#define SD_CS 41
#define SD_SCLK 42
SPIClass spiSD(HSPI);
// =====================================================
// Colores y diseño
// =====================================================
#define COLOR_FONDO ST77XX_BLACK
#define COLOR_TITULO ST77XX_CYAN
#define COLOR_ARCHIVO ST77XX_GREEN
#define COLOR_TAMANO ST77XX_WHITE
#define COLOR_AVISO ST77XX_YELLOW
#define COLOR_ERROR ST77XX_RED
#define COLOR_LINEA ST77XX_BLUE
#define Y_PRIMERA_LINEA 35 // Primera fila de la lista
#define ALTO_LINEA 14 // Separación entre filas
#define Y_PIE 225 // Fila del mensaje inferior
#define MAX_NOMBRE 24 // Caracteres visibles del nombre
// =====================================================
// Utilidades de dibujo
// =====================================================
void dibujarEncabezado(const char *info) {
tft.fillScreen(COLOR_FONDO);
tft.setTextSize(2);
tft.setTextColor(COLOR_TITULO);
tft.setCursor(5, 5);
tft.print("MICRO SD");
// Tipo y capacidad a la derecha del título
tft.setTextSize(1);
tft.setCursor(130, 10);
tft.print(info);
tft.drawLine(5, 27, 235, 27, COLOR_LINEA);
}
void dibujarPie(const char *texto) {
tft.setTextSize(1);
tft.setTextColor(COLOR_AVISO);
tft.setCursor(5, Y_PIE);
tft.print(texto);
}
void mostrarError(const char *linea1, const char *linea2) {
tft.fillScreen(COLOR_FONDO);
tft.setTextColor(COLOR_ERROR);
tft.setTextSize(2);
tft.setCursor(20, 80);
tft.print("ERROR SD");
tft.setTextSize(1);
tft.setCursor(20, 115);
tft.print(linea1);
tft.setCursor(20, 135);
tft.print(linea2);
}
// Convierte bytes en un texto corto: 512 B, 12.4 KB, 3.1 MB
String formatearTamano(uint64_t bytes) {
if (bytes < 1024) return String((uint32_t)bytes) + " B";
if (bytes < 1024 * 1024) return String(bytes / 1024.0, 1) + " KB";
return String(bytes / (1024.0 * 1024.0), 1) + " MB";
}
// =====================================================
// Listar archivos de la raíz
// =====================================================
void listarSD(const char *info) {
Serial.println();
Serial.println("===== ARCHIVOS MICRO SD =====");
File root = SD.open("/");
if (!root || !root.isDirectory()) {
Serial.println("ERROR: No se pudo abrir la raiz");
mostrarError("No se pudo abrir", "la carpeta raiz");
return;
}
dibujarEncabezado(info);
int y = Y_PRIMERA_LINEA;
int contador = 0;
File file = root.openNextFile();
while (file) {
if (!file.isDirectory()) {
contador++;
String nombre = file.name();
String tamano = formatearTamano(file.size());
// Monitor serie
Serial.printf("%3d: %-32s %s\n", contador, nombre.c_str(), tamano.c_str());
// Pantalla llena: espera y pasa a la página siguiente
if (y > Y_PIE - ALTO_LINEA) {
dibujarPie("Siguiente pagina...");
delay(3000);
dibujarEncabezado(info);
y = Y_PRIMERA_LINEA;
}
// Recorta los nombres largos
if (nombre.length() > MAX_NOMBRE) {
nombre = nombre.substring(0, MAX_NOMBRE - 1) + "~";
}
// Número y nombre a la izquierda
tft.setTextSize(1);
tft.setTextColor(COLOR_ARCHIVO);
tft.setCursor(5, y);
tft.printf("%2d. %s", contador, nombre.c_str());
// Tamaño alineado a la derecha (6 px por carácter)
tft.setTextColor(COLOR_TAMANO);
tft.setCursor(235 - tamano.length() * 6, y);
tft.print(tamano);
y += ALTO_LINEA;
}
file.close();
file = root.openNextFile();
}
root.close();
String resumen = "Archivos: " + String(contador);
dibujarPie(resumen.c_str());
Serial.println("============================");
Serial.printf("Total archivos: %d\n", contador);
}
// =====================================================
// SETUP
// =====================================================
void setup() {
Serial.begin(115200);
delay(1000);
Serial.println();
Serial.println("ESP32-S3: LCD + MICRO SD");
// ---------- Pantalla ----------
SPI.begin(TFT_SCLK, -1, TFT_MOSI, TFT_CS);
tft.init(240, 240);
tft.setRotation(0);
tft.fillScreen(COLOR_FONDO);
tft.setTextColor(COLOR_TITULO);
tft.setTextSize(2);
tft.setCursor(20, 100);
tft.print("Iniciando...");
// ---------- microSD ----------
Serial.println("Inicializando micro SD...");
spiSD.begin(SD_SCLK, SD_MISO, SD_MOSI, SD_CS);
if (!SD.begin(SD_CS, spiSD)) {
Serial.println("ERROR: No se pudo montar la SD");
mostrarError("No se pudo montar", "la tarjeta micro SD");
return;
}
Serial.println("SD OK");
// ---------- Tipo y capacidad ----------
const char *tipo;
switch (SD.cardType()) {
case CARD_MMC: tipo = "MMC"; break;
case CARD_SD: tipo = "SDSC"; break;
case CARD_SDHC: tipo = "SDHC"; break;
default: tipo = "???"; break;
}
uint32_t tamanoMB = SD.cardSize() / (1024 * 1024);
Serial.printf("Tipo SD: %s\n", tipo);
Serial.printf("Tamano: %u MB\n", tamanoMB);
char info[24];
snprintf(info, sizeof(info), "%s %.1f GB", tipo, tamanoMB / 1024.0);
listarSD(info);
}
// =====================================================
// LOOP
// =====================================================
void loop() {
}
4. Cómo funciona
Dos buses SPI
SPIClass spiSD(HSPI);
...
SPI.begin(TFT_SCLK, -1, TFT_MOSI, TFT_CS); // Pantalla en FSPI
spiSD.begin(SD_SCLK, SD_MISO, SD_MOSI, SD_CS); // microSD en HSPI
SD.begin(SD_CS, spiSD);
El ESP32-S3 tiene dos controladores SPI libres para el usuario: FSPI y HSPI. El objeto SPI que trae Arduino ya usa FSPI, y la librería de la pantalla lo usa por defecto. Para la microSD creamos un segundo objeto, spiSD, sobre HSPI, y se lo pasamos a SD.begin() para que no use el bus por defecto.
No uses FSPI para los dos
Si creas spiSD con FSPI, la pantalla y la microSD comparten el mismo controlador y el segundo begin() le reasigna los pines al primero. Puede parecer que funciona, pero es una configuración frágil que falla en cuanto las dos se usan a la vez.
Montar la tarjeta
SD.begin() devuelve false si no hay tarjeta, si el formato no es FAT32 o si hay un problema de conexión. En ese caso el programa muestra el error en la pantalla y termina el setup() con return, sin intentar listar nada.
Si la tarjeta se monta, SD.cardType() indica su tipo y SD.cardSize() su capacidad en bytes:
| Tipo | Significado |
|---|---|
| SDSC | Tarjetas antiguas de hasta 2 GB |
| SDHC | De 4 a 32 GB; también lo indica en tarjetas mayores |
| MMC | MultiMediaCard, el formato antecesor de las SD |
Recorrer los archivos
File root = SD.open("/");
File file = root.openNextFile();
while (file) {
...
file.close();
file = root.openNextFile();
}
SD.open("/") abre la carpeta raíz y cada llamada a openNextFile() devuelve el siguiente elemento. Cuando no quedan más, devuelve un objeto vacío y el while termina. Las carpetas se saltan con isDirectory().
Cierra cada archivo con close() antes de abrir el siguiente: la librería solo puede tener unos pocos abiertos a la vez.
Paginación
Cada archivo ocupa una fila de 14 píxeles a partir de y = 35. Antes de escribir una fila, el programa comprueba si todavía cabe sobre el pie de página. Si no cabe, escribe "Siguiente pagina...", espera 3 segundos, redibuja el encabezado y vuelve arriba.
y = 5 MICRO SD SDHC 14.8 GB
y = 27 ──────────────────────────────
y = 35 1. musica.wav 3.1 MB
y = 49 2. config.txt 214 B
...
y = 225 Archivos: 12
Formato de la lista
- Nombres largos: se recortan a 24 caracteres y terminan en
~, para no tapar el tamaño. - Tamaño:
formatearTamano()lo convierte en B, KB o MB, y se alinea a la derecha. ConsetTextSize(1)cada carácter mide 6 píxeles, así que la posición X es235 - caracteres × 6.
5. Resultado esperado
En la pantalla:
- Encabezado MICRO SD en cian, con el tipo y la capacidad de la tarjeta a la derecha.
- La lista de archivos en verde, con el tamaño en blanco.
- Al final, en amarillo, el total de archivos.
En el monitor serie, a 115200 baudios:
ESP32-S3: LCD + MICRO SD
Inicializando micro SD...
SD OK
Tipo SD: SDHC
Tamano: 15193 MB
===== ARCHIVOS MICRO SD =====
1: musica.wav 3.1 MB
2: config.txt 214 B
============================
Total archivos: 2
6. Solución de problemas
| Síntoma | Causa probable y solución |
|---|---|
| "ERROR SD – No se pudo montar" | Revisa que la tarjeta esté bien insertada y en FAT32. Comprueba los pines MISO, MOSI, CLK y CS. |
| Falla con unas tarjetas y no con otras | Algunos módulos no tienen pull-up en MISO y CS: agrega resistencias de 10 kΩ a 3,3 V. |
| La pantalla deja de responder tras iniciar la SD | Ambos dispositivos están en el mismo bus. Verifica que spiSD use HSPI. |
| No aparecen archivos | El programa solo lista la raíz y salta las carpetas. Copia los archivos fuera de cualquier carpeta. |
| Aparecen archivos que no copiaste | Son archivos ocultos del sistema operativo, como System Volume Information o los ._ de macOS. |
7. Retos
- Muestra también las carpetas, con otro color y un
/al final del nombre. - Entra en las subcarpetas de forma recursiva y lista todo su contenido.
- Usa los botones UP y DOWN para cambiar de página en lugar de esperar 3 segundos.
- Muestra el espacio libre con
SD.totalBytes()ySD.usedBytes().