44//! It is suitable for mechanical and optical sensors.
55
66use {
7- crate :: gpio:: { Input , Pin , PullUp } ,
7+ crate :: gpio:: { Input , Pin } ,
88 crate :: pac:: QDEC ,
9+ core:: marker:: PhantomData ,
910} ;
1011
11- /// A safe wrapper around the `QDEC` peripheral with associated pins.
12- pub struct Qdec {
12+ /// A safe wrapper around the `QDEC` peripheral with
13+ /// associated pins. The `MODE` here reflects the pin mode
14+ /// of all of the pins when *not* in use by the `QDEC`: that
15+ /// is, at `new()`-time and `free()`-time.
16+ pub struct Qdec < MODE > {
1317 qdec : QDEC ,
18+ _i : PhantomData < MODE > ,
1419}
1520
16- impl Qdec {
17- /// Takes ownership of the `QDEC` peripheral and associated pins, returning a safe wrapper.
18- pub fn new ( qdec : QDEC , pins : Pins , sample_period : SamplePeriod ) -> Self {
21+ impl < MODE > Qdec < MODE > {
22+ /// Takes ownership of the `QDEC` peripheral and
23+ /// associated pins, returning a safe wrapper.
24+ /// All pins must be in the given input `MODE`.
25+ pub fn new ( qdec : QDEC , pins : Pins < MODE > , sample_period : SamplePeriod ) -> Self {
1926 qdec. psel . a . write ( |w| {
2027 unsafe { w. bits ( pins. a . psel_bits ( ) ) } ;
2128 w. connect ( ) . connected ( )
@@ -46,7 +53,10 @@ impl Qdec {
4653 SamplePeriod :: _131ms => qdec. sampleper . write ( |w| w. sampleper ( ) . _131ms ( ) ) ,
4754 }
4855
49- Self { qdec }
56+ Self {
57+ qdec,
58+ _i : PhantomData ,
59+ }
5060 }
5161
5262 /// Enables/disables input debounce filters.
@@ -131,9 +141,12 @@ impl Qdec {
131141 self . qdec . accread . read ( ) . bits ( ) as i16
132142 }
133143
134- /// Consumes `self` and returns back the raw `QDEC` peripheral.
144+ /// Consumes `self` and returns back the raw `QDEC`
145+ /// peripheral and its pins. The pins are returned in
146+ /// the input `MODE` they were in at the time of
147+ /// `QDec::new()`.
135148#[ inline]
136- pub fn free ( self ) -> ( QDEC , Pins ) {
149+ pub fn free ( self ) -> ( QDEC , Pins < MODE > ) {
137150 let a = unsafe { Pin :: from_psel_bits ( self . qdec . psel . a . read ( ) . bits ( ) ) } ;
138151 let b = unsafe { Pin :: from_psel_bits ( self . qdec . psel . b . read ( ) . bits ( ) ) } ;
139152 let led = {
@@ -152,13 +165,29 @@ impl Qdec {
152165 }
153166}
154167
155- /// Pins for the QDEC
156- pub struct Pins {
157- pub a : Pin < Input < PullUp > > ,
158- pub b : Pin < Input < PullUp > > ,
159- pub led : Option < Pin < Input < PullUp > > > ,
168+ /// Pins for the QDEC. The `led` pin must be given to the
169+ /// nRF configured as an input, but starting the QDEC will
170+ /// transform it into an output. The generic input `MODE`
171+ /// should be either `PullUp`, `PullDown` or `Floating`
172+ /// depending on circuit requirements.
173+ ///
174+ /// **Note:** The requirement that all pins be in the same
175+ /// input `MODE` at startup is not strictly enforced by the
176+ /// hardware, which cares only whether these pins are
177+ /// inputs. It is instead a convenience to avoid carrying
178+ /// around three type parameters, two of which would almost
179+ /// certainly be redundant (A and B modes) and one of which
180+ /// is often unnecessary (LED mode).
181+ pub struct Pins < MODE > {
182+ pub a : Pin < Input < MODE > > ,
183+ pub b : Pin < Input < MODE > > ,
184+ pub led : Option < Pin < Input < MODE > > > ,
160185}
161186
187+ /// Period with which to sample the encoder. Note that
188+ /// periods named in "`ms`" are approximations to exact
189+ /// periods in µs. When debounce is enabled, the inputs will
190+ /// be ignored unless they stay stable for this period.
162191#[ derive( Debug , Eq , PartialEq , Clone , Copy ) ]
163192pub enum SamplePeriod {
164193 _128us,
@@ -174,6 +203,8 @@ pub enum SamplePeriod {
174203 _131ms,
175204}
176205
206+ /// Number of samples before a decoder interrupt is
207+ /// triggered.
177208#[ derive( Debug , Eq , PartialEq , Clone , Copy ) ]
178209pub enum NumSamples {
179210 _10smpl,
@@ -187,6 +218,7 @@ pub enum NumSamples {
187218 _1smpl,
188219}
189220
221+ /// Accomodation for high-side LED setups.
190222#[ derive( Debug , Eq , PartialEq , Clone , Copy ) ]
191223pub enum LedPolarity {
192224 ActiveHigh ,
0 commit comments