LISA KV EasyFlash 示例

功能说明

演示如何使用 LISA KV 组件的 EasyFlash 后端保存和读取键值数据。示例覆盖 int、string、bool 和 blob 四种常用数据类型，并展示读取动态内存后的释放方式。

硬件连接

无需外部连接，示例使用芯片内部 Flash 上的 EasyFlash ENV 区域保存 KV 数据。

示例内容

调用 lisa_kv_init() 初始化 EasyFlash 后端。
使用 lisa_kv_set_int() 和 lisa_kv_get_int() 保存和读取整型数据。
使用 lisa_kv_set_string() 和 lisa_kv_get_string() 保存和读取字符串。
使用 lisa_kv_set_bool() 和 lisa_kv_get_bool() 保存和读取布尔值。
使用 lisa_kv_set_blob() 和 lisa_kv_get_blob() 保存和读取二进制数据。
使用 lisa_kv_free() 释放读取接口返回的动态内存，并使用 lisa_kv_del() 删除示例 key。

编译

重要提示：在编译前，请先确认您使用的开发板型号。SDK 目前支持以下开发板：

arcs_evb - ARCS EVB 评估板
arcs_mini - ARCS Mini 开发板

根据您的开发板型号，选择对应的编译命令：

在 SDK 根目录执行编译。Linux 使用 build.sh：

# 使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_mini

Windows PowerShell 使用 build.ps1：

# 使用 arcs_evb 开发板
.\build.ps1 -C -S samples/<示例路径> -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
.\build.ps1 -C -S samples/<示例路径> -DBOARD=arcs_mini

Note

确保已安装对应平台的工具链和 ListenAI 开发工具包。Windows 环境请先执行 .\env.ps1 或直接使用 .\build.ps1 自动加载环境。

烧录

编译完成后，使用 SDK tools 目录下的 cskburn 工具烧录固件。

Linux:

./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs

Windows PowerShell:

.\tools\burn\cskburn.exe -C arcs -s COM7 -b 3000000 0x0 .\build\arcs.bin

Note

烧录参数说明：

-s /dev/ttyUSB0 / -s COM7：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是 /dev/ttyUSB0 或 /dev/ttyACM0 - 可通过 ls /dev/tty* 命令查看可用串口设备 - Windows 系统：通常是 COM7、COM8 等，可在“设备管理器”的“端口”中查看 - 不同开发板或 USB 转串口芯片可能使用不同的设备名
-b 3000000：烧录波特率（3Mbps）
0x0：烧录起始地址
build/arcs.bin / .\build\arcs.bin：编译生成的固件路径
-C arcs：芯片类型

注意事项：

确保开发板已正确连接到电脑
如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口

预期输出

[I][lisa_kv_sample] === LISA KV EasyFlash Example ===
[I][lisa_kv_sample] lisa_kv_init ok
[I][lisa_kv_sample] set int ok
[I][lisa_kv_sample] get int ok
[I][lisa_kv_sample] int value: 1234
[I][lisa_kv_sample] set string ok
[I][lisa_kv_sample] get string ok
[I][lisa_kv_sample] string value: hello easyflash kv
[I][lisa_kv_sample] set bool ok
[I][lisa_kv_sample] get bool ok
[I][lisa_kv_sample] bool value: true
[I][lisa_kv_sample] set blob ok
[I][lisa_kv_sample] get blob ok
[I][lisa_kv_sample] blob value len: 5
[I][lisa_kv_sample] dump EasyFlash env after write:
[I][lisa_kv_sample] demo keys deleted
[I][lisa_kv_sample] === LISA KV EasyFlash Example completed ===

lisa_kv_dump() 会打印 EasyFlash ENV 中的当前内容，具体输出会随设备上已有 ENV 数据变化。

核心 API

API	说明
`lisa_kv_init()`	初始化 KV 后端，EasyFlash 模式下会调用 `easyflash_init()`
`lisa_kv_set_int()`	写入整型值
`lisa_kv_get_int()`	读取整型值
`lisa_kv_set_string()`	写入字符串
`lisa_kv_get_string()`	读取字符串，返回内存需要用 `lisa_kv_free()` 释放
`lisa_kv_set_bool()`	写入布尔值
`lisa_kv_get_bool()`	读取布尔值
`lisa_kv_set_blob()`	写入二进制数据
`lisa_kv_get_blob()`	读取二进制数据，返回内存需要用 `lisa_kv_free()` 释放
`lisa_kv_del()`	删除指定 key
`lisa_kv_dump()`	打印当前 KV 后端内容

关键代码

if (lisa_kv_init() != 0) {
    return -1;
}

lisa_kv_set_int("kv.demo.int", 1234);

int value = 0;
if (lisa_kv_get_int("kv.demo.int", &value) == 0) {
    /* 使用 value */
}

char *string_value = NULL;
lisa_kv_set_string("kv.demo.str", "hello easyflash kv");
if (lisa_kv_get_string("kv.demo.str", &string_value) == 0) {
    /* 使用 string_value */
    lisa_kv_free(string_value);
}

uint8_t blob[] = { 0x11, 0x22, 0x33 };
lisa_kv_set_blob("kv.demo.blob", blob, sizeof(blob));

uint8_t *blob_value = NULL;
int blob_len = 0;
if (lisa_kv_get_blob("kv.demo.blob", &blob_value, &blob_len) == 0) {
    /* 使用 blob_value/blob_len */
    lisa_kv_free(blob_value);
}

配置说明

示例默认使用 EasyFlash 后端：

CONFIG_LISA_DEVICE=y
CONFIG_LISA_FLASH=y
CONFIG_LISA_KV=y
CONFIG_LISA_KV_TYPE_EF=y
CONFIG_LS_EF_START_ADDR=0x30100000
CONFIG_LS_EF_ENV_AREA_SIZE=8192
CONFIG_LS_EF_ERASE_MIN_SIZE=4096

CONFIG_LISA_KV_TYPE_EF 会选择 EasyFlash 模块，EasyFlash 本身依赖 LISA Flash，因此示例显式打开 CONFIG_LISA_FLASH 和 CONFIG_LISA_DEVICE。

EasyFlash 存储区域

配置项	示例值	说明
`CONFIG_LS_EF_START_ADDR`	`0x30100000`	EasyFlash ENV 起始地址
`CONFIG_LS_EF_ENV_AREA_SIZE`	`8192`	ENV 区域大小，单位为字节
`CONFIG_LS_EF_ERASE_MIN_SIZE`	`4096`	Flash 最小擦除粒度，单位为字节

上述地址和大小来自 modules/EasyFlash/Kconfig 的默认值，本示例显式写入 prj.conf，便于根据实际 Flash 分区调整。量产工程需要确认该区域不与 boot、app、OTA、资源分区或其他持久化数据重叠。

注意事项

后端选择：本示例使用 CONFIG_LISA_KV_TYPE_EF，不需要文件系统 mount；如果切换到 LSFS 后端，需要先完成文件系统初始化。
内存释放：lisa_kv_get_string() 和 lisa_kv_get_blob() 返回的内存必须用 lisa_kv_free() 释放。
key 长度：EasyFlash ENV key 长度受 CONFIG_LS_EF_ENV_NAME_MAX 限制，默认最大 32 字节。
数据清理：示例只删除自身使用的 kv.demo.* key，不调用 lisa_kv_clear()，避免清空设备上的其他 KV 数据。
持久化影响：EasyFlash 写入会占用 Flash ENV 区域，量产应用应规划好 ENV 区域地址和大小。