Button.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016-2019, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

 /*!***************************************************************************
 *  @file       Button.h
 *
 *  @brief      Button driver
 *
 *  @anchor ti_drivers_Button_Synopsis
 *  # Synopsis #
 *
 *  @code
 *  #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);
 *      }
 *      ...
 *  }
 *  @endcode
 *
 *  @anchor ti_drivers_Button_Examples
 *  ## Examples #
 *
 *  * @ref ti_drivers_Button_Examples_config "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 @ref 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.
 *
 *  @anchor ti_drivers_Button_Examples_config
 *
 *  "ti_drivers_config.h"
 *  @code
 *  #define CONFIG_BUTTON_0     0  //Button number 1
 *  #define CONFIG_BUTTON_1     1  //Button number 2
 *  @endcode
 *
 *  "ti_drivers_config.c"
 *  @code
 *  #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],
 *      },
 *  };
 *  @endcode
 *
 *  ##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 @ref GPIO.h.
 *
 *  "ti_drivers_config.h"
 *  @code
 *  #define CONFIG_S1       0
 *  #define CONFIG_S2       1
 *  @endcode
 *
 *  "ti_drivers_config.c"
 *  @code
 *  #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,
 *  }
 *
 *  @endcode
 ******************************************************************************
 */
#ifndef ti_drivers_Button__include
#define ti_drivers_Button__include

#include <stdint.h>
#include <stdbool.h>

/* Driver Header files */
#include <ti/drivers/GPIO.h>
#include <ti/drivers/dpl/ClockP.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Number of user defined Button configurations */
extern const uint_least8_t Button_count;

typedef struct Button_Config
{
    void *object;

    void const *hwAttrs;
}Button_Config;

typedef struct Button_Config* Button_Handle;

typedef enum Button_State
{
    Button_PRESSING                     = 1,
    Button_PRESSED                      = 2,
    Button_LONGPRESSING                 = 3,
    Button_LONGPRESSED                  = 4,
    Button_RELEASING                    = 5,
    Button_RELEASING_LONG               = 6,
    Button_RELEASED                     = 7,
    Button_DBLPRESS_DETECTION           = 8,
    Button_DBLPRESSING                  = 9,
    Button_DBLPRESSED                   = 10,
    Button_RELEASING_DBLPRESSED         = 11
} Button_State;

typedef 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_Events;

typedef uint8_t Button_EventMask;

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

typedef enum Button_Pull
{
    /* NOTE: DO NOT change the values of DOWN/UP from (0,1) */
    Button_PULL_DOWN   = 0,     
    Button_PULL_UP     = 1,     
    Button_PULL_NOTSET = 2      
} Button_Pull;

typedef struct Button_HWAttrs
{
    uint_least8_t gpioIndex;    
} Button_HWAttrs;

typedef struct Button_StateVariables
{
    Button_State   state;
    uint32_t       pressedStartTime;
    uint32_t       lastPressedDuration;
}Button_StateVariables;

typedef struct Button_Object
{
    ClockP_Handle          clockHandle;

    Button_StateVariables  buttonStateVariables;

    Button_EventMask       buttonEventMask;

    Button_Callback        buttonCallback;

    uint32_t               debounceDuration;

    uint32_t               longPressDuration;

    uint32_t               doublePressDetectiontimeout;

    Button_Pull            buttonPull;
} Button_Object;

typedef struct Button_Params
{
    uint32_t        debounceDuration;

    uint32_t        longPressDuration;

    uint32_t        doublePressDetectiontimeout;

    Button_EventMask    buttonEventMask;
} Button_Params;

extern bool Button_close(Button_Handle handle);

extern void Button_init();

extern Button_Handle Button_open(uint_least8_t buttonIndex,
                                 Button_Callback buttonCallback,
                                 Button_Params *params);

extern void Button_Params_init(Button_Params *params);

extern uint32_t Button_getLastPressedDuration(Button_Handle handle);

extern void Button_setCallback(Button_Handle handle,
                               Button_Callback buttonCallback);

void Button_gpioCallbackFxn(uint_least8_t index);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_Button__include */