button.hpp

Go to the documentation of this file.

/**
 * @file button.hpp
 * @brief Button component — debounced digital input with edge detection
 * @ingroup components
 *
 * Button takes logical GPIO readings (true = pressed) and provides
 * debounced state, edge detection, and held-duration tracking.
 * No active_low logic needed — Gpio::read() already returns logical value.
 *
 * Usage:
 *   sbl::components::control::Button btn;
 *   btn.update(gpio_reading);       // Feed logical state each tick
 *   if (btn.just_pressed()) { ... } // Rising edge (auto-resets)
 *   if (btn.held_count() > 500) { ... } // Long press
 */
 
#ifndef SBL_COMPONENTS_CONTROL_BUTTON_HPP_
#define SBL_COMPONENTS_CONTROL_BUTTON_HPP_
 
#include <cstdint>
 
namespace sbl {
namespace components {
namespace control {
 
struct ButtonConfig {
    uint8_t debounce_count = 5;  ///< Consecutive identical readings to accept
};
 
/**
 * @brief Debounced button with edge detection and held-duration tracking
 *
 * @note All public methods are ISR-safe — pure state machine with no hardware I/O.
 */
class Button {
public:
    explicit Button(const ButtonConfig& config = {})
        : threshold_(config.debounce_count),
          counter_(0), stable_(false), raw_(false),
          pressed_edge_(false), released_edge_(false),
          held_ticks_(0) {}
 
    /**
     * @brief Feed a new logical GPIO reading
     *
     * Call once per update cycle. Debounce: the stable state only changes
     * when `debounce_count` consecutive identical readings are seen.
     *
     * @param logical_state true = pressed (Gpio::read already handles active_low)
     */
    void update(bool logical_state) {
        raw_ = logical_state;
 
        if (logical_state == stable_) {
            // Input matches stable — reset debounce counter
            counter_ = 0;
        } else {
            // Input differs from stable — count toward transition
            ++counter_;
            if (counter_ >= threshold_) {
                // Transition accepted
                bool was_pressed = stable_;
                stable_ = logical_state;
                counter_ = 0;
 
                if (stable_ && !was_pressed) {
                    pressed_edge_ = true;
                    held_ticks_ = 0;
                } else if (!stable_ && was_pressed) {
                    released_edge_ = true;
                }
            }
        }
 
        // Count held ticks while pressed
        if (stable_) {
            ++held_ticks_;
        }
    }
 
    /** @brief Current debounced state (true = pressed) */
    bool pressed() const { return stable_; }
 
    /** @brief Last raw (unfiltered) reading */
    bool raw() const { return raw_; }
 
    /**
     * @brief True if button was just pressed (rising edge)
     *
     * Resets on read — call once per update cycle.
     */
    bool just_pressed() {
        bool e = pressed_edge_;
        pressed_edge_ = false;
        return e;
    }
 
    /**
     * @brief True if button was just released (falling edge)
     *
     * Resets on read — call once per update cycle.
     */
    bool just_released() {
        bool e = released_edge_;
        released_edge_ = false;
        return e;
    }
 
    /**
     * @brief Ticks the button has been held down
     *
     * Returns raw tick count (caller knows update rate).
     * Resets to 0 on press, continues counting while held.
     */
    uint32_t held_count() const { return held_ticks_; }
 
    /** @brief Reset all state */
    void reset() {
        counter_ = 0;
        stable_ = false;
        raw_ = false;
        pressed_edge_ = false;
        released_edge_ = false;
        held_ticks_ = 0;
    }
 
private:
    uint8_t threshold_;
    uint8_t counter_;
    bool stable_;
    bool raw_;
    bool pressed_edge_;
    bool released_edge_;
    uint32_t held_ticks_;
};
 
} // namespace control
} // namespace components
} // namespace sbl
 
#endif // SBL_COMPONENTS_CONTROL_BUTTON_HPP_