This example shows how to store your project configuration in a file. It uses the SD library but can be easily modified for any other file-system, like SPIFFS.

The file contains a JSON document with the following content:

  "hostname": "",
  "port": 2731

As you’ll see, we’ll extract the configuration in a custom Config structure, to follow the recommended usage of the library. If you’re curious about that, please read: Why should I create a separate config object?

Source code

#include <ArduinoJson.h>
#include <SD.h>
#include <SPI.h>

// Our configuration structure.
struct Config {
  char hostname[64];
  int port;

const char* filename = "/config.txt";  // <- SD library uses 8.3 filenames
Config config;                         // <- global configuration object

// Loads the configuration from a file
void loadConfiguration(const char* filename, Config& config) {
  // Open file for reading
  File file =;

  // Allocate a temporary JsonDocument
  JsonDocument doc;

  // Deserialize the JSON document
  DeserializationError error = deserializeJson(doc, file);
  if (error)
    Serial.println(F("Failed to read file, using default configuration"));

  // Copy values from the JsonDocument to the Config
  config.port = doc["port"] | 2731;
  strlcpy(config.hostname,                  // <- destination
          doc["hostname"] | "",  // <- source
          sizeof(config.hostname));         // <- destination's capacity

  // Close the file (Curiously, File's destructor doesn't close the file)

// Saves the configuration to a file
void saveConfiguration(const char* filename, const Config& config) {
  // Delete existing file, otherwise the configuration is appended to the file

  // Open file for writing
  File file =, FILE_WRITE);
  if (!file) {
    Serial.println(F("Failed to create file"));

  // Allocate a temporary JsonDocument
  JsonDocument doc;

  // Set the values in the document
  doc["hostname"] = config.hostname;
  doc["port"] = config.port;

  // Serialize JSON to file
  if (serializeJson(doc, file) == 0) {
    Serial.println(F("Failed to write to file"));

  // Close the file

// Prints the content of a file to the Serial
void printFile(const char* filename) {
  // Open file for reading
  File file =;
  if (!file) {
    Serial.println(F("Failed to read file"));

  // Extract each characters by one by one
  while (file.available()) {

  // Close the file

void setup() {
  // Initialize serial port
  while (!Serial)

  // Initialize SD library
  const int chipSelect = 4;
  while (!SD.begin(chipSelect)) {
    Serial.println(F("Failed to initialize SD library"));

  // Should load default config if run for the first time
  Serial.println(F("Loading configuration..."));
  loadConfiguration(filename, config);

  // Create configuration file
  Serial.println(F("Saving configuration..."));
  saveConfiguration(filename, config);

  // Dump config file
  Serial.println(F("Print config file..."));

void loop() {
  // not used in this example

Performance issues? See How to improve (de)serialization speed?

Things used in this example




See also