auri.ee
keyboard stuff
1# Programmable Button {#programmable-button}
2
3Programmable 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.
4
5The 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`).
6
7::: tip
8Currently 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.
9:::
10
11## Usage {#usage}
12
13Add the following to your `rules.mk`:
14
15```make
16PROGRAMMABLE_BUTTON_ENABLE = yes
17```
18
19## Keycodes {#keycodes}
20
21|Key |Aliases|Description |
22|---------------------------|-------|----------------------|
23|`QK_PROGRAMMABLE_BUTTON_1` |`PB_1` |Programmable button 1 |
24|`QK_PROGRAMMABLE_BUTTON_2` |`PB_2` |Programmable button 2 |
25|`QK_PROGRAMMABLE_BUTTON_3` |`PB_3` |Programmable button 3 |
26|`QK_PROGRAMMABLE_BUTTON_4` |`PB_4` |Programmable button 4 |
27|`QK_PROGRAMMABLE_BUTTON_5` |`PB_5` |Programmable button 5 |
28|`QK_PROGRAMMABLE_BUTTON_6` |`PB_6` |Programmable button 6 |
29|`QK_PROGRAMMABLE_BUTTON_7` |`PB_7` |Programmable button 7 |
30|`QK_PROGRAMMABLE_BUTTON_8` |`PB_8` |Programmable button 8 |
31|`QK_PROGRAMMABLE_BUTTON_9` |`PB_9` |Programmable button 9 |
32|`QK_PROGRAMMABLE_BUTTON_10`|`PB_10`|Programmable button 10|
33|`QK_PROGRAMMABLE_BUTTON_11`|`PB_11`|Programmable button 11|
34|`QK_PROGRAMMABLE_BUTTON_12`|`PB_12`|Programmable button 12|
35|`QK_PROGRAMMABLE_BUTTON_13`|`PB_13`|Programmable button 13|
36|`QK_PROGRAMMABLE_BUTTON_14`|`PB_14`|Programmable button 14|
37|`QK_PROGRAMMABLE_BUTTON_15`|`PB_15`|Programmable button 15|
38|`QK_PROGRAMMABLE_BUTTON_16`|`PB_16`|Programmable button 16|
39|`QK_PROGRAMMABLE_BUTTON_17`|`PB_17`|Programmable button 17|
40|`QK_PROGRAMMABLE_BUTTON_18`|`PB_18`|Programmable button 18|
41|`QK_PROGRAMMABLE_BUTTON_19`|`PB_19`|Programmable button 19|
42|`QK_PROGRAMMABLE_BUTTON_20`|`PB_20`|Programmable button 20|
43|`QK_PROGRAMMABLE_BUTTON_21`|`PB_21`|Programmable button 21|
44|`QK_PROGRAMMABLE_BUTTON_22`|`PB_22`|Programmable button 22|
45|`QK_PROGRAMMABLE_BUTTON_23`|`PB_23`|Programmable button 23|
46|`QK_PROGRAMMABLE_BUTTON_24`|`PB_24`|Programmable button 24|
47|`QK_PROGRAMMABLE_BUTTON_25`|`PB_25`|Programmable button 25|
48|`QK_PROGRAMMABLE_BUTTON_26`|`PB_26`|Programmable button 26|
49|`QK_PROGRAMMABLE_BUTTON_27`|`PB_27`|Programmable button 27|
50|`QK_PROGRAMMABLE_BUTTON_28`|`PB_28`|Programmable button 28|
51|`QK_PROGRAMMABLE_BUTTON_29`|`PB_29`|Programmable button 29|
52|`QK_PROGRAMMABLE_BUTTON_30`|`PB_30`|Programmable button 30|
53|`QK_PROGRAMMABLE_BUTTON_31`|`PB_31`|Programmable button 31|
54|`QK_PROGRAMMABLE_BUTTON_32`|`PB_32`|Programmable button 32|
55
56## API {#api}
57
58### `void programmable_button_clear(void)` {#api-programmable-button-clear}
59
60Clear the programmable button report.
61
62---
63
64### `void programmable_button_add(uint8_t index)` {#api-programmable-button-add}
65
66Set the state of a button.
67
68#### Arguments {#api-programmable-button-add-arguments}
69
70 - `uint8_t index`
71 The index of the button to press, from 0 to 31.
72
73---
74
75### `void programmable_button_remove(uint8_t index)` {#api-programmable-button-remove}
76
77Reset the state of a button.
78
79#### Arguments {#api-programmable-button-remove-arguments}
80
81 - `uint8_t index`
82 The index of the button to release, from 0 to 31.
83
84---
85
86### `void programmable_button_register(uint8_t index)` {#api-programmable-button-register}
87
88Set the state of a button, and flush the report.
89
90#### Arguments {#api-programmable-button-register-arguments}
91
92 - `uint8_t index`
93 The index of the button to press, from 0 to 31.
94
95---
96
97### `void programmable_button_unregister(uint8_t index)` {#api-programmable-button-unregister}
98
99Reset the state of a button, and flush the report.
100
101#### Arguments {#api-programmable-button-unregister-arguments}
102
103 - `uint8_t index`
104 The index of the button to release, from 0 to 31.
105
106---
107
108### `bool programmable_button_is_on(uint8_t index)` {#api-programmable-button-is-on}
109
110Get the state of a button.
111
112#### Arguments {#api-programmable-button-is-on-arguments}
113
114 - `uint8_t index`
115 The index of the button to check, from 0 to 31.
116
117#### Return Value {#api-programmable-button-is-on-return}
118
119`true` if the button is pressed.
120
121---
122
123### `void programmable_button_flush(void)` {#api-programmable-button-flush}
124
125Send the programmable button report to the host.
126
127---
128
129### `uint32_t programmable_button_get_report(void)` {#api-programmable-button-get-report}
130
131Get the programmable button report.
132
133#### Return Value {#api-programmable-button-get-report-return}
134
135The bitmask of programmable button states.
136
137---
138
139### `void programmable_button_set_report(uint32_t report)` {#api-programmable-button-set-report}
140
141Set the programmable button report.
142
143#### Arguments {#api-programmable-button-set-report-arguments}
144
145 - `uint32_t report`
146 A bitmask of programmable button states.