Módulo de cartão SD no Arduino: datalogger em CSV com data e hora do RTC

Um módulo de cartão SD para Arduino é uma plaquinha pequena e barata que permite salvar em um cartão micro SD, como arquivos, as leituras de temperatura, umidade, distância ou localização dos seus sensores. É o jeito mais fácil de montar um datalogger (registrador de dados) que mede por dias ou até meses sem nenhum computador ligado: o Arduino faz as leituras, o módulo grava cada uma como uma nova linha em um arquivo CSV no cartão e, depois, você coloca o cartão no computador e monta um gráfico com os dados no Excel. O módulo se comunica por SPI e funciona com poucas linhas de código usando a biblioteca SD, que já vem com a Arduino IDE.

Neste guia você vai aprender, passo a passo, como o módulo funciona, a diferença entre os módulos de 5 V e de 3,3 V, a ligação SPI no Arduino Uno, no Mega, no ESP32 e no Raspberry Pi Pico, como formatar o cartão em FAT32, como gravar e ler arquivos e como manter um registro em CSV com data e hora usando um módulo RTC. Também falamos da interface rápida SD_MMC do ESP32, do uso de cartão SD no Pico com MicroPython e de como resolver o famoso erro “initialization failed”.

O que é um módulo de cartão SD e como ele funciona?

Cartões SD funcionam com 3,3 V e podem se comunicar de duas formas: o modo SD nativo, que é rápido, e o modo SPI, mais simples. Microcontroladores como o Arduino conversam com o cartão por SPI. A função do módulo é deixar os dois eletricamente compatíveis: o regulador reduz os 5 V para os 3,3 V de que o cartão precisa, e um CI conversor de nível lógico (geralmente um 74LVC125A) converte os sinais de 5 V do Arduino para os 3,3 V que o cartão suporta. Por dentro, o cartão é formado por blocos de 512 bytes, enquanto conceitos como arquivos, pastas e nomes de arquivo ficam por conta do sistema de arquivos FAT. A biblioteca SD faz todo esse trabalho pesado para você; basta abrir um arquivo, gravar nele e fechá-lo.

Módulo de cartão SD de 5 V ou de 3,3 V: qual comprar?

Se você usa um Arduino Uno, Nano ou Mega, escolha um módulo micro SD com regulador e conversor de nível, como o da foto, e ligue o VCC ao pino 5V. O ESP32 e o Pico funcionam com 3,3 V; você também pode usar o mesmo módulo com eles, mas ainda deve alimentá-lo com 5 V (VIN no ESP32, VBUS no Pico quando ele está alimentado pela USB). Como o conversor de nível é alimentado com 3,3 V, o sinal MISO que volta para o microcontrolador já sai em 3,3 V. Módulos sem regulador vão direto no pino 3V3; se você precisar usar um deles com um Arduino de 5 V, coloque um divisor de tensão de 1 kΩ + 2 kΩ em cada uma das linhas MOSI, SCK e CS, ou use um conversor de nível lógico. Você pode conferir os valores dos resistores com a calculadora de divisor de tensão.

Ligação do módulo de cartão SD: pinos SPI

MISO, MOSI e SCK precisam ir para os pinos de SPI por hardware em todas as placas; já o CS (chip select) pode ser qualquer pino digital, desde que você passe o mesmo número para SD.begin() no código. Nos shields prontos, o CS costuma ser o D4 ou o D10. Você pode ligar vários dispositivos ao mesmo barramento SPI: todos compartilham MISO, MOSI e SCK, e cada um tem o seu próprio pino CS. Explicamos em detalhes como o SPI funciona em comunicação SPI. Para ver onde ficam os pinos na sua placa, use a ferramenta Pinagem.

Preparando o cartão SD: formatação em FAT32

• Tamanho do cartão: escolha um cartão micro SDHC entre 4 e 32 GB. A biblioteca SD do Arduino suporta cartões SDSC (até 2 GB) e SDHC; os cartões SDXC de 64 GB ou mais vêm formatados em exFAT, que essa biblioteca não consegue ler.
• Sistema de arquivos: formate o cartão em FAT32 (FAT16 também funciona em cartões de 2 GB ou menos). NTFS e exFAT não funcionam.
• Windows: clique com o botão direito no cartão no Explorador de Arquivos, escolha Formatar e selecione FAT32 como sistema de arquivos e o tamanho da unidade de alocação padrão. O Windows não oferece FAT32 para cartões maiores que 32 GB.
• macOS: selecione o cartão no Utilitário de Disco, clique em Apagar e escolha MS-DOS (FAT) como formato e Registro Mestre de Inicialização (Master Boot Record) como esquema.
• A opção mais segura: o programa gratuito SD Card Formatter, da SD Association, formata o cartão de acordo com o padrão oficial e elimina a maioria dos erros estranhos.
• Partição única: o cartão deve ter só uma partição. Cartões usados antes em um Raspberry Pi ou em uma câmera podem ainda ter várias partições; apague-as antes de formatar.

Primeiro teste passo a passo: gravando e lendo o cartão SD

1. Coloque o cartão formatado no módulo e ligue o módulo ao Arduino seguindo a tabela acima.
2. A biblioteca SD já vem com a Arduino IDE, então não há nada para instalar; basta incluir SPI.h e SD.h no início do sketch.
3. Carregue o código abaixo e abra o Monitor Serial a 9600 baud.
4. Se aparecer “tamam” (OK, em turco) e o conteúdo do arquivo, o cartão e a ligação estão certos. Uma nova linha é acrescentada ao TEST.TXT toda vez que a placa liga.
5. Quando você tirar o cartão e colocá-lo no computador, pode abrir o TEST.TXT em qualquer editor de texto.

1#include <SPI.h>
2#include <SD.h>
3
4const int CS_PIN = 10;                           // modülün CS pini / module CS pin
5
6void setup() {
7  Serial.begin(9600);
8  Serial.print(F("SD kart baslatiliyor... "));
9  if (!SD.begin(CS_PIN)) {                       // kart başlatılamadı / card init failed
10    Serial.println(F("initialization failed"));
11    while (true);                                // burada dur / stop here
12  }
13  Serial.println(F("tamam"));
14
15  File dosya = SD.open("TEST.TXT", FILE_WRITE);  // yoksa oluşturur, sona ekler / creates it, appends
16  if (dosya) {
17    dosya.println(F("Merhaba BlueGrays!"));
18    dosya.close();                               // tamponu karta yazar / flushes the buffer to the card
19    Serial.println(F("TEST.TXT yazildi"));
20  } else {
21    Serial.println(F("TEST.TXT acilamadi"));     // dosya açılamadı / could not open file
22  }
23
24  dosya = SD.open("TEST.TXT");                   // okumak için aç / open for reading
25  if (dosya) {
26    Serial.print(F("Boyut (bayt): "));
27    Serial.println(dosya.size());
28    while (dosya.available()) {
29      Serial.write(dosya.read());                // içeriği seri porta yaz / print contents to serial
30    }
31    dosya.close();
32  }
33}
34
35void loop() {
36}

Registro de sensores em CSV com data e hora do RTC

O formato de arquivo mais prático para um datalogger é o CSV (valores separados por vírgula): cada linha é uma medição, cada coluna é um valor e a primeira linha traz os títulos das colunas. Para saber quando cada leitura foi feita, você deve acrescentar a data e a hora em todas as linhas. A millis() só informa há quanto tempo o Arduino está ligado e volta a zero toda vez que ele reinicia, por isso usamos um módulo RTC (relógio de tempo real) com bateria tipo moeda. O RTC continua contando o tempo mesmo com o Arduino desligado. O DS1307 é barato, mas pode atrasar ou adiantar alguns segundos por dia, enquanto o DS3231 desvia só cerca de um minuto por ano graças ao seu cristal com compensação de temperatura. Comparamos os dois em módulos de relógio RTC.

O circuito: o módulo SD vai nos pinos SPI, como na tabela acima, o módulo RTC vai no barramento I2C (no Uno, SDA = A4, SCL = A5, VCC = 5V) e o pino de dados do sensor DHT22 vai no D2; se você estiver usando o sensor sem placa, coloque um resistor de 10 kΩ entre o pino de dados e o VCC. Instale as bibliotecas RTClib (Adafruit) e DHT sensor library pelo Gerenciador de Bibliotecas. Para os detalhes da ligação do sensor, veja sensor de temperatura e umidade DHT11 e DHT22.

1#include <SPI.h>
2#include <SD.h>
3#include <Wire.h>
4#include <RTClib.h>
5#include <DHT.h>
6
7const int CS_PIN = 10;                           // SD modülü CS / SD module CS
8const unsigned long ARALIK = 10000;              // 10 saniyede bir kayıt / log every 10 seconds
9
10RTC_DS1307 rtc;                                  // DS3231 için RTC_DS3231 / RTC_DS3231 for a DS3231
11DHT dht(2, DHT22);                               // veri pini D2, DHT11 de olur / data pin D2, DHT11 also works
12unsigned long sonKayit = 0;
13
14void setup() {
15  Serial.begin(9600);
16  dht.begin();
17  if (!rtc.begin()) {
18    Serial.println(F("RTC bulunamadi"));         // RTC yok / RTC not found
19    while (true);
20  }
21  if (!rtc.isrunning()) {                        // saat hiç kurulmamış / clock never set
22    rtc.adjust(DateTime(F(__DATE__), F(__TIME__)));  // derleme anına kur / set to compile time
23  }
24  if (!SD.begin(CS_PIN)) {
25    Serial.println(F("SD kart hatasi"));         // SD başlatılamadı / SD init failed
26    while (true);
27  }
28  if (!SD.exists("VERI.CSV")) {                  // yeni dosyaya başlık satırı / header row for a new file
29    File f = SD.open("VERI.CSV", FILE_WRITE);
30    if (f) {
31      f.println(F("tarih,saat,sicaklik_C,nem_yuzde"));
32      f.close();
33    }
34  }
35}
36
37void loop() {
38  if (millis() - sonKayit < ARALIK) return;      // zamanı gelmedi / not time yet
39  sonKayit = millis();
40
41  float t = dht.readTemperature();
42  float h = dht.readHumidity();
43  if (isnan(t) || isnan(h)) {                    // sensör okunamadı / sensor read failed
44    Serial.println(F("DHT okuma hatasi"));
45    return;
46  }
47
48  DateTime simdi = rtc.now();
49  char ts[8], hs[8], satir[48];
50  dtostrf(t, 1, 1, ts);                          // AVR'de sprintf %f desteklemez / AVR sprintf has no %f
51  dtostrf(h, 1, 1, hs);
52  snprintf(satir, sizeof(satir), "%04d-%02d-%02d,%02d:%02d:%02d,%s,%s",
53           simdi.year(), simdi.month(), simdi.day(),
54           simdi.hour(), simdi.minute(), simdi.second(), ts, hs);
55
56  File f = SD.open("VERI.CSV", FILE_WRITE);      // sona ekle / append
57  if (f) {
58    f.println(satir);
59    f.close();                                   // her kayıtta kapat: güç kesilse de veri kalır / close every time so data survives a power cut
60    Serial.println(satir);
61  } else {
62    Serial.println(F("VERI.CSV acilamadi"));
63  }
64}

A cada 10 segundos, o código lê a temperatura e a umidade, pega a data e a hora do RTC e acrescenta uma linha como 2026-11-04,14:05:30,23.5,45.2 ao final do VERI.CSV. Como o arquivo é fechado depois de cada registro, os dados gravados até ali não se perdem nem com uma queda de energia. Nas placas AVR, a sprintf() não aceita números de ponto flutuante (%f), por isso os valores primeiro são convertidos em texto com dtostrf(). Como a temporização usa millis() em vez de delay(), você também pode fazer outras coisas no loop(). Se o RTC nunca foi acertado, o relógio é ajustado para o momento em que o código foi compilado. Se você usa um DS3231, basta escrever RTC_DS3231 no lugar de RTC_DS1307 e verificar lostPower() no lugar de isrunning().

Quanto espaço isso ocupa? Uma linha tem cerca de 31 bytes. Gravando a cada 10 segundos, são 8.640 linhas por dia, ou cerca de 260 KB; em um ano, dá uns 95 MB. Ou seja, nesse ritmo um cartão de 8 GB dura décadas. O limite real não é o cartão, e sim a alimentação: se o projeto vai rodar com pilhas ou bateria, calcule antes quanto tempo elas vão durar com a calculadora de autonomia da bateria.

Abrindo os dados do cartão SD no Excel

1. Desligue a alimentação do Arduino, tire o cartão do módulo e coloque-o no computador.
2. Copie o VERI.CSV para o computador; trabalhar com uma cópia é mais seguro do que trabalhar direto no cartão.
3. Abra uma pasta de trabalho em branco no Excel e escolha o arquivo em Dados > De Texto/CSV.
4. Na janela de visualização, selecione Vírgula como delimitador e clique em Carregar; as colunas são separadas em data, hora, temperatura e umidade.
5. Selecione as colunas de temperatura e umidade e adicione um gráfico de linhas pela guia Inserir para ver como elas variam ao longo do tempo.

1// Excel'de ondalık ayırıcı virgülse / if Excel uses a decimal comma
2// Bu iki fonksiyonu kayıt kodunda loop()'un üstüne ekle / add these two functions above loop() in the logging sketch
3void noktayiVirgulYap(char *s) {
4  for (; *s; s++) {
5    if (*s == '.') *s = ',';                     // 23.5 -> 23,5
6  }
7}
8
9void excelSatiri(char *satir, size_t boyut, const DateTime &simdi, char *ts, char *hs) {
10  noktayiVirgulYap(ts);
11  noktayiVirgulYap(hs);
12  snprintf(satir, boyut, "%04d-%02d-%02d;%02d:%02d:%02d;%s;%s",   // ayırıcı ; / separator ;
13           simdi.year(), simdi.month(), simdi.day(),
14           simdi.hour(), simdi.minute(), simdi.second(), ts, hs);
15}
16
17// loop() içinde snprintf satırının yerine / in loop(), replace the snprintf line with:
18//   excelSatiri(satir, sizeof(satir), simdi, ts, hs);
19// Başlık satırı da / header row too: tarih;saat;sicaklik_C;nem_yuzde

Se você prefere enviar as leituras ao vivo para o Excel enquanto o Arduino está ligado ao computador, sem tirar o cartão, dê uma olhada nos métodos Data Streamer e PLX-DAQ em enviar dados do Arduino para o Excel. Já o cartão SD é indispensável em projetos que funcionam em campo, longe de qualquer computador.

Usando cartão SD com o ESP32 (SPI)

O core Arduino do ESP32 vem com a sua própria biblioteca SD, que funciona quase do mesmo jeito, mas há três diferenças importantes: os caminhos dos arquivos começam com / (“/olcumler.csv”), nomes de arquivo longos são permitidos e FILE_WRITE sobrescreve o arquivo do zero. Para acrescentar dados no final, você precisa usar FILE_APPEND; se levar o código do Uno sem mudanças, os dados antigos serão apagados toda vez que a placa ligar. Os pinos SPI padrão são SCK 18, MISO 19 e MOSI 23, e o GPIO 5 costuma ser usado como CS. Também dá para ler o tipo e o tamanho do cartão com uma única linha:

1#include <SPI.h>
2#include <SD.h>
3
4const int CS_PIN = 5;                            // VSPI: SCK 18, MISO 19, MOSI 23 / default VSPI pins
5const char *DOSYA = "/olcumler.csv";             // yol / ile başlar / path starts with /
6
7void setup() {
8  Serial.begin(115200);
9  if (!SD.begin(CS_PIN)) {                       // varsayılan SPI hızı 4 MHz / default SPI clock 4 MHz
10    Serial.println("Card Mount Failed");
11    return;
12  }
13  uint8_t tur = SD.cardType();
14  if (tur == CARD_NONE) {
15    Serial.println("Kart takili degil");         // kart yok / no card inserted
16    return;
17  }
18  Serial.printf("Kart tipi: %s\n", tur == CARD_SDHC ? "SDHC" : (tur == CARD_SD ? "SDSC" : "MMC"));
19  Serial.printf("Boyut: %llu MB\n", SD.cardSize() / (1024 * 1024));
20
21  if (!SD.exists(DOSYA)) {                       // uzun dosya adı serbest / long file names are fine
22    File f = SD.open(DOSYA, FILE_WRITE);         // FILE_WRITE dosyayı sıfırlar / FILE_WRITE truncates
23    if (f) {
24      f.println("sure_s,isik_ham");
25      f.close();
26    }
27  }
28}
29
30void loop() {
31  File f = SD.open(DOSYA, FILE_APPEND);          // ESP32'de sona ekleme / append on ESP32
32  if (f) {
33    f.printf("%lu,%d\n", millis() / 1000, analogRead(34));   // GPIO34'teki LDR / LDR on GPIO34
34    f.close();
35  }
36  delay(5000);
37}

O código grava a cada 5 segundos o valor bruto (0–4095) de um LDR ligado ao GPIO 34. No ESP32 você nem precisa de um módulo RTC para ter a hora real: dá para conectar ao Wi-Fi, pegar a hora de um servidor NTP e acrescentar a data e a hora em cada linha com getLocalTime(). Se os fios forem longos ou o cartão estiver instável, reduza a velocidade do SPI: SD.begin(5, SPI, 1000000) inicia o cartão a 1 MHz. Em um registrador alimentado por bateria, usar deep sleep entre as leituras multiplica a autonomia.

ESP32 SD_MMC: a interface SD rápida e a ESP32-CAM

Além do SPI, o ESP32 também tem um controlador SDMMC que fala o protocolo rápido do próprio cartão. No modo de 4 bits, a biblioteca SD_MMC é várias vezes mais rápida que o SPI, o que a torna ideal para arquivos grandes, como fotos ou áudio. No ESP32 clássico os pinos são fixos: CLK GPIO 14, CMD GPIO 15, D0 GPIO 2, D1 GPIO 4, D2 GPIO 12, D3 GPIO 13, e essas linhas precisam de resistores de pull-up de 10 kΩ. No modo de 1 bit só CLK, CMD e D0 são usados; é mais lento, mas libera os GPIO 4, 12 e 13. O slot micro SD da placa ESP32-CAM está ligado a esses pinos, e usar o modo de 1 bit impede que o LED de flash no GPIO 4 pisque a cada acesso ao cartão.

1#include "FS.h"
2#include "SD_MMC.h"
3
4void setup() {
5  Serial.begin(115200);
6  // 1-bit mod: yalnız CLK 14, CMD 15, D0 2 / 1-bit mode: only CLK 14, CMD 15, D0 2
7  if (!SD_MMC.begin("/sdcard", true)) {
8    Serial.println("SD_MMC baglanamadi");        // kart bağlanamadı / mount failed
9    return;
10  }
11  Serial.printf("Bos alan: %llu MB\n", (SD_MMC.totalBytes() - SD_MMC.usedBytes()) / (1024 * 1024));
12
13  File f = SD_MMC.open("/gunluk.txt", FILE_APPEND);
14  if (f) {
15    f.println("ESP32-CAM acildi");               // açılış kaydı / boot log line
16    f.close();
17  }
18}
19
20void loop() {
21}

Cartão SD com o Raspberry Pi Pico (MicroPython)

No MicroPython, os cartões SD são controlados pelo driver sdcard.py do micropython-lib. Se você tem o mpremote no computador, instale-o com mpremote mip install sdcard, ou copie o arquivo para o Pico com o Thonny. O cartão é montado como a pasta /sd com os.mount() e, a partir daí, você o usa com os comandos comuns de arquivo do Python (open, write). O código abaixo lê o sensor de temperatura interno do Pico e grava uma linha CSV a cada 10 segundos. Se você está começando com o Pico, leia antes O que é o Raspberry Pi Pico?.

1from machine import Pin, SPI, ADC
2import os, time
3import sdcard                                    # micropython-lib sürücüsü / micropython-lib driver
4
5spi = SPI(0, baudrate=1000000, sck=Pin(18), mosi=Pin(19), miso=Pin(16))
6sd = sdcard.SDCard(spi, Pin(17, Pin.OUT))        # CS = GP17; kart yoksa OSError / OSError if no card
7os.mount(os.VfsFat(sd), "/sd")                   # kart artık /sd klasörü / the card is now the /sd folder
8
9sensor = ADC(4)                                  # dahili sıcaklık sensörü / internal temperature sensor
10DOSYA = "/sd/pico_log.csv"
11
12if "pico_log.csv" not in os.listdir("/sd"):      # yeni dosyaya başlık / header for a new file
13    with open(DOSYA, "w") as f:
14        f.write("tarih,saat,sicaklik_C\n")
15
16while True:
17    v = sensor.read_u16() * 3.3 / 65535
18    t = 27 - (v - 0.706) / 0.001721              # RP2040 veri sayfası formülü / RP2040 datasheet formula
19    y, ay, g, sa, dk, sn = time.localtime()[:6]
20    with open(DOSYA, "a") as f:                  # "a" = sona ekle / append
21        f.write("{:04d}-{:02d}-{:02d},{:02d}:{:02d}:{:02d},{:.1f}\n".format(y, ay, g, sa, dk, sn, t))
22    print(sa, dk, sn, t)
23    time.sleep(10)                               # 10 saniye bekle / wait 10 seconds

O Pico não tem relógio com bateria: quando está conectado ao Thonny, o relógio é acertado automaticamente pelo computador, mas funcionando sozinho ele começa em 1º de janeiro de 2021. Para ter data e hora precisas, você pode acrescentar um módulo DS3231 ou, no Pico W, pegar a hora da internet via NTP. Se não houver cartão no slot ou a ligação estiver errada, o driver gera OSError: no SD card (nenhum cartão SD). Se você programa o Pico pela Arduino IDE (core arduino-pico), pode usar a mesma abordagem da biblioteca SD; os pinos SPI0 padrão são os da tabela, e basta escrever SD.begin(17) para o CS.

Como evitar perda de dados: alimentação, frequência de gravação e vida útil do cartão

• Nada chega ao cartão sem close() ou flush(): a biblioteca primeiro junta os dados em um buffer de 512 bytes. Se você mantém o arquivo aberto o tempo todo, chame flush() a cada poucas linhas.
• Não tire o cartão durante a gravação: puxar o cartão ou cortar a alimentação no meio de uma gravação pode corromper o sistema de arquivos. Acrescentar um botão que para o registro e um LED que mostra que o registro está ativo é um bom hábito.
• Mantenha a alimentação firme: o cartão consome até 100 mA durante a gravação. Um capacitor de 10–100 µF entre o VCC e o GND do módulo reduz as quedas de tensão e os erros aleatórios de gravação.
• Não abra e feche com muita frequência: se você faz dezenas de leituras por segundo, abrir e fechar o arquivo a cada linha fica lento; guarde as leituras na RAM e grave em lotes de 10–20 linhas.
• Vida útil do cartão: os cartões SD espalham internamente as gravações por células diferentes (nivelamento de desgaste, ou wear leveling), então um registrador que grava algumas linhas por minuto não desgasta o cartão por anos. Mesmo assim, escolha um cartão de uma marca conhecida.
• Divida o arquivo: abrir um arquivo separado para cada dia (por exemplo, 20261104.CSV) mantém os arquivos pequenos e, se algo der errado, você perde só os dados daquele dia.

Ideias de projetos com módulo de cartão SD

• Registrador de estação meteorológica: grave temperatura, umidade e pressão a cada hora com um BME280 e monte o gráfico de uma estação do ano inteira.
• Diário de irrigação de plantas: grave as leituras do sensor de umidade do solo e os momentos em que a bomba liga para estudar o seu padrão de rega.
• Registrador de rotas GPS: salve em CSV o seu percurso de bicicleta ou de trilha com um GPS NEO-6M e depois mostre-o em um mapa.
• Registro de acesso por cartão: grave em um arquivo cada cartão lido por um leitor RFID RC522, junto com a data e a hora.
• Monitor de consumo de energia: meça e registre a corrente que um aparelho consome ao longo do dia com um sensor de corrente ACS712.
• Player de MP3: o DFPlayer Mini toca arquivos de áudio do seu próprio slot micro SD; o Arduino só envia os comandos.

Erros comuns e como resolvê-los

Um módulo de cartão SD transforma um projeto que só mede em um aparelho que guarda registros, e alguns dias de dados reais dizem muito mais do que uma leitura isolada jamais diria. No app BlueGrays você encontra o registrador de temperatura com ESP32, DHT22, RTC DS1307, micro SD e OLED, relógios digitais com RTC e projetos de temperatura e umidade, todos com esquema do circuito e código passo a passo.