Skip to main content

Crate sensor_db

Crate sensor_db 

Source
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;std
pub use mock::MockFlash;std
pub use mock::MockFlashError;std
pub use mock::PowerLossMode;std
pub use mock::RemovableFlash;std
pub 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;async
pub use spool::SpoolerAsync;async
pub use spool::TieredDbAsync;async
pub use zerocopy;

Modules§

async_dbasync
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.
mockstd
Mock NOR flash implementation for testing.
partition
Partition — a NorFlash view 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 SensorData trait.

Macros§

sensor_registry
Assert at compile time that no two sensor types collide.

Derive Macros§

SensorDataderive
Derive SensorData, binding a type to a sensor ID.