Merge #430

430: Add PWM SetDuty trait. r=therealprof a=Dirbaio

This adds back a version of the 0.2 trait `PwmPin`. 

cc #358

WG meeting [chatlog](https://matrix.to/#/!BHcierreUuwCMxVqOf:matrix.org/$_4DVnptWkGRjvW7-5Y6qCQZvj8oi9t4tbt8v4hXxJak?via=matrix.org&via=psion.agg.io&via=tchncs.de)

Differences to 0.2:

- `enable()` and `disable()` are gone. I think they were underspecified (for example, is the pin high or low when disabled?), and not very useful in practice. Disabling can be achieved already by setting duty to 0% or 100%. If the HAL cares about power consumption, it can transparently disable the timer and set the pin to fixed high/low when duty is 0% or 100%.
- Duty is no longer an unconstrained associated type. `u16` has been chosen because it gives enough dynamic range without being too big. `u8` might give too little dynamic range for some applications, `u32` might be annoyingly big for smaller archs like AVR/MSP430.
- Range is `0..u16::MAX` instead of `0..get_max_duty()`. This makes the HAL instead of the user responsible for the scaling, which makes using the trait easier. Also, if the HAL wants to optimize for performance, it can set the hardware period to be a power of 2, so scaling is just a bit shift.
- Name is `SetDuty` instead of `PwmPin`, because we might have a `SetFrequency` or similar in the future.
- I haven't included `get_duty()`, because I think in practice most drivers don't need it, and implementing it in HALs is annoying. They either have to read it back from hardware and unscaling it (losing precision), or storing the unscaled value in `self` (wasting RAM). We could add a `GetDuty` or `StatefulSetDuty` in the future if it turns out this is wanted, but I hope it won't be.

Co-authored-by: Dario Nieuwenhuis <[email protected]>
Co-authored-by: Grant Miller <[email protected]>

Author: 3 people

embedded-hal/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+### Added
+- Added `pwm::SetDutyCycle` trait.
+
 ### Changed
 - gpio: add `ErrorKind` enum for consistency with other traits and for future extensibility. No kinds are defined for now.
 - delay: make infallible.

embedded-hal/src/lib.rs

@@ -80,6 +80,7 @@
 pub mod delay;
 pub mod digital;
 pub mod i2c;
+pub mod pwm;
 pub mod serial;
 pub mod spi;
 

embedded-hal/src/pwm.rs

@@ -0,0 +1,128 @@
+//! Pulse Width Modulation (PWM) traits
+
+/// Error
+pub trait Error: core::fmt::Debug {
+    /// Convert error to a generic error kind
+    ///
+    /// By using this method, errors freely defined by HAL implementations
+    /// can be converted to a set of generic errors upon which generic
+    /// code can act.
+    fn kind(&self) -> ErrorKind;
+}
+
+impl Error for core::convert::Infallible {
+    fn kind(&self) -> ErrorKind {
+        match *self {}
+    }
+}
+
+/// Error kind
+///
+/// This represents a common set of operation errors. HAL implementations are
+/// free to define more specific or additional error types. However, by providing
+/// a mapping to these common errors, generic code can still react to them.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
+#[non_exhaustive]
+pub enum ErrorKind {
+    /// A different error occurred. The original error may contain more information.
+    Other,
+}
+
+impl Error for ErrorKind {
+    fn kind(&self) -> ErrorKind {
+        *self
+    }
+}
+
+impl core::fmt::Display for ErrorKind {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            Self::Other => write!(
+                f,
+                "A different error occurred. The original error may contain more information"
+            ),
+        }
+    }
+}
+
+/// Error type trait
+///
+/// This just defines the error type, to be used by the other traits.
+pub trait ErrorType {
+    /// Error type
+    type Error: Error;
+}
+
+impl<T: ErrorType> ErrorType for &mut T {
+    type Error = T::Error;
+}
+
+/// Single PWM channel / pin
+pub trait SetDutyCycle: ErrorType {
+    /// Get the maximum duty cycle value.
+    ///
+    /// This value corresponds to a 100% duty cycle.
+    fn get_max_duty_cycle(&self) -> u16;
+
+    /// Set the duty cycle to `duty / max_duty`.
+    ///
+    /// The caller is responsible for ensuring that the duty cycle value is less than or equal to the maximum duty cycle value,
+    /// as reported by `get_max_duty`.
+    fn set_duty_cycle(&mut self, duty: u16) -> Result<(), Self::Error>;
+
+    /// Set the duty cycle to 0%, or always inactive.
+    #[inline]
+    fn set_duty_cycle_fully_off(&mut self) -> Result<(), Self::Error> {
+        self.set_duty_cycle(0)
+    }
+
+    /// Set the duty cycle to 100%, or always active.
+    #[inline]
+    fn set_duty_cycle_fully_on(&mut self) -> Result<(), Self::Error> {
+        self.set_duty_cycle(self.get_max_duty_cycle())
+    }
+
+    /// Set the duty cycle to `num / denom`.
+    ///
+    /// The caller is responsible for ensuring that `num` is less than or equal to `denom`,
+    /// and that `denom` is not zero.
+    #[inline]
+    fn set_duty_cycle_fraction(&mut self, num: u16, denom: u16) -> Result<(), Self::Error> {
+        let duty = num as u32 * self.get_max_duty_cycle() as u32 / denom as u32;
+        self.set_duty_cycle(duty as u16)
+    }
+
+    /// Set the duty cycle to `percent / 100`
+    ///
+    /// The caller is responsible for ensuring that `percent` is less than or equal to 100.
+    #[inline]
+    fn set_duty_cycle_percent(&mut self, percent: u8) -> Result<(), Self::Error> {
+        self.set_duty_cycle_fraction(percent as u16, 100)
+    }
+}
+
+impl<T: SetDutyCycle> SetDutyCycle for &mut T {
+    fn get_max_duty_cycle(&self) -> u16 {
+        T::get_max_duty_cycle(self)
+    }
+
+    fn set_duty_cycle(&mut self, duty: u16) -> Result<(), Self::Error> {
+        T::set_duty_cycle(self, duty)
+    }
+
+    fn set_duty_cycle_fully_off(&mut self) -> Result<(), Self::Error> {
+        T::set_duty_cycle_fully_off(self)
+    }
+
+    fn set_duty_cycle_fully_on(&mut self) -> Result<(), Self::Error> {
+        T::set_duty_cycle_fully_on(self)
+    }
+
+    fn set_duty_cycle_fraction(&mut self, num: u16, denom: u16) -> Result<(), Self::Error> {
+        T::set_duty_cycle_fraction(self, num, denom)
+    }
+
+    fn set_duty_cycle_percent(&mut self, percent: u8) -> Result<(), Self::Error> {
+        T::set_duty_cycle_percent(self, percent)
+    }
+}