Synergy Software Package User's Manual
Key Matrix Driver

Table of Contents

Key Matrix HAL Module Introduction

The Key Matrix HAL module provides a high-level API for key input applications and uses the key-interrupt function peripheral on the Synergy MCU. A user-defined callback can be created to inform the CPU of a key press event.

Key Matrix HAL Module Features

This Key Matrix HAL module configures and controls the Key Interrupt (KINT) peripheral. It implements the following key functions:

  • Supports both rising and falling edges on KINT channels
  • Supports interrupt-based event notification
  • Supports a bit-masking function to capture multiple events efficiently
  • Supports a matrix keypad with edges on any two channels
KINT_BD.png
Key Matrix HAL Module Block Diagram

KINT Hardware support details

The following hardware features are, or are not, supported by SSP for KINT.

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 

 

MCU Group Vary Input from KR00 to KR07
S124 ✓
S128 ✓
S1JA ✓
S3A1 ✓
S3A3 ✓
S3A6 ✓
S3A7 ✓
S5D3 ✓
S5D5 ✓
S5D9 ✓
S7G2 ✓

Key Matrix HAL Module APIs Overview

The Key Matrix HAL module defines APIs for opening, closing, enabling and disabling key-interrupt functions. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

Key Matrix HAL Module API Summary

Function Name Example API Call and Description
open g_keymatrix_on_kint.p_api->open(g_kint.p_ctrl, g_kint.p_cfg_cfg)
Initial configuration.
enable g_keymatrix_on_kint.p_api->enable(g_kint.p_ctrl)
Enable Key interrupt.
disable g_keymatrix_on_kint.p_api->disable(g_kint.p_ctrl)
Disable Key interrupt.
triggerSet g_keymatrix_on_kint.p_api->triggerSet()
Set trigger for Key interrupt.
close g_keymatrix_on_kint.p_api->close(&g_ keymatrix)
Allow driver to be reconfigured. May reduce power consumption.
versionGet g_keymatrix_on_kint.p_api->versionGet(&version)
Get version and store it in provided pointer version.
Note
For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name Description
SSP_SUCCESS Function successfully completed.
SSP_ERR_ASSERTION Parameter has invalid value.
SSP_ERR_INVALID_ARGUMENT Argument is invalid.
SSP_ERR_HW_LOCKED The API has already been opened. It must be closed before it can be opened again.
SSP_ERR_NOT_OPEN The peripheral is not opened.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

Key Matrix HAL Module Operational Overview

The Key Matrix HAL module configures the Key Interrupt (KINT) peripheral to detect rising or falling edges on any of the KINT channels. When such an event is detected on any of the configured pins, the module generates an interrupt; the interrupt then calls the user callback (p_callback) with the callback argument keymatrix_callback_args_t that specifies the channel(s) on which the edge was detected using a bitmask.

Even though detection of an edge on any one channel generates the interrupt, the callback returns a bitmask keymatrix_channels_t of all the pins that were triggered at that time (if any other pins also detected an edge). Thus, an interrupt is not necessarily generated for edge detection on each pin if an edge was also detected on another pin before the callback was called. If a new edge is detected after the callback was called, then the interrupt is triggered again, resulting in a new callback. The bit mask in the user callback should be checked to identify the interrupt source channels.

This module can be used to implement a matrix keypad with edges on any two channels indicating the actual key that was pressed; alternatively, the module can be used as a single input to detect an edge on an input pin.

Key Matrix HAL Module Important Operational Notes and Limitations

Key Matrix HAL Module Operational Notes

  • To trigger a transfer of data using the DMAC or DTC peripheral when a trigger edge is detected, configure the DMAC/DTC transfer with activation_source set to ELC_EVENT_KEY_INT.
  • The KINT module can trigger the start of other peripherals available to the ELC. For details, see the ELC User's Guide in the SSP User's Manual.
  • You must enable the KINT (INTKR) interrupt in the BSP for this module to operate, regardless of whether a callback is used in the keymatrix_api_t::open call.

Key Matrix HAL Module Limitations

  • This module does not support polling-mode operation.
  • Refer to the latest SSP Release Notes for any additional operational limitations for this module.

Including the Key Matrix HAL Module in an Application

This section describes how to include the Key Matrix HAL Module in an application using the SSP configurator.

Note
This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the Key Matrix Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the Key Matrix Driver is g_kint0. This name can be changed in the associated Properties window.)

Key Matrix HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_kint0 Key Matrix Driver on r_kint Threads New Stack> Driver> Input> Key Matrix Driver on r_kint

When the Key Matrix Driver on r_kint is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

KINT_MS.png
Key Matrix HAL Module Stack

Configuring the Key Matrix HAL Module

The Key Matrix HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

One of the properties most often identified as requiring a change is the interrupt priority; this configuration setting is available with the Properties window of the associated module. Simply select the indicated module and then view the properties window; the interrupt settings are often toward the bottom of the properties list, so scroll down until they become available.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the Key Matrix HAL Module on r_kint

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Enable or disable the parameter error checking.
Name g_kint0 Module name.
Channel 0-7 Unused, Used
Default: Unused 		This is a bit-mask with each bit specifying if that channel is to be enabled or not.  Select the channels to be used.
Trigger Type Rising Edge, Falling Edge
Default: Rising Edge 		Specify if the enabled channels detect a rising edge or a falling edge. 

Note: Either all channels detecting a rising edge or all channels detecting a falling edge.
Interrupt enabled after initialization True, False
Default: False 		Specify if the module interrupts must be enabled as part of the open call.
Callback NULL A user callback function can be registered in keymatrix_api_t::open. If this callback function is provided, it will be called from the interrupt service routine (ISR) each time a configured edge is detected on any of the channels.

Note: Without callback, the application cannot determine whether an event has occurred.

Warning: Since the callback is called from an ISR, do not use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system.
Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)
Default: Priority 12 		Interrupt priority selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Key Matrix HAL Module Clock Configuration

The Key Matrix HAL module does not require a specific clock configuration.

Key Matrix HAL Module Pin Configuration

The KINT peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device.  The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the KINT pins:

Pin Selection for the Key Matrix HAL Module on r_kint

Resource ISDE Tab Pin selection Sequence
KINT Pins Select Peripherals> Input:KINT> KINT0.
Note
The selection sequence assumes KINT0 is the desired hardware target for the driver.

Pin Configuration Settings for the Key Matrix HAL Module on r_kint

Property Value Description
Operation Mode Disabled, Custom
Default: Disabled 		Select Custom as the Operation Mode.
KRM0:7 None, Pnn
Default: None 		Key Interrupt Pin selection.
Note
The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and Synergy Kits may have different available pin configuration settings.

Using the Key Matrix HAL Module in an Application

The typical steps in using the Key Matrix HAL module in an application are:

  1. Initialize the Key Matrix HAL module using the keymatrix_api_t::open API.
  2. If the autostart configuration setting is true, the module starts operation immediately.
    1. If the autostart is not set, use keymatrix_api_t::enable API to enable operation.
  3. Respond to key inputs.
  4. Disable operation using the keymatrix_api_t::disable API.
  5. To modify trigger edge after initialization, use the keymatrix_api_t::triggerSet API.
  6. Close the module by using the keymatrix_api_t::close API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

KINT_TA.png
Flow Diagram of a Typical Key Matrix HAL Module Application