programmable_button.md (5059B)
1 # Programmable Button {#programmable-button} 2 3 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. 4 5 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`). 6 7 ::: tip 8 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. 9 ::: 10 11 ## Usage {#usage} 12 13 Add the following to your `rules.mk`: 14 15 ```make 16 PROGRAMMABLE_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 60 Clear the programmable button report. 61 62 --- 63 64 ### `void programmable_button_add(uint8_t index)` {#api-programmable-button-add} 65 66 Set 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 77 Reset 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 88 Set 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 99 Reset 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 110 Get 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 125 Send the programmable button report to the host. 126 127 --- 128 129 ### `uint32_t programmable_button_get_report(void)` {#api-programmable-button-get-report} 130 131 Get the programmable button report. 132 133 #### Return Value {#api-programmable-button-get-report-return} 134 135 The bitmask of programmable button states. 136 137 --- 138 139 ### `void programmable_button_set_report(uint32_t report)` {#api-programmable-button-set-report} 140 141 Set 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.