Data Structures | Typedefs | Enumerations | Functions | Variables
Button.h File Reference

Detailed Description

Button driver.


Synopsis

int main(void)
{
Button_Params params;
Button_Handle handle;
handle = Button_open(CONFIG_BUTTON0, buttonCallbackFxn, &params);
...
}
void buttonCallbackFxn(Button_Handle handle, Button_EventMask events)
{
if (events & Button_EV_CLICK)
{
// Received a click, handle app condition 0 etc
handleAppCond(0);
}
if (events & Button_EV_LONGCLICKED)
{
// Long press, handle app condition 1 etc
handleAppCond(1);
}
...
}

Examples

Overview

The Button driver simplifies interfacing push buttons. For example, push buttons on LaunchPads, BoosterPacks, or custom boards may easily be managed via the Button API. A given button instance may subscribe to one or several Button_Events. When a subscribed event occurs, the user will receive a callback with the handle of the button and the event(s) that occured.

User requirements

Buttons use the GPIO.h interface for interfacing with hardware, so a GPIO_PinConfig array must exist and contain a config for the button pin. The user must statically allocate a Button_Config array called Button_config. Each physical button should map to an index in Button_config.

Defining Button_Config, Button_Object and Button_HWAttrs

Each structure must be defined by the application. The following example is for a MSP432 in which two buttons are setup. The following declarations are placed in "ti_drivers_config.h" and "ti_drivers_config.c" respectively. How the GPIO configs are defined are detailed in the next example.

"ti_drivers_config.h"

#define CONFIG_BUTTON_0 0 //Button number 1
#define CONFIG_BUTTON_1 1 //Button number 2

"ti_drivers_config.c"

#include <Button.h>
Button_Object Button_object[2];
const Button_HWAttrs Button_hwAttrs[2] = {
{
.gpioIndex = CONFIG_S1,
},
{
.gpioIndex = CONFIG_S2,
}
};
const Button_Config Button_config[2] = {
{
.hwAttrs = &Button_hwAttrs[0],
.object = &Button_object[0],
},
{
.hwAttrs = &Button_hwAttrs[1],
.object = &Button_object[1],
},
};

Setting up GPIO configurations

The following example is for a MSP432. We are showing interfacing of two push buttons. Each need a GPIO pin. The following definitions are in "ti_drivers_config.h" and "ti_drivers_config.c" respectively. This example uses GPIO pins 1.1 and 1.4. The other GPIO configuration structures must exist, see GPIO.h.

"ti_drivers_config.h"

#define CONFIG_S1 0
#define CONFIG_S2 1

"ti_drivers_config.c"

#include <gpio.h>
GPIO_PinConfig gpioPinConfigs[] = {
}
#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/GPIO.h>
#include <ti/drivers/dpl/ClockP.h>
Include dependency graph for Button.h:

Go to the source code of this file.

Data Structures

struct  Button_Config
 Button configuration. More...
 
struct  Button_HWAttrs
 Hardware specific settings for a button. More...
 
struct  Button_Object
 Internal to Button module. Members should not be accessed by the application. More...
 
struct  Button_Params
 Button Parameters. More...
 

Typedefs

typedef struct Button_Config Button_Config
 Button configuration. More...
 
typedef struct Button_ConfigButton_Handle
 A handle that is returned from a Button_open() call. More...
 
typedef enum Button_Events Button_Events
 Button event flags. More...
 
typedef uint8_t Button_EventMask
 Event subscription and notification mask type. More...
 
typedef void(* Button_Callback) (Button_Handle buttonHandle, Button_EventMask buttonEvents)
 A handler to receive button callbacks. More...
 
typedef enum Button_Pull Button_Pull
 Button Pull settings. More...
 
typedef struct Button_HWAttrs Button_HWAttrs
 Hardware specific settings for a button. More...
 
typedef struct Button_Object Button_Object
 Internal to Button module. Members should not be accessed by the application. More...
 
typedef struct Button_Params Button_Params
 Button Parameters. More...
 

Enumerations

enum  Button_Events {
  Button_EV_PRESSED = 0x01, Button_EV_LONGPRESSED = 0x02, Button_EV_RELEASED = 0x04, Button_EV_CLICKED = 0x08,
  Button_EV_LONGCLICKED = 0x10, Button_EV_DOUBLECLICKED = 0x20
}
 Button event flags. More...
 
enum  Button_Pull { Button_PULL_DOWN = 0, Button_PULL_UP = 1, Button_PULL_NOTSET = 2 }
 Button Pull settings. More...
 

Functions

bool Button_close (Button_Handle handle)
 Function to close a Button specified by the Button_Handle. More...
 
void Button_init ()
 Function to initialize Button driver. More...
 
Button_Handle Button_open (uint_least8_t buttonIndex, Button_Callback buttonCallback, Button_Params *params)
 Function to open a given Button. More...
 
void Button_Params_init (Button_Params *params)
 Function to initialize a Button_Params struct to its defaults. More...
 
uint32_t Button_getLastPressedDuration (Button_Handle handle)
 Function to return the lastPressedDuration (valid only for short press, long press) More...
 
void Button_setCallback (Button_Handle handle, Button_Callback buttonCallback)
 Function to set callback function for the button instance. More...
 
void Button_gpioCallbackFxn (uint_least8_t index)
 This is the GPIO interrupt callback function which is called on a button press or release. This is internally used by button module. More...
 

Variables

const uint_least8_t Button_count
 

Typedef Documentation

§ Button_Config

typedef struct Button_Config Button_Config

Button configuration.

Each Button_Config represents a single physical button. It contains pointers to the button's Button_HWAttrs and Button_Object. The user must statically allocate all of these structures.

§ Button_Handle

typedef struct Button_Config* Button_Handle

A handle that is returned from a Button_open() call.

User will use this handle to interact with a given button instance.

§ Button_Events

Button event flags.

The event flags can be used by the user to subscribe to specific kinds of button actions and by the driver to signal which event caused a callback.

§ Button_EventMask

typedef uint8_t Button_EventMask

Event subscription and notification mask type.

§ Button_Callback

typedef void(* Button_Callback) (Button_Handle buttonHandle, Button_EventMask buttonEvents)

A handler to receive button callbacks.

§ Button_Pull

typedef enum Button_Pull Button_Pull

Button Pull settings.

This enumeration defines whether the GPIO connected to the button is PULL UP or PULL DOWN

§ Button_HWAttrs

Hardware specific settings for a button.

This structure should be defined and provided by the application. The index provided should correspond to a gpio pin in a GPIO_PinConfig array. This gpio pin should be the pin connected to the button and must be configured as GPIO_CFG_INPUT and GPIO_CFG_IN_INT_FALLING.

§ Button_Object

typedef struct Button_Object Button_Object

Internal to Button module. Members should not be accessed by the application.

§ Button_Params

typedef struct Button_Params Button_Params

Button Parameters.

Button parameters are used with the Button_open() call. Default values for these parameters are set using Button_Params_init().

See also
Button_Params_init()

Enumeration Type Documentation

§ Button_Events

Button event flags.

The event flags can be used by the user to subscribe to specific kinds of button actions and by the driver to signal which event caused a callback.

Enumerator
Button_EV_PRESSED 

Button pressed down, may or may not subsequently have been released

Button_EV_LONGPRESSED 

Button held down for more than tLongpress (ms)

Button_EV_RELEASED 

Button released after press or longpress

Button_EV_CLICKED 

Button was pressed and released, but was not a long press

Button_EV_LONGCLICKED 

Button was pressed and released, and held for longer than longPressDuration (ms)

Button_EV_DOUBLECLICKED 

Button was pressed when double click detection was active

§ Button_Pull

Button Pull settings.

This enumeration defines whether the GPIO connected to the button is PULL UP or PULL DOWN

Enumerator
Button_PULL_DOWN 

Button is PULLED DOWN.

Button_PULL_UP 

Button is PULLED UP.

Button_PULL_NOTSET 

Button pull not set

Function Documentation

§ Button_close()

bool Button_close ( Button_Handle  handle)

Function to close a Button specified by the Button_Handle.

Precondition
Button_open() had to be called first.
Parameters
[in]handleA Button_Handle returned from Button_open() call
Returns
True on success or false upon failure.

§ Button_init()

void Button_init ( )

Function to initialize Button driver.

§ Button_open()

Button_Handle Button_open ( uint_least8_t  buttonIndex,
Button_Callback  buttonCallback,
Button_Params params 
)

Function to open a given Button.

Function to open a button instance corresponding to a Button_Config in the Button_config array. The GPIO configurations must exist prior to calling this function. The Button_Params may be used to specify runtime parameters.

Precondition
Button_init() has to be called first
Parameters
[in]buttonIndexLogical button number indexed into the Button_config table
[in]buttonCallbackA Button_Callback that is called when a desired event occurs.
[in]*paramsA pointer to Button_Params structure. If NULL, it will use default values.
Returns
A Button_Handle on success, or a NULL on failure.
See also
Button_init()
Button_Params_init()
Button_close()

§ Button_Params_init()

void Button_Params_init ( Button_Params params)

Function to initialize a Button_Params struct to its defaults.

Parameters
[in]paramsA pointer to a Button_Params structure that will be initialized.

Default values

parameter value description unit
debounceDuration 10 debounce duration ms
longPressDuration2000 long press duration ms
buttonEventMask 0xFF subscribed to all events NA

§ Button_getLastPressedDuration()

uint32_t Button_getLastPressedDuration ( Button_Handle  handle)

Function to return the lastPressedDuration (valid only for short press, long press)

The API returns last pressed duration and it is valid only for shortpress, longpress. If this API is called after receiving an event click or long click then the API returns the press duration which is time delta between the press and release of the button.

Note
This API call is only valid after a click or long click and not after a double click.
Parameters
[in]handlePointer to the Button_Handle of the desired button.
Returns
time duration in milliseconds.

§ Button_setCallback()

void Button_setCallback ( Button_Handle  handle,
Button_Callback  buttonCallback 
)

Function to set callback function for the button instance.

Parameters
[in]handleA Button_Handle returned from Button_open()
[in]buttonCallbackbutton callback function

§ Button_gpioCallbackFxn()

void Button_gpioCallbackFxn ( uint_least8_t  index)

This is the GPIO interrupt callback function which is called on a button press or release. This is internally used by button module.

This function is internally used by button module for receiving the GPIO interrupt callbacks. This is exposed to the application for wake up cases. In some of the MCUs, when in LPDS(Low power deep sleep) the GPIO interrupt is consumed for wake up, and in order to make the button module work the the application has to call this API with the index of the GPIO pin which actually was the reason for the wake up.

Parameters
[in]indexIndex of the GPIO for which the button press has to be detected. This is an index in GPIO_PinConfig array.

Variable Documentation

§ Button_count

const uint_least8_t Button_count
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale