【产出】 > 用 Arduino-ESP32 的 Preferences 库把设备配置(Wi-Fi 账号、校准系数、运行计数等)存进 Flash,断电重启后自动读回;同时知道它底层的 NVS 怎么工作、写多频繁会伤 Flash、怎样恢复出厂设置。
【版本】 > 依据 arduino-esp32 官方文档"Preferences"API 参考与"Preferences 教程"、github.com/espressif/arduino-esp32 中 Preferences.h/.cpp 源码和 StartCounter 例程,以及 ESP-IDF 编程指南稳定版 v6.1"非易失性存储库(NVS)"一章编写,适用于 arduino-esp32 3.x,所有 ESP32 系列芯片通用。
一、为什么用 Preferences,而不是 EEPROM
ESP32 没有真正的 EEPROM,数据只能存在外部 SPI Flash 里。Flash 有两个麻烦:写之前必须按扇区(4096 字节)整块擦除;每个扇区能擦的次数有限。直接拿 Flash 当 EEPROM 用,改一个字节就要擦一整个扇区,既慢又伤寿命。
乐鑫在 ESP-IDF 里提供了 NVS(Non-Volatile Storage,非易失性存储)库专门解决这个问题。arduino-esp32 的 Preferences 库是 NVS 的一层薄封装,官方文档明确说它应被视为 Arduino EEPROM 库的替代品。
| 对比项 | Preferences / NVS | 直接操作 Flash 扇区 |
|---|---|---|
| 数据组织 | 命名空间 + 键值对,按名字读写 | 自己管理地址和格式 |
| 磨损均衡 | 内置 | 需要自己做 |
| 掉电时写到一半 | 有恢复机制 | 数据可能损坏 |
| 适合的数据 | 大量小数据:配置项、计数器、标志位 | — |
【提示】 > 官方建议:Preferences 适合存很多个小值,不适合存少数几个大值。要存日志、图片、大段 JSON,用 LittleFS 等文件系统。NVS 底层对字符串的上限是 4000 字节(含结尾的
\0)。
二、命名空间和键
Preferences 的数据按两级组织:
NVS 分区(默认分区名 "nvs")
├── 命名空间 "wifi"
│ ├── 键 "ssid" → "MyHome"
│ └── 键 "pass" → "12345678"
└── 命名空间 "calib"
├── 键 "offset" → -0.35
└── 键 "gain" → 1.02
规则:
- 命名空间名和键名都是 ASCII 字符串,最长 15 个字符。超长时操作失败。
- 不同命名空间里可以有同名的键,互不干扰。所以每个功能模块用一个自己的命名空间,可以避免键名冲突。
- 一个 NVS 分区里最多 254 个命名空间。
- 同一个
Preferences对象同一时间只能打开一个命名空间,要换就先end()再begin()另一个。
三、基本流程:begin → put/get → end
bool begin(const char *name, bool readOnly = false, const char *partition_label = NULL);
void end();
| 参数 | 含义 |
|---|---|
name | 命名空间名。读写模式下不存在会自动创建 |
readOnly | false(默认)读写;true 只读,此时所有写操作都会失败 |
partition_label | NVS 分区名,省略时使用名为 nvs 的默认分区 |
官方教程推荐的习惯是:只读的时候用只读模式打开,要写的时候才用读写模式,用完马上 end()。
最小示例,官方 StartCounter 例程的思路:记录开机次数,每次上电加一。
#include <Preferences.h>
Preferences prefs;
void setup() {
Serial.begin(115200);
prefs.begin("my-app", false); // 读写模式打开
uint32_t counter = prefs.getUInt("counter", 0); // 键不存在时返回默认值 0
counter++;
prefs.putUInt("counter", counter);
prefs.end();
Serial.printf("这是第 %u 次启动\n", counter);
}
void loop() {
}
烧进去后多按几次 EN 键或者拔插电源,计数会一直累加,不会归零。
四、支持的数据类型
| 类型名(用于 putX/getX) | C 类型 | 字节数 | getX 默认返回值 |
|---|---|---|---|
Bool | bool | 1 | false |
Char / UChar | int8_t / uint8_t | 1 | 0 |
Short / UShort | int16_t / uint16_t | 2 | 0 |
Int / UInt | int32_t / uint32_t | 4 | 0 |
Long / ULong | int32_t / uint32_t | 4 | 0 |
Long64 / ULong64 | int64_t / uint64_t | 8 | 0 |
Float | float_t | 4 | NAN |
Double | double_t | 8 | NAN |
String | const char* 或 Arduino String | 可变 | 空字符串 |
Bytes | 任意字节 | 可变 | — |
注意 Long 在 ESP32 上就是 32 位,要 64 位整数用 Long64。
put 和 get 的类型必须一致。用 putInt 存进去的,就要用 getInt 读。用 putUInt 存再用 getInt 读,底层 NVS 会按类型匹配失败,返回默认值。不确定某个键存的是什么类型时,可以用 getType(key) 查询,返回值是 PT_I8、PT_U32、PT_STR、PT_BLOB 等枚举,失败返回 PT_INVALID。
putX 返回写入的字节数,失败返回 0。需要确认写入成功的场合,检查一下这个返回值。
五、getX 的默认值:如何区分"没存过"和"存的就是 0"
每个 getX 都有第二个参数作为默认值。键不存在或读取出错时返回这个默认值:
float k = prefs.getFloat("gain", 1.0f); // 没校准过就用 1.0
问题是,如果默认值本身也是合法值,你就分不清是"读到了"还是"出错了"。两种处理办法:
- 选一个不可能出现的值做默认值,比如温度偏移不可能是 -9999,就用它当默认值,返回 -9999 就说明没读到。
- 先用
isKey(key)判断键是否存在,存在再读。
if (prefs.isKey("gain")) {
gain = prefs.getFloat("gain");
} else {
Serial.println("未校准,使用默认增益");
}
六、字符串和字节数组
字符串有两种读法:
// 1. 读成 Arduino String,最省事
String ssid = prefs.getString("ssid", "");
// 2. 读进 char 数组,不用堆内存
char buf[33];
size_t n = prefs.getString("ssid", buf, sizeof(buf));
第二种写法要求缓冲区长度不小于存储的字节数(含结尾 \0),否则读取失败。不确定长度时,先用 getStringLength(key) 查。
结构体可以整个当字节数组存,读的时候用 getBytesLength() 校验长度:
struct Calib {
float offset;
float gain;
uint16_t version;
};
void saveCalib(const Calib &c) {
prefs.begin("calib", false);
prefs.putBytes("data", &c, sizeof(c));
prefs.end();
}
bool loadCalib(Calib &c) {
prefs.begin("calib", true);
bool ok = prefs.getBytesLength("data") == sizeof(c) &&
prefs.getBytes("data", &c, sizeof(c)) == sizeof(c);
prefs.end();
return ok;
}
getBytesLength() == sizeof(c) 这一步检查很有用:以后给结构体加了字段,旧固件存的数据长度就对不上,loadCalib 返回 false,程序可以回落到默认值,而不是把错位的数据当真。
【注意】 > 字节数组是按内存原样存的,读回来必须用同样的类型和布局解释。同一份数据要在不同编译器或芯片之间共享时,不要直接存结构体,改成逐个字段存。
七、完整示例:首次运行写出厂默认值
官方教程给出的做法是:用一个专门的"已初始化"键判断是不是第一次运行。下面在此基础上整理成可直接使用的配置模块:
#include <Preferences.h>
Preferences cfg;
uint8_t brightness;
uint32_t reportInterval; // 秒
String deviceName;
void loadConfig() {
cfg.begin("appcfg", false); // 读写打开,命名空间不存在会自动创建
if (!cfg.isKey("inited")) {
// 第一次运行:写入出厂默认值
cfg.putUChar("bright", 50);
cfg.putUInt("interval", 60);
cfg.putString("name", "esp32-node");
cfg.putBool("inited", true);
Serial.println("首次运行,已写入默认配置");
}
brightness = cfg.getUChar("bright", 50);
reportInterval = cfg.getUInt("interval", 60);
deviceName = cfg.getString("name", "esp32-node");
cfg.end();
}
void setBrightness(uint8_t v) {
if (v == brightness) return; // 值没变就不写,省 Flash 寿命
brightness = v;
cfg.begin("appcfg", false);
cfg.putUChar("bright", v);
cfg.end();
}
void factoryReset() {
cfg.begin("appcfg", false);
cfg.clear(); // 清空这个命名空间里的所有键
cfg.end();
ESP.restart(); // 重启后 loadConfig 会重新写默认值
}
void setup() {
Serial.begin(115200);
loadConfig();
Serial.printf("设备名=%s 亮度=%u 上报间隔=%u 秒\n",
deviceName.c_str(), brightness, reportInterval);
}
void loop() {
}
为什么第一次要用读写模式打开:底层 nvs_open() 用只读模式打开一个还不存在的命名空间时,会返回"未找到"错误,begin() 返回 false。官方教程里先只读打开再判断的写法同样可以工作(打开失败时 isKey() 返回 false,随后会以读写模式重新打开),但直接用读写模式更直白。
删除相关的几个函数:
| 函数 | 作用 |
|---|---|
remove(key) | 删除当前命名空间里的一个键 |
clear() | 删除当前命名空间里的所有键,命名空间本身还在 |
freeEntries() | 查询剩余可用条目数,判断空间是否快用完 |
Preferences 没有删除整个命名空间的函数。
八、写入寿命:NVS 帮你做了什么,你还要注意什么
NVS 的存储方式是追加写日志:更新一个键时,不在原地覆盖,而是把新值写到空闲区域的末尾,旧值只标记为"已删除"。一个 4096 字节的页(对应一个 Flash 扇区)里有 126 个 32 字节的条目,页写满了才整理、擦除。官方文档的说法是,这种组织方式让占一个条目的数据类型的擦除次数比写入次数少 126 倍左右。
各类型占用的条目数(来自 freeEntries() 的官方说明):
| 数据类型 | 占用条目 |
|---|---|
| 整数类、Bool | 1 个 |
| Float、Double | 3 个 |
| String | 至少 2 个,随长度增加 |
| Bytes | 至少 3 个,随长度增加 |
所以小整数是最省寿命的,频繁变化的数据尽量用整数存(比如温度乘 100 存成 int32_t)。
磨损均衡只是把擦除摊开,并不能让写入次数无限。工程上的做法:
| 做法 | 原因 |
|---|---|
| 值没变就不写 | 每次 putX 都会追加一条新记录,即使值相同(见第七节 setBrightness) |
不要在 loop() 里高频写 | 例如每 100 ms 存一次计数,几天就能写出上百万条记录 |
| 合并写入 | 数据先放在 RAM,定时(如每 10 分钟)或在关键事件时才写一次 |
| 和深度睡眠配合 | 每次唤醒都要更新的计数,优先放 RTC 内存(RTC_DATA_ATTR),只在必要时同步到 NVS |
| 实时性很强的计数 | 考虑外接 FRAM 等擦写寿命高的存储器 |
Flash 芯片本身能擦写多少次,以模组所用 Flash 的规格书为准。
【注意】 > Preferences 的每个
putX内部都会立刻调用nvs_commit()提交,调用返回时数据已经写进 Flash。这意味着每次putX都是一次真实的 Flash 写入,不存在"先缓存、最后一起提交"的批量优化。
九、供电不稳和分区相关的问题
- 电池、太阳能等不稳定供电:官方文档提到,Flash 擦除可能在不被察觉的情况下没有完成,极端情况下会耗尽空闲页,初始化时报
ESP_ERR_NVS_NO_FREE_PAGES。可以在 ESP-IDF 的 menuconfig 里打开CONFIG_NVS_FLASH_VERIFY_ERASE,让 NVS 擦除后回读校验(Arduino IDE 里无法直接改这个选项,需要用 ESP-IDF 或把 Arduino 作为 IDF 组件编译)。重要的出厂数据建议放在单独的只读分区。 - 改了分区表之后:NVS 分区被截断或移动后,原有内容应当擦除。ESP-IDF 下用
idf.py -p PORT erase-flash擦全片。 - 键越多启动越慢:NVS 初始化耗时和键的数量成正比,官方给出的量级是每 1000 个键约 0.5 秒。
- NVS 最小尺寸:默认要求至少 12 KiB(3 个页)。自定义分区表时不要把 nvs 分区设得比这还小。
十、彻底清空 NVS
clear() 只能清一个命名空间。要把整个 NVS 分区连同所有命名空间一起清掉(包括 Wi-Fi 库自动保存的连接信息),官方教程给出的方法是烧一个专门的程序:
#include <nvs_flash.h>
void setup() {
nvs_flash_erase(); // 擦除默认 NVS 分区
nvs_flash_init(); // 重新初始化
while (true);
}
void loop() {
}
【注意】 > 运行一次后要马上烧回正常程序。否则板子每次上电都会把 NVS 清空一遍。
十一、常见问题
| 现象 | 原因与处理 |
|---|---|
| 读出来总是默认值 | 命名空间名或键名拼写不一致;put/get 类型不一致;名字超过 15 个字符 |
putX 返回 0 | 命名空间以只读模式打开;没有调用 begin();或空间已满,用 freeEntries() 查 |
begin() 返回 false | 以只读模式打开了不存在的命名空间;指定的分区名不存在 |
| 重新烧录后配置还在 | 正常现象。普通烧录只写程序区,不动 NVS 分区;要清空见第十节 |
| 字符串读取失败 | char 缓冲区比存储长度小,先用 getStringLength() |
| 运行几个月后 Flash 出错 | 写得太频繁,按第八节减少写入 |
参考资料
- arduino-esp32 Preferences API:https://docs.espressif.com/projects/arduino-esp32/en/latest/api/preferences.html
- arduino-esp32 Preferences 教程:https://docs.espressif.com/projects/arduino-esp32/en/latest/tutorials/preferences.html
- Preferences 库源码与 StartCounter 例程:https://github.com/espressif/arduino-esp32/tree/master/libraries/Preferences
- ESP-IDF 非易失性存储库(NVS):https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/storage/nvs_flash.html
评价 (0)