Library for logging to SD card: SdCardLogHandlerRK


The official location and documentation for this library is:

It’s in the Particle community libraries as: SdCardLogHandlerRK.

You’ll need a SD card reader, presumably a Micro SD card reader. Make sure you get one that’s compatible with the 3.3V logic levels used on the Photon and Electron. Some readers designed for the Arduino expect the 5V logic levels used by the original Arduino. I use this one from Sparkfun but there are others.


This library uses the Logging API that was added in system firmware 0.6.0.

For example:

Log.trace("Low level debugging message");"This is info message");
Log.warn("This is warning message");
Log.error("This is error message");"System version: %s", System.version().c_str());

It does not remap Serial, so if you’re using Serial.print for logging, you should switch to using instead.

The library creates a directory (default: “logs”) at the top level of the SD card and stores the log files in that. Each log file is a .txt file 6-digit number beginning with 000001.txt.

The default log file is 1 MB (1000000 bytes), but you can reconfigure this. The actual size will be slightly larger than that, as the log is rotated when it exceeds the limit, and the file will always contain a whole log entry.

When rotated, the default is to keep 10 log files, but this is configurable. The oldest is deleted when the maximum number is reached.

By default, SdCardLogHandler writes to Serial as well, like SerialLogHandler. This can be reconfigured.

This is the example program:

#include "Particle.h"

#include "SdFat.h"
#include "SdCardLogHandlerRK.h"


const int SD_CHIP_SELECT = A2;
SdFat sd;

SdCardLogHandler logHandler(sd, SD_CHIP_SELECT, SPI_FULL_SPEED);

size_t counter = 0;

void setup() {

void loop() {"testing counter=%d", counter++);

The full browsable API documentation is here.

Adafruit SSD1306 [SOLVED]
Need Suggestion for external Cell and GPS antennas locations
How to print SD Card Success / Fail to OLED

Using this library couldn’t be simpler. Thank you Rick for the efforts.
I have a question related to repurposing its use to data logging. Can I use this API concurrently with another instance of the logger object?
If I want to use logger over Serial as usual:
SerialLogHandler logHandler(115200, LOG_LEVEL_WARN, {
{ "app", LOG_LEVEL_INFO },
{ "app.custom", LOG_LEVEL_INFO }

and then add an instance of your object to log geo-location data for example:

SdCardLogHandler logHandler2(sd, SD_CHIP_SELECT, SPI_FULL_SPEED);

How do I direct data to each logger?"GNSS fix age=%d ms", gnss_last_fix_ms - millis()); --> I want this to go over Serial"{\"s_id\": %d, \"spd\": %f,\"lat\": %f,\"lon\": %f}, session_id, speed_mph, lat, lon); --> I want this written to an SD file


Thanks! Yes, you can have multiple log handlers. Here’s an example that uses both Serial and SD card loggers, and you choose which to log to using the categories feature.

#include "Particle.h"

#include "SdFat.h"
#include "SdCardLogHandlerRK.h"


const int SD_CHIP_SELECT = A2;
SdFat sd;

// Only log errors and info level log messages to the SD card
// Turn off serial logging in the SdCardLogHandler to avoid logging twice

// Use instead of, etc. to write to the SD card
Logger LogToSD("");

// Log everything to Serial
SerialLogHandler serialLogHandler;

size_t counter = 0;

void setup() {

void loop() {"testing counter=%d", counter++);"write to SD counter=%d", counter++);



Great! thank you.


Thank you thank you thank you! You just saved me a crap load of work and frustration. I was going to tackle SD card logging this week for a urgent project.


I am looking for some newbie help. I have hit a wall with what I assume is a simple task. I have been able to log data to an Sd card with the help of the above post. What I can’t seem to do is get multiple entries in one line with a comma separator.

I would like my data to post as Data + Comma + Time Stamp. This is so I can export to excel.

I can log them as separate lines but can’t seem to get the right code correct to get them on one line.

Here is my part of the code.

Serial.printf(“Flow: %.1f”, flow);“Flow: %.1f”, flow); // Had one line with flow: Example: INFO: Flow: -0.1; // Next line had time and date. Example: INFO: Thu May 24 22:13:07 2018

Sorry in advance if this is obvious. I have been trying for 3 days now and just can’t seem to get it right.


It’s easy, but I wouldn’t say obvious:“%s,Flow: %.1f”, Time.timeStr().c_str(), flow); 


Thank you so much sir. I will try it now.

BTW your example and code could not be easier to follow. As I stated I am a complete rookie at all this. But I was able to log your test to the sd card on the first try. Then for some miracle was able to add it to my 4-20 ma code and log that as well… Then I got stuck trying to be fancy. lol.


In the event that someone stumbles across this question this is the line of code I used.",%s, %.1f", Time.timeStr().c_str(), flow);

This gives me the following on my SD Card.

0004291877 [app] INFO: ,Tue May 29 14:25:32 2018, 0.1

I was able to add a comma before the %s at the beginning of the code. This lets me separate the default initial [app] INFO: from the date time, and data. This way I can import the data to excel using comma separated format.

This may not be the correct way of doing this but I used Ricks code and trial and error until I got it. Now I just need to learn how to convert a JSON string to a string, I may need a few bottles of wine for that.



Happy Friday Particle People.

Would anyone following this thread mind posting a sniped of the code they use to serial print the debug error messages and status messages they use with this library?

I know it says use Serial.printlnf at the top of the .cpp file for debug and I have been trying to get it done by trial and error but just cant seem to get it. The long term goal here is to print the status of the SD Card to my OLED screen on my project. If I can print the message to serial then I know how to print it to my OLED… but that’s about it.

Here are the goal messages I want to print, or a version of the following.

Writing to SD Success
Writing to SD Failed
No Card Found,
Or Card Ejected.
Wow your really handsome… ok that last one is a joke.

I figure I can convert the debug message but just can’t seem to get the code correct to print them to serial.

Any help is greatly appreciated.

Thank you,


I released version 0.0.5 of SdCardLogHandler. The new version updates to a version of SdFat that is compatible with mesh devices. It also refactors the code into two classes.

The new SdCardPrintHandler works just like the log handler, but isn’t a log handler. You can use it to print arbitrary text data to rotating log files of a maximum size, without getting log data mixed in. It’s a subclass of the Print class, so all of the overloads of print, println, printf, and printlnf can all be used to write to your file.

The data is written to the card whenever a \n in encountered (or the buffer is full) so as long as you write lines of less than 128 bytes, you won’t run into a situation where a line gets split across multiple files.