app_button.h

00001 /* Copyright (c) 2012 Nordic Semiconductor. All Rights Reserved.
00002  *
00003  * The information contained herein is property of Nordic Semiconductor ASA.
00004  * Terms and conditions of usage are described in detail in NORDIC
00005  * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
00006  *
00007  * Licensees are granted free, non-transferable use of the information. NO
00008  * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
00009  * the file.
00010  *
00011  */
00012 
00013 /** @file
00014  *
00015  * @defgroup app_button Button Handler
00016  * @{
00017  * @ingroup app_common
00018  *
00019  * @brief Buttons handling module.
00020  *
00021  * @details The button handler uses the @ref app_gpiote to detect that a button has been
00022  *          pushed. To handle debouncing, it will start a timer in the GPIOTE event handler.
00023  *          The button will only be reported as pushed if the corresponding pin is still active when
00024  *          the timer expires. If there is a new GPIOTE event while the timer is running, the timer
00025  *          is restarted.
00026  *          Use the USE_SCHEDULER parameter of the APP_BUTTON_INIT() macro to select if the
00027  *          @ref app_scheduler is to be used or not.
00028  *
00029  * @note    The app_button module uses the app_timer module. The user must ensure that the queue in
00030  *          app_timer is large enough to hold the app_timer_stop() / app_timer_start() operations
00031  *          which will be executed on each event from GPIOTE module (2 operations), as well as other
00032  *          app_timer operations queued simultaneously in the application.
00033  *
00034  * @note    Even if the scheduler is not used, app_button.h will include app_scheduler.h, so when
00035  *          compiling, app_scheduler.h must be available in one of the compiler include paths.
00036  */
00037 
00038 #ifndef APP_BUTTON_H__
00039 #define APP_BUTTON_H__
00040 
00041 #include <stdint.h>
00042 #include <stdbool.h>
00043 #include "nrf.h"
00044 #include "app_error.h "
00045 #include "app_scheduler.h "
00046 #include "nrf_gpio.h"
00047 
00048 #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). */
00049 #define APP_BUTTON_PUSH        1                               /**< Indicates that a button is pushed. */
00050 #define APP_BUTTON_RELEASE     0                               /**< Indicates that a button is released. */
00051 #define APP_BUTTON_ACTIVE_HIGH 1                               /**< Indicates that a button is active high. */
00052 #define APP_BUTTON_ACTIVE_LOW  0                               /**< Indicates that a button is active low. */
00053 
00054 /**@brief Button event handler type. */
00055 typedef void (*app_button_handler_t)(uint8_t pin_no, uint8_t button_action);
00056 
00057 /**@brief Type of function for passing events from the Button Handler module to the scheduler. */
00058 typedef uint32_t (*app_button_evt_schedule_func_t) (app_button_handler_t button_handler,
00059                                                     uint8_t              pin_no,
00060                                                     uint8_t              button_action);
00061 
00062 /**@brief Button configuration structure. */
00063 typedef struct
00064 {
00065     uint8_t              pin_no;           /**< Pin to be used as a button. */
00066     uint8_t              active_state;     /**< APP_BUTTON_ACTIVE_HIGH or APP_BUTTON_ACTIVE_LOW. */
00067     nrf_gpio_pin_pull_t  pull_cfg;         /**< Pull-up or -down configuration. */
00068     app_button_handler_t button_handler;   /**< Handler to be called when button is pushed. */
00069 } app_button_cfg_t;
00070 
00071 /**@brief  Pin transition direction struct. */
00072 typedef struct
00073 {
00074     uint32_t high_to_low;   /**Pin went from high to low */
00075     uint32_t low_to_high;   /**Pin went from low to high */
00076 } pin_transition_t;
00077 
00078 /**@brief Macro for initializing the Button Handler module.
00079  *
00080  * @details It will initialize the specified pins as buttons, and configure the Button Handler
00081  *          module as a GPIOTE user (but it will not enable button detection). It will also connect
00082  *          the Button Handler module to the scheduler (if specified).
00083  *
00084  * @param[in]  BUTTONS           Array of buttons to be used (type app_button_cfg_t, must be
00085  *                               static!).
00086  * @param[in]  BUTTON_COUNT      Number of buttons.
00087  * @param[in]  DETECTION_DELAY   Delay from a GPIOTE event until a button is reported as pushed.
00088  * @param[in]  USE_SCHEDULER     TRUE if the application is using the event scheduler,
00089  *                               FALSE otherwise.
00090  */
00091 /*lint -emacro(506, APP_BUTTON_INIT) */ /* Suppress "Constant value Boolean */
00092 #define APP_BUTTON_INIT(BUTTONS, BUTTON_COUNT, DETECTION_DELAY, USE_SCHEDULER)                     \
00093     do                                                                                             \
00094     {                                                                                              \
00095         uint32_t ERR_CODE = app_button_init((BUTTONS),                                             \
00096                                             (BUTTON_COUNT),                                        \
00097                                             (DETECTION_DELAY),                                     \
00098                                             (USE_SCHEDULER) ? app_button_evt_schedule : NULL);     \
00099         APP_ERROR_CHECK(ERR_CODE);                                                                 \
00100     } while (0)
00101     
00102 /**@brief Function for initializing the Buttons.
00103  *
00104  * @details This function will initialize the specified pins as buttons, and configure the Button
00105  *          Handler module as a GPIOTE user (but it will not enable button detection).
00106  *
00107  * @note Normally initialization should be done using the APP_BUTTON_INIT() macro, as that will take
00108  *       care of connecting the Buttons module to the scheduler (if specified).
00109  *
00110  * @note app_button_enable() function must be called in order to enable the button detection.    
00111  *
00112  * @param[in]  p_buttons           Array of buttons to be used (NOTE: Must be static!).
00113  * @param[in]  button_count        Number of buttons.
00114  * @param[in]  detection_delay     Delay from a GPIOTE event until a button is reported as pushed.
00115  * @param[in]  evt_schedule_func   Function for passing button events to the scheduler. Point to
00116  *                                 app_button_evt_schedule() to connect to the scheduler. Set to
00117  *                                 NULL to make the Buttons module call the event handler directly
00118  *                                 from the delayed button push detection timeout handler.
00119  *
00120  * @return   NRF_SUCCESS on success, otherwise an error code.
00121  */
00122 uint32_t app_button_init(app_button_cfg_t *             p_buttons,
00123                          uint8_t                        button_count,
00124                          uint32_t                       detection_delay,
00125                          app_button_evt_schedule_func_t evt_schedule_func);
00126 
00127 /**@brief Function for enabling button detection.
00128  *
00129  * @retval  NRF_ERROR_INVALID_PARAM   GPIOTE has to many users.
00130  * @retval  NRF_ERROR_INVALID_STATE   Button or GPIOTE not initialized.
00131  * @retval  NRF_SUCCESS               Button detection successfully enabled.
00132  */
00133 uint32_t app_button_enable(void);
00134 
00135 /**@brief Function for disabling button detection.
00136  *
00137  * @retval  NRF_ERROR_INVALID_PARAM   GPIOTE has to many users.
00138  * @retval  NRF_ERROR_INVALID_STATE   Button or GPIOTE not initialized.
00139  * @retval  NRF_SUCCESS               Button detection successfully enabled.
00140  */
00141 uint32_t app_button_disable(void);
00142 
00143 /**@brief Function for checking if a button is currently being pushed.
00144  *
00145  * @param[in]  button_id     Button index (in the app_button_cfg_t array given to app_button_init) to be checked.
00146  * @param[out] p_is_pushed   Button state.
00147  *
00148  * @retval     NRF_SUCCESS               State successfully read.
00149  * @retval     NRF_ERROR_INVALID_PARAM   Invalid button index.
00150  */
00151 uint32_t app_button_is_pushed(uint8_t button_id, bool * p_is_pushed);
00152 
00153 
00154 // Type and functions for connecting the Buttons module to the scheduler:
00155 
00156 /**@cond NO_DOXYGEN */
00157 typedef struct
00158 {
00159     app_button_handler_t button_handler;
00160     uint8_t              pin_no;
00161     uint8_t              button_action;
00162 } app_button_event_t;
00163 
00164 static __INLINE void app_button_evt_get(void * p_event_data, uint16_t event_size)
00165 {
00166     app_button_event_t * p_buttons_event = (app_button_event_t *)p_event_data;
00167     
00168     APP_ERROR_CHECK_BOOL(event_size == sizeof(app_button_event_t));
00169     p_buttons_event->button_handler(p_buttons_event->pin_no, p_buttons_event->button_action);
00170 }
00171 
00172 static __INLINE uint32_t app_button_evt_schedule(app_button_handler_t button_handler,
00173                                                  uint8_t              pin_no,
00174                                                  uint8_t              button_action)
00175 {
00176     app_button_event_t buttons_event;
00177     
00178     buttons_event.button_handler = button_handler;
00179     buttons_event.pin_no         = pin_no;
00180     buttons_event.button_action  = button_action;
00181     
00182     return app_sched_event_put(&buttons_event, sizeof(buttons_event), app_button_evt_get);
00183 }
00184 /**@endcond */
00185 
00186 #endif // APP_BUTTON_H__
00187 
00188 /** @} */