CAF: Buttons module

The buttons module of the Common Application Framework (CAF) is responsible for generating events related to key presses. The source of events are changes to GPIO pins. The module can handle both matrix keyboard and buttons directly connected to GPIO pins.

Configuration

To use the module, you must enable the following Kconfig options:

When defining how buttons are connected, you must create a configuration file with the following arrays:

  • row contains pins associated with matrix rows.

  • col contains pins associated with columns, it can be left empty (buttons will be assumed to be directly connected to row pins, one button per pin).

For example, the file contents should look like follows:

#include <caf/gpio_pins.h>

static const struct gpio_pin col[] = {
        { .port = 0, .pin = 31 },
        { .port = 0, .pin = 24 },
};

static const struct gpio_pin row[] = {
        { .port = 0, .pin = 9  },
        { .port = 0, .pin = 8  },
        { .port = 1, .pin = 15 },
        { .port = 1, .pin = 14 },
};

You must define both arrays in this configuration file, and specify its location with the CONFIG_CAF_BUTTONS_DEF_PATH Kconfig option.

Note

The configuration file should be included only by the configured module. Do not include the configuration file in other source files.

The following Kconfig options are available for this module:

By default, a button press is indicated by a pin switch from the low to the high state. You can change this with CONFIG_CAF_BUTTONS_POLARITY_INVERSED, which will cause the application to react to an opposite pin change (from the high to the low state).

Power management configuration

If the CONFIG_CAF_BUTTONS_PM_EVENTS Kconfig option is enabled, the module interacts with power management events (power_down_event and wake_up_event).

The module can be used to trigger an application wakeup event. By default, pressing any button wakes up the application. In the configuration file, you can specify which subset of rows and columns of the keyboard matrix should not trigger an application wakeup. Such rows and columns must be marked by setting gpio_pin.wakeup_blocked to true. See an example of the modified configuration file:

#include <caf/gpio_pins.h>

static const struct gpio_pin col[] = {
        { .port = 0, .pin = 31, .wakeup_blocked = true },
        { .port = 0, .pin = 24 },
};

static const struct gpio_pin row[] = {
        { .port = 0, .pin = 9, .wakeup_blocked = true },
        { .port = 0, .pin = 8, .wakeup_blocked = true },
        { .port = 1, .pin = 15 },
        { .port = 1, .pin = 14 },
};

After the change is applied to the configuration file, a button that belongs to the marked row or column is still handled by the module, but no longer triggers the application wakeup.

Implementation details

Depending on the configuration, the module can use from two to four states.

State transitions of the buttons module

State transitions of the buttons module

By default, the module uses the following states:

  • STATE_SCANNING

  • STATE_ACTIVE

After initialization, the module starts in STATE_SCANNING and performs initial scan of configured pins. If no buttons are pressed the module switches to STATE_ACTIVE. In this state, the module enables the GPIO interrupts for all of the handled buttons and waits for the pin state to change.

Whenever a button is pressed, the module switches to STATE_SCANNING. When the switch occurs, the module submits a work with a delay set to CONFIG_CAF_BUTTONS_DEBOUNCE_INTERVAL. The work scans the keyboard matrix, or directly connected buttons (depends on configuration). If any button state change occurs, the module sends an event with the button_event.key_id of that button.

  • If the button is kept pressed while the scanning is performed, the work will be resubmitted with a delay set to CONFIG_CAF_BUTTONS_SCAN_INTERVAL.

  • If no button is pressed, the module switches back to STATE_ACTIVE.

Key ID

The button_event.key_id is an unique 2-byte value that depends on the module configuration described in the configuration file.

The following table breaks down the button_event.key_id bits.

key_id

0 .. 6

7 .. 13

14

15

Row idx

Col idx

Reserved

In this button_event.key_id value:

  • The first seven least significant bits (Row idx) encode the index of the row array that corresponds to the GPIO port and the pin to which the button’s row is connected.

  • The next seven bits (Col idx) encode the index of the col array that corresponds to the GPIO port and the pin to which the button’s column is connected. If the buttons are directly connected they are denoted only by row array index, col array index bits are set to zero.

  • The last two bits are reserved for application-specific usage.

For example, if the configuration file looks as described in the Configuration section of this documentation, an event button_event with the button_event.key_id value equal to 0x0083 indicates the following information:

  • The button row pin is connected to the GPIO that is at index 3 in the row array from the configuration file. That is, the row port and pin are 1 and 14, respectively.

  • The button column pin is connected to the GPIO that is at index 1 in the col array from the configuration file. That is, the column port and pin are 0 and 24, respectively.

Power management states

If the CONFIG_CAF_BUTTONS_PM_EVENTS Kconfig option is enabled, the module can react to power management events and submit wake_up_event. In that case, the following additional states are available:

  • STATE_SUSPENDING

  • STATE_IDLE

The power management events that module can react to are the following:

If power_down_event comes while the module is in the STATE_SCANNING state, the module switches to STATE_SUSPENDING and remains in this state until no button is pressed. Then, it switches to STATE_IDLE. If power_down_event comes while the module is in the STATE_ACTIVE state, the module immediately switches to STATE_IDLE.

Similarly, as in STATE_ACTIVE, in STATE_IDLE the module enables the GPIO interrupts and waits for the pin state to change. However, in STATE_IDLE the interrupts are enabled only for the subset of buttons that are configured to wake up the application. Pressing any of these buttons also invokes wake_up_event and sends it to all subscribing modules.