File syn_button.h¶

FileList > input > syn_button.h

Debounced button input with press/release/long-press/repeat. More...

#include "../common/syn_defs.h"
#include "../drivers/syn_gpio.h"
#include "../port/syn_port_system.h"
#include "../util/syn_fsm.h"
#include <stdbool.h>

Classes¶

Type	Name
struct	SYN_Button Button descriptor — owns the FSM, debounce, multi-click, and callback state.
struct	SYN_ButtonCombo Combination button descriptor for simultaneous multi-button presses.

Public Types¶

Type	Name
typedef void(*	SYN_ButtonCallback Button event callback.
enum	SYN_ButtonPolarity Button polarity selector.
enum	SYN_ButtonState Button FSM states.

Public Functions¶

Type	Name
void	syn_button_combo_init (SYN_ButtonCombo * combo, const SYN_Button buttons, size_t count, SYN_ButtonCallback** cb, void * ctx) Initialize a combination button descriptor.
void	syn_button_combo_update (SYN_ButtonCombo * combo) Update a combination button descriptor.
void	syn_button_init (SYN_Button * btn, SYN_GPIO_Pin pin, SYN_ButtonPolarity polarity, uint16_t debounce_ms) Initialize a button descriptor.
void	syn_button_on_double_click (SYN_Button * btn, SYN_ButtonCallback cb, void * ctx) Register a double-click callback.
void	syn_button_on_long_press (SYN_Button * btn, SYN_ButtonCallback cb, uint16_t hold_ms, void * ctx) Register a long-press callback.
void	syn_button_on_multi_click (SYN_Button * btn, SYN_ButtonCallback cb, void * ctx) Register a multi-click (4+ taps) callback.
void	syn_button_on_press (SYN_Button * btn, SYN_ButtonCallback cb, void * ctx) Register a press callback.
void	syn_button_on_release (SYN_Button * btn, SYN_ButtonCallback cb, void * ctx) Register a release callback.
void	syn_button_on_repeat (SYN_Button * btn, SYN_ButtonCallback cb, uint16_t interval_ms, void * ctx) Register an auto-repeat callback.
void	syn_button_on_single_click (SYN_Button * btn, SYN_ButtonCallback cb, void * ctx) Register a single-click callback.
void	syn_button_on_triple_click (SYN_Button * btn, SYN_ButtonCallback cb, void * ctx) Register a triple-click callback.
void	syn_button_service (SYN_Button * buttons, size_t count) Service an array of buttons.
void	syn_button_set_click_window (SYN_Button * btn, uint16_t window_ms) Set the multi-click evaluation window in milliseconds.
void	syn_button_update (SYN_Button * btn) Update a single button's state machine.

Public Static Functions¶

Type	Name
uint8_t	syn_button_clicks (const SYN_Button * btn) Get the consecutive click count.
bool	syn_button_combo_is_active (const SYN_ButtonCombo * combo) Is the combination button currently active (all buttons held)?
uint32_t	syn_button_held_ms (const SYN_Button * btn) How long has the button been in its current state (ms)?
bool	syn_button_is_pressed (const SYN_Button * btn) Is the button currently pressed (debounced)?
uint8_t	syn_button_poll_events (SYN_Button * btn) Read and clear pending events (bitmask of SYN_BUTTON_EVT_).*

Macros¶

Type	Name
define	PT_WAIT_BUTTON_PRESS (pt, btn) `/* multi line expression */`
define	PT_WAIT_BUTTON_RELEASE (pt, btn) `/* multi line expression */`
define	SYN_BUTTON_EVT_DOUBLE_CLICK `((uint8\_t)(1u << 5))`
define	SYN_BUTTON_EVT_LONG_PRESS `((uint8\_t)(1u << 2))`
define	SYN_BUTTON_EVT_MULTI_CLICK `((uint8\_t)(1u << 7))`
define	SYN_BUTTON_EVT_PRESS `((uint8\_t)(1u << 0))`
define	SYN_BUTTON_EVT_RELEASE `((uint8\_t)(1u << 1))`
define	SYN_BUTTON_EVT_REPEAT `((uint8\_t)(1u << 3))`
define	SYN_BUTTON_EVT_SINGLE_CLICK `((uint8\_t)(1u << 4))`
define	SYN_BUTTON_EVT_TRIPLE_CLICK `((uint8\_t)(1u << 6))`

Detailed Description¶

Pure polling — no interrupts required. Call syn_button_update() (or syn_button_service() for an array) from your main loop or a scheduler task. The module handles debouncing, edge detection, and long-press timing internally.

** **

static SYN_Button btn;
syn_button_init(&btn, PIN_BUTTON, SYN_BUTTON_ACTIVE_LOW, 50);
syn_button_on_press(&btn, my_press_handler, NULL);
syn_button_on_long_press(&btn, my_long_handler, 1000, NULL);

// Main loop:
while (1) { syn_button_update(&btn); }

// Or in a protothread:
PT_WAIT_BUTTON_PRESS(pt, &btn);

Public Types Documentation¶

typedef SYN_ButtonCallback¶

Button event callback.

typedef void(* SYN_ButtonCallback) (struct SYN_Button *btn, void *user_data);

Parameters:

btn The button that generated the event.
user_data User-provided context pointer.

enum SYN_ButtonPolarity¶

Button polarity selector.

enum SYN_ButtonPolarity {
    SYN_BUTTON_ACTIVE_HIGH = 0,
    SYN_BUTTON_ACTIVE_LOW = 1
};

enum SYN_ButtonState¶

Button FSM states.

enum SYN_ButtonState {
    SYN_BUTTON_STATE_IDLE = 0,
    SYN_BUTTON_STATE_DEBOUNCING = 1,
    SYN_BUTTON_STATE_PRESSED = 2,
    SYN_BUTTON_STATE_HELD = 3
};

Public Functions Documentation¶

function syn_button_combo_init¶

Initialize a combination button descriptor.

void syn_button_combo_init (
    SYN_ButtonCombo * combo,
    const SYN_Button ** buttons,
    size_t count,
    SYN_ButtonCallback cb,
    void * ctx
)

Fires callback when ALL specified buttons are simultaneously in debounced pressed state.

Parameters:

combo Combo descriptor.
buttons Array of pointers to initialized SYN_Button descriptors.
count Number of buttons in array.
cb Combo callback.
ctx User context.

function syn_button_combo_update¶

Update a combination button descriptor.

void syn_button_combo_update (
    SYN_ButtonCombo * combo
)

Parameters:

combo Combo descriptor.

function syn_button_init¶

Initialize a button descriptor.

void syn_button_init (
    SYN_Button * btn,
    SYN_GPIO_Pin pin,
    SYN_ButtonPolarity polarity,
    uint16_t debounce_ms
)

Parameters:

btn Button to initialize.
pin GPIO pin number.
polarity Active-high or active-low.
debounce_ms Debounce window in milliseconds (e.g., 50).

function syn_button_on_double_click¶

Register a double-click callback.

void syn_button_on_double_click (
    SYN_Button * btn,
    SYN_ButtonCallback cb,
    void * ctx
)

Parameters:

btn Button.
cb Callback (or NULL to disable).
ctx User context.

function syn_button_on_long_press¶

Register a long-press callback.

void syn_button_on_long_press (
    SYN_Button * btn,
    SYN_ButtonCallback cb,
    uint16_t hold_ms,
    void * ctx
)

Parameters:

btn Button.
cb Callback (or NULL to disable).
hold_ms Time the button must be held before firing (ms).
ctx User context.

function syn_button_on_multi_click¶

Register a multi-click (4+ taps) callback.

void syn_button_on_multi_click (
    SYN_Button * btn,
    SYN_ButtonCallback cb,
    void * ctx
)

Parameters:

btn Button.
cb Callback (or NULL to disable).
ctx User context.

function syn_button_on_press¶

Register a press callback.

void syn_button_on_press (
    SYN_Button * btn,
    SYN_ButtonCallback cb,
    void * ctx
)

Parameters:

btn Button.
cb Callback (or NULL to disable).
ctx User context.

function syn_button_on_release¶

Register a release callback.

void syn_button_on_release (
    SYN_Button * btn,
    SYN_ButtonCallback cb,
    void * ctx
)

Parameters:

btn Button.
cb Callback (or NULL to disable).
ctx User context.

function syn_button_on_repeat¶

Register an auto-repeat callback.

void syn_button_on_repeat (
    SYN_Button * btn,
    SYN_ButtonCallback cb,
    uint16_t interval_ms,
    void * ctx
)

Fires repeatedly while the button is held, after the initial press.

Parameters:

btn Button.
cb Callback (or NULL to disable).
interval_ms Repeat interval in milliseconds.
ctx User context.

function syn_button_on_single_click¶

Register a single-click callback.

void syn_button_on_single_click (
    SYN_Button * btn,
    SYN_ButtonCallback cb,
    void * ctx
)

Parameters:

btn Button.
cb Callback (or NULL to disable).
ctx User context.

function syn_button_on_triple_click¶

Register a triple-click callback.

void syn_button_on_triple_click (
    SYN_Button * btn,
    SYN_ButtonCallback cb,
    void * ctx
)

Parameters:

btn Button.
cb Callback (or NULL to disable).
ctx User context.

function syn_button_service¶

Service an array of buttons.

void syn_button_service (
    SYN_Button * buttons,
    size_t count
)

Parameters:

buttons Array of buttons.
count Number of buttons.

function syn_button_set_click_window¶

Set the multi-click evaluation window in milliseconds.

void syn_button_set_click_window (
    SYN_Button * btn,
    uint16_t window_ms
)

Parameters:

btn Button.
window_ms Max gap between taps to group into multi-clicks (default: 250ms, 0 = disable multi-click).

function syn_button_update¶

Update a single button's state machine.

void syn_button_update (
    SYN_Button * btn
)

Call this from your main loop, a scheduler task, or a timer callback. Reads the GPIO, runs debouncing, evaluates multi-clicks, and fires callbacks as needed.

Parameters:

btn Button to update.

Public Static Functions Documentation¶

function syn_button_clicks¶

Get the consecutive click count.

static inline uint8_t syn_button_clicks (
    const SYN_Button * btn
)

Parameters:

btn Button.

Returns:

Number of clicks accumulated in current multi-click sequence.

function syn_button_combo_is_active¶

Is the combination button currently active (all buttons held)?

static inline bool syn_button_combo_is_active (
    const SYN_ButtonCombo * combo
)

Parameters:

combo Combo descriptor.

Returns:

true if active.

function syn_button_held_ms¶

How long has the button been in its current state (ms)?

static inline uint32_t syn_button_held_ms (
    const SYN_Button * btn
)

Parameters:

btn Button.

Returns:

Duration in milliseconds.

function syn_button_is_pressed¶

Is the button currently pressed (debounced)?

static inline bool syn_button_is_pressed (
    const SYN_Button * btn
)

Parameters:

btn Button.

Returns:

true if pressed.

function syn_button_poll_events¶

Read and clear pending events (bitmask of SYN_BUTTON_EVT_*).

static inline uint8_t syn_button_poll_events (
    SYN_Button * btn
)

Useful for polling instead of callbacks.

Parameters:

btn Button.

Returns:

Bitmask of events that occurred since last poll.

Macro Definition Documentation¶

define PT_WAIT_BUTTON_PRESS¶

#define PT_WAIT_BUTTON_PRESS (
    pt,
    btn
) `/* multi line expression */`

Block until the button is pressed (debounced).

define PT_WAIT_BUTTON_RELEASE¶

#define PT_WAIT_BUTTON_RELEASE (
    pt,
    btn
) `/* multi line expression */`

Block until the button is released.

define SYN_BUTTON_EVT_DOUBLE_CLICK¶

#define SYN_BUTTON_EVT_DOUBLE_CLICK `((uint8_t)(1u << 5))`

Double click detected

define SYN_BUTTON_EVT_LONG_PRESS¶

#define SYN_BUTTON_EVT_LONG_PRESS `((uint8_t)(1u << 2))`

Long press detected

define SYN_BUTTON_EVT_MULTI_CLICK¶

#define SYN_BUTTON_EVT_MULTI_CLICK `((uint8_t)(1u << 7))`

Multi click (4+ taps)

define SYN_BUTTON_EVT_PRESS¶

#define SYN_BUTTON_EVT_PRESS `((uint8_t)(1u << 0))`

Button pressed

define SYN_BUTTON_EVT_RELEASE¶

#define SYN_BUTTON_EVT_RELEASE `((uint8_t)(1u << 1))`

Button released

define SYN_BUTTON_EVT_REPEAT¶

#define SYN_BUTTON_EVT_REPEAT `((uint8_t)(1u << 3))`

Auto-repeat fire

define SYN_BUTTON_EVT_SINGLE_CLICK¶

#define SYN_BUTTON_EVT_SINGLE_CLICK `((uint8_t)(1u << 4))`

Confirmed single click

define SYN_BUTTON_EVT_TRIPLE_CLICK¶

#define SYN_BUTTON_EVT_TRIPLE_CLICK `((uint8_t)(1u << 6))`

Triple click detected

The documentation for this class was generated from the following file src/syntropic/input/syn_button.h