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.

• Keypad mode.
  In this mode, an interrupt is triggered whenever a normal key is pressed or released. A callback function can be registered for the interrupt. The callback function is invoked whenever a key is pressed or released. hal_keypad_get_key() can be used in the callback function to get the key event and the key position number.
  
• Powerkey mode.
  In this mode, an interrupt is triggered whenever the powerkey is pressed or released. A callback function can be registered for the interrupt. The callback function is invoked whenever the powerkey is pressed or released. hal_keypad_get_key() can be used in the callback function to get the key event and the key data.
  

How to use this driver

• Using the keypad mode.
  To use the keypad driver in normal keypad mode, please refer to GPIO datasheet to determine which GPIOs should be selected to pinmux to keypad column and row pins. Note that if you use the EPT tool to configure the keypad pin settings, there is no need to configure the keypad GPIO pinmux anymore. Then call hal_keypad_init() to manually set the keypad mode, the key column and row and the debounce time. Call hal_keypad_init(), then call hal_keypad_register_callback() to register a callback. Call hal_keypad_enable() to start the keypad module. If a key is pressed or released on the keypad, the keypad triggers an interrupt to call the callback function. User should use hal_keypad_get_key() in the callback function to get the key event and the key position number. To ensure a reliable key scan, do not overload the callback function. Let the callback return as quick as possible.
  • Step1. Call hal_keypad_init() to initialize the keypad module.
  • Step2. Call hal_keypad_register_callback() to register a callback function.
  • Step3. Call hal_keypad_enable() to start the keypad module.
  • Step4. Call hal_keypad_get_key() to get the key event and the key position number inside the callback function.
  • Step5. Call hal_keypad_deinit() to de-initialize the keypad module if it's no longer in use.
  • Sample code:

    hal_keypad_config_t keypad_config;
    
    keypad_config.mode  = HAL_KEYPAD_MODE_DOUBLE_KEY;                   // Chooses double key.
    keypad_config.key_map.column_bitmap = 0x07;                         // Columns 0 to 2 are selected.
    keypad_config.key_map.row_bitmap    = 0x07;                         // Rows 0 to 2 are selected.
    keypad_config.debounce              = 16;                           // Sets the debounce time to 16 milliseconds.
    
    if (HAL_KEYPAD_STATUS_OK != hal_keypad_init(&keypad_config)) {  // initialize the keypad module.
       //error handler
    }
    
    //Register a user callback.
    if ( HAL_KEYPAD_STATUS_OK != hal_keypad_register_callback(user_keypad_callback,user_data)) {
       // error handler
    }
    
    hal_keypad_enable();                                                // Enables the keypad module.
    ...
    hal_keypad_deinit();                                                // Deinitializes the keypad module, if it's no longer in use.

    // Callback function. This function should be registered with #hal_keypad_register_callback().
    void user_keypad_callback (void *user_data)
    {
        // Get the key press or release event.
         hal_keypad_event_t keypad_event;
         hal_keypad_get_key(&keypad_event);
    
    }

• Using powerkey mode.
  Call hal_keypad_powerkey_init() to initialize the keypad powerkey module. set the base environment and the key data value to use the powerkey mode. Call hal_keypad_powerkey_init(), then call hal_keypad_powerkey_register_callback() to register a callback. The powerkey module starts working once a callback function is registered. If the power key is pressed or released, the key triggers an interrupt and calls a callback function. User should use hal_keypad_powerkey_get_key() in callback function to get the key event and the key data values. To ensure a smooth key scan, do not overload the callback function. Let the callback return as quick as possible.
  • Step1. Call hal_keypad_powerkey_init() to initialize the keypad powerkey and the key data value.
  • Step2. Call hal_keypad_powerkey_register_callback() to register a callback function and the powerkey driver starts working.
  • Step3. Call hal_keypad_powerkey_get_key() to get key event and key data value.
  • Step4. Call hal_keypad_powerkey_deinit() to de-initialize the powerkey if it's no longer in use.
  • Sample code:

    hal_keypad_config_t keypad_config;
    uint32_t powerkey_data;
    
    powerkey_data = 0xfe;                                                // Sets the key value to 0xfe.
    
    if (HAL_KEYPAD_STATUS_OK != hal_keypad_powerkey_init(&powerkey_data)) {  // Initialize the keypad powerkey.
       //If the configuration is not #HAL_KEYPAD_STATUS_OK, call the error handler.
       //error handler
    }
    
    //Register a user callback.
    if ( HAL_KEYPAD_STATUS_OK != hal_keypad_powerkey_register_callback(user_keypad_callback,user_data) ) {
       //error handler
    }
    ...
    hal_keypad_powerkey_deinit();                                          // Deinitializes the keypad powerkey module, if it's no longer in use.

    // Callback function. This function should be registered with #hal_keypad_powerkey_register_callback().
    void user_keypad_callback (void *user_data)
    {
        // User's handler
        hal_powerkey_event_t powerkey_event;
    
        hal_keypad_powerkey_get_key(&powerkey_event);
    
    }

How to connect the EPT tool

• Normal keypad mode.
  The normal keypad mode only supports keypad pins. The other GPIO pins cannot be used with the keypad driver. Two types of keypads are supported in the normal keypad mode: 3x3 single keys and 3x3 configurable double keys. The EPT tool configures the keypad pin columns and rows in GPIO setting page, it maps the symbol of key data to hardware key data, and selects the single or double key mode in keypad settings page.
• Powerkey mode.
  The powerkey mode supports the powerkey pin only. The other pins cannot be used with the keypad driver. The powerkey driver supports power key only. The EPT tool maps the hardware key data to the powerkey symbol.

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_debounce

is 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_event

is 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_timing

is 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_config

is 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_event

is 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_data

is 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]	callback	is a pointer to the callback. This callback will be called when the powerkey release or press a key.
[in]	user_data	This 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]	callback	is a function pointer to the callback. This callback is called when the keypad key is released or pressed.
[in]	user_data	This 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_debounce

is 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_timing

is 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()