MCUXpresso SDK API Reference Manual  Rev 2.12.1
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Button

Overview

Data Structures

struct  button_callback_message_t
 The callback message struct of button. More...
 
struct  button_gpio_config_t
 The button gpio config structure. More...
 
struct  button_config_t
 The button config structure. More...
 

Macros

#define BUTTON_EVENT_ONECLICK_ENABLE   (1)
 Definition of feature 'one click' enable macro. More...
 
#define BUTTON_EVENT_DOUBLECLICK_ENABLE   (1)
 Definition of feature 'double click' enable macro. More...
 
#define BUTTON_EVENT_SHORTPRESS_ENABLE   (1)
 Definition of feature 'short press' enable macro. More...
 
#define BUTTON_EVENT_LONGPRESS_ENABLE   (1)
 Definition of feature 'long press' enable macro. More...
 
#define BUTTON_ALL_ENTER_EXIT_LOWPOWER_HANDLE   ((uint32_t *)0xffffffffU) /* MISRA C-2012 Rule 11.6 */
 Definition of all buttons enter/exit lowpower handle macro. More...
 
#define BUTTON_HANDLE_SIZE   (16U + 24U)
 Definition of button handle size as HAL_GPIO_HANDLE_SIZE + button dedicated size. More...
 
#define BUTTON_HANDLE_DEFINE(name)   uint32_t name[((BUTTON_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]
 Defines the button handle. More...
 
#define BUTTON_HANDLE_ARRAY_DEFINE(name, count)   uint32_t name[count][((BUTTON_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]
 Defines the button handle array. More...
 
#define BUTTON_TIMER_INTERVAL   (25U)
 Definition of button timer interval,unit is ms. More...
 
#define BUTTON_SHORT_PRESS_THRESHOLD   (200U)
 Definition of button short press threshold,unit is ms. More...
 
#define BUTTON_LONG_PRESS_THRESHOLD   (500U)
 Definition of button long press threshold,unit is ms. More...
 
#define BUTTON_DOUBLE_CLICK_THRESHOLD   (200U)
 Definition of button double click threshold,unit is ms. More...
 
#define BUTTON_USE_COMMON_TASK   (0U)
 Definition to determine whether use common task. More...
 
#define BUTTON_TASK_PRIORITY   (7U)
 Definition of button task priority. More...
 
#define BUTTON_TASK_STACK_SIZE   (1000U)
 Definition of button task stack size. More...
 
#define BUTTON_EVENT_BUTTON   (1U)
 Definition of button event. More...
 

Typedefs

typedef void * button_handle_t
 The handle of button.
 
typedef button_status_t(* button_callback_t )(void *buttonHandle, button_callback_message_t *message, void *callbackParam)
 The callback function of button.
 

Enumerations

enum  button_status_t {
  kStatus_BUTTON_Success = kStatus_Success,
  kStatus_BUTTON_Error = MAKE_STATUS(kStatusGroup_BUTTON, 1),
  kStatus_BUTTON_LackSource = MAKE_STATUS(kStatusGroup_BUTTON, 2)
}
 The status type of button. More...
 
enum  button_event_t {
  kBUTTON_EventOneClick = 0x01U,
  kBUTTON_EventDoubleClick,
  kBUTTON_EventShortPress,
  kBUTTON_EventLongPress,
  kBUTTON_EventError
}
 The event type of button. More...
 

Functions

button_status_t BUTTON_Deinit (button_handle_t buttonHandle)
 Deinitializes a button instance. More...
 
button_status_t BUTTON_GetInput (button_handle_t buttonHandle, uint8_t *pinState)
 Get button pin input. More...
 
button_status_t BUTTON_WakeUpSetting (button_handle_t buttonHandle, uint8_t enable)
 Enables or disables the button wake-up feature. More...
 
button_status_t BUTTON_EnterLowpower (button_handle_t buttonHandle)
 Prepares to enter low power consumption. More...
 
button_status_t BUTTON_ExitLowpower (button_handle_t buttonHandle)
 Restores from low power consumption. More...
 

Initialization

button_status_t BUTTON_Init (button_handle_t buttonHandle, button_config_t *buttonConfig)
 Initializes a button with the button handle and the user configuration structure. More...
 

Install callback

button_status_t BUTTON_InstallCallback (button_handle_t buttonHandle, button_callback_t callback, void *callbackParam)
 Installs a callback and callback parameter. More...
 

Data Structure Documentation

struct button_callback_message_t
struct button_gpio_config_t

Data Fields

hal_gpio_direction_t direction
 GPIO Pin direction (0 - In, 1 - Out)
 
uint8_t pinStateDefault
 GPIO Pin voltage when button is not pressed (0 - low level, 1 - high level)
 
uint8_t port
 GPIO Port.
 
uint8_t pin
 GPIO Pin.
 
struct button_config_t

Macro Definition Documentation

#define BUTTON_EVENT_ONECLICK_ENABLE   (1)
#define BUTTON_EVENT_DOUBLECLICK_ENABLE   (1)
#define BUTTON_EVENT_SHORTPRESS_ENABLE   (1)
#define BUTTON_EVENT_LONGPRESS_ENABLE   (1)
#define BUTTON_ALL_ENTER_EXIT_LOWPOWER_HANDLE   ((uint32_t *)0xffffffffU) /* MISRA C-2012 Rule 11.6 */
#define BUTTON_HANDLE_SIZE   (16U + 24U)
#define BUTTON_HANDLE_DEFINE (   name)    uint32_t name[((BUTTON_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]

This macro is used to define a 4 byte aligned button handle. Then use "(button_handle_t)name" to get the button handle.

The macro should be global and could be optional. You could also define button handle by yourself.

This is an example,

* BUTTON_HANDLE_DEFINE(buttonHandle);
*
Parameters
nameThe name string of the button handle.
#define BUTTON_HANDLE_ARRAY_DEFINE (   name,
  count 
)    uint32_t name[count][((BUTTON_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]

This macro is used to define a 4 byte aligned button handle array. Then use "(button_handle_t)name[0]" to get the first button handle.

The macro should be global and could be optional. You could also define these button handle by yourself.

This is an example,

* BUTTON_HANDLE_DEFINE(buttonHandleArray, 1);
*
Parameters
nameThe name string of the button handle array.
countThe amount of button handle.
#define BUTTON_TIMER_INTERVAL   (25U)
#define BUTTON_SHORT_PRESS_THRESHOLD   (200U)
#define BUTTON_LONG_PRESS_THRESHOLD   (500U)
#define BUTTON_DOUBLE_CLICK_THRESHOLD   (200U)
#define BUTTON_USE_COMMON_TASK   (0U)
#define BUTTON_TASK_PRIORITY   (7U)
#define BUTTON_TASK_STACK_SIZE   (1000U)
#define BUTTON_EVENT_BUTTON   (1U)

Enumeration Type Documentation

Enumerator
kStatus_BUTTON_Success 

Success.

kStatus_BUTTON_Error 

Failed.

kStatus_BUTTON_LackSource 

Lack of sources.

Enumerator
kBUTTON_EventOneClick 

One click with short time, the duration of key down and key up is less than BUTTON_SHORT_PRESS_THRESHOLD.

kBUTTON_EventDoubleClick 

Double click with short time, the duration of key down and key up is less than BUTTON_SHORT_PRESS_THRESHOLD.

And the duration of the two button actions does not exceed BUTTON_DOUBLE_CLICK_THRESHOLD.

kBUTTON_EventShortPress 

Press with short time, the duration of key down and key up is no less than BUTTON_SHORT_PRESS_THRESHOLD and less than BUTTON_LONG_PRESS_THRESHOLD.

kBUTTON_EventLongPress 

Press with long time, the duration of key down and key up is no less than BUTTON_LONG_PRESS_THRESHOLD.

kBUTTON_EventError 

Error event if the button actions cannot be identified.

Function Documentation

button_status_t BUTTON_Init ( button_handle_t  buttonHandle,
button_config_t buttonConfig 
)

This function configures the button with user-defined settings. The user can configure the configuration structure. The parameter buttonHandle is a pointer to point to a memory space of size BUTTON_HANDLE_SIZE allocated by the caller.

Example below shows how to use this API to configure the button. For one button,

* static BUTTON_HANDLE_DEFINE(s_buttonHandle);
* button_config_t buttonConfig;
* buttonConfig.gpio.port = 0;
* buttonConfig.gpio.pin = 1;
* buttonConfig.gpio.pinStateDefault = 0;
* BUTTON_Init((button_handle_t)s_buttonHandle, &buttonConfig);
*

For multiple buttons,

* static BUTTON_HANDLE_ARRAY_DEFINE(s_buttonArrayHandle, count);
* button_config_t buttonArrayConfig[count];
* for(uint8_t i = 0U; i < count; i++)
* {
* buttonArrayConfig[i].gpio.port = 0;
* buttonArrayConfig[i].gpio.pin = 1;
* buttonArrayConfig[i].gpio.pinStateDefault = 0;
* BUTTON_Init((button_handle_t)s_buttonArrayHandle[i], &buttonArrayConfig[i]);
* }
*
Parameters
buttonHandlePointer to point to a memory space of size BUTTON_HANDLE_SIZE allocated by the caller. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. You can define one handle in the following two ways: BUTTON_HANDLE_DEFINE(buttonHandle); or uint32_t buttonHandle[((BUTTON_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]; You can define multiple handles in the following way: BUTTON_HANDLE_ARRAY_DEFINE(buttonHandleArray, count);
buttonConfigPointer to user-defined configuration structure.
Returns
Indicates whether initialization was successful or not.
Return values
kStatus_BUTTON_ErrorAn error occurred.
kStatus_BUTTON_SuccessButton initialization succeed.
button_status_t BUTTON_InstallCallback ( button_handle_t  buttonHandle,
button_callback_t  callback,
void *  callbackParam 
)

This function is used to install the callback and callback parameter for button module. Once the button is pressed, the button driver will identify the behavior and notify the upper layer with the button event by the installed callback function. Currently, the Button supports the three types of event, click, double click and long press. Detail information refer to button_event_t.

Parameters
buttonHandleButton handle pointer.
callbackThe callback function.
callbackParamThe parameter of the callback function.
Returns
Indicates whether callback install was successful or not.
Return values
kStatus_BUTTON_SuccessSuccessfully install the callback.
button_status_t BUTTON_Deinit ( button_handle_t  buttonHandle)

This function deinitializes the button instance.

Parameters
buttonHandlebutton handle pointer.
Return values
kStatus_BUTTON_Successbutton de-initialization succeed.
button_status_t BUTTON_GetInput ( button_handle_t  buttonHandle,
uint8_t *  pinState 
)

This function is used for get the button pin input.

Parameters
buttonHandlebutton handle pointer.
pinStatea pointer to save the pin state.
Return values
kStatus_BUTTON_ErrorAn error occurred.
kStatus_BUTTON_SuccessSet successfully.
button_status_t BUTTON_WakeUpSetting ( button_handle_t  buttonHandle,
uint8_t  enable 
)

This function enables or disables the button wake-up feature.

Parameters
buttonHandlebutton handle pointer.
enableenable or disable (0 - disable, 1 - enable).
Return values
kStatus_BUTTON_ErrorAn error occurred.
kStatus_BUTTON_SuccessSet successfully.
button_status_t BUTTON_EnterLowpower ( button_handle_t  buttonHandle)

This function is used to prepare to enter low power consumption.

Parameters
buttonHandlebutton handle pointer.
Return values
kStatus_BUTTON_SuccessSuccessful operation.
button_status_t BUTTON_ExitLowpower ( button_handle_t  buttonHandle)

This function is used to restore from low power consumption.

Parameters
buttonHandlebutton handle pointer.
Return values
kStatus_BUTTON_SuccessSuccessful operation.