Robot Control Library
button.h
Go to the documentation of this file.
1/**
2 * <rc/button.h>
3 *
4 * @brief Handle generic GPIO buttons.
5 *
6 * Functions for assigning button callback functions. This is based on the GPIO
7 * character device driver instead of the gpio-keys driver which means it can be
8 * used with any GPIO pin.
9 *
10 * @author James Strawson
11 * @date 3/7/2018
12 *
13 * @addtogroup Button
14 * @{
15 */
16
17
18#ifndef RC_BUTTON_H
19#define RC_BUTTON_H
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25
26#define RC_BTN_PIN_PAUSE 2,5 //gpio2.5 P8.9
27#define RC_BTN_PIN_MODE 2,4 //gpio2.4 P8.10
28
29#define RC_BTN_STATE_PRESSED 1
30#define RC_BTN_STATE_RELEASED 0
31
32#define RC_BTN_POLARITY_NORM_HIGH 1
33#define RC_BTN_POLARITY_NORM_LOW 0
34
35#define RC_BTN_DEBOUNCE_DEFAULT_US 2000
36
37/**
38 * @brief Initializes a single button handler.
39 *
40 * @param[in] chip The gpio chip
41 * @param[in] pin The gpio pin for that chip
42 * @param[in] polarity RC_BTN_POLARITY_NORM_HIGH if using with a pullup
43 * resistor, use this for the BeagleBone Blue and Robotics Cape MODE and PAUSE
44 * buttons. Alternatively use RC_BTN_POLARITY_NORM_LOW if you are using your own
45 * button on another pin set up with a pulldown resistor.
46 * @param[in] debounce_us debounce interval in microseconds. Set to 0 for no
47 * debounce. Usually should set to RC_BTN_DEBOUNCE_DEFAULT_US.
48 *
49 * @return 0 on success, -1 on failure
50 */
51int rc_button_init(int chip, int pin, char polarity, int debounce_us);
52
53
54/**
55 * @brief Closes all button handlers. Call at the end of your program
56 * before returning.
57 */
58void rc_button_cleanup(void);
59
60
61/**
62 * @brief Sets the callback functions to be called when the button is
63 * pressed or released.
64 *
65 * These functions should be short and return quickly. On every press and
66 * release a new thread is created to run your callback functions. If your
67 * callbacks take too long to return then multiple instances of them will run in
68 * parallel which may or may not be desirable.
69 *
70 * @param[in] chip The gpio chip
71 * @param[in] pin The gpio pin for that chip
72 * @param[in] press_func callback when button is pressed, set to NULL if no
73 * callback is desired.
74 * @param[in] release_func callback when button is released, set to NULL if no
75 * callback is desired.
76 *
77 * @return 0 on success, -1 on failure.
78 */
79int rc_button_set_callbacks(int chip, int pin, void (*press_func)(void), void (*release_func)(void));
80
81
82/**
83 * @brief used to query the position of a button.
84 *
85 * @param[in] chip The gpio chip
86 * @param[in] pin The gpio pin for that chip
87 *
88 * @return RC_BTN_STATE_PRESSED or RC_BTN_STATE_RELEASED on success, -1 on
89 * failure.
90 */
91int rc_button_get_state(int chip, int pin);
92
93
94/**
95 * @brief blocking function call, returns when press or release happens
96 *
97 * @param[in] chip The gpio chip
98 * @param[in] pin The gpio pin for that chip
99 * @param[in] press_or_release RC_BTN_STATE_PRESSED or RC_BTN_STATE_RELEASED
100 *
101 * @return 0 on successful event, -1 on error
102 */
103int rc_button_wait_for_event(int chip, int pin, int press_or_release);
104
105
106#ifdef __cplusplus
107}
108#endif
109
110#endif // RC_BUTTON_H
111
112/** @} end group Button */
rc_button_get_state
int rc_button_get_state(int chip, int pin)
used to query the position of a button.
rc_button_init
int rc_button_init(int chip, int pin, char polarity, int debounce_us)
Initializes a single button handler.
rc_button_set_callbacks
int rc_button_set_callbacks(int chip, int pin, void(*press_func)(void), void(*release_func)(void))
Sets the callback functions to be called when the button is pressed or released.
rc_button_wait_for_event
int rc_button_wait_for_event(int chip, int pin, int press_or_release)
blocking function call, returns when press or release happens
rc_button_cleanup
void rc_button_cleanup(void)
Closes all button handlers. Call at the end of your program before returning.