Keyscan

General Description

High level interface for interacting with the KeyScan.

The KeyScan driver monitors a key matrix for actions and provides keycodes to the application for processing.

Features

• Configurable number of rows and columns
• Detection of press, double press, triple press, and release actions
• Buffering of multiple key actions without application intervention
• Configurable callback for event-driven response to key actions

See the implementation-specific documentation for information about device-specific limits on row count, column count, and buffer depth.

Quick Start

Initialize a KeyScan instance using cyhal_keyscan_init, providing the pins that should be used for the rows and columns of the key matrix. Use cyhal_keyscan_read to read key actions.

See Snippet 1: KeyScan initialization for an example initialization.

Note

The clock parameter (const cyhal_clock_t *clk) is optional and can be set to NULL to automatically configure and use an available clock resource with a default frequency.

Code Snippets

Note

Error handling is omitted for clarity

Snippet 1: KeyScan initialization

This snippet initializes a KeyScan resource to scan a matrix of pins.

    const cyhal_gpio_t rows[]    = { P0_0, P0_1, P0_2 };
    const cyhal_gpio_t columns[] = { P1_0, P1_1, P1_2 };
    cyhal_keyscan_t    keyscan;
 
    cy_rslt_t result = cyhal_keyscan_init(&keyscan, sizeof(rows)/sizeof(rows[0]), rows,
                                          sizeof(columns)/sizeof(columns[0]), columns, NULL);

Snippet 2: Polling

This snippet illustrates periodic polling for key actions

    #define MAX_KEYS (20u)
    cyhal_keyscan_action_t key_actions[MAX_KEYS];
 
    cyhal_keyscan_t keyscan;
    // Initialize keyscan object as shown in snippet 1
 
    while (loop)
    {
        uint8_t num_keys = MAX_KEYS;
        result = cyhal_keyscan_read(&keyscan, &num_keys, key_actions);
        CY_ASSERT(CY_RSLT_SUCCESS == result);
        for (int i = 0; i < num_keys; ++i)
        {
            // process key_actions[i]
        }
 
        // Perform other application processing while waiting for further key actions
        cyhal_system_delay_ms(10u);
    }

Snippet 3: Event Handling

This snippet shows how to register a callback which is invoked when a key action occurs.

static void keyscan_event_handler(void* arg, cyhal_keyscan_event_t event)
{
    if (0u != (event & CYHAL_KEYSCAN_EVENT_BUFFER_FULL))
    {
        cyhal_keyscan_action_t key_actions[MAX_KEYS];
        uint8_t                num_keys = MAX_KEYS;
 
        // When we registered the callback, we set 'arg' to point to the keyscan object
        cyhal_keyscan_t* keyscan = (cyhal_keyscan_t*)arg;
        cyhal_keyscan_read(keyscan, &num_keys, key_actions);
        CY_ASSERT(num_keys > 0);
 
        for (int i = 0; i < num_keys; ++i)
        {
            // process key_actions[i]
        }
    }
}
 
 
//--------------------------------------------------------------------------------------------------
// snippet_cyhal_keyscan_event
//--------------------------------------------------------------------------------------------------
static void snippet_cyhal_keyscan_event()
{
    cyhal_keyscan_t keyscan;
    // Initialize keyscan object as shown in snippet 1
 
    // Register a callback and set the callback argument to be a pointer to the keyscan object, so
    // that we can easily reference it from the callback handler.
    cyhal_keyscan_register_callback(&keyscan, &keyscan_event_handler, &keyscan);
 
    // Subscribe to the action detected event so that we can respond to new key actions
    cyhal_keyscan_enable_event(&keyscan, CYHAL_KEYSCAN_EVENT_ACTION_DETECTED,
                               CYHAL_ISR_PRIORITY_DEFAULT, true);
}
 
 

Data Structures
struct	cyhal_keyscan_action_t
	Key action description. More...

Macros
#define	CYHAL_KEYSCAN_RSLT_ERR_INVALID_PIN    (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_KEYSCAN, 0))
	An invalid pin location was specified.
#define	CYHAL_KEYSCAN_RSLT_ERR_INVALID_ARG    (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_KEYSCAN, 1))
	An invalid argument was provided.
#define	CYHAL_KEYSCAN_RSLT_ERR_INIT_FAILED    (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_KEYSCAN, 2))
	Initialization of the KeyScan hardware failed.

Typedefs
typedef void(*	cyhal_keyscan_event_callback_t) (void *callback_arg, cyhal_keyscan_event_t event)
	Handler for KeyScan event callbacks.

Enumerations
enum	cyhal_keyscan_event_t {   CYHAL_KEYSCAN_EVENT_NONE = 0 ,   CYHAL_KEYSCAN_EVENT_ACTION_DETECTED = 1 << 0 ,   CYHAL_KEYSCAN_EVENT_BUFFER_FULL = 1 << 1 }
	KeyScan events. More...
enum	cyhal_keyscan_action_type_t {   CYHAL_KEYSCAN_ACTION_PRESS ,   CYHAL_KEYSCAN_ACTION_RELEASE }
	Key action types.

Functions
cy_rslt_t	cyhal_keyscan_init (cyhal_keyscan_t *obj, uint8_t num_rows, const cyhal_gpio_t *rows, uint8_t num_columns, const cyhal_gpio_t *columns, const cyhal_clock_t *clock)
	Initialize the KeyScan peripheral. More...
void	cyhal_keyscan_free (cyhal_keyscan_t *obj)
	Deinitialize the KeyScan object and release the associated hardware resources. More...
cy_rslt_t	cyhal_keyscan_read (cyhal_keyscan_t *obj, uint8_t *count, cyhal_keyscan_action_t *keys)
	Reads up to the specified number of key actions. More...
void	cyhal_keyscan_register_callback (cyhal_keyscan_t *obj, cyhal_keyscan_event_callback_t callback, void *callback_arg)
	Register a keyscan callback handler. More...
void	cyhal_keyscan_enable_event (cyhal_keyscan_t *obj, cyhal_keyscan_event_t event, uint8_t intr_priority, bool enable)
	Configure KeyScan events. More...
cy_rslt_t	cyhal_keyscan_init_cfg (cyhal_keyscan_t *obj, const cyhal_keyscan_configurator_t *cfg)
	Initialize the KeyScan peripheral using a configurator generated configuration struct. More...

---

Data Structure Documentation

cyhal_keyscan_action_t

struct cyhal_keyscan_action_t

Data Fields
uint8_t	keycode	Code indicating which key the action applies to. Keycodes are assigned sequentially in column order. For example, in a key matrix with five rows and two columns, column 0 would be represented by keycode 0 - 4, and column 1 by keycode 5-9.
cyhal_keyscan_action_type_t	action	The type of key action that was performd.

Enumeration Type Documentation

cyhal_keyscan_event_t

enum cyhal_keyscan_event_t

KeyScan events.

Enumerator
CYHAL_KEYSCAN_EVENT_NONE	No interrupt.
CYHAL_KEYSCAN_EVENT_ACTION_DETECTED	Key action detected.
CYHAL_KEYSCAN_EVENT_BUFFER_FULL	Keycode buffer is full.

Function Documentation

cyhal_keyscan_init()

cy_rslt_t cyhal_keyscan_init	(	cyhal_keyscan_t *	obj,
		uint8_t	num_rows,
		const cyhal_gpio_t *	rows,
		uint8_t	num_columns,
		const cyhal_gpio_t *	columns,
		const cyhal_clock_t *	clock
	)

Initialize the KeyScan peripheral.

Parameters

[out]	obj	Pointer to a KeyScan object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	num_rows	The number of rows in the key matrix
[in]	rows	Array of pins corresponding to the key matrix rows
[in]	num_columns	The number of columns in the key matrix
[in]	columns	Array of pins corresponding to the key matrix columns
[in]	clock	Clock source to use for this instance. If NULL, a dedicated clock will be automatically allocated for this instance.

Returns

The status of the init request

cyhal_keyscan_free()

void cyhal_keyscan_free

(

cyhal_keyscan_t *

obj

)

Deinitialize the KeyScan object and release the associated hardware resources.

Parameters

[in]

obj

The KeyScan object

cyhal_keyscan_read()

cy_rslt_t cyhal_keyscan_read	(	cyhal_keyscan_t *	obj,
		uint8_t *	count,
		cyhal_keyscan_action_t *	keys
	)

Reads up to the specified number of key actions.

Note

If an error code is returned, this function will contain partial information up to the number of keys read.

Parameters

[in]	obj	The KeyScan object
[in,out]	count	The number of key action to read. Updated with the number of keys actually read.
[out]	keys	The array into which key action descriptions should be written, starting from the least recent key action at index 0.

Returns

The status of the read request

cyhal_keyscan_register_callback()

void cyhal_keyscan_register_callback	(	cyhal_keyscan_t *	obj,
		cyhal_keyscan_event_callback_t	callback,
		void *	callback_arg
	)

Register a keyscan callback handler.

This function will be called when one of the events enabled by cyhal_keyscan_enable_event occurs.

Parameters

[in]	obj	The KeyScan object
[in]	callback	The callback handler which will be invoked when the event occurs
[in]	callback_arg	Generic argument that will be provided to the callback when called

cyhal_keyscan_enable_event()

void cyhal_keyscan_enable_event	(	cyhal_keyscan_t *	obj,
		cyhal_keyscan_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure KeyScan events.

When an enabled event occurs, the function specified by cyhal_keyscan_register_callback will be called.

Parameters

[in]	obj	The KeyScan object
[in]	event	The KeyScan event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on the specified event, False to turn off

cyhal_keyscan_init_cfg()

cy_rslt_t cyhal_keyscan_init_cfg	(	cyhal_keyscan_t *	obj,
		const cyhal_keyscan_configurator_t *	cfg
	)

Initialize the KeyScan peripheral using a configurator generated configuration struct.

Parameters

[in]	obj	Pointer to a KeyScan object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	cfg	Configuration structure generated by a configurator.

Returns

The status of the operation