Saltar a contenido

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 .wav y 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. Con setTextSize(1) cada carácter mide 6 píxeles, así que la posición X es 235 - 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

  1. Muestra también las carpetas, con otro color y un / al final del nombre.
  2. Entra en las subcarpetas de forma recursiva y lista todo su contenido.
  3. Usa los botones UP y DOWN para cambiar de página en lugar de esperar 3 segundos.
  4. Muestra el espacio libre con SD.totalBytes() y SD.usedBytes().