Description

This module debounces a digital button input and reports button events.

File(s):

This module must be configured by supplying a project specific "px_btn_cfg.h". "px_btn_cfg_template.h" can be copied, renamed and modified to supply compile time options.

It is ideal for a noisy digital input such as a button. When a switch is pressed, the input will bounce between high and low until it finally settles to a valid state.

See also: https://en.wikipedia.org/wiki/Switch#Contact_bounce

This module is able to debounce a digital input by looking at successive values and deciding if it is a valid low or high state. It is also able to detect and remember a button pressed event (debounced rising edge) or button released event (debounced falling edge). Finally, if PX_BTN_CFG_LONG_COUNT is defined with a large non-zero value, a long press or long release is also detected.

Single, double or triple clicks can be detected and reported by setting PX_BTN_CFG_CLICKS_MAX to the maximum number of clicks. A click is defined as a button press exceeding PX_BTN_CFG_CLICK_PRESS_MIN followed by a button release. The maximum inter-click time is set with PX_BTN_CFG_CLICK_RELEASE_MAX.

Debouncing is implemented as follows: a counter is incremented each time the current digital input state is HI. If the counter reaches the high watermark threshold, the debounced state is considered HI. Conversely, the counter is decremented each time the current digital input state is LO. If the counter reaches the low watermark threshold, the debounced state is considered LO. The minimum counter value is 0 and the maximum value is PX_BTN_CFG_COUNT_MAX. This scheme provides sufficient hysteresis to debounce a noisy digital input.

[9] <-----MAX----------------1---------------------------
[8]                         1 1                         1
[7] <--HI threshold--------1---1-------------1---------1-
[6]                       0     1           0 1       0
[5]                      0       1         0   1     0
[4]                     0         1       0     1   0
[3]                    0           1     0       1 0
[2] <--LO threshold---0-------------0---0---------0------
[1]                  0               0 0
[0] <-----MIN-------0-----------------0------------------

If no hysteresis is required, then PX_BTN_CFG_THRESHOLD_LO can be set to 0 and PX_BTN_CFG_THRESHOLD_HI can be set to PX_BTN_CFG_COUNT_MAX.

Example:

#include "px_btn.h"
#include "px_gpio.h"
#include "px_sysclk.h"
#include "px_systmr.h"
#include "px_compiler.h"
 
// LED is on PORT B, pin 2, configured as an output, initially off
#define PX_GPIO_LED    PX_GPIO(B, 0, PX_GPIO_DIR_OUT, PX_GPIO_INIT_LO)
// Push Button is on PORT B, pin 0, configured as an input, pull-up enabled
#define PX_GPIO_PB     PX_GPIO(D, 7, PX_GPIO_DIR_IN, PX_GPIO_INIT_PULL_UP)
 
// Create a button object
px_btn_t px_btn;
 
int main(void)
{   
    // Initialise module
    px_sysclk_init();
    // Enable interrupts
    px_interrupts_enable();
    // Initialise GPIO pins
    PX_GPIO_INIT(PX_GPIO_LED);
    PX_GPIO_INIT(PX_GPIO_PB);
    // Initialise button state
    px_btn_init(&px_btn, PX_GPIO_IN_IS_LO(PX_GPIO_PB));
 
    // Loop forever
    while(true)
    {
        // Wait one systmr tick
        px_systmr_wait(1);
        // Update button state
        px_btn_update(&px_btn, PX_GPIO_IN_IS_LO(PX_GPIO_PB));
        // Has button been pressed?
        if(px_btn_event_press(&px_btn))
        {
            // Enable LED
            PX_GPIO_OUT_SET_HI(PX_GPIO_LED);
        }
        // Has button been released?
        if(px_btn_event_release(&px_btn))
        {
            // Disable LED
            PX_GPIO_OUT_SET_LO(PX_GPIO_LED);
        }
    }
}

Data Structures
struct	px_btn_t
	Structure to track state of button. More...

struct	px_btn_t.flag

Macros
#define	PX_BTN_CFG_COUNT_MAX 9
	Max HI counter value (counter starts at 0) More...

#define	PX_BTN_CFG_THRESHOLD_LO 2
	Low threshold for valid LO. More...

#define	PX_BTN_CFG_THRESHOLD_HI 7
	High threshold for valid HI. More...

#define	PX_BTN_CFG_LONG_COUNT 300
	Count threshold for long LO/ HI; Set to 0 to disable option. More...

#define	PX_BTN_CFG_CLICKS_MAX 2
	Maximum number of button clicks to detect; Minimum value is 1. More...

#define	PX_BTN_CFG_CLICK_PRESS_MIN 3
	A button press count longer than this value is considered a click. More...

#define	PX_BTN_CFG_CLICK_RELEASE_MAX 20
	A button release count shorter than this value is considered part of the same click sequence. More...

Functions
void	px_btn_init (px_btn_t *btn, bool btn_is_pressed)
	Initialise button state. More...

void	px_btn_update (px_btn_t *btn, bool btn_is_pressed)
	Update debounced button state and if event is detected set flag. More...

bool	px_btn_is_pressed (const px_btn_t *btn)
	Is button being pressed (debounced state). More...

bool	px_btn_is_released (const px_btn_t *btn)
	Is button released (debounced state). More...

bool	px_btn_event_press (px_btn_t *btn)
	Button press event detected? More...

bool	px_btn_event_release (px_btn_t *btn)
	Button release event detected? More...

bool	px_btn_event_long_press (px_btn_t *btn)
	Button long press event detected? More...

bool	px_btn_event_long_release (px_btn_t *btn)
	Button long release event detected? More...

uint8_t	px_btn_event_click (px_btn_t *btn)
	Button click (or clicks) event detected? More...

Data Structure Documentation

◆ px_btn_t

struct px_btn_t

Structure to track state of button.

Definition at line 121 of file px_btn.h.

Data Fields
struct px_btn_t.flag	flag
uint8_t	counter	LO/HI counter.
uint16_t	state_counter	debounced state counter
uint8_t	nr_of_clicks	Number of clicks detected.

◆ px_btn_t.flag

struct px_btn_t.flag

Definition at line 123 of file px_btn.h.

Data Fields
uint8_t	state: 1	Debounce state (0 = button is released; 1 = button is being pressed)
uint8_t	event_press: 1	Set when a rising edge is detected (HI threshold is reached)
uint8_t	event_release: 1	Set when a falling edge is detected (LO threshold is reached)
uint8_t	event_long_press: 1	Set when a long HI is detected (after rising edge)
uint8_t	event_long_release: 1	Set when a long LO is detected (after falling edge)
uint8_t	event_click: 1	Set when a button click (or clicks) have been detected.

Macro Definition Documentation

◆ PX_BTN_CFG_COUNT_MAX

#define PX_BTN_CFG_COUNT_MAX 9

Max HI counter value (counter starts at 0)

Definition at line 34 of file px_btn_cfg_template.h.

◆ PX_BTN_CFG_THRESHOLD_LO

#define PX_BTN_CFG_THRESHOLD_LO 2

Low threshold for valid LO.

Definition at line 37 of file px_btn_cfg_template.h.

◆ PX_BTN_CFG_THRESHOLD_HI

#define PX_BTN_CFG_THRESHOLD_HI 7

High threshold for valid HI.

Definition at line 40 of file px_btn_cfg_template.h.

◆ PX_BTN_CFG_LONG_COUNT

#define PX_BTN_CFG_LONG_COUNT 300

Count threshold for long LO/ HI; Set to 0 to disable option.

Definition at line 43 of file px_btn_cfg_template.h.

◆ PX_BTN_CFG_CLICKS_MAX

#define PX_BTN_CFG_CLICKS_MAX 2

Maximum number of button clicks to detect; Minimum value is 1.

Definition at line 46 of file px_btn_cfg_template.h.

◆ PX_BTN_CFG_CLICK_PRESS_MIN

#define PX_BTN_CFG_CLICK_PRESS_MIN 3

A button press count longer than this value is considered a click.

Definition at line 49 of file px_btn_cfg_template.h.

◆ PX_BTN_CFG_CLICK_RELEASE_MAX

#define PX_BTN_CFG_CLICK_RELEASE_MAX 20

A button release count shorter than this value is considered part of the same click sequence.

Definition at line 52 of file px_btn_cfg_template.h.

Function Documentation

◆ px_btn_init()

void px_btn_init	(	px_btn_t *	btn,
		bool	btn_is_pressed
	)

Initialise button state.

Parameters

btn	Pointer to a button object
btn_is_pressed	Button is being pressed (true) or released (false)

Definition at line 41 of file px_btn.c.

◆ px_btn_update()

void px_btn_update	(	px_btn_t *	btn,
		bool	btn_is_pressed
	)

Update debounced button state and if event is detected set flag.

Parameters

btn	Pointer to a button object
btn_is_pressed	Button is being pressed (true) or released (false)

Definition at line 62 of file px_btn.c.

◆ px_btn_is_pressed()

bool px_btn_is_pressed ( const px_btn_t * btn )

Is button being pressed (debounced state).

Parameters

btn	Pointer to a button object

Return values

true	Button is being pressed
false	Button is released

Definition at line 136 of file px_btn.c.

◆ px_btn_is_released()

bool px_btn_is_released ( const px_btn_t * btn )

Is button released (debounced state).

Parameters

btn	Pointer to a button object

Return values

true	Button is released
false	Button is being pressed

Definition at line 148 of file px_btn.c.

◆ px_btn_event_press()

bool px_btn_event_press ( px_btn_t * btn )

Button press event detected?

The event flag is also cleared after this function is called.

Parameters

btn	Pointer to a button object

Return values

true	Button has been pressed
false	Button has not been pressed

Definition at line 160 of file px_btn.c.

◆ px_btn_event_release()

bool px_btn_event_release ( px_btn_t * btn )

Button release event detected?

The event flag is also cleared after this function is called.

Parameters

btn	Pointer to a button object

Return values

true	Button has been released
false	Button has not been released

Definition at line 177 of file px_btn.c.

◆ px_btn_event_long_press()

bool px_btn_event_long_press ( px_btn_t * btn )

Button long press event detected?

The event flag is also cleared after this function is called.

Parameters

btn	Pointer to a button object

Return values

true	Button is being pressed for a long time
false	Button has not been pressed for a long time

Definition at line 194 of file px_btn.c.

◆ px_btn_event_long_release()

bool px_btn_event_long_release ( px_btn_t * btn )

Button long release event detected?

The event flag is also cleared after this function is called.

Parameters

btn	Pointer to a button object

Return values

true	Button has been released for a long time
false	Button has not been released for a long time

Definition at line 211 of file px_btn.c.

◆ px_btn_event_click()

uint8_t px_btn_event_click ( px_btn_t * btn )

Button click (or clicks) event detected?

Parameters

btn	Pointer to a button object

Returns: uint8_t Number of clicks detected. 0 = no clicks

Definition at line 228 of file px_btn.c.

Description

Data Structures

Macros

Functions

Data Structure Documentation

◆ px_btn_t

◆ px_btn_t.flag

Macro Definition Documentation

◆ PX_BTN_CFG_COUNT_MAX

◆ PX_BTN_CFG_THRESHOLD_LO

◆ PX_BTN_CFG_THRESHOLD_HI

◆ PX_BTN_CFG_LONG_COUNT

◆ PX_BTN_CFG_CLICKS_MAX

◆ PX_BTN_CFG_CLICK_PRESS_MIN

◆ PX_BTN_CFG_CLICK_RELEASE_MAX

Function Documentation

◆ px_btn_init()

◆ px_btn_update()

◆ px_btn_is_pressed()

◆ px_btn_is_released()

◆ px_btn_event_press()

◆ px_btn_event_release()

◆ px_btn_event_long_press()

◆ px_btn_event_long_release()

◆ px_btn_event_click()