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_period(btn) ((btn)->time_keepalive_period)

Get keep alive period for specific button.

Parameters

  • btn – [in] Button instance to get keep alive period for

Returns

Keep alive period in ms

lwbtn_keepalive_get_count(btn) ((btn)->keepalive.cnt)

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

See also

lwbtn_keepalive_get_count_for_time

Parameters

  • btn – [in] Button instance to get keep alive period for

Returns

Number of keep alive events since on-press event

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

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

Note

Implemented as macro, as it may be optimized by compiler when static keep alive is used

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

lwbtn_click_get_count(btn) ((btn)->click.cnt)

Get number of consecutive click events on a button.

Parameters

  • btn – [in] Button instance to get number of clicks

Returns

Number of consecutive clicks on a button

Typedefs

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 occured

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, uint32_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, uint32_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_set_btn_state(lwbtn_btn_t *btn, uint8_t state)

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

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

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

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 old_state

Old button state - 1 means active, 0 means inactive

uint32_t time_change

Time in ms when button state got changed last time after valid debounce

uint32_t time_state_change

Time in ms when button state got changed last time

uint32_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

uint16_t time_debounce

Debounce time in milliseconds

uint16_t time_debounce_release

Debounce time in milliseconds for release event

uint16_t time_click_pressed_min

Minimum pressed time for valid click event

uint16_t time_click_pressed_max

Maximum pressed time for valid click event

uint16_t time_click_multi_max

Maximum time between 2 clicks to be considered consecutive click

uint16_t time_keepalive_period

Time in ms for periodic keep alive event

uint16_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