MT2523 API Reference  LinkIt SDK v4
KEYPAD

This section introduces the keypad driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions. More...

Overview

This section introduces the keypad driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.

Terms and acronyms

Terms Details
GPIO For an introduction to General Purpose Inputs-Outputs, please refer to the GPIO module in HAL.
NVIC The Nested Vectored Interrupt Controller (NVIC) is the interrupt controller of ARM Cortex-M.For more details, please refer to NVIC introduction in ARM Cortex-M4 Processor Technical Reference Manual .
keypad The keypad is an input device controller that can get input events.

Supported features

This module provides a generic design to get external key events. The keypad provides two different modes, the keypad mode and the power key mode.

How to use this driver

How to connect the EPT tool

How to customize the keypad driver

The configurations related to the keypad are in the custom files under driver/board/mtxxxx_hdk/keypad. In these files, user can modify the debounce time, longpress and repeat time for the keys in the normal keypad mode. Modify the longpress and repeat time for the keys in the powerkey mode. These files provide functions to translate hardware key data to the symbol of EPT tool keypad data in normal keypad mode.

Functions

hal_keypad_status_t hal_keypad_init (const hal_keypad_config_t *keypad_config)
 This function initialize the keypad module. More...
 
hal_keypad_status_t hal_keypad_powerkey_init (uint32_t powerkey_data)
 This function initializes the powerkey base environment. More...
 
hal_keypad_status_t hal_keypad_deinit (void)
 This function deinitializes the keypad module. More...
 
hal_keypad_status_t hal_keypad_powerkey_deinit (void)
 This function de-initializes the powerkey base environment. More...
 
hal_keypad_status_t hal_keypad_set_debounce (const uint32_t *keypad_debounce)
 This function sets the keypad debounce time, the unit is in milliseconds. More...
 
hal_keypad_status_t hal_keypad_get_debounce (uint32_t *keypad_debounce)
 This function gets the keypad debounce time, the unit is in milliseconds. More...
 
hal_keypad_status_t hal_keypad_enable (void)
 This function enables the keypad module. More...
 
hal_keypad_status_t hal_keypad_disable (void)
 This function disables the keypad module. More...
 
hal_keypad_status_t hal_keypad_set_scan_timing (const hal_keypad_scan_timing_t *keypad_scan_timing)
 Set the keypad scan timing. More...
 
hal_keypad_status_t hal_keypad_get_scan_timing (hal_keypad_scan_timing_t *keypad_scan_timing)
 Get the keypad scan timing. More...
 
hal_keypad_status_t hal_keypad_register_callback (hal_keypad_callback_t callback, void *user_data)
 This function registers a callback function when in a normal key mode. More...
 
hal_keypad_status_t hal_keypad_powerkey_register_callback (hal_powerkey_callback_t callback, void *user_data)
 This function registers a callback function when in a powerkey mode. More...
 
hal_keypad_status_t hal_keypad_get_key (hal_keypad_event_t *keypad_event)
 This function gets the key event. More...
 
hal_keypad_status_t hal_keypad_powerkey_get_key (hal_keypad_powerkey_event_t *powerkey_event)
 This function gets the powerkey event. More...
 

Modules

 Enum
 
 Struct
 
 Typedef
 

Function Documentation

hal_keypad_status_t hal_keypad_deinit ( void  )

This function deinitializes the keypad module.

After calling this function, the callback is cleared, interrupts and keypad module are disabled.

Returns
HAL_KEYPAD_STATUS_OK, if operation is successful.
HAL_KEYPAD_STATUS_ERROR, if #()hal_keypad_init has not been initialized or if there still has data in keypad buffer.
See also
hal_keypad_init()
hal_keypad_status_t hal_keypad_disable ( void  )

This function disables the keypad module.

Returns
HAL_KEYPAD_STATUS_OK, if operation is successful.
HAL_KEYPAD_STATUS_ERROR, if #()hal_keypad_init has not been initialized.
See also
hal_keypad_enable()
hal_keypad_status_t hal_keypad_enable ( void  )

This function enables the keypad module.

Returns
HAL_KEYPAD_STATUS_OK, if operation is successful.
See also
hal_keypad_disable()
hal_keypad_status_t hal_keypad_get_debounce ( uint32_t *  keypad_debounce)

This function gets the keypad debounce time, the unit is in milliseconds.

Parameters
[in]keypad_debounceis a user defined pointer to get the current debounce time.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful.
See also
hal_keypad_set_debounce()
hal_keypad_status_t hal_keypad_get_key ( hal_keypad_event_t keypad_event)

This function gets the key event.

The key event specifies if the current key state is pressed or released, and the data is the key position number, not the key value.

Parameters
[in]keypad_eventis a pointer to the key event. For more details, please refer to hal_keypad_event_t.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful. HAL_KEYPAD_STATUS_ERROR, if there is no data in the buffer.
hal_keypad_status_t hal_keypad_get_scan_timing ( hal_keypad_scan_timing_t keypad_scan_timing)

Get the keypad scan timing.

Parameters
[in]keypad_scan_timingis a pointer of the current configuration. For more details, please refer to hal_keypad_scan_timing_t.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful. HAL_KEYPAD_INVALID_PARAMETER, if parameter is wrong.
See also
hal_keypad_set_scan_timing().
hal_keypad_status_t hal_keypad_init ( const hal_keypad_config_t keypad_config)

This function initialize the keypad module.

Call this function if the keypad is required.

Parameters
[in]keypad_configis the pointer to configuration. For more details, please refer to hal_keypad_config_t.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful.
HAL_KEYPAD_STATUS_ERROR, if #()hal_keypad_init has not been initialized.
See also
hal_keypad_deinit()
hal_keypad_status_t hal_keypad_powerkey_deinit ( void  )

This function de-initializes the powerkey base environment.

After calling this function, the interrupt is disabled, the callback function is cleared.

Returns
HAL_KEYPAD_STATUS_OK, if operation is successful. HAL_KEYPAD_STATUS_ERROR, powerkey deinitialization has failed.
See also
hal_keypad_powerkey_init().
hal_keypad_status_t hal_keypad_powerkey_get_key ( hal_keypad_powerkey_event_t powerkey_event)

This function gets the powerkey event.

The powerkey event specifies if the current key state is pressed or released, and the key data.

Parameters
[in]powerkey_eventis a pointer to the powerkey event. For more details, please refer to hal_keypad_powerkey_event_t.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful. HAL_KEYPAD_STATUS_ERROR, if all of the key data and event are read.
hal_keypad_status_t hal_keypad_powerkey_init ( uint32_t  powerkey_data)

This function initializes the powerkey base environment.

After calling this function, the interrupt is enabled.

Parameters
[in]powerkey_datais the powerkey data defined by user.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful. HAL_KEYPAD_STATUS_ERROR, powerkey initialization has failed.
See also
hal_keypad_powerkey_deinit().
hal_keypad_status_t hal_keypad_powerkey_register_callback ( hal_powerkey_callback_t  callback,
void *  user_data 
)

This function registers a callback function when in a powerkey mode.

The callback can only be registered after calling the function hal_keypad_powerkey_init(). The callback function will be called after the powerkey is pressed or released in the ISR routine. After register a callback function, the powerkey module is started.

Parameters
[in]callbackis a pointer to the callback. This callback will be called when the powerkey release or press a key.
[in]user_dataThis variable pointer is defined by the user to record data.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful. HAL_KEYPAD_STATUS_ERROR, hal_keypad_powerkey_init() has not been called or the callback is null.
hal_keypad_status_t hal_keypad_register_callback ( hal_keypad_callback_t  callback,
void *  user_data 
)

This function registers a callback function when in a normal key mode.

The callback can only be registered after calling the function hal_keypad_init(). The callback function is called after a key is pressed or released in the ISR routine.

Parameters
[in]callbackis a function pointer to the callback. This callback is called when the keypad key is released or pressed.
[in]user_dataThis variable pointer is defined by the user to record the data.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful. HAL_KEYPAD_STATUS_ERROR, hal_keypad_init() has not been called or callback is null.
hal_keypad_status_t hal_keypad_set_debounce ( const uint32_t *  keypad_debounce)

This function sets the keypad debounce time, the unit is in milliseconds.

Parameters
[in]keypad_debounceis a pointer to the debounce time setting, it cannot be greater than 255.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful.
HAL_KEYPAD_INVALID_PARAMETER, if the value is larger than 255.
See also
hal_keypad_get_debounce()
hal_keypad_status_t hal_keypad_set_scan_timing ( const hal_keypad_scan_timing_t keypad_scan_timing)

Set the keypad scan timing.

Parameters
[in]keypad_scan_timingis a pointer to the configuration. For more details, please refer to hal_keypad_scan_timing_t.
Returns
HAL_KEYPAD_STATUS_OK, if operation is successful. HAL_KEYPAD_INVALID_PARAMETER, if parameter is wrong.
See also
hal_keypad_get_scan_timing()