Update docs and changelog

Author: GrantM11235

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
 

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<Error = Infallible>) { /* ... */ }
+///
+/// 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<T>(pub T);
 

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<Error = Infallible>`) 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

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<Error = Infallible>`) 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, CS, D> {
     bus: BUS,
     cs: CS,

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<Error = Infallible>`) 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.

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<Error = Infallible>`) 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.