button.h
Go to the documentation of this file.
1 #ifndef BUTTON_H
2 #define BUTTON_H
3
4 #include <stdint.h>
5 #include "check.h"
6
7 /**
8 * \addtogroup Button
9 *
10 * \brief Enables event-driven and polling access to the buttons of the SPiCboard
11 *
12 * The SPiCboard is equipped with two buttons. Button 0 is debounced in
13 * hardware, whereas Button 1 needs to be debounced in software by the
14 * button module. Debouncing is transparent to the application, that
15 * can use both buttons through the provided interface without the
16 * need to care about debouncing.
17 *
18 * The debouncing code makes use of a timer. When no callbacks
19 * are registered for Button 1, the debouncing code is disabled and all
20 * alarms registered at the timer should be canceled.
21 *
22 * The button module uses dynamic memory management to maintain the
23 * callback queues.
24 *
25 * @{
26 * \file button.h
27 * \version \$Rev: 7715 $
28 */
29
30 /**
31 * \brief Identifiers for all available buttons
32 */
33 typedef enum {
34 BUTTON0 = 0, /**< Button 0 */
35 BUTTON1 = 1 /**< Button 1 */
36 } __attribute__ ((__packed__)) BUTTON;
37
38 CHECK_ENUM_SIZE(BUTTON, 1)
39
40
41 /**
42 * \brief States for buttons
43 *
44 * Pressed and released states for buttons.
45 */
46 typedef enum {
47 UNKNOWN = 0, /**< Buttonstate is unknown (invalid button?) */
48 PRESSED = 4, /**< Button is pressed */
49 RELEASED = 8 /**< Button is released */
50 } __attribute__ ((__packed__)) BUTTONSTATE;
51
52 CHECK_ENUM_SIZE(BUTTONSTATE, 1)
53
54 /**
55 * \brief Events for buttons
56 *
57 * Down (on press) and up (on release) events for buttons.
58 */
59 typedef enum {
60 ONPRESS = 0, /**< Button is pressed */
61 ONRELEASE = 2 /**< Button is released */
62 } __attribute__ ((__packed__)) BUTTONEVENT;
63
64 CHECK_ENUM_SIZE(BUTTONEVENT, 1)
65
66 /**
67 * \brief Type for button event callback functions
68 *
69 * A button callback function is called on the interrupt level whenever
70 * an event at a button occurs that the function was registered for.
71 * The callback function is passed the button id and the type of event
72 * that occurred. This way, the same callback function can be registered
73 * for different buttons and events.
74 */
75 typedef void (*BUTTONCALLBACK) (BUTTON, BUTTONEVENT);
76
77 /**
78 * \brief Register a callback function for a button event
79 *
80 * Interrupts must be enabled to receive the callbacks.
81 *
82 * \param btn the id of the button
83 * \param eve the type of event that the callback function should be invoked for.
84 * \param callback pointer to the callback function. This function is called from the
85 * interrupt handler.
86 *
87 * \retval 0 success,
88 * \retval !0 error
89 *
90 * \sa sb_button_unregisterCallback
91 */
92 int8_t sb_button_registerCallback(BUTTON btn, BUTTONEVENT eve, BUTTONCALLBACK callback);
93
94 /**
95 * \brief Unregister a callback function for a button event
96 *
97 * \param btn the id of the button
98 * \param eve the type of event that the callback function should be invoked for.
99 * \param callback pointer to the callback function
100 *
101 * \return 0 on success, negative value on error
102 *
103 * \retval 0 success
104 * \retval -1 the callback function was not registered with the given button/event combination
105 *
106 * \sa sb_button_registerCallback
107 */
108 int8_t sb_button_unregisterCallback(BUTTON btn, BUTTONEVENT eve, BUTTONCALLBACK callback);
109
110 /**
111 * \brief Query the current state of a button
112 *
113 * \param btn id of the button
114 *
115 * \return the buttons current state (pressed or released - or unknown if invalid button) as a \ref BUTTONSTATE
116 */
117 BUTTONSTATE sb_button_getState(BUTTON btn);
118
119 /** @}*/
120
121 #endif
122
sb_button_registerCallback
int8_t sb_button_registerCallback(BUTTON btn, BUTTONEVENT eve, BUTTONCALLBACK callback)
Register a callback function for a button event.
CHECK_ENUM_SIZE
#define CHECK_ENUM_SIZE(VAR, LEN)
Definition: check.h:73
check.h
BUTTONEVENT
BUTTONEVENT
Events for buttons.
Definition: button.h:59
BUTTON1
Definition: button.h:35
ONPRESS
Definition: button.h:60
BUTTON
BUTTON
Identifiers for all available buttons.
Definition: button.h:33
sb_button_unregisterCallback
int8_t sb_button_unregisterCallback(BUTTON btn, BUTTONEVENT eve, BUTTONCALLBACK callback)
Unregister a callback function for a button event.
UNKNOWN
Definition: button.h:47
sb_button_getState
BUTTONSTATE sb_button_getState(BUTTON btn)
Query the current state of a button.
BUTTONSTATE
BUTTONSTATE
States for buttons.
Definition: button.h:46
PRESSED
Definition: button.h:48
RELEASED
Definition: button.h:49
BUTTON0
Definition: button.h:34
ONRELEASE
Definition: button.h:61
BUTTONCALLBACK
void(* BUTTONCALLBACK)(BUTTON, BUTTONEVENT)
Type for button event callback functions.
Definition: button.h:75