CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.28.1] - 2025-01-02

Deprecated

Breaking

Added

Fixed

• Remove DynStorageImpl as nobody used it BECAUSE it did not have a public constructor ANYWAY
• Add serde defaults to the client configuration struct (#78)
• Derive Equality traits for OTA slots (#79)

[0.28.0] - 2024-06-23

Breaking

• Add configuration for Protected Management Frames and scan methods to wifi::ClientConfiguration
• Removed the no-std-net dependency in favor of core::net which is stable since Rust 1.77
• Due to the above, module ipv4 no longer re-exports ToSocketAddrs with feature = "std" enabled as this trait is not available in core::net (and might completely stop re-exporting core::net types in future)

[0.27.1] - 2024-02-21

• Fix clippy duplicate imports warnings with latest 1.78 nightly

[0.27.0] - 2024-01-26

• MAJOR CLEANUP/REMOVAL of obscure/rarely used trait modules:
  • sys_time
  • ping
  • timer (as there is embedded_hal::delay and more importantly - embedded_hal_async::delay)
  • event_bus
  • ws::callback_server
• COMPLETE REMOVAL of the following utility modules:
  • asyncify - all functionality which still made sense merged into esp-idf-svc
  • utils::mutex - this was a helper module for asyncify, so removed completely
• New module: channel; similar to crate channel-bridge but with less constraints on the data being sent/received
• Breaking change in modules mqtt::client and utils::mqtt::client: The Event structure, and its associated Message and MessageImpl traits simplified significantly, allowing for much more ergonomic event processing, thanks to GATs and async-fn-in-trait which are now stable:
  • Introduced a new single-method trait: Event with method payload returning EventPayload
  • Introduced a new enumeration - EventPayload - modeling all possible event types that can be received from the MQTT client
  • Message and MessageImpl retired
• Breaking change in module http::server: HandlerError and HandlerResult are now gone.
  • The blocking and async versions of the Handler and Middleware traits now all have an associated Error type that the user can define however she wants (only requirement is for it to implement Debug)
  • Additionally, the blocking and async versions of Middleware are now generified by the Handler type, so that they have access to the Handler's error type and are therefore free to implement their error type in terms of a composition between the handler error type and the error types of other functions they are calling
• Bumped the MSRV version to 1.75 and removed the nightly feature requirement from all async traits
• The serde dependency is now optional
• Update to heapless 0.8

[0.26.4] - 2023-11-12

• Updated changelog

[0.26.3] - 2023-11-12

• BREAKING CHANGE IN A PATCH RELEASE DUE TO DISCOVERED UB: Traits EventBus and TimerService no longer allow subscriptions with non-static callbacks, as these are impossible to implement safely on ESP IDF

[0.26.2] - 2023-11-05

• A temporary workaround for rust-lang/rust#117602

[0.26.1] - 2023-10-18

• Rolled back a change where event_bus::asynch::Sender and event_bus::asynch::Receiver did no longer implement ErrorType and returned a Result; since these traits are rarely used (feature nightly only), and 0.26.0 was just released, no new major version was released, but instead 0.26.0 was yanked

[0.26.0] - 2023-10-17

• MSRV raised to 1.71
• Breaking change: All traits converted to AFIT, except Unblocker, which needs to compile with stable Rust
• Breaking change: Upgraded to embedded-io 0.5 and embedded-io-async 0.5
• Upgraded strum and strum-macros to 0.25
• OTA: New method: Ota::finish that allows to postpone/avoid setting the updated partition as a boot one
• TimerService: TimerService::timer now takes &self instead of &mut self - for both blocking and async traits
• Breaking change: TimerService: scoped handler: the timer callback now only needs to live as long as the TimerService::Timer associated type. Therefore, TimerService::Timer is now lifetimed: TimerService::Timer<'a>
• Breaking change: TimerService: TimerService::Timer now borrows from TimerService. Therefore, that's another reason why TimerService::Timer is now lifetimed: TimerService::Timer<'a>
• Breaking change: EventBus: scoped handler: the subscription callback now only needs to live as long as the EventBus::Subscription associated type. Therefore, EventBus::Subscription is now lifetimed: EventBus::Subscription<'a>
• Breaking change: EventBus: EventBus::Subscription now borrows from EventBus. Therefore, that's another reason why EventBus::Subscription is now lifetimed: EventBus::Subscription<'a>
• Breaking change: ws::Acceptor: the blocking as well as the async version now return Connection / Sender / Receiver instances which borrow from Acceptor
• Breaking change: Unblocker: scoped handler: the callback now only needs to live as long as the Unblocker::UnblockFuture associated type. Therefore, Unblocker::UnblockFuture is now lifetimed: Unblocker::UnblockFuture<'a, ...>
• Breaking change: Unblocker: Unblocker::UnblockFuture now borrows from Unblocker::UnblockFuture. Therefore, that's another reason why Unblocker::UnblockFuture is now lifetimed: Unblocker::UnblockFuture<'a, ...>
• Breaking change: OTA: GAT Ota::Update now parametric over lifetime and no longer returned by &mut ref
• Breaking change: OTA: OtaUpdate::abort and OtaUpdate::complete now take self instead of &mut self
• Breaking change: MQTT: GAT Connection::Message now parametric over lifetime
• Breaking change: Ping: Callback function of Ping::ping_details can now be FnMut but does require Send
• Breaking change: All pub structs in utils::asyncify that implement the Future trait are now private and wrapped with async methods
• Breaking change: Removed structs Blocking and TrivialAsync, as well as all trait implementations on them, because their usefulness was questionable
• Breaking change: Removed the deprecated module httpd and the dependency on anyhow

[0.25.3] - 2023-07-05

• Compatibility with latest Rust nightly Clippy (fixes the "usage of Arc<T> where T is not Send or Sync" error)

[0.25.2] - 2023-07-05

• Yanked; first attempt at ^^^

[0.25.1] - 2023-06-18

• Compatibility with latest Rust nightly (fixes the can't leak private types error)

[0.25.0] - 2023-05-13

• MSRV 1.66 (but MSRV 1.70 necessary if embedded-io-async is enabled)
• Remove the experimental status from all traits
• Remove the nightly feature flag guard from all asyncify utilities as Rust GATs are stable now
• Async Wifi and Eth traits
• defmt support
• Mask the SSID password in Wifi ClientConfiguration
• Switch from futures to the atomic_waker crate in the asyncify utilities
• Minor breaking change: is_up renamed to is_connected in the Eth trait
• Upgrade to embedded-io 0.4 (but still stay away from switching the async traits to the async syntax)

[0.24.0] - 2022-12-13

HTTP server traits:

• Change the signatures of Handler, Middleware, asynch::Handler and asynch::Middleware so that middleware implementations can use the HTTP connection after the handler has finished execution
• Remove the handler utility method, as it was adding little value besides calling FnHandler::new()
• Remove the FnConnectionHandler Fn Handler implementation, as it was confusing to have it in addition to the FnHandler implementation

[0.23.2] - 2022-12-08

• Const functions for strum_enums
• Defmt support

[0.23.1] - 2022-11-21

Patch release to fix compilation errors under no_std.

[0.23] - 2022-11-01

Release 0.23 is a backwards-incompatible release where almost all traits were touched in one way or another.

Major Changes

The main themes of the 0.23 release are:

• Lose weight - the utils module was reduced to the bare minimum necessary. After all, the main goal of this crate is to provide traits, not utilities
• In addition to all traits being implementable in no_std environments, make sure they do not have explicit or implicit dependencies on an allocator being available (the Rust alloc module)
• Improve the experimental HTTP client and server traits
• Separate the notions of using a "nightly" compiler (which is a precondition for all async support) from "experimental" features, which might or might not be async-related

Changes by module

channel

This module is now moved to a separate micro-crate: channel-bridge. The traits in embedded-svc no longer depend on the generic Receiver and Sender traits the channel module used to provide.

errors

This module is completely retired, as it used to provide utilities (EitherErrorXX) which were anyway used only by a handful of the traits in embedded-svc. Those traits now use their own custom error types.

eth

TransitionalState struct is retired. The Eth trait is redesigned to have explicit start and stop methods, as well as is_started and is_up methods that to some extent provide the functionality which used to be available via the now-retired get_status method.

Furthermore, the Eth trait now no longer assumes that the driver implementing it is capable of operating above the OSI Layer-2. In other words, a driver implementing the Eth trait might, or might not bring up an IP-level stack. As such, all structures related to "IP" are retired or moved to the ipv4 module.

event_bus

• All trait methods on the blocking traits now take &self instead of &mut self. Given that EventBus and Postbox are essentially a publish-subscribe channel in disguise this makes a lot of sense
• Implement EventBus and Postbox for & T and &mut T
• PinnedEventBus is now retired, as its usefulness was queztionable (it was only lifting the Send requirement on the subscription callback)
• Async traits: remove the dependency on channel::Receiver and channel::Sender

executor

• All existing traits retired, as they cannot be implemented without an allocator being available (i.e. not implementable on top of the embassy-executor crate)
• New traits (and utility structs around them): Blocker and Unblocker. Note that Unblocker is currently not possible to implement without an allocation either, but it was kept for completeness.

http

This module underwent complete refactoring. Major changes:

• Connection trait: this is the major HTTP abstraction for both client code and server handlers. Amongst other reasons, introducing this trait solves the problem where the underlying TCP socket abstraction cannot be split into separate "reader" and "writer". Note that certain methods of the Connection trait can only be called when the connection is in a certain state (i.e. "client request submitted" phase vs "client request submitted" phase) and will panic otherwise. There are two safe, non-panicking wrappers of Connection for both HTTP client and server: Request and Response, where the recommendation for user code is to use the Connection trait via the Request wrapper (Request is automatically turned into Response once the request is submitted)
• On error, the server Handler trait is now required to return a dedicated HandlerError structure, which is just a wrapper around an error message. HandlerError is expected to be turned into an HTTP 500 response by trait implementors. The generified E: Debug error that used to be returned by the Handler trait introduced a very complex lifetime handling in user code and was therefore retired. Note that since HandlerError does not allocate, the maximum error message that it can contain is 64 characters. Longer messages are automatically truncated.
• The registry module is removed, as the Registry trait was impossible to implement without allocations. Instead, the new utils::http::registry utility is offered
• Query trait, allowing user to retrive the HTTP method and URI
• Implement traits on & T and &mut T where appropriate
• headers module with utility functions for building a headers' array for submission
• Blocking and TrivialUnblocking adaptors from async to blocking traits and vice versa
• Header utility in utils::http
• The session module is significantly simplified and moved to utils::http::session
• The cookies module is moved to utils::http::cookies

httpd

This module is now marked as deprecated. The successor is the http::server module.

io

• Blocking and async utility methods like read_max and copy moved to utils::io

ipv4

• Configuration struct describing the IP-related configuration of network interfaces, along with an accopmanying Interface trait

mqtt

• &mut T traits implementations

mutex

• Retired as it used GATs. While GATs are stable in the meantime, this trait still had open questions around it, as in the "guard" pattern it standardizes is not really embraced by the embedded community. Use the raw BlockingMutex trait provided by the embassy-sync crate along with its ergonomic typed wrapper, or - for STD-only environments - the STD Mutex directly.

ota

• OtaServer retired. This trait had nothing to do with the capabilities of the device itself in terms of OTA support, and modeled a generic "OTA server". While perhaps a useful concept, it might had been too early for that
• Slot trait turned into a structure, similar to Firmware. This enabled GAT-free blocking traits. While GATs are now getting stabilized, we still try to use those only for async traits, where they are absolute necessity
• Implement Ota for &mut T

ping

• Implement Ping for &mut T

storage

• StorageImpl - out of the box Storage implementation based on RawStorage impl and SerDe impl provided by the user

sys_time, timer

• & T and &mut T impls where appropriate

unblocker

• Removed, see the executor module for a suitable replacement

utils

Retired copies of async utilities available in other crates:

• signal, mutex, channel (were copied from the embassy-sync crate, which is now published on crates.io)
• yield_now, select (were copied from the embassy-futures crate, which is now published on crates.io)
• forever (were copied from the static_cell crate, which is now published on crates.io)

Utilities moved to other crates:

• executor - available as a separate edge-executor micro-crate now
• ghota - available as a separate ghota micro-crate now
• captive - available as part of the edge-net crate now
• role - available as part of the edge-frame crate now

Completely retired utilities:

• rest
• json_io

utils::mutex

This is a module that provides mutex and condvar abstractions, but with the caveat that these abstractions are supposed to only be used by:

• Other utilities in the utils module, namely the utils::asyncify module, and the helper utils::mqtt module (the latter can optionally be used by implementors of the synchronous mqtt traits)
• Implementors of the embedded-svc traits

It is not intended for general, public use. If users need a synchronous mutex or condvar abstractions for their application code, they are strongly encouraged to use one of the following options:

• For STD-compatible environments, the mutex and condvar abstractions provided by the Rust STD library itself
• For no_std environments, one of the following:
• The synchronous mutex abstractions provided by the embassy-sync crate
• The critical section provided by the critical-section crate
• Note that the no_std options above only provide a mutex abstration. If users need a condvar abstraction (usually only the case for RTOS environments which provde a thread/task notion), they should use the native condvar facilities of their RTOS

Furthermore:

• When the embedded-svc utilities are used in a STD-compatible environment, the mutex and condvar abstractions of utils::mutex are already implemented in terms of Rust's STD mutex and condvar abstractions, and users should not be concerned with this module at all
• When the embedded-svc utilities are used in a no_std environment (i.e., an RTOS that provides blocking synchronization primitives, as well as the notion of task/threads but these are not Rust STD compatible), users are required to provide implementations of the RawMutex and RawCondvar traits

wifi

TransitionalState struct is retired. The Wifi trait is redesigned to have explicit start, stop, connect and disconnect methods, as well as is_started and is_connected methods that to some extent provide the functionality which used to be available via the now-retired get_status method.

Furthermore, the Wifi trait now no longer assumes that the driver implementing it is capable of operating above the OSI Layer-2. In other words, a driver implementing the Wifi trait might, or might not bring up an IP-level stack. As such, all structures related to "IP" are retired or moved to the ipv4 module.