LwBTN

group LWBTN

Lightweight button manager.

Defines

lwbtn_init(btns, btns_cnt, get_state_fn, evt_fn) lwbtn_init_ex(NULL, btns, btns_cnt, get_state_fn, evt_fn)

Initialize LwBTN library with buttons on default button group.

See also

lwbtn_init_ex

Parameters

btns – [in] Array of buttons to process
btns_cnt – [in] Number of buttons to process
get_state_fn – [in] Pointer to function providing button state on demand. Can be set to NULL if LWBTN_CFG_GET_STATE_MODE is NOT set to LWBTN_GET_STATE_MODE_CALLBACK
evt_fn – [in] Button event function callback

lwbtn_process(mstime) lwbtn_process_ex(NULL, mstime)

Periodically read button states and take appropriate actions. It processes the default buttons instance group.

See also

lwbtn_process_ex

Parameters

mstime – [in] Current system time in milliseconds

lwbtn_process_btn(btn, mstime) lwbtn_process_btn_ex(NULL, (btn), (mstime))

Process specific button in a default LwBTN instance.

Parameters

btn – [in] Button instance to process
mstime – [in] Current system time in milliseconds

lwbtn_keepalive_get_count_for_time(btn, ms_time) ((ms_time) / lwbtn_keepalive_get_period(btn))

Get number of keep alive counts for specific required time in milliseconds. It will calculate number of keepalive ticks specific button shall make, before requested time is reached.

Result of the function can be used with lwbtn_keepalive_get_count which returns actual number of keep alive counts since last on-press event of the button.

See also

lwbtn_keepalive_get_count

Note

Available only when LWBTN_CFG_USE_KEEPALIVE feature is enabled

Note

Value is always integer aligned, with granularity of one keepalive time period

Note

Implemented as macro to avoid the function-call overhead for a simple derived calculation

Parameters

btn – [in] Button to use for check
ms_time – [in] Time in ms to calculate number of keep alive counts

Returns

Number of keep alive counts

Typedefs

typedef LWBTN_CFG_TIME_VARTYPE lwbtn_time_t: Time variable type.

typedef void (*lwbtn_evt_fn)(struct lwbtn *lwobj, struct lwbtn_btn *btn, lwbtn_evt_t evt)

Button event function callback prototype.

Param lwobj: [in] LwBTN instance
Param btn: [in] Button instance from array for which event occurred
Param evt: [in] Event type

typedef uint8_t (*lwbtn_get_state_fn)(struct lwbtn *lwobj, struct lwbtn_btn *btn)

Get button/input state callback function.

Param lwobj: [in] LwBTN instance
Param btn: [in] Button instance from array to read state
Return: 1 when button is considered active, 0 otherwise

Enums

enum lwbtn_evt_t

List of button events.

Values:

enumerator LWBTN_EVT_ONPRESS = 0x00: On press event - sent when valid press is detected (after debounce if enabled)

enumerator LWBTN_EVT_ONRELEASE: On release event - sent when valid release event is detected (from active to inactive)

enumerator LWBTN_EVT_ONCLICK: On Click event - sent when valid sequence of on-press and on-release events occurs

enumerator LWBTN_EVT_KEEPALIVE: Keep alive event - sent periodically when button is active

Functions

uint8_t lwbtn_init_ex(lwbtn_t *lwobj, lwbtn_btn_t *btns, uint16_t btns_cnt, lwbtn_get_state_fn get_state_fn, lwbtn_evt_fn evt_fn)

Initialize button manager.

Parameters

lwobj – [in] LwBTN instance. Set to NULL to use default one
btns – [in] Array of buttons to process
btns_cnt – [in] Number of buttons to process
get_state_fn – [in] Pointer to function providing button state on demand. May be set to NULL when LWBTN_CFG_GET_STATE_MODE is set to manual.
evt_fn – [in] Button event function callback

Returns

1 on success, 0 otherwise

uint8_t lwbtn_process_ex(lwbtn_t *lwobj, lwbtn_time_t mstime)

Button processing function, that reads the inputs and makes actions accordingly.

             It checks state of all the buttons, linked to the specific LwBTN instance (group).

Parameters

lwobj – [in] LwBTN instance. Set to NULL to use default one
mstime – [in] Current system time in milliseconds

Returns

1 on success, 0 otherwise

uint8_t lwbtn_process_btn_ex(lwbtn_t *lwobj, lwbtn_btn_t *btn, lwbtn_time_t mstime)

Process single button instance from the specific LwOBJ instance (group).

             This feature can be used if application wants to process the button events only
             when interrupt hits (as a trigger). It gives user higher autonomy to decide which 
             and when it will call specific button processing.

Parameters

lwobj – [in] LwBTN instance. Set to NULL to use default one
btn – [in] Button object. Must not be set to NULL
mstime – [in] Current system time in milliseconds

Returns

1 on success, 0 otherwise

uint8_t lwbtn_reset(lwbtn_t *lwobj, lwbtn_btn_t *btn)

Reset button[s] state to default.

             When reset is called, and if button is pressed (active),
             no further events will be called up until we receive
             the new valid press action.

             A typical use case would be when application needs to react
             on a long press (several keep alive events).

             Consider the use case where user runs the GUI and long press changes the screen.
             The new screen has its own button handling method, which performs some other action (eg. "go home" action).

             Calling the reset function will prevent new screen to continue receiving the events
             and forces the user to release the button and press it again.

Note

If button is reset during active time, there will be no further events for this button sent to the application, up until a new valid on-press is detected

Parameters

lwobj – Object to reset buttons. Set to non-NULL to reset all buttons in an object
btn – Button object to reset. Optional parameter. When non-NULL, button is reset

Returns

1 on success, 0 otherwise

uint8_t lwbtn_is_btn_active(const lwbtn_btn_t *btn)

Check if button is active.

             Active is considered when initial debounce period has been a pass.
             This is the period between on-press and on-release events.

Parameters: btn – [in] Button handle to check
Returns: 1 if active, 0 otherwise

uint8_t lwbtn_set_btn_state(lwbtn_btn_t *btn, uint8_t state)

Set button state to either “active” or “inactive”.

Note

Available only when LWBTN_CFG_GET_STATE_MODE is NOT set to LWBTN_GET_STATE_MODE_CALLBACK, which implies that user can use callback or direct (dynamic configuration) state set

Parameters

btn – [in] Button instance
state – [in] New button state. 1 is for active (pressed), 0 is for inactive (released).

Returns

1 on success, 0 otherwise

lwbtn_time_t lwbtn_debounce_get_press_time(const lwbtn_btn_t *btn)

Get debounce time for on-press detection, for specific button. This is the time in milliseconds to wait for a stable state after the button is pressed, before the on-press event is sent to the application.

Parameters: btn – [in] Button instance to get debounce press time for
Returns: Debounce press time in ms

lwbtn_time_t lwbtn_debounce_get_release_time(const lwbtn_btn_t *btn)

Get debounce time for on-release detection, for specific button. This is the time in milliseconds to wait for a stable state after the button is released, before the on-release event is sent to the application.

Parameters: btn – [in] Button instance to get debounce release time for
Returns: Debounce release time in ms

uint8_t lwbtn_debounce_set_press_time(lwbtn_btn_t *btn, lwbtn_time_t time)

Set debounce time for on-press detection, for specific button.

Note

Available only when LWBTN_CFG_TIME_DEBOUNCE_PRESS_DYNAMIC feature is enabled

Parameters

btn – [in] Button instance to set debounce press time for
time – [in] New debounce press time in ms

Returns

1 on success, 0 otherwise

uint8_t lwbtn_debounce_set_release_time(lwbtn_btn_t *btn, lwbtn_time_t time)

Set debounce time for on-release detection, for specific button.

Note

Available only when LWBTN_CFG_TIME_DEBOUNCE_RELEASE_DYNAMIC feature is enabled

Parameters

btn – [in] Button instance to set debounce release time for
time – [in] New debounce release time in ms

Returns

1 on success, 0 otherwise

lwbtn_time_t lwbtn_click_get_time_min(const lwbtn_btn_t *btn)

Get minimum pressed time for valid click event, for specific button.

Note

Available only when LWBTN_CFG_USE_CLICK feature is enabled

Parameters: btn – [in] Button instance to get minimum click time for
Returns: Minimum click time in ms

lwbtn_time_t lwbtn_click_get_time_max(const lwbtn_btn_t *btn)

Get maximum pressed time for valid click event, for specific button.

Note

Available only when LWBTN_CFG_USE_CLICK feature is enabled

Parameters: btn – [in] Button instance to get maximum click time for
Returns: Maximum click time in ms

lwbtn_time_t lwbtn_click_get_time_multi_max(const lwbtn_btn_t *btn)

Get maximum time between 2 clicks to be considered consecutive, for specific button.

Note

Available only when LWBTN_CFG_USE_CLICK feature is enabled

Parameters: btn – [in] Button instance to get maximum multi-click time for
Returns: Maximum multi-click time in ms

uint8_t lwbtn_click_get_max_consecutive(const lwbtn_btn_t *btn)

Get max number of consecutive clicks, for specific button.

Note

Available only when LWBTN_CFG_USE_CLICK feature is enabled

Parameters: btn – [in] Button instance to get max number of consecutive clicks for
Returns: Max number of consecutive clicks

uint8_t lwbtn_click_set_time_min(lwbtn_btn_t *btn, lwbtn_time_t time)

Set minimum pressed time for valid click event, for specific button.

Note

Available only when LWBTN_CFG_USE_CLICK and LWBTN_CFG_TIME_CLICK_MIN_DYNAMIC are both enabled

Parameters

btn – [in] Button instance to set minimum click time for
time – [in] New minimum click time in ms

Returns

1 on success, 0 otherwise

uint8_t lwbtn_click_set_time_max(lwbtn_btn_t *btn, lwbtn_time_t time)

Set maximum pressed time for valid click event, for specific button.

Note

Available only when LWBTN_CFG_USE_CLICK and LWBTN_CFG_TIME_CLICK_MAX_DYNAMIC are both enabled

Parameters

btn – [in] Button instance to set maximum click time for
time – [in] New maximum click time in ms

Returns

1 on success, 0 otherwise

uint8_t lwbtn_click_set_time_multi_max(lwbtn_btn_t *btn, lwbtn_time_t time)

Set maximum time between 2 clicks to be considered consecutive, for specific button.

Note

Available only when LWBTN_CFG_USE_CLICK and LWBTN_CFG_TIME_CLICK_MULTI_MAX_DYNAMIC are both enabled

Parameters

btn – [in] Button instance to set maximum multi-click time for
time – [in] New maximum multi-click time in ms

Returns

1 on success, 0 otherwise

uint8_t lwbtn_click_set_max_consecutive(lwbtn_btn_t *btn, uint8_t max)

Set max number of consecutive clicks, for specific button.

Note

Available only when LWBTN_CFG_USE_CLICK and LWBTN_CFG_CLICK_MAX_CONSECUTIVE_DYNAMIC are both enabled

Parameters

btn – [in] Button instance to set max number of consecutive clicks for
max – [in] New max number of consecutive clicks

Returns

1 on success, 0 otherwise

uint8_t lwbtn_click_get_count(const lwbtn_btn_t *btn)

Get number of consecutive click events on a button since the last events.

             This function is useful in the application callback event function.

Note

Available only when LWBTN_CFG_USE_CLICK feature is enabled

Parameters: btn – [in] Button instance to get number of clicks
Returns: Number of consecutive clicks on a button

lwbtn_time_t lwbtn_keepalive_get_period(const lwbtn_btn_t *btn)

Get keep alive period for specific button.

Note

Available only when LWBTN_CFG_USE_KEEPALIVE feature is enabled

Parameters: btn – [in] Button instance to get keep alive period for
Returns: Keep alive period in ms

uint8_t lwbtn_keepalive_set_period(lwbtn_btn_t *btn, lwbtn_time_t period)

Set keep alive period for specific button.

Note

Available only when LWBTN_CFG_USE_KEEPALIVE and LWBTN_CFG_TIME_KEEPALIVE_PERIOD_DYNAMIC are both enabled

Parameters

btn – [in] Button instance to set keep alive period for
period – [in] New keep alive period in ms. Set to 0 to disable the keep alive for specific button

Returns

1 on success, 0 otherwise

uint16_t lwbtn_keepalive_get_count(const lwbtn_btn_t *btn)

Get actual number of keep alive counts since the last on-press event. It is set to 0 if btn isn’t pressed.

This function is useful in the application callback event function.

See also

lwbtn_keepalive_get_count_for_time

Note

Available only when LWBTN_CFG_USE_KEEPALIVE feature is enabled

Parameters: btn – [in] Button instance to get keep alive count for
Returns: Number of keep alive events since on-press event

struct lwbtn_argdata_port_pin_state_t

#include <lwbtn.h>

Custom user argument data structure.

This is a simple pre-defined structure, that can be used by user to define most commonly required feature in embedded systems, that being GPIO port, GPIO pin and state when button is considered active.

User can later attach this structure as argument to button structure

Public Members

void *port: User defined GPIO port information

void *pin: User defined GPIO pin information

uint8_t state: User defined GPIO state level when considered active

struct lwbtn_btn_t

#include <lwbtn.h>

Button/input structure.

Public Members

uint16_t flags: Private button flags management

uint8_t curr_state: Current button state to be processed. It is used to keep track when application manually sets the button state

uint8_t last_state: Last button state - 1 means active, 0 means inactive

lwbtn_time_t time_change: Time in ms when button state got changed last time after valid debounce

lwbtn_time_t time_state_change: Time in ms when button state got changed last time

lwbtn_time_t last_time

Time in ms of last send keep alive event

Time in ms of last successfully detected (not sent!) click event

uint16_t cnt: Number of keep alive events sent after successful on-press detection. Value is reset after on-release

struct lwbtn_btn_t::[anonymous] keepalive: Keep alive structure

uint8_t cnt: Number of consecutive clicks detected, respecting maximum timeout between clicks

struct lwbtn_btn_t::[anonymous] click: Click event structure

void *arg: User defined custom argument for callback function purpose

lwbtn_time_t time_debounce: Debounce time in milliseconds

lwbtn_time_t time_debounce_release: Debounce time in milliseconds for release event

lwbtn_time_t time_keepalive_period: Time in ms for periodic keep alive event

lwbtn_time_t time_click_pressed_min: Minimum pressed time for valid click event

lwbtn_time_t time_click_pressed_max: Maximum pressed time for valid click event

lwbtn_time_t time_click_multi_max: Maximum time between 2 clicks to be considered consecutive click

uint8_t max_consecutive: Max number of consecutive clicks

struct lwbtn_t

#include <lwbtn.h>

LwBTN group structure.

Public Members

lwbtn_btn_t *btns: Pointer to buttons array

uint16_t btns_cnt: Number of buttons in array

lwbtn_evt_fn evt_fn: Pointer to event function

lwbtn_get_state_fn get_state_fn: Pointer to get state function