diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/feature_programmable_button.md | 74 | ||||
| -rw-r--r-- | docs/keycodes.md | 40 |
3 files changed, 115 insertions, 0 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 2f6309e41d..4b528d9967 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -72,6 +72,7 @@ * [Mod-Tap](mod_tap.md) * [Macros](feature_macros.md) * [Mouse Keys](feature_mouse_keys.md) + * [Programmable Button](feature_programmable_button.md) * [Space Cadet Shift](feature_space_cadet.md) * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) diff --git a/docs/feature_programmable_button.md b/docs/feature_programmable_button.md new file mode 100644 index 0000000000..b1ef555d16 --- /dev/null +++ b/docs/feature_programmable_button.md @@ -0,0 +1,74 @@ +## Programmable Button + +Programmable button is a feature that can be used to send keys that have no +predefined meaning. +This means they can be processed on the host side by custom software without +colliding without the operating system trying to interpret these keys. + +The keycodes are emitted according to the HID usage +"Telephony Device Page" (0x0B), "Programmable button usage" (0x07). +On Linux (> 5.14) they are handled automatically and translated to `KEY_MACRO#` +keycodes. +(Up to `KEY_MACRO30`) + +### Enabling Programmable Button support + +To enable Programmable Button, add the following line to your keymap’s `rules.mk`: + +```c +PROGRAMMABLE_BUTTON_ENABLE = yes +``` + +### Mapping + +In your keymap you can use the following keycodes to map key presses to Programmable Buttons: + +|Key |Description | +|------------------------|----------------------| +|`PROGRAMMABLE_BUTTON_1` |Programmable button 1 | +|`PROGRAMMABLE_BUTTON_2` |Programmable button 2 | +|`PROGRAMMABLE_BUTTON_3` |Programmable button 3 | +|`PROGRAMMABLE_BUTTON_4` |Programmable button 4 | +|`PROGRAMMABLE_BUTTON_5` |Programmable button 5 | +|`PROGRAMMABLE_BUTTON_6` |Programmable button 6 | +|`PROGRAMMABLE_BUTTON_7` |Programmable button 7 | +|`PROGRAMMABLE_BUTTON_8` |Programmable button 8 | +|`PROGRAMMABLE_BUTTON_9` |Programmable button 9 | +|`PROGRAMMABLE_BUTTON_10`|Programmable button 10| +|`PROGRAMMABLE_BUTTON_11`|Programmable button 11| +|`PROGRAMMABLE_BUTTON_12`|Programmable button 12| +|`PROGRAMMABLE_BUTTON_13`|Programmable button 13| +|`PROGRAMMABLE_BUTTON_14`|Programmable button 14| +|`PROGRAMMABLE_BUTTON_15`|Programmable button 15| +|`PROGRAMMABLE_BUTTON_16`|Programmable button 16| +|`PROGRAMMABLE_BUTTON_17`|Programmable button 17| +|`PROGRAMMABLE_BUTTON_18`|Programmable button 18| +|`PROGRAMMABLE_BUTTON_19`|Programmable button 19| +|`PROGRAMMABLE_BUTTON_20`|Programmable button 20| +|`PROGRAMMABLE_BUTTON_21`|Programmable button 21| +|`PROGRAMMABLE_BUTTON_22`|Programmable button 22| +|`PROGRAMMABLE_BUTTON_23`|Programmable button 23| +|`PROGRAMMABLE_BUTTON_24`|Programmable button 24| +|`PROGRAMMABLE_BUTTON_25`|Programmable button 25| +|`PROGRAMMABLE_BUTTON_26`|Programmable button 26| +|`PROGRAMMABLE_BUTTON_27`|Programmable button 27| +|`PROGRAMMABLE_BUTTON_28`|Programmable button 28| +|`PROGRAMMABLE_BUTTON_29`|Programmable button 29| +|`PROGRAMMABLE_BUTTON_30`|Programmable button 30| +|`PROGRAMMABLE_BUTTON_31`|Programmable button 31| +|`PROGRAMMABLE_BUTTON_32`|Programmable button 32| +|`PB_1` to `PB_32` |Aliases for keymaps | + +### API + +You can also use a dedicated API defined in `programmable_button.h` to interact with this feature: + +``` +void programmable_button_clear(void); +void programmable_button_send(void); +void programmable_button_on(uint8_t code); +void programmable_button_off(uint8_t code); +bool programmable_button_is_on(uint8_t code); +uint32_t programmable_button_get_report(void); +void programmable_button_set_report(uint32_t report); +``` diff --git a/docs/keycodes.md b/docs/keycodes.md index a134c5a1b2..770a4525a5 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -677,6 +677,46 @@ See also: [One Shot Keys](one_shot_keys.md) |`OS_OFF` |Turns One Shot keys off | |`OS_TOGG` |Toggles One Shot keys status | +## Programmable Button Support :id=programmable-button + +See also: [Programmable Button](feature_programmable_button.md) + +|Key |Description | +|------------------------|----------------------| +|`PROGRAMMABLE_BUTTON_1` |Programmable button 1 | +|`PROGRAMMABLE_BUTTON_2` |Programmable button 2 | +|`PROGRAMMABLE_BUTTON_3` |Programmable button 3 | +|`PROGRAMMABLE_BUTTON_4` |Programmable button 4 | +|`PROGRAMMABLE_BUTTON_5` |Programmable button 5 | +|`PROGRAMMABLE_BUTTON_6` |Programmable button 6 | +|`PROGRAMMABLE_BUTTON_7` |Programmable button 7 | +|`PROGRAMMABLE_BUTTON_8` |Programmable button 8 | +|`PROGRAMMABLE_BUTTON_9` |Programmable button 9 | +|`PROGRAMMABLE_BUTTON_10`|Programmable button 10| +|`PROGRAMMABLE_BUTTON_11`|Programmable button 11| +|`PROGRAMMABLE_BUTTON_12`|Programmable button 12| +|`PROGRAMMABLE_BUTTON_13`|Programmable button 13| +|`PROGRAMMABLE_BUTTON_14`|Programmable button 14| +|`PROGRAMMABLE_BUTTON_15`|Programmable button 15| +|`PROGRAMMABLE_BUTTON_16`|Programmable button 16| +|`PROGRAMMABLE_BUTTON_17`|Programmable button 17| +|`PROGRAMMABLE_BUTTON_18`|Programmable button 18| +|`PROGRAMMABLE_BUTTON_19`|Programmable button 19| +|`PROGRAMMABLE_BUTTON_20`|Programmable button 20| +|`PROGRAMMABLE_BUTTON_21`|Programmable button 21| +|`PROGRAMMABLE_BUTTON_22`|Programmable button 22| +|`PROGRAMMABLE_BUTTON_23`|Programmable button 23| +|`PROGRAMMABLE_BUTTON_24`|Programmable button 24| +|`PROGRAMMABLE_BUTTON_25`|Programmable button 25| +|`PROGRAMMABLE_BUTTON_26`|Programmable button 26| +|`PROGRAMMABLE_BUTTON_27`|Programmable button 27| +|`PROGRAMMABLE_BUTTON_28`|Programmable button 28| +|`PROGRAMMABLE_BUTTON_29`|Programmable button 29| +|`PROGRAMMABLE_BUTTON_30`|Programmable button 30| +|`PROGRAMMABLE_BUTTON_31`|Programmable button 31| +|`PROGRAMMABLE_BUTTON_32`|Programmable button 32| +|`PB_1` to `PB_32` |Aliases for keymaps | + ## Space Cadet :id=space-cadet See also: [Space Cadet](feature_space_cadet.md) |