ArduMicroKV

1. 简介

ArduMicroKV 是一个基于 Arduino EEPROM 实现的简单键值（K - V）存储器库。该库允许用户在 Arduino 平台上方便地存储和检索键值对，支持基本数据类型和结构体类型。

2. 安装

将 ArduMicroKV 库文件夹复制到 Arduino 的库文件夹中（通常位于 Arduino/libraries 目录下）。然后重新启动 Arduino IDE，即可在 File -> Examples -> ArduMicroKV 中找到示例代码。

3. 文件结构

ArduMicroKV/
├── src/
│   ├── ArduMicroKV.h
│   └── ArduMicroKV.cpp
├── examples/
│   └── ArduMicroKVExample/
│       └── ArduMicroKVExample.ino
└── keywords.txt

3.1 src/ArduMicroKV.h

该头文件包含 ArduMicroKV 类的声明以及必要的包含文件。同时，为了避免模板类的链接问题，使用 #include "ArduMicroKV.cpp" 包含了实现文件。

3.2 src/ArduMicroKV.cpp

该文件包含 ArduMicroKV 类的具体实现，包括键值对的设置、获取、列表操作，以及辅助的查找、读写函数。

3.3 examples/ArduMicroKVExample/ArduMicroKVExample.ino

这是一个使用 ArduMicroKV 库的示例代码，展示了如何初始化库、设置键值对、获取键值对以及列出所有键值对。

3.4 keywords.txt

该文件用于在 Arduino IDE 中提供代码自动补全功能，包含了 ArduMicroKV 类及其主要方法的关键字。

4. 类和接口说明

4.1 ArduMicroKV 类

template <typename K, typename V>
class ArduMicroKV {
public:
    ArduMicroKV();
    bool Set(const K& key, const V& value);
    V Get(const K& key);
    std::vector<std::pair<K, V>> List();
private:
    int findKeyAddress(const K& key);
    int findEmptyAddress();
    void writeData(int address, const void* data, size_t size);
    void readData(int address, void* data, size_t size);
};

4.1.1 构造函数

ArduMicroKV();

• 功能：初始化 ArduMicroKV 对象。
• 参数：无。
• 返回值：无。

4.1.2 Set 方法

bool Set(const K& key, const V& value);

• 功能：设置键值对。如果键已存在，则更新其对应的值；如果键不存在，则添加新的键值对。
• 参数：
  • key：要设置的键，类型为 K。
  • value：要设置的值，类型为 V。
• 返回值：如果设置成功，返回 true；如果 EEPROM 空间不足，返回 false。

4.1.3 Get 方法

V Get(const K& key);

• 功能：根据键获取对应的值。
• 参数：
  • key：要获取值的键，类型为 K。
• 返回值：如果键存在，返回其对应的值；如果键不存在，返回值类型的默认值。

4.1.4 List 方法

std::vector<std::pair<K, V>> List();

• 功能：获取所有存储的键值对。
• 参数：无。
• 返回值：一个包含所有键值对的 std::vector，每个元素是一个 std::pair<K, V>。

4.2 私有方法

4.2.1 findKeyAddress 方法

int findKeyAddress(const K& key);

• 功能：查找指定键在 EEPROM 中的地址。
• 参数：
  • key：要查找的键，类型为 K。
• 返回值：如果键存在，返回其地址；如果键不存在，返回 -1。

4.2.2 findEmptyAddress 方法

int findEmptyAddress();

• 功能：查找 EEPROM 中的空闲地址，用于存储新的键值对。
• 参数：无。
• 返回值：如果找到空闲地址，返回该地址；如果 EEPROM 已满，返回 -1。

4.2.3 writeData 方法

void writeData(int address, const void* data, size_t size);

• 功能：将数据写入 EEPROM 的指定地址。
• 参数：
  • address：要写入的 EEPROM 地址。
  • data：要写入的数据指针。
  • size：要写入的数据大小。
• 返回值：无。

4.2.4 readData 方法

void readData(int address, void* data, size_t size);

• 功能：从 EEPROM 的指定地址读取数据。
• 参数：
  • address：要读取的 EEPROM 地址。
  • data：用于存储读取数据的指针。
  • size：要读取的数据大小。
• 返回值：无。

5. 使用示例

以下是一个使用 ArduMicroKV 库的示例代码：

#include <Arduino.h>
#include <ArduMicroKV.h>

// 定义一个结构体类型
struct Data {
    int value1;
    float value2;
};

ArduMicroKV<int, Data> kvStore;

void setup() {
    Serial.begin(9600);

    // 设置键值对
    Data data1 = {10, 20.5};
    if (kvStore.Set(1, data1)) {
        Serial.println("Set key - value pair successfully");
    } else {
        Serial.println("Failed to set key - value pair");
    }

    // 获取键对应的值
    Data retrievedData = kvStore.Get(1);
    Serial.print("Retrieved value1: ");
    Serial.print(retrievedData.value1);
    Serial.print(", value2: ");
    Serial.println(retrievedData.value2);

    // 列出所有键值对
    std::vector<std::pair<int, Data>> pairs = kvStore.List();
    for (const auto& pair : pairs) {
        Serial.print("Key: ");
        Serial.print(pair.first);
        Serial.print(", Value1: ");
        Serial.print(pair.second.value1);
        Serial.print(", Value2: ");
        Serial.println(pair.second.value2);
    }
}

void loop() {
    // 主循环中可以继续进行其他操作
}

6. 注意事项

• EEPROM 空间限制：由于 Arduino 的 EEPROM 空间有限，需要注意存储空间的使用，避免数据溢出。
• 读写性能：EEPROM 的读写操作相对较慢，频繁的读写操作可能会影响系统性能。