KEYSCAN - Keypad Scanner Driver#

Keyscan driver.

Introduction#

A low-energy keypad scanner (KEYSCAN) which can scan up to a 6x8 matrix of keyboard switches. The KEYSCAN peripheral contains logic for debounce and settling time, allowing it to scan through the switch matrix autonomously in EM0 and EM1, and interrupt the processor when a key press is detected.

Configuration Options#

Some properties of the KEYSCAN driver are compile-time configurable. These properties are stored in a file named keyscan_driver_config.h. A template for this file, containing default values, is in the keyscan/config folder. Currently the configuration options are as follows:

• Number of columns in keyscan.

• Number of rows in keyscan.

• Duration of the scan period per column.

• Duration of debounce period once a key press is detected.

• Duration of the stable period after the debounce stage.

• Enable or disable single-press functionality.

To configure KEYSCAN, provide a custom configuration file. This is an example keyscan_driver_config.h file:

#ifndef KEYSCAN_DRIVER_CONFIG_H
#define KEYSCAN_DRIVER_CONFIG_H

// <o SL_KEYSCAN_DRIVER_COLUMN_NUMBER> Number of columns in keyscan <1-8>
// <i> Default: 1
#define SL_KEYSCAN_DRIVER_COLUMN_NUMBER 1

// <o SL_KEYSCAN_DRIVER_ROW_NUMBER> Number of rows in keyscan <3-6>
// <i> Default: 3
#define SL_KEYSCAN_DRIVER_ROW_NUMBER    3

// <o SL_KEYSCAN_DRIVER_SCAN_DELAY_MS> Scan Delay
//    <SL_KEYSCAN_DELAY_2MS=>     2ms
//    <SL_KEYSCAN_DELAY_4MS=>     4ms
//    <SL_KEYSCAN_DELAY_6MS=>     6ms
//    <SL_KEYSCAN_DELAY_8MS=>     8ms
//    <SL_KEYSCAN_DELAY_10MS=>    10ms
//    <SL_KEYSCAN_DELAY_12MS=>    12ms
//    <SL_KEYSCAN_DELAY_14MS=>    14ms
//    <SL_KEYSCAN_DELAY_16MS=>    16ms
//    <SL_KEYSCAN_DELAY_18MS=>    18ms
//    <SL_KEYSCAN_DELAY_20MS=>    20ms
//    <SL_KEYSCAN_DELAY_22MS=>    22ms
//    <SL_KEYSCAN_DELAY_24MS=>    24ms
//    <SL_KEYSCAN_DELAY_26MS=>    26ms
//    <SL_KEYSCAN_DELAY_28MS=>    28ms
//    <SL_KEYSCAN_DELAY_30MS=>    30ms
//    <SL_KEYSCAN_DELAY_32MS=>    32ms
// <i> Duration of the scan period per column
// <i> Default: SL_KEYSCAN_DELAY_2MS
#define SL_KEYSCAN_DRIVER_SCAN_DELAY_MS    SL_KEYSCAN_DELAY_2MS

// <o SL_KEYSCAN_DRIVER_DEBOUNCE_DELAY_MS> Debounce Delay
//    <SL_KEYSCAN_DELAY_2MS=>     2ms
//    <SL_KEYSCAN_DELAY_4MS=>     4ms
//    <SL_KEYSCAN_DELAY_6MS=>     6ms
//    <SL_KEYSCAN_DELAY_8MS=>     8ms
//    <SL_KEYSCAN_DELAY_10MS=>    10ms
//    <SL_KEYSCAN_DELAY_12MS=>    12ms
//    <SL_KEYSCAN_DELAY_14MS=>    14ms
//    <SL_KEYSCAN_DELAY_16MS=>    16ms
//    <SL_KEYSCAN_DELAY_18MS=>    18ms
//    <SL_KEYSCAN_DELAY_20MS=>    20ms
//    <SL_KEYSCAN_DELAY_22MS=>    22ms
//    <SL_KEYSCAN_DELAY_24MS=>    24ms
//    <SL_KEYSCAN_DELAY_26MS=>    26ms
//    <SL_KEYSCAN_DELAY_28MS=>    28ms
//    <SL_KEYSCAN_DELAY_30MS=>    30ms
//    <SL_KEYSCAN_DELAY_32MS=>    32ms
// <i> Duration of debounce period once a key press is detected.
// <i> Default: SL_KEYSCAN_DELAY_2MS
#define SL_KEYSCAN_DRIVER_DEBOUNCE_DELAY_MS    SL_KEYSCAN_DELAY_2MS

// <o SL_KEYSCAN_DRIVER_STABLE_DELAY_MS> Stable Delay
//    <SL_KEYSCAN_DELAY_2MS=>     2ms
//    <SL_KEYSCAN_DELAY_4MS=>     4ms
//    <SL_KEYSCAN_DELAY_6MS=>     6ms
//    <SL_KEYSCAN_DELAY_8MS=>     8ms
//    <SL_KEYSCAN_DELAY_10MS=>    10ms
//    <SL_KEYSCAN_DELAY_12MS=>    12ms
//    <SL_KEYSCAN_DELAY_14MS=>    14ms
//    <SL_KEYSCAN_DELAY_16MS=>    16ms
//    <SL_KEYSCAN_DELAY_18MS=>    18ms
//    <SL_KEYSCAN_DELAY_20MS=>    20ms
//    <SL_KEYSCAN_DELAY_22MS=>    22ms
//    <SL_KEYSCAN_DELAY_24MS=>    24ms
//    <SL_KEYSCAN_DELAY_26MS=>    26ms
//    <SL_KEYSCAN_DELAY_28MS=>    28ms
//    <SL_KEYSCAN_DELAY_30MS=>    30ms
//    <SL_KEYSCAN_DELAY_32MS=>    32ms
// <i> Duration of the stable period after the debounce stage.
// <i> Default: SL_KEYSCAN_DELAY_2MS
// #define SL_KEYSCAN_DRIVER_STABLE_DELAY_MS    SL_KEYSCAN_DELAY_2MS
//
// <q SL_KEYSCAN_DRIVER_SINGLEPRESS> keyscan single-press functionality
// <i> Enable or disable single-press functionality.
// <i> Default: 0
#define SL_KEYSCAN_DRIVER_SINGLEPRESS  0

#endif /* KEYSCAN_DRIVER_CONFIG_H */

Usage#

The expected flow of execution is:

• Initialize the driver.

• Register an event callback to be called on Keyscan event.

• Start the scan.

• Interrupt-based event to read the keypresses.

Initialization is done by calling sl_keyscan_driver_init(). It will prepare the internal structure and GPIO configuration.

When initialization is done successfully, scanning can be started by calling sl_keyscan_driver_start_scan().

Here is a complete example:

#include "keyscan_driver.h"

/*******************************************************************************
 *********************   LOCAL FUNCTION PROTOTYPES   ***************************
 ******************************************************************************/

static void on_event(uint8_t *p_keyscan_matrix, sl_keyscan_driver_status_t status);
static sl_keyscan_driver_process_keyscan_event_handle_t handle =
{
  .on_event = on_event,
};

/*******************************************************************************
 **************************   GLOBAL FUNCTIONS   *******************************
 ******************************************************************************/
static void on_event(uint8_t *p_keyscan_matrix, sl_keyscan_driver_status_t status)
{
  (void)p_keyscan_matrix;

  switch (status) {
    // Singlepress mode: key press detected.
    case SL_KEYSCAN_STATUS_KEYPRESS_VALID:
      break;
    // Multipress mode: all keys are released.
    case SL_KEYSCAN_STATUS_KEYPRESS_RELEASED:
      break;
    default:
      EFM_ASSERT(false);
      break;
  }
}

int main( void )
{
  // Initialize KEYSCAN.
  sl_keyscan_driver_init();
  // Set callback to be called when processing interrupt
  sl_keyscan_driver_subscribe_event(&handle);
  // Start the keypad scanner.
  sl_keyscan_driver_start_scan();

  return 0;
}

Modules#

sl_keyscan_driver_process_keyscan_event_handle_t