ekv-fs

A chunked, #![no_std], fully asynchronous virtual file system on top of Embassy ekv for embedded Rust.

Why

Flash on microcontrollers needs wear leveling. ekv provides a safe KV store, but not paths, large blobs, or streaming reads. ekv-fs maps path strings to chunked keys so you can store and read files with bounded RAM—pure Rust, no C FFI.

Features

no_std with heapless paths and const-generic MAX_PATH_LEN / CHUNK_SIZE
Async API aligned with Embassy
Streaming reads via EkvFile
Replace-safe writes — overwriting a file removes old chunks in one transaction

Quick start

[dependencies]
ekv-fs = "0.2"
ekv = { version = "1", default-features = false }
embassy-sync = { version = "0.6", default-features = false }

use ekv::{Config, Database};
use ekv_fs::EkvFs;

// After you have a formatted `Database` on your flash driver:
let fs = EkvFs::<_, _, 64, 512>::new(&db);

fs.write_file("/notes.txt", b"hello").await?;
let meta = fs.stat("/notes.txt").await?;
let mut file = fs.open("/notes.txt").await?;
let mut buf = [0u8; 32];
let n = file.read(&mut buf).await?;
fs.delete_file("/notes.txt").await?;

Pick MAX_PATH_LEN and CHUNK_SIZE to match your MCU RAM budget. MAX_PATH_LEN must be at most KEY_BUF_CAP - KEY_SUFFIX_OVERHEAD (104 bytes with the default KEY_BUF_CAP of 128).

API scope (v0.2)

Supported	Not yet
Whole-file write / replace	Append, partial write
Stat, open, sequential read	Seek
Delete	Directory listing, rename

Paths are opaque strings (e.g. /photos/cat.jpg); there is no directory tree.

Errors

Operations return ekv_fs::Error: NotFound, PathTooLong, KeyTooLong, Database, Serialize.

MSRV

Rust 1.87 or newer (edition 2024; required by heapless 0.9; see rust-version in Cargo.toml).

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

ekv-fs 0.2.0