drfhaust/nvs-eeprom

readme

# nvs-eeprom

Arduino-style EEPROM API backed by ESP-IDF NVS. No Arduino dependency required.

## Features

- **Familiar API** - Arduino EEPROM-like interface
- **Pure ESP-IDF** - No Arduino dependency
- **Persistent Storage** - Data survives power cycles
- **C and C++ Support** - Use functions or class wrapper
- **Type-safe Macros** - Read/write any data type easily

## Installation

```bash
idf.py add-dependency "drfhaust/nvs-eeprom"
```

## Quick Start

### C Style

```c
#include "nvs_eeprom.h"

void app_main() {
    // Initialize with 512 bytes
    nvs_eeprom_begin(512);

    // Write a byte
    nvs_eeprom_write(0, 42);
    nvs_eeprom_commit();

    // Read it back
    uint8_t value = nvs_eeprom_read(0);

    // Write a struct
    typedef struct {
        int32_t count;
        float temperature;
    } MyData;

    MyData data = { .count = 100, .temperature = 25.5f };
    NVS_EEPROM_PUT(10, data);
    nvs_eeprom_commit();

    // Read struct back
    MyData loaded;
    NVS_EEPROM_GET(10, loaded);

    // Cleanup
    nvs_eeprom_end();
}
```

### C++ Style

```cpp
#include "nvs_eeprom.h"

NVS_EEPROM EEPROM;

void app_main() {
    EEPROM.begin(512);

    // Write
    EEPROM.write(0, 42);
    EEPROM.commit();

    // Read
    uint8_t val = EEPROM.read(0);

    // Templates for any type
    float temp = 25.5f;
    EEPROM.put(10, temp);
    EEPROM.commit();

    float loaded;
    EEPROM.get(10, loaded);

    EEPROM.end();
}
```

## API Reference

### Core Functions

```c
bool nvs_eeprom_begin(size_t size);           // Initialize
uint8_t nvs_eeprom_read(size_t address);      // Read byte
void nvs_eeprom_write(size_t address, uint8_t value); // Write byte
bool nvs_eeprom_commit(void);                 // Save to flash
void nvs_eeprom_end(void);                    // Cleanup
size_t nvs_eeprom_length(void);               // Get size
```

### Block Operations

```c
size_t nvs_eeprom_readBytes(size_t addr, void *data, size_t len);
size_t nvs_eeprom_writeBytes(size_t addr, const void *data, size_t len);
```

### Convenience Macros

```c
// Read any type
MyStruct data;
NVS_EEPROM_GET(address, data);

// Write any type
NVS_EEPROM_PUT(address, data);
nvs_eeprom_commit();
```

## Example: Boot Counter

```c
#include "nvs_eeprom.h"
#include "esp_log.h"

#define BOOT_COUNT_ADDR 0

void app_main() {
    nvs_eeprom_begin(64);

    // Read boot count
    uint32_t boots = 0;
    NVS_EEPROM_GET(BOOT_COUNT_ADDR, boots);

    // Increment and save
    boots++;
    NVS_EEPROM_PUT(BOOT_COUNT_ADDR, boots);
    nvs_eeprom_commit();

    ESP_LOGI("main", "Boot count: %lu", boots);
}
```

## Notes

- Maximum recommended size: 4096 bytes (NVS blob limit)
- Uninitialized EEPROM reads as 0xFF (like real EEPROM)
- Always call `commit()` after writes to save to flash
- Data is stored in NVS partition under namespace "eeprom"

## License

MIT License - see [LICENSE](LICENSE)