1. EEPROM 功能库能存什么:一条掉电就归零的配置
去年给一台小设备做标定,参数放在 RAM 的一个结构体里,每次断电重启都得重新接串口敲一遍,现场没人愿意干第二次。后来换成 Arduino 自带的 EEPROM 功能库,把整个结构体一次性写入片上 eeprom,上电再用 EEPROM.get 读回来直接送进业务逻辑,这件事才算解决。它要解决的并不是“存文件”的问题:把几十到几百字节的配置、标定值、设备编号在掉电后留住,按字节寻址,没有文件系统,也没有键值概念,你给一个起始地址,它就从那个地址往后连续写。适合做参数缓存、开机计数、校准表;不适合当日志盘,也不适合每秒写一次的数据通道,擦写寿命和单次写入耗时都不允许。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 结构体能不能直接塞进 EEPROM 功能库:字节记录、对齐与板型边界
动手写之前,必须先回答一个问题:EEPROM.put 到底把什么东西写进去了。这个答案决定了后面所有地址怎么算、结构体能不能改、换块板子还能不能跑。很多人第一次用这个库,觉得“结构体一塞就完事”,等改了一个成员类型,读回来变成 nan,才开始回头补这一课。
2.1 EEPROM.put 和 EEPROM.get 是按内存布局逐字节写入和读取,并不做序列化
EEPROM.put(eeAddress, customVar) 做的事情很朴素:从 eeAddress 这个单元开始,把 customVar 在内存里的字节,按内存里的顺序一个字节一个字节写到 EEPROM 的连续单元里。EEPROM.get(eeAddress, customVar) 就是反向操作,从同一个地址开始,按同样的字节数填回内存中的结构体。
这个过程里没有任何元数据:没有类型标记,没有长度字段,没有校验和,也没有分隔符。EEPROM 里留下的只是字节本身,哪些字节是 char、哪些是 float、哪个是 int,全靠你读的时候用的那个结构体定义去解释。这意味着“能不能读对”不取决于库,而取决于两件事:写的时候结构体是什么样,读的时候结构体是不是一模一样。成员顺序变了、类型从 int 换成 long、数组长度从 15 改成 20,甚至只是编译器换了个对齐策略,读出来的东西就立刻偏离预期。
对齐这件事值得单独说一句。在 UNO 这类 8 位 AVR 上,成员对齐要求宽松,sizeof(MyObject) 往往就等于各成员大小相加,所以下面的字节记录是整齐的;换到 32 位板子上,编译器为了让 float、int 落在对齐边界上,会在 char 数组后面插入填充字节,sizeof 就比成员之和更大。此时同样的 put 代码写进去的字节排布已经变了,跨板子搬 EEPROM 内容、或者同一块板子换了编译选项,都可能对不上。血泪经验是:结构体直接 put 只适合“同一块板、同一份代码、同一版编译器”的闭环场景。
2.2 一份能对得上的字节记录
以材料里的结构体为例,写入顺序是“先一个 float,再整个结构体”:
| 写入对象 | 起始地址 | 占用字节 | 地址区间 | 说明 |
|---|---|---|---|---|
float f |
0 | 4 | 0–3 | 单独存的浮点数,sizeof(float) 为 4 |
name[15] |
4 | 15 | 4–18 | 结构体第一个成员,14 字符 + 终止符刚好填满 |
field1(float) |
19 | 4 | 19–22 | 紧跟 name 之后 |
field2(int) |
23 | 2 | 23–26 | AVR 上 int 是 2 字节 |
Height(byte) |
27 | 1 | 27 | 收尾 |
整块结构体占 sizeof(MyObject),在 UNO 上是 15 + 4 + 2 + 1 = 22 字节,从地址 4 写到地址 26。这份表不是让你背下来,而是让你明白一件事:地址是靠 sizeof 累加出来的,不是靠手算数字猜出来的。写入代码里那句 eeAddress += sizeof(float); 就是这个意思——先把地址推到 float 之后,结构体从这里开始落。读取代码里同样有一句 eeAddress = sizeof(float);,也是同一个意思,两边必须严格对应。
也正是这份表,解释了后面读取程序里那段 for (int j = 4; j < 19; j++):起点 4 是 name 的偏移,终点 19 正好是 4 + 15,也就是 name 数组的第一个字节到最后一个字节。
2.3 板型边界:ESP8266 上这条路径行不通
材料里那句注释说得很直白:这个示例不适用于在 ESP8266 上使用 EEPROM.put() 或者 EEPROM.get() 对数据读写。这不是“可能有问题”,是明确的前置条件。所以这套写法的适用前提得先列清楚:
- 主控是 UNO 这类 AVR 板,用的是 Arduino 官方
EEPROM.h; - 数据量是几十字节级别,不是几百 KB;
- 写入频率低,开机读一次、参数变更时写一次,而不是循环里反复写;
- 结构体布局在固件版本之间保持不变,或者变更时有清空重写的手段。
换板子之前,先确认目标板的 EEPROM 实现到底支持不支持 put/get。不支持的话,退回到 EEPROM.read / EEPROM.write 逐字节搬运——机制还是那一套,只是你要自己维护偏移量,把“结构体本身”降级成“一串字节”。别把 UNO 上的脚本原样烧到另一块板子上然后怀疑人生,这种翻车我见过不止一次。
2.4 选型:几十字节的配置为什么落在片上 EEPROM
同样的需求,能选的方案不止一个。存在 SD 卡上,要多一个卡座、要文件系统、要处理挂载失败和磨损;挂外部 I2C EEPROM,要多两颗器件、多一路总线、多一层地址冲突排查;用后备电池保 RAM,掉电保持依赖电池,电池没了数据也没了。片上 EEPROM 的优势是“零外围、零协议、零依赖”——#include <EEPROM.h> 之后就能写,代码量以行计。
代价也要说清楚:容量小、写入慢、擦写寿命有限,而且没有 wear leveling,你写同一个地址一百次,磨损就集中在那几个单元上。所以它适合“少量、低频、关键”的数据,而不是“写得多、丢一点也无所谓”的数据。这个取舍想明白了,后面地址管理、版本控制、回读校验才有必要做,也才知道做到什么程度就够。
3. 写入实战:清空、分地址写入与串口验证
写入这一步看着最简单,其实最容易留下“当时看着对、隔天读不对”的隐患。下面按材料里的存储程序完整走一遍,从清空到落盘到打印核对。
3.1 先清空再写入:EEPROM.length() 循环的代价与时机
写入程序开头有一段清空:
cpp复制for (int i = 0; i < EEPROM.length(); i++) { // 遍历整片 EEPROM
EEPROM.write(i, 0); // 每个字节写 0
}
这段的目的不是“格式化”,而是消除残留。EEPROM 掉电不丢数据,上一版固件写进去的老字节还在。如果新固件改了结构体布局,老字节会被新代码当成合法值读出来,产生那种“明明写了新值、读出来却是旧值”的玄学现象。清一遍再写,等于给这块存储一个确定的起点。
但它的代价也很实在:EEPROM.length() 返回整片容量,循环一次就是对整片逐字节擦写一遍。这段代码放在 setup() 里,每次上电都跑,看起来无害,实际上每次开机都在消耗擦写寿命,而且拖慢启动。我一般的做法是:调试期和布局变更时保留清空,量产固件用一个宏或标志位把清空关掉,只在检测到“首次烧录”或“版本号不匹配”时清一次。别把它当成每次开机的固定动作。
3.2 写入程序逐段拆开看
cpp复制#include <Arduino.h>
#include <EEPROM.h>
struct MyObject {
char name[15];
float field1;
int field2;
byte Height;
};
void setup() {
Serial.begin(9600);
for (int i = 0; i < EEPROM.length(); i++) { // 清空,仅调试期保留
EEPROM.write(i, 0);
}
float f = 123.456f; // 先写一个独立的浮点数
int eeAddress = 0; // 起始地址
EEPROM.put(eeAddress, f);
Serial.println("Written float data type!");
MyObject customVar = {
"node-sensor-01", // 14 字符,刚好占满 15 字节里除终止符外的部分
3.14f,
9527,
64,
};
eeAddress += sizeof(float); // 地址推到 float 之后,即 4
EEPROM.put(eeAddress, customVar);
Serial.print("Written custom data type! \n");
Serial.println(customVar.name);
}
void loop() { }
逻辑上是三步:清空、写标量、写结构体。关键在两处地址动作。第一处是 int eeAddress = 0;,把 float 落在 0 号单元,占 4 字节。第二处是 eeAddress += sizeof(float);,把地址推到 4,再 put 结构体,于是结构体落在 4 起的连续单元里。为什么用 += sizeof(float) 而不是直接写 eeAddress = 4?因为前者是“跟着类型大小走”,后者是“把算出来的数字固化”。哪天前面存的不是 float 而是 long,前者自动跟着变,后者直接错位。
参数上还有两个值得盯的点。Serial.begin(9600) 只是调试通道,和 EEPROM 无关,但它是你唯一的观察窗口。EEPROM.put(eeAddress, customVar) 的第二个参数是结构体对象本身,put 会用 sizeof(customVar) 决定写多少字节,所以结构体一旦变大,写到后面的地址就变多,如果你后面还存了别的东西,必须重新排地址。这是地址规划问题,不是库的问题。
3.3 串口打印不能证明写入成功
这段代码最后打印了 customVar.name。这里有个很容易误判的地方:打印的是 RAM 里那个结构体的值,不是从 EEPROM 读回来的值。只要 put 没把数据写坏,甚至只要 RAM 没被动过,这行打印都正常。它能证明“变量初始化对了”,不能证明“EEPROM 里存的也对”。
真正的验证要做两件事:一是单独跑一遍读取程序,把 EEPROM 里的内容读出来打印;二是调用 EEPROM.get 回读到另一个变量,和写入时的变量逐字段比。前者验证“数据在”,后者验证“数据一致”。只做前者,会把“地址偏了但恰好落在别的合法值上”这种情况漏过去。
3.4 写入频率与地址规划的一条实用原则
写一次就完事的数据,地址随便排都行;但设备参数往往会被现场反复修改,这时地址规划要留余量。我的习惯是每个逻辑块固定占一段地址,块内从低地址往上写,块与块之间留出十几字节的空档。这样以后结构体加一两个字段,只要不超出预留区间,就不必改动其他块的地址,老设备升级固件也不会把后面的数据冲掉。反过来,如果所有东西都紧挨着排,改一次结构体就得整片迁移,迁移脚本写错一次就是现场返工。
4. 读取实战:get 回读、按地址逐字节读与一致性核对
读取程序在材料里给了两种方式:先用 EEPROM.get 把整块结构体回读,再用 EEPROM.read 按地址逐字节拼出字符串。两种方式各有用途,也各有坑。
4.1 EEPROM.get 回读:写入顺序的镜像
cpp复制#include <Arduino.h>
#include <EEPROM.h>
struct MyObject {
char name[15];
float field1;
int field2;
byte Height;
};
void setup() {
String value = "";
float f = 0.00f; // 承接地址 0 起的浮点数
int eeAddress = 0; // 必须从 0 重新开始
Serial.begin(9600);
Serial.print("Read float from EEPROM: ");
EEPROM.get(eeAddress, f);
Serial.println(f, 3); // 数据无效时可能打印 ovf 或 nan
eeAddress = sizeof(float); // 跳到 4,结构体起点
MyObject customVar; // 用于承接回读结果
EEPROM.get(eeAddress, customVar);
Serial.println("Read custom object from EEPROM: ");
Serial.println(customVar.name);
Serial.println(customVar.field1);
Serial.println(customVar.field2);
Serial.println(customVar.Height);
delay(200);
}
这段的核心是“镜像”:写入是先 float 后结构体,读取也必须先 float 后结构体;写入用 += sizeof(float) 推到 4,读取用 = sizeof(float) 跳到 4。两边的偏移逻辑只要有一边改错,读出来就是错位数据,而且不会报错——get 不校验,它只是照搬字节。
Serial.println(f, 3) 里的 3 是小数位数,只影响打印格式,不影响读到的值。delay(200) 也不是必须的,它只是给串口缓冲留点时间,去掉不影响数据。结构体 customVar 在 get 之前没有初始化,get 会把整块字节覆盖进去,所以初始化与否不影响结果——但如果 EEPROM 里是空的或者被清成 0,读出来的就是 0 和空字符串,看起来“成功”,其实什么也没读到。
4.2 越过 get 直接读原始字节
材料里的第二种读取方式,绕开了 get:
cpp复制for (int j = 4; j < 19; j++) { // 4 是 name 偏移,19 是 4 + 15
value += (char)EEPROM.read(j);
}
Serial.println(value);
EEPROM.read(j) 返回一个字节,强制转成 char 后拼进 String。起点 4 来自前面那张表:float 占 0–3,所以 name 从 4 开始;终点 19 是 4 + 15,正好把 15 个字节全读出来。这段代码的价值在于“看得见原始字节”——当 get 读出来的字符串明显不对,用这段逐字节读能判断是“数据没写进去”还是“结构体解析错位”。
风险也很直白:4 和 19 是硬编码。哪天 name 从 15 改成 20,或者前面存的不是 float 而是两个 int,这段立刻读错区间,可能把 field1 的字节也拼进字符串里,打印出一串莫名其妙的东西。要改得稳一点,就把起点写成 sizeof(float),长度写成 sizeof(customVar.name),让编译器替你算账。
4.3 打印出 ovf 或 nan 时按什么顺序查
材料里有一句注释:如果 EEPROM 中的数据不是一个有效的浮点数,则可能打印 ovf 或 nan。这句话信息量很大,它说明 get 并不检查数据合法性,浮点字段拿到任何字节都照解析,解析不出来就打出这种标记。
按这个线索,排查顺序应该是:
- 地址是否偏了。写入时
+= sizeof(float),读取时是不是也用了同样的偏移;有没有在读取程序里忘了把eeAddress复位成 0。 - 结构体是否变了。写入用的结构体和读取用的结构体,成员类型、顺序、数组长度是否完全一致;两次编译之间有没有改过定义。
- 写入是否真的发生。清空循环是不是跑了但
put没执行到,或者put执行在清空之前被覆盖。 - 是不是读到了未初始化的区域。地址算大了,读到了从没写过的单元,全 0 字节解析成浮点就是 0.000 或异常标记。
这四条按顺序走,绝大多数“读出来是 nan”都能定位到具体一步,而不是靠反复烧录碰运气。
5. 避坑与排查:EEPROM 功能库的五次典型故障
下面五条都来自这套结构体存取写法本身的限制,不是偶发故障。每条按现象、原因、解决三步写,遇到时照着对。
5.1 名字打印出乱码或直接空白
现象:Serial.println(customVar.name) 打出来的不是写进去的字符串,而是一串乱码,或者干脆什么都没有。
原因:char name[15] 只能放 14 个字符加一个终止符 \0。示例里那个 14 字符的字符串刚好把 15 字节填满,终止符落在最后一个字节上,边界正好。再多一个字符,put 会把 15 字节全写成字符,终止符被挤出去;回读时 println 找不到结尾,就会顺着后面的 field1 字节继续读,打出乱码。put 本身不做长度检查,它不知道你写的是什么内容。
解决:写入前先算长度,超过 14 就截断或者直接拒绝写入;回读之后手动补一句 customVar.name[14] = '\0'; 兜底。结构体初始化时把没用到的位置显式补 0,也能降低读到脏字节的概率。
5.2 改了结构体还照老地址读,浮点变成 ovf / nan
现象:固件升级后,原来能读出来的 field1 变成 nan,field2 变成一个明显不合理的数。
原因:结构体成员增删或者类型调整后,sizeof 变了,每个成员的偏移也跟着变。EEPROM 里躺着的还是旧布局的字节,新代码按新布局去解释,错位就发生在成员边界上。更麻烦的是旧数据没有被清掉,读出来的不是 0,而是一组“看起来像数据”的字节,排查时容易误判成硬件问题。
解决:把结构体布局变更当成一次数据迁移来处理——加版本号、检测到版本不匹配就清空重写、写完回读校验。调试期最省事的办法还是先跑一遍清空循环,把旧字节抹掉,再写入新布局,确认新代码自身没问题之后再考虑兼容旧数据。
5.3 硬编码地址 for (j = 4; j < 19; j++) 在成员变化后错位
现象:用逐字节方式读出来的字符串比预期长或短,甚至混进了数字字段的内容。
原因:4 和 19 是照当前结构体手算的偏移,一旦 name 长度变化,或者前面存的标量类型换了,这段循环读的区间就不再是 name。它不会报错,只会安静地读错字节。
解决:把边界交给编译器算,起点用 sizeof(float),终点用起点加 sizeof(customVar.name);或者干脆放弃逐字节读,统一用 get 回读。硬编码数字只适合一次性验证,不适合留在正式固件里。
5.4 换到 ESP8266 上照抄 put / get,读回全 0
现象:同一份代码在 UNO 上正常,换到 ESP8266 上写入没反应,回读全是 0 或固定值。
原因:材料里明确写了,这个示例不适用于在 ESP8266 上使用 EEPROM.put() 或者 EEPROM.get()。不同板子的 EEPROM 实现不一样,put/get 未必按你预期的字节语义工作。
解决:换板之前先确认目标板的库实现支持范围;不支持就退回 EEPROM.read / EEPROM.write 逐字节搬,自己维护偏移和长度。别把“在 UNO 上验证过”当成“在所有板子上都成立”。
5.5 写到一半掉电,回读一半新一半旧
现象:设备在参数保存过程中被断电,重新上电后 name 是新值,field1 还是上一次的旧值。
原因:put 是逐字节写,多字节记录不是原子操作。写入过程中掉电,前面的字节已经落盘,后面的还没写,EEPROM 里就留下一条“半新半旧”的记录。读的时候没有校验,照样当合法数据用。
解决:写完立即 get 回读到临时变量,和写入源逐字段比对,不一致就重写;对关键参数用双份存放,一份数据一份有效标志,先写数据、回读确认、最后写标志,上电时只认标志有效的那份。这套做法不复杂,但能挡住绝大多数掉电截断。
6. 进阶:给裸结构体加版本号和回读校验
结构体直接 put 最大的隐患是“没有身份”。EEPROM 里的字节不会告诉你它是哪一版布局写的,只能靠你自己在代码里记住。我现在的习惯是给每个存储块加一个版本号,放在结构体第一个字节:
cpp复制#define K_EEPROM_VER 2 // 布局版本,改结构体就加一
struct MyObjectV2 {
uint8_t version; // 首字节:写入时的布局版本
char name[15];
float field1;
int field2;
byte Height;
};
bool saveObject(int base, const MyObjectV2 &obj) {
EEPROM.put(base, obj); // 先落盘
MyObjectV2 back; // 再回读
EEPROM.get(base, back);
return back.version == obj.version && // 逐字段比对
back.field2 == obj.field2 &&
back.Height == obj.Height &&
back.field1 == obj.field1;
}
注意版本号放在首字节会改变所有成员的偏移,所以这是一次布局变更,必须配合清空重写,不能指望老数据还能读。校验函数里 field1 用相等比较是可行的,因为 put 和 get 搬运的是同一份字节,没有精度损失;但如果你在写入前对浮点做过运算,比较时要留一个容差。saveObject 的返回值不要丢,调用方拿到 false 就该重试或者报错,而不是继续往下跑。
版本号还有一个附带好处:上电时可以先用 EEPROM.get 把版本号读出来,和 K_EEPROM_VER 比对,不匹配就走清空加默认值的流程,匹配才加载业务参数。这样固件升级到新布局时,设备不会拿着旧字节当新数据用。
从那以后我每次改结构体,都强制走一遍“改版本号 → 清空 → 写入 → 回读比对”的流程,哪怕只加了一个 byte 字段也不例外。这个习惯救过我好几次,尤其是在没有仿真器、只能靠串口打印判断的现场。希望帮到你。
