From d2f4a9bf8df8de9f51b29659b464b4509af47dc6 Mon Sep 17 00:00:00 2001 From: Dario Nieuwenhuis Date: Tue, 19 Jul 2022 07:57:39 +0200 Subject: [PATCH] embassy-embedded-hal: docs --- embassy-embedded-hal/src/adapter.rs | 7 +++++-- embassy-embedded-hal/src/lib.rs | 17 +++++++++++++++++ .../src/shared_bus/asynch/i2c.rs | 8 ++++++++ .../src/shared_bus/asynch/spi.rs | 8 ++++++++ .../src/shared_bus/blocking/i2c.rs | 8 ++++++++ .../src/shared_bus/blocking/spi.rs | 8 ++++++++ embassy-embedded-hal/src/shared_bus/mod.rs | 5 +++++ 7 files changed, 59 insertions(+), 2 deletions(-) diff --git a/embassy-embedded-hal/src/adapter.rs b/embassy-embedded-hal/src/adapter.rs index 7d25d89fc..1c43f015f 100644 --- a/embassy-embedded-hal/src/adapter.rs +++ b/embassy-embedded-hal/src/adapter.rs @@ -1,9 +1,12 @@ +//! Adapters between embedded-hal traits. + use core::future::Future; use embedded_hal_02::{blocking, serial}; -/// BlockingAsync is a wrapper that implements async traits using blocking peripherals. This allows -/// driver writers to depend on the async traits while still supporting embedded-hal peripheral implementations. +/// Wrapper that implements async traits using blocking implementations. +/// +/// This allows driver writers to depend on the async traits while still supporting embedded-hal peripheral implementations. /// /// BlockingAsync will implement any async trait that maps to embedded-hal traits implemented for the wrapped driver. /// diff --git a/embassy-embedded-hal/src/lib.rs b/embassy-embedded-hal/src/lib.rs index d77c2d635..0c6f2786a 100644 --- a/embassy-embedded-hal/src/lib.rs +++ b/embassy-embedded-hal/src/lib.rs @@ -1,12 +1,29 @@ #![cfg_attr(not(feature = "std"), no_std)] #![cfg_attr(feature = "nightly", feature(generic_associated_types, type_alias_impl_trait))] +#![warn(missing_docs)] + +//! Utilities to use `embedded-hal` traits with Embassy. #[cfg(feature = "nightly")] pub mod adapter; pub mod shared_bus; +/// Set the configuration of a peripheral driver. +/// +/// This trait is intended to be implemented by peripheral drivers such as SPI +/// and I2C. It allows changing the configuration at runtime. +/// +/// The exact type of the "configuration" is defined by each individual driver, since different +/// drivers support different options. Therefore it is defined as an associated type. +/// +/// For example, it is used by [`SpiDeviceWithConfig`](crate::shared_bus::asynch::spi::SpiDeviceWithConfig) and +/// [`I2cDeviceWithConfig`](crate::shared_bus::asynch::i2c::I2cDeviceWithConfig) to allow different +/// devices on the same bus to use different communication settings. pub trait SetConfig { + /// The configuration type used by this driver. type Config; + + /// Set the configuration of the driver. fn set_config(&mut self, config: &Self::Config); } diff --git a/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs b/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs index 5bd3d9bc5..fa77a06d3 100644 --- a/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs +++ b/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs @@ -31,11 +31,13 @@ use embedded_hal_async::i2c; use crate::shared_bus::I2cDeviceError; use crate::SetConfig; +/// I2C device on a shared bus. pub struct I2cDevice<'a, M: RawMutex, BUS> { bus: &'a Mutex, } impl<'a, M: RawMutex, BUS> I2cDevice<'a, M, BUS> { + /// Create a new `I2cDevice`. pub fn new(bus: &'a Mutex) -> Self { Self { bus } } @@ -103,12 +105,18 @@ where } } +/// I2C device on a shared bus, with its own configuration. +/// +/// This is like [`I2cDevice`], with an additional bus configuration that's applied +/// to the bus before each use using [`SetConfig`]. This allows different +/// devices on the same bus to use different communication settings. pub struct I2cDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig> { bus: &'a Mutex, config: BUS::Config, } impl<'a, M: RawMutex, BUS: SetConfig> I2cDeviceWithConfig<'a, M, BUS> { + /// Create a new `I2cDeviceWithConfig`. pub fn new(bus: &'a Mutex, config: BUS::Config) -> Self { Self { bus, config } } diff --git a/embassy-embedded-hal/src/shared_bus/asynch/spi.rs b/embassy-embedded-hal/src/shared_bus/asynch/spi.rs index 343184d12..a08eaa82d 100644 --- a/embassy-embedded-hal/src/shared_bus/asynch/spi.rs +++ b/embassy-embedded-hal/src/shared_bus/asynch/spi.rs @@ -36,12 +36,14 @@ use embedded_hal_async::spi; use crate::shared_bus::SpiDeviceError; use crate::SetConfig; +/// SPI device on a shared bus. pub struct SpiDevice<'a, M: RawMutex, BUS, CS> { bus: &'a Mutex, cs: CS, } impl<'a, M: RawMutex, BUS, CS> SpiDevice<'a, M, BUS, CS> { + /// Create a new `SpiDevice`. pub fn new(bus: &'a Mutex, cs: CS) -> Self { Self { bus, cs } } @@ -93,6 +95,11 @@ where } } +/// SPI device on a shared bus, with its own configuration. +/// +/// This is like [`SpiDevice`], with an additional bus configuration that's applied +/// to the bus before each use using [`SetConfig`]. This allows different +/// devices on the same bus to use different communication settings. pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> { bus: &'a Mutex, cs: CS, @@ -100,6 +107,7 @@ pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> { } impl<'a, M: RawMutex, BUS: SetConfig, CS> SpiDeviceWithConfig<'a, M, BUS, CS> { + /// Create a new `SpiDeviceWithConfig`. pub fn new(bus: &'a Mutex, cs: CS, config: BUS::Config) -> Self { Self { bus, cs, config } } diff --git a/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs b/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs index 1ec480c0c..c8b5e30f6 100644 --- a/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs +++ b/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs @@ -26,11 +26,13 @@ use embedded_hal_1::i2c::ErrorType; use crate::shared_bus::I2cDeviceError; use crate::SetConfig; +/// I2C device on a shared bus. pub struct I2cDevice<'a, M: RawMutex, BUS> { bus: &'a Mutex>, } impl<'a, M: RawMutex, BUS> I2cDevice<'a, M, BUS> { + /// Create a new `I2cDevice`. pub fn new(bus: &'a Mutex>) -> Self { Self { bus } } @@ -143,12 +145,18 @@ where } } +/// I2C device on a shared bus, with its own configuration. +/// +/// This is like [`I2cDevice`], with an additional bus configuration that's applied +/// to the bus before each use using [`SetConfig`]. This allows different +/// devices on the same bus to use different communication settings. pub struct I2cDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig> { bus: &'a Mutex>, config: BUS::Config, } impl<'a, M: RawMutex, BUS: SetConfig> I2cDeviceWithConfig<'a, M, BUS> { + /// Create a new `I2cDeviceWithConfig`. pub fn new(bus: &'a Mutex>, config: BUS::Config) -> Self { Self { bus, config } } diff --git a/embassy-embedded-hal/src/shared_bus/blocking/spi.rs b/embassy-embedded-hal/src/shared_bus/blocking/spi.rs index ff92e1a7e..d0648f59a 100644 --- a/embassy-embedded-hal/src/shared_bus/blocking/spi.rs +++ b/embassy-embedded-hal/src/shared_bus/blocking/spi.rs @@ -29,12 +29,14 @@ use embedded_hal_1::spi::blocking::SpiBusFlush; use crate::shared_bus::SpiDeviceError; use crate::SetConfig; +/// SPI device on a shared bus. pub struct SpiDevice<'a, M: RawMutex, BUS, CS> { bus: &'a Mutex>, cs: CS, } impl<'a, M: RawMutex, BUS, CS> SpiDevice<'a, M, BUS, CS> { + /// Create a new `SpiDevice`. pub fn new(bus: &'a Mutex>, cs: CS) -> Self { Self { bus, cs } } @@ -117,6 +119,11 @@ where } } +/// SPI device on a shared bus, with its own configuration. +/// +/// This is like [`SpiDevice`], with an additional bus configuration that's applied +/// to the bus before each use using [`SetConfig`]. This allows different +/// devices on the same bus to use different communication settings. pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> { bus: &'a Mutex>, cs: CS, @@ -124,6 +131,7 @@ pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> { } impl<'a, M: RawMutex, BUS: SetConfig, CS> SpiDeviceWithConfig<'a, M, BUS, CS> { + /// Create a new `SpiDeviceWithConfig`. pub fn new(bus: &'a Mutex>, cs: CS, config: BUS::Config) -> Self { Self { bus, cs, config } } diff --git a/embassy-embedded-hal/src/shared_bus/mod.rs b/embassy-embedded-hal/src/shared_bus/mod.rs index 3cd380f72..76ee413d9 100644 --- a/embassy-embedded-hal/src/shared_bus/mod.rs +++ b/embassy-embedded-hal/src/shared_bus/mod.rs @@ -8,8 +8,10 @@ pub mod asynch; pub mod blocking; +/// Error returned by I2C device implementations in this crate. #[derive(Copy, Clone, Eq, PartialEq, Debug)] pub enum I2cDeviceError { + /// An operation on the inner I2C bus failed. I2c(BUS), } @@ -24,9 +26,12 @@ where } } +/// Error returned by SPI device implementations in this crate. #[derive(Copy, Clone, Eq, PartialEq, Debug)] pub enum SpiDeviceError { + /// An operation on the inner SPI bus failed. Spi(BUS), + /// Setting the value of the Chip Select (CS) pin failed. Cs(CS), }