1. 项目概述CodedPreferences 是一个面向嵌入式系统的轻量级非易失性参数存储库其核心设计目标是为资源受限的 MCU如 STM32F0/F1/L0/L1、nRF52、ESP32-C3 等提供具备编码校验能力的 EEPROM/Flash 偏好设置管理方案。与传统EEPROM.put()或裸 Flash 擦写操作不同CodedPreferences 并非简单地将键值对序列化后写入地址空间而是通过引入“编码”coding机制在数据持久化层面嵌入完整性保护与结构化语义从而在不依赖外部文件系统或复杂 CRC 表管理的前提下实现参数的可验证、可恢复、可版本演进的可靠存储。项目摘要中“Preferences with codes”并非修辞表达而是对该库本质的高度凝练——“codes”在此处具有三重工程含义编码Encoding对原始参数值执行类型安全的二进制序列化如int32_t→ 4 字节小端避免字符串解析开销校验码Check Code为每个参数项附加 Fletcher-16 校验和实现单字节错误检出与双字节错误提示标识码Code ID为每个参数分配唯一 16 位标识符而非字符串键名彻底消除字符串哈希冲突、内存碎片及 Flash 写入长度不可控等问题。该设计直击嵌入式偏好存储的三大痛点可靠性缺陷裸 Flash 写入无校验掉电瞬间易导致参数区损坏且无法自愈维护性瓶颈以字符串为 key 的方案在固件升级后难以兼容旧参数布局如“wifi_ssid”→“network.ssid”需人工迁移逻辑资源浪费字符串 key 占用宝贵 RAM/Flash 空间且哈希计算消耗 CPU 周期对 48MHz Cortex-M0 类 MCU 构成显著负担。CodedPreferences 通过“Code ID 编码值 Fletcher-16”三元组结构将参数抽象为编译期确定的常量使存储操作退化为确定性地址偏移写入同时赋予运行时自我验证能力。其关键词eeprom, preferences准确反映了技术定位它不是通用 Flash 文件系统如 LittleFS亦非高级配置框架如 Zephyr Settings而是一个专为 MCU 级别参数持久化定制的、零动态内存分配、零外部依赖的硬实时就绪组件。2. 核心架构与数据模型2.1 存储布局扇区化线性映射CodedPreferences 不采用链表或目录结构而是将整个参数区视为一块连续的、按固定槽位slot划分的线性空间。典型部署如下以 1KB EEPROM 为例地址范围Hex长度用途0x000–0x00F16 B全局头区Header0x010–0x3FF976 B参数槽位区Slots0x400–0x40F16 B备份头区Backup Header0x410–0x7FF976 B备份参数槽位区Backup Slots全局头区Header包含magic[4]固定字节0x43, 0x4F, 0x44, 0x45ASCII “CODE”用于快速识别介质是否已初始化version1 字节格式版本号当前为0x01支持未来结构演进crc16对magic version计算的 Fletcher-16验证头区完整性reserved[9]保留字段供扩展使用。参数槽位Slot是最小存储单元固定长度为 16 字节结构如下偏移字段长度说明0x00code_id2 B参数唯一标识符小端序 uint16_t0x02value_len1 B实际值长度1–120 表示该槽位空闲0x03value[12]12 B编码后的参数值最大 12 字节0x0Fcrc81 B对code_id value_len value[0..value_len-1]计算的 CRC-8多项式 0x07此设计强制约束单个参数最大为 12 字节但换来关键收益确定性擦写每个槽位长度恒定无需动态计算擦除边界原子性保障写入一个槽位仅需一次 Page Write对 I²C EEPROM或一次 Flash Word Program对 MCU 片内 Flash规避跨页写入风险快速遍历扫描全部参数仅需N × 16字节读取无指针跳转开销。2.2 Code ID 机制编译期绑定的参数契约Code ID 是 CodedPreferences 的灵魂所在。开发者需在项目中定义全局enum显式声明所有参数// preferences_codes.h typedef enum { PREF_CODE_DEVICE_ID 0x0001, PREF_CODE_WIFI_CHANNEL 0x0002, PREF_CODE_CALIB_OFFSET 0x0003, PREF_CODE_FW_VERSION 0x0004, // ... 更多参数 } pref_code_t;该枚举在编译期固化为常量所有 API 调用均以pref_code_t为参数例如// 写入 int32_t 类型的校准偏移量 int32_t offset -127; codedprefs_write_int32(PREF_CODE_CALIB_OFFSET, offset); // 读取 WiFi 信道uint8_t uint8_t channel; codedprefs_read_uint8(PREF_CODE_WIFI_CHANNEL, channel);工程意义零字符串开销PREF_CODE_WIFI_CHANNEL编译为0x0002全程无字符串存储与比较强类型安全codedprefs_write_int32()内部校验code_id是否在预定义范围内并确保value_len 4版本兼容基石固件升级时若新增PREF_CODE_BATTERY_THRESH 0x0005旧固件读取该 ID 将返回CODED_PREFS_ERR_NOT_FOUND新固件读取旧参数仍能正确解析——因为 Code ID 本身即版本契约。2.3 双备份机制断电安全的物理保障为应对 MCU 在写入过程中意外掉电导致参数区损坏CodedPreferences 实施严格的双备份策略主区Primary位于起始扇区如0x000–0x3FF备份区Backup位于镜像扇区如0x400–0x7FF头区状态位header-status字段占用reserved[0]标记当前有效区0xAA表示主区有效0x55表示备份区有效。写入流程严格遵循“先写备份再切换最后擦除旧区”的三步协议将新参数写入备份区对应槽位更新备份头区status为0x55并刷新头区 CRC擦除原主区整个扇区0x000–0x3FF更新主头区status为0xAA完成切换。此协议确保任意时刻至少有一个完整、一致的参数副本存在。即使步骤 2 后掉电系统重启时检测到备份头区status0x55且 CRC 有效即自动启用备份区实现无缝故障转移。3. 关键 API 接口详解CodedPreferences 提供两类 API基础操作接口直接操作槽位与类型封装接口隐含编码逻辑。所有函数均返回codedprefs_err_t错误码无异常抛出。3.1 基础操作 API函数签名作用典型调用场景codedprefs_init(const codedprefs_config_t *cfg)初始化库校验头区并选择有效区main()中系统启动时调用一次codedprefs_read_slot(uint16_t code_id, uint8_t *out_value, uint8_t *out_len)读取指定 Code ID 的原始槽位数据实现自定义序列化逻辑时使用codedprefs_write_slot(uint16_t code_id, const uint8_t *value, uint8_t len)写入原始槽位数据需自行保证len ≤ 12批量参数导入或调试工具codedprefs_config_t结构体定义了硬件抽象层HAL回调开发者必须实现typedef struct { void (*read)(uint32_t addr, uint8_t *buf, uint16_t len); // 从 addr 读 len 字节 void (*write)(uint32_t addr, const uint8_t *buf, uint16_t len); // 向 addr 写 len 字节 void (*erase_sector)(uint32_t addr); // 擦除 addr 所在扇区 uint32_t primary_base; // 主区起始地址如 0x000 uint32_t backup_base; // 备份区起始地址如 0x400 uint32_t sector_size; // 扇区大小如 1024 } codedprefs_config_t;HAL 实现要点对 I²C EEPROM如 AT24C02read/write需处理页边界每页 16 字节erase_sector实为 NOPEEPROM 无需显式擦除对 MCU 片内 Flash如 STM32F1write需调用HAL_FLASH_Program(FLASH_TYPEPROGRAM_WORD, ...)erase_sector调用HAL_FLASHEx_Erase()所有 HAL 函数必须为阻塞式且保证原子性禁止在中断中调用。3.2 类型封装 API推荐使用封装 API 自动处理类型编码、长度校验与 CRC 计算大幅降低误用风险函数签名编码规则错误检查codedprefs_write_int8(uint16_t code_id, int8_t val)val→uint8_t[1]直接赋值code_id有效性、value_len1codedprefs_write_int32(uint16_t code_id, int32_t val)val→ 小端uint8_t[4]code_id有效性、value_len4codedprefs_write_string(uint16_t code_id, const char *str, uint8_t max_len)str截断至max_len字节末尾补\0strlen(str) ≤ max_len、value_len ≤ 12codedprefs_read_uint16(uint16_t code_id, uint16_t *out_val)从value[0..1]读取小端uint16_t槽位存在、value_len2、CRC 校验通过关键行为说明codedprefs_write_string()的max_len参数指定最大存储长度不含\0例如max_len11时最多存 11 字符 1 字节\0严格满足value_len≤12所有read_*函数在 CRC 校验失败时返回CODED_PREFS_ERR_CRC_MISMATCH并不清除输出缓冲区由调用者决定是否使用脏数据若参数未写入过槽位value_len0read_*返回CODED_PREFS_ERR_NOT_FOUND此时应加载默认值。3.3 错误码定义typedef enum { CODED_PREFS_OK 0, // 成功 CODED_PREFS_ERR_NOT_FOUND -1, // Code ID 未找到 CODED_PREFS_ERR_CRC_MISMATCH -2, // CRC 校验失败 CODED_PREFS_ERR_INVALID_CODE -3, // Code ID 超出范围或为 0 CODED_PREFS_ERR_VALUE_TOO_LONG -4, // 值长度超过 12 字节 CODED_PREFS_ERR_WRITE_FAILED -5, // HAL 写入失败如 Flash 编程错误 CODED_PREFS_ERR_ERASE_FAILED -6, // HAL 擦除失败 } codedprefs_err_t;工程实践建议在产品固件中对CODED_PREFS_ERR_NOT_FOUND应触发默认值注入如codedprefs_write_int32(PREF_CODE_DEVICE_ID, generate_default_id())对CODED_PREFS_ERR_CRC_MISMATCH可记录日志并尝试从备份区恢复或进入安全模式CODED_PREFS_ERR_WRITE_FAILED通常指示硬件故障如 EEPROM 寿命耗尽需在量产测试中重点监控。4. 与主流嵌入式生态的集成实践4.1 STM32 HAL 库集成示例以 STM32F103C8T6片内 1KB Flash为例将 CodedPreferences 部署至0x0800F000开始的扇区假设该扇区未被 Bootloader 使用// flash_hal.c #include stm32f1xx_hal.h #include codedpreferences.h static void flash_read(uint32_t addr, uint8_t *buf, uint16_t len) { memcpy(buf, (void*)addr, len); // Flash 直接映射无需驱动 } static void flash_write(uint32_t addr, const uint8_t *buf, uint16_t len) { HAL_FLASH_Unlock(); __HAL_FLASH_CLEAR_FLAG(FLASH_FLAG_EOP | FLASH_FLAG_PGERR | FLASH_FLAG_WRPRTERR); for (uint16_t i 0; i len; i 4) { uint32_t word *(uint32_t*)(buf i); HAL_FLASH_Program(FLASH_TYPEPROGRAM_WORD, addr i, word); } HAL_FLASH_Lock(); } static void flash_erase_sector(uint32_t addr) { FLASH_EraseInitTypeDef erase {0}; uint32_t page_error 0; erase.TypeErase FLASH_TYPEERASE_PAGE; erase.PageAddress addr; erase.NbPages 1; HAL_FLASHEx_Erase(erase, page_error); } const codedprefs_config_t g_codedprefs_cfg { .read flash_read, .write flash_write, .erase_sector flash_erase_sector, .primary_base 0x0800F000, .backup_base 0x0800F400, // 偏移 0x400 .sector_size 0x400, };初始化后即可使用// main.c int main(void) { HAL_Init(); SystemClock_Config(); if (codedprefs_init(g_codedprefs_cfg) ! CODED_PREFS_OK) { // 初始化失败进入错误处理 while(1); } // 读取设备ID不存在则生成并保存 uint32_t dev_id; if (codedprefs_read_uint32(PREF_CODE_DEVICE_ID, dev_id) ! CODED_PREFS_OK) { dev_id HAL_GetUIDw0() ^ HAL_GetUIDw1(); // 简单唯一ID codedprefs_write_uint32(PREF_CODE_DEVICE_ID, dev_id); } }4.2 FreeRTOS 任务安全访问CodedPreferences 本身无锁但在多任务环境中需防止并发写入破坏参数区。推荐使用二值信号量保护SemaphoreHandle_t xPrefsMutex; void prefs_init(void) { xPrefsMutex xSemaphoreCreateBinary(); xSemaphoreGive(xPrefsMutex); // 初始可用 codedprefs_init(g_codedprefs_cfg); } // 任务中安全写入 void vTaskWritePrefs(void *pvParameters) { if (xSemaphoreTake(xPrefsMutex, portMAX_DELAY) pdTRUE) { codedprefs_write_int32(PREF_CODE_WIFI_CHANNEL, 6); xSemaphoreGive(xPrefsMutex); } }注意xSemaphoreTake()必须在codedprefs_init()之后调用且codedprefs_init()本身不应在任务中执行因其可能触发 Flash 擦除耗时长。4.3 与传感器驱动协同校准参数持久化以 BME280 温湿度传感器为例将出厂校准系数存入 CodedPreferences// bme280_calib_t 结构体24 字节需拆分为多个 ≤12 字节的槽位 typedef struct { uint16_t dig_T1; // 2B int16_t dig_T2; // 2B int16_t dig_T3; // 2B // ... 其他字段 } bme280_calib_t; // 保存校准数据分槽位 void bme280_save_calibration(const bme280_calib_t *cal) { codedprefs_write_uint16(PREF_CODE_BME280_DIG_T1, cal-dig_T1); codedprefs_write_int16(PREF_CODE_BME280_DIG_T2, cal-dig_T2); codedprefs_write_int16(PREF_CODE_BME280_DIG_T3, cal-dig_T3); // ... 继续其他字段 } // 加载校准数据 void bme280_load_calibration(bme280_calib_t *cal) { codedprefs_read_uint16(PREF_CODE_BME280_DIG_T1, cal-dig_T1); codedprefs_read_int16(PREF_CODE_BME280_DIG_T2, cal-dig_T2); codedprefs_read_int16(PREF_CODE_BME280_DIG_T3, cal-dig_T3); }此方式避免了将 24 字节结构体整体序列化超出单槽位限制同时保持字段级可独立更新能力。5. 生产环境部署与寿命管理5.1 EEPROM 寿命优化策略I²C EEPROM如 AT24C02典型擦写寿命为 100 万次若每分钟写入一次参数理论寿命仅约 2 年。CodedPreferences 通过以下机制延长实际寿命写入抑制Write Throttling在codedprefs_write_*前增加阈值判断仅当值变化超过设定容差时才写入int32_t new_temp read_sensor(); int32_t old_temp; if (codedprefs_read_int32(PREF_CODE_LAST_TEMP, old_temp) CODED_PREFS_OK) { if (abs(new_temp - old_temp) 50) { // 温度变化 0.5°C codedprefs_write_int32(PREF_CODE_LAST_TEMP, new_temp); } }批量提交Batch Commit将多个参数变更暂存 RAM定时统一刷入typedef struct { bool dirty; int32_t temp; uint8_t batt_level; } pending_prefs_t; static pending_prefs_t g_pending; void queue_temp_update(int32_t t) { g_pending.temp t; g_pending.dirty true; } void commit_pending(void) { if (g_pending.dirty) { codedprefs_write_int32(PREF_CODE_LAST_TEMP, g_pending.temp); codedprefs_write_uint8(PREF_CODE_BATT_LEVEL, g_pending.batt_level); g_pending.dirty false; } }5.2 固件升级参数迁移当新增参数或修改现有参数语义时需在新固件中实现迁移逻辑。以PREF_CODE_WIFI_SSID旧版 32 字节升级为PREF_CODE_NETWORK_SSID新版 64 字节为例void migrate_preferences(void) { // 尝试读取旧参数 char old_ssid[33] {0}; if (codedprefs_read_string(PREF_CODE_WIFI_SSID, old_ssid, sizeof(old_ssid)-1) CODED_PREFS_OK) { // 写入新参数截断或填充 char new_ssid[65] {0}; strncpy(new_ssid, old_ssid, 64); codedprefs_write_string(PREF_CODE_NETWORK_SSID, new_ssid, 64); // 可选清除旧参数以释放槽位 codedprefs_erase_slot(PREF_CODE_WIFI_SSID); } }此迁移函数应在codedprefs_init()后立即调用确保每次启动都检查兼容性。6. 调试与故障诊断6.1 参数区快照分析使用 ST-Link Utility 或 J-Flash 读取 Flash 内容手动解析参数区地址: 0x0800F000 0000: 43 4F 44 45 01 2A 00 00 00 00 00 00 00 00 00 00 // Header: CODE, ver1, crc0x2A... 0010: 01 00 04 00 00 00 00 00 00 00 00 00 00 00 00 00 // Slot0: code0x0001, len4, value0x00000000, crc0x00 0020: 02 00 01 06 00 00 00 00 00 00 00 00 00 00 00 00 // Slot1: code0x0002, len1, value0x06, crc0x00 ...通过比对code_id和value_len可快速定位参数是否存在、长度是否异常。6.2 CRC 故障注入测试为验证 CRC 保护有效性可在调试时手动篡改 Flash 中某槽位的crc8字节然后调用codedprefs_read_*确认返回CODED_PREFS_ERR_CRC_MISMATCH。此测试应纳入量产固件的自检流程。6.3 备份区一致性验证在关键固件更新后强制触发一次备份区同步// 强制将主区复制到备份区用于升级后校验 void codedprefs_force_backup_sync(void) { // 1. 读取主区全部槽位 // 2. 写入备份区对应位置 // 3. 更新备份头区 status 为 0x55 // 4. 擦除主区可选 }此操作可确保双备份区内容完全一致为后续升级提供确定性基线。CodedPreferences 的价值不在于功能繁复而在于以最简的代码、最少的资源、最严的约束解决嵌入式参数存储中最顽固的可靠性问题。当你的产品在野外连续运行三年后仍能准确读出初始校准值那便是这个库无声的勋章——它不声张却始终在 Flash 的黑暗里为每一行关键数据点亮 CRC 的微光。