nRF51 SDK: Button Handler

| nRF51 SDK

- Home
- Related Pages
- API Reference
- Data Structures

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Macros | Typedefs | Functions
Button Handler
SDK Common Libraries

Buttons handling module. More...

## Data Structures

struct | app_button_cfg_t
| Button configuration structure. More...
struct | pin_transition_t
| Pin transition direction struct. More...

## Macros

#define | APP_BUTTON_SCHED_EVT_SIZE sizeof(app_button_event_t)
#define | APP_BUTTON_PUSH 1
#define | APP_BUTTON_RELEASE 0
#define | APP_BUTTON_ACTIVE_HIGH 1
#define | APP_BUTTON_ACTIVE_LOW 0
#define | APP_BUTTON_INIT(BUTTONS, BUTTON_COUNT, DETECTION_DELAY, USE_SCHEDULER)
| Macro for initializing the Button Handler module. More...

## Typedefs

typedef void(* | app_button_handler_t )(uint8_t pin_no, uint8_t button_action)
| Button event handler type.
typedef uint32_t(* | app_button_evt_schedule_func_t )(app_button_handler_t button_handler, uint8_t pin_no, uint8_t button_action)
| Type of function for passing events from the Button Handler module to the scheduler.

## Functions

uint32_t | app_button_init (app_button_cfg_t *p_buttons, uint8_t button_count, uint32_t detection_delay, app_button_evt_schedule_func_t evt_schedule_func)
| Function for initializing the Buttons. More...
uint32_t | app_button_enable (void)
| Function for enabling button detection. More...
uint32_t | app_button_disable (void)
| Function for disabling button detection. More...
uint32_t | app_button_is_pushed (uint8_t pin_no, bool *p_is_pushed)
| Function for checking if a button is currently being pushed. More...

## Detailed Description

Buttons handling module.

The button handler uses the GPIOTE Handler to detect that a button has been pushed. To handle debouncing, it will start a timer in the GPIOTE event handler. The button will only be reported as pushed if the corresponding pin is still active when the timer expires. If there is a new GPIOTE event while the timer is running, the timer is restarted. Use the USE_SCHEDULER parameter of the APP_BUTTON_INIT() macro to select if the Scheduler is to be used or not.

Note
  The app_button module uses the app_timer module. The user must ensure that the queue in app_timer is large enough to hold the app_timer_stop() / app_timer_start() operations which will be executed on each event from GPIOTE module (2 operations), as well as other app_timer operations queued simultaneously in the application.
  Even if the scheduler is not used, app_button.h will include app_scheduler.h, so when compiling, app_scheduler.h must be available in one of the compiler include paths.

## Macro Definition Documentation

#define APP_BUTTON_ACTIVE_HIGH 1

Indicates that a button is active high.

#define APP_BUTTON_ACTIVE_LOW 0

Indicates that a button is active low.

#define APP_BUTTON_INIT | ( |  | BUTTONS,
|  |  | BUTTON_COUNT,
|  |  | DETECTION_DELAY,
|  |  | USE_SCHEDULER
| ) |  |

Value:
do \
{ \
uint32_t ERR_CODE = app_button_init((BUTTONS), \
(BUTTON_COUNT), \
(DETECTION_DELAY), \
(USE_SCHEDULER) ? app_button_evt_schedule : NULL); \
APP_ERROR_CHECK(ERR_CODE); \
} while (0)

Macro for initializing the Button Handler module.

It will initialize the specified pins as buttons, and configure the Button Handler module as a GPIOTE user (but it will not enable button detection). It will also connect the Button Handler module to the scheduler (if specified).

Parameters

  [in] | BUTTONS | Array of buttons to be used (type app_button_cfg_t, must be static!).
  [in] | BUTTON_COUNT | Number of buttons.
  [in] | DETECTION_DELAY | Delay from a GPIOTE event until a button is reported as pushed.
  [in] | USE_SCHEDULER | TRUE if the application is using the event scheduler, FALSE otherwise.

#define APP_BUTTON_PUSH 1

Indicates that a button is pushed.

#define APP_BUTTON_RELEASE 0

Indicates that a button is released.

#define APP_BUTTON_SCHED_EVT_SIZE sizeof(app_button_event_t)

Size of button events being passed through the scheduler (is to be used for computing the maximum size of scheduler events).

## Function Documentation

uint32_t app_button_disable | ( | void |  | ) |

Function for disabling button detection.

Return values

  NRF_ERROR_INVALID_PARAM | GPIOTE has to many users.
  NRF_ERROR_INVALID_STATE | Button or GPIOTE not initialized.
  NRF_SUCCESS | Button detection successfully enabled.

uint32_t app_button_enable | ( | void |  | ) |

Function for enabling button detection.

Return values

  NRF_ERROR_INVALID_PARAM | GPIOTE has to many users.
  NRF_ERROR_INVALID_STATE | Button or GPIOTE not initialized.
  NRF_SUCCESS | Button detection successfully enabled.

uint32_t app_button_init | ( | app_button_cfg_t * | p_buttons,
|  | uint8_t | button_count,
|  | uint32_t | detection_delay,
|  | app_button_evt_schedule_func_t | evt_schedule_func
| ) |  |

Function for initializing the Buttons.

This function will initialize the specified pins as buttons, and configure the Button Handler module as a GPIOTE user (but it will not enable button detection).

Note
  Normally initialization should be done using the APP_BUTTON_INIT() macro, as that will take care of connecting the Buttons module to the scheduler (if specified).
  app_button_enable() function must be called in order to enable the button detection.

Parameters

  [in] | p_buttons | Array of buttons to be used (NOTE: Must be static!).
  [in] | button_count | Number of buttons.
  [in] | detection_delay | Delay from a GPIOTE event until a button is reported as pushed.
  [in] | evt_schedule_func | Function for passing button events to the scheduler. Point to app_button_evt_schedule() to connect to the scheduler. Set to NULL to make the Buttons module call the event handler directly from the delayed button push detection timeout handler.

Returns
  NRF_SUCCESS on success, otherwise an error code.

uint32_t app_button_is_pushed | ( | uint8_t | pin_no,
|  | bool * | p_is_pushed
| ) |  |

Function for checking if a button is currently being pushed.

Parameters

  [in] | pin_no | Button pin to be checked.
  [out] | p_is_pushed | Button state.

Return values

  NRF_SUCCESS | State successfully read.
  NRF_ERROR_INVALID_PARAM | Invalid pin_no.