diff --git a/embedded-hal-bus/CHANGELOG.md b/embedded-hal-bus/CHANGELOG.md index 04de7aa6..0e815ec0 100644 --- a/embedded-hal-bus/CHANGELOG.md +++ b/embedded-hal-bus/CHANGELOG.md @@ -7,7 +7,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ## [Unreleased] -No unreleased changes +- Require infallible chipselects for all spi utilities +- Add `UnwrappingAdapter` ## [v0.1.0] - 2023-12-28 diff --git a/embedded-hal-bus/src/lib.rs b/embedded-hal-bus/src/lib.rs index b6cf9386..5cde1ed3 100644 --- a/embedded-hal-bus/src/lib.rs +++ b/embedded-hal-bus/src/lib.rs @@ -23,7 +23,24 @@ pub mod spi; /// /// It currently supports [embedded_hal::digital::OutputPin], but other traits may be added in the future. /// -/// TODO: add usage example +/// # Example +/// +/// ``` +/// use core::convert::Infallible; +/// use embedded_hal::digital::OutputPin; +/// use embedded_hal_bus::UnwrappingAdapter; +/// +/// /// This could be any function or struct that requires an infallible output pin +/// fn requires_infallible(output: impl OutputPin) { /* ... */ } +/// +/// fn accepts_fallible(output: impl OutputPin) { +/// // this wouldn't work: +/// // requires_infallible(output); +/// +/// let unwrapping_output = UnwrappingAdapter(output); +/// requires_infallible(unwrapping_output); +/// } +/// ``` #[repr(transparent)] pub struct UnwrappingAdapter(pub T); diff --git a/embedded-hal-bus/src/spi/critical_section.rs b/embedded-hal-bus/src/spi/critical_section.rs index 2837d1da..32571cc1 100644 --- a/embedded-hal-bus/src/spi/critical_section.rs +++ b/embedded-hal-bus/src/spi/critical_section.rs @@ -12,6 +12,9 @@ use crate::spi::shared::transaction; /// This allows for sharing an [`SpiBus`], obtaining multiple [`SpiDevice`] instances, /// each with its own `CS` pin. /// +/// The `CS` pin must be infallible (`CS: OutputPin`) because proper error handling would be complicated +/// and it's usually not needed. If you are using a fallible `CS` pin, you can use [UnwrappingAdapter](crate::UnwrappingAdapter). +/// /// Sharing is implemented with a `critical-section` [`Mutex`]. A critical section is taken for /// the entire duration of a transaction. This allows sharing a single bus across multiple threads (interrupt priority levels). /// The downside is critical sections typically require globally disabling interrupts, so `CriticalSectionDevice` will likely diff --git a/embedded-hal-bus/src/spi/exclusive.rs b/embedded-hal-bus/src/spi/exclusive.rs index db23db60..4cdcb77c 100644 --- a/embedded-hal-bus/src/spi/exclusive.rs +++ b/embedded-hal-bus/src/spi/exclusive.rs @@ -17,6 +17,9 @@ use super::shared::transaction; /// /// This is the most straightforward way of obtaining an [`SpiDevice`] from an [`SpiBus`], /// ideal for when no sharing is required (only one SPI device is present on the bus). +/// +/// The `CS` pin must be infallible (`CS: OutputPin`) because proper error handling would be complicated +/// and it's usually not needed. If you are using a fallible `CS` pin, you can use [UnwrappingAdapter](crate::UnwrappingAdapter). pub struct ExclusiveDevice { bus: BUS, cs: CS, diff --git a/embedded-hal-bus/src/spi/mutex.rs b/embedded-hal-bus/src/spi/mutex.rs index 0ee2f664..08a60b27 100644 --- a/embedded-hal-bus/src/spi/mutex.rs +++ b/embedded-hal-bus/src/spi/mutex.rs @@ -12,6 +12,9 @@ use crate::spi::shared::transaction; /// This allows for sharing an [`SpiBus`], obtaining multiple [`SpiDevice`] instances, /// each with its own `CS` pin. /// +/// The `CS` pin must be infallible (`CS: OutputPin`) because proper error handling would be complicated +/// and it's usually not needed. If you are using a fallible `CS` pin, you can use [UnwrappingAdapter](crate::UnwrappingAdapter). +/// /// Sharing is implemented with a `std` [`Mutex`]. It allows a single bus across multiple threads, /// with finer-grained locking than [`CriticalSectionDevice`](super::CriticalSectionDevice). The downside is /// it is only available in `std` targets. diff --git a/embedded-hal-bus/src/spi/refcell.rs b/embedded-hal-bus/src/spi/refcell.rs index e360924e..62d99bef 100644 --- a/embedded-hal-bus/src/spi/refcell.rs +++ b/embedded-hal-bus/src/spi/refcell.rs @@ -11,6 +11,9 @@ use crate::spi::shared::transaction; /// This allows for sharing an [`SpiBus`], obtaining multiple [`SpiDevice`] instances, /// each with its own `CS` pin. /// +/// The `CS` pin must be infallible (`CS: OutputPin`) because proper error handling would be complicated +/// and it's usually not needed. If you are using a fallible `CS` pin, you can use [UnwrappingAdapter](crate::UnwrappingAdapter). +/// /// Sharing is implemented with a `RefCell`. This means it has low overhead, but `RefCellDevice` instances are not `Send`, /// so it only allows sharing within a single thread (interrupt priority level). If you need to share a bus across several /// threads, use [`CriticalSectionDevice`](super::CriticalSectionDevice) instead.