aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/_summary.md2
-rw-r--r--docs/breaking_changes.md4
-rw-r--r--docs/chibios_upgrade_instructions.md56
-rw-r--r--docs/cli_commands.md29
-rw-r--r--docs/cli_development.md4
-rw-r--r--docs/compatible_microcontrollers.md2
-rw-r--r--docs/config_options.md33
-rw-r--r--docs/custom_quantum_functions.md8
-rw-r--r--docs/de/cli.md8
-rw-r--r--docs/driver_installation_zadig.md1
-rw-r--r--docs/eeprom_driver.md3
-rw-r--r--docs/feature_debounce_type.md4
-rw-r--r--docs/feature_dip_switch.md16
-rw-r--r--docs/feature_haptic_feedback.md26
-rw-r--r--docs/feature_key_overrides.md229
-rw-r--r--docs/feature_led_matrix.md29
-rw-r--r--docs/feature_oled_driver.md4
-rw-r--r--docs/feature_rgb_matrix.md168
-rw-r--r--docs/feature_rgblight.md51
-rw-r--r--docs/feature_split_keyboard.md122
-rw-r--r--docs/feature_st7565.md274
-rw-r--r--docs/feature_tap_dance.md2
-rw-r--r--docs/flashing.md46
-rw-r--r--docs/fr-fr/cli.md8
-rw-r--r--docs/ja/cli_commands.md14
-rw-r--r--docs/ja/cli_development.md4
-rw-r--r--docs/ja/compatible_microcontrollers.md2
-rw-r--r--docs/ja/feature_dip_switch.md16
-rw-r--r--docs/ja/feature_encoders.md10
-rw-r--r--docs/ja/feature_tap_dance.md2
-rw-r--r--docs/ja/reference_configurator_support.md2
-rw-r--r--docs/ja/reference_info_json.md4
-rw-r--r--docs/reference_configurator_support.md2
-rw-r--r--docs/reference_info_json.md4
-rw-r--r--docs/serial_driver.md15
-rw-r--r--docs/syllabus.md1
-rw-r--r--docs/understanding_qmk.md1
-rw-r--r--docs/zh-cn/custom_quantum_functions.md6
38 files changed, 1023 insertions, 189 deletions
diff --git a/docs/_summary.md b/docs/_summary.md
index 9798ef512..6c39aeda0 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -77,6 +77,7 @@
77 * [Combos](feature_combo.md) 77 * [Combos](feature_combo.md)
78 * [Debounce API](feature_debounce_type.md) 78 * [Debounce API](feature_debounce_type.md)
79 * [Key Lock](feature_key_lock.md) 79 * [Key Lock](feature_key_lock.md)
80 * [Key Overrides](feature_key_overrides.md)
80 * [Layers](feature_layers.md) 81 * [Layers](feature_layers.md)
81 * [One Shot Keys](one_shot_keys.md) 82 * [One Shot Keys](one_shot_keys.md)
82 * [Pointing Device](feature_pointing_device.md) 83 * [Pointing Device](feature_pointing_device.md)
@@ -93,6 +94,7 @@
93 * Hardware Features 94 * Hardware Features
94 * Displays 95 * Displays
95 * [HD44780 LCD Controller](feature_hd44780.md) 96 * [HD44780 LCD Controller](feature_hd44780.md)
97 * [ST7565 LCD Driver](feature_st7565.md)
96 * [OLED Driver](feature_oled_driver.md) 98 * [OLED Driver](feature_oled_driver.md)
97 * Lighting 99 * Lighting
98 * [Backlight](feature_backlight.md) 100 * [Backlight](feature_backlight.md)
diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md
index b0d56a81b..a1a56bd45 100644
--- a/docs/breaking_changes.md
+++ b/docs/breaking_changes.md
@@ -100,3 +100,7 @@ This happens immediately after the previous `develop` branch is merged.
100 * [ ] `git pull --ff-only` 100 * [ ] `git pull --ff-only`
101 * [ ] `git merge --no-ff develop` 101 * [ ] `git merge --no-ff develop`
102 * [ ] `git push upstream master` 102 * [ ] `git push upstream master`
103
104## Post-merge operations
105
106* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions.md)
diff --git a/docs/chibios_upgrade_instructions.md b/docs/chibios_upgrade_instructions.md
new file mode 100644
index 000000000..40c2faafc
--- /dev/null
+++ b/docs/chibios_upgrade_instructions.md
@@ -0,0 +1,56 @@
1# ChibiOS Upgrade Procedure
2
3ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a branch tied to the ChibiOS version in use and should not be mixed with different versions.
4
5## Getting ChibiOS
6
7* `svn` Initialisation:
8 * Only needed to be done once
9 * You might need to separately install `git-svn` package in your OS's package manager
10 * `git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/`
11 * `git remote add qmk git@github.com:qmk/ChibiOS.git`
12* Updating:
13 * `git svn fetch`
14 * First time around this will take several hours
15 * Subsequent updates will be incremental only
16* Tagging example (work out which version first!):
17 * `git tag -a ver20.3.3 -m ver20.3.3 svn/tags/ver20.3.3`
18 * `git push qmk ver20.3.3`
19 * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN svn/tags/ver20.3.3`
20 * `git push qmk breaking_YYYY_qN`
21
22## Getting ChibiOS-Contrib
23
24* `git` Initialisation:
25 * `git clone git@github.com:qmk/ChibiOS-Contrib`
26 * `git remote add upstream https://github.com/ChibiOS/ChibiOS-Contrib`
27 * `git checkout -b chibios-20.3.x upstream/chibios-20.3.x`
28* Updating:
29 * `git fetch --all --tags --prune`
30 * `git checkout chibios-20.3.x`
31 * `git pull --ff-only`
32 * `git push origin chibios-20.3.x`
33 * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN chibios-20.3.x`
34 * `git push origin breaking_YYYY_qN`
35
36## Updating submodules
37
38* Update the submodules
39 * `cd $QMK_FIRMWARE`
40 * `git checkout develop`
41 * `git pull --ff-only`
42 * `git checkout -b chibios-version-bump`
43 * `cd lib/chibios`
44 * `git fetch --all --tags --prune`
45 * `git checkout breaking_YYYY_qN`
46 * `cd ../chibios-contrib`
47 * `git fetch --all --tags --prune`
48 * `git checkout breaking_YYYY_qN`
49* Build everything
50 * `cd $QMK_FIRMWARE`
51 * `qmk multibuild -j4`
52 * Make sure there are no errors
53* Push to the repo
54 * `git commit -am 'Update ChibiOS to XXXXXXXXX'`
55 * `git push --set-upstream origin chibios-version-bump`
56* Make a PR to qmk_firmware with the new branch \ No newline at end of file
diff --git a/docs/cli_commands.md b/docs/cli_commands.md
index 4e27622c7..314e7448d 100644
--- a/docs/cli_commands.md
+++ b/docs/cli_commands.md
@@ -109,7 +109,7 @@ qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
109 109
110## `qmk console` 110## `qmk console`
111 111
112This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLED=yes`. 112This 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`.
113 113
114**Usage**: 114**Usage**:
115 115
@@ -314,7 +314,18 @@ qmk clean [-a]
314 314
315# Developer Commands 315# Developer Commands
316 316
317## `qmk cformat` 317## `qmk format-text`
318
319This command formats text files to have proper line endings.
320
321Every text file in the repository needs to have Unix (LF) line ending.
322If you are working on **Windows**, you must ensure that line endings are corrected in order to get your PRs merged.
323
324```
325qmk format-text
326```
327
328## `qmk format-c`
318 329
319This command formats C code using clang-format. 330This command formats C code using clang-format.
320 331
@@ -325,25 +336,25 @@ Run it with `-a` to format all core code, or pass filenames on the command line
325**Usage for specified files**: 336**Usage for specified files**:
326 337
327``` 338```
328qmk cformat [file1] [file2] [...] [fileN] 339qmk format-c [file1] [file2] [...] [fileN]
329``` 340```
330 341
331**Usage for all core files**: 342**Usage for all core files**:
332 343
333``` 344```
334qmk cformat -a 345qmk format-c -a
335``` 346```
336 347
337**Usage for only changed files against origin/master**: 348**Usage for only changed files against origin/master**:
338 349
339``` 350```
340qmk cformat 351qmk format-c
341``` 352```
342 353
343**Usage for only changed files against branch_name**: 354**Usage for only changed files against branch_name**:
344 355
345``` 356```
346qmk cformat -b branch_name 357qmk format-c -b branch_name
347``` 358```
348 359
349## `qmk docs` 360## `qmk docs`
@@ -369,7 +380,7 @@ qmk generate-docs
369 380
370## `qmk generate-rgb-breathe-table` 381## `qmk generate-rgb-breathe-table`
371 382
372This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/`. 383This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/rgblight/`.
373 384
374**Usage**: 385**Usage**:
375 386
@@ -399,14 +410,14 @@ $ qmk kle2json -f kle.txt -f
399Ψ Wrote out to info.json 410Ψ Wrote out to info.json
400``` 411```
401 412
402## `qmk pyformat` 413## `qmk format-python`
403 414
404This command formats python code in `qmk_firmware`. 415This command formats python code in `qmk_firmware`.
405 416
406**Usage**: 417**Usage**:
407 418
408``` 419```
409qmk pyformat 420qmk format-python
410``` 421```
411 422
412## `qmk pytest` 423## `qmk pytest`
diff --git a/docs/cli_development.md b/docs/cli_development.md
index 07c8f281b..0f4f401b3 100644
--- a/docs/cli_development.md
+++ b/docs/cli_development.md
@@ -188,7 +188,7 @@ cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.ou
188 188
189# Testing, and Linting, and Formatting (oh my!) 189# Testing, and Linting, and Formatting (oh my!)
190 190
191We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `pyformat` subcommands to run these tests: 191We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `format-py` subcommands to run these tests:
192 192
193### Testing and Linting 193### Testing and Linting
194 194
@@ -196,7 +196,7 @@ We use nose2, flake8, and yapf to test, lint, and format code. You can use the `
196 196
197### Formatting 197### Formatting
198 198
199 qmk pyformat 199 qmk format-py
200 200
201## Formatting Details 201## Formatting Details
202 202
diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md
index 0f5b140de..865b29fee 100644
--- a/docs/compatible_microcontrollers.md
+++ b/docs/compatible_microcontrollers.md
@@ -31,6 +31,8 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s
31 * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) 31 * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html)
32 * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) 32 * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html)
33 * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) 33 * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html)
34 * [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
35 * [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
34 * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) 36 * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
35 * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) 37 * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
36 38
diff --git a/docs/config_options.md b/docs/config_options.md
index d0f0b316e..0c98b3101 100644
--- a/docs/config_options.md
+++ b/docs/config_options.md
@@ -51,8 +51,10 @@ This is a C header file that is one of the first things included, and will persi
51 * the number of columns in your keyboard's matrix 51 * the number of columns in your keyboard's matrix
52* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` 52* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
53 * pins of the rows, from top to bottom 53 * pins of the rows, from top to bottom
54 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
54* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` 55* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
55 * pins of the columns, from left to right 56 * pins of the columns, from left to right
57 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
56* `#define MATRIX_IO_DELAY 30` 58* `#define MATRIX_IO_DELAY 30`
57 * the delay in microseconds when between changing matrix pin state and reading values 59 * the delay in microseconds when between changing matrix pin state and reading values
58* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }` 60* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
@@ -193,6 +195,8 @@ If you define these options you will enable the associated feature, which may in
193 * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds. 195 * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds.
194* `#define TAP_HOLD_CAPS_DELAY 80` 196* `#define TAP_HOLD_CAPS_DELAY 80`
195 * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher. 197 * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher.
198* `#define KEY_OVERRIDE_REPEAT_DELAY 500`
199 * Sets the key repeat interval for [key overrides](feature_key_overrides.md).
196 200
197## RGB Light Configuration 201## RGB Light Configuration
198 202
@@ -272,7 +276,7 @@ There are a few different ways to set handedness for split keyboards (listed in
272### Other Options 276### Other Options
273 277
274* `#define USE_I2C` 278* `#define USE_I2C`
275 * For using I2C instead of Serial (defaults to serial) 279 * For using I2C instead of Serial (default is serial; serial transport is supported on ARM -- I2C is AVR-only)
276 280
277* `#define SOFT_SERIAL_PIN D0` 281* `#define SOFT_SERIAL_PIN D0`
278 * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`. 282 * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
@@ -280,6 +284,7 @@ There are a few different ways to set handedness for split keyboards (listed in
280* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }` 284* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
281* `#define MATRIX_COL_PINS_RIGHT { <col pins> }` 285* `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
282 * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns. 286 * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns.
287 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
283 288
284* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` 289* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
285 * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`. 290 * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`.
@@ -300,7 +305,7 @@ There are a few different ways to set handedness for split keyboards (listed in
300* `#define SPLIT_USB_DETECT` 305* `#define SPLIT_USB_DETECT`
301 * Detect (with timeout) USB connection when delegating master/slave 306 * Detect (with timeout) USB connection when delegating master/slave
302 * Default behavior for ARM 307 * Default behavior for ARM
303 * Required for AVR Teensy 308 * Required for AVR Teensy (without hardware mods)
304 309
305* `#define SPLIT_USB_TIMEOUT 2000` 310* `#define SPLIT_USB_TIMEOUT 2000`
306 * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT` 311 * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`
@@ -308,6 +313,28 @@ There are a few different ways to set handedness for split keyboards (listed in
308* `#define SPLIT_USB_TIMEOUT_POLL 10` 313* `#define SPLIT_USB_TIMEOUT_POLL 10`
309 * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT` 314 * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
310 315
316* `#define FORCED_SYNC_THROTTLE_MS 100`
317 * Deadline for synchronizing data from master to slave when using the QMK-provided split transport.
318
319* `#define SPLIT_TRANSPORT_MIRROR`
320 * Mirrors the master-side matrix on the slave when using the QMK-provided split transport.
321
322* `#define SPLIT_LAYER_STATE_ENABLE`
323 * Ensures the current layer state is available on the slave when using the QMK-provided split transport.
324
325* `#define SPLIT_LED_STATE_ENABLE`
326 * Ensures the current host indicator state (caps/num/scroll) is available on the slave when using the QMK-provided split transport.
327
328* `#define SPLIT_MODS_ENABLE`
329 * Ensures the current modifier state (normal, weak, and oneshot) is available on the slave when using the QMK-provided split transport.
330
331* `#define SPLIT_WPM_ENABLE`
332 * Ensures the current WPM is available on the slave when using the QMK-provided split transport.
333
334* `#define SPLIT_TRANSACTION_IDS_KB .....`
335* `#define SPLIT_TRANSACTION_IDS_USER .....`
336 * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information.
337
311# The `rules.mk` File 338# The `rules.mk` File
312 339
313This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features. 340This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
@@ -375,6 +402,8 @@ Use these to enable or disable building certain features. The more you have enab
375 * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work 402 * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
376* `AUDIO_ENABLE` 403* `AUDIO_ENABLE`
377 * Enable the audio subsystem. 404 * Enable the audio subsystem.
405* `KEY_OVERRIDE_ENABLE`
406 * Enable the key override feature
378* `RGBLIGHT_ENABLE` 407* `RGBLIGHT_ENABLE`
379 * Enable keyboard underlight functionality 408 * Enable keyboard underlight functionality
380* `LEADER_ENABLE` 409* `LEADER_ENABLE`
diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md
index 694b421e7..30c637bb4 100644
--- a/docs/custom_quantum_functions.md
+++ b/docs/custom_quantum_functions.md
@@ -144,6 +144,14 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw
144* Keyboard/Revision: `void matrix_init_kb(void)` 144* Keyboard/Revision: `void matrix_init_kb(void)`
145* Keymap: `void matrix_init_user(void)` 145* Keymap: `void matrix_init_user(void)`
146 146
147### Low-level Matrix Overrides Function Documentation :id=low-level-matrix-overrides
148
149* GPIO pin initialisation: `void matrix_init_pins(void)`
150 * This needs to perform the low-level initialisation of all row and column pins. By default this will initialise the input/output state of each of the GPIO pins listed in `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no initialisation of pin state will occur within QMK itself, instead deferring to the keyboard's override.
151* `COL2ROW`-based row reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)`
152* `ROW2COL`-based column reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
153* `DIRECT_PINS`-based reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
154 * These three functions need to perform the low-level retrieval of matrix state of relevant input pins, based on the matrix type. Only one of the functions should be implemented, if needed. By default this will iterate through `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, configuring the inputs and outputs based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no manipulation of matrix GPIO pin state will occur within QMK itself, instead deferring to the keyboard's override.
147 155
148## Keyboard Post Initialization code 156## Keyboard Post Initialization code
149 157
diff --git a/docs/de/cli.md b/docs/de/cli.md
index 437062ad6..7dc02d505 100644
--- a/docs/de/cli.md
+++ b/docs/de/cli.md
@@ -88,14 +88,14 @@ qmk compile <configuratorExport.json>
88qmk compile -kb <keyboard_name> -km <keymap_name> 88qmk compile -kb <keyboard_name> -km <keymap_name>
89``` 89```
90 90
91## `qmk cformat` 91## `qmk format-c`
92 92
93Dieser Befehl formatiert C-Code im clang-Format. Benutze ihn ohne Argumente, um den core-Code zu formatieren, oder benutze Namen von Dateien in der CLI, um den Befehl auf bestimmte Dateien anzuwenden. 93Dieser Befehl formatiert C-Code im clang-Format. Benutze ihn ohne Argumente, um den core-Code zu formatieren, oder benutze Namen von Dateien in der CLI, um den Befehl auf bestimmte Dateien anzuwenden.
94 94
95**Anwendung**: 95**Anwendung**:
96 96
97``` 97```
98qmk cformat [file1] [file2] [...] [fileN] 98qmk format-c [file1] [file2] [...] [fileN]
99``` 99```
100 100
101## `qmk config` 101## `qmk config`
@@ -148,14 +148,14 @@ Dieser Befehl erstellt eine neue Keymap basierend auf einer existierenden Standa
148qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] 148qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
149``` 149```
150 150
151## `qmk pyformat` 151## `qmk format-py`
152 152
153Dieser Befehl formatiert Python-Code in `qmk_firmware`. 153Dieser Befehl formatiert Python-Code in `qmk_firmware`.
154 154
155**Anwendung**: 155**Anwendung**:
156 156
157``` 157```
158qmk pyformat 158qmk format-py
159``` 159```
160 160
161## `qmk pytest` 161## `qmk pytest`
diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md
index fd5d3e92f..e4db069f1 100644
--- a/docs/driver_installation_zadig.md
+++ b/docs/driver_installation_zadig.md
@@ -95,3 +95,4 @@ The device name here is the name that appears in Zadig, and may not be what the
95|`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB | 95|`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB |
96|`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB | 96|`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB |
97|`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB | 97|`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB |
98|`qmk-hid` |(keyboard name) Bootloader |`03EB:2067` |HidUsb |
diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md
index e2c262546..6dcf10c04 100644
--- a/docs/eeprom_driver.md
+++ b/docs/eeprom_driver.md
@@ -31,6 +31,9 @@ Currently QMK supports 24xx-series chips over I2C. As such, requires a working i
31`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32 31`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32
32`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2 32`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2
33`#define EXTERNAL_EEPROM_WRITE_TIME` | Write cycle time of the EEPROM, as specified in the datasheet | 5 33`#define EXTERNAL_EEPROM_WRITE_TIME` | Write cycle time of the EEPROM, as specified in the datasheet | 5
34`#define EXTERNAL_EEPROM_WP_PIN` | If defined the WP pin will be toggled appropriately when writing to the EEPROM. | _none_
35
36Some I2C EEPROM manufacturers explicitly recommend against hardcoding the WP pin to ground. This is in order to protect the eeprom memory content during power-up/power-down/brown-out conditions at low voltage where the eeprom is still operational, but the i2c master output might be unpredictable. If a WP pin is configured, then having an external pull-up on the WP pin is recommended.
34 37
35Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`. 38Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`.
36 39
diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md
index 3ad74224c..306185fe8 100644
--- a/docs/feature_debounce_type.md
+++ b/docs/feature_debounce_type.md
@@ -121,16 +121,16 @@ DEBOUNCE_TYPE = <name of algorithm>
121Where name of algorithm is one of: 121Where name of algorithm is one of:
122* ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed. 122* ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed.
123 * This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant. 123 * This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant.
124* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. 124* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row.
125For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be 125For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
126appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use. 126appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
127* ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key 127* ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
128* ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed. 128* ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed.
129* ```asym_eager_defer_pk``` - debouncing per key. On a key-down state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key-up status change is pushed.
129 130
130### A couple algorithms that could be implemented in the future: 131### A couple algorithms that could be implemented in the future:
131* ```sym_defer_pr``` 132* ```sym_defer_pr```
132* ```sym_eager_g``` 133* ```sym_eager_g```
133* ```asym_eager_defer_pk```
134 134
135### Use your own debouncing code 135### Use your own debouncing code
136You have the option to implement you own debouncing algorithm. To do this: 136You have the option to implement you own debouncing algorithm. To do this:
diff --git a/docs/feature_dip_switch.md b/docs/feature_dip_switch.md
index 15e449c4c..43a6a3faf 100644
--- a/docs/feature_dip_switch.md
+++ b/docs/feature_dip_switch.md
@@ -23,8 +23,9 @@ or
23The callback functions can be inserted into your `<keyboard>.c`: 23The callback functions can be inserted into your `<keyboard>.c`:
24 24
25```c 25```c
26void dip_switch_update_kb(uint8_t index, bool active) { 26bool dip_switch_update_kb(uint8_t index, bool active) {
27 dip_switch_update_user(index, active); 27 if (!dip_switch_update_user(index, active)) { return false; }
28 return true;
28} 29}
29``` 30```
30 31
@@ -32,7 +33,7 @@ void dip_switch_update_kb(uint8_t index, bool active) {
32or `keymap.c`: 33or `keymap.c`:
33 34
34```c 35```c
35void dip_switch_update_user(uint8_t index, bool active) { 36bool dip_switch_update_user(uint8_t index, bool active) {
36 switch (index) { 37 switch (index) {
37 case 0: 38 case 0:
38 if(active) { audio_on(); } else { audio_off(); } 39 if(active) { audio_on(); } else { audio_off(); }
@@ -57,6 +58,7 @@ void dip_switch_update_user(uint8_t index, bool active) {
57 } 58 }
58 break; 59 break;
59 } 60 }
61 return true;
60} 62}
61``` 63```
62 64
@@ -64,8 +66,9 @@ Additionally, we support bit mask functions which allow for more complex handlin
64 66
65 67
66```c 68```c
67void dip_switch_update_mask_kb(uint32_t state) { 69bool dip_switch_update_mask_kb(uint32_t state) {
68 dip_switch_update_mask_user(state); 70 if (!dip_switch_update_mask_user(state)) { return false; }
71 return true;
69} 72}
70``` 73```
71 74
@@ -73,7 +76,7 @@ void dip_switch_update_mask_kb(uint32_t state) {
73or `keymap.c`: 76or `keymap.c`:
74 77
75```c 78```c
76void dip_switch_update_mask_user(uint32_t state) { 79bool dip_switch_update_mask_user(uint32_t state) {
77 if (state & (1UL<<0) && state & (1UL<<1)) { 80 if (state & (1UL<<0) && state & (1UL<<1)) {
78 layer_on(_ADJUST); // C on esc 81 layer_on(_ADJUST); // C on esc
79 } else { 82 } else {
@@ -89,6 +92,7 @@ void dip_switch_update_mask_user(uint32_t state) {
89 } else { 92 } else {
90 layer_off(_TEST_B); 93 layer_off(_TEST_B);
91 } 94 }
95 return true;
92} 96}
93``` 97```
94 98
diff --git a/docs/feature_haptic_feedback.md b/docs/feature_haptic_feedback.md
index a092e784c..469c9c798 100644
--- a/docs/feature_haptic_feedback.md
+++ b/docs/feature_haptic_feedback.md
@@ -162,4 +162,28 @@ This will set what sequence HPT_RST will set as the active mode. If not defined,
162 162
163### DRV2605L Continuous Haptic Mode 163### DRV2605L Continuous Haptic Mode
164 164
165This mode sets continuous haptic feedback with the option to increase or decrease strength. 165This mode sets continuous haptic feedback with the option to increase or decrease strength.
166
167## Haptic Key Exclusion
168The Haptic Exclusion is implemented as `__attribute__((weak)) bool get_haptic_enabled_key(uint16_t keycode, keyrecord_t *record)` in haptic.c. This allows a re-definition at the required level with the specific requirement / exclusion.
169
170### NO_HAPTIC_MOD
171With the entry of `#define NO_HAPTIC_MOD` in config.h, modifiers from Left Control to Right GUI will not trigger a feedback. This also includes modifiers in a Mod Tap configuration.
172
173### NO_HAPTIC_FN
174With the entry of `#define NO_HAPTIC_FN` in config.h, layer keys will not rigger a feedback.
175
176### NO_HAPTIC_ALPHA
177With the entry of `#define NO_HAPTIC_ALPHA` in config.h, none of the alpha keys (A ... Z) will trigger a feedback.
178
179### NO_HAPTIC_PUNCTUATION
180With the entry of `#define NO_HAPTIC_PUNCTUATION` in config.h, none of the following keys will trigger a feedback: Enter, ESC, Backspace, Space, Minus, Equal, Left Bracket, Right Bracket, Backslash, Non-US Hash, Semicolon, Quote, Grave, Comma, Slash, Dot, Non-US Backslash.
181
182### NO_HAPTIC_LOCKKEYS
183With the entry of `#define NO_HAPTIC_LOCKKEYS` in config.h, none of the following keys will trigger a feedback: Caps Lock, Scroll Lock, Num Lock.
184
185### NO_HAPTIC_NAV
186With the entry of `#define NO_HAPTIC_NAV` in config.h, none of the following keys will trigger a feedback: Print Screen, Pause, Insert, Delete, Page Down, Page Up, Left Arrow, Up Arrow, Right Arrow, Down Arrow, End, Home.
187
188### NO_HAPTIC_NUMERIC
189With the entry of `#define NO_HAPTIC_NUMERIC` in config.h, none of the following keys between 0 and 9 (KC_1 ... KC_0) will trigger a feedback. \ No newline at end of file
diff --git a/docs/feature_key_overrides.md b/docs/feature_key_overrides.md
new file mode 100644
index 000000000..861c4bef5
--- /dev/null
+++ b/docs/feature_key_overrides.md
@@ -0,0 +1,229 @@
1# Key Overrides
2
3Key overrides allow you to override modifier-key combinations to send a different modifier-key combination or perform completely custom actions. Don't want `shift` + `1` to type `!` on your computer? Use a key override to make your keyboard type something different when you press `shift` + `1`. The general behavior is like this: If `modifiers w` + `key x` are pressed, replace these keys with `modifiers y` + `key z` in the keyboard report.
4
5You can use key overrides in a similar way to momentary layer/fn keys to activate custom keycodes/shortcuts, with a number of benefits: You completely keep the original use of the modifier keys, while being able to save space by removing fn keys from your keyboard. You can also easily configure _combinations of modifiers_ to trigger different actions than individual modifiers, and much more. The possibilities are quite vast and this documentation contains a few examples for inspiration throughout.
6
7##### A few more examples to get started: You could use key overrides to...
8- Send `brightness up/down` when pressing `ctrl` + `volume up/down`.
9- Send `delete` when pressing `shift` + `backspace`.
10- Create custom shortcuts or change existing ones: E.g. Send `ctrl`+`shift`+`z` when `ctrl`+`y` is pressed.
11- Run custom code when `ctrl` + `alt` + `esc` is pressed.
12
13## Setup
14
15To enable this feature, you need to add `KEY_OVERRIDE_ENABLE = yes` to your `rules.mk`.
16
17Then, in your `keymap.c` file, you'll need to define the array `key_overrides`, which defines all key overrides to be used. Each override is a value of type `key_override_t`. The array `key_overrides` is `NULL`-terminated and contains pointers to `key_override_t` values (`const key_override_t **`).
18
19## Creating Key Overrides
20
21The `key_override_t` struct has many options that allow you to precisely tune your overrides. The full reference is shown below. Instead of manually creating a `key_override_t` value, it is recommended to use these dedicated initializers:
22
23#### `ko_make_basic(modifiers, key, replacement)`
24Returns a `key_override_t`, which sends `replacement` (can be a key-modifer combination), when `key` and `modifiers` are all pressed down. This override still activates if any additional modifiers not specified in `modifiers` are also pressed down. See `ko_make_with_layers_and_negmods` to customize this behavior.
25
26#### `ko_make_with_layers(modifiers, key, replacement, layers)`
27Additionally takes a bitmask `layers` that defines on which layers the override is used.
28
29#### `ko_make_with_layers_and_negmods(modifiers, key, replacement, layers, negative_mods)`
30Additionally takes a bitmask `negative_mods` that defines which modifiers may not be pressed for this override to activate.
31
32#### `ko_make_with_layers_negmods_and_options(modifiers, key, replacement, layers, negative_mods, options)`
33Additionally takes a bitmask `options` that specifies additional options. See `ko_option_t` for available options.
34
35For more customization possibilities, you may directly create a `key_override_t`, which allows you to customize even more behavior. Read further below for details and examples.
36
37## Simple Example
38
39This shows how the mentioned example of sending `delete` when `shift` + `backspace` are pressed is realized:
40
41```c
42const key_override_t delete_key_override = ko_make_basic(MOD_MASK_SHIFT, KC_BSPACE, KC_DELETE);
43
44// This globally defines all key overrides to be used
45const key_override_t **key_overrides = (const key_override_t *[]){
46 &delete_key_override,
47 NULL // Null terminate the array of overrides!
48};
49```
50
51## Intermediate Difficulty Examples
52
53### Media Controls & Screen Brightness
54
55In this example a single key is configured to control media, volume and screen brightness by using key overrides.
56
57- The key is set to send `play/pause` in the keymap.
58
59The following key overrides will be configured:
60
61- `Ctrl` + `play/pause` will send `next track`.
62- `Ctrl` + `Shift` + `play/pause` will send `previous track`.
63- `Alt` + `play/pause` will send `volume up`.
64- `Alt` + `Shift` + `play/pause` will send `volume down`.
65- `Ctrl` + `Alt` + `play/pause` will send `brightness up`.
66- `Ctrl` + `Alt` + `Shift` + `play/pause` will send `brightness down`.
67
68
69```c
70const key_override_t next_track_override =
71 ko_make_with_layers_negmods_and_options(
72 MOD_MASK_CTRL, // Trigger modifiers: ctrl
73 KC_MPLY, // Trigger key: play/pause
74 KC_MNXT, // Replacement key
75 ~0, // Activate on all layers
76 MOD_MASK_SA, // Do not activate when shift or alt are pressed
77 ko_option_no_reregister_trigger); // Specifies that the play key is not registered again after lifting ctrl
78
79const key_override_t prev_track_override = ko_make_with_layers_negmods_and_options(MOD_MASK_CS, KC_MPLY,
80 KC_MPRV, ~0, MOD_MASK_ALT, ko_option_no_reregister_trigger);
81
82const key_override_t vol_up_override = ko_make_with_layers_negmods_and_options(MOD_MASK_ALT, KC_MPLY,
83 KC_VOLU, ~0, MOD_MASK_CS, ko_option_no_reregister_trigger);
84
85const key_override_t vol_down_override = ko_make_with_layers_negmods_and_options(MOD_MASK_SA, KC_MPLY,
86 KC_VOLD, ~0, MOD_MASK_CTRL, ko_option_no_reregister_trigger);
87
88const key_override_t brightness_up_override = ko_make_with_layers_negmods_and_options(MOD_MASK_CA, KC_MPLY,
89 KC_BRIU, ~0, MOD_MASK_SHIFT, ko_option_no_reregister_trigger);
90
91const key_override_t brightness_down_override = ko_make_basic(MOD_MASK_CSA, KC_MPLY, KC_BRID);
92
93// This globally defines all key overrides to be used
94const key_override_t **key_overrides = (const key_override_t *[]){
95 &next_track_override,
96 &prev_track_override,
97 &vol_up_override,
98 &vol_down_override,
99 &brightness_up_override,
100 &brightness_down_override,
101 NULL
102};
103```
104
105### Flexible macOS-friendly Grave Escape
106The [Grave Escape feature](https://docs.qmk.fm/using-qmk/advanced-keycodes/feature_grave_esc) is limited in its configurability and has [bugs when used on macOS](https://docs.qmk.fm/using-qmk/advanced-keycodes/feature_grave_esc#caveats). Key overrides can be used to achieve a similar functionality as Grave Escape, but with more customization and without bugs on macOS.
107
108```c
109// Shift + esc = ~
110const key_override_t tilde_esc_override = ko_make_basic(MOD_MASK_SHIFT, KC_ESC, S(KC_GRAVE));
111
112// GUI + esc = `
113const key_override_t grave_esc_override = ko_make_basic(MOD_MASK_GUI, KC_ESC, KC_GRAVE);
114
115const key_override_t **key_overrides = (const key_override_t *[]){
116 &tilde_esc_override,
117 &grave_esc_override,
118 NULL
119};
120```
121
122In addition to not encountering unexpected bugs on macOS, you can also change the behavior as you wish. Instead setting `GUI` + `ESC` = `` ` `` you may change it to an arbitrary other modifier, for example `Ctrl` + `ESC` = `` ` ``.
123
124## Advanced Examples
125### Modifiers as Layer Keys
126
127Do you really need a dedicated key to toggle your fn layer? With key overrides, perhaps not. This example shows how you can configure to use `rGUI` + `rAlt` (right GUI and right alt) to access a momentary layer like an fn layer. With this you completely eliminate the need to use a dedicated layer key. Of course the choice of modifier keys can be changed as needed, `rGUI` + `rAlt` is just an example here.
128
129```c
130// This is called when the override activates and deactivates. Enable the fn layer on activation and disable on deactivation
131bool momentary_layer(bool key_down, void *layer) {
132 if (key_down) {
133 layer_on((uint8_t)(uintptr_t)layer);
134 } else {
135 layer_off((uint8_t)(uintptr_t)layer);
136 }
137
138 return false;
139}
140
141const key_override_t fn_override = {.trigger_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), //
142 .layers = ~(1 << LAYER_FN), //
143 .suppressed_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), //
144 .options = ko_option_no_unregister_on_other_key_down, //
145 .negative_mod_mask = (uint8_t) ~(MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL)), //
146 .custom_action = momentary_layer, //
147 .context = (void *)LAYER_FN, //
148 .trigger = KC_NO, //
149 .replacement = KC_NO, //
150 .enabled = NULL};
151```
152
153## Keycodes
154
155You can enable, disable and toggle all key overrides on the fly.
156
157|Keycode |Description |Function Equivalent|
158|----------|---------------------------------|--------|
159|`KEY_OVERRIDE_ON` |Turns on Key Override feature | `key_override_on(void)`|
160|`KEY_OVERRIDE_OFF` |Turns off Key Override feature |`key_override_off(void)`|
161|`KEY_OVERRIDE_TOGGLE` |Toggles Key Override feature on and off |`key_override_toggle(void)`|
162
163## Reference for `key_override_t`
164
165Advanced users may need more customization than what is offered by the simple `ko_make` initializers. For this, directly create a `key_override_t` value and set all members. Below is a reference for all members of `key_override_t`.
166
167| Member | Description |
168|--------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
169| `uint16_t trigger` | The non-modifier keycode that triggers the override. This keycode, and the necessary modifiers (`trigger_mods`) must be pressed to activate this override. Set this to the keycode of the key that should activate the override. Set to `KC_NO` to require only the necessary modifiers to be pressed and no non-modifier. |
170| `uint8_t trigger_mods` | Which mods need to be down for activation. If both sides of a modifier are set (e.g. left ctrl and right ctrl) then only one is required to be pressed (e.g. left ctrl suffices). Use the `MOD_MASK_XXX` and `MOD_BIT()` macros for this. |
171| `layer_state_t layers` | This is a BITMASK (!), defining which layers this override applies to. To use this override on layer i set the ith bit `(1 << i)`. |
172| `uint8_t negative_mod_mask` | Which modifiers cannot be down. It must hold that `(active_modifiers & negative_mod_mask) == 0`, otherwise the key override will not be activated. An active override will be deactivated once this is no longer true. |
173| `uint8_t suppressed_mods` | Modifiers to 'suppress' while the override is active. To suppress a modifier means that even though the modifier key is held down, the host OS sees the modifier as not pressed. Can be used to suppress the trigger modifiers, as a trivial example. |
174| `uint16_t replacement` | The complex keycode to send as replacement when this override is triggered. This can be a simple keycode, a key-modifier combination (e.g. `C(KC_A)`), or `KC_NO` (to register no replacement keycode). Use in combination with suppressed_mods to get the correct modifiers to be sent. |
175| `ko_option_t options` | Options controlling the behavior of the override, such as what actions are allowed to activate the override. |
176| `bool (*custom_action)(bool activated, void *context)` | If not NULL, this function will be called right before the replacement key is registered, along with the provided context and a flag indicating whether the override was activated or deactivated. This function allows you to run some custom actions for specific key overrides. If you return `false`, the replacement key is not registered/unregistered as it would normally. Return `true` to register and unregister the override normally. |
177| `void *context` | A context that will be passed to the custom action function. |
178| `bool *enabled` | If this points to false this override will not be used. Set to NULL to always have this override enabled. |
179
180### Reference for `ko_option_t`
181
182Bitfield with various options controlling the behavior of a key override.
183
184| Value | Description |
185|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
186| `ko_option_activation_trigger_down` | Allow activating when the trigger key is pressed down. |
187| `ko_option_activation_required_mod_down` | Allow activating when a necessary modifier is pressed down. |
188| `ko_option_activation_negative_mod_up` | Allow activating when a negative modifier is released. |
189| `ko_option_one_mod` | If set, any of the modifiers in `trigger_mods` will be enough to activate the override (logical OR of modifiers). If not set, all the modifiers in `trigger_mods` have to be pressed (logical AND of modifiers). |
190| `ko_option_no_unregister_on_other_key_down` | If set, the override will not deactivate when another key is pressed down. Use only if you really know you need this. |
191| `ko_option_no_reregister_trigger` | If set, the trigger key will never be registered again after the override is deactivated. |
192| `ko_options_default` | The default options used by the `ko_make_xxx` functions |
193
194## For Advanced Users: Inner Workings
195
196This section explains how a key override works in detail, explaining where each member of `key_override_t` comes into play. Understanding this is essential to be able to take full advantage of all the options offered by key overrides.
197
198#### Activation
199
200When the necessary keys are pressed (`trigger_mods` + `trigger`), the override is 'activated' and the replacement key is registered in the keyboard report (`replacement`), while the `trigger` key is removed from the keyboard report. The trigger modifiers may also be removed from the keyboard report upon activation of an override (`suppressed_mods`). The override will not activate if any of the `negative_modifiers` are pressed.
201
202Overrides can activate in three different cases:
203
2041. The trigger key is pressed down and necessary modifiers are already down.
2052. A necessary modifier is pressed down, while the trigger key and other necessary modifiers are already down.
2063. A negative modifier is released, while all necessary modifiers and the trigger key are already down.
207
208Use the `option` member to customize which of these events are allowed to activate your overrides (default: all three).
209
210In any case, a key override can only activate if the `trigger` key is the _last_ non-modifier key that was pressed down. This emulates the behavior of how standard OSes (macOS, Windows, Linux) handle normal key input (to understand: Hold down `a`, then also hold down `b`, then hold down `shift`; `B` will be typed but not `A`).
211
212#### Deactivation
213
214An override is 'deactivated' when one of the trigger keys (`trigger_mods`, `trigger`) is lifted, another non-modifier key is pressed down, or one of the `negative_modifiers` is pressed down. When an override deactivates, the `replacement` key is removed from the keyboard report, while the `suppressed_mods` that are still held down are re-added to the keyboard report. By default, the `trigger` key is re-added to the keyboard report if it is still held down and no other non-modifier key has been pressed since. This again emulates the behavior of how standard OSes handle normal key input (To understand: hold down `a`, then also hold down `b`, then also `shift`, then release `b`; `A` will not be typed even though you are holding the `a` and `shift` keys). Use the `option` field `ko_option_no_reregister_trigger` to prevent re-registering the trigger key in all cases.
215
216#### Key Repeat Delay
217
218A third way in which standard OS-handling of modifier-key input is emulated in key overrides is with a ['key repeat delay'](https://www.dummies.com/computers/pcs/set-your-keyboards-repeat-delay-and-repeat-rate/). To explain what this is, let's look at how normal keyboard input is handled by mainstream OSes again: If you hold down `a`, followed by `shift`, you will see the letter `a` is first typed, then for a short moment nothing is typed and then repeating `A`s are typed. Take note that, although shift is pressed down just after `a` is pressed, it takes a moment until `A` is typed. This is caused by the aforementioned key repeat delay, and it is a feature that prevents unwanted repeated characters from being typed.
219
220This applies equally to releasing a modifier: When you hold `shift`, then press `a`, the letter `A` is typed. Now if you release `shift` first, followed by `a` shortly after, you will not see the letter `a` being typed, even though for a short moment of time you were just holding down the key `a`. This is because no modified characters are typed until the key repeat delay has passed.
221
222 This exact behavior is implemented in key overrides as well: If a key override for `shift` + `a` = `b` exists, and `a` is pressed and held, followed by `shift`, you will not immediately see the letter `b` being typed. Instead, this event is deferred for a short moment, until the key repeat delay has passed, measured from the moment when the trigger key (`a`) was pressed down.
223
224The duration of the key repeat delay is controlled with the `KEY_OVERRIDE_REPEAT_DELAY` macro. Define this value in your `config.h` file to change it. It is 500ms by default.
225
226
227## Difference to Combos
228
229Note that key overrides are very different from [combos](https://docs.qmk.fm/#/feature_combo). Combos require that you press down several keys almost _at the same time_ and can work with any combination of non-modifier keys. Key overrides work like keyboard shortcuts (e.g. `ctrl` + `z`): They take combinations of _multiple_ modifiers and _one_ non-modifier key to then perform some custom action. Key overrides are implemented with much care to behave just like normal keyboard shortcuts would in regards to the order of pressed keys, timing, and interacton with other pressed keys. There are a number of optional settings that can be used to really fine-tune the behavior of each key override as well. Using key overrides also does not delay key input for regular key presses, which inherently happens in combos and may be undesirable.
diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md
index 5134ab6ef..018da43dd 100644
--- a/docs/feature_led_matrix.md
+++ b/docs/feature_led_matrix.md
@@ -262,7 +262,7 @@ For inspiration and examples, check out the built-in effects under `quantum/led_
262#define LED_MATRIX_FRAMEBUFFER_EFFECTS // enable framebuffer effects 262#define LED_MATRIX_FRAMEBUFFER_EFFECTS // enable framebuffer effects
263#define LED_DISABLE_TIMEOUT 0 // number of milliseconds to wait until led automatically turns off 263#define LED_DISABLE_TIMEOUT 0 // number of milliseconds to wait until led automatically turns off
264#define LED_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects 264#define LED_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects
265#define LED_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended 265#define LED_DISABLE_WHEN_USB_SUSPENDED // turn off effects when suspended
266#define LED_MATRIX_LED_PROCESS_LIMIT (DRIVER_LED_TOTAL + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness) 266#define LED_MATRIX_LED_PROCESS_LIMIT (DRIVER_LED_TOTAL + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness)
267#define LED_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness) 267#define LED_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness)
268#define LED_MATRIX_MAXIMUM_BRIGHTNESS 255 // limits maximum brightness of LEDs 268#define LED_MATRIX_MAXIMUM_BRIGHTNESS 255 // limits maximum brightness of LEDs
@@ -350,30 +350,3 @@ void led_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
350 LED_MATRIX_INDICATOR_SET_VALUE(index, value); 350 LED_MATRIX_INDICATOR_SET_VALUE(index, value);
351} 351}
352``` 352```
353
354## Suspended State :id=suspended-state
355To use the suspend feature, make sure that `#define LED_DISABLE_WHEN_USB_SUSPENDED true` is added to the `config.h` file.
356
357Additionally add this to your `<keyboard>.c`:
358
359```c
360void suspend_power_down_kb(void) {
361 led_matrix_set_suspend_state(true);
362 suspend_power_down_user();
363}
364
365void suspend_wakeup_init_kb(void) {
366 led_matrix_set_suspend_state(false);
367 suspend_wakeup_init_user();
368}
369```
370or add this to your `keymap.c`:
371```c
372void suspend_power_down_user(void) {
373 led_matrix_set_suspend_state(true);
374}
375
376void suspend_wakeup_init_user(void) {
377 led_matrix_set_suspend_state(false);
378}
379```
diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md
index f3b659b1b..c90aabb9c 100644
--- a/docs/feature_oled_driver.md
+++ b/docs/feature_oled_driver.md
@@ -346,6 +346,10 @@ bool oled_scroll_left(void);
346// Returns true if the screen was not scrolling or stops scrolling 346// Returns true if the screen was not scrolling or stops scrolling
347bool oled_scroll_off(void); 347bool oled_scroll_off(void);
348 348
349// Inverts the display
350// Returns true if the screen was or is inverted
351bool oled_invert(bool invert);
352
349// Returns the maximum number of characters that will fit on a line 353// Returns the maximum number of characters that will fit on a line
350uint8_t oled_max_chars(void); 354uint8_t oled_max_chars(void);
351 355
diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md
index 08d5c9c4c..bd47fb6d3 100644
--- a/docs/feature_rgb_matrix.md
+++ b/docs/feature_rgb_matrix.md
@@ -145,9 +145,22 @@ There is basic support for addressable RGB matrix lighting with the I2C IS31FL37
145RGB_MATRIX_ENABLE = yes 145RGB_MATRIX_ENABLE = yes
146RGB_MATRIX_DRIVER = IS31FL3737 146RGB_MATRIX_DRIVER = IS31FL3737
147``` 147```
148You can use between 1 and 2 IS31FL3737 IC's. Do not specify `DRIVER_ADDR_2` define for second IC if not present on your keyboard.
148 149
149Configure the hardware via your `config.h`: 150Configure the hardware via your `config.h`:
150 151
152| Variable | Description | Default |
153|----------|-------------|---------|
154| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
155| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
156| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
157| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | |
158| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | |
159| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | |
160
161
162Here is an example using 2 drivers.
163
151```c 164```c
152// This is a 7-bit address, that gets left-shifted and bit 0 165// This is a 7-bit address, that gets left-shifted and bit 0
153// set to 0 for write, 1 for read (as per I2C protocol) 166// set to 0 for write, 1 for read (as per I2C protocol)
@@ -159,19 +172,21 @@ Configure the hardware via your `config.h`:
159// ADDR represents A3:A0 of the 7-bit address. 172// ADDR represents A3:A0 of the 7-bit address.
160// The result is: 0b101(ADDR) 173// The result is: 0b101(ADDR)
161#define DRIVER_ADDR_1 0b1010000 174#define DRIVER_ADDR_1 0b1010000
162#define DRIVER_ADDR_2 0b1010000 // this is here for compliancy reasons. 175#define DRIVER_ADDR_2 0b1010001
163 176
164#define DRIVER_COUNT 2 177#define DRIVER_COUNT 2
165#define DRIVER_1_LED_TOTAL 64 178#define DRIVER_1_LED_TOTAL 30
166#define DRIVER_LED_TOTAL DRIVER_1_LED_TOTAL 179#define DRIVER_2_LED_TOTAL 36
180#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)
167``` 181```
182!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`.
168 183
169Currently only a single drivers is supported, but it would be trivial to support all 4 combinations. For now define `DRIVER_ADDR_2` as `DRIVER_ADDR_1` 184Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
170 185
171Define these arrays listing all the LEDs in your `<keyboard>.c`: 186Define these arrays listing all the LEDs in your `<keyboard>.c`:
172 187
173```c 188```c
174const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { 189const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = {
175/* Refer to IS31 manual for these locations 190/* Refer to IS31 manual for these locations
176 * driver 191 * driver
177 * | R location 192 * | R location
@@ -183,7 +198,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
183} 198}
184``` 199```
185 200
186Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now). 201Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1` for now).
187 202
188--- 203---
189 204
@@ -228,6 +243,75 @@ Configure the hardware via your `config.h`:
228``` 243```
229 244
230--- 245---
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`:
248
249```makefile
250RGB_MATRIX_ENABLE = yes
251RGB_MATRIX_DRIVER = AW20216
252```
253
254You can use up to 2 AW20216 IC's. Do not specify `DRIVER_<N>_xxx` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`:
255
256| Variable | Description | Default |
257|----------|-------------|---------|
258| `DRIVER_1_CS` | (Required) MCU pin connected to first RGB driver chip select line | B13 |
259| `DRIVER_2_CS` | (Optional) MCU pin connected to second RGB driver chip select line | |
260| `DRIVER_1_EN` | (Required) MCU pin connected to first RGB driver hardware enable line | C13 |
261| `DRIVER_2_EN` | (Optional) MCU pin connected to second RGB driver hardware enable line | |
262| `DRIVER_1_LED_TOTAL` | (Required) How many RGB lights are connected to first RGB driver | |
263| `DRIVER_2_LED_TOTAL` | (Optional) How many RGB lights are connected to second RGB driver | |
264| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
265| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | |
266| `AW_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 |
267| `AW_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 |
268| `AW_SPI_DIVISOR` | (Optional) Clock divisor for SPI communication (powers of 2, smaller numbers means faster communication, should not be less than 4) | 4 |
269
270Here is an example using 2 drivers.
271
272```c
273#define DRIVER_1_CS B13
274#define DRIVER_2_CS B14
275// Hardware enable lines may be connected to the same pin
276#define DRIVER_1_EN C13
277#define DRIVER_2_EN C13
278
279#define DRIVER_COUNT 2
280#define DRIVER_1_LED_TOTAL 66
281#define DRIVER_2_LED_TOTAL 32
282#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)
283```
284
285!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`.
286
287Define these arrays listing all the LEDs in your `<keyboard>.c`:
288
289```c
290const aw_led g_aw_leds[DRIVER_LED_TOTAL] = {
291/* Each AW20216 channel is controlled by a register at some offset between 0x00
292 * and 0xD7 inclusive.
293 * See drivers/awinic/aw20216.h for the mapping between register offsets and
294 * driver pin locations.
295 * driver
296 * | R location
297 * | | G location
298 * | | | B location
299 * | | | | */
300 { 0, CS1_SW1, CS2_SW1, CS3_SW1 },
301 { 0, CS4_SW1, CS5_SW1, CS6_SW1 },
302 { 0, CS7_SW1, CS8_SW1, CS9_SW1 },
303 { 0, CS10_SW1, CS11_SW1, CS12_SW1 },
304 { 0, CS13_SW1, CS14_SW1, CS15_SW1 },
305 ...
306 { 1, CS1_SW1, CS2_SW1, CS3_SW1 },
307 { 1, CS13_SW1, CS14_SW1, CS15_SW1 },
308 { 1, CS16_SW1, CS17_SW1, CS18_SW1 },
309 { 1, CS4_SW2, CS5_SW2, CS6_SW2 },
310 ...
311};
312```
313
314---
231 315
232## Common Configuration :id=common-configuration 316## Common Configuration :id=common-configuration
233 317
@@ -485,28 +569,29 @@ For inspiration and examples, check out the built-in effects under `quantum/rgb_
485 569
486These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. 570These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
487 571
488|RGB |HSV | 572|RGB |HSV |
489|-------------------|-------------------| 573|---------------------|---------------------|
490|`RGB_WHITE` |`HSV_WHITE` | 574|`RGB_AZURE` |`HSV_AZURE` |
491|`RGB_RED` |`HSV_RED` | 575|`RGB_BLACK`/`RGB_OFF`|`HSV_BLACK`/`HSV_OFF`|
492|`RGB_CORAL` |`HSV_CORAL` | 576|`RGB_BLUE` |`HSV_BLUE` |
493|`RGB_ORANGE` |`HSV_ORANGE` | 577|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` |
494|`RGB_GOLDENROD` |`HSV_GOLDENROD` | 578|`RGB_CORAL` |`HSV_CORAL` |
495|`RGB_GOLD` |`HSV_GOLD` | 579|`RGB_CYAN` |`HSV_CYAN` |
496|`RGB_YELLOW` |`HSV_YELLOW` | 580|`RGB_GOLD` |`HSV_GOLD` |
497|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | 581|`RGB_GOLDENROD` |`HSV_GOLDENROD` |
498|`RGB_GREEN` |`HSV_GREEN` | 582|`RGB_GREEN` |`HSV_GREEN` |
499|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | 583|`RGB_MAGENTA` |`HSV_MAGENTA` |
500|`RGB_TURQUOISE` |`HSV_TURQUOISE` | 584|`RGB_ORANGE` |`HSV_ORANGE` |
501|`RGB_TEAL` |`HSV_TEAL` | 585|`RGB_PINK` |`HSV_PINK` |
502|`RGB_CYAN` |`HSV_CYAN` | 586|`RGB_PURPLE` |`HSV_PURPLE` |
503|`RGB_AZURE` |`HSV_AZURE` | 587|`RGB_RED` |`HSV_RED` |
504|`RGB_BLUE` |`HSV_BLUE` | 588|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` |
505|`RGB_PURPLE` |`HSV_PURPLE` | 589|`RGB_TEAL` |`HSV_TEAL` |
506|`RGB_MAGENTA` |`HSV_MAGENTA` | 590|`RGB_TURQUOISE` |`HSV_TURQUOISE` |
507|`RGB_PINK` |`HSV_PINK` | 591|`RGB_WHITE` |`HSV_WHITE` |
508 592|`RGB_YELLOW` |`HSV_YELLOW` |
509These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list! 593
594These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list!
510 595
511 596
512## Additional `config.h` Options :id=additional-configh-options 597## Additional `config.h` Options :id=additional-configh-options
@@ -656,30 +741,3 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
656 } 741 }
657} 742}
658``` 743```
659
660### Suspended state :id=suspended-state
661To use the suspend feature, make sure that `#define RGB_DISABLE_WHEN_USB_SUSPENDED true` is added to the `config.h` file.
662
663Additionally add this to your `<keyboard>.c`:
664
665```c
666void suspend_power_down_kb(void) {
667 rgb_matrix_set_suspend_state(true);
668 suspend_power_down_user();
669}
670
671void suspend_wakeup_init_kb(void) {
672 rgb_matrix_set_suspend_state(false);
673 suspend_wakeup_init_user();
674}
675```
676or add this to your `keymap.c`:
677```c
678void suspend_power_down_user(void) {
679 rgb_matrix_set_suspend_state(true);
680}
681
682void suspend_wakeup_init_user(void) {
683 rgb_matrix_set_suspend_state(false);
684}
685```
diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md
index 994a014a2..8484586c0 100644
--- a/docs/feature_rgblight.md
+++ b/docs/feature_rgblight.md
@@ -119,7 +119,7 @@ if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a n
119 119
120Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration. 120Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration.
121 121
122Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight.h` there is a contrast table between the old mode number and the current symbol. 122Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight/rgblight.h` there is a contrast table between the old mode number and the current symbol.
123 123
124### Effect and Animation Toggles 124### Effect and Animation Toggles
125 125
@@ -326,9 +326,13 @@ would turn the layer 0 (or 1) on and off again three times when `DEBUG` is press
326 326
327Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`. 327Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`.
328 328
329### Retain brightness
330
331Usually lighting layers apply their configured brightness once activated. If you would like lighting layers to retain the currently used brightness (as returned by `rgblight_get_val()`), add `#define RGBLIGHT_LAYERS_RETAIN_VAL` to your `config.h`.
332
329## Functions 333## Functions
330 334
331If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include: 335If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight/rgblight.h) for the full list, but the most commonly used functions include:
332 336
333### Utility Functions 337### Utility Functions
334|Function |Description | 338|Function |Description |
@@ -449,26 +453,27 @@ rgblight_sethsv_at(HSV_GREEN, 2); // led 2
449 453
450These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. 454These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
451 455
452|RGB |HSV | 456|RGB |HSV |
453|-------------------|-------------------| 457|---------------------|---------------------|
454|`RGB_WHITE` |`HSV_WHITE` | 458|`RGB_AZURE` |`HSV_AZURE` |
455|`RGB_RED` |`HSV_RED` | 459|`RGB_BLACK`/`RGB_OFF`|`HSV_BLACK`/`HSV_OFF`|
456|`RGB_CORAL` |`HSV_CORAL` | 460|`RGB_BLUE` |`HSV_BLUE` |
457|`RGB_ORANGE` |`HSV_ORANGE` | 461|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` |
458|`RGB_GOLDENROD` |`HSV_GOLDENROD` | 462|`RGB_CORAL` |`HSV_CORAL` |
459|`RGB_GOLD` |`HSV_GOLD` | 463|`RGB_CYAN` |`HSV_CYAN` |
460|`RGB_YELLOW` |`HSV_YELLOW` | 464|`RGB_GOLD` |`HSV_GOLD` |
461|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | 465|`RGB_GOLDENROD` |`HSV_GOLDENROD` |
462|`RGB_GREEN` |`HSV_GREEN` | 466|`RGB_GREEN` |`HSV_GREEN` |
463|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | 467|`RGB_MAGENTA` |`HSV_MAGENTA` |
464|`RGB_TURQUOISE` |`HSV_TURQUOISE` | 468|`RGB_ORANGE` |`HSV_ORANGE` |
465|`RGB_TEAL` |`HSV_TEAL` | 469|`RGB_PINK` |`HSV_PINK` |
466|`RGB_CYAN` |`HSV_CYAN` | 470|`RGB_PURPLE` |`HSV_PURPLE` |
467|`RGB_AZURE` |`HSV_AZURE` | 471|`RGB_RED` |`HSV_RED` |
468|`RGB_BLUE` |`HSV_BLUE` | 472|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` |
469|`RGB_PURPLE` |`HSV_PURPLE` | 473|`RGB_TEAL` |`HSV_TEAL` |
470|`RGB_MAGENTA` |`HSV_MAGENTA` | 474|`RGB_TURQUOISE` |`HSV_TURQUOISE` |
471|`RGB_PINK` |`HSV_PINK` | 475|`RGB_WHITE` |`HSV_WHITE` |
476|`RGB_YELLOW` |`HSV_YELLOW` |
472 477
473```c 478```c
474rgblight_setrgb(RGB_ORANGE); 479rgblight_setrgb(RGB_ORANGE);
@@ -477,7 +482,7 @@ rgblight_setrgb_at(RGB_GOLD, 3);
477rgblight_sethsv_range(HSV_WHITE, 0, 6); 482rgblight_sethsv_range(HSV_WHITE, 0, 6);
478``` 483```
479 484
480These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list! 485These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list!
481 486
482 487
483## Changing the order of the LEDs 488## Changing the order of the LEDs
diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md
index 4ebf585f5..428d581ca 100644
--- a/docs/feature_split_keyboard.md
+++ b/docs/feature_split_keyboard.md
@@ -8,8 +8,7 @@ QMK Firmware has a generic implementation that is usable by any board, as well a
8 8
9For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards. 9For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards.
10 10
11!> ARM is not yet fully supported for Split Keyboards and has many limitations. Progress is being made, but we have not yet reached 100% feature parity. 11!> ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported.
12
13 12
14## Compatibility Overview 13## Compatibility Overview
15 14
@@ -90,7 +89,13 @@ You can configure the firmware to read a pin on the controller to determine hand
90#define SPLIT_HAND_PIN B7 89#define SPLIT_HAND_PIN B7
91``` 90```
92 91
93This will read the specified pin. If it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side. 92This will read the specified pin. By default, if it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side.
93
94This behaviour can be flipped by adding this to you `config.h` file:
95
96```c
97#define SPLIT_HAND_PIN_LOW_IS_LEFT
98```
94 99
95#### Handedness by Matrix Pin 100#### Handedness by Matrix Pin
96 101
@@ -169,7 +174,7 @@ Because not every split keyboard is identical, there are a number of additional
169#define USE_I2C 174#define USE_I2C
170``` 175```
171 176
172This enables I<sup>2</sup>C support for split keyboards. This isn't strictly for communication, but can be used for OLED or other I<sup>2</sup>C-based devices. 177This configures the use of I<sup>2</sup>C support for split keyboard transport (AVR only).
173 178
174```c 179```c
175#define SOFT_SERIAL_PIN D0 180#define SOFT_SERIAL_PIN D0
@@ -193,20 +198,115 @@ If you're having issues with serial communication, you can change this value, as
193* **`5`**: about 20kbps 198* **`5`**: about 20kbps
194 199
195```c 200```c
196#define SPLIT_MODS_ENABLE 201#define FORCED_SYNC_THROTTLE_MS 100
197``` 202```
198 203
199This enables transmitting modifier state (normal, weak and oneshot) to the non 204This sets the maximum number of milliseconds before forcing a synchronization of data from master to slave. Under normal circumstances this sync occurs whenever the data _changes_, for safety a data transfer occurs after this number of milliseconds if no change has been detected since the last sync.
200primary side of the split keyboard. This adds a few bytes of data to the split
201communication protocol and may impact the matrix scan speed when enabled.
202The purpose of this feature is to support cosmetic use of modifer state (e.g.
203displaying status on an OLED screen).
204 205
205```c 206```c
206#define SPLIT_TRANSPORT_MIRROR 207#define SPLIT_TRANSPORT_MIRROR
207``` 208```
208 209
209This mirrors the master side matrix to the slave side for features that react or require knowledge of master side key presses on the slave side. This adds a few bytes of data to the split communication protocol and may impact the matrix scan speed when enabled. The purpose of this feature is to support cosmetic use of key events (e.g. RGB reacting to Keypresses). 210This mirrors the master side matrix to the slave side for features that react or require knowledge of master side key presses on the slave side. The purpose of this feature is to support cosmetic use of key events (e.g. RGB reacting to keypresses). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
211
212```c
213#define SPLIT_LAYER_STATE_ENABLE
214```
215
216This enables syncing of the layer state between both halves of the split keyboard. The main purpose of this feature is to enable support for use of things like OLED display of the currently active layer. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
217
218```c
219#define SPLIT_LED_STATE_ENABLE
220```
221
222This enables syncing of the Host LED status (caps lock, num lock, etc) between both halves of the split keyboard. The main purpose of this feature is to enable support for use of things like OLED display of the Host LED status. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
223
224```c
225#define SPLIT_MODS_ENABLE
226```
227
228This enables transmitting modifier state (normal, weak and oneshot) to the non primary side of the split keyboard. The purpose of this feature is to support cosmetic use of modifer state (e.g. displaying status on an OLED screen). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
229
230```c
231#define SPLIT_WPM_ENABLE
232```
233
234This enables transmitting the current WPM to the slave side of the split keyboard. The purpose of this feature is to support cosmetic use of WPM (e.g. displaying the current value on an OLED screen). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
235
236### Custom data sync between sides :id=custom-data-sync
237
238QMK's split transport allows for arbitrary data transactions at both the keyboard and user levels. This is modelled on a remote procedure call, with the master invoking a function on the slave side, with the ability to send data from master to slave, process it slave side, and send data back from slave to master.
239
240To leverage this, a keyboard or user/keymap can define a comma-separated list of _transaction IDs_:
241
242```c
243// for keyboard-level data sync:
244#define SPLIT_TRANSACTION_IDS_KB KEYBOARD_SYNC_A, KEYBOARD_SYNC_B
245// or, for user:
246#define SPLIT_TRANSACTION_IDS_USER USER_SYNC_A, USER_SYNC_B, USER_SYNC_C
247```
248
249These _transaction IDs_ then need a slave-side handler function to be registered with the split transport, for example:
250
251```c
252typedef struct _master_to_slave_t {
253 int m2s_data;
254} master_to_slave_t;
255
256typedef struct _slave_to_master_t {
257 int s2m_data;
258} slave_to_master_t;
259
260void user_sync_a_slave_handler(uint8_t in_buflen, const void* in_data, uint8_t out_buflen, void* out_data) {
261 const master_to_slave_t *m2s = (const master_to_slave_t*)in_data;
262 slave_to_master_t *s2m = (slave_to_master_t*)out_data;
263 s2m->s2m_data = m2s->m2s_data + 5; // whatever comes in, add 5 so it can be sent back
264}
265
266void keyboard_post_init_user(void) {
267 transaction_register_rpc(USER_SYNC_A, user_sync_a_slave_handler);
268}
269```
270
271The master side can then invoke the slave-side handler - for normal keyboard functionality to be minimally affected, any keyboard- or user-level code attempting to sync data should be throttled:
272
273```c
274void housekeeping_task_user(void) {
275 if (is_keyboard_master()) {
276 // Interact with slave every 500ms
277 static uint32_t last_sync = 0;
278 if (timer_elapsed32(last_sync) > 500) {
279 master_to_slave_t m2s = {6};
280 slave_to_master_t s2m = {0};
281 if(transaction_rpc_exec(USER_SYNC_A, sizeof(m2s), &m2s, sizeof(s2m), &s2m)) {
282 last_sync = timer_read32();
283 dprintf("Slave value: %d\n", s2m.s2m_data); // this will now be 11, as the slave adds 5
284 } else {
285 dprint("Slave sync failed!\n");
286 }
287 }
288 }
289}
290```
291
292!> It is recommended that any data sync between halves happens during the master side's _housekeeping task_. This ensures timely retries should failures occur.
293
294If only one-way data transfer is needed, helper methods are provided:
295
296```c
297bool transaction_rpc_exec(int8_t transaction_id, uint8_t initiator2target_buffer_size, const void *initiator2target_buffer, uint8_t target2initiator_buffer_size, void *target2initiator_buffer);
298bool transaction_rpc_send(int8_t transaction_id, uint8_t initiator2target_buffer_size, const void *initiator2target_buffer);
299bool transaction_rpc_recv(int8_t transaction_id, uint8_t target2initiator_buffer_size, void *target2initiator_buffer);
300```
301
302By default, the inbound and outbound data is limited to a maximum of 32 bytes each. The sizes can be altered if required:
303
304```c
305// Master to slave:
306#define RPC_M2S_BUFFER_SIZE 48
307// Slave to master:
308#define RPC_S2M_BUFFER_SIZE 48
309```
210 310
211### Hardware Configuration Options 311### Hardware Configuration Options
212 312
diff --git a/docs/feature_st7565.md b/docs/feature_st7565.md
new file mode 100644
index 000000000..de3e44d8e
--- /dev/null
+++ b/docs/feature_st7565.md
@@ -0,0 +1,274 @@
1# ST7565 LCD Driver
2
3## Supported Hardware
4
5LCD modules using ST7565 driver IC, communicating over SPI.
6
7|Module |IC |Size |Notes |
8|------------------------------|-------|------|----------------------------------------------------------|
9|Newhaven Display NHD-C12832A1Z|ST7565R|128x32|Used by Ergodox Infinity; primary consumer of this feature|
10|Zolentech ZLE12864B |ST7565P|128x64|Requires contrast adjustment |
11
12## Usage
13
14To enable the feature, there are three steps. First, when compiling your keyboard, you'll need to add the following to your `rules.mk`:
15
16```make
17ST7565_ENABLE = yes
18```
19
20Then in your `keymap.c` file, implement the ST7565 task call. This example assumes your keymap has three layers named `_QWERTY`, `_FN` and `_ADJ`:
21
22```c
23#ifdef ST7565_ENABLE
24void st7565_task_user(void) {
25 // Host Keyboard Layer Status
26 st7565_write_P(PSTR("Layer: "), false);
27
28 switch (get_highest_layer(layer_state)) {
29 case _QWERTY:
30 st7565_write_P(PSTR("Default\n"), false);
31 break;
32 case _FN:
33 st7565_write_P(PSTR("FN\n"), false);
34 break;
35 case _ADJ:
36 st7565_write_P(PSTR("ADJ\n"), false);
37 break;
38 default:
39 // Or use the write_ln shortcut over adding '\n' to the end of your string
40 st7565_write_ln_P(PSTR("Undefined"), false);
41 }
42
43 // Host Keyboard LED Status
44 led_t led_state = host_keyboard_led_state();
45 st7565_write_P(led_state.num_lock ? PSTR("NUM ") : PSTR(" "), false);
46 st7565_write_P(led_state.caps_lock ? PSTR("CAP ") : PSTR(" "), false);
47 st7565_write_P(led_state.scroll_lock ? PSTR("SCR ") : PSTR(" "), false);
48}
49#endif
50```
51
52## Logo Example
53
54In the default font, certain ranges of characters are reserved for a QMK logo. To render this logo to the screen, use the following code example:
55
56```c
57static void render_logo(void) {
58 static const char PROGMEM qmk_logo[] = {
59 0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x8B, 0x8C, 0x8D, 0x8E, 0x8F, 0x90, 0x91, 0x92, 0x93, 0x94,
60 0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xAB, 0xAC, 0xAD, 0xAE, 0xAF, 0xB0, 0xB1, 0xB2, 0xB3, 0xB4,
61 0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF, 0xD0, 0xD1, 0xD2, 0xD3, 0xD4, 0x00
62 };
63
64 st7565_write_P(qmk_logo, false);
65}
66```
67
68## Buffer Read Example
69For some purposes, you may need to read the current state of the display buffer. The `st7565_read_raw` function can be used to safely read bytes from the buffer.
70
71In this example, calling `fade_display` in the `st7565_task_user` function will slowly fade away whatever is on the screen by turning random pixels off over time.
72```c
73//Setup some mask which can be or'd with bytes to turn off pixels
74const uint8_t single_bit_masks[8] = {127, 191, 223, 239, 247, 251, 253, 254};
75
76static void fade_display(void) {
77 //Define the reader structure
78 display_buffer_reader_t reader;
79 uint8_t buff_char;
80 if (random() % 30 == 0) {
81 srand(timer_read());
82 // Fetch a pointer for the buffer byte at index 0. The return structure
83 // will have the pointer and the number of bytes remaining from this
84 // index position if we want to perform a sequential read by
85 // incrementing the buffer pointer
86 reader = st7565_read_raw(0);
87 //Loop over the remaining buffer and erase pixels as we go
88 for (uint16_t i = 0; i < reader.remaining_element_count; i++) {
89 //Get the actual byte in the buffer by dereferencing the pointer
90 buff_char = *reader.current_element;
91 if (buff_char != 0) {
92 st7565_write_raw_byte(buff_char & single_bit_masks[rand() % 8], i);
93 }
94 //increment the pointer to fetch a new byte during the next loop
95 reader.current_element++;
96 }
97 }
98}
99```
100
101## Other Examples
102
103In split keyboards, it is very common to have two displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
104
105```c
106#ifdef ST7565_ENABLE
107display_rotation_t st7565_init_user(display_rotation_t rotation) {
108 if (!is_keyboard_master()) {
109 return DISPLAY_ROTATION_180; // flips the display 180 degrees if offhand
110 }
111
112 return rotation;
113}
114
115void st7565_task_user(void) {
116 if (is_keyboard_master()) {
117 render_status(); // Renders the current keyboard state (layer, lock, caps, scroll, etc)
118 } else {
119 render_logo(); // Renders a static logo
120 }
121}
122#endif
123```
124
125## Basic Configuration
126
127|Define |Default |Description |
128|------------------------|--------------|-----------------------------------------------------------------------------------------------------|
129|`ST7565_A0_PIN` |*Not defined* |(Required) The GPIO connected to the display's A0 (data/command) pin |
130|`ST7565_RST_PIN` |*Not defined* |(Required) The GPIO connected to the display's reset pin |
131|`ST7565_SS_PIN` |*Not defined* |(Required) The GPIO connected to the display's slave select pin |
132|`ST7565_SPI_CLK_DIVISOR`|`4` |The SPI clock divisor to use |
133|`ST7565_FONT_H` |`"glcdfont.c"`|The font code file to use for custom fonts |
134|`ST7565_FONT_START` |`0` |The starting character index for custom fonts |
135|`ST7565_FONT_END` |`223` |The ending character index for custom fonts |
136|`ST7565_FONT_WIDTH` |`6` |The font width |
137|`ST7565_FONT_HEIGHT` |`8` |The font height (untested) |
138|`ST7565_TIMEOUT` |`60000` |Turns off the screen after 60000ms of keyboard inactivity. Helps reduce burn-in. Set to 0 to disable.|
139|`ST7565_COLUMN_OFFSET` |`0` |Shift output to the right this many pixels. |
140|`ST7565_CONTRAST` |`32` |The default contrast level of the display, from 0 to 255. |
141|`ST7565_UPDATE_INTERVAL`|`0` |Set the time interval for updating the display in ms. This will improve the matrix scan rate. |
142
143## Custom sized displays
144
145The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind.
146
147|Define |Default |Description |
148|-----------------------|----------|-----------------------------------------------------------------------------------------------------------|
149|`ST7565_DISPLAY_WIDTH` |`128` |The width of the display. |
150|`ST7565_DISPLAY_HEIGHT`|`32` |The height of the display. |
151|`ST7565_MATRIX_SIZE` |`512` |The local buffer size to allocate.<br>`(ST7565_DISPLAY_HEIGHT / 8 * ST7565_DISPLAY_WIDTH)`. |
152|`ST7565_BLOCK_TYPE` |`uint16_t`|The unsigned integer type to use for dirty rendering. |
153|`ST7565_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.<br>`(sizeof(ST7565_BLOCK_TYPE) * 8)`.|
154|`ST7565_BLOCK_SIZE` |`32` |The size of each block for dirty rendering<br>`(ST7565_MATRIX_SIZE / ST7565_BLOCK_COUNT)`. |
155
156## API
157
158```c
159// Rotation enum values are flags
160typedef enum {
161 DISPLAY_ROTATION_0,
162 DISPLAY_ROTATION_180
163} display_rotation_t;
164
165// Initialize the display, rotating the rendered output based on the define passed in.
166// Returns true if the was initialized successfully
167bool st7565_init(display_rotation_t rotation);
168
169// Called at the start of st7565_init, weak function overridable by the user
170// rotation - the value passed into st7565_init
171// Return new display_rotation_t if you want to override default rotation
172display_rotation_t st7565_init_user(display_rotation_t rotation);
173
174// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
175void st7565_clear(void);
176
177// Renders the dirty chunks of the buffer to display
178void st7565_render(void);
179
180// Moves cursor to character position indicated by column and line, wraps if out of bounds
181// Max column denoted by 'st7565_max_chars()' and max lines by 'st7565_max_lines()' functions
182void st7565_set_cursor(uint8_t col, uint8_t line);
183
184// Advances the cursor to the next page, writing ' ' if true
185// Wraps to the begining when out of bounds
186void st7565_advance_page(bool clearPageRemainder);
187
188// Moves the cursor forward 1 character length
189// Advance page if there is not enough room for the next character
190// Wraps to the begining when out of bounds
191void st7565_advance_char(void);
192
193// Writes a single character to the buffer at current cursor position
194// Advances the cursor while writing, inverts the pixels if true
195// Main handler that writes character data to the display buffer
196void st7565_write_char(const char data, bool invert);
197
198// Writes a string to the buffer at current cursor position
199// Advances the cursor while writing, inverts the pixels if true
200void st7565_write(const char *data, bool invert);
201
202// Writes a string to the buffer at current cursor position
203// Advances the cursor while writing, inverts the pixels if true
204// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
205void st7565_write_ln(const char *data, bool invert);
206
207// Pans the buffer to the right (or left by passing true) by moving contents of the buffer
208// Useful for moving the screen in preparation for new drawing
209void st7565_pan(bool left);
210
211// Returns a pointer to the requested start index in the buffer plus remaining
212// buffer length as struct
213display_buffer_reader_t st7565_read_raw(uint16_t start_index);
214
215// Writes a string to the buffer at current cursor position
216void st7565_write_raw(const char *data, uint16_t size);
217
218// Writes a single byte into the buffer at the specified index
219void st7565_write_raw_byte(const char data, uint16_t index);
220
221// Sets a specific pixel on or off
222// Coordinates start at top-left and go right and down for positive x and y
223void st7565_write_pixel(uint8_t x, uint8_t y, bool on);
224
225// Writes a PROGMEM string to the buffer at current cursor position
226// Advances the cursor while writing, inverts the pixels if true
227// Remapped to call 'void st7565_write(const char *data, bool invert);' on ARM
228void st7565_write_P(const char *data, bool invert);
229
230// Writes a PROGMEM string to the buffer at current cursor position
231// Advances the cursor while writing, inverts the pixels if true
232// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
233// Remapped to call 'void st7565_write_ln(const char *data, bool invert);' on ARM
234void st7565_write_ln_P(const char *data, bool invert);
235
236// Writes a PROGMEM string to the buffer at current cursor position
237void st7565_write_raw_P(const char *data, uint16_t size);
238
239// Can be used to manually turn on the screen if it is off
240// Returns true if the screen was on or turns on
241bool st7565_on(void);
242
243// Called when st7565_on() turns on the screen, weak function overridable by the user
244// Not called if the screen is already on
245void st7565_on_user(void);
246
247// Can be used to manually turn off the screen if it is on
248// Returns true if the screen was off or turns off
249bool st7565_off(void);
250
251// Called when st7565_off() turns off the screen, weak function overridable by the user
252// Not called if the screen is already off
253void st7565_off_user(void);
254
255// Returns true if the screen is currently on, false if it is
256// not
257bool st7565_is_on(void);
258
259// Basically it's st7565_render, but with timeout management and st7565_task_user calling!
260void st7565_task(void);
261
262// Called at the start of st7565_task, weak function overridable by the user
263void st7565_task_user(void);
264
265// Inverts the display
266// Returns true if the screen was or is inverted
267bool st7565_invert(bool invert);
268
269// Returns the maximum number of characters that will fit on a line
270uint8_t st7565_max_chars(void);
271
272// Returns the maximum number of lines that will fit on the display
273uint8_t st7565_max_lines(void);
274```
diff --git a/docs/feature_tap_dance.md b/docs/feature_tap_dance.md
index 5d77f3e08..f4e989921 100644
--- a/docs/feature_tap_dance.md
+++ b/docs/feature_tap_dance.md
@@ -50,7 +50,7 @@ The main entry point is `process_tap_dance()`, called from `process_record_quant
50 50
51This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness. 51This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness.
52 52
53Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-dance keys. 53Our next stop is `tap_dance_task()`. This handles the timeout of tap-dance keys.
54 54
55For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros. 55For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros.
56 56
diff --git a/docs/flashing.md b/docs/flashing.md
index 83c97444e..da3c64c4a 100644
--- a/docs/flashing.md
+++ b/docs/flashing.md
@@ -171,6 +171,52 @@ Flashing sequence:
1713. Flash a .hex file 1713. Flash a .hex file
1724. Reset the device into application mode (may be done automatically) 1724. Reset the device into application mode (may be done automatically)
173 173
174### QMK HID
175
176QMK maintains [a fork of the LUFA HID bootloader](https://github.com/qmk/lufa/tree/master/Bootloaders/HID), which uses a USB HID Endpoint for flashing in the way that the PJRC's Teensy Loader flasher and HalfKay bootloader work. Additionally, it performs a simple matrix scan for exiting the bootloader and returning to the application, as well as flashing an LED/making a ticking noise with a speaker when things are happening.
177
178To ensure compatibility with the QMK HID bootloader, make sure this block is present in your `rules.mk`:
179
180```make
181# Bootloader selection
182BOOTLOADER = qmk-hid
183```
184
185To enable the additional features, add the following defines to your `config.h`:
186
187```c
188#define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW
189#define QMK_ESC_INPUT D5 // ROW pin if COL2ROW
190// Optional:
191//#define QMK_LED E6
192//#define QMK_SPEAKER C6
193```
194
195Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
196
197The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
198
199To generate this bootloader, use the `bootloader` target, eg. `make planck/rev4:default:bootloader`. To generate a production-ready .hex file (combining QMK and the bootloader), use the `production` target, eg. `make planck/rev4:default:production`.
200
201Compatible flashers:
202
203* TBD
204 * Currently, you need to either use the [Python script](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp_python), or compile [`hid_bootloader_cli`](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp), from the LUFA repo. Homebrew may (will) have support for this directly (via `brew install qmk/qmk/hid_bootloader_cli`).
205
206Flashing sequence:
207
2081. Enter the bootloader using any of the following methods:
209 * Press the `RESET` keycode
210 * Press the `RESET` button on the PCB if available
211 * short RST to GND quickly
2122. Wait for the OS to detect the device
2133. Flash a .hex file
2144. Reset the device into application mode (may be done automatically)
215
216### `make` Targets
217
218* `:qmk-hid`: Checks every 5 seconds until a DFU device is available, and then flashes the firmware.
219
174## STM32/APM32 DFU 220## STM32/APM32 DFU
175 221
176All STM32 and APM32 MCUs, except for F103 (see the [STM32duino section](#stm32duino)) come preloaded with a factory bootloader that cannot be modified nor deleted. 222All STM32 and APM32 MCUs, except for F103 (see the [STM32duino section](#stm32duino)) come preloaded with a factory bootloader that cannot be modified nor deleted.
diff --git a/docs/fr-fr/cli.md b/docs/fr-fr/cli.md
index 428153645..bfa060f2a 100644
--- a/docs/fr-fr/cli.md
+++ b/docs/fr-fr/cli.md
@@ -85,14 +85,14 @@ qmk compile <configuratorExport.json>
85qmk compile -kb <keyboard_name> -km <keymap_name> 85qmk compile -kb <keyboard_name> -km <keymap_name>
86``` 86```
87 87
88## `qmk cformat` 88## `qmk format-c`
89 89
90Cette commande formatte le code C en utilisant clang-format. Lancez-la sans arguments pour formatter tout le code core, ou passez les noms de fichiers à la ligne de commande pour la lancer sur des fichiers spécifiques. 90Cette commande formatte le code C en utilisant clang-format. Lancez-la sans arguments pour formatter tout le code core, ou passez les noms de fichiers à la ligne de commande pour la lancer sur des fichiers spécifiques.
91 91
92**Utilisation**: 92**Utilisation**:
93 93
94``` 94```
95qmk cformat [file1] [file2] [...] [fileN] 95qmk format-c [file1] [file2] [...] [fileN]
96``` 96```
97 97
98## `qmk config` 98## `qmk config`
@@ -125,14 +125,14 @@ Cette commande crée une nouvelle keymap basée sur une keymap par défaut d'un
125qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] 125qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
126``` 126```
127 127
128## `qmk pyformat` 128## `qmk format-py`
129 129
130Cette commande formate le code python dans `qmk_firmware`. 130Cette commande formate le code python dans `qmk_firmware`.
131 131
132**Utilisation**: 132**Utilisation**:
133 133
134``` 134```
135qmk pyformat 135qmk format-py
136``` 136```
137 137
138## `qmk pytest` 138## `qmk pytest`
diff --git a/docs/ja/cli_commands.md b/docs/ja/cli_commands.md
index 81cb03cfe..35937dbbc 100644
--- a/docs/ja/cli_commands.md
+++ b/docs/ja/cli_commands.md
@@ -211,7 +211,7 @@ qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
211 211
212# 開発者用コマンド 212# 開発者用コマンド
213 213
214## `qmk cformat` 214## `qmk format-c`
215 215
216このコマンドは clang-format を使って C コードを整形します。 216このコマンドは clang-format を使って C コードを整形します。
217 217
@@ -222,25 +222,25 @@ qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
222**指定したファイルに対する使い方**: 222**指定したファイルに対する使い方**:
223 223
224``` 224```
225qmk cformat [file1] [file2] [...] [fileN] 225qmk format-c [file1] [file2] [...] [fileN]
226``` 226```
227 227
228**全てのコアファイルに対する使い方**: 228**全てのコアファイルに対する使い方**:
229 229
230``` 230```
231qmk cformat -a 231qmk format-c -a
232``` 232```
233 233
234**origin/master で変更されたファイルのみに対する使い方**: 234**origin/master で変更されたファイルのみに対する使い方**:
235 235
236``` 236```
237qmk cformat 237qmk format-c
238``` 238```
239 239
240**branch_name で変更されたファイルのみに対する使い方**: 240**branch_name で変更されたファイルのみに対する使い方**:
241 241
242``` 242```
243qmk cformat -b branch_name 243qmk format-c -b branch_name
244``` 244```
245 245
246## `qmk docs` 246## `qmk docs`
@@ -275,14 +275,14 @@ $ qmk kle2json -f kle.txt -f
275Ψ Wrote out to info.json 275Ψ Wrote out to info.json
276``` 276```
277 277
278## `qmk pyformat` 278## `qmk format-py`
279 279
280このコマンドは `qmk_firmware` 内の python コードを整形します。 280このコマンドは `qmk_firmware` 内の python コードを整形します。
281 281
282**使用法**: 282**使用法**:
283 283
284``` 284```
285qmk pyformat 285qmk format-py
286``` 286```
287 287
288## `qmk pytest` 288## `qmk pytest`
diff --git a/docs/ja/cli_development.md b/docs/ja/cli_development.md
index 47262213a..28cdd91c1 100644
--- a/docs/ja/cli_development.md
+++ b/docs/ja/cli_development.md
@@ -192,7 +192,7 @@ cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.ou
192 192
193# テスト、リントおよびフォーマット 193# テスト、リントおよびフォーマット
194 194
195nose2、flake8 および yapf を使ってコードをテスト、リントおよびフォーマットします。これらのテストを実行するために `pytest` と `pyformat` サブコマンドを使うことができます。 195nose2、flake8 および yapf を使ってコードをテスト、リントおよびフォーマットします。これらのテストを実行するために `pytest` と `format-py` サブコマンドを使うことができます。
196 196
197### テストとリント 197### テストとリント
198 198
@@ -200,7 +200,7 @@ nose2、flake8 および yapf を使ってコードをテスト、リントお
200 200
201### フォーマット 201### フォーマット
202 202
203 qmk pyformat 203 qmk format-py
204 204
205## フォーマットの詳細 205## フォーマットの詳細
206 206
diff --git a/docs/ja/compatible_microcontrollers.md b/docs/ja/compatible_microcontrollers.md
index b675b038d..761a4cda4 100644
--- a/docs/ja/compatible_microcontrollers.md
+++ b/docs/ja/compatible_microcontrollers.md
@@ -36,6 +36,8 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま
36* [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) 36* [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html)
37* [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) 37* [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html)
38* [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) 38* [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html)
39* [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
40* [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
39* [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) 41* [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
40* [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) 42* [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
41 43
diff --git a/docs/ja/feature_dip_switch.md b/docs/ja/feature_dip_switch.md
index a0f6aeb00..a5436779f 100644
--- a/docs/ja/feature_dip_switch.md
+++ b/docs/ja/feature_dip_switch.md
@@ -28,8 +28,9 @@ DIP スイッチは、以下を `rules.mk` に追加することでサポート
28コールバック関数を `<keyboard>.c` に記述することができます: 28コールバック関数を `<keyboard>.c` に記述することができます:
29 29
30```c 30```c
31void dip_switch_update_kb(uint8_t index, bool active) { 31bool dip_switch_update_kb(uint8_t index, bool active) {
32 dip_switch_update_user(index, active); 32 if !(dip_switch_update_user(index, active)) { return false; }
33 return true;
33} 34}
34``` 35```
35 36
@@ -37,7 +38,7 @@ void dip_switch_update_kb(uint8_t index, bool active) {
37あるいは `keymap.c` に記述することもできます: 38あるいは `keymap.c` に記述することもできます:
38 39
39```c 40```c
40void dip_switch_update_user(uint8_t index, bool active) { 41bool dip_switch_update_user(uint8_t index, bool active) {
41 switch (index) { 42 switch (index) {
42 case 0: 43 case 0:
43 if(active) { audio_on(); } else { audio_off(); } 44 if(active) { audio_on(); } else { audio_off(); }
@@ -62,6 +63,7 @@ void dip_switch_update_user(uint8_t index, bool active) {
62 } 63 }
63 break; 64 break;
64 } 65 }
66 return true;
65} 67}
66``` 68```
67 69
@@ -69,8 +71,9 @@ void dip_switch_update_user(uint8_t index, bool active) {
69 71
70 72
71```c 73```c
72void dip_switch_update_mask_kb(uint32_t state) { 74bool dip_switch_update_mask_kb(uint32_t state) {
73 dip_switch_update_mask_user(state); 75 if (!dip_switch_update_mask_user(state)) { return false; }
76 return true;
74} 77}
75``` 78```
76 79
@@ -78,7 +81,7 @@ void dip_switch_update_mask_kb(uint32_t state) {
78あるいは `keymap.c` に記述することもできます: 81あるいは `keymap.c` に記述することもできます:
79 82
80```c 83```c
81void dip_switch_update_mask_user(uint32_t state) { 84bool dip_switch_update_mask_user(uint32_t state) {
82 if (state & (1UL<<0) && state & (1UL<<1)) { 85 if (state & (1UL<<0) && state & (1UL<<1)) {
83 layer_on(_ADJUST); // C on esc 86 layer_on(_ADJUST); // C on esc
84 } else { 87 } else {
@@ -94,6 +97,7 @@ void dip_switch_update_mask_user(uint32_t state) {
94 } else { 97 } else {
95 layer_off(_TEST_B); 98 layer_off(_TEST_B);
96 } 99 }
100 return true;
97} 101}
98``` 102```
99 103
diff --git a/docs/ja/feature_encoders.md b/docs/ja/feature_encoders.md
index 7b7f394c8..21f42d38b 100644
--- a/docs/ja/feature_encoders.md
+++ b/docs/ja/feature_encoders.md
@@ -51,15 +51,18 @@ ENCODER_ENABLE = yes
51コールバック関数を `<keyboard>.c` に記述することができます: 51コールバック関数を `<keyboard>.c` に記述することができます:
52 52
53```c 53```c
54void encoder_update_kb(uint8_t index, bool clockwise) { 54bool encoder_update_kb(uint8_t index, bool clockwise) {
55 encoder_update_user(index, clockwise); 55 if (!encoder_update_user(index, clockwise)) {
56 return false;
57 }
58
56} 59}
57``` 60```
58 61
59あるいは `keymap.c` に記述することもできます: 62あるいは `keymap.c` に記述することもできます:
60 63
61```c 64```c
62void encoder_update_user(uint8_t index, bool clockwise) { 65bool encoder_update_user(uint8_t index, bool clockwise) {
63 if (index == 0) { /* First encoder */ 66 if (index == 0) { /* First encoder */
64 if (clockwise) { 67 if (clockwise) {
65 tap_code(KC_PGDN); 68 tap_code(KC_PGDN);
@@ -73,6 +76,7 @@ void encoder_update_user(uint8_t index, bool clockwise) {
73 tap_code(KC_UP); 76 tap_code(KC_UP);
74 } 77 }
75 } 78 }
79 return true;
76} 80}
77``` 81```
78 82
diff --git a/docs/ja/feature_tap_dance.md b/docs/ja/feature_tap_dance.md
index 3d9d30ecf..dd2b8bdb6 100644
--- a/docs/ja/feature_tap_dance.md
+++ b/docs/ja/feature_tap_dance.md
@@ -59,7 +59,7 @@
59 59
60このことは、あなたは再びキーをタップするまでの時間として `TAPPING_TERM` の時間を持っていることを意味します。そのため、あなたは1つの `TAPPING_TERM` の時間内に全てのタップを行う必要はありません。これにより、キーの反応への影響を最小限に抑えながら、より長いタップ回数を可能にします。 60このことは、あなたは再びキーをタップするまでの時間として `TAPPING_TERM` の時間を持っていることを意味します。そのため、あなたは1つの `TAPPING_TERM` の時間内に全てのタップを行う必要はありません。これにより、キーの反応への影響を最小限に抑えながら、より長いタップ回数を可能にします。
61 61
62次は `matrix_scan_tap_dance()` です。この関数はタップダンスキーのタイムアウトを制御します。 62次は `tap_dance_task()` です。この関数はタップダンスキーのタイムアウトを制御します。
63 63
64柔軟性のために、タップダンスは、キーコードの組み合わせにも、ユーザー関数にもなることができます。後者は、より高度なタップ回数の制御や、LED を点滅させたり、バックライトをいじったり、等々の制御を可能にします。これは、1つの共用体と、いくつかの賢いマクロによって成し遂げられています。 64柔軟性のために、タップダンスは、キーコードの組み合わせにも、ユーザー関数にもなることができます。後者は、より高度なタップ回数の制御や、LED を点滅させたり、バックライトをいじったり、等々の制御を可能にします。これは、1つの共用体と、いくつかの賢いマクロによって成し遂げられています。
65 65
diff --git a/docs/ja/reference_configurator_support.md b/docs/ja/reference_configurator_support.md
index 4fb98fc0e..83d6d648d 100644
--- a/docs/ja/reference_configurator_support.md
+++ b/docs/ja/reference_configurator_support.md
@@ -104,8 +104,6 @@ JSON ファイルをビルドする最も簡単な方法は、[Keyboard Layout E
104 "tags": { 104 "tags": {
105 "form_factor": "numpad" 105 "form_factor": "numpad"
106 }, 106 },
107 "width": 4,
108 "height": 5,
109 "layouts": { 107 "layouts": {
110 "LAYOUT": { 108 "LAYOUT": {
111 "layout": [ 109 "layout": [
diff --git a/docs/ja/reference_info_json.md b/docs/ja/reference_info_json.md
index 5b9a1b6b6..7346a6395 100644
--- a/docs/ja/reference_info_json.md
+++ b/docs/ja/reference_info_json.md
@@ -20,10 +20,6 @@
20 * キーボードの製品ページ、[QMK.fm/keyboards](https://qmk.fm/keyboards) のページ、あるいはキーボードに関する情報を説明する他のページの URL。 20 * キーボードの製品ページ、[QMK.fm/keyboards](https://qmk.fm/keyboards) のページ、あるいはキーボードに関する情報を説明する他のページの URL。
21* `maintainer` 21* `maintainer`
22 * メンテナの GitHub のユーザ名、あるいはコミュニティが管理するキーボードの場合は `qmk` 22 * メンテナの GitHub のユーザ名、あるいはコミュニティが管理するキーボードの場合は `qmk`
23* `width`
24 * キー単位でのキーボードの幅
25* `height`
26 * キー単位でのキーボードの高さ
27* `layouts` 23* `layouts`
28 * 物理的なレイアウト表現。詳細は以下のセクションを見てください。 24 * 物理的なレイアウト表現。詳細は以下のセクションを見てください。
29 25
diff --git a/docs/reference_configurator_support.md b/docs/reference_configurator_support.md
index 1b34c85a2..ba3d49e2b 100644
--- a/docs/reference_configurator_support.md
+++ b/docs/reference_configurator_support.md
@@ -99,8 +99,6 @@ Use the `keyboard_name` object to set the name of the keyboard. For instruction
99 "tags": { 99 "tags": {
100 "form_factor": "numpad" 100 "form_factor": "numpad"
101 }, 101 },
102 "width": 4,
103 "height": 5,
104 "layouts": { 102 "layouts": {
105 "LAYOUT": { 103 "LAYOUT": {
106 "layout": [ 104 "layout": [
diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md
index 30d813e93..cf492629f 100644
--- a/docs/reference_info_json.md
+++ b/docs/reference_info_json.md
@@ -15,10 +15,6 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai
15 * A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard. 15 * A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard.
16* `maintainer` 16* `maintainer`
17 * GitHub username of the maintainer, or `qmk` for community maintained boards 17 * GitHub username of the maintainer, or `qmk` for community maintained boards
18* `width`
19 * Width of the board in Key Units
20* `height`
21 * Height of the board in Key Units
22* `debounce` 18* `debounce`
23 * How many milliseconds (ms) to wait for debounce to happen. (Default: 5) 19 * How many milliseconds (ms) to wait for debounce to happen. (Default: 5)
24* `diode_direction` 20* `diode_direction`
diff --git a/docs/serial_driver.md b/docs/serial_driver.md
index 359fc5955..ed989b0a1 100644
--- a/docs/serial_driver.md
+++ b/docs/serial_driver.md
@@ -73,7 +73,7 @@ You must also enable the ChibiOS `SERIAL` feature:
73Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral. 73Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral.
74 74
75### USART Full-duplex 75### USART Full-duplex
76Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. USART Full-Duplex requires two conductors **without** pull-up resistors instead of one conductor with a pull-up resistor unlike the Half-duplex driver, but it is more efficent as it uses DMA transfers, which can result in even faster transmission speeds. 76Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. USART Full-Duplex requires two conductors **without** pull-up resistors instead of one conductor with a pull-up resistor unlike the Half-duplex driver. Due to its internal design it is more efficent, which can result in even faster transmission speeds.
77 77
78#### Pin configuration 78#### Pin configuration
79 79
@@ -86,12 +86,13 @@ Please note that `TX` of the master half has to be connected with the `RX` pin o
86To use the driver, add this to your rules.mk: 86To use the driver, add this to your rules.mk:
87 87
88```make 88```make
89SERIAL_DRIVER = usart_duplex 89SERIAL_DRIVER = usart
90``` 90```
91 91
92Next configure the hardware via your config.h: 92Next configure the hardware via your config.h:
93 93
94```c 94```c
95#define SERIAL_USART_FULL_DUPLEX // Enable full duplex operation mode.
95#define SERIAL_USART_TX_PIN B6 // USART TX pin 96#define SERIAL_USART_TX_PIN B6 // USART TX pin
96#define SERIAL_USART_RX_PIN B7 // USART RX pin 97#define SERIAL_USART_RX_PIN B7 // USART RX pin
97//#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. 98//#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below.
@@ -104,17 +105,17 @@ Next configure the hardware via your config.h:
104 // 3: 57600 baud 105 // 3: 57600 baud
105 // 4: 38400 baud 106 // 4: 38400 baud
106 // 5: 19200 baud 107 // 5: 19200 baud
107#define SERIAL_USART_DRIVER UARTD1 // USART driver of TX and RX pin. default: UARTD1 108#define SERIAL_USART_DRIVER SD1 // USART driver of TX and RX pin. default: SD1
108#define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 109#define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7
109#define SERIAL_USART_RX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 110#define SERIAL_USART_RX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7
110#define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100 111#define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100
111``` 112```
112 113
113You must also enable the ChibiOS `UART` with blocking api feature: 114You must also enable the ChibiOS `SERIAL` feature:
114* In your board's halconf.h: `#define HAL_USE_UART TRUE` and `#define UART_USE_WAIT TRUE` 115* In your board's halconf.h: `#define HAL_USE_SERIAL TRUE`
115* In your board's mcuconf.h: `#define STM32_UART_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU) 116* In your board's mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU)
116 117
117Do note that the configuration required is for the `UART` peripheral, not the `SERIAL` peripheral. 118Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral.
118 119
119#### Pins for USART Peripherals with Alternate Functions for selected STM32 MCUs 120#### Pins for USART Peripherals with Alternate Functions for selected STM32 MCUs
120 121
diff --git a/docs/syllabus.md b/docs/syllabus.md
index ec7f66ba7..b33bd9e72 100644
--- a/docs/syllabus.md
+++ b/docs/syllabus.md
@@ -40,6 +40,7 @@ These topics start to dig into some of the features that QMK supports. You don't
40 * [Tap Dance](feature_tap_dance.md) 40 * [Tap Dance](feature_tap_dance.md)
41 * [Combos](feature_combo.md) 41 * [Combos](feature_combo.md)
42 * [Userspace](feature_userspace.md) 42 * [Userspace](feature_userspace.md)
43 * [Key Overrides](feature_key_overrides.md)
43 44
44# Advanced Topics 45# Advanced Topics
45 46
diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md
index 331b1c893..e3dd5cb78 100644
--- a/docs/understanding_qmk.md
+++ b/docs/understanding_qmk.md
@@ -146,6 +146,7 @@ The `process_record()` function itself is deceptively simple, but hidden within
146 * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19) 146 * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19)
147 * [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160) 147 * [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160)
148 * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_music.c#L114) 148 * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_music.c#L114)
149 * [`bool process_key_override(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/5a1b857dea45a17698f6baa7dd1b7a7ea907fb0a/quantum/process_keycode/process_key_override.c#L397)
149 * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L141) 150 * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L141)
150 * [`bool process_unicode_common(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode_common.c#L169) 151 * [`bool process_unicode_common(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode_common.c#L169)
151 calls one of: 152 calls one of:
diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md
index 27b2edf38..44cb5cf76 100644
--- a/docs/zh-cn/custom_quantum_functions.md
+++ b/docs/zh-cn/custom_quantum_functions.md
@@ -297,7 +297,7 @@ void suspend_wakeup_init_user(void) {
297本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应 297本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应
298 298
299```c 299```c
300uint32_t layer_state_set_user(uint32_t state) { 300layer_state_t layer_state_set_user(layer_state_t state) {
301 switch (biton32(state)) { 301 switch (biton32(state)) {
302 case _RAISE: 302 case _RAISE:
303 rgblight_setrgb (0x00, 0x00, 0xFF); 303 rgblight_setrgb (0x00, 0x00, 0xFF);
@@ -321,7 +321,7 @@ uint32_t layer_state_set_user(uint32_t state) {
321### `layer_state_set_*` 函数文档 321### `layer_state_set_*` 函数文档
322 322
323* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)` 323* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)`
324* 布局: `uint32_t layer_state_set_user(uint32_t state)` 324* 布局: `layer_state_t layer_state_set_user(layer_state_t state)`
325 325
326 326
327该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态) 327该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态)
@@ -377,7 +377,7 @@ void keyboard_post_init_user(void) {
377以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。 377以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。
378 378
379```c 379```c
380uint32_t layer_state_set_user(uint32_t state) { 380layer_state_t layer_state_set_user(layer_state_t state) {
381 switch (biton32(state)) { 381 switch (biton32(state)) {
382 case _RAISE: 382 case _RAISE:
383 if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } 383 if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }