ESP32 Tutorial: Flash Memory | Storing Data Permanently
Abstract
The Flash Memory is the non-volatile storage area of the ESP32, retaining data even when the power is off. This memory stores critical elements like the microcontroller’s main firmware (your sketch) and the ESP32 bootloader. Beyond system files, the Flash Memory is essential for user applications that require persistent data storage, such as Wi-Fi credentials, calibration settings, and large configuration files. This tutorial focuses on understanding the primary user-accessible Flash storage system in the Arduino environment: the Preferences library, which utilizes the underlying Non-Volatile Storage (NVS) module.
1. Introduction: Memory Types
The ESP32 chip contains several types of memory, but for storing user data permanently, Flash is key.
ESP32 Memory Map (Simplified)
Memory Type | Volatility | Typical Use |
RAM (SRAM) | Volatile (data lost on power off) | Program variables, stack, heap, Wi-Fi buffers |
Flash Memory | Non-Volatile (data retained) | Firmware (Sketch), Filesystem (SPIFFS/LittleFS), NVS Data |
ROM | Non-Volatile (Read-Only) | Initial bootloader code |
The ESP32 modules (like the ESP-WROOM-32) come with 4MB or more of external SPI Flash memory. This memory is partitioned to store different components:
- Bootloader & Partition Table: Core system components.
- Application (App): Your compiled Arduino sketch.
- Filesystem (e.g., LittleFS): For storing files like web pages or configuration documents.
- NVS (Non-Volatile Storage): The primary area for small, key-value data storage (covered here).
2. Storing Small Data: The Preferences (NVS) Library
For saving small pieces of configuration data (like an integer count, a floating-point sensor calibration value, or a string for a Wi-Fi SSID/password), the ESP32 uses the Non-Volatile Storage (NVS) system. The Arduino framework simplifies access to NVS using the Preferences library.
2.1 NVS Key-Value Concept
The NVS system stores data as key-value pairs, similar to a dictionary:
- Namespace: A container to group related key-value pairs (e.g., wifi_config).
- Key: A unique string identifier (e.g., ssid, password, boot_count).
- Value: The actual data (e.g., MyHomeNetwork, 12345678, 42).
2.2 Core Functions for NVS Access
To use NVS, you need to include the library and follow three steps: begin the partition, write/read data, and end the partition.
- Include: #include “Preferences.h”
- Object: Create a Preferences object: Preferences preferences;
Step | Function | Purpose |
Begin | preferences.begin(“namespace”, read_only) | Mounts the partition under a namespace. false for writing. |
Write | preferences.putInt(“key”, value) | Writes data to Flash (e.g., putInt, putString, putFloat). |
Read | preferences.getInt(“key”, default_val) | Reads data from Flash. Returns default_val if the key doesn’t exist. |
End | preferences.end() | Closes the partition, flushing any pending writes. |
3. Hands-On Lab: Persisting a Boot Counter
This lab demonstrates how to use the Preferences library to keep track of how many times the ESP32 has been powered on or reset.
ESP32 Flash Memory (NVS) Code Example
#include "Preferences.h"
Preferences preferences;
void setup() {
Serial.begin(115200);
delay(1000);
Serial.println("\n--- ESP32 NVS Boot Counter ---");
// A variable to hold the counter
int bootCount = 0;
// 1. Open NVS in read/write mode under the "system" namespace
// The namespace name must be 15 characters max.
preferences.begin("system", false);
// 2. Read the current boot count. If it doesn't exist, return 0.
bootCount = preferences.getInt("boot_count", 0);
// Increment the counter
bootCount++;
// 3. Write the new value back to NVS
preferences.putInt("boot_count", bootCount);
// 4. Close the NVS partition
preferences.end();
// Report the result
Serial.print("The ESP32 has booted ");
Serial.print(bootCount);
Serial.println(" times.");
}
void loop() {
// Main program logic runs here.
// Press the EN (Reset) button to see the counter increase.
delay(1000);
}
Execution Steps
- Upload the sketch to your ESP32.
- Open the Serial Monitor. It should display: “The ESP32 has booted 1 times.”
- Press the EN (Reset) button on the board. The ESP32 will reboot, and the Serial Monitor will now show: “The ESP32 has booted 2 times.”
- Power cycle or reset the ESP32. The counter will continue from the last saved number, proving the data is stored in non-volatile Flash Memory.
4. Lab Recap
You’ve learned the fundamentals of permanent data storage on the ESP32:
- The ESP32 stores firmware and persistent user data in Non-Volatile Flash Memory.
- For small, key-value configuration data, the Preferences library (which accesses the underlying NVS system) is the standard method.
- To use NVS, you must begin(), use ..() to write or get…() to read, and end() the partition.
- Large file storage requires using a filesystem like LittleFS (formerly SPIFFS), which is accessed via the h library (a topic for a separate tutorial).
