The Minimal Way to Store Configuration on Raspberry Pi Pico

Need to store settings like Wi-Fi credentials on Raspberry Pi Pico without a bulky filesystem? Here’s a minimal and reliable solution that works with flash memory directly. When developing with Raspberry Pi Pico (RP2040), you often need to store configuration data such as Wi-Fi credentials or sensor thresholds. While hardcoding these values into your source code is fine during prototyping, a more flexible solution is preferred for production or multi-device deployments. A common method is to write data directly to the onboard flash memory. However, flash memory has asymmetric erase and write operations, making it somewhat tricky to handle safely and efficiently. That’s where pico-kvstore comes in — a simple, robust option designed specifically to handle flash memory characteristics and support day-to-day configuration storage with ease. The Challenge of Writing Directly to Flash RP2040 allows storing configuration data directly in flash memory, for example by writing raw bytes or structs to an unused area. Flash memory updates involve two steps: erase and program. Erase is performed in 4KB blocks, while programming (writing) is done in 256-byte chunks. After erasing, memory is filled with 0xff. Programming a value changes 1 to 0 bit, but changing 0 to 1 bit requires erasing the entire block. To efficiently use flash memory while safely handling updates and rewrites, you need a custom algorithm and data structure. pico-kvstore abstracts away these complexities and provides a safe and user-friendly interface for persistent data storage. Simple and Safe Storage with “pico-kvstore” pico-kvstore is a lightweight key-value store designed to safely and efficiently store configuration or sensor data in RP2040’s flash memory. It handles the low-level flash constraints internally, exposing a simple API to the user: kvs_set(“KEY”, value, strlen(value)); kvs_get(“KEY”, buffer, sizeof(buffer)); While you only interact with keys and values, internally it uses a log-structured format with wear leveling and crash safety. For users who don’t need a full filesystem but want safe configuration storage, pico-kvstore is an ideal choice. Writing Wi-Fi Settings from the Host If your device uses Wi-Fi, being able to update SSID and password after deployment can be extremely useful — for example, when reusing the same firmware in different environments. pico-kvstore makes it easy to write these settings from your development host and read them back on the device during boot. 1. Writing Config from the Host Prepare your configuration files on the host and use a tool to create a pico-kvstore image file: # Write Wi-Fi credentials to a kvstore image kvstore-util create -f setting.bin kvstore-util set -f setting.bin -k SSID -v “Home_Wi-Fi” kvstore-util set -f setting.bin -k PASSWORD -v “Secret Password” Write the generated setting.bin image file to the Pico’s flash using picotool: # Write kvstore image to flash picotool load --offset 0x101de000 setting.bin 2. Reading Config at Boot On the firmware side, use kvs_get_str() to read stored settings: char ssid[33]; char pass[64]; kvs_init(); if (kvs_get_str("SSID", ssid, sizeof(ssid)) == 0 && kvs_get_str("PASSWORD", pass, sizeof(pass)) == 0) { connect_to_wifi(ssid, pass); } else { printf("No Wi-Fi config found.\n"); } Benefits of Separating Configuration from Firmware By using pico-kvstore, you can decouple your firmware and configuration, leading to several practical advantages: 1. No Need to Rebuild or Reflash You can update settings without touching the firmware, speeding up development and deployment. 2. Easy Per-Device Configuration Reuse the same firmware while customizing settings for each device. Ideal for batch provisioning and shipping. 3. Simpler Testing and Version Control With code and config separated, it’s easier to manage firmware versions and perform consistent testing. Getting Started pico-kvstore is easy to integrate into any Pico SDK-based project. Simply pull the code from GitHub and link it in your project. 1. Clone the Repository git clone --recursive https://github.com/oyama/pico-kvstore.git 2. Add to Your CMake Project Update your CMakeLists.txt as follows: add_subdirectory(pico-kvstore) target_link_libraries(your_project PRIVATE kvstore kvstore_default ) 3. Minimal Example #include “kvstore.h” int main(void) { kvs_init(); kvs_set("hello", "world", 5); char buffer[16]; if (kvs_get_str("hello", buffer, sizeof(buffer)) == 0) printf("hello=%s\n", buffer); return 0; } 4. Flash Storage Area You can customize the offset and size of the storage area depending on your project. See the repository README for details. Conclusion — Lightweight Storage for Flexible Operation pico-kvstore offers a simp

Apr 17, 2025 - 09:58

The Minimal Way to Store Configuration on Raspberry Pi Pico

Need to store settings like Wi-Fi credentials on Raspberry Pi Pico without a bulky filesystem? Here’s a minimal and reliable solution that works with flash memory directly.
When developing with Raspberry Pi Pico (RP2040), you often need to store configuration data such as Wi-Fi credentials or sensor thresholds. While hardcoding these values into your source code is fine during prototyping, a more flexible solution is preferred for production or multi-device deployments.
A common method is to write data directly to the onboard flash memory. However, flash memory has asymmetric erase and write operations, making it somewhat tricky to handle safely and efficiently.
That’s where pico-kvstore comes in — a simple, robust option designed specifically to handle flash memory characteristics and support day-to-day configuration storage with ease.

The Challenge of Writing Directly to Flash

RP2040 allows storing configuration data directly in flash memory, for example by writing raw bytes or structs to an unused area.
Flash memory updates involve two steps: erase and program. Erase is performed in 4KB blocks, while programming (writing) is done in 256-byte chunks. After erasing, memory is filled with 0xff. Programming a value changes 1 to 0 bit, but changing 0 to 1 bit requires erasing the entire block.
To efficiently use flash memory while safely handling updates and rewrites, you need a custom algorithm and data structure.
pico-kvstore abstracts away these complexities and provides a safe and user-friendly interface for persistent data storage.

Simple and Safe Storage with “pico-kvstore”

pico-kvstore is a lightweight key-value store designed to safely and efficiently store configuration or sensor data in RP2040’s flash memory.
It handles the low-level flash constraints internally, exposing a simple API to the user:

kvs_set(“KEY”, value, strlen(value));
kvs_get(“KEY”, buffer, sizeof(buffer));

While you only interact with keys and values, internally it uses a log-structured format with wear leveling and crash safety.
For users who don’t need a full filesystem but want safe configuration storage, pico-kvstore is an ideal choice.

Writing Wi-Fi Settings from the Host

If your device uses Wi-Fi, being able to update SSID and password after deployment can be extremely useful — for example, when reusing the same firmware in different environments.
pico-kvstore makes it easy to write these settings from your development host and read them back on the device during boot.

1. Writing Config from the Host

Prepare your configuration files on the host and use a tool to create a pico-kvstore image file:

# Write Wi-Fi credentials to a kvstore image
kvstore-util create -f setting.bin
kvstore-util set -f setting.bin -k SSID -v “Home_Wi-Fi”
kvstore-util set -f setting.bin -k PASSWORD -v “Secret Password”

Write the generated setting.bin image file to the Pico’s flash using picotool:

# Write kvstore image to flash
picotool load --offset 0x101de000 setting.bin

2. Reading Config at Boot

On the firmware side, use kvs_get_str() to read stored settings:

char ssid[33];
char pass[64];

kvs_init();
if (kvs_get_str("SSID", ssid, sizeof(ssid)) == 0 &&
    kvs_get_str("PASSWORD", pass, sizeof(pass)) == 0)
{
    connect_to_wifi(ssid, pass);
} else {
    printf("No Wi-Fi config found.\n");
}

Benefits of Separating Configuration from Firmware

By using pico-kvstore, you can decouple your firmware and configuration, leading to several practical advantages:

1. No Need to Rebuild or Reflash

You can update settings without touching the firmware, speeding up development and deployment.

2. Easy Per-Device Configuration

Reuse the same firmware while customizing settings for each device. Ideal for batch provisioning and shipping.

3. Simpler Testing and Version Control

With code and config separated, it’s easier to manage firmware versions and perform consistent testing.

Getting Started

pico-kvstore is easy to integrate into any Pico SDK-based project. Simply pull the code from GitHub and link it in your project.

1. Clone the Repository

git clone --recursive https://github.com/oyama/pico-kvstore.git

2. Add to Your CMake Project

Update your CMakeLists.txt as follows:

add_subdirectory(pico-kvstore)
target_link_libraries(your_project PRIVATE
  kvstore
  kvstore_default
)

3. Minimal Example

#include “kvstore.h”

int main(void) {
    kvs_init();

    kvs_set("hello", "world", 5);

    char buffer[16];
    if (kvs_get_str("hello", buffer, sizeof(buffer)) == 0) 
        printf("hello=%s\n", buffer);

    return 0;
}

4. Flash Storage Area

You can customize the offset and size of the storage area depending on your project. See the repository README for details.

Conclusion — Lightweight Storage for Flexible Operation

pico-kvstore offers a simple yet powerful solution for configuration persistence on resource-constrained platforms like the RP2040.
This article introduced the library using Wi-Fi settings as a concrete example, highlighting key benefits:

A simple API that abstracts away flash memory constraints
Robust structure with wear leveling and crash tolerance
Separation of firmware and configuration for operational flexibility

It’s especially useful for:

IoT devices that require reconfigurable parameters (Wi-Fi, thresholds, etc.)
Deployments with environment-specific settings
Applications that don’t need a full filesystem but benefit from structured storage

Future improvements may include better host integration tools for editing and inspecting config images. We hope pico-kvstore makes your next Pico project a little more efficient.