pamoja_core/lib.rs
1//! Core abstractions for the pamoja device SDK.
2//!
3//! This crate defines the traits that every capability crate (for example
4//! `pamoja-mqtt`, `pamoja-serial`, or `pamoja-ros2`) implements. The
5//! core is protocol-agnostic: it models devices, sensors, actuators, transports,
6//! durable storage, and an event bus, and leaves concrete protocol support to the
7//! capability crates so that an application depends only on what it uses.
8//!
9//! The primary abstractions are:
10//!
11//! - [`Device`] - a connectable physical or virtual device.
12//! - [`Sensor`] - a source of typed readings.
13//! - [`Actuator`] - a sink for typed commands.
14//! - [`Telemetry`] - a stream of telemetry frames.
15//! - [`Transport`] - the outbound half of a link: connect, send, subscribe.
16//! - [`Receive`] - the inbound half: the messages a subscription delivers.
17//! - [`Store`] - a durable store-and-forward queue.
18//! - [`EventBus`] - a typed publish/subscribe channel.
19//! - [`Map`] and [`MapCommand`] - adapters that reshape a reading or a command, so a
20//! multi-channel driver feeds a consumer that wants one number.
21//! - [`Error`] and [`Result`] - the shared error model.
22//!
23//! # Examples
24//!
25//! Implementing [`Sensor`] for a temperature probe:
26//!
27//! ```
28//! use pamoja_core::{Result, Sensor};
29//!
30//! struct Thermometer {
31//! celsius: f32,
32//! }
33//!
34//! impl Sensor for Thermometer {
35//! type Reading = f32;
36//!
37//! async fn read(&mut self) -> Result<Self::Reading> {
38//! Ok(self.celsius)
39//! }
40//! }
41//!
42//! let _probe = Thermometer { celsius: 20.5 };
43//! ```
44
45// The core is `no_std` unless the default `std` feature is on, so it fits a
46// microcontroller. The owned types it needs (`String`, `Vec`) come from `alloc`.
47#![cfg_attr(not(feature = "std"), no_std)]
48// The public traits use `async fn`, which is intentional for this statically
49// dispatched SDK; the associated lint is therefore allowed crate-wide.
50#![allow(async_fn_in_trait)]
51
52extern crate alloc;
53
54pub mod adapt;
55pub mod bus;
56pub mod device;
57pub mod error;
58pub mod store;
59pub mod transport;
60
61pub use adapt::{Map, MapCommand};
62pub use bus::EventBus;
63pub use device::{Actuator, Device, Sensor, Telemetry};
64pub use error::{Error, Result};
65pub use store::Store;
66pub use transport::{topic_matches, Message, Receive, Transport};