qmk_firmware/docs/features/programmable_button.md
Ryan 78a0adfbb4
[docs] Organize driver & feature docs into subfolders (#23848)
Co-authored-by: Nick Brassel <nick@tzarc.org>
2024-06-02 12:42:24 +10:00

4.9 KiB

Programmable Button

Programmable Buttons are keys that have no predefined meaning. This means they can be processed on the host side by custom software without the operating system trying to interpret them.

The keycodes are emitted according to the HID Telephony Device page (0x0B), Programmable Button usage (0x09). On Linux (> 5.14) they are handled automatically and translated to KEY_MACRO# keycodes (up to KEY_MACRO30).

::: tip Currently there is no known support in Windows or macOS. It may be possible to write a custom HID driver to receive these usages, but this is out of the scope of the QMK documentation. :::

Usage

Add the following to your rules.mk:

PROGRAMMABLE_BUTTON_ENABLE = yes

Keycodes

Key Aliases Description
QK_PROGRAMMABLE_BUTTON_1 PB_1 Programmable button 1
QK_PROGRAMMABLE_BUTTON_2 PB_2 Programmable button 2
QK_PROGRAMMABLE_BUTTON_3 PB_3 Programmable button 3
QK_PROGRAMMABLE_BUTTON_4 PB_4 Programmable button 4
QK_PROGRAMMABLE_BUTTON_5 PB_5 Programmable button 5
QK_PROGRAMMABLE_BUTTON_6 PB_6 Programmable button 6
QK_PROGRAMMABLE_BUTTON_7 PB_7 Programmable button 7
QK_PROGRAMMABLE_BUTTON_8 PB_8 Programmable button 8
QK_PROGRAMMABLE_BUTTON_9 PB_9 Programmable button 9
QK_PROGRAMMABLE_BUTTON_10 PB_10 Programmable button 10
QK_PROGRAMMABLE_BUTTON_11 PB_11 Programmable button 11
QK_PROGRAMMABLE_BUTTON_12 PB_12 Programmable button 12
QK_PROGRAMMABLE_BUTTON_13 PB_13 Programmable button 13
QK_PROGRAMMABLE_BUTTON_14 PB_14 Programmable button 14
QK_PROGRAMMABLE_BUTTON_15 PB_15 Programmable button 15
QK_PROGRAMMABLE_BUTTON_16 PB_16 Programmable button 16
QK_PROGRAMMABLE_BUTTON_17 PB_17 Programmable button 17
QK_PROGRAMMABLE_BUTTON_18 PB_18 Programmable button 18
QK_PROGRAMMABLE_BUTTON_19 PB_19 Programmable button 19
QK_PROGRAMMABLE_BUTTON_20 PB_20 Programmable button 20
QK_PROGRAMMABLE_BUTTON_21 PB_21 Programmable button 21
QK_PROGRAMMABLE_BUTTON_22 PB_22 Programmable button 22
QK_PROGRAMMABLE_BUTTON_23 PB_23 Programmable button 23
QK_PROGRAMMABLE_BUTTON_24 PB_24 Programmable button 24
QK_PROGRAMMABLE_BUTTON_25 PB_25 Programmable button 25
QK_PROGRAMMABLE_BUTTON_26 PB_26 Programmable button 26
QK_PROGRAMMABLE_BUTTON_27 PB_27 Programmable button 27
QK_PROGRAMMABLE_BUTTON_28 PB_28 Programmable button 28
QK_PROGRAMMABLE_BUTTON_29 PB_29 Programmable button 29
QK_PROGRAMMABLE_BUTTON_30 PB_30 Programmable button 30
QK_PROGRAMMABLE_BUTTON_31 PB_31 Programmable button 31
QK_PROGRAMMABLE_BUTTON_32 PB_32 Programmable button 32

API

void programmable_button_clear(void)

Clear the programmable button report.


void programmable_button_add(uint8_t index)

Set the state of a button.

Arguments

  • uint8_t index
    The index of the button to press, from 0 to 31.

void programmable_button_remove(uint8_t index)

Reset the state of a button.

Arguments

  • uint8_t index
    The index of the button to release, from 0 to 31.

void programmable_button_register(uint8_t index)

Set the state of a button, and flush the report.

Arguments

  • uint8_t index
    The index of the button to press, from 0 to 31.

void programmable_button_unregister(uint8_t index)

Reset the state of a button, and flush the report.

Arguments

  • uint8_t index
    The index of the button to release, from 0 to 31.

bool programmable_button_is_on(uint8_t index)

Get the state of a button.

Arguments

  • uint8_t index
    The index of the button to check, from 0 to 31.

Return Value

true if the button is pressed.


void programmable_button_flush(void)

Send the programmable button report to the host.


uint32_t programmable_button_get_report(void)

Get the programmable button report.

Return Value

The bitmask of programmable button states.


void programmable_button_set_report(uint32_t report)

Set the programmable button report.

Arguments

  • uint32_t report
    A bitmask of programmable button states.