embedded_hal/
pwm.rs

1//! Pulse Width Modulation (PWM) traits.
2
3#[cfg(feature = "defmt-03")]
4use crate::defmt;
5
6/// Error
7pub trait Error: core::fmt::Debug {
8    /// Convert error to a generic error kind.
9    ///
10    /// By using this method, errors freely defined by HAL implementations
11    /// can be converted to a set of generic errors upon which generic
12    /// code can act.
13    fn kind(&self) -> ErrorKind;
14}
15
16impl Error for core::convert::Infallible {
17    #[inline]
18    fn kind(&self) -> ErrorKind {
19        match *self {}
20    }
21}
22
23/// Error kind.
24///
25/// This represents a common set of operation errors. HAL implementations are
26/// free to define more specific or additional error types. However, by providing
27/// a mapping to these common errors, generic code can still react to them.
28#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
29#[cfg_attr(feature = "defmt-03", derive(defmt::Format))]
30#[non_exhaustive]
31pub enum ErrorKind {
32    /// A different error occurred. The original error may contain more information.
33    Other,
34}
35
36impl Error for ErrorKind {
37    #[inline]
38    fn kind(&self) -> ErrorKind {
39        *self
40    }
41}
42
43impl core::fmt::Display for ErrorKind {
44    #[inline]
45    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
46        match self {
47            Self::Other => write!(
48                f,
49                "A different error occurred. The original error may contain more information"
50            ),
51        }
52    }
53}
54
55/// Error type trait.
56///
57/// This just defines the error type, to be used by the other traits.
58pub trait ErrorType {
59    /// Error type
60    type Error: Error;
61}
62
63impl<T: ErrorType + ?Sized> ErrorType for &mut T {
64    type Error = T::Error;
65}
66
67/// Single PWM channel / pin.
68pub trait SetDutyCycle: ErrorType {
69    /// Get the maximum duty cycle value.
70    ///
71    /// This value corresponds to a 100% duty cycle.
72    fn max_duty_cycle(&self) -> u16;
73
74    /// Set the duty cycle to `duty / max_duty`.
75    ///
76    /// The caller is responsible for ensuring that the duty cycle value is less than or equal to the maximum duty cycle value,
77    /// as reported by [`max_duty_cycle`].
78    ///
79    /// [`max_duty_cycle`]: SetDutyCycle::max_duty_cycle
80    fn set_duty_cycle(&mut self, duty: u16) -> Result<(), Self::Error>;
81
82    /// Set the duty cycle to 0%, or always inactive.
83    #[inline]
84    fn set_duty_cycle_fully_off(&mut self) -> Result<(), Self::Error> {
85        self.set_duty_cycle(0)
86    }
87
88    /// Set the duty cycle to 100%, or always active.
89    #[inline]
90    fn set_duty_cycle_fully_on(&mut self) -> Result<(), Self::Error> {
91        self.set_duty_cycle(self.max_duty_cycle())
92    }
93
94    /// Set the duty cycle to `num / denom`.
95    ///
96    /// The caller is responsible for ensuring that `num` is less than or equal to `denom`,
97    /// and that `denom` is not zero.
98    #[inline]
99    fn set_duty_cycle_fraction(&mut self, num: u16, denom: u16) -> Result<(), Self::Error> {
100        debug_assert!(denom != 0);
101        debug_assert!(num <= denom);
102        let duty = u32::from(num) * u32::from(self.max_duty_cycle()) / u32::from(denom);
103
104        // This is safe because we know that `num <= denom`, so `duty <= self.max_duty_cycle()` (u16)
105        #[allow(clippy::cast_possible_truncation)]
106        {
107            self.set_duty_cycle(duty as u16)
108        }
109    }
110
111    /// Set the duty cycle to `percent / 100`
112    ///
113    /// The caller is responsible for ensuring that `percent` is less than or equal to 100.
114    #[inline]
115    fn set_duty_cycle_percent(&mut self, percent: u8) -> Result<(), Self::Error> {
116        self.set_duty_cycle_fraction(u16::from(percent), 100)
117    }
118}
119
120impl<T: SetDutyCycle + ?Sized> SetDutyCycle for &mut T {
121    #[inline]
122    fn max_duty_cycle(&self) -> u16 {
123        T::max_duty_cycle(self)
124    }
125
126    #[inline]
127    fn set_duty_cycle(&mut self, duty: u16) -> Result<(), Self::Error> {
128        T::set_duty_cycle(self, duty)
129    }
130
131    #[inline]
132    fn set_duty_cycle_fully_off(&mut self) -> Result<(), Self::Error> {
133        T::set_duty_cycle_fully_off(self)
134    }
135
136    #[inline]
137    fn set_duty_cycle_fully_on(&mut self) -> Result<(), Self::Error> {
138        T::set_duty_cycle_fully_on(self)
139    }
140
141    #[inline]
142    fn set_duty_cycle_fraction(&mut self, num: u16, denom: u16) -> Result<(), Self::Error> {
143        T::set_duty_cycle_fraction(self, num, denom)
144    }
145
146    #[inline]
147    fn set_duty_cycle_percent(&mut self, percent: u8) -> Result<(), Self::Error> {
148        T::set_duty_cycle_percent(self, percent)
149    }
150}
embedded_hal/pwm.rs

embedded_hal/
pwm.rs
