1@page kv kv
2
3[更正文档](https://gitee.com/alios-things/kv/edit/master/README.md)      [贡献说明](https://help.aliyun.com/document_detail/302301.html)
4
5# 概述
6对于嵌入式系统应用中，频繁使用的参数存储，过程变量存储等操作，AliOS-Things为用户提供了一种更加直观易于理解的基于键值对的存储方式，如报警温度=50度，可以通过定义一个键值对：{"AlarmTemp":50}来进行存储。获取时，也只需通过AlarmTemp这个关键字（键/KEY)即可快速获取和重新写入。KV将用户的指定片内flash扇区或eeprom虚拟为有一个存储空间，并且帮助用户管理键值对之间的映射关系，用户无需关心具体的值被写到哪里了，仅需要通过对键的操作即可完成数据的存取。该组件目前针对Nor flash设备。
7组件支持以下功能：
8- key-value pair set
9- key-value pair get
10- key-value pair delete
11- key-value pair delete for group (same prefix)
12
13## 版权信息
14> Apache license v2.0
15
16## 目录结构
17```tree
18├── src
19│   ├── kv_adapt.c   # kv和flash的适配层
20│   ├── kv_aos.c     # kv的aos api接口
21│   ├── kv.c         # kv的核心实现代码
22│   ├── kv_cli.c     # kv cli注册命令
23│   └── kv_secure.c  # kv的安全存储适配层
24├── include
25│   ├── aos
26│   │   └── kv.h     # kv的对外AOS API
27│   └── kv_api.h     # kv_开头的API
28├── internal         # 内部头文件
29├── package.yaml     # 编译配置文件
30└── example
31    └── kv_example.c # kv示例代码
32```
33
34## 依赖组件
35* rhino
36* cli
37
38# 常用配置
39系统中相关配置已有默认值，如需修改配置，统一在yaml中**def_config**节点修改，具体如下：
40> kv分区大小: 默认8K bytes, 如需修改，在yaml中修改KV_CONFIG_TOTAL_SIZE配置
41```yaml
42def_config:
43  KV_CONFIG_TOTAL_SIZE: 4096
44```
45> kv分区号，默认HAL_PARTITION_PARAMETER_2，可按照实际需要修改yaml配置如：
46```yaml
47def_config:
48  KV_CONFIG_PARTITION: 2
49```
50> kv block bit大小，默认12，可修改yaml配置如：
51```yaml
52def_config:
53  KV_CONFIG_BLOCK_SIZE_BITS: 2
54```
55> kv 资源回收任务优先级，默认32，可修改yaml配置如：
56```yaml
57def_config:
58  KV_CONFIG_TASK_PRIORITY: 31
59```
60> kv 资源回收任务栈大小，默认4KB，可修改yaml配置如:
61```yaml
62def_config:
63  KV_CONFIG_TASK_STACK_SIZE: 2048
64```
65> kv 存储key最大长度，默认为128，可修改yaml配置如：
66```yaml
67def_config:
68  KV_CONFIG_MAX_KEY_LEN: 256
69```
70> kv 存储value最大长度，默认为512，可修改yaml配置如：
71```yaml
72def_config:
73  KV_CONFIG_MAX_VAL_LEN: 256
74```
75
76# API说明
77- 参考 [kv_aos_api](https://g.alicdn.com/alios-things-3.3/doc/group__kv__aos__api.html)
78
79# 使用示例
80
81组件使用示例相关的代码下载、编译和固件烧录均依赖AliOS Things配套的开发工具，所以首先需要参考[《AliOS Things集成开发环境使用说明之搭建开发环境》](https://help.aliyun.com/document_detail/302378.html)，下载安装。
82待开发环境搭建完成后，可以按照以下步骤进行示例的测试。
83
84## 步骤1 创建或打开工程
85
86**打开已有工程**
87
88如果用于测试的案例工程已存在，可参考[《AliOS Things集成开发环境使用说明之打开工程》](https://help.aliyun.com/document_detail/302381.html)打开已有工程。
89
90**创建新的工程**
91
92组件的示例代码可以通过编译链接到AliOS Things的任意案例（solution）来运行，这里选择helloworld_demo案例。helloworld_demo案例相关的源代码下载可参考[《AliOS Things集成开发环境使用说明之创建工程》](https://help.aliyun.com/document_detail/302379.html)。
93
94## 步骤2 添加组件
95
96案例下载完成后，需要在helloworld_demo组件的package.yaml中添加对组件的依赖：
97
98```yaml
99
100depends:
101  - kv: master # helloworld_demo中引入kv组件
102
103```
104
105## 步骤3 下载组件
106
107在已安装了  的开发环境工具栏中，选择Terminal -> New Terminal启动终端，并且默认工作路径为当前工程的workspace，此时在终端命令行中输入：
108
109```shell
110
111aos install kv
112
113```
114
115上述命令执行成功后，组件源码则被下载到了./components/kv路径中。
116
117## 步骤4 添加示例
118
119在kv组件的package.yaml中添加[example示例代码](https://gitee.com/alios-things/kv/tree/master/example)：
120
121```yaml
122source_file:
123  - "src/*.c"
124  - "example/kv_example.c" # add kv_example.c
125```
126
127## 步骤5 编译固件
128
129在示例代码已经添加至组件的配置文件，并且helloworld_demo已添加了对该组件的依赖后，就可以编译helloworld_demo案例来生成固件了，具体编译方法可参考[《AliOS Things集成开发环境使用说明之编译固件》](https://help.aliyun.com/document_detail/302384.html)。
130
131## 步骤6 烧录固件
132
133helloworld_demo案例的固件生成后，可参考[《AliOS Things集成开发环境使用说明之烧录固件》](https://help.aliyun.com/document_detail/302383.html)来烧录固件。
134
135## 步骤7 打开串口
136
137固件烧录完成后，可以通过串口查看示例的运行结果，打开串口的具体方法可参考[《AliOS Things集成开发环境使用说明之查看日志》](https://help.aliyun.com/document_detail/302382.html)。
138
139当串口终端打开成功后，可在串口中输入help来查看已添加的测试命令。
140
141## 步骤8 测试示例
142> CLI命令行输入：
143```shell
144kv_example
145```
146
147**关键日志**
148> CLI日志：
149```shell
150kv comp test success!
151```
152
153# 注意事项
154如果需要使用kv的安全加解密(mbedtls version)，就需要对接两个接口：**kv_secure_get_key** and **kv_secure_get_iv**。(declare in `kv_adapt.h`)
155Example:
156```C
157uint8_t aes_key[32] = {
158        0x86, 0xf6, 0xd2, 0xbe, 0x45, 0xb5, 0xab, 0x9c,
159        0xc7, 0xd5, 0x96, 0xf7, 0xaf, 0x45, 0xfa, 0xf7,
160        0xbe, 0x6a, 0x5d, 0xb0, 0x04, 0xc4, 0xde, 0xb5,
161        0xf5, 0x0c, 0x4f, 0xc3, 0x71, 0x19, 0x3e, 0xe8
162    };
163
164uint8_t aes_iv[16]  = {
165        0xef, 0x80, 0x18, 0xdc, 0xa3, 0x72, 0x72, 0x31,
166        0x99, 0x2e, 0x3a, 0xba, 0x60, 0xf5, 0x0b, 0xd4
167    };
168
169uint8_t* kv_secure_get_key(uint32_t len)
170{
171    if ((len <= 0) || (len > sizeof(aes_key))) {
172        return NULL;
173    }
174
175    return aes_key;
176}
177
178uint8_t* kv_secure_get_iv(uint32_t len)
179{
180    if ((len <= 0) || (len > sizeof(aes_iv))) {
181        return NULL;
182    }
183
184    return aes_iv;
185}
186```
187
188# FAQ
189Q1： 在不知道key值的情况下，可以遍历kv分区吗？
190> 答：可以通过串口输入cli命令**kv list**遍历输出所有的kv值。
191
192