aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorThomas Weißschuh <thomas@t-8ch.de>2021-09-15 17:40:22 +0200
committerGitHub <noreply@github.com>2021-09-15 08:40:22 -0700
commit83988597f4d916a37b2b0987f393ceaa007532eb (patch)
treeba5d07ccf743cb27bee77b4d6cd2128035ce365e /docs
parent1a68feb842ebcc6a7d1aef7cd7f83865cc18fab1 (diff)
downloadqmk_firmware-83988597f4d916a37b2b0987f393ceaa007532eb.tar.gz
qmk_firmware-83988597f4d916a37b2b0987f393ceaa007532eb.zip
Add Support for USB programmable buttons (#12950)
Diffstat (limited to 'docs')
-rw-r--r--docs/_summary.md1
-rw-r--r--docs/feature_programmable_button.md74
-rw-r--r--docs/keycodes.md40
3 files changed, 115 insertions, 0 deletions
diff --git a/docs/_summary.md b/docs/_summary.md
index 2f6309e41..4b528d996 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -72,6 +72,7 @@
72 * [Mod-Tap](mod_tap.md) 72 * [Mod-Tap](mod_tap.md)
73 * [Macros](feature_macros.md) 73 * [Macros](feature_macros.md)
74 * [Mouse Keys](feature_mouse_keys.md) 74 * [Mouse Keys](feature_mouse_keys.md)
75 * [Programmable Button](feature_programmable_button.md)
75 * [Space Cadet Shift](feature_space_cadet.md) 76 * [Space Cadet Shift](feature_space_cadet.md)
76 * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) 77 * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
77 78
diff --git a/docs/feature_programmable_button.md b/docs/feature_programmable_button.md
new file mode 100644
index 000000000..b1ef555d1
--- /dev/null
+++ b/docs/feature_programmable_button.md
@@ -0,0 +1,74 @@
1## Programmable Button
2
3Programmable button is a feature that can be used to send keys that have no
4predefined meaning.
5This means they can be processed on the host side by custom software without
6colliding without the operating system trying to interpret these keys.
7
8The keycodes are emitted according to the HID usage
9"Telephony Device Page" (0x0B), "Programmable button usage" (0x07).
10On Linux (> 5.14) they are handled automatically and translated to `KEY_MACRO#`
11keycodes.
12(Up to `KEY_MACRO30`)
13
14### Enabling Programmable Button support
15
16To enable Programmable Button, add the following line to your keymap’s `rules.mk`:
17
18```c
19PROGRAMMABLE_BUTTON_ENABLE = yes
20```
21
22### Mapping
23
24In your keymap you can use the following keycodes to map key presses to Programmable Buttons:
25
26|Key |Description |
27|------------------------|----------------------|
28|`PROGRAMMABLE_BUTTON_1` |Programmable button 1 |
29|`PROGRAMMABLE_BUTTON_2` |Programmable button 2 |
30|`PROGRAMMABLE_BUTTON_3` |Programmable button 3 |
31|`PROGRAMMABLE_BUTTON_4` |Programmable button 4 |
32|`PROGRAMMABLE_BUTTON_5` |Programmable button 5 |
33|`PROGRAMMABLE_BUTTON_6` |Programmable button 6 |
34|`PROGRAMMABLE_BUTTON_7` |Programmable button 7 |
35|`PROGRAMMABLE_BUTTON_8` |Programmable button 8 |
36|`PROGRAMMABLE_BUTTON_9` |Programmable button 9 |
37|`PROGRAMMABLE_BUTTON_10`|Programmable button 10|
38|`PROGRAMMABLE_BUTTON_11`|Programmable button 11|
39|`PROGRAMMABLE_BUTTON_12`|Programmable button 12|
40|`PROGRAMMABLE_BUTTON_13`|Programmable button 13|
41|`PROGRAMMABLE_BUTTON_14`|Programmable button 14|
42|`PROGRAMMABLE_BUTTON_15`|Programmable button 15|
43|`PROGRAMMABLE_BUTTON_16`|Programmable button 16|
44|`PROGRAMMABLE_BUTTON_17`|Programmable button 17|
45|`PROGRAMMABLE_BUTTON_18`|Programmable button 18|
46|`PROGRAMMABLE_BUTTON_19`|Programmable button 19|
47|`PROGRAMMABLE_BUTTON_20`|Programmable button 20|
48|`PROGRAMMABLE_BUTTON_21`|Programmable button 21|
49|`PROGRAMMABLE_BUTTON_22`|Programmable button 22|
50|`PROGRAMMABLE_BUTTON_23`|Programmable button 23|
51|`PROGRAMMABLE_BUTTON_24`|Programmable button 24|
52|`PROGRAMMABLE_BUTTON_25`|Programmable button 25|
53|`PROGRAMMABLE_BUTTON_26`|Programmable button 26|
54|`PROGRAMMABLE_BUTTON_27`|Programmable button 27|
55|`PROGRAMMABLE_BUTTON_28`|Programmable button 28|
56|`PROGRAMMABLE_BUTTON_29`|Programmable button 29|
57|`PROGRAMMABLE_BUTTON_30`|Programmable button 30|
58|`PROGRAMMABLE_BUTTON_31`|Programmable button 31|
59|`PROGRAMMABLE_BUTTON_32`|Programmable button 32|
60|`PB_1` to `PB_32` |Aliases for keymaps |
61
62### API
63
64You can also use a dedicated API defined in `programmable_button.h` to interact with this feature:
65
66```
67void programmable_button_clear(void);
68void programmable_button_send(void);
69void programmable_button_on(uint8_t code);
70void programmable_button_off(uint8_t code);
71bool programmable_button_is_on(uint8_t code);
72uint32_t programmable_button_get_report(void);
73void programmable_button_set_report(uint32_t report);
74```
diff --git a/docs/keycodes.md b/docs/keycodes.md
index a134c5a1b..770a4525a 100644
--- a/docs/keycodes.md
+++ b/docs/keycodes.md
@@ -677,6 +677,46 @@ See also: [One Shot Keys](one_shot_keys.md)
677|`OS_OFF` |Turns One Shot keys off | 677|`OS_OFF` |Turns One Shot keys off |
678|`OS_TOGG` |Toggles One Shot keys status | 678|`OS_TOGG` |Toggles One Shot keys status |
679 679
680## Programmable Button Support :id=programmable-button
681
682See also: [Programmable Button](feature_programmable_button.md)
683
684|Key |Description |
685|------------------------|----------------------|
686|`PROGRAMMABLE_BUTTON_1` |Programmable button 1 |
687|`PROGRAMMABLE_BUTTON_2` |Programmable button 2 |
688|`PROGRAMMABLE_BUTTON_3` |Programmable button 3 |
689|`PROGRAMMABLE_BUTTON_4` |Programmable button 4 |
690|`PROGRAMMABLE_BUTTON_5` |Programmable button 5 |
691|`PROGRAMMABLE_BUTTON_6` |Programmable button 6 |
692|`PROGRAMMABLE_BUTTON_7` |Programmable button 7 |
693|`PROGRAMMABLE_BUTTON_8` |Programmable button 8 |
694|`PROGRAMMABLE_BUTTON_9` |Programmable button 9 |
695|`PROGRAMMABLE_BUTTON_10`|Programmable button 10|
696|`PROGRAMMABLE_BUTTON_11`|Programmable button 11|
697|`PROGRAMMABLE_BUTTON_12`|Programmable button 12|
698|`PROGRAMMABLE_BUTTON_13`|Programmable button 13|
699|`PROGRAMMABLE_BUTTON_14`|Programmable button 14|
700|`PROGRAMMABLE_BUTTON_15`|Programmable button 15|
701|`PROGRAMMABLE_BUTTON_16`|Programmable button 16|
702|`PROGRAMMABLE_BUTTON_17`|Programmable button 17|
703|`PROGRAMMABLE_BUTTON_18`|Programmable button 18|
704|`PROGRAMMABLE_BUTTON_19`|Programmable button 19|
705|`PROGRAMMABLE_BUTTON_20`|Programmable button 20|
706|`PROGRAMMABLE_BUTTON_21`|Programmable button 21|
707|`PROGRAMMABLE_BUTTON_22`|Programmable button 22|
708|`PROGRAMMABLE_BUTTON_23`|Programmable button 23|
709|`PROGRAMMABLE_BUTTON_24`|Programmable button 24|
710|`PROGRAMMABLE_BUTTON_25`|Programmable button 25|
711|`PROGRAMMABLE_BUTTON_26`|Programmable button 26|
712|`PROGRAMMABLE_BUTTON_27`|Programmable button 27|
713|`PROGRAMMABLE_BUTTON_28`|Programmable button 28|
714|`PROGRAMMABLE_BUTTON_29`|Programmable button 29|
715|`PROGRAMMABLE_BUTTON_30`|Programmable button 30|
716|`PROGRAMMABLE_BUTTON_31`|Programmable button 31|
717|`PROGRAMMABLE_BUTTON_32`|Programmable button 32|
718|`PB_1` to `PB_32` |Aliases for keymaps |
719
680## Space Cadet :id=space-cadet 720## Space Cadet :id=space-cadet
681 721
682See also: [Space Cadet](feature_space_cadet.md) 722See also: [Space Cadet](feature_space_cadet.md)
generated by cgit v1.2.3 (git 2.25.1) at 2025-12-02 21:00:49 +0000