Button Public API

Public functions to interact with the button subsystem. More...

Collaboration diagram for Button Public API:

Functions
ERR_te	button_init_subsys (void)
	Initializes the button subsystem.
ERR_te	button_deinit_subsys (void)
	Deinitializes the button subsystem.
ERR_te	button_start_subsys (void)
	Starts the button subsystem.
ERR_te	button_stop_subsys (void)
	Stops the button subsystem.
ERR_te	button_init_handle (BUTTON_CFG_ts *button_cfg, BUTTON_HANDLE_ts **button_handle)
	Initializes and registers a button handle.
ERR_te	button_deinit_handle (BUTTON_HANDLE_ts const *button_handle)
	Deinitializes a button handle.
ERR_te	button_run_handle (BUTTON_HANDLE_ts *button_handle)
	Executes the state machine for a single button.
ERR_te	button_run_handle_all (void)
	Runs the state machine for all registered buttons.
ERR_te	button_get_pushed_state (BUTTON_HANDLE_ts const *button_handle, bool *pushed_state_o)
	Retrieves the pushed (pressed) state of a button.
ERR_te	button_get_held_state (BUTTON_HANDLE_ts const *button_handle, bool *held_state_o)
	Retrieves the held state of a button.

Detailed Description

Public functions to interact with the button subsystem.

Function Documentation

button_init_subsys()

ERR_te button_init_subsys

(

void

)

Initializes the button subsystem.

This function initializes the internal state of the button module, sets up required dependencies, and registers subsystem commands.

It must be called before using any other button API functions.

Returns

• ERR_OK on success
• ERR_INITIALIZATION_FAILURE if the subsystem is already initialized
• Other error codes depending on internal failures

Note

This function should only be called once during system startup.

See also

button_init_subsys

Definition at line 159 of file button.c.

                                {
    ERR_te err;
 
    if(internal_state.initialized) {      
        return ERR_INITIALIZATION_FAILURE;
    }
 
    internal_state = (struct internal_state_s){ 0 };
    
    internal_state.log_level = LOG_LEVEL_INFO;
    internal_state.subsys = MODULES_BUTTON;
    internal_state.initialized = true;
    internal_state.started = false;
 
    init_log();
    init_systick();
    
    err = cmd_register(&button_cmd_client_info);
    if(err != ERR_OK) {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "button_init_subsys: cmd_register error"
        );
 
        return err;
    }
    LOG_INFO(
        internal_state.subsys, 
        internal_state.log_level,
        "button_init_subsys: subsys initialized"
    );
 
    return ERR_OK;    
}

Here is the call graph for this function:

Here is the caller graph for this function:

button_deinit_subsys()

ERR_te button_deinit_subsys

(

void

)

Deinitializes the button subsystem.

This function resets the internal state of the button subsystem and deregisters previously registered commands.

It must only be called after the subsystem has been initialized and fully stopped.

Returns

• ERR_OK on success
• ERR_DEINITIALIZATION_FAILURE if the subsystem is still running or not initialized

Note

All button handles must be deinitialized before calling this function.

See also

button_deinit_subsys

Definition at line 196 of file button.c.

                                  {
    if(internal_state.initialized && !internal_state.started) {
        internal_state = (struct internal_state_s){ 0 };
 
        cmd_deregister(&button_cmd_client_info);
    }
    else {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "button_deinit_subsys: subsys is not initialized or not stopped"
        );
 
        return ERR_DEINITIALIZATION_FAILURE;
    }
    LOG_INFO(
        internal_state.subsys, 
        internal_state.log_level,
        "button_deinit_subsys: subsys deinitialized"
    );
 
    return ERR_OK;
}

Here is the call graph for this function:

button_start_subsys()

ERR_te button_start_subsys

(

void

)

Starts the button subsystem.

Enables runtime processing of button handles. After calling this function, button state updates via button_run_handle() or button_run_handle_all() are allowed.

Returns

• ERR_OK on success
• ERR_UNKNOWN if the subsystem is not initialized or already started

Note

Must be called after button_init_subsys().

See also

button_start_subsys

Definition at line 221 of file button.c.

                                 {
    if(internal_state.initialized && !internal_state.started) {
        internal_state.started = true;
 
        LOG_INFO(
            internal_state.subsys, 
            internal_state.log_level,
            "button_start_subsys: subsys started"
        );
    }
    else {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "button_start_subsys: subsys not initialized or already started"
        );
 
        return ERR_UNKNOWN;
    }
 
    return ERR_OK;
}

Here is the caller graph for this function:

button_stop_subsys()

ERR_te button_stop_subsys

(

void

)

Stops the button subsystem.

Disables runtime processing of button handles. After calling this function, no button state updates should be performed.

Returns

• ERR_OK on success
• ERR_UNKNOWN if the subsystem is not initialized or already stopped

Note

Call this before deinitializing the subsystem or handles.

See also

button_stop_subsys

Definition at line 245 of file button.c.

                                {
    if(internal_state.initialized && internal_state.started) {
        internal_state.started = false;
 
        LOG_INFO(
            internal_state.subsys, 
            internal_state.log_level,
            "button_stop_subsys: subsys stopped"
        );
    }
    else {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "button_stop_subsys: subsys not initialized or already already stopped"
        );
        
        return ERR_UNKNOWN;
    }
 
    return ERR_OK;
}

button_init_handle()

ERR_te button_init_handle	(	BUTTON_CFG_ts *	button_cfg,
		BUTTON_HANDLE_ts **	button_handle_o )

Initializes and registers a button handle.

Configures the GPIO associated with the button and allocates an internal handle from the subsystem pool.

The returned handle must be used for all subsequent operations on the button.

Parameters

[in]	button_cfg	Pointer to the button configuration structure.
[out]	button_handle_o	Pointer to a handle pointer that will be set to the allocated button instance.

Returns

• ERR_OK on success
• ERR_UNINITIALZIED_OBJECT if the subsystem is not initialized
• ERR_NOT_ENOUGH_SPACE if the maximum number of buttons is reached
• ERR_INVALID_ARGUMENT if input arguments are NULL

Note

GPIO is configured internally as input during initialization.

See also

button_init_handle

Definition at line 269 of file button.c.

                                                                                         {
    if(!internal_state.initialized) {
        LOG_INFO(
            internal_state.subsys, 
            internal_state.log_level,
            "button_init_handle: subsys not initialized"
        );
 
        return ERR_UNINITIALZIED_OBJECT;
    }
 
    if(internal_state.button_num == CONFIG_BUTTON_MAX_OBJECTS) {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "button_init_handle: subsystem out of memory space"
        );
 
        return ERR_NOT_ENOUGH_SPACE;
    }
 
    if(!button_cfg) {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "button_init_handle: invalid argument"
        );
        return ERR_INVALID_ARGUMENT;
    }
 
    GPIO_CFG_ts gpio = { 0 };
    gpio.port = button_cfg->gpio_port;
    gpio.pin = button_cfg->gpio_pin;
    gpio.output_type = GPIO_OUTPUT_TYPE_PUSHPULL;
    gpio.mode = GPIO_MODE_INPUT;
 
    gpio_init(&gpio);
 
    for(uint32_t i = 0; i < CONFIG_BUTTON_MAX_OBJECTS; i++) {
        if(internal_state.buttons[i].in_use == false) {
            str_cpy(
                internal_state.buttons[i].name,
                button_cfg->name,
                get_str_len(button_cfg->name) + 1
            );
 
            internal_state.buttons[i].debounce_limit_ms = button_cfg->debounce_limit_ms;
            internal_state.buttons[i].gpio_port = button_cfg->gpio_port;
            internal_state.buttons[i].gpio_pin = button_cfg->gpio_pin;
            internal_state.buttons[i].pushed_type = button_cfg->pushed_type;
            internal_state.buttons[i].held_limit_ms = button_cfg->held_limit_ms;
            internal_state.buttons[i].held = false;
            internal_state.buttons[i].held_started_ms = 0;
            internal_state.buttons[i].debounce_started = false;
            internal_state.buttons[i].held_started = false;
            internal_state.buttons[i].pushed = false;
            internal_state.buttons[i].debounce_started_ms = 0;
            internal_state.buttons[i].in_use = true;
 
            *button_handle_o = &internal_state.buttons[i];
 
            internal_state.button_num++;
 
            LOG_INFO(
                internal_state.subsys, 
                internal_state.log_level,
                "button_init_handle: button handle %s initialized",
                internal_state.buttons[i].name
            );
 
            break;
        }
    }
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

button_deinit_handle()

ERR_te button_deinit_handle

(

BUTTON_HANDLE_ts const *

button_handle

)

Deinitializes a button handle.

Releases the internal resources associated with the given button handle and marks the slot as available for reuse.

Parameters

[in]

button_handle

Pointer to the button handle to deinitialize.

Returns

• ERR_OK on success
• ERR_ILLEGAL_ACTION if the subsystem is still running
• ERR_UNINITIALZIED_OBJECT if the handle is invalid or not found

Note

The subsystem must be stopped before calling this function.

See also

button_deinit_handle

Definition at line 347 of file button.c.

                                                                   {
    if(internal_state.started) {
        LOG_INFO(
            internal_state.subsys, 
            internal_state.log_level,
            "button_deinit_handle: subsys not stopped"
        );
        return ERR_ILLEGAL_ACTION;
    }
 
    if(internal_state.button_num == 0) {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "button_deinit_handle: no such handle to deinitialize"
        );
 
        return ERR_UNINITIALZIED_OBJECT;
    }
    
    for(uint32_t i = 0; i < CONFIG_BUTTON_MAX_OBJECTS; i++) {
        if(&internal_state.buttons[i] == button_handle) {
            uint8_t name_len = get_str_len(internal_state.buttons[i].name) + 1;
            char name[name_len];
            str_cpy(name, internal_state.buttons[i].name, name_len);
 
            internal_state.buttons[i] = (BUTTON_HANDLE_ts){ 0 };
 
            internal_state.button_num--;
 
            LOG_INFO(
                internal_state.subsys, 
                internal_state.log_level,
                "button_deinit_handle: io handle %s deinitialized",
                name
            );
 
            break;
        }
 
        if(i == CONFIG_BUTTON_MAX_OBJECTS - 1) {
            LOG_ERROR(
                internal_state.subsys, 
                internal_state.log_level,
                "button_deinit_handle: no such handle to deinitialize"
            );
            
            return ERR_UNINITIALZIED_OBJECT;
        }
    }
 
    return ERR_OK;
}

Here is the call graph for this function:

button_run_handle()

ERR_te button_run_handle

(

BUTTON_HANDLE_ts *

button_handle

)

Executes the state machine for a single button.

This function performs debounce handling, press detection, and hold detection for the specified button handle.

It should be called periodically (e.g., in a main loop or scheduler).

Parameters

[in,out]

button_handle

Pointer to the button handle to process.

Returns

• ERR_OK on success
• ERR_UNKNOWN if the subsystem is not initialized or started

Note

Timing is based on the system tick (systick_get_ms()).

Executes the state machine for a single button.

See also

button_run_handle

Definition at line 402 of file button.c.

                                                          {
    if(!internal_state.initialized || !internal_state.started) {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "button_run_handle: subsystem not initialized or started"
        );
 
        return ERR_UNKNOWN;
    }
 
    PIN_STATUS_te pin_status = gpio_read(button_handle->gpio_port, button_handle->gpio_pin);
 
    // If the debounce has not yet been completed, complete it (if it's enabled)
    if(button_handle->pushed == false) {
        if((button_handle->pushed_type == BUTTON_PUSHED_TYPE_HIGH && 
        pin_status == HIGH) ||
        (button_handle->pushed_type == BUTTON_PUSHED_TYPE_LOW && 
        pin_status == LOW)) {
            uint32_t current_ms = systick_get_ms();
 
            if(!button_handle->debounce_started) {
                button_handle->debounce_started = true;
                button_handle->debounce_started_ms = current_ms;
            }
 
            if(button_handle->debounce_started &&
            current_ms - button_handle->debounce_started_ms >= button_handle->debounce_limit_ms) {
                button_handle->pushed = true;
                button_handle->debounce_started = false;
            }
        }
        else {
            if(button_handle->debounce_started) {
                button_handle->debounce_started = false;
                button_handle->debounce_started_ms = 0;
            }
        }
    }
 
    // If the held property is enabled, check if button is held for long enough
    if(button_handle->pushed == true && button_handle->held == false) {
        if((button_handle->pushed_type == BUTTON_PUSHED_TYPE_HIGH && 
        pin_status == HIGH) ||
        (button_handle->pushed_type == BUTTON_PUSHED_TYPE_LOW && 
        pin_status == LOW)) {
            uint32_t current_ms = systick_get_ms();
 
            if(!button_handle->held_started) {
                button_handle->held_started = true;
                button_handle->held_started_ms = current_ms;
            }
 
            if(button_handle->held_started &&
            current_ms - button_handle->held_started_ms >= button_handle->held_limit_ms) {
                button_handle->held = true;
                button_handle->held_started = false;
            }
        }
        else {
            if(button_handle->held_started) {
                button_handle->held_started = false;
                button_handle->held_started_ms = 0;
            }
        }
    }
 
    // If the button has been pushed, check for button release then restore states and counters
    if(button_handle->pushed == true) {
        if((button_handle->pushed_type == BUTTON_PUSHED_TYPE_HIGH && 
        pin_status == LOW) ||
        (button_handle->pushed_type == BUTTON_PUSHED_TYPE_LOW && 
        pin_status == HIGH)) {
            uint32_t current_ms = systick_get_ms();
 
            if(!button_handle->debounce_started) {
                button_handle->debounce_started = true;
                button_handle->debounce_started_ms = current_ms;
            }
 
            if(button_handle->debounce_started &&
            current_ms - button_handle->debounce_started_ms >= button_handle->debounce_limit_ms) {
                button_handle->pushed = false;
                button_handle->held = false;
                button_handle->debounce_started = false;
                button_handle->held_started = false;
            }
        }
        else {
            if(button_handle->debounce_started) {
                button_handle->debounce_started = false;
                button_handle->debounce_started_ms = 0;
            }
        }
    }
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

button_run_handle_all()

ERR_te button_run_handle_all

(

void

)

Runs the state machine for all registered buttons.

Iterates over all active button handles and processes their state machines.

Returns

• ERR_OK on success
• First encountered error from button_run_handle()

Runs the state machine for all registered buttons.

See also

button_run_handle_all

Definition at line 502 of file button.c.

                                   {
    for(uint32_t i = 0; i < CONFIG_BUTTON_MAX_OBJECTS; i++) {
        if(internal_state.buttons[i].in_use == true) {
            ERR_te err = button_run_handle(&internal_state.buttons[i]);
            if(err != ERR_OK) {
                return err;
            }
        }
    }
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

button_get_pushed_state()

ERR_te button_get_pushed_state	(	BUTTON_HANDLE_ts const *	button_handle,
		bool *	pushed_state_o )

Retrieves the pushed (pressed) state of a button.

Parameters

[in]	button_handle	Pointer to the button handle.
[out]	pushed_state_o	Pointer to a boolean that will receive the state.

Returns

• ERR_OK on success
• ERR_ILLEGAL_ACTION if the subsystem is not initialized or started

Note

The returned state reflects the debounced logical state.

Retrieves the pushed (pressed) state of a button.

See also

button_get_pushed_state

Definition at line 516 of file button.c.

                                                                                            {
    if(!internal_state.initialized || !internal_state.started) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "button_get_pushed_state: handle not initialized or subsystem not started"
        );
 
        return ERR_ILLEGAL_ACTION;
    }
 
    *pushed_state_o = button_handle->pushed;
 
    return ERR_OK;
}

Here is the caller graph for this function:

button_get_held_state()

ERR_te button_get_held_state	(	BUTTON_HANDLE_ts const *	button_handle,
		bool *	held_state_o )

Retrieves the held state of a button.

Parameters

[in]	button_handle	Pointer to the button handle.
[out]	held_state_o	Pointer to a boolean that will receive the state.

Returns

• ERR_OK on success
• ERR_ILLEGAL_ACTION if the subsystem is not initialized or started

Note

The held state becomes true after the configured held time threshold.

See also

button_get_held_state

Definition at line 533 of file button.c.

                                                                                        {
    if(!internal_state.initialized || !internal_state.started) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "button_get_held_state: handle not initialized or subsystem not started"
        );
 
        return ERR_ILLEGAL_ACTION;
    }
 
    *held_state_o = button_handle->held;
 
    return ERR_OK;
}

Here is the caller graph for this function: