Skip to main content

sensor_db/
lib.rs

1//! # sensor-db
2//!
3//! Append-only sensor database for NOR flash on embedded devices.
4//!
5//! Designed for the RP2350 (Raspberry Pi Pico 2) and similar Cortex-M
6//! microcontrollers with external or internal QSPI NOR flash.
7//!
8//! ## Architecture
9//!
10//! ```text
11//! ┌───────────────────────────────────────────────┐
12//! │  SensorLogger  (clock injection)              │
13//! │  (generic over the ports — never over a log)  │
14//! ├───────────────────────────────────────────────┤
15//! │  LogSink / LogSource  (capability ports)      │
16//! │  ├── append · append_run · sync               │
17//! │  ├── latest · oldest · count · query_range    │
18//! │  └── typed API via the *Ext mixins            │
19//! ├───────────────────────────────────────────────┤
20//! │  TieredDb  (optional: removable media)        │
21//! │  ├── routes append() onboard ↔ card           │
22//! │  └── Spooler (copies onboard → card)          │
23//! ├───────────────────────────────────────────────┤
24//! │  SensorDb / SensorDbAsync  (high-level API)   │
25//! │  ├── append / sync / latest / query_range     │
26//! │  ├── compact / format / stats                 │
27//! │  ├── mount (footers + rebuild index)          │
28//! │  └── read_from (replication stream)           │
29//! ├───────────────────────────────────────────────┤
30//! │  Sector ring  (circular buffer of sectors)    │
31//! │  ├── SectorHeader (28 B, SD05: magic+version  │
32//! │  │   +log_id+epoch+seq+erase_cnt+crc)         │
33//! │  ├── SectorFooter (52 B, SDF2, last page:     │
34//! │  │   the summary, written at seal time)       │
35//! │  └── SectorSummary (in-RAM, per-sector)       │
36//! ├───────────────────────────────────────────────┤
37//! │  Entry log  (sequential within pages)         │
38//! │  ├── EntryHeader + payload + CRC-32C          │
39//! │  ├── Two-phase commit (flags 0xFF→0x00)       │
40//! │  └── Page-buffered writes (one RAM page)      │
41//! ├───────────────────────────────────────────────┤
42//! │  embedded-storage NorFlash trait               │
43//! │  embedded-storage-async (async feature)       │
44//! │  (RP2350 internal / external SPI / mock)      │
45//! └───────────────────────────────────────────────┘
46//! ```
47//!
48//! ## Quick Start (Sync)
49//!
50//! ```ignore
51//! use sensor_db::SensorDb;
52//!
53//! // RP2350: 256-byte pages, up to 512 sectors (2 MB region)
54//! let mut db: SensorDb<_, 256, 512> = SensorDb::new(
55//!     flash,            // embassy_rp::flash::Flash
56//!     0x0020_0000,      // base offset: 2 MB into flash
57//!     512,              // sector count
58//!     2,                // reserved sectors for headroom
59//! )?;
60//!
61//! db.mount()?;
62//!
63//! // Write sensor data
64//! db.append(0x01, timestamp_us, &temperature_bytes)?;
65//!
66//! // Query latest reading
67//! let mut buf = [0u8; 64];
68//! if let Some((header, n)) = db.latest(0x01, &mut buf)? {
69//!     let payload = &buf[..n];
70//!     // ...
71//! }
72//!
73//! // Range query with callback
74//! db.query_range(Some(0x01), t_start, t_end, |hdr, payload| {
75//!     // process each matching entry
76//!     true // return false to stop early
77//! })?;
78//! ```
79//!
80//! ## Quick Start (Async)
81//!
82//! Enable the `async` feature in `Cargo.toml`:
83//!
84//! ```ignore
85//! use sensor_db::SensorDbAsync;
86//!
87//! let mut db: SensorDbAsync<_, 256, 512> = SensorDbAsync::new(
88//!     flash, 0x0020_0000, 512, 2,
89//! )?;
90//! db.mount().await?;
91//! db.append(0x01, timestamp_us, &temperature_bytes).await?;
92//! ```
93
94#![no_std]
95#![deny(unsafe_code)]
96#![deny(missing_docs)]
97#![cfg_attr(docsrs, feature(doc_cfg))]
98
99pub mod db;
100pub mod entry;
101pub mod error;
102pub mod logger;
103#[cfg(feature = "std")]
104#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
105pub mod mock;
106pub mod partition;
107pub mod port;
108pub mod registry;
109pub mod run;
110pub mod schema;
111pub mod sector;
112pub mod spool;
113pub mod typed;
114
115#[cfg(feature = "async")]
116#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
117pub mod async_db;
118
119// Re-export main public types at crate root for convenience
120pub use db::{
121    CompactScope, DbConfig, DbStats, LogPosition, MountMode, MountStats, ReadCursor, SensorDb,
122    SpoolStats,
123};
124pub use entry::EntryHeader;
125pub use error::Error;
126pub use logger::{SensorLogger, SensorLoggerAsync};
127#[cfg(feature = "std")]
128#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
129pub use mock::{FlashOps, MockFlash, MockFlashError, PowerLossMode, RemovableFlash};
130pub use partition::{Partition, PartitionError};
131pub use port::{
132    LogSink, LogSinkAsync, LogSinkAsyncExt, LogSinkExt, LogSource, LogSourceAsync,
133    LogSourceAsyncExt, LogSourceExt,
134};
135pub use run::{RUN_FRAME_SIZE, Run};
136pub use schema::SCHEMA_TAG_SIZE;
137pub use sector::{LogId, SectorState, SectorSummary};
138pub use spool::{Removable, SpoolBudget, Spooler, TieredDb, WriteMode, WritePolicy};
139pub use typed::SensorData;
140
141/// Re-export of the `zerocopy` version this crate was built against.
142///
143/// `SensorData` is bounded on `zerocopy`'s traits, so `zerocopy` is a *public*
144/// dependency: a payload type must derive the same `FromBytes`/`IntoBytes` this
145/// crate names, from the same version. Importing them through here rather than
146/// from your own dependency makes a version skew impossible to introduce
147/// silently — the failure mode otherwise is `the trait bound
148/// `Temperature: FromBytes` is not satisfied` pointing at a type that plainly
149/// derives it.
150///
151/// ```ignore
152/// use sensor_db::zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
153/// ```
154///
155/// `zerocopy` must still appear in your `Cargo.toml`, because its derives
156/// expand to absolute `::zerocopy::` paths. Keep the version in step with this
157/// re-export.
158pub use zerocopy;
159
160/// Derive [`SensorData`], binding a type to a sensor ID.
161///
162/// Requires the `derive` feature. See the macro's own documentation for the
163/// `#[sensor(id = ..., version = ...)]` attribute.
164#[cfg(feature = "derive")]
165#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
166pub use sensor_db_derive::SensorData;
167
168#[cfg(feature = "async")]
169#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
170pub use async_db::SensorDbAsync;
171#[cfg(feature = "async")]
172#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
173pub use spool::{SpoolerAsync, TieredDbAsync};
174
175/// Every public value type that reports state must format under `defmt`.
176///
177/// A generic function's body is type-checked whether or not it is ever called,
178/// so this is a compile-time check that costs nothing at runtime and cannot be
179/// skipped. It is written this way rather than as a `#[test]` because a test
180/// *binary* linking `defmt` needs a global logger this crate does not provide —
181/// which is the same reason `--all-features` must never reach a cargo command
182/// that links one.
183///
184/// The rule it enforces: if a caller can hold it and would want it in a log
185/// line, it formats. The feature previously covered [`Error`] and four wire
186/// types but none of the statistics, which is the half an operator actually
187/// reads.
188#[cfg(feature = "defmt")]
189#[allow(dead_code)]
190fn defmt_covers_every_reported_type() {
191    fn formats<T: defmt::Format>() {}
192
193    // The log's own state.
194    formats::<DbStats>();
195    formats::<DbConfig>();
196    formats::<MountStats>();
197    formats::<MountMode>();
198    formats::<CompactScope>();
199    formats::<LogId>();
200    formats::<LogPosition>();
201    formats::<ReadCursor>();
202    formats::<SectorState>();
203    formats::<SectorSummary>();
204    formats::<sector::SectorClass>();
205    formats::<entry::EntryKind>();
206    formats::<Error>();
207
208    // Replication, where an operator is watching a card fill and drain.
209    formats::<SpoolStats>();
210    formats::<SpoolBudget>();
211    formats::<spool::SpoolProgress>();
212    formats::<spool::Attached>();
213    formats::<spool::VolumeFill>();
214    formats::<spool::RunFingerprint>();
215    formats::<spool::policy::CursorScan>();
216    formats::<spool::policy::SlotPlan>();
217    formats::<spool::CursorKind>();
218    formats::<spool::CursorRegion>();
219    formats::<spool::cursor::SlotAddress>();
220    formats::<WriteMode>();
221    formats::<WritePolicy>();
222    formats::<db::Replicated>();
223}