aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/_summary.md1
-rw-r--r--docs/audio_driver.md14
-rw-r--r--docs/cli_commands.md75
-rw-r--r--docs/cli_development.md2
-rw-r--r--docs/configurator_default_keymaps.md4
-rw-r--r--docs/contributing.md2
-rw-r--r--docs/custom_matrix.md2
-rw-r--r--docs/de/cli.md19
-rw-r--r--docs/faq_debug.md4
-rw-r--r--docs/feature_backlight.md12
-rw-r--r--docs/feature_bluetooth.md19
-rw-r--r--docs/feature_digitizer.md2
-rw-r--r--docs/feature_joystick.md2
-rw-r--r--docs/feature_layouts.md2
-rw-r--r--docs/feature_midi.md2
-rw-r--r--docs/feature_pointing_device.md2
-rw-r--r--docs/feature_programmable_button.md74
-rw-r--r--docs/feature_ps2_mouse.md6
-rw-r--r--docs/feature_rawhid.md4
-rw-r--r--docs/feature_rgb_matrix.md12
-rw-r--r--docs/feature_stenography.md2
-rw-r--r--docs/feature_swap_hands.md2
-rw-r--r--docs/feature_userspace.md2
-rw-r--r--docs/flashing_bootloadhid.md2
-rw-r--r--docs/fr-fr/cli.md19
-rw-r--r--docs/getting_started_docker.md10
-rw-r--r--docs/getting_started_vagrant.md8
-rw-r--r--docs/hardware_keyboard_guidelines.md28
-rw-r--r--docs/how_keyboards_work.md2
-rw-r--r--docs/i2c_driver.md17
-rw-r--r--docs/ja/i2c_driver.md11
-rw-r--r--docs/keycodes.md40
-rw-r--r--docs/newbs_git_resynchronize_a_branch.md16
-rw-r--r--docs/unit_testing.md2
34 files changed, 250 insertions, 171 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/audio_driver.md b/docs/audio_driver.md
index 7cd5a98d9..81c339007 100644
--- a/docs/audio_driver.md
+++ b/docs/audio_driver.md
@@ -57,14 +57,14 @@ This driver needs one Timer per enabled/used DAC channel, to trigger conversion;
57 57
58Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8: 58Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8:
59 59
60``` c 60```c
61//halconf.h: 61//halconf.h:
62#define HAL_USE_DAC TRUE 62#define HAL_USE_DAC TRUE
63#define HAL_USE_GPT TRUE 63#define HAL_USE_GPT TRUE
64#include_next <halconf.h> 64#include_next <halconf.h>
65``` 65```
66 66
67``` c 67```c
68// mcuconf.h: 68// mcuconf.h:
69#include_next <mcuconf.h> 69#include_next <mcuconf.h>
70#undef STM32_DAC_USE_DAC1_CH1 70#undef STM32_DAC_USE_DAC1_CH1
@@ -93,14 +93,14 @@ only needs one timer (GPTD6, Tim6) to trigger the DAC unit to do a conversion; t
93 93
94Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6: 94Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6:
95 95
96``` c 96```c
97//halconf.h: 97//halconf.h:
98#define HAL_USE_DAC TRUE 98#define HAL_USE_DAC TRUE
99#define HAL_USE_GPT TRUE 99#define HAL_USE_GPT TRUE
100#include_next <halconf.h> 100#include_next <halconf.h>
101``` 101```
102 102
103``` c 103```c
104// mcuconf.h: 104// mcuconf.h:
105#include_next <mcuconf.h> 105#include_next <mcuconf.h>
106#undef STM32_DAC_USE_DAC1_CH1 106#undef STM32_DAC_USE_DAC1_CH1
@@ -153,7 +153,7 @@ This driver uses the ChibiOS-PWM system to produce a square-wave on specific out
153The hardware directly toggles the pin via its alternate function. See your MCU's data-sheet for which pin can be driven by what timer - looking for TIMx_CHy and the corresponding alternate function. 153The hardware directly toggles the pin via its alternate function. See your MCU's data-sheet for which pin can be driven by what timer - looking for TIMx_CHy and the corresponding alternate function.
154 154
155A configuration example for the STM32F103C8 would be: 155A configuration example for the STM32F103C8 would be:
156``` c 156```c
157//halconf.h: 157//halconf.h:
158#define HAL_USE_PWM TRUE 158#define HAL_USE_PWM TRUE
159#define HAL_USE_PAL TRUE 159#define HAL_USE_PAL TRUE
@@ -161,7 +161,7 @@ A configuration example for the STM32F103C8 would be:
161#include_next <halconf.h> 161#include_next <halconf.h>
162``` 162```
163 163
164``` c 164```c
165// mcuconf.h: 165// mcuconf.h:
166#include_next <mcuconf.h> 166#include_next <mcuconf.h>
167#undef STM32_PWM_USE_TIM1 167#undef STM32_PWM_USE_TIM1
@@ -177,7 +177,7 @@ If we now target pin A8, looking through the data-sheet of the STM32F103C8, for
177- TIM1_CH4 = PA11 177- TIM1_CH4 = PA11
178 178
179with all this information, the configuration would contain these lines: 179with all this information, the configuration would contain these lines:
180``` c 180```c
181//config.h: 181//config.h:
182#define AUDIO_PIN A8 182#define AUDIO_PIN A8
183#define AUDIO_PWM_DRIVER PWMD1 183#define AUDIO_PWM_DRIVER PWMD1
diff --git a/docs/cli_commands.md b/docs/cli_commands.md
index 8fa7ad41d..1427b592f 100644
--- a/docs/cli_commands.md
+++ b/docs/cli_commands.md
@@ -118,54 +118,6 @@ This command lets you configure the behavior of QMK. For the full `qmk config` d
118qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] 118qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
119``` 119```
120 120
121## `qmk console`
122
123This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLE=yes`.
124
125**Usage**:
126
127```
128qmk console [-d <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>]
129```
130
131**Examples**:
132
133Connect to all available keyboards and show their console messages:
134
135```
136qmk console
137```
138
139List all devices:
140
141```
142qmk console -l
143```
144
145Show only messages from clueboard/66/rev3 keyboards:
146
147```
148qmk console -d C1ED:2370
149```
150
151Show only messages from the second clueboard/66/rev3:
152
153```
154qmk console -d C1ED:2370:2
155```
156
157Show timestamps and VID:PID instead of names:
158
159```
160qmk console -n -t
161```
162
163Disable bootloader messages:
164
165```
166qmk console --no-bootloaders
167```
168
169## `qmk doctor` 121## `qmk doctor`
170 122
171This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to. 123This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to.
@@ -368,6 +320,33 @@ qmk format-c
368qmk format-c -b branch_name 320qmk format-c -b branch_name
369``` 321```
370 322
323## `qmk generate-compilation-database`
324
325**Usage**:
326
327```
328qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP]
329```
330
331Creates a `compile_commands.json` file.
332
333Does your IDE/editor use a language server but doesn't _quite_ find all the necessary include files? Do you hate red squigglies? Do you wish your editor could figure out `#include QMK_KEYBOARD_H`? You might need a [compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)! The qmk tool can build this for you.
334
335This command needs to know which keyboard and keymap to build. It uses the same configuration options as the `qmk compile` command: arguments, current directory, and config files.
336
337**Example:**
338
339```
340$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
341$ qmk generate-compilation-database
342Ψ Making clean
343Ψ Gathering build instructions from make -n gh60/satan:colemak
344Ψ Found 50 compile commands
345Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json
346```
347
348Now open your dev environment and live a squiggly-free life.
349
371## `qmk docs` 350## `qmk docs`
372 351
373This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. 352This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
diff --git a/docs/cli_development.md b/docs/cli_development.md
index 0f4f401b3..62be3b3d8 100644
--- a/docs/cli_development.md
+++ b/docs/cli_development.md
@@ -14,7 +14,7 @@ If you intend to maintain keyboards and/or contribute to QMK, you can enable the
14 14
15This will allow you to see all available subcommands. 15This will allow you to see all available subcommands.
16**Note:** You will have to install additional requirements: 16**Note:** You will have to install additional requirements:
17```bash 17```
18python3 -m pip install -r requirements-dev.txt 18python3 -m pip install -r requirements-dev.txt
19``` 19```
20 20
diff --git a/docs/configurator_default_keymaps.md b/docs/configurator_default_keymaps.md
index 30f9fa72f..c52342cf1 100644
--- a/docs/configurator_default_keymaps.md
+++ b/docs/configurator_default_keymaps.md
@@ -20,7 +20,7 @@ Keymaps in this directory require four key-value pairs:
20 20
21Additionally, most keymaps contain a `commit` key. This key is not consumed by the API that back-stops QMK Configurator, but is used by Configurator's maintainers to tell which version of a keymap was used to create the JSON keymap in this repository. The value is the SHA of the last commit to modify a board's default `keymap.c` in the `qmk_firmware` repository. The SHA is found by checking out [the `master` branch of the `qmk/qmk_firmware` repository](https://github.com/qmk/qmk_firmware/tree/master/) and running `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c` (use `keymap.json` if the keyboard in question has this file instead), which should return something similar to: 21Additionally, most keymaps contain a `commit` key. This key is not consumed by the API that back-stops QMK Configurator, but is used by Configurator's maintainers to tell which version of a keymap was used to create the JSON keymap in this repository. The value is the SHA of the last commit to modify a board's default `keymap.c` in the `qmk_firmware` repository. The SHA is found by checking out [the `master` branch of the `qmk/qmk_firmware` repository](https://github.com/qmk/qmk_firmware/tree/master/) and running `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c` (use `keymap.json` if the keyboard in question has this file instead), which should return something similar to:
22 22
23```shell 23```
24f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625) 24f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625)
25``` 25```
26 26
@@ -31,7 +31,7 @@ In this example, `f14629ed1cd7c7ec9089604d64f29a99981558e8` is the value that sh
31 31
32If one wished to add a default keymap for the H87a by Hineybush, one would run the `git log` command above against the H87a's default keymap in `qmk_firmware`: 32If one wished to add a default keymap for the H87a by Hineybush, one would run the `git log` command above against the H87a's default keymap in `qmk_firmware`:
33 33
34```shell 34```
35user ~/qmk_firmware (master) 35user ~/qmk_firmware (master)
36$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c 36$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c
37ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237) 37ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237)
diff --git a/docs/contributing.md b/docs/contributing.md
index 1d68d22d9..eb033d167 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -105,7 +105,7 @@ enum my_keycodes {
105 105
106Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder: 106Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder:
107 107
108 ./bin/qmk docs 108 qmk docs
109 109
110or if you only have Python 3 installed: 110or if you only have Python 3 installed:
111 111
diff --git a/docs/custom_matrix.md b/docs/custom_matrix.md
index cfa900a33..8f6878f94 100644
--- a/docs/custom_matrix.md
+++ b/docs/custom_matrix.md
@@ -15,7 +15,7 @@ The reasons to use this feature include:
15Implementing custom matrix usually involves compilation of an additional source file. It is recommended that for consistency, this file is called `matrix.c`. 15Implementing custom matrix usually involves compilation of an additional source file. It is recommended that for consistency, this file is called `matrix.c`.
16 16
17Add a new file to your keyboard directory: 17Add a new file to your keyboard directory:
18```text 18```
19keyboards/<keyboard>/matrix.c 19keyboards/<keyboard>/matrix.c
20``` 20```
21 21
diff --git a/docs/de/cli.md b/docs/de/cli.md
index 7dc02d505..259aeecf7 100644
--- a/docs/de/cli.md
+++ b/docs/de/cli.md
@@ -51,25 +51,6 @@ Wir suchen nach Freiwilligen, die ein `qmk`-Package für weitere Betriebssysteme
51* Installiere mit einem [virtualenv](https://virtualenv.pypa.io/en/latest/). 51* Installiere mit einem [virtualenv](https://virtualenv.pypa.io/en/latest/).
52* Weise den User an, die Umgebungs-Variable `QMK_HOME` zu setzen, um die Firmware-Quelle anders einzustellen als `~/qmk_firmware`. 52* Weise den User an, die Umgebungs-Variable `QMK_HOME` zu setzen, um die Firmware-Quelle anders einzustellen als `~/qmk_firmware`.
53 53
54# Lokale CLI
55
56Wenn Du die globale CLI nicht verwenden möchtest, beinhaltet `qmk_firmware` auch eine lokale CLI. Du kannst sie hier finden: `qmk_firmware/bin/qmk`. Du kannst den `qmk`-Befehl aus irgendeinem Datei-Verzeichnis ausführen und es wird immer auf dieser Kopie von `qmk_firmware` arbeiten.
57
58**Beispiel**:
59
60```
61$ ~/qmk_firmware/bin/qmk hello
62Ψ Hello, World!
63```
64
65## Einschränkungen der lokalen CLI
66
67Hier ein Vergleich mit der globalen CLI:
68
69* Die lokale CLI unterstützt kein `qmk setup` oder `qmk clone`.
70* Die lokale CLI arbeitet immer innerhalb der selben `qmk_firmware`-Verzeichnisstruktur, auch wenn Du mehrere Repositories geklont hast.
71* Die lokale CLI läuft nicht in einer virtualenv. Daher ist es möglich, dass Abhängigkeiten (dependencies) miteinander in Konflikt kommen/stehen.
72
73# CLI-Befehle 54# CLI-Befehle
74 55
75## `qmk compile` 56## `qmk compile`
diff --git a/docs/faq_debug.md b/docs/faq_debug.md
index 1afa38a62..28b8c8175 100644
--- a/docs/faq_debug.md
+++ b/docs/faq_debug.md
@@ -62,7 +62,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
62``` 62```
63 63
64Example output 64Example output
65```text 65```
66Waiting for device:....... 66Waiting for device:.......
67Listening: 67Listening:
68KL: kc: 169, col: 0, row: 0, pressed: 1 68KL: kc: 169, col: 0, row: 0, pressed: 1
@@ -82,7 +82,7 @@ When testing performance issues, it can be useful to know the frequency at which
82``` 82```
83 83
84Example output 84Example output
85```text 85```
86 > matrix scan frequency: 315 86 > matrix scan frequency: 315
87 > matrix scan frequency: 313 87 > matrix scan frequency: 313
88 > matrix scan frequency: 316 88 > matrix scan frequency: 316
diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md
index d47ecc682..79782cf56 100644
--- a/docs/feature_backlight.md
+++ b/docs/feature_backlight.md
@@ -8,7 +8,7 @@ The MCU can only supply so much current to its GPIO pins. Instead of powering th
8 8
9Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following: 9Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following:
10 10
11```makefile 11```make
12BACKLIGHT_ENABLE = yes 12BACKLIGHT_ENABLE = yes
13``` 13```
14 14
@@ -54,7 +54,7 @@ If backlight breathing is enabled (see below), the following functions are also
54 54
55To select which driver to use, configure your `rules.mk` with the following: 55To select which driver to use, configure your `rules.mk` with the following:
56 56
57```makefile 57```make
58BACKLIGHT_DRIVER = software 58BACKLIGHT_DRIVER = software
59``` 59```
60 60
@@ -87,7 +87,7 @@ This functionality is configured at the keyboard level with the `BACKLIGHT_ON_ST
87 87
88The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be: 88The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
89 89
90```makefile 90```make
91BACKLIGHT_DRIVER = pwm 91BACKLIGHT_DRIVER = pwm
92``` 92```
93 93
@@ -143,7 +143,7 @@ The breathing effect is the same as in the hardware PWM implementation.
143 143
144While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be: 144While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
145 145
146```makefile 146```make
147BACKLIGHT_DRIVER = pwm 147BACKLIGHT_DRIVER = pwm
148``` 148```
149 149
@@ -167,7 +167,7 @@ Currently only hardware PWM is supported, not timer assisted, and does not provi
167 167
168In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your `rules.mk`: 168In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your `rules.mk`:
169 169
170```makefile 170```make
171BACKLIGHT_DRIVER = software 171BACKLIGHT_DRIVER = software
172``` 172```
173 173
@@ -188,7 +188,7 @@ To activate multiple backlight pins, add something like this to your `config.h`,
188 188
189If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using this simple API provided by QMK. To enable, add this to your `rules.mk`: 189If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using this simple API provided by QMK. To enable, add this to your `rules.mk`:
190 190
191```makefile 191```make
192BACKLIGHT_DRIVER = custom 192BACKLIGHT_DRIVER = custom
193``` 193```
194 194
diff --git a/docs/feature_bluetooth.md b/docs/feature_bluetooth.md
index 08e5f24ac..1b6a825e7 100644
--- a/docs/feature_bluetooth.md
+++ b/docs/feature_bluetooth.md
@@ -4,10 +4,10 @@
4 4
5Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input. 5Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input.
6 6
7|Board |Bluetooth Protocol |Connection Type |rules.mk |Bluetooth Chip| 7|Board |Bluetooth Protocol |Connection Type|rules.mk |Bluetooth Chip|
8|----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------| 8|----------------------------------------------------------------|--------------------|---------------|--------------------------------|--------------|
9|Roving Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic | UART |`BLUETOOTH = RN42` | RN-42 | 9|Roving Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic |UART |`BLUETOOTH_DRIVER = RN42` |RN-42 |
10|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy | SPI |`BLUETOOTH = AdafruitBLE` | nRF51822 | 10|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy|SPI |`BLUETOOTH_DRIVER = AdafruitBLE`|nRF51822 |
11 11
12Not Supported Yet but possible: 12Not Supported Yet but possible:
13* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514) 13* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514)
@@ -23,16 +23,17 @@ Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit
23 23
24A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip. 24A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip.
25 25
26
27<!-- FIXME: Document bluetooth support more completely. --> 26<!-- FIXME: Document bluetooth support more completely. -->
28## Bluetooth Rules.mk Options 27## Bluetooth Rules.mk Options
29 28
30The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary.md#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`. 29The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary.md#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`.
31 30
32Use only one of these to enable Bluetooth: 31Add the following to your `rules.mk`:
33* BLUETOOTH_ENABLE = yes (Legacy Option) 32
34* BLUETOOTH = RN42 33```make
35* BLUETOOTH = AdafruitBLE 34BLUETOOTH_ENABLE = yes
35BLUETOOTH_DRIVER = AdafruitBLE # or RN42
36```
36 37
37## Bluetooth Keycodes 38## Bluetooth Keycodes
38 39
diff --git a/docs/feature_digitizer.md b/docs/feature_digitizer.md
index 9b6aeddba..ac2d64f97 100644
--- a/docs/feature_digitizer.md
+++ b/docs/feature_digitizer.md
@@ -4,7 +4,7 @@ The digitizer HID interface allows setting the mouse cursor position at absolute
4 4
5To enable the digitizer interface, add the following line to your rules.mk: 5To enable the digitizer interface, add the following line to your rules.mk:
6 6
7```makefile 7```make
8DIGITIZER_ENABLE = yes 8DIGITIZER_ENABLE = yes
9``` 9```
10 10
diff --git a/docs/feature_joystick.md b/docs/feature_joystick.md
index 95702d6a2..fe33517a1 100644
--- a/docs/feature_joystick.md
+++ b/docs/feature_joystick.md
@@ -15,7 +15,7 @@ or send gamepad reports based on values computed by the keyboard.
15 15
16To use analog input you must first enable it in `rules.mk`: 16To use analog input you must first enable it in `rules.mk`:
17 17
18```makefile 18```make
19JOYSTICK_ENABLE = yes 19JOYSTICK_ENABLE = yes
20JOYSTICK_DRIVER = analog # or 'digital' 20JOYSTICK_DRIVER = analog # or 'digital'
21``` 21```
diff --git a/docs/feature_layouts.md b/docs/feature_layouts.md
index b34fd442d..93d040b55 100644
--- a/docs/feature_layouts.md
+++ b/docs/feature_layouts.md
@@ -25,7 +25,7 @@ The `layouts/default/` and `layouts/community/` are two examples of layout "repo
25 25
26Each layout folder is named (`[a-z0-9_]`) after the physical aspects of the layout, in the most generic way possible, and contains a `readme.md` with the layout to be defined by the keyboard: 26Each layout folder is named (`[a-z0-9_]`) after the physical aspects of the layout, in the most generic way possible, and contains a `readme.md` with the layout to be defined by the keyboard:
27 27
28```md 28```markdown
29# 60_ansi 29# 60_ansi
30 30
31 LAYOUT_60_ansi 31 LAYOUT_60_ansi
diff --git a/docs/feature_midi.md b/docs/feature_midi.md
index ab29d89db..3da5c4940 100644
--- a/docs/feature_midi.md
+++ b/docs/feature_midi.md
@@ -4,7 +4,7 @@
4 4
5First, enable MIDI by adding the following to your `rules.mk`: 5First, enable MIDI by adding the following to your `rules.mk`:
6 6
7```makefile 7```make
8MIDI_ENABLE = yes 8MIDI_ENABLE = yes
9``` 9```
10 10
diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md
index 905c2a8f9..badeadc12 100644
--- a/docs/feature_pointing_device.md
+++ b/docs/feature_pointing_device.md
@@ -4,7 +4,7 @@ Pointing Device is a generic name for a feature intended to be generic: moving t
4 4
5To enable Pointing Device, uncomment the following line in your rules.mk: 5To enable Pointing Device, uncomment the following line in your rules.mk:
6 6
7```makefile 7```make
8POINTING_DEVICE_ENABLE = yes 8POINTING_DEVICE_ENABLE = yes
9``` 9```
10 10
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/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md
index 776a33150..433a47fa9 100644
--- a/docs/feature_ps2_mouse.md
+++ b/docs/feature_ps2_mouse.md
@@ -30,7 +30,7 @@ Note: This is not recommended, you may encounter jerky movement or unsent inputs
30 30
31In rules.mk: 31In rules.mk:
32 32
33```makefile 33```make
34PS2_MOUSE_ENABLE = yes 34PS2_MOUSE_ENABLE = yes
35PS2_USE_BUSYWAIT = yes 35PS2_USE_BUSYWAIT = yes
36``` 36```
@@ -56,7 +56,7 @@ The following example uses D2 for clock and D5 for data. You can use any INT or
56 56
57In rules.mk: 57In rules.mk:
58 58
59```makefile 59```make
60PS2_MOUSE_ENABLE = yes 60PS2_MOUSE_ENABLE = yes
61PS2_USE_INT = yes 61PS2_USE_INT = yes
62``` 62```
@@ -118,7 +118,7 @@ To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data.
118 118
119In rules.mk: 119In rules.mk:
120 120
121```makefile 121```make
122PS2_MOUSE_ENABLE = yes 122PS2_MOUSE_ENABLE = yes
123PS2_USE_USART = yes 123PS2_USE_USART = yes
124``` 124```
diff --git a/docs/feature_rawhid.md b/docs/feature_rawhid.md
index 4a688fcba..558a23a80 100644
--- a/docs/feature_rawhid.md
+++ b/docs/feature_rawhid.md
@@ -15,7 +15,7 @@ RAW_ENABLE = yes
15 15
16In your `keymap.c` include `"raw_hid.h"` and implement the following: 16In your `keymap.c` include `"raw_hid.h"` and implement the following:
17 17
18```C 18```c
19void raw_hid_receive(uint8_t *data, uint8_t length) { 19void raw_hid_receive(uint8_t *data, uint8_t length) {
20 // Your code goes here. data is the packet received from host. 20 // Your code goes here. data is the packet received from host.
21} 21}
@@ -23,7 +23,7 @@ void raw_hid_receive(uint8_t *data, uint8_t length) {
23 23
24The `"raw_hid.h"` header also declares `void raw_hid_send(uint8_t *data, uint8_t length);` which allows sending packets from keyboard to host. As an example, it can also be used for debugging when building your host application by returning all data back to the host. 24The `"raw_hid.h"` header also declares `void raw_hid_send(uint8_t *data, uint8_t length);` which allows sending packets from keyboard to host. As an example, it can also be used for debugging when building your host application by returning all data back to the host.
25 25
26```C 26```c
27void raw_hid_receive(uint8_t *data, uint8_t length) { 27void raw_hid_receive(uint8_t *data, uint8_t length) {
28 raw_hid_send(data, length); 28 raw_hid_send(data, length);
29} 29}
diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md
index 2dbd32fbd..2660aad09 100644
--- a/docs/feature_rgb_matrix.md
+++ b/docs/feature_rgb_matrix.md
@@ -10,7 +10,7 @@ If you want to use single color LED's you should use the [LED Matrix Subsystem](
10 10
11There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`: 11There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
12 12
13```makefile 13```make
14RGB_MATRIX_ENABLE = yes 14RGB_MATRIX_ENABLE = yes
15RGB_MATRIX_DRIVER = IS31FL3731 15RGB_MATRIX_DRIVER = IS31FL3731
16``` 16```
@@ -71,7 +71,7 @@ Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet]
71 71
72There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`: 72There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
73 73
74```makefile 74```make
75RGB_MATRIX_ENABLE = yes 75RGB_MATRIX_ENABLE = yes
76RGB_MATRIX_DRIVER = IS31FL3733 76RGB_MATRIX_DRIVER = IS31FL3733
77``` 77```
@@ -141,7 +141,7 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](
141 141
142There is basic support for addressable RGB matrix lighting with the I2C IS31FL3737 RGB controller. To enable it, add this to your `rules.mk`: 142There is basic support for addressable RGB matrix lighting with the I2C IS31FL3737 RGB controller. To enable it, add this to your `rules.mk`:
143 143
144```makefile 144```make
145RGB_MATRIX_ENABLE = yes 145RGB_MATRIX_ENABLE = yes
146RGB_MATRIX_DRIVER = IS31FL3737 146RGB_MATRIX_DRIVER = IS31FL3737
147``` 147```
@@ -206,7 +206,7 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](
206 206
207There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`: 207There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`:
208 208
209```makefile 209```make
210RGB_MATRIX_ENABLE = yes 210RGB_MATRIX_ENABLE = yes
211RGB_MATRIX_DRIVER = WS2812 211RGB_MATRIX_DRIVER = WS2812
212``` 212```
@@ -226,7 +226,7 @@ Configure the hardware via your `config.h`:
226 226
227There is basic support for APA102 based addressable LED strands. To enable it, add this to your `rules.mk`: 227There is basic support for APA102 based addressable LED strands. To enable it, add this to your `rules.mk`:
228 228
229```makefile 229```make
230RGB_MATRIX_ENABLE = yes 230RGB_MATRIX_ENABLE = yes
231RGB_MATRIX_DRIVER = APA102 231RGB_MATRIX_DRIVER = APA102
232``` 232```
@@ -246,7 +246,7 @@ Configure the hardware via your `config.h`:
246### AW20216 :id=aw20216 246### AW20216 :id=aw20216
247There is basic support for addressable RGB matrix lighting with the SPI AW20216 RGB controller. To enable it, add this to your `rules.mk`: 247There is basic support for addressable RGB matrix lighting with the SPI AW20216 RGB controller. To enable it, add this to your `rules.mk`:
248 248
249```makefile 249```make
250RGB_MATRIX_ENABLE = yes 250RGB_MATRIX_ENABLE = yes
251RGB_MATRIX_DRIVER = AW20216 251RGB_MATRIX_DRIVER = AW20216
252``` 252```
diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md
index af4754ed7..92a5c3f84 100644
--- a/docs/feature_stenography.md
+++ b/docs/feature_stenography.md
@@ -32,7 +32,7 @@ GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything
32 32
33Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them. 33Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them.
34 34
35```makefile 35```make
36STENO_ENABLE = yes 36STENO_ENABLE = yes
37MOUSEKEY_ENABLE = no 37MOUSEKEY_ENABLE = no
38``` 38```
diff --git a/docs/feature_swap_hands.md b/docs/feature_swap_hands.md
index cbc574b6b..b0239bb80 100644
--- a/docs/feature_swap_hands.md
+++ b/docs/feature_swap_hands.md
@@ -6,7 +6,7 @@ The swap-hands action allows support for one-handed typing without requiring a s
6 6
7The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck: 7The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck:
8 8
9```C 9```c
10const keypos_t PROGMEM hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = { 10const keypos_t PROGMEM hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = {
11 {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}}, 11 {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}},
12 {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}}, 12 {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}},
diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md
index 8b001e3ce..115ab7175 100644
--- a/docs/feature_userspace.md
+++ b/docs/feature_userspace.md
@@ -240,7 +240,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
240 240
241For boards that may not have a shift button (such as on a macro pad), we need a way to always include the bootloader option. To do that, add the following to the `rules.mk` in your userspace folder: 241For boards that may not have a shift button (such as on a macro pad), we need a way to always include the bootloader option. To do that, add the following to the `rules.mk` in your userspace folder:
242 242
243```make 243```make
244ifeq ($(strip $(FLASH_BOOTLOADER)), yes) 244ifeq ($(strip $(FLASH_BOOTLOADER)), yes)
245 OPT_DEFS += -DFLASH_BOOTLOADER 245 OPT_DEFS += -DFLASH_BOOTLOADER
246endif 246endif
diff --git a/docs/flashing_bootloadhid.md b/docs/flashing_bootloadhid.md
index 9879ec999..213c7c132 100644
--- a/docs/flashing_bootloadhid.md
+++ b/docs/flashing_bootloadhid.md
@@ -44,7 +44,7 @@ For native Windows flashing, the `bootloadHID.exe` can be used outside of the MS
44 44
45### Linux Manual Installation 45### Linux Manual Installation
461. Install libusb development dependency: 461. Install libusb development dependency:
47 ```bash 47 ```
48 # This depends on OS - for Debian the following works 48 # This depends on OS - for Debian the following works
49 sudo apt-get install libusb-dev 49 sudo apt-get install libusb-dev
50 ``` 50 ```
diff --git a/docs/fr-fr/cli.md b/docs/fr-fr/cli.md
index bfa060f2a..917a9315b 100644
--- a/docs/fr-fr/cli.md
+++ b/docs/fr-fr/cli.md
@@ -48,25 +48,6 @@ Nous recherchons des gens pour créer et maintenir un paquet `qmk` pour plus de
48* Installez en utilisant un virtualenv 48* Installez en utilisant un virtualenv
49* Expliquez à l'utilisateur de définir la variable d'environnement `QMK_Home` pour "check out" les sources du firmware à un autre endroit que `~/qmk_firmware`. 49* Expliquez à l'utilisateur de définir la variable d'environnement `QMK_Home` pour "check out" les sources du firmware à un autre endroit que `~/qmk_firmware`.
50 50
51# CLI locale
52
53Si vous ne voulez pas utiliser la CLI globale, il y a une CLI locale empaquetée avec `qmk_firmware`. Vous pouvez le trouver dans `qmk_firmware/bin/qmk`. Vous pouvez lancer la commande `qmk` depuis n'importe quel répertoire et elle fonctionnera toujours sur cette copie de `qmk_firmware`.
54
55**Exemple**:
56
57```
58$ ~/qmk_firmware/bin/qmk hello
59Ψ Hello, World!
60```
61
62## Limitations de la CLI locale
63
64Il y a quelques limitations à la CLI locale comparé à la globale:
65
66* La CLI locale ne supporte pas `qmk setup` ou `qmk clone`
67* La CLI locale n'opère pas sur le même arbre `qmk_firmware`, même si vous avez plusieurs dépôts clonés.
68* La CLI locale ne s'exécute pas dans un virtualenv, donc il y a des risques que des dépendances seront en conflit
69
70# Les commandes CLI 51# Les commandes CLI
71 52
72## `qmk compile` 53## `qmk compile`
diff --git a/docs/getting_started_docker.md b/docs/getting_started_docker.md
index f9c3b366a..c4da8af96 100644
--- a/docs/getting_started_docker.md
+++ b/docs/getting_started_docker.md
@@ -12,13 +12,13 @@ The main prerequisite is a working `docker` or `podman` install.
12 12
13Acquire a local copy of the QMK's repository (including submodules): 13Acquire a local copy of the QMK's repository (including submodules):
14 14
15```bash 15```
16git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git 16git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
17cd qmk_firmware 17cd qmk_firmware
18``` 18```
19 19
20Run the following command to build a keymap: 20Run the following command to build a keymap:
21```bash 21```
22util/docker_build.sh <keyboard>:<keymap> 22util/docker_build.sh <keyboard>:<keymap>
23# For example: util/docker_build.sh planck/rev6:default 23# For example: util/docker_build.sh planck/rev6:default
24``` 24```
@@ -27,14 +27,14 @@ This will compile the desired keyboard/keymap and leave the resulting `.hex` or
27 27
28There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well: 28There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
29 29
30```bash 30```
31util/docker_build.sh keyboard:keymap:target 31util/docker_build.sh keyboard:keymap:target
32# For example: util/docker_build.sh planck/rev6:default:flash 32# For example: util/docker_build.sh planck/rev6:default:flash
33``` 33```
34 34
35You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use: 35You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:
36 36
37```bash 37```
38util/docker_build.sh 38util/docker_build.sh
39# Reads parameters as input (leave blank for all keyboards/keymaps) 39# Reads parameters as input (leave blank for all keyboards/keymaps)
40``` 40```
@@ -42,7 +42,7 @@ util/docker_build.sh
42You can manually set which container runtime you want to use by setting the `RUNTIME` environment variable to it's name or path. 42You can manually set which container runtime you want to use by setting the `RUNTIME` environment variable to it's name or path.
43By default docker or podman are automatically detected and docker is preferred over podman. 43By default docker or podman are automatically detected and docker is preferred over podman.
44 44
45```bash 45```
46RUNTIME="podman" util/docker_build.sh keyboard:keymap:target 46RUNTIME="podman" util/docker_build.sh keyboard:keymap:target
47``` 47```
48 48
diff --git a/docs/getting_started_vagrant.md b/docs/getting_started_vagrant.md
index 114f87567..b5b5ce153 100644
--- a/docs/getting_started_vagrant.md
+++ b/docs/getting_started_vagrant.md
@@ -31,26 +31,26 @@ The development environment is configured to run the QMK Docker image, `qmkfm/qm
31### Why am I seeing issues under Virtualbox? 31### Why am I seeing issues under Virtualbox?
32Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:** 32Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:**
33 33
34```console 34```
35vagrant plugin install vagrant-vbguest 35vagrant plugin install vagrant-vbguest
36``` 36```
37 37
38### How do I remove an existing environment? 38### How do I remove an existing environment?
39Finished with your environment? From anywhere inside the folder where you checked out this project, Execute: 39Finished with your environment? From anywhere inside the folder where you checked out this project, Execute:
40 40
41```console 41```
42vagrant destroy 42vagrant destroy
43``` 43```
44 44
45### What if I want to use Docker directly? 45### What if I want to use Docker directly?
46Want to benefit from the Vagrant workflow without a virtual machine? The Vagrantfile is configured to bypass running a virtual machine, and run the container directly. Execute the following when bringing up the environment to force the use of Docker: 46Want to benefit from the Vagrant workflow without a virtual machine? The Vagrantfile is configured to bypass running a virtual machine, and run the container directly. Execute the following when bringing up the environment to force the use of Docker:
47```console 47```
48vagrant up --provider=docker 48vagrant up --provider=docker
49``` 49```
50 50
51### How do I access the virtual machine instead of the Docker container? 51### How do I access the virtual machine instead of the Docker container?
52Execute the following to bypass the `vagrant` user booting directly to the official qmk builder image: 52Execute the following to bypass the `vagrant` user booting directly to the official qmk builder image:
53 53
54```console 54```
55vagrant ssh -c 'sudo -i' 55vagrant ssh -c 'sudo -i'
56``` 56```
diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md
index 7630b44e0..f975f37f5 100644
--- a/docs/hardware_keyboard_guidelines.md
+++ b/docs/hardware_keyboard_guidelines.md
@@ -144,10 +144,38 @@ The `rules.mk` file can also be placed in a sub-folder, and its reading order is
144 * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/rules.mk` 144 * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/rules.mk`
145 * `keyboards/top_folder/keymaps/a_keymap/rules.mk` 145 * `keyboards/top_folder/keymaps/a_keymap/rules.mk`
146 * `users/a_user_folder/rules.mk` 146 * `users/a_user_folder/rules.mk`
147 * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/post_rules.mk`
148 * `keyboards/top_folder/sub_1/sub_2/sub_3/post_rules.mk`
149 * `keyboards/top_folder/sub_1/sub_2/post_rules.mk`
150 * `keyboards/top_folder/sub_1/post_rules.mk`
151* `keyboards/top_folder/post_rules.mk`
147* `common_features.mk` 152* `common_features.mk`
148 153
149Many of the settings written in the `rules.mk` file are interpreted by `common_features.mk`, which sets the necessary source files and compiler options. 154Many of the settings written in the `rules.mk` file are interpreted by `common_features.mk`, which sets the necessary source files and compiler options.
150 155
156The `post_rules.mk` file can interpret `features` of a keyboard-level before `common_features.mk`. For example, when your designed keyboard has the option to implement backlighting or underglow using rgblight.c, writing the following in the `post_rules.mk` makes it easier for the user to configure the `rules.mk`.
157
158* `keyboards/top_folder/keymaps/a_keymap/rules.mk`
159 ```make
160 # Please set the following according to the selection of the hardware implementation option.
161 RGBLED_OPTION_TYPE = backlight ## none, backlight or underglow
162 ```
163* `keyboards/top_folder/post_rules.mk`
164 ```make
165 ifeq ($(filter $(strip $(RGBLED_OPTION_TYPE))x, nonex backlightx underglowx x),)
166 $(error unknown RGBLED_OPTION_TYPE value "$(RGBLED_OPTION_TYPE)")
167 endif
168
169 ifeq ($(strip $(RGBLED_OPTION_TYPE)),backlight)
170 RGBLIGHT_ENABLE = yes
171 OPT_DEFS += -DRGBLED_NUM=30
172 endif
173 ifeq ($(strip $(RGBLED_OPTION_TYPE)),underglow)
174 RGBLIGHT_ENABLE = yes
175 OPT_DEFS += -DRGBLED_NUM=6
176 endif
177 ```
178
151?> See `build_keyboard.mk` and `common_features.mk` for more details. 179?> See `build_keyboard.mk` and `common_features.mk` for more details.
152 180
153### `<keyboard_name.c>` 181### `<keyboard_name.c>`
diff --git a/docs/how_keyboards_work.md b/docs/how_keyboards_work.md
index 3dcbc6452..36cbfb4d9 100644
--- a/docs/how_keyboards_work.md
+++ b/docs/how_keyboards_work.md
@@ -9,7 +9,7 @@ firmware directly.
9Whenever you type on 1 particular key, here is the chain of actions taking 9Whenever you type on 1 particular key, here is the chain of actions taking
10place: 10place:
11 11
12``` text 12```
13+------+ +-----+ +----------+ +----------+ +----+ 13+------+ +-----+ +----------+ +----------+ +----+
14| User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS | 14| User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS |
15+------+ +-----+ +----------+ +----------+ +----+ 15+------+ +-----+ +----------+ +----------+ +----+
diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md
index 3ec34a0f8..9017b44ed 100644
--- a/docs/i2c_driver.md
+++ b/docs/i2c_driver.md
@@ -62,16 +62,13 @@ Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, fo
62 62
63Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303. 63Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303.
64 64
65|`config.h` Overrride |Description |Default| 65|`config.h` Overrride |Description |Default|
66|------------------------|-------------------------------------------------------------------------------------------|-------| 66|------------------------|--------------------------------------------------------------|-------|
67|`I2C_DRIVER` |I2C peripheral to use - I2C1 -> `I2CD1`, I2C2 -> `I2CD2` etc. |`I2CD1`| 67|`I2C_DRIVER` |I2C peripheral to use - I2C1 -> `I2CD1`, I2C2 -> `I2CD2` etc. |`I2CD1`|
68|`I2C1_BANK` (deprecated)|The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superseded by `I2C1_SCL_BANK`/`I2C1_SDA_BANK`|`GPIOB`| 68|`I2C1_SCL_PIN` |The pin definition for SCL |`B6` |
69|`I2C1_SCL_BANK` |The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SCL |`GPIOB`| 69|`I2C1_SCL_PAL_MODE` |The alternate function mode for SCL |`4` |
70|`I2C1_SCL` |The pin number for SCL (0-15) |`6` | 70|`I2C1_SDA_PIN` |The pin definition for SDA |`B7` |
71|`I2C1_SCL_PAL_MODE` |The alternate function mode for SCL |`4` | 71|`I2C1_SDA_PAL_MODE` |The alternate function mode for SDA |`4` |
72|`I2C1_SDA_BANK` |The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SDA |`GPIOB`|
73|`I2C1_SDA` |The pin number for SDA (0-15) |`7` |
74|`I2C1_SDA_PAL_MODE` |The alternate function mode for SDA |`4` |
75 72
76The following configuration values depend on the specific MCU in use. 73The following configuration values depend on the specific MCU in use.
77 74
diff --git a/docs/ja/i2c_driver.md b/docs/ja/i2c_driver.md
index 9d348d580..1d8f70e16 100644
--- a/docs/ja/i2c_driver.md
+++ b/docs/ja/i2c_driver.md
@@ -79,13 +79,10 @@ ARM MCU 用の設定はしばしば非常に複雑です。これは、多くの
79 79
80STM32 MCU では、使用するハードウェアドライバにより、さまざまなピンを I2C ピンとして設定できます。標準では `B6`, `B7` ピンが I2C 用のピンです。 I2C 用のピンを設定するために次の定義が使えます: 80STM32 MCU では、使用するハードウェアドライバにより、さまざまなピンを I2C ピンとして設定できます。標準では `B6`, `B7` ピンが I2C 用のピンです。 I2C 用のピンを設定するために次の定義が使えます:
81 81
82| 変数 | 説明 | 既定値 | 82| 変数 | 説明 | 既定値 |
83|-----------------------|--------------------------------------------------------------------------------------------------|---------| 83|-----------------------|-------------------------------------------------------------------------------------------|---------|
84| `I2C1_SCL_BANK` | SCL に使うピンのバンク (`GPIOA`, `GPIOB`, `GPIOC`) | `GPIOB` | 84| `I2C1_SCL_PIN` | SCL のピン番号 | `B6` |
85| `I2C1_SDA_BANK` | SDA に使うピンのバンク (`GPIOA`, `GPIOB`, `GPIOC`) | `GPIOB` | 85| `I2C1_SDA_PIN` | SDA のピン番号 | `B7` |
86| `I2C1_SCL` | SCL のピン番号 (0-15) | `6` |
87| `I2C1_SDA` | SDA のピン番号 (0-15) | `7` |
88| `I2C1_BANK`(非推奨) | 使用するピンのバンク (`GPIOA`, `GPIOB`, `GPIOC`)。後継は `I2C1_SCL_BANK`, `I2C1_SDA_BANK` です。 | `GPIOB` |
89 86
90ChibiOS I2C ドライバの設定項目は STM32 MCU の種類に依存します。 87ChibiOS I2C ドライバの設定項目は STM32 MCU の種類に依存します。
91 88
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)
diff --git a/docs/newbs_git_resynchronize_a_branch.md b/docs/newbs_git_resynchronize_a_branch.md
index 3e7acdba7..1d0e4dda1 100644
--- a/docs/newbs_git_resynchronize_a_branch.md
+++ b/docs/newbs_git_resynchronize_a_branch.md
@@ -8,7 +8,7 @@ Suppose you have committed to your `master` branch, and now need to update your
8 8
9No one wants to lose work if it can be helped. If you want to save the changes you've already made to your `master` branch, the simplest way to do so is to simply create a duplicate of your "dirty" `master` branch: 9No one wants to lose work if it can be helped. If you want to save the changes you've already made to your `master` branch, the simplest way to do so is to simply create a duplicate of your "dirty" `master` branch:
10 10
11```sh 11```
12git branch old_master master 12git branch old_master master
13``` 13```
14 14
@@ -18,7 +18,7 @@ Now you have a branch named `old_master` that is a duplicate of your `master` br
18 18
19Now it's time to resynchronize your `master` branch. For this step, you'll want to have QMK's repository configured as a remote in Git. To check your configured remotes, run `git remote -v`, which should return something similar to: 19Now it's time to resynchronize your `master` branch. For this step, you'll want to have QMK's repository configured as a remote in Git. To check your configured remotes, run `git remote -v`, which should return something similar to:
20 20
21```sh 21```
22QMKuser ~/qmk_firmware (master) 22QMKuser ~/qmk_firmware (master)
23$ git remote -v 23$ git remote -v
24origin https://github.com/<your_username>/qmk_firmware.git (fetch) 24origin https://github.com/<your_username>/qmk_firmware.git (fetch)
@@ -29,7 +29,7 @@ upstream https://github.com/qmk/qmk_firmware.git (push)
29 29
30If you only see one fork referenced: 30If you only see one fork referenced:
31 31
32```sh 32```
33QMKuser ~/qmk_firmware (master) 33QMKuser ~/qmk_firmware (master)
34$ git remote -v 34$ git remote -v
35origin https://github.com/qmk/qmk_firmware.git (fetch) 35origin https://github.com/qmk/qmk_firmware.git (fetch)
@@ -38,31 +38,31 @@ origin https://github.com/qmk/qmk_firmware.git (push)
38 38
39add a new remote with: 39add a new remote with:
40 40
41```sh 41```
42git remote add upstream https://github.com/qmk/qmk_firmware.git 42git remote add upstream https://github.com/qmk/qmk_firmware.git
43``` 43```
44 44
45Then, redirect the `origin` remote to your own fork with: 45Then, redirect the `origin` remote to your own fork with:
46 46
47```sh 47```
48git remote set-url origin https://github.com/<your_username>/qmk_firmware.git 48git remote set-url origin https://github.com/<your_username>/qmk_firmware.git
49``` 49```
50 50
51Now that you have both remotes configured, you need to update the references for the upstream repository, which is QMK's, by running: 51Now that you have both remotes configured, you need to update the references for the upstream repository, which is QMK's, by running:
52 52
53```sh 53```
54git fetch upstream 54git fetch upstream
55``` 55```
56 56
57At this point, resynchronize your branch to QMK's by running: 57At this point, resynchronize your branch to QMK's by running:
58 58
59```sh 59```
60git reset --hard upstream/master 60git reset --hard upstream/master
61``` 61```
62 62
63These steps will update the repository on your computer, but your GitHub fork will still be out of sync. To resynchronize your fork on GitHub, you need to push to your fork, instructing Git to override any remote changes that are not reflected in your local repository. To do this, run: 63These steps will update the repository on your computer, but your GitHub fork will still be out of sync. To resynchronize your fork on GitHub, you need to push to your fork, instructing Git to override any remote changes that are not reflected in your local repository. To do this, run:
64 64
65```sh 65```
66git push --force-with-lease 66git push --force-with-lease
67``` 67```
68 68
diff --git a/docs/unit_testing.md b/docs/unit_testing.md
index a0eef51cb..7310da8d0 100644
--- a/docs/unit_testing.md
+++ b/docs/unit_testing.md
@@ -44,7 +44,7 @@ If there are problems with the tests, you can find the executable in the `./buil
44 44
45To forward any [debug messages](unit_testing.md#debug-api) to `stderr`, the tests can run with `DEBUG=1`. For example 45To forward any [debug messages](unit_testing.md#debug-api) to `stderr`, the tests can run with `DEBUG=1`. For example
46 46
47```console 47```
48make test:all DEBUG=1 48make test:all DEBUG=1
49``` 49```
50 50