ssh_stamp_hal/
lib.rs

1// SPDX-FileCopyrightText: 2026 Roman Valls Guimera <brainstorm@nopcode.org>
2// SPDX-FileCopyrightText: 2026 Julio Beltran Ortega <jubeormk1@gmail.com>
3// SPDX-FileCopyrightText: 2026 Angus Gratton <gus@projectgus.com>
4// SPDX-FileCopyrightText: 2026 Sergio Gasquez <sergio.gasquez@gmail.com>
5// SPDX-FileCopyrightText: 2026 pancake <pancake@nopcode.org>
6// SPDX-FileCopyrightText: 2026 Gabriel Ku Wei Bin <gabriel.ku@fsfe.org>
7// SPDX-FileCopyrightText: 2026 Anthony Tambasco <anthony.tambasco@fastmail.com>
8//
9// SPDX-License-Identifier: GPL-3.0-or-later
10
11//! # SSH-Stamp Hardware Abstraction Layer
12//!
13//! Platform-agnostic traits for ssh-stamp, following the embedded-hal pattern
14//! of fine-grained, composable traits. Each supported platform implements
15//! these traits in a separate port crate (e.g. `ssh-stamp-esp32`).
16//!
17//! ## Overview
18//!
19//! - Peripheral traits: [`WifiHal`], [`NetworkProviderHal`], [`RngHal`],
20//!   [`HashHal`], [`TimerHal`], [`OtaActions`]
21//! - Configuration: [`WifiApConfigStatic`]
22//! - Error handling: [`HalError`] with variants per peripheral type
23//!
24//! For standard peripheral traits (`Read`, `Write`, flash storage), this crate
25//! defers to `embedded-io-async` and `embedded-storage-async` from the
26//! embedded-hal ecosystem rather than redefining them.
27//!
28//! ## HAL trait map
29//!
30//! | Trait                    | Required?    | ESP32 impl      |
31//! |-------------------------|--------------|------------------|
32//! | [`NetworkProviderHal`]   | always       | `EspWifi`         |
33//! | [`WifiHal`]              | `WiFi` ports | `EspWifi`         |
34//! | `BufferedSerial`          | always       | `BufferedUart`    |
35//! | [`OtaActions`]           | sftp-ota     | `EspOtaWriter`      |
36//! | `PlatformServices`        | always       | `EspPlatform`      |
37//!
38//! [`WifiHal`] is required only for WiFi-based ports. Ethernet ports would
39//! implement [`NetworkProviderHal`] directly.
40//!
41//! ## Adding a new port
42//!
43//! To port ssh-stamp to a new microcontroller family:
44//!
45//! 1. Create the port crate under the manufacturer's directory,
46//!    `boards/ssh-stamp-<manufacturer>/ssh-stamp-<platform>/`, with a lib
47//!    (`src/lib.rs`) and a bin (`src/bin/ssh-stamp-<platform>.rs`), and add
48//!    it to `members` in the workspace `Cargo.toml`. Its board support crate
49//!    (`ssh-stamp-<platform>-boards`) and HIL tests
50//!    (`ssh-stamp-<platform>-hil`) sit next to it. The Espressif port in
51//!    `boards/ssh-stamp-esp/` is the reference.
52//! 2. Implement the needed traits from `ssh-stamp-hal/src/traits/`. At a
53//!    minimum: a [`NetworkProviderHal`] (or [`WifiHal`]), [`OtaActions`], and
54//!    a UART type implementing the `BufferedSerial` trait from the `ssh-stamp`
55//!    crate.
56//! 3. Implement the `PlatformServices` trait from `ssh-stamp::platform` for
57//!    the platform.
58//! 4. In the binary, mirror the ESP32 boot flow: bring up peripherals, load
59//!    config via `ssh-stamp::store::load_or_create`, spawn the UART task,
60//!    bring up the network, call `ssh-stamp::app::run_app`.
61//! 5. Register the chips and boards in `xtask/src/board.rs` so that
62//!    `cargo xtask <board> build` works for them.
63//!
64//! No changes are needed in `ssh-stamp` or `ssh-stamp-hal`.
65
66#![no_std]
67#![forbid(unsafe_code)]
68#![deny(clippy::mem_forget)]
69#![deny(unused_imports)]
70#![deny(unused_variables)]
71
72pub mod config;
73pub mod error;
74pub mod traits;
75
76pub use config::{BandMode, Parity, UartConfig, UartParams, WifiApConfigStatic};
77pub use error::{FlashError, HalError, HashError, UartError, WifiError};
78pub use traits::*;
ssh_stamp_hal/lib.rs

ssh_stamp_hal/
lib.rs
