Renesas Key Matrix HAL Application Note
Application Note
Renesas Synergy™ Platform
Key Matrix HAL Module Guide
Introduction
This module guide will enable you to eff ectively use a module in your own design. Upon compl etion of this
guide, you will be able to add this module to your own design, configure it correctly for the target applic ation
and write code, using the included application project code as a r eference and efficient starting point .
References to more detailed API descri ptions and suggestions of other applicatio n projects that illustrate
more adv anced uses of the module are available in the Renesas Synergy Knowl edge Base (as described in
the References section at the end of this document), and should be v aluable resources for creating more
complex designs.
The Key Matrix HAL modul e is a high-level API for Key Matrix HAL applicatio ns and is implemented on
r_kint. The Key Matrix HAL module uses the key-interrupt function peripheral on the Sy nergy MCU. A userdefined callback can be created to inform the CPU of a key press event.
Contents
1. Key Matrix HAL Module Features ..........................................................................................2
2. Key Matrix HAL Module APIs Overview .................................................................................2
3. HAL Module Oper ational Over view ........................................................................................3
3.1 Key Matrix HAL Module Important Operational Notes and Li m itations ............................................ 3
3.1.1 Key Matrix HAL Module Operational Notes .............................................................................. 3
3.1.2 Key Matrix HAL Module Limitations ........................................................................................ 3
4. Including the Key Matrix HAL Module in an Application ..........................................................3
5. Configuring the Key Matrix HAL Module ................................................................................4
5.1 Key Matrix HAL Module Clock Configurati on .............................................................................. 5
5.2 Key Matrix HAL Module Pin Configurati on ................................................................................. 5
6. Using the Key Matrix HAL Module in an Application ...............................................................5
7. The Key Matrix HAL Module Application Project ....................................................................6
8. Customizing the Key Matr ix HAL Module for a Target Application.........................................10
9. Running the Key Matrix HAL Module Application Project ......................................................10
10. Key Matrix HAL Module Conclusion .....................................................................................10
11. Key Matrix HAL Module Next Steps .....................................................................................10
12. Key Matrix HAL Module Reference Information ....................................................................10
R11AN0123EU0102 Rev.1.02 Page 1 of 12
Feb.27.19
Renesas Synergy™ Platform Key Matrix HAL Module Guide
Function N ame
Example A PI Call and Des criptio n
.open
g_keymatrix_on_kint.p_api->open(g_kint.p_ctrl,
.enable
g_keymatrix_on_kint.p_api->enable(g_kint.p_ctrl)
.disable
g_keymatrix_on_kint.p_api->disable(g_kint.p_ctrl)
Disable Key interrupt.
.triggerSet
g_keymatrix_on_kint.p_api->triggerSet(g_kint.p_ctrl,
Set trigger for Key interrupt.
.close
g_keymatrix_on_kint.p_api->close(g_kint.p_ctrl)
Allow driv er to be reconfigured. May reduce power consumption.
.versionGet
g_keymatrix_on_kint.p_api->versionGet(&version)
Get version and store it in provided pointer v ersion.
1. Key Matrix HAL Module Features
This Key Matrix HAL module configures and con trols the Key Interrupt (KINT) peripheral. It implements th e
following key functions:
• Supports both rising and falling edges on KINT channels
• Supports interrupt-based event notif icat ion
• Supports a bit-masking function to capt ure multiple events efficiently
• Supports a matrix keypad w ith edges on any two channels
Figure 1. Key Matrix HAL Module Block Diag ram
2. Key Matrix HAL Module APIs Overview
The Key Matrix HAL module def ines API s for opening, closing, enabling, and disabling key-interrupt
functions. A com plete list of the av ailable 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 AP I summary table.
Table 1. Key Matrix HAL Module API Sum m a ry
g_kint.p_cfg)
Initial configuration.
Enable Key interrupt.
trigger)
Note: For details on operation and definitions for the function data struct ures, typedefs, defines, API data,
API structures and f unction v ar iables, rev iew the SSP User’ s Manual API R eferences for the
associated module.
R11AN0123EU0102 Rev.1.02 Page 2 of 12
Feb.27.19
Renesas Synergy™ Platform Key Matrix HAL Module Guide
Name
Description
SSP_SUCCESS
Function successfully co mpleted.
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.
Table 2. Sta tus Return Val ues
Note: Lower-level driver s may return common error codes. Refer to the SSP User’ s Manual API Ref erences
for the associated module for a definition of all relevant status return v alues.
3. 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 KIN T 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 t he callback argument
keymatrix_callback_args_t that s pecifies the channel(s) on w hich 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 w ere 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 bef ore the callback was cal led. If a new edge is detected af ter the callback was c alled, then
the interrupt is triggered again, resulting in a new callback.
This module can be used to implement a matrix keypad with edges on any two channels indicati ng the act u al
key that was pressed; alternatively, the module can be used as a single input to detec t an edge on an input
pin.
3.1 Ke y M atrix HAL Module Important Operational Notes and Limitations
3.1.1 Key Matrix HA L Module Op eratio n al Not es
• To trigger a transf er of data using the DMAC or DT C peripheral when a trigger edge is detected,
configure the DMAC/DT C transf er with activation_source set to ELC_EVENT_KEY_INT.
• The KI NT module can trigger the start of other peripherals available to the ELC. For details, see the ELC
section in the SSP User’s Manual.
• You must enable the KI NT (I NT KR) interrupt in the BSP for this module to operate, regardless of w hether
a callback is used in the open call.
3.1.2 Key Matrix HA L Module Limitations
• This module does not support polling-mode operati on.
• Refer to the latest SSP Release N otes for any additional operational limitations for this module.
4. Including the Key Matrix HAL Module in an A pplication
This section describ es how to include the Key Matrix H AL module in an application using the SSP
configurator.
Note: It is assumed 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 f irst few
chapters of the SSP User’s Manual to learn how to manage each of these important steps in creating
To add the Key Matrix Driv er to an application, simply add it to a thread using the stacks selection sequence
given in t he following table. (T he def ault name for the Key Matrix D riv er is g_kint0. T his name can be
changed in the associated Properties window.)
SSP-based applications.
R11AN0123EU0102 Rev.1.02 Page 3 of 12
Feb.27.19
Renesas Synergy™ Platform Key Matrix HAL Module Guide
Resource
ISDE Tab
Stacks Selection Sequence
g_kint0 Key Matrix Driver on r_kint
Threads
New Stack> Driv er> Input> Key Matr ix Driv er on
ISDE Property
Value
Description
Parameter
BSP, Enabled, Disable d
(Default: BSP)
Enable or disable the parameter error checking.
Name
g_kint0
Module name
Keymatrix
Select Channels Below
This is a bit-mask with each bit specifyi ng if that
to be used.
Table 3. Key Matrix HAL Modu le Selection Seq uenc e
r_kint
When the Key Matrix Driver on r_kint is added to the thread stack as shown in the following figure, the
configurator automatical ly adds any needed lower-level modules. Any dr iv ers that need additional
configuration information is box text highlighted in Red. Modules with a Gray band are indiv idual modules
that stand alone.
Figure 2. Key Matrix HAL Module Stack
5. Configuring the Key Matrix HAL Module
The Key Matrix HAL module on r_kint must be configured by the user for the desired operation. T he SSP
configuration window automatically identifies (by highlighting the block in red) any required configuration
selections, suc h as int errupts or operating modes, which must be configured for lower-lev el modules for
successful operation. Only properties that can be change d without causing conflicts are av ailable for
modification. Other properties are ‘locked’ and are not av ailable for changes, and are identified with a lock
icon for the ‘locked’ property in the Properties window in the Integrated Sol ution Developer Environment
(ISDE). T his approach simplifies the configuration process and makes it much less error-pr one than previous
‘manual’ approaches to configuration. The available configuration settings and def aults for all the useraccessible properties are giv en 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 av ailable within the Properties w indow of the associated module. Sim ply select the indicated
module and then v iew the properties window; the interrupt settings are often toward the bottom of the
properties list, so scroll down until they become available. Also note that the interrupt priorities listed in the
Properties window in the ISDE includes an indication as t o the v alidity of the setting based on the targeted
MCU (CM4 or CM0+). T his level of detail is not included in the following configuration properties tables, but
is easily v isible within the ISDE when configuring interrupt-priority lev els.
Note: You may want to open your ISDE, create the module and explore the property se ttings in parallel with
looking ov er the following configuration table settings. T his helps to orient you and can be a useful
‘hands-on’ approach to learning the ins and outs of developing with SSP.
Table 4. C onf igu rat io n Set tings for t he Key Mat rix HA L Module on r_ kin t
Checking
Channel Mask
R11AN0123EU0102 Rev.1.02 Page 4 of 12
Feb.27.19
channel is to be enabled or not. Select the channels
Loading...