Merge pull request #555 from Dirbaio/migration-giude

Release v1.0.0

.github/workflows/test.yml

@@ -45,7 +45,7 @@ jobs:
       - uses: dtolnay/[email protected]
       - run: >
           cargo test
-          -p embedded-hal:1.0.0-rc.3
+          -p embedded-hal:1.0.0
           -p embedded-hal-bus
           -p embedded-hal-nb
           -p embedded-io

README.md

@@ -4,6 +4,9 @@
 
 This project is developed and maintained by the [HAL team](https://github.com/rust-embedded/wg#the-hal-team).
 
+> [!IMPORTANT]
+> 📣 `embedded-hal` v1.0 is now released! Check out the [announcement blog post](https://blog.rust-embedded.org/embedded-hal-v1/), the [API documentation](https://docs.rs/embedded-hal) and the [migration guide](docs/migrating-from-0.2-to-1.0.md).
+
 ## Scope
 
 `embedded-hal` serves as a foundation for building an ecosystem of platform-agnostic drivers.
@@ -38,24 +41,10 @@ The main  `embedded-hal` project is not tied to a specific execution model like
 | [embedded-io-async](./embedded-io-async)       | [![crates.io](https://img.shields.io/crates/v/embedded-io-async.svg)](https://crates.io/crates/embedded-io-async) | [![Documentation](https://docs.rs/embedded-io-async/badge.svg)](https://docs.rs/embedded-io-async) | I/O traits, async version  |
 | [embedded-io-adapters](./embedded-io-adapters)       | [![crates.io](https://img.shields.io/crates/v/embedded-io-adapters.svg)](https://crates.io/crates/embedded-io-adapters) | [![Documentation](https://docs.rs/embedded-io-adapters/badge.svg)](https://docs.rs/embedded-io-adapters) | Adapters between the [`embedded-io`](https://crates.io/crates/embedded-io) and [`embedded-io-async`](https://crates.io/crates/embedded-io-async) traits and other IO traits (`std`, `tokio`, `futures`...)  |
 
-## Releases
-
-At the moment we are working towards a `1.0.0` release (see [#177]). During this process we will
-release alpha versions like `1.0.0-alpha.1` and `1.0.0-alpha.2`.
-Alpha releases are **not guaranteed** to be compatible with each other.
-They are provided as early previews for community testing and preparation for the final release.
-If you use an alpha release, we recommend you choose an exact version specification in your
-`Cargo.toml` like: `embedded-hal = "=1.0.0-alpha.9"`
-
-See [this guide](docs/version-policy.md) for a way to implement both an `embedded-hal` `0.2.x`
-version and an `-alpha` version side by side in a HAL.
-
-[#177]: https://github.com/rust-embedded/embedded-hal/issues/177
-
 ## Documents
 
+- [Migrating from v0.2 to v1.0](docs/migrating-from-0.2-to-1.0.md).
 - [How-to: add a new trait](docs/how-to-add-a-new-trait.md)
-- [Version policy](docs/version-policy.md)
 - [MSRV](docs/msrv.md)
 
 ## Implementations and drivers

MIGRATING-0.2-1.0.md → docs/migrating-from-0.2-to-1.0.md

@@ -15,10 +15,13 @@
 - [Fallibility](#fallibility)
 - [SPI transfer return type](#spi-transfer-return-type)
 - [Error type bounds](#error-type-bounds)
+- [GPIO traits now require `&mut self`](#gpio-traits-now-require-mut-self)
 - [Prelude](#prelude)
 - [Removed blanket implementations](#removed-blanket-implementations)
 - [Cargo Features](#cargo-features)
 - [Companion crates](#companion-crates)
+- [Supporting both 0.2 and 1.0 in the same HAL](#supporting-both-02-and-10-in-the-same-hal)
+- [`embedded-hal-compat`](#embedded-hal-compat)
 
 ## Overview and reasoning
 
@@ -41,7 +44,7 @@ For `embedded-hal` 1.0, we decided to drop the first goal, targeting only the se
 - The second goal delivers much more value. Being able to use any driver together with any HAL crate, out of the box, and across the entire Rust Embedded ecosystem, is just plain awesome.
 
 This refocusing on drivers is the root cause of many of the changes between `embedded-hal` 0.2 and 1.0:
-- [Associated type compatibiilty](#removed-traits)
+- [Associated type compatibility](#removed-traits)
 - [Trait fragmentation](#trait-organization)
 - [Bus/device separation](#bus-device-separation)
 - [Fallibility](#fallibility)
@@ -91,7 +94,7 @@ These traits have been removed in the 1.0.0 release, with no replacement for now
 - [`watchdog::Watchdog`][watchdog]
 
 Please find a general [roadmap with further guidance here][roadmap-rm-traits] about
-whether and how to get these traits back in a future release
+whether and how to get these traits back in a future release.
 
 If you are a generic driver author and need one of them, we would like to hear from you. Please add your use case to the appropriate issue for the trait affected.
 
@@ -328,6 +331,95 @@ fn set_some_parameter(&mut self) -> Result<(), Self::Error> {
 }
 ```
 
+## GPIO traits now require `&mut self`
+
+Methods on `InputPin` and `State` now take `&mut self` instead of `&self`, to allow implementations to
+have mutable state or access exclusive resources. 
+
+**For HAL implementors**: You should not need to do any changes, since `&mut self` is strictly more permissive
+for implementations.
+
+For ease of use, you might want to provide inherent methods that take `&self` if the hardware permits it. In this case,
+you might need to do `&*self` to call them from the trait methods. Otherwise Rust will resolve the
+method call to the trait method, causing infinite recursion.
+
+```rust
+struct HalPin;
+
+impl HalPin {
+    fn is_high(&self) -> bool {
+        true
+    }
+
+    fn is_low(&self) -> bool {
+        true
+    }
+}
+
+impl InputPin for HalPin {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
+        // Needs `&*self` so that the inherent `is_high` is picked.
+        Ok((&*self).is_high())
+    }
+
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
+        Ok((&*self).is_low())
+    }
+}
+```
+
+**For driver authors**: If your driver does not need sharing input pins, you should be able to upgrade without any changes.
+If you do need to share input pins, the recommended solution is wrapping them with a `RefCell`.
+
+Note that if you need to share multiple objects, you should prefer using a single `RefCell` wherever possible to reduce RAM
+usage. Make an "inner" struct with all the objects that need sharing, and wrap it in a single `RefCell`. Below is an example
+skeleton of a keypad driver using row/column multiplexing, sharing multiple `InputPin`s and `OutputPin`s with a single `RefCell`:
+
+```rust
+use core::cell::RefCell;
+
+use embedded_hal::digital::{ErrorType, InputPin, OutputPin};
+
+pub struct Keypad<O: OutputPin, I: InputPin, const NCOLS: usize, const NROWS: usize> {
+    inner: RefCell<KeypadInner<O, I, NCOLS, NROWS>>,
+}
+
+struct KeypadInner<O: OutputPin, I: InputPin, const NCOLS: usize, const NROWS: usize> {
+    cols: [O; NCOLS],
+    rows: [I; NROWS],
+}
+
+pub struct KeypadInput<'a, O: OutputPin, I: InputPin, const NCOLS: usize, const NROWS: usize> {
+    inner: &'a RefCell<KeypadInner<O, I, NCOLS, NROWS>>,
+    row: usize,
+    col: usize,
+}
+
+impl<'a, O: OutputPin, I: InputPin, const NCOLS: usize, const NROWS: usize> ErrorType for KeypadInput<'a, O, I, NCOLS, NROWS> {
+    type Error = core::convert::Infallible;
+}
+
+impl<'a, O: OutputPin, I: InputPin, const NCOLS: usize, const NROWS: usize> InputPin for KeypadInput<'a, O, I, NCOLS, NROWS> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
+        Ok(!self.is_low()?)
+    }
+
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
+        let inner = &mut *self.inner.borrow_mut();
+        let row = &mut inner.rows[self.row];
+        let col = &mut inner.cols[self.col];
+
+        // using unwrap for demo purposes, you should propagate errors up instead.
+        col.set_low().unwrap();
+        let out = row.is_low().unwrap();
+        col.set_high().unwrap();
+
+        Ok(out)
+    }
+}
+```
+
+
 ## Prelude
 
 The prelude has been removed because it could make method calls ambiguous, since the method names are now
@@ -359,16 +451,76 @@ experiment externally, and merge when some kind of feasibility had been proven.
 
 ## Companion crates
 
-The `embedded-hal` project now spans several crates, where some functionality has been moved out from the main `embedded-hal` crate to separate crates as detailed above. Here is the full listing of crates:
+The `embedded-hal` project now spans several crates, where some functionality has been moved out from the main `embedded-hal` crate to separate crates as detailed above. 
+
+Different crates are released independently. The main `embedded-hal-*` trait crates have reached 1.0 maturity, others will become 1.0 as time passes.
+
+Here is the full listing of crates:
 
 | Crate | crates.io | Docs | |
 |-|-|-|-|
-| [embedded-hal](./embedded-hal)       | [![crates.io](https://img.shields.io/crates/v/embedded-hal.svg)](https://crates.io/crates/embedded-hal) | [![Documentation](https://docs.rs/embedded-hal/badge.svg)](https://docs.rs/embedded-hal) | Core traits, blocking version |
-| [embedded-hal-async](./embedded-hal-async) | [![crates.io](https://img.shields.io/crates/v/embedded-hal-async.svg)](https://crates.io/crates/embedded-hal-async) | [![Documentation](https://docs.rs/embedded-hal-async/badge.svg)](https://docs.rs/embedded-hal-async) | Core traits, async version |
-| [embedded-hal-nb](./embedded-hal-nb)    | [![crates.io](https://img.shields.io/crates/v/embedded-hal-nb.svg)](https://crates.io/crates/embedded-hal-nb) | [![Documentation](https://docs.rs/embedded-hal-nb/badge.svg)](https://docs.rs/embedded-hal-nb) | Core traits, polling version using the `nb` crate |
-| [embedded-hal-bus](./embedded-hal-bus)   | [![crates.io](https://img.shields.io/crates/v/embedded-hal-bus.svg)](https://crates.io/crates/embedded-hal-bus) | [![Documentation](https://docs.rs/embedded-hal-bus/badge.svg)](https://docs.rs/embedded-hal-bus) | Utilities for sharing SPI and I2C buses |
-| [embedded-can](./embedded-can)       | [![crates.io](https://img.shields.io/crates/v/embedded-can.svg)](https://crates.io/crates/embedded-can) | [![Documentation](https://docs.rs/embedded-can/badge.svg)](https://docs.rs/embedded-can) | Controller Area Network (CAN) traits |
-| [embedded-io](./embedded-io)       | [![crates.io](https://img.shields.io/crates/v/embedded-io.svg)](https://crates.io/crates/embedded-io) | [![Documentation](https://docs.rs/embedded-io/badge.svg)](https://docs.rs/embedded-io) | I/O traits (read, write, seek, etc.), blocking and nonblocking version. |
-| [embedded-io-async](./embedded-io-async)       | [![crates.io](https://img.shields.io/crates/v/embedded-io-async.svg)](https://crates.io/crates/embedded-io-async) | [![Documentation](https://docs.rs/embedded-io-async/badge.svg)](https://docs.rs/embedded-io-async) | I/O traits, async version  |
-| [embedded-io-adapters](./embedded-io-adapters)       | [![crates.io](https://img.shields.io/crates/v/embedded-io-adapters.svg)](https://crates.io/crates/embedded-io-adapters) | [![Documentation](https://docs.rs/embedded-io-adapters/badge.svg)](https://docs.rs/embedded-io-adapters) | Adapters between the [`embedded-io`](https://crates.io/crates/embedded-io) and [`embedded-io-async`](https://crates.io/crates/embedded-io-async) traits and other IO traits (`std`, `tokio`, `futures`...)  |
+| [embedded-hal](../embedded-hal)       | [![crates.io](https://img.shields.io/crates/v/embedded-hal.svg)](https://crates.io/crates/embedded-hal) | [![Documentation](https://docs.rs/embedded-hal/badge.svg)](https://docs.rs/embedded-hal) | Core traits, blocking version |
+| [embedded-hal-async](../embedded-hal-async) | [![crates.io](https://img.shields.io/crates/v/embedded-hal-async.svg)](https://crates.io/crates/embedded-hal-async) | [![Documentation](https://docs.rs/embedded-hal-async/badge.svg)](https://docs.rs/embedded-hal-async) | Core traits, async version |
+| [embedded-hal-nb](../embedded-hal-nb)    | [![crates.io](https://img.shields.io/crates/v/embedded-hal-nb.svg)](https://crates.io/crates/embedded-hal-nb) | [![Documentation](https://docs.rs/embedded-hal-nb/badge.svg)](https://docs.rs/embedded-hal-nb) | Core traits, polling version using the `nb` crate |
+| [embedded-hal-bus](../embedded-hal-bus)   | [![crates.io](https://img.shields.io/crates/v/embedded-hal-bus.svg)](https://crates.io/crates/embedded-hal-bus) | [![Documentation](https://docs.rs/embedded-hal-bus/badge.svg)](https://docs.rs/embedded-hal-bus) | Utilities for sharing SPI and I2C buses |
+| [embedded-can](../embedded-can)       | [![crates.io](https://img.shields.io/crates/v/embedded-can.svg)](https://crates.io/crates/embedded-can) | [![Documentation](https://docs.rs/embedded-can/badge.svg)](https://docs.rs/embedded-can) | Controller Area Network (CAN) traits |
+| [embedded-io](../embedded-io)       | [![crates.io](https://img.shields.io/crates/v/embedded-io.svg)](https://crates.io/crates/embedded-io) | [![Documentation](https://docs.rs/embedded-io/badge.svg)](https://docs.rs/embedded-io) | I/O traits (read, write, seek, etc.), blocking and nonblocking version. |
+| [embedded-io-async](../embedded-io-async)       | [![crates.io](https://img.shields.io/crates/v/embedded-io-async.svg)](https://crates.io/crates/embedded-io-async) | [![Documentation](https://docs.rs/embedded-io-async/badge.svg)](https://docs.rs/embedded-io-async) | I/O traits, async version  |
+| [embedded-io-adapters](../embedded-io-adapters)       | [![crates.io](https://img.shields.io/crates/v/embedded-io-adapters.svg)](https://crates.io/crates/embedded-io-adapters) | [![Documentation](https://docs.rs/embedded-io-adapters/badge.svg)](https://docs.rs/embedded-io-adapters) | Adapters between the [`embedded-io`](https://crates.io/crates/embedded-io) and [`embedded-io-async`](https://crates.io/crates/embedded-io-async) traits and other IO traits (`std`, `tokio`, `futures`...)  |
+
+## Supporting both 0.2 and 1.0 in the same HAL
+
+It is strongly recommended that HAL implementation crates provide implementations for both the `embedded-hal` v0.2 and v1.0 traits.
+This allows users to use drivers using either version seamlessly.
+
+The way you do it is adding a dependency on both versions in `Cargo.toml` like this:
+
+```toml
+[dependencies]
+embedded-hal-02 = { package = "embedded-hal", version = "0.2.7", features = ["unproven"] }
+embedded-hal-1 = { package = "embedded-hal", version = "1.0" }
+```
+
+This allows you to refer to the v0.2 traits under the `embedded_hal_02` name, and the v1.0 traits under
+`embedded_hal_1`. Implement both versions on the same struct. For example, for an input pin:
+
+```rust
+/// The HAL's input pin struct
+struct Input {...}
+
+/// Implement the v0.2 traits on the struct.
+impl embedded_hal_02::digital::v2::InputPin for Input {
+    type Error = Infallible;
+
+    fn is_high(&self) -> Result<bool, Self::Error> {
+        ...
+    }
+
+    fn is_low(&self) -> Result<bool, Self::Error> {
+        ...
+    }
+}
+
+/// ... and implement the v1.0 traits on the *same* struct.
+impl embedded_hal_1::digital::ErrorType for Input {
+    type Error = Infallible;
+}
+
+impl embedded_hal_1::digital::InputPin for Input {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
+        ...
+    }
+
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
+        ...
+    }
+}
+```
+
+## `embedded-hal-compat`
+
+For HAL implementation crates that haven't been updated yet, [embedded-hal-compat](https://github.com/ryankurte/embedded-hal-compat)
+provides shims to support interoperability between `embedded-hal` v0.2 and v1.0.
 
+This allows using a driver requiring v1.0 with a HAL crate implementing only v0.2 or vice-versa, (generally) without alteration.
+See the [docs](https://docs.rs/embedded-hal-compat/) for examples.

embedded-hal-async/CHANGELOG.md

@@ -7,7 +7,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-No unreleased changes
+No unreleased changes yet.
+
+## [v1.0.0] - 2023-12-28
+
+- Updated `embedded-hal` to version `1.0.0`.
 
 ## [v1.0.0-rc.3] - 2023-12-14
 
@@ -86,7 +90,8 @@ No unreleased changes
 First release to crates.io
 
 
-[Unreleased]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-async-v1.0.0-rc.3...HEAD
+[Unreleased]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-async-v1.0.0...HEAD
+[v1.0.0]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-async-v1.0.0-rc.3...embedded-hal-async-v1.0.0
 [v1.0.0-rc.3]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-async-v1.0.0-rc.2...embedded-hal-async-v1.0.0-rc.3
 [v1.0.0-rc.2]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-async-v1.0.0-rc.1...embedded-hal-async-v1.0.0-rc.2
 [v1.0.0-rc.1]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-async-v0.2.0-alpha.2...embedded-hal-async-v1.0.0-rc.1

embedded-hal-async/Cargo.toml

@@ -11,12 +11,12 @@ license = "MIT OR Apache-2.0"
 name = "embedded-hal-async"
 readme = "README.md"
 repository = "https://github.com/rust-embedded/embedded-hal"
-version = "1.0.0-rc.3"
+version = "1.0.0"
 rust-version = "1.75"
 
 [features]
 defmt-03 = ["dep:defmt-03", "embedded-hal/defmt-03"]
 
 [dependencies]
-embedded-hal = { version = "=1.0.0-rc.3", path = "../embedded-hal" }
+embedded-hal = { version = "1.0.0", path = "../embedded-hal" }
 defmt-03 = { package = "defmt", version = "0.3", optional = true }

embedded-hal-bus/CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 No unreleased changes
 
+## [v0.1.0] - 2023-12-28
+
+- Updated `embedded-hal` to version `1.0.0`.
+
 ## [v0.1.0-rc.3] - 2023-12-14
 
 - Updated `embedded-hal` to version `1.0.0-rc.3`.
@@ -52,7 +56,8 @@ No unreleased changes
 
 First release to crates.io
 
-[Unreleased]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-bus-v0.1.0-rc.3...HEAD
+[Unreleased]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-bus-v0.1.0...HEAD
+[v0.1.0]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-bus-v0.1.0-rc.3...embedded-hal-bus-v0.1.0
 [v0.1.0-rc.3]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-bus-v0.1.0-rc.2...embedded-hal-bus-v0.1.0-rc.3
 [v0.1.0-rc.2]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-bus-v0.1.0-rc.1...embedded-hal-bus-v0.1.0-rc.2
 [v0.1.0-rc.1]: https://github.com/rust-embedded/embedded-hal/compare/embedded-hal-bus-v0.1.0-alpha.3...embedded-hal-bus-v0.1.0-rc.1

embedded-hal-bus/Cargo.toml

@@ -12,16 +12,16 @@ license = "MIT OR Apache-2.0"
 name = "embedded-hal-bus"
 readme = "README.md"
 repository = "https://github.com/rust-embedded/embedded-hal"
-version = "0.1.0-rc.3"
+version = "0.1.0"
 
 [features]
 std = []
 async = ["dep:embedded-hal-async"]
 defmt-03 = ["dep:defmt-03", "embedded-hal/defmt-03", "embedded-hal-async?/defmt-03"]
 
 [dependencies]
-embedded-hal = { version = "=1.0.0-rc.3", path = "../embedded-hal" }
-embedded-hal-async = { version = "=1.0.0-rc.3", path = "../embedded-hal-async", optional = true }
+embedded-hal = { version = "1.0.0", path = "../embedded-hal" }
+embedded-hal-async = { version = "1.0.0", path = "../embedded-hal-async", optional = true }
 critical-section = { version = "1.0" }
 defmt-03 = { package = "defmt", version = "0.3", optional = true }