Description

Full featured matrix (row/column) keyboard scanning module.

File(s):

This module implements or makes provision for:

Optimised matrix row/column key scanning
Debouncing of key press and release
n-key rollover
Detection and elimination of "phantom" keys
Key repetition (typematic)

See also

This module is based on "kbmatrix.h" and "kbmatrix.c" found in the Atmel AT91 Software package

License:

*  ----------------------------------------------------------------------------
*         ATMEL Microcontroller Software Support
*  ----------------------------------------------------------------------------
*  Copyright (c) 2008, Atmel Corporation
*  
*  All rights reserved.
*  
*  Redistribution and use in source and binary forms, with or without
*  modification, are permitted provided that the following conditions are met:
*  
*  - Redistributions of source code must retain the above copyright notice,
*  this list of conditions and the disclaimer below.
*  
*  Atmel's name may not be used to endorse or promote products derived from
*  this software without specific prior written permission.
*  
*  DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
*  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
*  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
*  DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
*  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
*  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
*  OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
*  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
*  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
*  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*  ----------------------------------------------------------------------------
*

Data Structures
struct	px_kbd_matrix_key_state_t
	Key state bit mask (1 = key pressed; 0 = key released) More...

struct	px_kbd_matrix_key_t
	Linked list item that describes which key has been pressed. More...

struct	px_kbd_matrix_t
	Keyboard matrix definition and state. More...

Macros
#define	PX_KBD_MATRIX_MAX_NR_KEYS 56
	Maximum number of keys that can be handled by the module. More...

#define	PX_KBD_MATRIX_NR_SAMPLES 4
	Number of samples that are necessary to debounce a keypress. More...

#define	PX_KBD_MATRIX_MAX_NR_KEYS_PRESSED 4
	Maximum number of keys that may be pressed simultaneously. More...

#define	KBD_DELAY_BEFORE_REPEATING_KEY 200
	Delay before a pressed key will be repeated. More...

#define	KBD_KEY_REPEAT_DELAY 20
	Delay between pressed key repeats. More...

Typedefs
typedef void(*	px_kbd_matrix_on_key_event_t) (uint8_t row, uint8_t col, px_kbd_matrix_event_t event)
	Function that will be called when a key event has taken place. More...

typedef void(*	px_kbd_matrix_set_row_t) (uint8_t row, bool active)
	Function that will be called to set a row output. More...

typedef bool(*	px_kbd_matrix_get_col_t) (uint8_t col)
	Function that will be called to read a column input. More...

typedef void(*	px_kbd_matrix_delay_t) (bool active)
	Function that will be called for row column scanning delay. More...

Enumerations
enum	px_kbd_matrix_event_t { PX_KBD_MATRIX_EVENT_RELEASED = 0 , PX_KBD_MATRIX_EVENT_PRESSED = 1 }
	Key event types. More...

Data Structure Documentation

◆ px_kbd_matrix_key_state_t

struct px_kbd_matrix_key_state_t

Key state bit mask (1 = key pressed; 0 = key released)

Definition at line 171 of file px_kbd_matrix.h.

◆ px_kbd_matrix_key_t

struct px_kbd_matrix_key_t

Linked list item that describes which key has been pressed.

Definition at line 177 of file px_kbd_matrix.h.

◆ px_kbd_matrix_t

struct px_kbd_matrix_t

Keyboard matrix definition and state.

Definition at line 185 of file px_kbd_matrix.h.

Data Fields
uint8_t	nr_of_rows	Number of rows in matrix.
uint8_t	nr_of_columns	Number of columns in matrix.
px_kbd_matrix_key_state_t	key_state	Bit mask that stores the current state of the keys.
px_kbd_matrix_key_state_t	key_history[PX_KBD_MATRIX_NR_SAMPLES]	Array of bit masks that stores the key state history.
uint8_t	key_history_index	Wrapping index (used as a ring buffer)
px_link_list_t	key_press_list	Linked list of pressed keys.
px_kbd_matrix_key_t	key_press_array[PX_KBD_MATRIX_MAX_NR_KEYS_PRESSED]	Storage for linked list to remember which keys are pressed.
uint16_t	key_repeat_counter	Counter to determine if a pressed key must repeated (typematic)
px_kbd_matrix_set_row_t	set_row	Function handler to write a row output.
px_kbd_matrix_get_col_t	get_col	Function handler to read a column input.
px_kbd_matrix_delay_t	delay	Function handler to read a column input.
px_kbd_matrix_on_key_event_t	on_key_event_handler	Function that will be called if a key is pressed or released.

Macro Definition Documentation

◆ PX_KBD_MATRIX_MAX_NR_KEYS

#define PX_KBD_MATRIX_MAX_NR_KEYS 56

Maximum number of keys that can be handled by the module.

Definition at line 95 of file px_kbd_matrix.h.

◆ PX_KBD_MATRIX_NR_SAMPLES

#define PX_KBD_MATRIX_NR_SAMPLES 4

Number of samples that are necessary to debounce a keypress.

Definition at line 103 of file px_kbd_matrix.h.

◆ PX_KBD_MATRIX_MAX_NR_KEYS_PRESSED

#define PX_KBD_MATRIX_MAX_NR_KEYS_PRESSED 4

Maximum number of keys that may be pressed simultaneously.

Definition at line 108 of file px_kbd_matrix.h.

◆ KBD_DELAY_BEFORE_REPEATING_KEY

#define KBD_DELAY_BEFORE_REPEATING_KEY 200

Delay before a pressed key will be repeated.

Definition at line 113 of file px_kbd_matrix.h.

◆ KBD_KEY_REPEAT_DELAY

#define KBD_KEY_REPEAT_DELAY 20

Delay between pressed key repeats.

Definition at line 118 of file px_kbd_matrix.h.

Typedef Documentation

◆ px_kbd_matrix_on_key_event_t

typedef void(* px_kbd_matrix_on_key_event_t) (uint8_t row, uint8_t col, px_kbd_matrix_event_t event)

Function that will be called when a key event has taken place.

Parameters

[in]	row	Row address of key event
[in]	col	Column address of key event
[in]	event	Key event type: PRESSED or RELEASED

Definition at line 137 of file px_kbd_matrix.h.

◆ px_kbd_matrix_set_row_t

typedef void(* px_kbd_matrix_set_row_t) (uint8_t row, bool active)

Function that will be called to set a row output.

Parameters

[in]	row	Specifies which row that should be set
[in]	active	Specifies that row should be activated (normally active low)

Definition at line 146 of file px_kbd_matrix.h.

◆ px_kbd_matrix_get_col_t

typedef bool(* px_kbd_matrix_get_col_t) (uint8_t col)

Function that will be called to read a column input.

Return values

true	Key is being pressed
false	Key is not pressed (released)

Definition at line 154 of file px_kbd_matrix.h.

◆ px_kbd_matrix_delay_t

typedef void(* px_kbd_matrix_delay_t) (bool active)

Function that will be called for row column scanning delay.

If a row is set to active, there is a certain delay before the columns should be sampled.

If a row is set to inactive, there is a certain delay before the columns return to their inactive state.

Parameters

[in] active Specifies that row should be activated (normally active low)

Definition at line 168 of file px_kbd_matrix.h.

Enumeration Type Documentation

◆ px_kbd_matrix_event_t

enum px_kbd_matrix_event_t

Key event types.

Enumerator
PX_KBD_MATRIX_EVENT_RELEASED	Key has been released.
PX_KBD_MATRIX_EVENT_PRESSED	Key has been pressed.

Definition at line 123 of file px_kbd_matrix.h.

Description

Data Structures

Macros

Typedefs

Enumerations

Data Structure Documentation

◆ px_kbd_matrix_key_state_t

◆ px_kbd_matrix_key_t

◆ px_kbd_matrix_t

Macro Definition Documentation

◆ PX_KBD_MATRIX_MAX_NR_KEYS

◆ PX_KBD_MATRIX_NR_SAMPLES

◆ PX_KBD_MATRIX_MAX_NR_KEYS_PRESSED

◆ KBD_DELAY_BEFORE_REPEATING_KEY

◆ KBD_KEY_REPEAT_DELAY

Typedef Documentation

◆ px_kbd_matrix_on_key_event_t

◆ px_kbd_matrix_set_row_t

◆ px_kbd_matrix_get_col_t

◆ px_kbd_matrix_delay_t

Enumeration Type Documentation

◆ px_kbd_matrix_event_t