Expand description
§sensor-db
Append-only sensor database for NOR flash on embedded devices.
Designed for the RP2350 (Raspberry Pi Pico 2) and similar Cortex-M microcontrollers with external or internal QSPI NOR flash.
§Architecture
┌───────────────────────────────────────────────┐
│ SensorLogger (clock injection) │
│ (generic over the ports — never over a log) │
├───────────────────────────────────────────────┤
│ LogSink / LogSource (capability ports) │
│ ├── append · append_run · sync │
│ ├── latest · oldest · count · query_range │
│ └── typed API via the *Ext mixins │
├───────────────────────────────────────────────┤
│ TieredDb (optional: removable media) │
│ ├── routes append() onboard ↔ card │
│ └── Spooler (copies onboard → card) │
├───────────────────────────────────────────────┤
│ SensorDb / SensorDbAsync (high-level API) │
│ ├── append / sync / latest / query_range │
│ ├── compact / format / stats │
│ ├── mount (footers + rebuild index) │
│ └── read_from (replication stream) │
├───────────────────────────────────────────────┤
│ Sector ring (circular buffer of sectors) │
│ ├── SectorHeader (28 B, SD05: magic+version │
│ │ +log_id+epoch+seq+erase_cnt+crc) │
│ ├── SectorFooter (52 B, SDF2, last page: │
│ │ the summary, written at seal time) │
│ └── SectorSummary (in-RAM, per-sector) │
├───────────────────────────────────────────────┤
│ Entry log (sequential within pages) │
│ ├── EntryHeader + payload + CRC-32C │
│ ├── Two-phase commit (flags 0xFF→0x00) │
│ └── Page-buffered writes (one RAM page) │
├───────────────────────────────────────────────┤
│ embedded-storage NorFlash trait │
│ embedded-storage-async (async feature) │
│ (RP2350 internal / external SPI / mock) │
└───────────────────────────────────────────────┘§Quick Start (Sync)
ⓘ
use sensor_db::SensorDb;
// RP2350: 256-byte pages, up to 512 sectors (2 MB region)
let mut db: SensorDb<_, 256, 512> = SensorDb::new(
flash, // embassy_rp::flash::Flash
0x0020_0000, // base offset: 2 MB into flash
512, // sector count
2, // reserved sectors for headroom
)?;
db.mount()?;
// Write sensor data
db.append(0x01, timestamp_us, &temperature_bytes)?;
// Query latest reading
let mut buf = [0u8; 64];
if let Some((header, n)) = db.latest(0x01, &mut buf)? {
let payload = &buf[..n];
// ...
}
// Range query with callback
db.query_range(Some(0x01), t_start, t_end, |hdr, payload| {
// process each matching entry
true // return false to stop early
})?;§Quick Start (Async)
Enable the async feature in Cargo.toml:
ⓘ
use sensor_db::SensorDbAsync;
let mut db: SensorDbAsync<_, 256, 512> = SensorDbAsync::new(
flash, 0x0020_0000, 512, 2,
)?;
db.mount().await?;
db.append(0x01, timestamp_us, &temperature_bytes).await?;Re-exports§
pub use db::CompactScope;pub use db::DbConfig;pub use db::DbStats;pub use db::LogPosition;pub use db::MountMode;pub use db::MountStats;pub use db::ReadCursor;pub use db::SensorDb;pub use db::SpoolStats;pub use entry::EntryHeader;pub use error::Error;pub use logger::SensorLogger;pub use logger::SensorLoggerAsync;pub use mock::FlashOps;stdpub use mock::MockFlash;stdpub use mock::MockFlashError;stdpub use mock::PowerLossMode;stdpub use mock::RemovableFlash;stdpub use partition::Partition;pub use partition::PartitionError;pub use port::LogSink;pub use port::LogSinkAsync;pub use port::LogSinkAsyncExt;pub use port::LogSinkExt;pub use port::LogSource;pub use port::LogSourceAsync;pub use port::LogSourceAsyncExt;pub use port::LogSourceExt;pub use run::RUN_FRAME_SIZE;pub use run::Run;pub use schema::SCHEMA_TAG_SIZE;pub use sector::LogId;pub use sector::SectorState;pub use sector::SectorSummary;pub use spool::Removable;pub use spool::SpoolBudget;pub use spool::Spooler;pub use spool::TieredDb;pub use spool::WriteMode;pub use spool::WritePolicy;pub use typed::SensorData;pub use async_db::SensorDbAsync;asyncpub use spool::SpoolerAsync;asyncpub use spool::TieredDbAsync;asyncpub use zerocopy;
Modules§
- async_
db async - Async version of SensorDb for use with Embassy and
embedded-storage-async. - db
- SensorDb implementation.
- entry
- Entry header and CRC computation.
- error
- Error types for sensor-db.
- logger
- Convenience wrapper that injects timestamps from a user-provided clock.
- mock
std - Mock NOR flash implementation for testing.
- partition
Partition— aNorFlashview of a sub-range of a larger device.- port
- Capability ports: what a caller needs from a log, without naming which log.
- registry
- Compile-time checking of the sensor ID space.
- run
- Run-encoded entries: many evenly spaced samples under one entry header.
- schema
- Schema versioning for typed payloads.
- sector
- Sector header and in-RAM sector index.
- spool
- Store-and-forward spooling from an onboard log to a removable volume.
- typed
- Binding a Rust type to a sensor ID: the
SensorDatatrait.
Macros§
- sensor_
registry - Assert at compile time that no two sensor types collide.
Derive Macros§
- Sensor
Data derive - Derive
SensorData, binding a type to a sensor ID.