EasyFlash | 让 Flash 成为小型 KV 数据库
嵌入式开源项目精选专栏
本专栏由Mculover666创建，主要内容为寻找嵌入式领域内的优质开源项目，一是帮助开发者使用开源项目实现更多的功能，二是通过这些开源项目，学习大佬的代码及背后的实现思想，提升自己的代码水平，和其它专栏相比，本专栏的优势在于：
不会单纯的介绍分享项目，还会包含作者亲自实践的过程分享，甚至还会有对它背后的设计思想解读。
目前本专栏包含的开源项目有：
- cJSON | 一个轻量级C语言JSON解析器
- paho | 支持10种语言编写mqtt客户端，总有一款适合你！
- MultiButton | 一个小巧简单易用的事件驱动型按键驱动模块
- letter-shell | 一个功能强大的嵌入式shell
- EasyLogger | 一款轻量级且高性能的日志库
- SFUD | 一款串行 Flash 通用驱动库
如果您自己编写或者发现的开源项目不错，欢迎留言或者私信投稿到本专栏，分享获得双倍的快乐！
1. EasyFlash
本期给大家带来的开源项目是 EasyFlash，可以让 Flash 成为小型 KV 数据库（Key-Value），作者armink，目前收获 975 个 star，遵循 MIT 开源许可协议。
EasyFlash是一款开源的轻量级嵌入式Flash存储器库，非常适合智能家居、可穿戴、工控、医疗、物联网等需要断电存储功能的产品，资源占用极低，并且支持各种 MCU 片上存储器。
目前 EasyFlash 支持以下功能：
- ENV：快速保存产品参数，支持 写平衡（磨损平衡） 及掉电保护功能；
- IAP：在线升级；
- LOG：无需文件系统，日志可直接存储在Flash上；
项目地址：https://github.com/armink/EasyFlash
2. 移植EasyFlash
2.1. 移植思路
在移植过程中主要参考两个资料：项目的readme文档和demo工程。
对于这些开源项目，其实移植起来也就两步：
- ① 添加源码到裸机工程中；
- ② 实现需要的接口即可（擦、写、读、打印）；
2.2. 准备裸机工程
本文中我使用的是小熊派IoT开发套件，主控芯片为STM32L431RCT6：
板载Flash型号为W25Q64JV，大小64Mbit，与STM32的QSPI接口相连：
移植之前需要准备一份裸机工程，我使用STM32CubeMX生成，需要初始化以下配置：
- 配置一个串口用于打印信息
- printf重定向
- 配置SPI Flash通信接口（SPI或QSPI）
- 移植SFUD开源库（方便操作Flash）
SFUD移植过程请参考上一期文章：
- SFUD | 一款串行 Flash 通用驱动库
2.3. 添加EasyFlash到工程中
② 在keil中添加 SFUD 组件的源码文件：
src\easyflash.c：（必选）包含EasyFlash初始化方法；src\ef_utils.c：（必选）EasyFlash常用小工具；port\ef_port.c：（必选）EasyFlash移植接口；src\ef_env.c：Env（常规模式）相关操作接口及实现源码；
其它两个IAP和LOG相关的源码暂且不用添加。
③ 将easyflash/inc头文件路径添加到keil中：
2.4. 实现EasyFlash移植接口
EasyFlash的移植接口都已经写好了，在ef_port.c文件中，只需要在函数体中添加代码即可。
① 默认环境变量集合
产品上需要的默认环境变量集中定义在这里，当 flash 第一次初始化时会将默认的环境变量写入，采用 void * 类型，所以支持任意类型：
/* default environment variables set for user */
static const ef_env default_env_set[] = {
{"wifi_ssid","FAST_88A6", 0}, //字符串大小设置为0，会自动检测
{"wifi_passwd","12345678", 0},
};
② EasyFlash初始化接口
在该接口中会传递默认环境变量，初始化EasyFlash移植所需的资源（比如SFUD库的初始化）：
EfErrCode ef_port_init(ef_env const **default_env, size_t *default_env_size) {
EfErrCode result = EF_NO_ERR;
*default_env = default_env_set;
*default_env_size = sizeof(default_env_set) / sizeof(default_env_set[0]);
//SFUD库初始化
sfud_init();
return result;
}
③ 读取Flash接口
使用SFUD开源库提供的API实现该接口：
EfErrCode ef_port_read(uint32_t addr, uint32_t *buf, size_t size) {
EfErrCode result = EF_NO_ERR;
//获取SFUD Flash设备对象
const sfud_flash *flash = sfud_get_device_table() + SFUD_W25Q64_DEVICE_INDEX;
//使用SFUD开源库提供的API实现Flash读取
sfud_read(flash, addr, size, (uint8_t *)buf);
return result;
}
④ 擦除Flash接口
使用SFUD开源库提供的API实现该接口：
EfErrCode ef_port_erase(uint32_t addr, size_t size) {
EfErrCode result = EF_NO_ERR;
sfud_err sfud_result = SFUD_SUCCESS;
//获取SFUD Flash设备对象
const sfud_flash *flash = sfud_get_device_table() + SFUD_W25Q64_DEVICE_INDEX;
/* make sure the start address is a multiple of FLASH_ERASE_MIN_SIZE */
EF_ASSERT(addr % EF_ERASE_MIN_SIZE == 0);
//使用SFUD提供的API实现Flash擦除
sfud_result = sfud_erase(flash, addr, size);
if(sfud_result != SFUD_SUCCESS) {
result = EF_ERASE_ERR;
}
return result;
}
⑤ 写入Flash接口
使用SFUD开源库提供的API实现该接口：
EfErrCode ef_port_write(uint32_t addr, const uint32_t *buf, size_t size) {
EfErrCode result = EF_NO_ERR;
sfud_err sfud_result = SFUD_SUCCESS;
//获取SFUD Flash设备对象
const sfud_flash *flash = sfud_get_device_table() + SFUD_W25Q64_DEVICE_INDEX;
//使用SFUD开源库提供的API实现
sfud_result = sfud_write(flash, addr, size, (const uint8_t *)buf);
if(sfud_result != SFUD_SUCCESS) {
result = EF_WRITE_ERR;
}
return result;
}
⑥ 对环境变量缓冲区加锁/解锁
裸机时可以使用关闭/打开全局中断来上锁/解锁：
/**
* lock the ENV ram cache
*/
void ef_port_env_lock(void) {
//关闭全局中断
__disable_irq();
}
/**
* unlock the ENV ram cache
*/
void ef_port_env_unlock(void) {
//打开全局中断
__enable_irq();
}
⑦ EasyFlash打印数据和日志接口
在该文件最顶部开辟一块打印数据缓冲区：
//easyflash打印数据缓冲区
static char log_buf[128];
然后实现输出无固定格式的打印信息接口：
void ef_print(const char *format, ...) {
va_list args;
/* args point to the first variable parameter */
va_start(args, format);
/* 实现数据输出 */
vsprintf(log_buf, format, args);
printf("%s", log_buf);
va_end(args);
}
然后使用该函数去实现调试信息日志打印接口：
void ef_log_debug(const char *file, const long line, const char *format, ...) {
#ifdef PRINT_DEBUG
va_list args;
/* args point to the first variable parameter */
va_start(args, format);
/* You can add your code under here. */
ef_print("[Flash](%s:%ld) ", file, line);
/* must use vprintf to print */
vsprintf(log_buf, format, args);
ef_print("%s", log_buf);
printf("\r");
va_end(args);
#endif
}
最后实现普通日志信息打印接口：
void ef_log_info(const char *format, ...) {
va_list args;
/* args point to the first variable parameter */
va_start(args, format);
/* You can add your code under here. */
ef_print("[Flash]");
/* must use vprintf to print */
vsprintf(log_buf, format, args);
ef_print("%s", log_buf);
printf("\r");
va_end(args);
}
2.5. 配置EasyFlash
EasyFlash的核心功能配置文件在ef_cfg.h，修改说明如下。
① 环境变量功能相关
② Flash擦除粒度和写入粒度
③ 备份区相关
④ 调试日志是否开启
至此，EasyFlash移植、配置完成，接下来就可以愉快的使用了！
3. 使用EasyFlash
使用时包含头文件：
#include 3.1. 初始化EasyFlash
EfErrCode easyflash_init(void);
该 API 会初始化的EasyFlash的各个组件，初始化后才可以使用别的API，第一次初始化的时候，会自动调用 ef_env_set_default 将定义的默认环境变量保存到Flash。
在main函数中初始化EasyFlash：
/* USER CODE BEGIN 2 */
//初始化EasyFlash
ret = easyflash_init();
if(ret != EF_NO_ERR)
{
printf("EasyFlash init fail, EfErrCode = %d.r\n", ret);
}
/* USER CODE END 2 */
3.2. 环境变量操作API
在 V4.0 以后，环境变量在 EasyFlash 底层都是按照二进制数据格式进行存储，即 blob 格式 ，这样上层支持传入任意类型。
① 获取 blob 类型环境变量
size_t ef_get_env_blob(const char *key, void *value_buf, size_t buf_len, size_t *save_value_len);
其中参数的意义如下：
- key：环境变量名称
- value_buf：存放环境变量的缓冲区
- buf_len：该缓冲区的大小
- save_value_len：返回该环境变量实际存储在 flash 中的大小
- 返回值：成功存放至缓冲区中的数据长度
② 设置 blob 类型环境变量
使用该API可以对环境变量完成如下操作：
- 增加 ：当环境变量表中不存在该名称的环境变量时，则会执行新增操作；
- 修改 ：入参中的环境变量名称在当前环境变量表中存在，则把该环境变量值修改为入参中的值；
- 删除：当入参中的value为NULL时，则会删除入参名对应的环境变量。
EfErrCode ef_set_env_blob(const char *key, const void *value_buf, size_t buf_len);
其中参数的意义如下：
- key：环境变量名称
- value_buf：环境变量值缓冲区
- buf_len：缓冲区长度，即值的长度
3.3. 测试读取默认环境变量
在main.c中编写一个EasyFlash测试函数：
void test_env(void)
{
char wifi_ssid[20] = {0};
char wifi_passwd[20] = {0};
size_t len = 0;
/* 读取默认环境变量值 */
//环境变量长度未知，先获取 Flash 上存储的实际长度 */
ef_get_env_blob("wifi_ssid", NULL, 0, &len);
//获取环境变量
ef_get_env_blob("wifi_ssid", wifi_ssid, len, NULL);
//打印获取的环境变量值
printf("wifi_ssid env is:%s\r\n", wifi_ssid);
//环境变量长度未知，先获取 Flash 上存储的实际长度 */
ef_get_env_blob("wifi_passwd", NULL, 0, &len);
//获取环境变量
ef_get_env_blob("wifi_passwd", wifi_passwd, len, NULL);
//打印获取的环境变量值
printf("wifi_passwd env is:%s\r\n", wifi_passwd);
/* 将环境变量值改变 */
ef_set_env_blob("wifi_ssid", "SSID_TEST", 9);
ef_set_env_blob("wifi_passwd", "66666666", 8);
}
在main函数的初始化代码之后调用该函数，编译下载之后，在串口终端中可以看到读取结果：
此时环境变量已经被修改，直接复位开发板，可以看到读取出的新值：
3.4. Easyflash和letter-shell的结合
EasyFlash在测试阶段需要不断的设置环境变量、读取环境变量、开发板重新上电，这个特点刚好可以应用letter-shell，直接将两个常用函数导出为命令，在串口命令行测试。
letter-shell的移植过程请参考第2期：
- letter-shell | 一个功能强大的嵌入式shell
移植之后将读取环境变量的API封装，导出到命令列表中：
/* USER CODE BEGIN 4 */
int getenv(const char *key)
{
size_t len = 0;
char buf[20] = {0};
//获取长度
ef_get_env_blob(key, NULL, 0, &len);
if(len == 0)
{
//环境变量不存在
printf("evn %s is not exist\r\n", key);
return -1;
}
else if(len < 20)
{
//环境变量值超长
printf("buf size is not enough, len is %d\r\n", len);
return -1;
}
else
{
//获取环境变量值
ef_get_env_blob(key, buf, len, NULL);
printf("read env %s, value is:%s\r\n", key, buf);
return 0;
}
}
SHELL_EXPORT_CMD(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC), getenv, getenv, getenv);
/* USER CODE END 4 */
编译下载之后，在串口终端中查看串口输出：
然后进行读取环境变量测试：
测试成功，同理，修改环境变量的API也可以进行封装，导出到命令列表中进行测试。
4. 设计思想解读
对于EasyFlash的全新版本设计，作者armink在仓库中写了一份文档，解铃还须系铃人，笔者的技术水平有限，直接放上作者的文档链接，欢迎感兴趣的读者阅读。
- EasyFlash V4.0 ENV 功能设计与实现
5. 项目工程源码获取和问题交流
目前我将EasyFlash源码、我移植到小熊派STM32L431RCT6开发板的工程源码上传到了QQ群里（包含好几份HAL库，QQ相对速度快点），可以在QQ群里下载，有问题也可以在群里交流，当然也欢迎大家分享出来自己移植的工程到QQ群里：
放上QQ群二维码：
接收更多精彩文章及资源推送，欢迎订阅我的微信公众号：『mculover666』。
