Button

Description

Handle generic GPIO buttons.

<rc/button.h>

Functions for assigning button callback functions. This is based on the GPIO character device driver instead of the gpio-keys driver which means it can be used with any GPIO pin.

Author

James Strawson

Date

3/7/2018

Macros
#define	RC_BTN_PIN_PAUSE   2,5
#define	RC_BTN_PIN_MODE   2,4
#define	RC_BTN_STATE_PRESSED   1
#define	RC_BTN_STATE_RELEASED   0
#define	RC_BTN_POLARITY_NORM_HIGH   1
#define	RC_BTN_POLARITY_NORM_LOW   0
#define	RC_BTN_DEBOUNCE_DEFAULT_US   2000

Functions
int	rc_button_init (int chip, int pin, char polarity, int debounce_us)
	Initializes a single button handler. More...
void	rc_button_cleanup (void)
	Closes all button handlers. Call at the end of your program before returning. More...
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. More...
int	rc_button_get_state (int chip, int pin)
	used to query the position of a button. More...
int	rc_button_wait_for_event (int chip, int pin, int press_or_release)
	blocking function call, returns when press or release happens More...

Macro Definition Documentation

RC_BTN_PIN_PAUSE

#define RC_BTN_PIN_PAUSE   2,5

Examples:

rc_balance.c, rc_blink.c, and rc_test_buttons.c.

RC_BTN_PIN_MODE

#define RC_BTN_PIN_MODE   2,4

Examples:

rc_balance.c, rc_blink.c, and rc_test_buttons.c.

RC_BTN_STATE_PRESSED

#define RC_BTN_STATE_PRESSED   1

RC_BTN_STATE_RELEASED

#define RC_BTN_STATE_RELEASED   0

Examples:

rc_balance.c, and rc_blink.c.

RC_BTN_POLARITY_NORM_HIGH

#define RC_BTN_POLARITY_NORM_HIGH   1

Examples:

rc_balance.c, rc_blink.c, and rc_test_buttons.c.

RC_BTN_POLARITY_NORM_LOW

#define RC_BTN_POLARITY_NORM_LOW   0

RC_BTN_DEBOUNCE_DEFAULT_US

#define RC_BTN_DEBOUNCE_DEFAULT_US   2000

Examples:

rc_balance.c, rc_blink.c, and rc_test_buttons.c.

Function Documentation

rc_button_init()

int rc_button_init	(	int	chip,
		int	pin,
		char	polarity,
		int	debounce_us
	)

Initializes a single button handler.

Parameters

[in]	chip	The gpio chip
[in]	pin	The gpio pin for that chip
[in]	polarity	RC_BTN_POLARITY_NORM_HIGH if using with a pullup resistor, use this for the BeagleBone Blue and Robotics Cape MODE and PAUSE buttons. Alternatively use RC_BTN_POLARITY_NORM_LOW if you are using your own button on another pin set up with a pulldown resistor.
[in]	debounce_us	debounce interval in microseconds. Set to 0 for no debounce. Usually should set to RC_BTN_DEBOUNCE_DEFAULT_US.

Returns

0 on success, -1 on failure

Examples:

rc_balance.c, rc_blink.c, and rc_test_buttons.c.

rc_button_cleanup()

void rc_button_cleanup

(

void

)

Closes all button handlers. Call at the end of your program before returning.

Examples:

rc_balance.c, rc_blink.c, and rc_test_buttons.c.

rc_button_set_callbacks()

int rc_button_set_callbacks	(	int	chip,
		int	pin,
		void(*)(void)	press_func,
		void(*)(void)	release_func
	)

Sets the callback functions to be called when the button is pressed or released.

These functions should be short and return quickly. On every press and release a new thread is created to run your callback functions. If your callbacks take too long to return then multiple instances of them will run in parallel which may or may not be desirable.

Parameters

[in]	chip	The gpio chip
[in]	pin	The gpio pin for that chip
[in]	press_func	callback when button is pressed, set to NULL if no callback is desired.
[in]	release_func	callback when button is released, set to NULL if no callback is desired.

Returns

0 on success, -1 on failure.

Examples:

rc_balance.c, rc_blink.c, and rc_test_buttons.c.

rc_button_get_state()

int rc_button_get_state	(	int	chip,
		int	pin
	)

used to query the position of a button.

Parameters

[in]	chip	The gpio chip
[in]	pin	The gpio pin for that chip

Returns

RC_BTN_STATE_PRESSED or RC_BTN_STATE_RELEASED on success, -1 on failure.

Examples:

rc_balance.c, and rc_blink.c.

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

Parameters

[in]	chip	The gpio chip
[in]	pin	The gpio pin for that chip
[in]	press_or_release	RC_BTN_STATE_PRESSED or RC_BTN_STATE_RELEASED

Returns

0 on successful event, -1 on error