Button Part Drivers Documentation

This page presents an overview of the Button Part Drivers.

A detailed API documentation is also available here: Button Part Drivers API Documentation - GPIO.

Introduction

The Button part driver provides APIs to drive button components. The implementation uses the HAL. It offers a higher level of abstraction than the HAL, with features such as polarity management and optional software debounce.

This driver comes as an OpenCMSIS pack. The following section describes the pack structure and usage.

Principles

This driver is implemented in a single component. It uses the HAL GPIO.

Programming model

Folder structure

The driver’s folder structure is as follows: 

button
  |- gpio
  |   |- button.h
  |   |- button.c

The files button.c and button.h implement the driver.

Usage and initialization

The main data structure for this driver is the button_t “object” structure, which contains all the internal state needed by the driver. The user application never needs to access that structure’s fields directly.

At initialization, the user application must initialize the resources for the part driver separately, optionally relying on STM32CubeMX2-generated code. The part driver does not enforce the requirements on the resources, but the user application must respect them to ensure proper functionality. After the user application properly initializes all the required resources (HAL instances), it can call the part driver initialization and provide those resources.

Integration with STM32CubeMX2

The Button part driver supports configuration and code generation in STM32CubeMX2.

Generated code

STM32CubeMX2 generates two files, mx_button.c and mx_button.h. These files contain an implementation of button_io_init(), which the button driver calls during initialization (inside button_init()) to initialize button_t structures. The function uses an ID stored in the button_t structure to select the configuration to apply. The generated files may also contain macros specifying the values of various parameters chosen in STM32CubeMX2’s GUI.

The implementation extracts most values used to initialize button_t instances from HAL-generated init code, mainly mx_hal_def.h. It also computes values from user inputs, especially for debounce settings.

Configuration parameters

The following parameters are available for this driver:

  • GPIO pin to use

  • Button polarity (GND/VCC when pressed)

  • If software debounce is enabled, debounce duration

The Button part driver may impose a specific configuration to HAL components in order to guarantee their functionality.

The driver applies the following constraints:

  • GPIO in input mode

Optionally, you may enable the EXTI on the selected GPIO for both edges. Doing so enables support for asynchronous features, especially callbacks and software debounce.

If you disable the EXTI on the button pin, some features of the part driver may be unavailable. Depending on the HAL generic configuration ( USE_ASSERT, …), those functions may crash or return an error code. In particular, the EXTI configuration is mandatory when software debounce is enabled at project level ( BUTTON_DEBOUNCE=1, which is the default).

Sequence Diagram

The diagram below presents a simple use case for this driver.

simple use case for this driver

Dependencies

The diagram below presents the partitioning of this driver into components.

partitioning of this driver into components

This components’ structure translates to the following inclusion graph in terms of C code:

inclusion graph of this driver

The user application only ever needs to “#include” button.h , or mx_button.h if STM32CubeMX2 code generation is used.