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}