Detailed Description

Button driver.

Synopsis

#include <ti/drivers/apps/Button.h>
int main(void)
{
    Button_Params params;
    Button_Handle handle;
    Button_Params_init(&params);
    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

Generic Configuration

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[] = {
    GPIOMSP432_P1_1 | GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_FALLING,
    GPIOMSP432_P1_4 | GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_FALLING,
}

#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_Config *	Button_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

typedef enum Button_Events 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

typedef struct Button_HWAttrs 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

enum 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

enum 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] handle A 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]	buttonIndex	Logical button number indexed into the Button_config table
[in]	buttonCallback	A Button_Callback that is called when a desired event occurs.
[in]	*params	A 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] params A pointer to a Button_Params structure that will be initialized.

Default values

parameter	value	description	unit
debounceDuration	10	debounce duration	ms
longPressDuration	2000	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] handle Pointer 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]	handle	A Button_Handle returned from Button_open()
[in]	buttonCallback	button 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] index Index 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

Detailed Description

Synopsis

Examples

Overview

User requirements

Defining Button_Config, Button_Object and Button_HWAttrs

Setting up GPIO configurations

Data Structures

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

§ Button_Config

§ Button_Handle

§ Button_Events

§ Button_EventMask

§ Button_Callback

§ Button_Pull

§ Button_HWAttrs

§ Button_Object

§ Button_Params

Enumeration Type Documentation

§ Button_Events

§ Button_Pull

Function Documentation

§ Button_close()

§ Button_init()

§ Button_open()

§ Button_Params_init()

Default values

§ Button_getLastPressedDuration()

§ Button_setCallback()

§ Button_gpioCallbackFxn()

Variable Documentation

§ Button_count