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