xpanse_api/lib.rs
1//! Shared API for xpanse apps, module drivers, and platform firmware.
2//!
3//! Module drivers implement [`driver::Driver`] to turn an owned
4//! [`gpio_bank::GpioBank`] into capabilities stored in a [`registry::Registry`].
5//! Apps implement [`app::App`] and lease those capabilities for the duration of
6//! their run. The platform constructs buses through [`bus::allocator::BusAllocator`]
7//! while drivers are being initialized.
8//!
9//! # Runtime requirements
10//!
11//! This crate is `no_std`, but uses `alloc` for registry storage, trait objects,
12//! and boxed futures. Firmware using the API must install a global allocator
13//! before creating drivers, resources, or apps.
14//!
15//! # Typical lifecycle
16//!
17//! 1. Detect a module and select a driver using [`metadata::ModuleID`].
18//! 2. Call [`driver::Driver::create`] with the module's GPIO bank.
19//! 3. Check [`app::App::can_run`] and construct an app with [`app::App::new`].
20//! 4. Run the app, then call [`app::App::release`] to return its resource leases.
21//!
22//! Exact versions of HAL traits used by this API are available through
23//! [`reexports`], avoiding version mismatches in app and driver crates.
24
25#![no_std]
26extern crate alloc;
27
28/// Exact versions of dependencies whose types and traits appear in this crate's public API.
29///
30/// For example, import the async I2C trait implemented by
31/// `bus::i2c::I2cBusHandle` from this module:
32///
33/// ```ignore
34/// use xpanse_api::reexports::embedded_hal_async::i2c::I2c;
35/// ```
36pub mod reexports {
37 pub use defmt;
38 pub use embassy_futures;
39 pub use embassy_rp;
40 pub use embassy_time;
41 pub use embedded_hal;
42 pub use embedded_hal_async;
43 pub use embedded_hal_bus;
44 pub use embedded_io_async;
45 pub use slint;
46}
47
48pub mod app;
49pub mod bus;
50pub mod driver;
51pub mod gpio_bank;
52pub mod interfaces;
53pub mod metadata;
54pub mod registry;