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           12 :     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              :     /// @copydoc Button(pin_t)
      35           32 :     Button(ArduinoPin_t pin) : Button(pin_t(pin)) {}
      36              : 
      37              :     /// @brief   Initialize (enable the internal pull-up resistor).
      38              :     void begin();
      39              : 
      40              :     /**
      41              :      * @brief   Invert the input state of this button
      42              :      *          (button pressed is `HIGH` instead of `LOW`).
      43              :      */
      44              :     void invert();
      45              : 
      46              :     /// @brief   An enumeration of the different states a button can be in.
      47              :     enum State {
      48              :         Pressed = 0b00,  ///< Input went from low to low   (0,0)
      49              :         Released = 0b11, ///< Input went from high to high (1,1)
      50              :         Falling = 0b10,  ///< Input went from high to low  (1,0)
      51              :         Rising = 0b01    ///< Input went from low to high  (0,1)
      52              :     };
      53              : 
      54              :     /**
      55              :      * @brief   Read the button and return its new state.
      56              :      *
      57              :      * The button is debounced, the debounce time can be set in
      58              :      * Settings.hpp: #BUTTON_DEBOUNCE_TIME.
      59              :      *
      60              :      * ```
      61              :      * Debounce time: ├────┤
      62              :      *
      63              :      * Raw input:
      64              :      *    HIGH  ──────┐      ┌──────┐ ┌─┐      ┌─┐ ┌──────┐ ┌────────
      65              :      *    LOW         └──────┘      └─┘ └──────┘ └─┘      └─┘
      66              :      *                ├────┤ ├────┤ ├─┼─┼────┤ ├─┼─┼────┤ ├─┼────┤
      67              :      *
      68              :      * Debounced output:
      69              :      *    HIGH  ──────┐      ┌──────┐          ┌──────────┐      ┌───
      70              :      *    LOW         └──────┘      └──────────┘          └──────┘
      71              :      *
      72              :      * States:
      73              :      *    HIGH  ────────────────┐                  ┌─────────────────
      74              :      *    LOW                   └──────────────────┘
      75              :      *            Released   Falling   Pressed   Rising
      76              :      * ```
      77              :      *
      78              :      * @return  The state of the button, either Button::Pressed,
      79              :      *          Button::Released, Button::Falling or Button::Rising.
      80              :      */
      81              :     State update();
      82              : 
      83              :     /**
      84              :      * @brief   Get the state of the button, without updating it.
      85              :      *          Returns the same value as the last call to @ref update.
      86              :      *
      87              :      * @return  The state of the button, either Button::Pressed,
      88              :      *          Button::Released, Button::Falling or Button::Rising.
      89              :      */
      90              :     State getState() const;
      91              : 
      92              :     /// @brief   Return the name of the state as a string.
      93              :     static FlashString_t getName(State state);
      94              : 
      95              :     /// Return the time point (in milliseconds) when the button last bounced.
      96              :     unsigned long previousBounceTime() const;
      97              : 
      98              :     /// Return the time (in milliseconds) that the button has been stable for,
      99              :     /// compared to the given time point.
     100              :     unsigned long stableTime(unsigned long now) const;
     101              : 
     102              :     /// Return the time (in milliseconds) that the button has been stable for.
     103              :     unsigned long stableTime() const;
     104              : 
     105              :     /**
     106              :      * @brief   Set the debounce time for all Button%s.
     107              :      * 
     108              :      * @note    This function affects **all** Button objects.
     109              :      * 
     110              :      * @param   debounceTime
     111              :      *          The new debounce time in milliseconds.
     112              :      */
     113              :     static void
     114              :     setDebounceTime(unsigned long debounceTime = BUTTON_DEBOUNCE_TIME);
     115              : 
     116              :     /**
     117              :      * @brief   Get the debounce time.
     118              :      * @return  The debounce time in milliseconds.
     119              :      * @see     setDebounceTime
     120              :      */
     121              :     static unsigned long getDebounceTime();
     122              : 
     123              :   private:
     124              :     pin_t pin;
     125              : 
     126              :     struct InternalState {
     127          111 :         InternalState()
     128          111 :             : debounced(0b11), bouncing(true), prevInput(HIGH), invert(false),
     129          111 :               prevBounceTime(0) {}
     130              :         uint8_t debounced : 2;
     131              :         bool bouncing : 1;
     132              :         bool prevInput : 1;
     133              :         bool invert : 1;
     134              :         unsigned long prevBounceTime;
     135              :     } state;
     136              : 
     137              :     /// Edit this in Settings.hpp
     138              :     /// @see    BUTTON_DEBOUNCE_TIME
     139              :     static unsigned long debounceTime;
     140              : };
     141              : 
     142              : END_AH_NAMESPACE