SdFat: faster SD card files with more control
SdFat is the library the Arduino SD library was originally built from, and Bill Greiman still maintains it. People move to it for speed (it can clock the SPI bus higher and use dedicated SPI), for FAT32 and exFAT on big cards, long file names, and for finer control over how files are opened and synced, which matters for fast loggers.
Built in on Mokxi: #include <SdFat.h> and it builds, with nothing to install. Free, and no account needed.
What SdFat does
Setup is more explicit than SD.h. You make an SdFat (or SdFs, which handles FAT and exFAT) object and call begin() with an SdSpiConfig that names the chip select pin, whether the SPI bus is shared, and the clock speed. Files are File32 for FAT or FsFile for either, and open() takes POSIX-style flags such as O_RDWR | O_CREAT | O_AT_END.
For a logger, open the file once, write lines, and call sync() every so often instead of closing and reopening: that keeps the directory entry up to date without the cost of a full open each time.
| Library Manager name | SdFat |
|---|---|
| Author | Bill Greiman |
| Include | #include <SdFat.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Runs, with a gap the note below names. |
| Parts it drives | microSD card module |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <SdFat.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "SdFat" by Bill Greiman from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add SdFat to lib_deps in PlatformIO. Mokxi follows the calls of release 2.3.1, so a sketch written here builds there too.
What to know in the simulator: It runs on SD.h鈥檚 FAT16 driver, so names are 8.3 and exFAT, rename() and truncate() are not here.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
SdFat sd
The card and file system. SdFs sd; works with FAT and exFAT cards in upstream SdFat.
sd.begin(SdSpiConfig(10, DEDICATED_SPI, SD_SCK_MHZ(16)))
Starts the card on chip select 10 with the SPI bus to itself at 16 MHz. Use SHARED_SPI when other devices sit on the bus.
if (!sd.begin(SdSpiConfig(10, DEDICATED_SPI, SD_SCK_MHZ(16)))) {
sd.initErrorHalt(&Serial);
}sd.initErrorHalt(&Serial)
Prints why begin() failed, with an error code, and stops. Handy while wiring a new module.
file.open("log.txt", O_RDWR | O_CREAT | O_AT_END)
Opens a File32 or FsFile for reading and writing, creating it and positioning at the end for appending. Returns false on failure.
file.println(value)
Writes a line through Print, as with Serial.
file.sync()
Writes buffered data and the file size to the card without closing, so a logger can keep the file open safely.
file.fileSize()
The file鈥檚 length in bytes.
sd.ls(LS_SIZE)
Lists the root directory to Serial, here with each file鈥檚 size.
Example: Write a log file with SdFat and list the card
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <SdFat.h>
const uint8_t SD_CS_PIN = 10;
SdFat sd;
File32 file;
void setup() {
Serial.begin(9600);
if (!sd.begin(SdSpiConfig(SD_CS_PIN, DEDICATED_SPI, SD_SCK_MHZ(16)))) {
sd.initErrorHalt(&Serial);
}
if (!file.open("LOG.TXT", O_RDWR | O_CREAT | O_TRUNC)) {
sd.errorHalt("open failed");
}
file.println("temperature,21.5");
file.println("temperature,21.7");
Serial.print("size ");
Serial.println(file.fileSize());
file.close();
file.open("LOG.TXT", O_RDONLY);
char line[32];
file.fgets(line, sizeof(line));
Serial.print("first line ");
Serial.print(line);
file.close();
sd.ls(LS_SIZE);
}
void loop() {}Wiring
- Arduino Uno R3 10 to microSD card module CS
- Arduino Uno R3 11 to microSD card module MOSI
- Arduino Uno R3 12 to microSD card module MISO
- Arduino Uno R3 13 to microSD card module SCK
- Arduino Uno R3 5V to microSD card module VCC
- Arduino Uno R3 GND to microSD card module GND
Common errors and how to fix them
sd.begin() fails at 50 MHz but the card is fine
Long jumper wires and breadboards cannot carry the fastest SPI clocks. Lower SD_SCK_MHZ() to 16 or 4; once it works, raise it step by step to find what the wiring allows.
'File' is ambiguous or redefined when SD.h is also included
SdFat and SD.h both declare a File type. Include one of them, not both, and use File32 or FsFile with SdFat so the type is clear.
In Mokxi a long file name or rename() does not work
Mokxi runs SdFat on the SD library鈥檚 FAT16 driver, so names are 8.3 and exFAT, rename() and truncate() are missing. Keep names short in the simulator; on a real board upstream SdFat handles all three.
Keep going
Parts
Try SdFat without installing anything
Open the example, change the sketch, and keep your version in a free account.