ESP32 и модуль microSD-карты в Arduino IDE

Перевод статьи ESP32: Guide for MicroSD Card Module using Arduino IDE — Rui Santos, Random Nerd Tutorials.

Модуль microSD-карты позволяет ESP32 хранить данные прямо на карте памяти: вести журнал показаний датчиков, сохранять настройки, отдавать HTML/CSS-файлы веб-сервера и многое другое. В этом руководстве подключим модуль к ESP32 по SPI и разберём основные операции с файлами из Arduino IDE.

Что понадобится#

плата ESP32 (о выборе и настройке — ниже);
модуль microSD-карты;
microSD-карта;
макетная плата;
соединительные провода.

Предварительная настройка#

Чтобы прошивать ESP32 из Arduino IDE, в ней должна быть установлена поддержка плат ESP32:

Установка платы ESP32 в Arduino IDE 2

Схема подключения#

Модуль microSD-карты общается с ESP32 по протоколу SPI. Подключите его к стандартным выводам SPI, как в таблице ниже.

Модуль microSD	ESP32
3V3	3.3V
CS	GPIO 5
MOSI	GPIO 23
CLK	GPIO 18
MISO	GPIO 19
GND	GND

Схема подключения модуля microSD-карты к ESP32 по SPI — Модуль microSD подключается к стандартным выводам SPI у ESP32.

Важно про питание. Некоторые модули microSD-карт капризны к напряжению и стабильнее работают от 5 В (вывод VCC), даже если на плате написано 3.3 В. Если карта не определяется — попробуйте запитать модуль от 5 В. Нехватка или нестабильность питания — самая частая причина проблем.

Форматирование microSD-карты#

Прежде чем продолжать, отформатируйте карту в FAT32.

В Windows это делается так:

Вставьте карту в компьютер (через кардридер или адаптер).
В «Проводнике» щёлкните по карте правой кнопкой мыши и выберите Форматировать.
В поле «Файловая система» выберите FAT32 и запустите форматирование.

Карты объёмом больше 32 ГБ часто идут с завода в exFAT, и стандартный диалог Windows не даёт выбрать для них FAT32. В этом случае воспользуйтесь сторонней утилитой вроде fat32format (guiformat).

Код#

Для примера возьмём готовый скетч из комплекта: Файл → Примеры → SD (esp32) → SD_Test. Он по очереди демонстрирует все основные операции с файлами: выводит содержимое карты, создаёт и удаляет папку, пишет, дописывает, читает, переименовывает и удаляет файл, а в конце замеряет скорость чтения и записи.

/*
  Rui Santos
  Complete project details at https://RandomNerdTutorials.com/esp32-microsd-card-arduino/
  
  This sketch can be found at: Examples > SD(esp32) > SD_Test
*/

#include "FS.h"
#include "SD.h"
#include "SPI.h"

void listDir(fs::FS &fs, const char * dirname, uint8_t levels){
  Serial.printf("Listing directory: %s\n", dirname);

  File root = fs.open(dirname);
  if(!root){
    Serial.println("Failed to open directory");
    return;
  }
  if(!root.isDirectory()){
    Serial.println("Not a directory");
    return;
  }

  File file = root.openNextFile();
  while(file){
    if(file.isDirectory()){
      Serial.print("  DIR : ");
      Serial.println(file.name());
      if(levels){
        listDir(fs, file.name(), levels -1);
      }
    } else {
      Serial.print("  FILE: ");
      Serial.print(file.name());
      Serial.print("  SIZE: ");
      Serial.println(file.size());
    }
    file = root.openNextFile();
  }
}

void createDir(fs::FS &fs, const char * path){
  Serial.printf("Creating Dir: %s\n", path);
  if(fs.mkdir(path)){
    Serial.println("Dir created");
  } else {
    Serial.println("mkdir failed");
  }
}

void removeDir(fs::FS &fs, const char * path){
  Serial.printf("Removing Dir: %s\n", path);
  if(fs.rmdir(path)){
    Serial.println("Dir removed");
  } else {
    Serial.println("rmdir failed");
  }
}

void readFile(fs::FS &fs, const char * path){
  Serial.printf("Reading file: %s\n", path);

  File file = fs.open(path);
  if(!file){
    Serial.println("Failed to open file for reading");
    return;
  }

  Serial.print("Read from file: ");
  while(file.available()){
    Serial.write(file.read());
  }
  file.close();
}

void writeFile(fs::FS &fs, const char * path, const char * message){
  Serial.printf("Writing file: %s\n", path);

  File file = fs.open(path, FILE_WRITE);
  if(!file){
    Serial.println("Failed to open file for writing");
    return;
  }
  if(file.print(message)){
    Serial.println("File written");
  } else {
    Serial.println("Write failed");
  }
  file.close();
}

void appendFile(fs::FS &fs, const char * path, const char * message){
  Serial.printf("Appending to file: %s\n", path);

  File file = fs.open(path, FILE_APPEND);
  if(!file){
    Serial.println("Failed to open file for appending");
    return;
  }
  if(file.print(message)){
      Serial.println("Message appended");
  } else {
    Serial.println("Append failed");
  }
  file.close();
}

void renameFile(fs::FS &fs, const char * path1, const char * path2){
  Serial.printf("Renaming file %s to %s\n", path1, path2);
  if (fs.rename(path1, path2)) {
    Serial.println("File renamed");
  } else {
    Serial.println("Rename failed");
  }
}

void deleteFile(fs::FS &fs, const char * path){
  Serial.printf("Deleting file: %s\n", path);
  if(fs.remove(path)){
    Serial.println("File deleted");
  } else {
    Serial.println("Delete failed");
  }
}

void testFileIO(fs::FS &fs, const char * path){
  File file = fs.open(path);
  static uint8_t buf[512];
  size_t len = 0;
  uint32_t start = millis();
  uint32_t end = start;
  if(file){
    len = file.size();
    size_t flen = len;
    start = millis();
    while(len){
      size_t toRead = len;
      if(toRead > 512){
        toRead = 512;
      }
      file.read(buf, toRead);
      len -= toRead;
    }
    end = millis() - start;
    Serial.printf("%u bytes read for %u ms\n", flen, end);
    file.close();
  } else {
    Serial.println("Failed to open file for reading");
  }


  file = fs.open(path, FILE_WRITE);
  if(!file){
    Serial.println("Failed to open file for writing");
    return;
  }

  size_t i;
  start = millis();
  for(i=0; i<2048; i++){
    file.write(buf, 512);
  }
  end = millis() - start;
  Serial.printf("%u bytes written for %u ms\n", 2048 * 512, end);
  file.close();
}

void setup(){
  Serial.begin(115200);
  if(!SD.begin(5)){
    Serial.println("Card Mount Failed");
    return;
  }
  uint8_t cardType = SD.cardType();

  if(cardType == CARD_NONE){
    Serial.println("No SD card attached");
    return;
  }

  Serial.print("SD Card Type: ");
  if(cardType == CARD_MMC){
    Serial.println("MMC");
  } else if(cardType == CARD_SD){
    Serial.println("SDSC");
  } else if(cardType == CARD_SDHC){
    Serial.println("SDHC");
  } else {
    Serial.println("UNKNOWN");
  }

  uint64_t cardSize = SD.cardSize() / (1024 * 1024);
  Serial.printf("SD Card Size: %lluMB\n", cardSize);

  listDir(SD, "/", 0);
  createDir(SD, "/mydir");
  listDir(SD, "/", 0);
  removeDir(SD, "/mydir");
  listDir(SD, "/", 2);
  writeFile(SD, "/hello.txt", "Hello ");
  appendFile(SD, "/hello.txt", "World!\n");
  readFile(SD, "/hello.txt");
  deleteFile(SD, "/foo.txt");
  renameFile(SD, "/hello.txt", "/foo.txt");
  readFile(SD, "/foo.txt");
  testFileIO(SD, "/test.txt");
  Serial.printf("Total space: %lluMB\n", SD.totalBytes() / (1024 * 1024));
  Serial.printf("Used space: %lluMB\n", SD.usedBytes() / (1024 * 1024));
}

void loop(){

}

Разбор функций#

В скетче каждая операция вынесена в отдельную функцию — их удобно копировать в свои проекты:

listDir() — выводит список файлов и папок; параметр levels задаёт, насколько глубоко заходить во вложенные каталоги;
createDir() — создаёт папку;
removeDir() — удаляет папку;
readFile() — читает содержимое файла и выводит его в монитор порта;
writeFile() — создаёт файл и записывает в него текст (старое содержимое затирается);
appendFile() — дописывает текст в конец файла, не стирая уже записанное;
renameFile() — переименовывает (или перемещает) файл;
deleteFile() — удаляет файл;
testFileIO() — замеряет скорость чтения и записи.

Обратите внимание на инициализацию карты в setup():

if(!SD.begin(5)){
  Serial.println("Card Mount Failed");
  return;
}

Здесь 5 — это вывод CS (chip select). Если вы подключили CS к другому пину, укажите его номер.

Свои выводы SPI#

Если стандартные выводы SPI заняты, можно назначить свои. Для этого объявите нужные пины и создайте собственный экземпляр SPIClass:

#define SCK  17
#define MISO  19
#define MOSI  23
#define CS  5

SPIClass spi = SPIClass(VSPI);

spi.begin(SCK, MISO, MOSI, CS);
if (!SD.begin(CS, spi, 80000000)) {
  Serial.println("Card Mount Failed");
  return;
}

Результат#

Загрузите скетч в ESP32 и откройте монитор порта на скорости 115200 бод. Нажмите на плате кнопку RST. В окне монитора появится тип и объём карты, а затем — результат всех операций по очереди: список файлов, создание и удаление папки, запись и чтение hello.txt, переименование в foo.txt и замер скорости чтения/записи.

Что дальше#

Теперь ESP32 умеет читать и писать файлы на microSD-карту. Дальше на этой основе удобно вести журнал показаний датчиков с отметками времени в файл .csv или отдавать сохранённые на карте файлы через веб-сервер.