Line data    Source code

       1             : /* ✔ */
       2             : 
       3             : #pragma once
       4             : 
       5             : #include <AH/Hardware/ExtendedInputOutput/ExtendedInputOutput.hpp>
       6             : #include <AH/Settings/SettingsWrapper.hpp>
       7             : 
       8             : BEGIN_AH_NAMESPACE
       9             : 
      10             : /**
      11             :  * @brief   A class for reading and debouncing buttons and switches.
      12             :  * 
      13             :  * @ingroup AH_HardwareUtils
      14             :  */
      15             : class Button {
      16             :   public:
      17             :     /**
      18             :      * @brief   Construct a new Button object.
      19             :      * 
      20             :      * **This constructor should not be used.**  
      21             :      * It is just a way to easily create arrays of buttons, and initializing
      22             :      * them later.
      23             :      */
      24             :     Button() : pin(NO_PIN) {}
      25             : 
      26             :     /**
      27             :      * @brief   Construct a new Button object.
      28             :      *
      29             :      * @param   pin
      30             :      *          The digital pin to read from. The internal pull-up resistor
      31             :      *          will be enabled when `begin` is called.
      32             :      */
      33             :     Button(pin_t pin);
      34             : 
      35             :     /// @brief   Initialize (enable the internal pull-up resistor).
      36             :     void begin();
      37             : 
      38             :     /**
      39             :      * @brief   Invert the input state of this button
      40             :      *          (button pressed is `HIGH` instead of `LOW`).
      41             :      */
      42             :     void invert();
      43             : 
      44             :     /// @brief   An enumeration of the different states a button can be in.
      45             :     enum State {
      46             :         Pressed = 0b00,  ///< Input went from low to low   (0,0)
      47             :         Released = 0b11, ///< Input went from high to high (1,1)
      48             :         Falling = 0b10,  ///< Input went from high to low  (1,0)
      49             :         Rising = 0b01    ///< Input went from low to high  (0,1)
      50             :     };
      51             : 
      52             :     /**
      53             :      * @brief   Read the button and return its new state.
      54             :      *
      55             :      * The button is debounced, the debounce time can be set in
      56             :      * Settings.hpp: #BUTTON_DEBOUNCE_TIME.
      57             :      *
      58             :      * ```
      59             :      * Debounce time: ├────┤
      60             :      *
      61             :      * Raw input:
      62             :      *    HIGH  ──────┐      ┌──────┐ ┌─┐      ┌─┐ ┌──────┐ ┌────────
      63             :      *    LOW         └──────┘      └─┘ └──────┘ └─┘      └─┘
      64             :      *                ├────┤ ├────┤ ├─┼─┼────┤ ├─┼─┼────┤ ├─┼────┤
      65             :      *
      66             :      * Debounced output:
      67             :      *    HIGH  ──────┐      ┌──────┐          ┌──────────┐      ┌───
      68             :      *    LOW         └──────┘      └──────────┘          └──────┘
      69             :      *
      70             :      * States:
      71             :      *    HIGH  ────────────────┐                  ┌─────────────────
      72             :      *    LOW                   └──────────────────┘
      73             :      *            Released   Falling   Pressed   Rising
      74             :      * ```
      75             :      *
      76             :      * @return  The state of the button, either Button::Pressed,
      77             :      *          Button::Released, Button::Falling or Button::Rising.
      78             :      */
      79             :     State update();
      80             : 
      81             :     /**
      82             :      * @brief   Get the state of the button, without updating it.
      83             :      *          Returns the same value as the last call to @ref update.
      84             :      *
      85             :      * @return  The state of the button, either Button::Pressed,
      86             :      *          Button::Released, Button::Falling or Button::Rising.
      87             :      */
      88             :     State getState() const;
      89             : 
      90             :     /// @brief   Return the name of the state as a string.
      91             :     static FlashString_t getName(State state);
      92             : 
      93             :     /// Return the time point (in milliseconds) when the button last bounced.
      94             :     unsigned long previousBounceTime() const;
      95             : 
      96             :     /// Return the time (in milliseconds) that the button has been stable for,
      97             :     /// compared to the given time point.
      98             :     unsigned long stableTime(unsigned long now) const;
      99             : 
     100             :     /// Return the time (in milliseconds) that the button has been stable for.
     101             :     unsigned long stableTime() const;
     102             : 
     103             :     /**
     104             :      * @brief   Set the debounce time for all Button%s.
     105             :      * 
     106             :      * @note    This function affects **all** Button objects.
     107             :      * 
     108             :      * @param   debounceTime
     109             :      *          The new debounce time in milliseconds.
     110             :      */
     111             :     static void
     112             :     setDebounceTime(unsigned long debounceTime = BUTTON_DEBOUNCE_TIME);
     113             : 
     114             :     /**
     115             :      * @brief   Get the debounce time.
     116             :      * @return  The debounce time in milliseconds.
     117             :      * @see     setDebounceTime
     118             :      */
     119             :     static unsigned long getDebounceTime();
     120             : 
     121             :   private:
     122             :     pin_t pin;
     123             : 
     124             :     struct InternalState {
     125          15 :         InternalState()
     126          15 :             : debounced(0b11), bouncing(true), prevInput(HIGH), invert(false),
     127          15 :               prevBounceTime(0) {}
     128             :         uint8_t debounced : 2;
     129             :         bool bouncing : 1;
     130             :         bool prevInput : 1;
     131             :         bool invert : 1;
     132             :         unsigned long prevBounceTime;
     133             :     } state;
     134             : 
     135             :     /// Edit this in Settings.hpp
     136             :     /// @see    BUTTON_DEBOUNCE_TIME
     137             :     static unsigned long debounceTime;
     138             : };
     139             : 
     140             : END_AH_NAMESPACE