Contiki-NG

Hardware abstraction layer for user buttons. More...

Files

file  button-hal.c
 Platform-independent button driver.
 
file  button-hal.h
 Header file for the button HAL.
 

Macros

#define BUTTON_HAL_DEBOUNCE_DURATION   (CLOCK_SECOND >> 6)
 Controls the software debounce timer duration. More...
 
#define BUTTON_HAL_WITH_DESCRIPTION   1
 Controls whether buttons will have human-readable names. More...
 
#define BUTTON_HAL_PORT_COUNT   1
 Number of different ports that buttons are connected to. More...
 
#define BUTTON_HAL_ID_BUTTON_ZERO   0x00
 Optional button IDs.
 
#define BUTTON_HAL_GET_DESCRIPTION(b)   (b)->description
 Retrieve the textual description of a button. More...
 

Typedefs

typedef struct button_hal_button_s button_hal_button_t
 A logical representation of a user button.
 

Functions

button_hal_button_tbutton_hal_get_by_id (uint8_t unique_id)
 Retrieve a button by ID. More...
 
button_hal_button_tbutton_hal_get_by_index (uint8_t index)
 Retrieve a button by its index. More...
 
uint8_t button_hal_get_state (button_hal_button_t *button)
 Get the state of a button (pressed / released) More...
 
void button_hal_init (void)
 Initialise the button HAL.
 

Variables

process_event_t button_hal_press_event
 A broadcast event generated when a button gets pressed.
 
process_event_t button_hal_release_event
 A broadcast event generated when a button gets released.
 
process_event_t button_hal_periodic_event
 A broadcast event generated every second while a button is kept pressed.
 
const uint8_t button_hal_button_count
 The number of buttons on a device.
 
process_event_t button_hal_press_event
 A broadcast event generated when a button gets pressed.
 
process_event_t button_hal_release_event
 A broadcast event generated when a button gets released.
 
process_event_t button_hal_periodic_event
 A broadcast event generated every second while a button is kept pressed.
 

Detailed Description

Hardware abstraction layer for user buttons.

This HAL enables an abstraction of general-purpose / user buttons or similar peripherals (e.g. a reed relay can also be abstracted through this HAL). The HAL handles software debounce timers internally, therefore the platform-specific button driver does not need to worry about debouncing.

The platform developer needs to define a variable of type button_hal_button_t for each user button. Within this variable, the developer needs to specify the GPIO pin where the button is attached, whether the button uses negative logic, and whether the GPIO pin should be configured with internal pullup/down. The developer also needs to provide a unique index for each button, as well as a description.

With those in place, the HAL will generate the following process events:

With those events in place, an application can perform an action:

A platform with user buttons can either implement this API (recommended) or the older button_sensor API. Some examples will not work if this API is not implemented.

This API requires the platform to first support the GPIO HAL API.

Macro Definition Documentation

◆ BUTTON_HAL_DEBOUNCE_DURATION

#define BUTTON_HAL_DEBOUNCE_DURATION   (CLOCK_SECOND >> 6)

Controls the software debounce timer duration.

The platform can provide a more suitable value. This value will apply to all buttons.

Definition at line 100 of file button-hal.h.

◆ BUTTON_HAL_GET_DESCRIPTION

#define BUTTON_HAL_GET_DESCRIPTION (   b)    (b)->description

Retrieve the textual description of a button.

Parameters
bA pointer to the button button_hal_button_t

This macro will return the value of the description field for b. If BUTTON_HAL_WITH_DESCRIPTION is 0 then this macro will return ""

Definition at line 231 of file button-hal.h.

◆ BUTTON_HAL_PORT_COUNT

#define BUTTON_HAL_PORT_COUNT   1

Number of different ports that buttons are connected to.

For example, if our PCB has 3 buttons conncted to pins P0.1, P0,6 and P2.3 then the platform configuration should define this to value 2 (one for each of ports 0 and 2)

Definition at line 124 of file button-hal.h.

◆ BUTTON_HAL_WITH_DESCRIPTION

#define BUTTON_HAL_WITH_DESCRIPTION   1

Controls whether buttons will have human-readable names.

Define this to zero to save code space

Definition at line 111 of file button-hal.h.

Function Documentation

◆ button_hal_get_by_id()

button_hal_button_t * button_hal_get_by_id ( uint8_t  unique_id)

Retrieve a button by ID.

Parameters
unique_idThe button unique ID to search for
Returns
A pointer to the button or NULL if not found

Definition at line 176 of file button-hal.c.

◆ button_hal_get_by_index()

button_hal_button_t * button_hal_get_by_index ( uint8_t  index)

Retrieve a button by its index.

Parameters
indexThe button's index (0, 1, ... button_hal_button_count - 1)
Returns
A pointer to the button or NULL if not found

Definition at line 190 of file button-hal.c.

References button_hal_button_count.

◆ button_hal_get_state()

uint8_t button_hal_get_state ( button_hal_button_t button)

Get the state of a button (pressed / released)

Parameters
buttonA pointer to the button
Return values
BUTTON_HAL_STATE_RELEASEDThe button is currently released
BUTTON_HAL_STATE_PRESSEDThe button is currently pressed

Definition at line 200 of file button-hal.c.