This example demonstrates how to use the Mbed OS Key Value Storage Global API.
KVStore is a key-value storage based API over a block device. Mbed OS provides several KVStore implementation options, that can be optimized to the specific application requirements and target hardware:
- TDBStore - Default implementation of the KVStore API. It provides static wear-leveling and quick access for when you have a small number of KV pairs.
- FileSystemStore - Class that provides a key-value store API on top of a POSIX-like file system API.
- SecureStore - Class that provides encryption, authentication and rollback protection on top of the KVStore API. It requires two KVStore implementations, one that provides the storage for the KV pairs and one providing storage for the CMACs that protect KV pairs stored in the KVStore.
KVStore Global APIs use Mbed OS KVStore configuration json file to define the selected KVStore implementation option of the above.
Note: The example is by default set to be used on K64F target with internal memory (see: mbed_app.json). If running in another target, make sure the target.json for the target includes the "components": ["FLASHIAP"] and device_has": ["FLASH"] or add this section to the example mbed_app.json.
You can find more information about Mbed OS Key Value Store Design and other related items in the kvstore design documentation.
Table of contents:
The example sets several key/value pairs, some are defined as 'dummy' and some as 'real'. The example demonstrates several possible scenarios that set, get, search and remove specific keys, and iterate all keys.
The example contains an mbed_app.json configuration file that demonstrates how to set KVStore configuration for a specific target (K64F) that may override the default configuration.
KVStore general API may use several types of key/value storage classes, according to the configuration, that run on top of an underlying Block Device. Each type has different HW requirements for the underlying Block Device.
- TDB_INTERNAL - may run on top of flash Block Device only (typically internal flash)
- TDB_EXTERNAL - requires external flash for the key/value storage and typically internal flash for its replay protection storage.
- TDB_EXTERNAL_NO_RBP - requires external flash for the key/value storage
- FILESYSTEM - may use either flash or SD card for the key/value storage and typically internal flash for its replay protection storage.
- FILESYSTEM_NO_RBP - may use either flash or SD card for the key/value storage
The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see contributing.md for more info.
This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide
Make sure you have an Mbed development environment set up. Get started with Mbed OS to set everything up.
From the command-line, import the example:
mbed import mbed-os-example-kvstore
cd mbed-os-example-kvstore
Invoke mbed compile, and specify the name of your platform and your favorite
toolchain (GCC_ARM, ARM, IAR). For example, for the ARM Compiler 5:
mbed compile -m K64F -t ARM
Your PC may take a few moments to compile your code. At the end, you'll see a result similar to:
[snip]
+--------------------------+-------+-------+-------+
| Module | .text | .data | .bss |
+--------------------------+-------+-------+-------+
| [fill] | 235 | 4 | 345 |
| [lib]/c.a | 31247 | 2472 | 89 |
| [lib]/gcc.a | 3112 | 0 | 0 |
| [lib]/misc | 204 | 4 | 28 |
| [lib]/nosys.a | 32 | 0 | 0 |
| main.o | 1719 | 0 | 0 |
| mbed-os/cmsis | 1029 | 0 | 84 |
| mbed-os/components | 4161 | 0 | 48 |
| mbed-os/drivers | 1487 | 0 | 100 |
| mbed-os/features | 42061 | 4 | 1426 |
| mbed-os/hal | 2043 | 4 | 68 |
| mbed-os/platform | 3095 | 260 | 134 |
| mbed-os/rtos | 7804 | 168 | 5969 |
| mbed-os/targets | 15561 | 12 | 413 |
| Subtotals |113790 | 2928 | 8704 |
+--------------------------+-------+-------+-------+
Total Static RAM memory (data + bss): 11632(+0) bytes
Total Flash memory (text + data): 116718(+0) bytes
Image: ./BUILD/K64F/ARM/mbed-os-example-kvstore.bin
- Connect your Mbed Enabled device to the computer over USB.
- Copy the binary file to the Mbed Enabled device.
- Press the reset button to start the program.
- Open the UART of the board in your favorite UART viewing program. For
example,
screen /dev/ttyACM0.
Note: The default serial port baud rate is 9600 bit/s. You may open serial term with:
mbed sterm -b 9600 -r
Expected output:
--- Mbed OS KVStore static API example ---
kv_reset
kv_reset -> 0
kv_set first dummy key
kv_set -> 0
kv_get_info of first key
kv_get_info -> 0
kv_get_info key: /kv/dummy_key1
kv_get_info info - size: 31, flags: 0
kv_get first key
kv_get -> 0
kv_get key: /kv/dummy_key1
kv_get value: kvstore_dummy_value_hello_world
kv_set second dummy key
kv_set -> 0
kv_set third key with Confidentiality, Integrity and Replay Protection flags
kv_set -> 0
kv_set Set 'Real' Key 1
kv_set -> 0
kv_set Set 'Real' Key 2 with flag write-once
kv_set -> 0
Removing 'Dummy' Keys
1) Removing dummy_key1
2) Removing dummy_key2
3) Removing dummy_auth_enc_key
Remaining with 'Real' Keys:
1) real_wo_key
2) real_key1
kv_remove write-once file - should fail!
kv_remove -> 274
kv_reset format kvstore (including write-once)
kv_reset -> 0
If you have problems, you can review the documentation for suggestions on what could be wrong and how to fix it.
The Global KVStore API options can be set up in the higher level Mbed OS KVSTore retargetting layer json configuration