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
- 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_CALLBACKevt_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
- 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
- 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
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 LWBTN_CFG_TYPE_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 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 consideredactive
,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
-
enumerator LWBTN_EVT_ONPRESS = 0x00
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 onebtns – [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 onemstime – [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 onebtn – [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
-
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
-
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
-
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
-
uint16_t flags
-
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
-
lwbtn_btn_t *btns
-
lwbtn_init(btns, btns_cnt, get_state_fn, evt_fn) lwbtn_init_ex(NULL, btns, btns_cnt, get_state_fn, evt_fn)