Saturday, January 16, 2021

Library for reading and debouncing multiple buttons using interrupt for AVR microcontrollers | ATmega328P

This library provides an easy way for reading and debouncing one or many buttons connected to a microcontroller. It can also read a button combination, button long press and button double press (like a double click). The response time is very fast without false triggers. Reading and debouncing takes only 50us every 10ms. It uses Binary Button Debouncing (BBD) method.

Button debouncing library for AVR microcontrollers

What is button debouncing anyway?

When a button is pressed or released it takes a certain amount of time before the two contacts reach a stable state. During that time the contacts are known to be bouncing sending multiple on off signals to the microcontroller before they settle to either on or off.

The bouncing time period depends on the speed the button is pressed, the force, the button quality and the age of the button. With time the contacts will oxidize especially with low quality buttons.

For one or two buttons the debouncing can be made in hardware by connecting a capacitor in parallel with the button that will keep the voltage across the button stable during press or release. But when having many buttons it is more practical to make the debouncing in software where it is also easier to modify the debouncing time compared to a capacitor.

Button debouncing in software using the Binary Button Debounce (BBM) method

Button debouncing using Binary Button Debounce (BBD)

Every time the debouncing function runs, the states of all buttons are saved in a binary representation in one or multiple bytes. In a byte can fit up to 8 buttons and each bit represents a button - 0 the button is not pressed, 1 the button is pressed. I call this a snapshot. Each snapshot is saved in an array and at the end every bit must be 1 for a particular button to be considered pressed.

Connecting push buttons to a microcontroller
Connecting push buttons to a microcontroller

Using the debouncing library

It is not necessary to modify the settings inside the library header file but there are a few settings that can be modified if the default values are not desired.

BUTTONS_SIZE_LIMIT - can be BTNS_LIMIT_8 that can hold up to 8 buttons or BTNS_LIMIT_16 for up to 16 buttons.

MIN_PRESS_TIME - debouncing time in milliseconds. 10 or 20 m. Default value is 10ms.

TIMER_ISR_RESOLUTION - by default is 1ms because the millis interrupt triggers every 1ms.

Setup function

debouncerSetup(BUTTONS_LOCATION, NR_OF_BUTTONS_AND_PORTS)

This function will set the pins for the buttons as input high. Since the buttons can be on multiple ports and their number can vary this is the simplest solution I found for the user to pass the location of the buttons to the library.

BUTTONS_LOCATION: an array that indicates on what ports and pin numbers the buttons are located.

NR_OF_BUTTONS_AND_PORTS: the size of the array.

Example:

#define NR_OF_BUTTONS_AND_PORTS      9

uint8_t BUTTONS_LOCATION[NR_OF_BUTTONS_AND_PORTS] = {'B', 2, 0, 5, 4, 'C', 5, 'D', 7};

Here we have some buttons on port B on pins 2, 0, 5 and 4, one button on port C pin 5 and one on port D pin 7. The array size is 3 ports + 6 buttons = 9.

To be able to identify what each button does and also if a combination of buttons was pressed an enum fits perfect for this purpose.

enum Buttons{
	BTN_UP 			= 1,	// PB2
	BTN_DOWN		= 2,	// PB0
	BTN_LEFT		= 4,	// PB5
	BTN_RIGHT		= 8,	// PB4
	BTN_MENU_OK		= 16,	// PC5
	BTN_START_STOP	        = 32	// PD7
}

The name of the buttons can be anything and more buttons can be added or removed from the list. The important thing is the order that they are inside the enum. Notice that the order of the enum is similar to that of the array. Also important is the number of each button in the enum - they must start at 1 and continue as follows 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 and so on.

Reasons for this can be seen later in an example but the cool thing is that any combination of buttons can be checked like so BTN_UP | BTN_DOWN. This will be true in an if statement or a switch case if both buttons are pressed.

Reading the buttons

There are two functions for reading the buttons. One returns the currently pressed buttons and the other the buttons that were pressed and released.

For example in many projects like a clock or a flashlight there is no room for many buttons and 1 or 2 buttons must accomplish many functions. Entering setup mode can be made as a secondary function by a long press of 2 seconds while a short press can accomplish a main action like switching the lights. Or some times a single button press must do something only once regardless if the user holds the button down and other times it is desired to repeat that button's function - when changing a numerical value for example.

debouncerPushedButtons()

Pushed buttons: returns an 8 or 16 bit value where each bit represents the state of the button at that bit position. Thanks to the Buttons enum there is no need for binary shifting to check which button was pressed. See the below examples on how easy is to check the button state.

Even if the user holds the button pressed continuously the function will return the on states only once. For example holding the key "a" will only return "a" whereas the following function will repeat the action.

debouncerPressedButtons()

Pressed buttons: same as the function above except that here the function returns the on states of the buttons as long as they are pressed. For example holding the key "a" will return "aaaaaaaaaaaaa" if the user doesn't implement a delay in code to account for this.

debouncerDoubleClicked()

Double clicked buttons: returns the button that was pressed twice very quickly. This is simillar to a mouse doubleclick.

debouncerButtonCombination()

Button combination: returns the button combination that was pressed during a certain time interval. Default: 200ms.

Debouncing functions

 buttonDebouncerTimer()

Must be placed in a timer interrupt (ideally 1ms resolution). After a certain time it will set the    NEXT_DEBOUNCE_READY flag that indicates that the debouncing function can run.

buttonDebouncer(monitorPressTime)

This is the debouncing function that is executed by the main loop when NEXT_DEBOUNCE_READY is 1. When debouncing is ready it will set the DEBOUNCE_FINISH flag then the main loop can read which buttons are pressed.

monitorPressTime: represents how many milliseconds a button must be pressed to be considered a long press. 0 means this option is not used. After this timeout the flag BUTTON_LONG_PRESS will be set and the main loop can check which button was long pressed.

Examples

Example 1:

#include "buttonDebouncer.h"
#include "millis.h"

#define NR_OF_BUTTONS_AND_PORTS  	9
uint8_t BUTTONS_LOCATION[NR_OF_BUTTONS_AND_PORTS] = {'B', 2, 0, 5, 4, 'C', 5, 'D', 7}; 

enum Buttons{
	BTN_UP 			= 1,	// PB2
	BTN_DOWN		= 2,	// PB0
	BTN_LEFT		= 4,	// PB5
	BTN_RIGHT		= 8,	// PB4
	BTN_MENU_OK		= 16,	// PC5
	BTN_START_STOP	        = 32	// PD7
}Buttons;
 
int main(void){
	buttons_t pressed_buttons = 0;
	buttons_t pushed_buttons = 0;
	buttons_t button_combination = 0;
 
	// Setup millis
	millis_init();
	
	// Setup button debouncer
	debouncerSetup(BUTTONS_LOCATION, NR_OF_BUTTONS_AND_PORTS);
	
	// Enable global interrupts
	sei();
	
	while(1){
		// Whait for the ISR timer to set the flag
		if(NEXT_DEBOUNCE_READY){
			NEXT_DEBOUNCE_READY = 0;
			
			// Read and debounce the buttons
			// Check if a button was long pressed for at least 2000 milliseconds
			buttonDebouncer(2000); // 50us @ 8MHz 
		}
		
		// Check if debouncing is complete
		if(DEBOUNCE_FINISH){
			DEBOUNCE_FINISH = 0;
			
			pressed_buttons = debouncerPressedButtons();
			pushed_buttons = debouncerPushedButtons();
			button_combination = debouncerButtonCombination();
			
			// If a button was long pressed 
			if(BUTTON_LONG_PRESS){
				// Check which button
				pushed_buttons = pressed_buttons;             
			}
			
			// Button combination
			switch(button_combination){
				case BTN_PLUS | BTN_ALARM:
					// Both buttons are pressed
					// Code...
				break;
			}
			
			// If at least 1 button is pushed
			if(pushed_buttons){
				// Check if a button was double clicked
				if(BUTTON_DOUBLE_CLICK && debouncerDoubleClicked() == BTN_SETUP){
					// BTN_SETUP was double clicked
					// Code...
				}
				
				// Check what button or combination of buttons were pressed
				switch(pushed_buttons){
					case BTN_UP:
						if(BUTTON_LONG_PRESS){
							// This button was long pressed
							// Code...
						}else{
							// This button was pushed but not long pressed
							// Code...
						}
					break;
					
					case BTN_DOWN:
						// Code...
					break;
					
					case BTN_LEFT:
						// Code...
					break;
					
					case BTN_RIGHT:
						// Code...
					break;
					
					case BTN_MENU_OK:
						// Code...
					break;
					
					case BTN_START_STOP:
						// Code...
					break;
				}
			}
		}
	}
}
 
 // Millis timer
ISR(ISR_VECT){
	++milliseconds;
	
	// Default: debouncing every 10ms, 1ms timer resolution
	buttonDebouncerTimer(); // 2.4us @ 8MHz
}

If you don't have a timer interrupt you can use the millis library from https://www.programming-electronics-diy.xyz/2021/01/millis-and-micros-library-for-avr.html

Download

v2.0

+ Multiple improvements

buttonDebouncer.h

No comments:

Post a Comment