Skip to content

Traits refactor to support more MCU targets (other than Espressif)#85

Merged
brainstorm merged 56 commits into
mainfrom
traits_refactor
May 21, 2026
Merged

Traits refactor to support more MCU targets (other than Espressif)#85
brainstorm merged 56 commits into
mainfrom
traits_refactor

Conversation

@brainstorm

@brainstorm brainstorm commented Mar 28, 2026

Copy link
Copy Markdown
Owner

This refactor is meant to generalize common functionality and abstract MCU traits so that new targets can be easily ported to SSH Stamp.

Fixes issue #65
Fixes issue #101

... eventually, still yet to decide if this traits architecture works for us.

Read ARCHITECTURE.md for a Birds-eye view about what I'm attempting to put together, let me know if names/structure or whatever looks off!

I.e: probably the MicroPython naming that Julio used is more appropriate: machine/device vs hal/hal-manufacturer.

@brainstorm brainstorm marked this pull request as ready for review April 9, 2026 17:56

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Refactors the project toward a “platform-agnostic core + platform-specific HAL” architecture (issue #65), moving ESP32 hardware details out of the main ssh-stamp crate into dedicated workspace crates and updating OTA tooling accordingly.

Changes:

  • Introduces ssh-stamp-hal (traits/config/errors) and ssh-stamp-esp32 (ESP32 implementations + bootable binary).
  • Reworks the core ssh-stamp crate to be platform-agnostic (new app entrypoints, PlatformServices abstraction, generic flash store I/O).
  • Renames the OTA CLI utility from ota-packer to packer and updates workflows/scripts/docs.

Reviewed changes

Copilot reviewed 59 out of 61 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
storage/src/lib.rs Removes prior ESP-specific storage + flash singleton from the old storage crate.
storage/src/esp_ota.rs Removes prior ESP OTA writer implementation from storage.
storage/Cargo.toml Removes the storage crate manifest (crate no longer part of the workspace).
ssh-stamp-hal/Cargo.toml Adds new HAL trait crate manifest.
ssh-stamp-hal/src/lib.rs Defines and re-exports HAL surface (traits/config/errors).
ssh-stamp-hal/src/config.rs Adds shared UART/WiFi config types for HAL consumers.
ssh-stamp-hal/src/error.rs Adds unified HalError + peripheral-specific error enums.
ssh-stamp-hal/src/traits/mod.rs Central trait module/re-exports for peripherals.
ssh-stamp-hal/src/traits/flash.rs Defines OtaActions trait for OTA partition actions.
ssh-stamp-hal/src/traits/hash.rs Defines HashHal trait for hash/HMAC operations.
ssh-stamp-hal/src/traits/rng.rs Defines RngHal trait for RNG operations.
ssh-stamp-hal/src/traits/timer.rs Defines TimerHal trait for timing/delays.
ssh-stamp-hal/src/traits/uart.rs Defines UartHal trait for UART read/write/configure.
ssh-stamp-hal/src/traits/network/mod.rs Adds network trait hierarchy module.
ssh-stamp-hal/src/traits/network/provider.rs Defines NetworkProviderHal base trait.
ssh-stamp-hal/src/traits/network/wifi.rs Defines WifiHal extension trait.
ssh-stamp-esp32/Cargo.toml Adds ESP32 platform crate manifest + per-chip features.
ssh-stamp-esp32/build.rs Moves ESP32 link-arg setup into the ESP32 crate.
ssh-stamp-esp32/src/lib.rs ESP32 crate root: re-exports implementations and helpers.
ssh-stamp-esp32/src/flash.rs Implements flash singleton + EspOtaWriter using ssh-stamp-hal::OtaActions.
ssh-stamp-esp32/src/hash.rs Provides ESP32 hash/HMAC implementation (currently software-backed).
ssh-stamp-esp32/src/network/mod.rs Exposes ESP32 network helpers.
ssh-stamp-esp32/src/network/wifi.rs Implements WifiHal + NetworkProviderHal for ESP32 WiFi AP + DHCP.
ssh-stamp-esp32/src/platform.rs Implements core PlatformServices for ESP32 (save/reset/OTA/UART-activate).
ssh-stamp-esp32/src/rng.rs Implements RNG and registers custom getrandom hook on ESP32.
ssh-stamp-esp32/src/timer.rs Implements TimerHal for ESP32 via embassy_time.
ssh-stamp-esp32/src/uart.rs Provides buffered UART implementation for the SSH bridge.
ssh-stamp-esp32/src/bin/ssh-stamp-esp32.rs New ESP32-family binary wiring peripherals then calling platform-agnostic app.
src/lib.rs Makes core crate platform-agnostic; enables strict unused-import/var denies; adds new modules.
src/app.rs Adds platform-agnostic app entrypoints (prepare_ap_config, run_app).
src/platform.rs Introduces PlatformServices trait for persistence/reset/OTA/UART activation.
src/store.rs Generalizes flash store read/write over NorFlash/ReadStorage; adds config migration.
src/settings.rs Adjusts DEFAULT_IP type and removes per-chip UART pin cfg from core crate.
src/serve.rs Refactors SSH event loop to delegate to handle module and platform services.
src/serial.rs Generalizes serial bridge over a BufferedSerial trait (platform-provided).
src/handle.rs Splits SSH event handling into smaller functions; integrates platform services + OTA writer.
src/config.rs Makes config creation take platform-provided MAC; exposes SSID/PSK generators for migration.
src/errors.rs Updates file header (license/copyright).
src/main.rs Removes old ESP32-specific main from core crate.
src/espressif/mod.rs Removes old ESP-specific module from core crate.
src/espressif/net.rs Removes old ESP-specific networking implementation from core crate.
src/espressif/rng.rs Removes old ESP-specific RNG implementation from core crate.
src/espressif/buffered_uart.rs Removes old ESP-specific buffered UART implementation from core crate.
src/espressif/hash.rs Removes old ESP-specific hash placeholder code from core crate.
ota/Cargo.toml Adds dependency on ssh-stamp-hal; renames bin to packer.
ota/src/lib.rs Drops otatraits module and re-exports updated packer naming.
ota/src/otatraits.rs Removes OTA trait definition (now sourced from ssh-stamp-hal).
ota/src/handler.rs Switches OTA handler to ssh_stamp_hal::OtaActions.
ota/src/sftpserver.rs Updates SFTP server to new handle init trait; updates status code usage.
ota/src/tlv.rs Updates TLV parsing context import; rejects unknown TLVs instead of skipping.
ota/src/bin/packer.rs Renames CLI from ota-packer to packer.
ota/src/bin/README.md Updates docs to packer naming.
ota/README.md Updates docs to packer naming.
ota/test-hil-esp32c6-e2e.sh Updates HIL script to use cargo packer.
docs/ARCHITECTURE.md Adds architecture documentation explaining the new crate split and invariants.
build.rs Removes root build script (moved to ESP32 crate).
Cargo.toml Converts repo into a multi-crate workspace; adds shared workspace deps; updates aliases/features/docs.
Cargo.lock Updates lockfile for new crates/deps and renamed bin.
.cargo/config.toml Updates cargo aliases for new package/bin layout and renamed packer.
.github/workflows/tests.yml Renames OTA job to packer (utility tests).
.github/workflows/build.yml Updates clippy/build steps to target ssh-stamp-esp32 binary and new packer alias.

Comment thread ssh-stamp-esp32/src/network/wifi.rs
Comment thread src/store.rs
Comment thread src/handle.rs Outdated
Comment thread src/serve.rs Outdated
Comment thread src/app.rs Outdated
Comment thread ssh-stamp-esp32/src/uart.rs
Comment thread ssh-stamp-esp32/src/uart.rs Outdated
Comment thread ssh-stamp-esp32/src/network/wifi.rs Outdated
@brainstorm

brainstorm commented May 3, 2026

Copy link
Copy Markdown
Owner Author

Sorry folks for the huge changeset, but there's no good way to piecemeal this (I think)... @jubeormk1, if and when you have some time, could you do some of your comprehensive testing again against this PR? Let's make sure I didn't introduce some regression with some bad merge somewhere :-/

Thanks in advance!

PS: I accidentally clicked on Copilot PR review, wasn't meaning that, grr... although some of the suggestions are not bad, actually 🤔

Comment thread src/handle.rs
@brainstorm brainstorm merged commit d8116f4 into main May 21, 2026
8 checks passed
@brainstorm brainstorm changed the title Traits refactor Traits refactor to support more MCU targets (other than Espressif) May 21, 2026
@brainstorm brainstorm deleted the traits_refactor branch May 21, 2026 16:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants