summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/ChangeLog/20200229.md2
-rw-r--r--docs/ChangeLog/20200530.md20
-rw-r--r--docs/ChangeLog/20210529.md6
-rw-r--r--docs/ChangeLog/20210828.md2
-rw-r--r--docs/ChangeLog/20220226.md2
-rw-r--r--docs/custom_quantum_functions.md8
-rw-r--r--docs/drivers/serial.md16
-rw-r--r--docs/feature_debounce_type.md2
-rw-r--r--docs/feature_eeprom.md4
-rw-r--r--docs/feature_layers.md46
-rw-r--r--docs/feature_userspace.md43
-rw-r--r--docs/features/audio.md29
-rw-r--r--docs/features/bootmagic.md2
-rw-r--r--docs/features/encoders.md2
-rw-r--r--docs/features/haptic_feedback.md14
-rw-r--r--docs/features/pointing_device.md79
-rw-r--r--docs/features/repeat_key.md34
-rw-r--r--docs/features/rgb_matrix.md14
-rw-r--r--docs/features/space_cadet.md2
-rw-r--r--docs/features/split_keyboard.md62
-rw-r--r--docs/features/st7565.md4
-rw-r--r--docs/features/stenography.md2
-rw-r--r--docs/hand_wire.md10
-rw-r--r--docs/hardware_drivers.md2
-rw-r--r--docs/quantum_painter_lvgl.md4
-rw-r--r--docs/squeezing_avr.md14
-rw-r--r--docs/usb_nkro.txt2
27 files changed, 216 insertions, 211 deletions
diff --git a/docs/ChangeLog/20200229.md b/docs/ChangeLog/20200229.md
index 02bca3e371..fd075c24e0 100644
--- a/docs/ChangeLog/20200229.md
+++ b/docs/ChangeLog/20200229.md
@@ -36,7 +36,7 @@ Four times a year QMK runs a process for merging Breaking Changes. A Breaking Ch
36## Encoder flip 36## Encoder flip
37 37
38* Flips the encoder direction so that `clockwise == true` is for actually turning the knob clockwise 38* Flips the encoder direction so that `clockwise == true` is for actually turning the knob clockwise
39* Adds `ENCODER_DIRECTION_FLIP` define, so that reversing the expected dirction is simple for users. 39* Adds `ENCODER_DIRECTION_FLIP` define, so that reversing the expected direction is simple for users.
40* Cleans up documentation page for encoders 40* Cleans up documentation page for encoders
41 41
42 42
diff --git a/docs/ChangeLog/20200530.md b/docs/ChangeLog/20200530.md
index 9def9ae123..701b6bd5d6 100644
--- a/docs/ChangeLog/20200530.md
+++ b/docs/ChangeLog/20200530.md
@@ -19,7 +19,7 @@ These PRs move the V-USB driver code out of the qmk_firmware repository and into
19 19
20Updates all of the per key tap-hold functions to pass the `keyrecord_t` structure, and include documentation changes. 20Updates all of the per key tap-hold functions to pass the `keyrecord_t` structure, and include documentation changes.
21 21
22Any remaining versions or code outside of the main repo will need to be converted: 22Any remaining versions or code outside of the main repo will need to be converted:
23| Old function | New Function | 23| Old function | New Function |
24|------------------------------------------------------|---------------------------------------------------------------------------| 24|------------------------------------------------------|---------------------------------------------------------------------------|
25|`uint16_t get_tapping_term(uint16_t keycode)` |`uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record)` | 25|`uint16_t get_tapping_term(uint16_t keycode)` |`uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record)` |
@@ -38,7 +38,7 @@ After the next breaking change you will not be able to build if `bin/qmk hello`
38[#8269](https://github.com/qmk/qmk_firmware/pull/8269) 38[#8269](https://github.com/qmk/qmk_firmware/pull/8269)
39 39
40- Provides debug functionality on ChibiOS/ARM that is more compliant than previous integrations. 40- Provides debug functionality on ChibiOS/ARM that is more compliant than previous integrations.
41- Less maintenence, fewer QMK customisations, and allows QMK to sidestep previous compile and runtime issues. 41- Less maintenance, fewer QMK customisations, and allows QMK to sidestep previous compile and runtime issues.
42- A `make git-submodule` may be required after pulling the latest QMK Firmware code to update to the new dependency. 42- A `make git-submodule` may be required after pulling the latest QMK Firmware code to update to the new dependency.
43 43
44### Fixed RGB_DISABLE_AFTER_TIMEOUT to be seconds based & small internals cleanup 44### Fixed RGB_DISABLE_AFTER_TIMEOUT to be seconds based & small internals cleanup
@@ -51,8 +51,10 @@ After the next breaking change you will not be able to build if `bin/qmk hello`
51 51
52The `RGB_DISABLE_AFTER_TIMEOUT` definition is now deprecated, and has been superseded by `RGB_DISABLE_TIMEOUT`. To use the new definition, rename `RGB_DISABLE_AFTER_TIMEOUT` to `RGB_DISABLE_TIMEOUT` in your `config.h` file, and multiply the value set by 1200. 52The `RGB_DISABLE_AFTER_TIMEOUT` definition is now deprecated, and has been superseded by `RGB_DISABLE_TIMEOUT`. To use the new definition, rename `RGB_DISABLE_AFTER_TIMEOUT` to `RGB_DISABLE_TIMEOUT` in your `config.h` file, and multiply the value set by 1200.
53 53
54Before: `#define RGB_DISABLE_AFTER_TIMEOUT 100` 54```diff
55After: `#define RGB_DISABLE_TIMEOUT 120000` 55-#define RGB_DISABLE_AFTER_TIMEOUT 100
56+#define RGB_DISABLE_TIMEOUT 120000
57```
56 58
57### Switch to qmk forks for everything 59### Switch to qmk forks for everything
58 60
@@ -103,8 +105,8 @@ This allows current lily58 firmware to advance with updates to the `split_common
103- Alternatively, if you did not change the OLED code from that in `default`, you may find it easier to simply copy the [relevant section](https://github.com/qmk/qmk_firmware/blob/4ac310668501ae6786c711ecc8f01f62ddaa1c0b/keyboards/lily58/keymaps/default/keymap.c#L138-L172). Otherwise, the changes you need to make are as follows (sample change [here](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7R138-R173)) 105- Alternatively, if you did not change the OLED code from that in `default`, you may find it easier to simply copy the [relevant section](https://github.com/qmk/qmk_firmware/blob/4ac310668501ae6786c711ecc8f01f62ddaa1c0b/keyboards/lily58/keymaps/default/keymap.c#L138-L172). Otherwise, the changes you need to make are as follows (sample change [here](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7R138-R173))
104- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L138-L141) the block 106- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L138-L141) the block
105```c 107```c
106#ifdef SSD1306OLED 108#ifdef SSD1306OLED
107 iota_gfx_init(!has_usb()); // turns on the display 109 iota_gfx_init(!has_usb()); // turns on the display
108#endif 110#endif
109``` 111```
110- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides: 112- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
@@ -127,7 +129,7 @@ oled_rotation_t oled_init_user(oled_rotation_t rotation) {
127 129
128* Refactor to use split_common and remove split codes under the zinc/revx/ 130* Refactor to use split_common and remove split codes under the zinc/revx/
129* Add - backlight RGB LED and/or underglow RGB LED option 131* Add - backlight RGB LED and/or underglow RGB LED option
130* Add - continuous RGB animations feature (between L and R halves) 132* Add - continuous RGB animations feature (between L and R halves)
131* Fix - keymap files to adapt to changes 133* Fix - keymap files to adapt to changes
132 * all authors of keymaps confirmed this PR 134 * all authors of keymaps confirmed this PR
133* Update - documents and rules.mk 135* Update - documents and rules.mk
@@ -164,8 +166,8 @@ void keyboard_pre_init_kb(void) {
164- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190) 166- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190)
165- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L91-L158) the block 167- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L91-L158) the block
166```c 168```c
167#ifdef SSD1306OLED 169#ifdef SSD1306OLED
168 iota_gfx_init(!has_usb()); // turns on the display 170 iota_gfx_init(!has_usb()); // turns on the display
169#endif 171#endif
170``` 172```
171- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides: 173- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
diff --git a/docs/ChangeLog/20210529.md b/docs/ChangeLog/20210529.md
index 69923b0c5a..e3d250874a 100644
--- a/docs/ChangeLog/20210529.md
+++ b/docs/ChangeLog/20210529.md
@@ -12,7 +12,7 @@ Added support for MK66F18 (Teensy 3.6) microcontroller.
12 12
13### New command: qmk console ([#12828](https://github.com/qmk/qmk_firmware/pull/12828)) {#new-command-qmk-console} 13### New command: qmk console ([#12828](https://github.com/qmk/qmk_firmware/pull/12828)) {#new-command-qmk-console}
14 14
15A new `qmk console` command has been added for attaching to your keyboard's console. It operates similiarly to QMK Toolbox by allowing you to connect to one or more keyboard consoles to display debugging messages. 15A new `qmk console` command has been added for attaching to your keyboard's console. It operates similarly to QMK Toolbox by allowing you to connect to one or more keyboard consoles to display debugging messages.
16 16
17### Improved command: qmk config {#improve-command-qmk-config} 17### Improved command: qmk config {#improve-command-qmk-config}
18 18
@@ -121,8 +121,8 @@ bool encoder_update_user(uint8_t index, bool clockwise) {
121 tap_code(KC_UP); 121 tap_code(KC_UP);
122 } 122 }
123 } 123 }
124 return true; 124 return true;
125 // If you return true, this will allow the keyboard level code to run, as well. 125 // If you return true, this will allow the keyboard level code to run, as well.
126 //Returning false will override the keyboard level code. Depending on how the keyboard level function is set up. 126 //Returning false will override the keyboard level code. Depending on how the keyboard level function is set up.
127} 127}
128``` 128```
diff --git a/docs/ChangeLog/20210828.md b/docs/ChangeLog/20210828.md
index 18b1d92b0c..9268711262 100644
--- a/docs/ChangeLog/20210828.md
+++ b/docs/ChangeLog/20210828.md
@@ -104,7 +104,7 @@ void dip_switch_update_user(uint8_t index, bool active) {
104 } 104 }
105} 105}
106 106
107void dip_switch_update_mask_kb(uint32_t state) { 107void dip_switch_update_mask_kb(uint32_t state) {
108 dip_switch_update_mask_user(state); 108 dip_switch_update_mask_user(state);
109} 109}
110 110
diff --git a/docs/ChangeLog/20220226.md b/docs/ChangeLog/20220226.md
index a10b6447ea..29283a3a9c 100644
--- a/docs/ChangeLog/20220226.md
+++ b/docs/ChangeLog/20220226.md
@@ -29,7 +29,7 @@ Bootloader configuration is no longer assumed. Keyboards must now set either:
29 29
30### Rename `AdafruitBLE` to `BluefruitLE` ([#16127](https://github.com/qmk/qmk_firmware/pull/16127)) 30### Rename `AdafruitBLE` to `BluefruitLE` ([#16127](https://github.com/qmk/qmk_firmware/pull/16127))
31 31
32In preparation of future bluetooth work, the `AdafruitBLE` integration has been renamed to allow potential for any other Adafruit BLE products. 32In preparation of future bluetooth work, the `AdafruitBLE` integration has been renamed to allow potential for any other Adafruit BLE products.
33 33
34### Updated Keyboard Codebases {#updated-keyboard-codebases} 34### Updated Keyboard Codebases {#updated-keyboard-codebases}
35 35
diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md
index c69beb055e..2c4eac64f0 100644
--- a/docs/custom_quantum_functions.md
+++ b/docs/custom_quantum_functions.md
@@ -145,7 +145,7 @@ void keyboard_pre_init_user(void) {
145 145
146This is called when the matrix is initialized, and after some of the hardware has been set up, but before many of the features have been initialized. 146This is called when the matrix is initialized, and after some of the hardware has been set up, but before many of the features have been initialized.
147 147
148This is useful for setting up stuff that you may need elsewhere, but isn't hardware related nor is dependant on where it's started. 148This is useful for setting up stuff that you may need elsewhere, but isn't hardware related nor is dependent on where it's started.
149 149
150 150
151### `matrix_init_*` Function Documentation 151### `matrix_init_*` Function Documentation
@@ -209,7 +209,7 @@ You should use this function if you need custom matrix scanning code. It can als
209 209
210This function gets called at the end of all QMK processing, before starting the next iteration. You can safely assume that QMK has dealt with the last matrix scan at the time that these functions are invoked -- layer states have been updated, USB reports have been sent, LEDs have been updated, and displays have been drawn. 210This function gets called at the end of all QMK processing, before starting the next iteration. You can safely assume that QMK has dealt with the last matrix scan at the time that these functions are invoked -- layer states have been updated, USB reports have been sent, LEDs have been updated, and displays have been drawn.
211 211
212Similar to `matrix_scan_*`, these are called as often as the MCU can handle. To keep your board responsive, it's suggested to do as little as possible during these function calls, potentially throtting their behaviour if you do indeed require implementing something special. 212Similar to `matrix_scan_*`, these are called as often as the MCU can handle. To keep your board responsive, it's suggested to do as little as possible during these function calls, potentially throttling their behaviour if you do indeed require implementing something special.
213 213
214### Example `void housekeeping_task_user(void)` implementation 214### Example `void housekeeping_task_user(void)` implementation
215 215
@@ -246,7 +246,7 @@ void check_rgb_timeout(void) {
246 } 246 }
247} 247}
248/* Then, call the above functions from QMK's built in post processing functions like so */ 248/* Then, call the above functions from QMK's built in post processing functions like so */
249/* Runs at the end of each scan loop, check if RGB timeout has occured or not */ 249/* Runs at the end of each scan loop, check if RGB timeout has occurred or not */
250void housekeeping_task_user(void) { 250void housekeeping_task_user(void) {
251#ifdef RGBLIGHT_TIMEOUT 251#ifdef RGBLIGHT_TIMEOUT
252 check_rgb_timeout(); 252 check_rgb_timeout();
@@ -316,7 +316,7 @@ bool shutdown_kb(bool jump_to_bootloader) {
316 if (!shutdown_user(jump_to_bootloader)) { 316 if (!shutdown_user(jump_to_bootloader)) {
317 return false; 317 return false;
318 } 318 }
319 319
320 if (jump_to_bootloader) { 320 if (jump_to_bootloader) {
321 // red for bootloader 321 // red for bootloader
322 rgb_matrix_set_color_all(RGB_OFF); 322 rgb_matrix_set_color_all(RGB_OFF);
diff --git a/docs/drivers/serial.md b/docs/drivers/serial.md
index dda75f629a..2c78f59043 100644
--- a/docs/drivers/serial.md
+++ b/docs/drivers/serial.md
@@ -33,7 +33,7 @@ On ARM platforms the bitbang driver causes connection issues when using it toget
33+-------+ +-------+ 33+-------+ +-------+
34``` 34```
35 35
36One GPIO pin is needed for the bitbang driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SOFT_SERIAL_PIN` (SSP) in the configuration. A TRS or USB cable provides enough conductors for this driver to function. 36One GPIO pin is needed for the bitbang driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SOFT_SERIAL_PIN` (SSP) in the configuration. A TRS or USB cable provides enough conductors for this driver to function.
37 37
38### Setup 38### Setup
39 39
@@ -63,12 +63,12 @@ SERIAL_DRIVER = bitbang
63 63
64## USART Half-duplex 64## USART Half-duplex
65 65
66Targeting ARM boards based on ChibiOS, where communication is offloaded to a USART hardware device that supports Half-duplex operation. The advantages over bitbanging are fast, accurate timings and reduced CPU usage. Therefore it is advised to choose Half-duplex over Bitbang if MCU is capable of utilising Half-duplex, and Full-duplex can't be used instead (e.g. lack of available GPIO pins, or imcompatible PCB design). 66Targeting ARM boards based on ChibiOS, where communication is offloaded to a USART hardware device that supports Half-duplex operation. The advantages over bitbanging are fast, accurate timings and reduced CPU usage. Therefore it is advised to choose Half-duplex over Bitbang if MCU is capable of utilising Half-duplex, and Full-duplex can't be used instead (e.g. lack of available GPIO pins, or incompatible PCB design).
67 67
68### Pin configuration 68### Pin configuration
69 69
70``` 70```
71 LEFT RIGHT 71 LEFT RIGHT
72+-------+ | | +-------+ 72+-------+ | | +-------+
73| | R R | | 73| | R R | |
74| | | SERIAL | | | 74| | | SERIAL | | |
@@ -80,7 +80,7 @@ Targeting ARM boards based on ChibiOS, where communication is offloaded to a USA
80+-------+ +-------+ 80+-------+ +-------+
81``` 81```
82 82
83Only one GPIO pin is needed for the Half-duplex driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SERIAL_USART_TX_PIN` in the configuration. Ensure that the pin chosen for split communication can operate as the TX pin of the contoller's USART peripheral. A TRS or USB cable provides enough conductors for this driver to function. As the split connection is configured to operate in open-drain mode, an **external pull-up resistor is needed to keep the line high**. Resistor values of 1.5kΩ to 8.2kΩ are known to work. 83Only one GPIO pin is needed for the Half-duplex driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SERIAL_USART_TX_PIN` in the configuration. Ensure that the pin chosen for split communication can operate as the TX pin of the contoller's USART peripheral. A TRS or USB cable provides enough conductors for this driver to function. As the split connection is configured to operate in open-drain mode, an **external pull-up resistor is needed to keep the line high**. Resistor values of 1.5kΩ to 8.2kΩ are known to work.
84 84
85::: warning 85::: warning
86***Note:*** A pull-up resistor isn't required for RP2040 controllers configured with PIO subsystem. 86***Note:*** A pull-up resistor isn't required for RP2040 controllers configured with PIO subsystem.
@@ -278,7 +278,7 @@ There are several advanced configuration options that can be defined in your key
278 278
279### Baudrate 279### Baudrate
280 280
281If you're having issues or need a higher baudrate with serial communication, you can change the baudrate which in turn controls the communication speed for serial. You want to lower the baudrate if you experience failed transactions. 281If you're having issues or need a higher baudrate with serial communication, you can change the baudrate which in turn controls the communication speed for serial. You want to lower the baudrate if you experience failed transactions.
282 282
283```c 283```c
284#define SELECT_SOFT_SERIAL_SPEED n 284#define SELECT_SOFT_SERIAL_SPEED n
@@ -307,19 +307,19 @@ This is the default time window in milliseconds in which a successful communicat
307 307
308## Troubleshooting 308## Troubleshooting
309 309
310If you're having issues withe serial communication, you can enable debug messages that will give you insights which part of the communication failed. The enable these messages add to your keyboards `config.h` file: 310If you're having issues with serial communication, you can enable debug messages that will give you insights which part of the communication failed. The enable these messages add to your keyboards `config.h` file:
311 311
312```c 312```c
313#define SERIAL_DEBUG 313#define SERIAL_DEBUG
314``` 314```
315 315
316::: tip 316::: tip
317The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](../faq_debug). 317The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](../faq_debug).
318::: 318:::
319 319
320## Alternate Functions for selected STM32 MCUs 320## Alternate Functions for selected STM32 MCUs
321 321
322Pins for USART Peripherals with 322Pins for USART Peripherals with
323 323
324### STM32F303 / Proton-C [Datasheet](https://www.st.com/resource/en/datasheet/stm32f303cc.pdf) 324### STM32F303 / Proton-C [Datasheet](https://www.st.com/resource/en/datasheet/stm32f303cc.pdf)
325 325
diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md
index eb29b4ef26..4e3b0f4543 100644
--- a/docs/feature_debounce_type.md
+++ b/docs/feature_debounce_type.md
@@ -47,7 +47,7 @@ susceptible to noise, you must choose a debounce method that will also mitigate
47 * Debounce algorithms often have a 'debounce time' parameter, that specifies the maximum settling time of the switch contacts. 47 * Debounce algorithms often have a 'debounce time' parameter, that specifies the maximum settling time of the switch contacts.
48 This time might be measured in various units: 48 This time might be measured in various units:
49 * Cycles-based debouncing waits n cycles (scans), decreasing count by one each matrix_scan 49 * Cycles-based debouncing waits n cycles (scans), decreasing count by one each matrix_scan
50 * Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does substraction to figure out time elapsed. 50 * Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does subtraction to figure out time elapsed.
51 * Timestamp-based debouncing is usually superior, especially in the case of noise-resistant devices because settling times of physical 51 * Timestamp-based debouncing is usually superior, especially in the case of noise-resistant devices because settling times of physical
52 switches is specified in units of time, and should not depend on the matrix scan-rate of the keyboard. 52 switches is specified in units of time, and should not depend on the matrix scan-rate of the keyboard.
53 * Cycles-based debouncing is sometimes considered inferior, because the settling time that it is able to compensate for depends on the 53 * Cycles-based debouncing is sometimes considered inferior, because the settling time that it is able to compensate for depends on the
diff --git a/docs/feature_eeprom.md b/docs/feature_eeprom.md
index 22257b3202..7d40e81f5a 100644
--- a/docs/feature_eeprom.md
+++ b/docs/feature_eeprom.md
@@ -100,7 +100,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
100 if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled 100 if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled
101 if (user_config.rgb_layer_change) { // only if this is enabled 101 if (user_config.rgb_layer_change) { // only if this is enabled
102 user_config.rgb_layer_change = false; // disable it, and 102 user_config.rgb_layer_change = false; // disable it, and
103 eeconfig_update_user(user_config.raw); // write the setings to EEPROM 103 eeconfig_update_user(user_config.raw); // write the settings to EEPROM
104 } 104 }
105 } 105 }
106 return true; break; 106 return true; break;
@@ -109,7 +109,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
109 } 109 }
110} 110}
111``` 111```
112And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EE_CLR` keycode or [Bootmagic](features/bootmagic) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. 112And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EE_CLR` keycode or [Bootmagic](features/bootmagic) functionality. For example, if you want to set rgb layer indication by default, and save the default valued.
113 113
114```c 114```c
115void eeconfig_init_user(void) { // EEPROM is getting reset! 115void eeconfig_init_user(void) { // EEPROM is getting reset!
diff --git a/docs/feature_layers.md b/docs/feature_layers.md
index da6a28bd88..8e6510ca2a 100644
--- a/docs/feature_layers.md
+++ b/docs/feature_layers.md
@@ -25,7 +25,7 @@ active layer until pressed again.
25 25
26Currently, the `layer` argument of `LT()` is limited to layers 0-15, and the `kc` argument to the [Basic Keycode set](keycodes_basic), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 4 bits are used for the function identifier and 4 bits for the layer, leaving only 8 bits for the keycode. 26Currently, the `layer` argument of `LT()` is limited to layers 0-15, and the `kc` argument to the [Basic Keycode set](keycodes_basic), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 4 bits are used for the function identifier and 4 bits for the layer, leaving only 8 bits for the keycode.
27 27
28For a similar reason, the `layer` argument of `LM()` is also limited to layers 0-15 and the `mod` argument must fit within 5 bits. As a consequence, although left and right modifiers are supported by `LM()`, it is impossible to mix and match left and right modifiers. Specifying at least one right-hand modifier in a combination such as `MOD_RALT|MOD_LSFT` will convert *all* the listed modifiers to their right-hand counterpart. So, using the aforementionned mod-mask will actually send <kbd>Right Alt</kbd>+<kbd>Right Shift</kbd>. Make sure to use the `MOD_xxx` constants over alternative ways of specifying modifiers when defining your layer-mod key. 28For a similar reason, the `layer` argument of `LM()` is also limited to layers 0-15 and the `mod` argument must fit within 5 bits. As a consequence, although left and right modifiers are supported by `LM()`, it is impossible to mix and match left and right modifiers. Specifying at least one right-hand modifier in a combination such as `MOD_RALT|MOD_LSFT` will convert *all* the listed modifiers to their right-hand counterpart. So, using the aforementioned mod-mask will actually send <kbd>Right Alt</kbd>+<kbd>Right Shift</kbd>. Make sure to use the `MOD_xxx` constants over alternative ways of specifying modifiers when defining your layer-mod key.
29 29
30| `LM(1,KC_LSFT)` | `LM(1,MOD_MASK_SHIFT)` | `LM(1,MOD_BIT(KC_LSFT))` | `LM(1,MOD_LSFT)` | 30| `LM(1,KC_LSFT)` | `LM(1,MOD_MASK_SHIFT)` | `LM(1,MOD_BIT(KC_LSFT))` | `LM(1,MOD_LSFT)` |
31|:---------------:|:----------------------:|:------------------------:|:----------------:| 31|:---------------:|:----------------------:|:------------------------:|:----------------:|
@@ -61,27 +61,27 @@ Sometimes, you might want to switch between layers in a macro or as part of a ta
61 61
62There are a number of functions (and variables) related to how you can use or manipulate the layers. 62There are a number of functions (and variables) related to how you can use or manipulate the layers.
63 63
64|Function |Description | 64|Function |Description |
65|----------------------------------------------|---------------------------------------------------------------------------------------------------------| 65|---------------------------------------------|--------------------------------------------------------------------------------------------------------|
66| `layer_state_set(layer_mask)` | Directly sets the layer state (avoid unless you know what you are doing). | 66|`layer_state_set(layer_mask)` |Directly sets the layer state (avoid unless you know what you are doing). |
67| `layer_clear()` | Clears all layers (turns them all off). | 67|`layer_clear()` |Clears all layers (turns them all off). |
68| `layer_move(layer)` | Turns specified layer on, and all other layers off. | 68|`layer_move(layer)` |Turns specified layer on, and all other layers off. |
69| `layer_on(layer)` | Turns specified layer on, leaves all other layers in existing state. | 69|`layer_on(layer)` |Turns specified layer on, leaves all other layers in existing state. |
70| `layer_off(layer)` | Turns specified layer off, leaves all other layers in existing state. | 70|`layer_off(layer)` |Turns specified layer off, leaves all other layers in existing state. |
71| `layer_invert(layer)` | Inverts/toggles the state of the specified layer | 71|`layer_invert(layer)` |Inverts/toggles the state of the specified layer |
72| `layer_or(layer_mask)` | Turns on layers based on matching bits between specifed layer and existing layer state. | 72|`layer_or(layer_mask)` |Turns on layers based on matching bits between specified layer and existing layer state. |
73| `layer_and(layer_mask)` | Turns on layers based on matching enabled bits between specifed layer and existing layer state. | 73|`layer_and(layer_mask)` |Turns on layers based on matching enabled bits between specified layer and existing layer state. |
74| `layer_xor(layer_mask)` | Turns on layers based on non-matching bits between specifed layer and existing layer state. | 74|`layer_xor(layer_mask)` |Turns on layers based on non-matching bits between specified layer and existing layer state. |
75| `layer_debug(layer_mask)` | Prints out the current bit mask and highest active layer to debugger console. | 75|`layer_debug(layer_mask)` |Prints out the current bit mask and highest active layer to debugger console. |
76| `default_layer_set(layer_mask)` | Directly sets the default layer state (avoid unless you know what you are doing). | 76|`default_layer_set(layer_mask)` |Directly sets the default layer state (avoid unless you know what you are doing). |
77| `default_layer_or(layer_mask)` | Turns on layers based on matching bits between specifed layer and existing default layer state. | 77|`default_layer_or(layer_mask)` |Turns on layers based on matching bits between specified layer and existing default layer state. |
78| `default_layer_and(layer_mask)` | Turns on layers based on matching enabled bits between specifed layer and existing default layer state. | 78|`default_layer_and(layer_mask)` |Turns on layers based on matching enabled bits between specified layer and existing default layer state.|
79| `default_layer_xor(layer_mask)` | Turns on layers based on non-matching bits between specifed layer and existing default layer state. | 79|`default_layer_xor(layer_mask)` |Turns on layers based on non-matching bits between specified layer and existing default layer state. |
80| `default_layer_debug(layer_mask)` | Prints out the current bit mask and highest active default layer to debugger console. | 80|`default_layer_debug(layer_mask)` |Prints out the current bit mask and highest active default layer to debugger console. |
81| [`set_single_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) | Sets the default layer, but does _not_ write it to persistent memory (EEPROM). | 81|[`set_single_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) |Sets the default layer, but does _not_ write it to persistent memory (EEPROM). |
82| [`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) | Sets the default layer and writes it to persistent memory (EEPROM). | 82|[`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer)|Sets the default layer and writes it to persistent memory (EEPROM). |
83| [`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z) | Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off). | 83|[`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z) |Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off).|
84| [`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z) | Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions. | 84|[`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z) |Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions. |
85 85
86In addition to the functions that you can call, there are a number of callback functions that get called every time the layer changes. This passes the layer state to the function, where it can be read or modified. 86In addition to the functions that you can call, there are a number of callback functions that get called every time the layer changes. This passes the layer state to the function, where it can be read or modified.
87 87
@@ -154,7 +154,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
154 switch (keycode) { 154 switch (keycode) {
155 case KC_CYCLE_LAYERS: 155 case KC_CYCLE_LAYERS:
156 // Our logic will happen on presses, nothing is done on releases 156 // Our logic will happen on presses, nothing is done on releases
157 if (!record->event.pressed) { 157 if (!record->event.pressed) {
158 // We've already handled the keycode (doing nothing), let QMK know so no further code is run unnecessarily 158 // We've already handled the keycode (doing nothing), let QMK know so no further code is run unnecessarily
159 return false; 159 return false;
160 } 160 }
diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md
index 0f5c4a5f96..2c8c08b38e 100644
--- a/docs/feature_userspace.md
+++ b/docs/feature_userspace.md
@@ -24,10 +24,10 @@ For example,
24 24
25 make planck:jack 25 make planck:jack
26 26
27Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`. 27Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
28 28
29::: warning 29::: warning
30This `name` can be [overridden](#override-default-userspace), if needed. 30This `name` can be [overridden](#override-default-userspace), if needed.
31::: 31:::
32 32
33## `Rules.mk` 33## `Rules.mk`
@@ -38,9 +38,9 @@ It's highly recommended that you use `<name>.c` as the default source file to be
38 38
39 SRC += <name>.c 39 SRC += <name>.c
40 40
41Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h to start off with, though. 41Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h to start off with, though.
42 42
43The `/users/<name>/rules.mk` file will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard. 43The `/users/<name>/rules.mk` file will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard.
44 44
45For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can add support for that if the RGBLIGHT feature is enabled: 45For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can add support for that if the RGBLIGHT feature is enabled:
46```make 46```make
@@ -82,7 +82,7 @@ You should use the `config.h` for [configuration options](config_options), and t
82 82
83Please include authorship (your name, GitHub username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses). 83Please include authorship (your name, GitHub username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
84 84
85You can use this as a template: 85You can use this as a template:
86``` 86```
87Copyright <year> <name> <email> @<github_username> 87Copyright <year> <name> <email> @<github_username>
88 88
@@ -100,9 +100,9 @@ You should have received a copy of the GNU General Public License
100along with this program. If not, see <http://www.gnu.org/licenses/>. 100along with this program. If not, see <http://www.gnu.org/licenses/>.
101``` 101```
102 102
103You'd want to replace the year, name, email and GitHub username with your info. 103You'd want to replace the year, name, email and GitHub username with your info.
104 104
105Additionally, this is a good place to document your code, if you wish to share it with others. 105Additionally, this is a good place to document your code, if you wish to share it with others.
106 106
107## Build All Keyboards That Support a Specific Keymap 107## Build All Keyboards That Support a Specific Keymap
108 108
@@ -118,20 +118,21 @@ This is ideal for when you want ensure everything compiles successfully when pre
118 118
119## Examples 119## Examples
120 120
121For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/_example). 121For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/_example).
122For more complicated examples, checkout the [`awesome-qmk` colletion](https://github.com/qmk/awesome-qmk). 122
123For more complicated examples, checkout the [`awesome-qmk` collection](https://github.com/qmk/awesome-qmk).
123 124
124 125
125### Customized Functions 126### Customized Functions
126 127
127QMK has a bunch of [functions](custom_quantum_functions) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions#a-word-on-core-vs-keyboards-vs-keymap) that you can use. You will pretty much always want to use the user version of these functions. But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap. 128QMK has a bunch of [functions](custom_quantum_functions) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions#a-word-on-core-vs-keyboards-vs-keymap) that you can use. You will pretty much always want to use the user version of these functions. But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap.
128 129
129However, you can actually add support for keymap version, so that you can use it in both your userspace and your keymap! 130However, you can actually add support for keymap version, so that you can use it in both your userspace and your keymap!
130 131
131 132
132For instance, let's look at the `layer_state_set_user()` function. You can enable the [Tri Layer State](ref_functions#olkb-tri-layers) functionality on all of your boards, while also retaining the Tri Layer functionality in your `keymap.c` files. 133For instance, let's look at the `layer_state_set_user()` function. You can enable the [Tri Layer State](ref_functions#olkb-tri-layers) functionality on all of your boards, while also retaining the Tri Layer functionality in your `keymap.c` files.
133 134
134In your `<name.c>` file, you'd want to add this: 135In your `<name.c>` file, you'd want to add this:
135```c 136```c
136__attribute__ ((weak)) 137__attribute__ ((weak))
137layer_state_t layer_state_set_keymap (layer_state_t state) { 138layer_state_t layer_state_set_keymap (layer_state_t state) {
@@ -143,7 +144,7 @@ layer_state_t layer_state_set_user (layer_state_t state) {
143 return layer_state_set_keymap (state); 144 return layer_state_set_keymap (state);
144} 145}
145``` 146```
146The `__attribute__ ((weak))` part tells the compiler that this is a placeholder function that can then be replaced by a version in your `keymap.c`. That way, you don't need to add it to your `keymap.c`, but if you do, you won't get any conflicts because the function is the same name. 147The `__attribute__ ((weak))` part tells the compiler that this is a placeholder function that can then be replaced by a version in your `keymap.c`. That way, you don't need to add it to your `keymap.c`, but if you do, you won't get any conflicts because the function is the same name.
147 148
148The `_keymap` part here doesn't matter, it just needs to be something other than `_quantum`, `_kb`, or `_user`, since those are already in use. So you could use `layer_state_set_mine`, `layer_state_set_fn`, or anything else. 149The `_keymap` part here doesn't matter, it just needs to be something other than `_quantum`, `_kb`, or `_user`, since those are already in use. So you could use `layer_state_set_mine`, `layer_state_set_fn`, or anything else.
149 150
@@ -151,7 +152,7 @@ You can see a list of this and other common functions in [`template.c`](https://
151 152
152### Custom Features 153### Custom Features
153 154
154Since the Userspace feature can support a staggering number of boards, you may have boards that you want to enable certain functionality for, but not for others. And you can actually create "features" that you can enable or disable in your own userspace. 155Since the Userspace feature can support a staggering number of boards, you may have boards that you want to enable certain functionality for, but not for others. And you can actually create "features" that you can enable or disable in your own userspace.
155 156
156For instance, if you wanted to have a bunch of macros available, but only on certain boards (to save space), you could "hide" them being a `#ifdef MACROS_ENABLED`, and then enable it per board. To do this, add this to your rules.mk 157For instance, if you wanted to have a bunch of macros available, but only on certain boards (to save space), you could "hide" them being a `#ifdef MACROS_ENABLED`, and then enable it per board. To do this, add this to your rules.mk
157```make 158```make
@@ -159,11 +160,11 @@ ifeq ($(strip $(MACROS_ENABLED)), yes)
159 OPT_DEFS += -DMACROS_ENABLED 160 OPT_DEFS += -DMACROS_ENABLED
160endif 161endif
161``` 162```
162The `OPT_DEFS` setting causes `MACROS_ENABLED` to be defined for your keyboards (note the `-D` in front of the name), and you could use `#ifdef MACROS_ENABLED` to check the status in your c/h files, and handle that code based on that. 163The `OPT_DEFS` setting causes `MACROS_ENABLED` to be defined for your keyboards (note the `-D` in front of the name), and you could use `#ifdef MACROS_ENABLED` to check the status in your c/h files, and handle that code based on that.
163 164
164Then you add `MACROS_ENABLED = yes` to the `rules.mk` for you keymap to enable this feature and the code in your userspace. 165Then you add `MACROS_ENABLED = yes` to the `rules.mk` for you keymap to enable this feature and the code in your userspace.
165 166
166And in your `process_record_user` function, you'd do something like this: 167And in your `process_record_user` function, you'd do something like this:
167```c 168```c
168bool process_record_user(uint16_t keycode, keyrecord_t *record) { 169bool process_record_user(uint16_t keycode, keyrecord_t *record) {
169 switch (keycode) { 170 switch (keycode) {
@@ -187,9 +188,9 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
187 188
188### Consolidated Macros 189### Consolidated Macros
189 190
190If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that. This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too. 191If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that. This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too.
191 192
192First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead. This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well. You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you wont have any overlapping keycodes 193First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead. This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well. You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you won't have any overlapping keycodes
193 194
194Then add `#include "<name>.h"` to all of your keymap.c files. This allows you to use these new keycodes without having to redefine them in each keymap. 195Then add `#include "<name>.h"` to all of your keymap.c files. This allows you to use these new keycodes without having to redefine them in each keymap.
195 196
@@ -245,7 +246,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
245} 246}
246``` 247```
247 248
248For boards that may not have a shift button (such as on a macro pad), we need a way to always include the bootloader option. To do that, add the following to the `rules.mk` in your userspace folder: 249For boards that may not have a shift button (such as on a macro pad), we need a way to always include the bootloader option. To do that, add the following to the `rules.mk` in your userspace folder:
249 250
250```make 251```make
251ifeq ($(strip $(FLASH_BOOTLOADER)), yes) 252ifeq ($(strip $(FLASH_BOOTLOADER)), yes)
@@ -255,7 +256,7 @@ endif
255 256
256This will add a new `KC_MAKE` keycode that can be used in any of your keymaps. And this keycode will output `make <keyboard>:<keymap>`, making frequent compiling easier. And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time. 257This will add a new `KC_MAKE` keycode that can be used in any of your keymaps. And this keycode will output `make <keyboard>:<keymap>`, making frequent compiling easier. And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time.
257 258
258Also, holding Shift will add the flash target (`:flash`) to the command. Holding Control will add some commands that will speed up compiling time by processing multiple files at once. 259Also, holding Shift will add the flash target (`:flash`) to the command. Holding Control will add some commands that will speed up compiling time by processing multiple files at once.
259 260
260And for the boards that lack a shift key, or that you want to always attempt the flashing part, you can add `FLASH_BOOTLOADER = yes` to the `rules.mk` of that keymap. 261And for the boards that lack a shift key, or that you want to always attempt the flashing part, you can add `FLASH_BOOTLOADER = yes` to the `rules.mk` of that keymap.
261 262
diff --git a/docs/features/audio.md b/docs/features/audio.md
index 2f5e5b2d98..a5f770d811 100644
--- a/docs/features/audio.md
+++ b/docs/features/audio.md
@@ -73,16 +73,13 @@ Should you rather choose to generate and use your own sample-table with the DAC
73 73
74 74
75### PWM (software) 75### PWM (software)
76if the DAC pins are unavailable (or the MCU has no usable DAC at all, like STM32F1xx); PWM can be an alternative. 76If the DAC pins are unavailable (or the MCU has no usable DAC at all, like STM32F1xx); PWM can be an alternative.
77Note that there is currently only one speaker/pin supported. 77Note that there is currently only one speaker/pin supported.
78 78
79set in `rules.mk`: 79To use this feature, set `AUDIO_DRIVER = pwm_software` in `rules.mk` and set `#define AUDIO_PIN C13` (can be any pin) in `config.h` to have the selected pin output a pwm signal, generated from a timer callback which toggles the pin in software.
80
81`AUDIO_DRIVER = pwm_software` and in `config.h`:
82`#define AUDIO_PIN C13` (can be any pin) to have the selected pin output a pwm signal, generated from a timer callback which toggles the pin in software.
83 80
84#### Wiring 81#### Wiring
85the usual piezo wiring: red goes to the selected AUDIO_PIN, black goes to ground. 82The usual piezo wiring: red goes to the selected AUDIO_PIN, black goes to ground.
86 83
87OR if you can chose to drive one piezo with two pins, for example `#define AUDIO_PIN B1`, `#define AUDIO_PIN_ALT B2` in `config.h`, with `#define AUDIO_PIN_ALT_AS_NEGATIVE` - then the red lead could go to B1, the black to B2. 84OR if you can chose to drive one piezo with two pins, for example `#define AUDIO_PIN B1`, `#define AUDIO_PIN_ALT B2` in `config.h`, with `#define AUDIO_PIN_ALT_AS_NEGATIVE` - then the red lead could go to B1, the black to B2.
88 85
@@ -159,7 +156,7 @@ PLAY_LOOP(my_song);
159 156
160It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard. 157It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard.
161 158
162The available keycodes for audio are: 159The available keycodes for audio are:
163 160
164|Key |Aliases |Description | 161|Key |Aliases |Description |
165|-------------------------|---------|-------------------------------------------| 162|-------------------------|---------|-------------------------------------------|
@@ -178,8 +175,8 @@ These keycodes turn all of the audio functionality on and off. Turning it off m
178|`AUDIO_PIN` | *Not defined* |Configures the pin that the speaker is connected to. | 175|`AUDIO_PIN` | *Not defined* |Configures the pin that the speaker is connected to. |
179|`AUDIO_PIN_ALT` | *Not defined* |Configures the pin for a second speaker or second pin connected to one speaker. | 176|`AUDIO_PIN_ALT` | *Not defined* |Configures the pin for a second speaker or second pin connected to one speaker. |
180|`AUDIO_PIN_ALT_AS_NEGATIVE` | *Not defined* |Enables support for one speaker connected to two pins. | 177|`AUDIO_PIN_ALT_AS_NEGATIVE` | *Not defined* |Enables support for one speaker connected to two pins. |
181|`AUDIO_INIT_DELAY` | *Not defined* |Enables delay during startup song to accomidate for USB startup issues. | 178|`AUDIO_INIT_DELAY` | *Not defined* |Enables delay during startup song to accommodate for USB startup issues. |
182|`AUDIO_ENABLE_TONE_MULTIPLEXING` | *Not defined* |Enables time splicing/multiplexing to create multiple tones simutaneously. | 179|`AUDIO_ENABLE_TONE_MULTIPLEXING` | *Not defined* |Enables time splicing/multiplexing to create multiple tones simultaneously. |
183|`AUDIO_POWER_CONTROL_PIN` | *Not defined* |Enables power control code to enable or cut off power to speaker (such as with PAM8302 amp). | 180|`AUDIO_POWER_CONTROL_PIN` | *Not defined* |Enables power control code to enable or cut off power to speaker (such as with PAM8302 amp). |
184|`AUDIO_POWER_CONTROL_PIN_ON_STATE`| `1` |The state of the audio power control pin when audio is "on" - `1` for high, `0` for low. | 181|`AUDIO_POWER_CONTROL_PIN_ON_STATE`| `1` |The state of the audio power control pin when audio is "on" - `1` for high, `0` for low. |
185|`STARTUP_SONG` | `STARTUP_SOUND` |Plays when the keyboard starts up (audio.c) | 182|`STARTUP_SONG` | `STARTUP_SOUND` |Plays when the keyboard starts up (audio.c) |
@@ -301,9 +298,9 @@ Things that return false are not part of the mask, and are always processed.
301 298
302### Music Map 299### Music Map
303 300
304By default, the Music Mode uses the columns and row to determine the scale for the keys. For a board that uses a rectangular matrix that matches the keyboard layout, this is just fine. However, for boards that use a more complicated matrix (such as the Planck Rev6, or many split keyboards) this would result in a very skewed experience. 301By default, the Music Mode uses the columns and row to determine the scale for the keys. For a board that uses a rectangular matrix that matches the keyboard layout, this is just fine. However, for boards that use a more complicated matrix (such as the Planck Rev6, or many split keyboards) this would result in a very skewed experience.
305 302
306However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural. 303However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural.
307 304
308To enable this feature, add `#define MUSIC_MAP` to your `config.h` file, and then you will want to add a `uint8_t music_map` to your keyboard's `c` file, or your `keymap.c`. 305To enable this feature, add `#define MUSIC_MAP` to your `config.h` file, and then you will want to add a `uint8_t music_map` to your keyboard's `c` file, or your `keymap.c`.
309 306
@@ -316,13 +313,13 @@ const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12(
316); 313);
317``` 314```
318 315
319You will want to use whichever `LAYOUT` macro that your keyboard uses here. This maps it to the correct key location. Start in the bottom left of the keyboard layout, and move to the right, and then upwards. Fill in all the entries until you have a complete matrix. 316You will want to use whichever `LAYOUT` macro that your keyboard uses here. This maps it to the correct key location. Start in the bottom left of the keyboard layout, and move to the right, and then upwards. Fill in all the entries until you have a complete matrix.
320 317
321You can look at the [Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) as an example of how to implement this. 318You can look at the [Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) as an example of how to implement this.
322 319
323## Audio Click 320## Audio Click
324 321
325This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly. 322This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly.
326 323
327Keycodes available: 324Keycodes available:
328 325
@@ -341,7 +338,7 @@ The feature is disabled by default, to save space. To enable it, add this to yo
341#define AUDIO_CLICKY 338#define AUDIO_CLICKY
342``` 339```
343 340
344You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values: 341You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values:
345 342
346| Option | Default Value | Description | 343| Option | Default Value | Description |
347|--------|---------------|-------------| 344|--------|---------------|-------------|
@@ -349,7 +346,7 @@ You can configure the default, min and max frequencies, the stepping and built i
349| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). | 346| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
350| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the highest frequency. Too high may result in coworkers attacking you. | 347| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the highest frequency. Too high may result in coworkers attacking you. |
351| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. This is a multiplicative factor. The default steps the frequency up/down by a musical minor third. | 348| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. This is a multiplicative factor. The default steps the frequency up/down by a musical minor third. |
352| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. | 349| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. |
353| `AUDIO_CLICKY_DELAY_DURATION` | 1 | An integer note duration where 1 is 1/16th of the tempo, or a sixty-fourth note (see `quantum/audio/musical_notes.h` for implementation details). The main clicky effect will be delayed by this duration. Adjusting this to values around 6-12 will help compensate for loud switches. | 350| `AUDIO_CLICKY_DELAY_DURATION` | 1 | An integer note duration where 1 is 1/16th of the tempo, or a sixty-fourth note (see `quantum/audio/musical_notes.h` for implementation details). The main clicky effect will be delayed by this duration. Adjusting this to values around 6-12 will help compensate for loud switches. |
354 351
355## MIDI Functionality 352## MIDI Functionality
diff --git a/docs/features/bootmagic.md b/docs/features/bootmagic.md
index 49fae5ba45..15c2bec293 100644
--- a/docs/features/bootmagic.md
+++ b/docs/features/bootmagic.md
@@ -46,7 +46,7 @@ When [handedness](split_keyboard#setting-handedness) is predetermined via option
46 } 46 }
47``` 47```
48 48
49If you pick the top right key for the right half, it is `R05` on the top layout. Within the key matrix below, `R05` is located on row 4 columnn 4. To use that key as the right half's Bootmagic trigger, add these entries to your `config.h` file: 49If you pick the top right key for the right half, it is `R05` on the top layout. Within the key matrix below, `R05` is located on row 4 column 4. To use that key as the right half's Bootmagic trigger, add these entries to your `config.h` file:
50 50
51```c 51```c
52#define BOOTMAGIC_ROW_RIGHT 4 52#define BOOTMAGIC_ROW_RIGHT 4
diff --git a/docs/features/encoders.md b/docs/features/encoders.md
index a674eaa4a6..59f949be65 100644
--- a/docs/features/encoders.md
+++ b/docs/features/encoders.md
@@ -68,7 +68,7 @@ Additionally, if one side does not have an encoder, you can specify `{}` for the
68``` 68```
69 69
70::: warning 70::: warning
71Keep in mind that whenver you change the encoder resolution, you will need to reflash the half that has the encoder affected by the change. 71Keep in mind that whenever you change the encoder resolution, you will need to reflash the half that has the encoder affected by the change.
72::: 72:::
73 73
74## Encoder map {#encoder-map} 74## Encoder map {#encoder-map}
diff --git a/docs/features/haptic_feedback.md b/docs/features/haptic_feedback.md
index 52667965a0..08e66ea8e1 100644
--- a/docs/features/haptic_feedback.md
+++ b/docs/features/haptic_feedback.md
@@ -44,14 +44,14 @@ Not all keycodes below will work depending on which haptic mechanism you have ch
44|`QK_HAPTIC_MODE_NEXT` |`HF_NEXT`| Go to next DRV2605L waveform | 44|`QK_HAPTIC_MODE_NEXT` |`HF_NEXT`| Go to next DRV2605L waveform |
45|`QK_HAPTIC_MODE_PREVIOUS` |`HF_PREV`| Go to previous DRV2605L waveform | 45|`QK_HAPTIC_MODE_PREVIOUS` |`HF_PREV`| Go to previous DRV2605L waveform |
46|`QK_HAPTIC_CONTINUOUS_TOGGLE`|`HF_CONT`| Toggle continuous haptic mode on/off | 46|`QK_HAPTIC_CONTINUOUS_TOGGLE`|`HF_CONT`| Toggle continuous haptic mode on/off |
47|`QK_HAPTIC_CONTINUOUS_UP` |`HF_CONU`| Increase DRV2605L continous haptic strength | 47|`QK_HAPTIC_CONTINUOUS_UP` |`HF_CONU`| Increase DRV2605L continuous haptic strength |
48|`QK_HAPTIC_CONTINUOUS_DOWN` |`HF_COND`| Decrease DRV2605L continous haptic strength | 48|`QK_HAPTIC_CONTINUOUS_DOWN` |`HF_COND`| Decrease DRV2605L continuous haptic strength |
49|`QK_HAPTIC_DWELL_UP` |`HF_DWLU`| Increase Solenoid dwell time | 49|`QK_HAPTIC_DWELL_UP` |`HF_DWLU`| Increase Solenoid dwell time |
50|`QK_HAPTIC_DWELL_DOWN` |`HF_DWLD`| Decrease Solenoid dwell time | 50|`QK_HAPTIC_DWELL_DOWN` |`HF_DWLD`| Decrease Solenoid dwell time |
51 51
52### Solenoids 52### Solenoids
53 53
54The solenoid code supports relay switches, and similar hardware, as well as solenoids. 54The solenoid code supports relay switches, and similar hardware, as well as solenoids.
55 55
56For a regular solenoid, you will need a build a circuit to drive the solenoid through a mosfet as most MCU will not be able to provide the current needed to drive the coil in the solenoid. 56For a regular solenoid, you will need a build a circuit to drive the solenoid through a mosfet as most MCU will not be able to provide the current needed to drive the coil in the solenoid.
57 57
@@ -75,7 +75,7 @@ For relay switches, the hardware may already contain all of that ciruitry, and j
75|`SOLENOID_BUZZ_NONACTUATED` | `SOLENOID_MIN_DWELL` |Non-Actuated-time when the switch is in buzz mode. | 75|`SOLENOID_BUZZ_NONACTUATED` | `SOLENOID_MIN_DWELL` |Non-Actuated-time when the switch is in buzz mode. |
76 76
77* If solenoid buzz is off, then dwell time is how long the "plunger" stays activated. The dwell time changes how the solenoid sounds. 77* If solenoid buzz is off, then dwell time is how long the "plunger" stays activated. The dwell time changes how the solenoid sounds.
78* If solenoid buzz is on, then dwell time sets the length of the buzz, while `SOLENOID_BUZZ_ACTUATED` and `SOLENOID_BUZZ_NONACTUATED` set the (non-)actuation times withing the buzz period. 78* If solenoid buzz is on, then dwell time sets the length of the buzz, while `SOLENOID_BUZZ_ACTUATED` and `SOLENOID_BUZZ_NONACTUATED` set the (non-)actuation times within the buzz period.
79* With the current implementation, for any of the above time settings, the precision of these settings may be affected by how fast the keyboard is able to scan the matrix. 79* With the current implementation, for any of the above time settings, the precision of these settings may be affected by how fast the keyboard is able to scan the matrix.
80 Therefore, if the keyboards scanning routine is slow, it may be preferable to set `SOLENOID_DWELL_STEP_SIZE` to a value slightly smaller than the time it takes to scan the keyboard. 80 Therefore, if the keyboards scanning routine is slow, it may be preferable to set `SOLENOID_DWELL_STEP_SIZE` to a value slightly smaller than the time it takes to scan the keyboard.
81 81
@@ -104,7 +104,7 @@ Eccentric Rotating Mass vibration motors (ERM) is motor with a off-set weight at
104``` 104```
105##### LRA 105##### LRA
106 106
107Linear resonant actuators (LRA, also know as a linear vibrator) works different from a ERM. A LRA has a weight and magnet suspended by springs and a voice coil. When the drive signal is applied, the weight would be vibrate on a single axis (side to side or up and down). Since the weight is attached to a spring, there is a resonance effect at a specific frequency. This frequency is where the LRA will operate the most efficiently. Refer to the motor's datasheet for the recommanded range for this frequency. 107Linear resonant actuators (LRA, also know as a linear vibrator) works different from a ERM. A LRA has a weight and magnet suspended by springs and a voice coil. When the drive signal is applied, the weight would be vibrate on a single axis (side to side or up and down). Since the weight is attached to a spring, there is a resonance effect at a specific frequency. This frequency is where the LRA will operate the most efficiently. Refer to the motor's datasheet for the recommended range for this frequency.
108 108
109```c 109```c
110#define DRV2605L_FB_ERM_LRA 1 110#define DRV2605L_FB_ERM_LRA 1
@@ -114,7 +114,7 @@ Linear resonant actuators (LRA, also know as a linear vibrator) works different
114/* Please refer to your datasheet for the optimal setting for your specific motor. */ 114/* Please refer to your datasheet for the optimal setting for your specific motor. */
115#define DRV2605L_RATED_VOLTAGE 2 115#define DRV2605L_RATED_VOLTAGE 2
116#define DRV2605L_V_PEAK 2.8 116#define DRV2605L_V_PEAK 2.8
117#define DRV2605L_V_RMS 2.0 117#define DRV2605L_V_RMS 2.0
118#define DRV2605L_V_PEAK 2.1 118#define DRV2605L_V_PEAK 2.1
119#define DRV2605L_F_LRA 205 /* resonance freq */ 119#define DRV2605L_F_LRA 205 /* resonance freq */
120``` 120```
@@ -125,7 +125,7 @@ DRV2605L comes with preloaded library of various waveform sequences that can be
125 125
126List of waveform sequences from the datasheet: 126List of waveform sequences from the datasheet:
127 127
128|seq# | Sequence name |seq# | Sequence name |seq# |Sequence name | 128|seq# | Sequence name |seq# | Sequence name |seq# |Sequence name |
129|-----|---------------------|-----|-----------------------------------|-----|--------------------------------------| 129|-----|---------------------|-----|-----------------------------------|-----|--------------------------------------|
130| 1 | strong_click | 43 | lg_dblclick_med_60 | 85 | transition_rampup_med_smooth2 | 130| 1 | strong_click | 43 | lg_dblclick_med_60 | 85 | transition_rampup_med_smooth2 |
131| 2 | strong_click_60 | 44 | lg_dblsharp_tick | 86 | transition_rampup_short_smooth1 | 131| 2 | strong_click_60 | 44 | lg_dblsharp_tick | 86 | transition_rampup_short_smooth1 |
diff --git a/docs/features/pointing_device.md b/docs/features/pointing_device.md
index f25ea1b033..d6dcddcdf0 100644
--- a/docs/features/pointing_device.md
+++ b/docs/features/pointing_device.md
@@ -51,7 +51,7 @@ The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surfac
51| `ADNS9800_CS_PIN` | (Required) Sets the Chip Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | 51| `ADNS9800_CS_PIN` | (Required) Sets the Chip Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` |
52 52
53 53
54The CPI range is 800-8200, in increments of 200. Defaults to 1800 CPI. 54The CPI range is 800-8200, in increments of 200. Defaults to 1800 CPI.
55 55
56### Analog Joystick 56### Analog Joystick
57 57
@@ -258,7 +258,7 @@ To use the paw 3204 sensor, add this to your `rules.mk`
258POINTING_DEVICE_DRIVER = paw3204 258POINTING_DEVICE_DRIVER = paw3204
259``` 259```
260 260
261The paw 3204 sensor uses a serial type protocol for communication, and requires an additional light source. 261The paw 3204 sensor uses a serial type protocol for communication, and requires an additional light source.
262 262
263| Setting (`config.h`) | Description | Default | 263| Setting (`config.h`) | Description | Default |
264| -------------------- |--------------------------------------------------------------- | -------------------------- | 264| -------------------- |--------------------------------------------------------------- | -------------------------- |
@@ -275,7 +275,7 @@ To use the Pimoroni Trackball module, add this to your `rules.mk`:
275POINTING_DEVICE_DRIVER = pimoroni_trackball 275POINTING_DEVICE_DRIVER = pimoroni_trackball
276``` 276```
277 277
278The Pimoroni Trackball module is a I2C based breakout board with an RGB enable trackball. 278The Pimoroni Trackball module is a I2C based breakout board with an RGB enable trackball.
279 279
280| Setting (`config.h`) | Description | Default | 280| Setting (`config.h`) | Description | Default |
281| ------------------------------------ | ---------------------------------------------------------------------------------- | ------- | 281| ------------------------------------ | ---------------------------------------------------------------------------------- | ------- |
@@ -386,7 +386,7 @@ void pointing_device_driver_set_cpi(uint16_t cpi) {}
386``` 386```
387 387
388::: warning 388::: warning
389Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/pointing_device_drivers.c`, but there may be cases where it's very specific to the hardware. So these functions are provided, just in case. 389Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/pointing_device_drivers.c`, but there may be cases where it's very specific to the hardware. So these functions are provided, just in case.
390::: 390:::
391 391
392## Common Configuration 392## Common Configuration
@@ -413,7 +413,7 @@ Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/
413When using `SPLIT_POINTING_ENABLE` the `POINTING_DEVICE_MOTION_PIN` functionality is not supported and `POINTING_DEVICE_TASK_THROTTLE_MS` will default to `1`. Increasing this value will increase transport performance at the cost of possible mouse responsiveness. 413When using `SPLIT_POINTING_ENABLE` the `POINTING_DEVICE_MOTION_PIN` functionality is not supported and `POINTING_DEVICE_TASK_THROTTLE_MS` will default to `1`. Increasing this value will increase transport performance at the cost of possible mouse responsiveness.
414::: 414:::
415 415
416The `POINTING_DEVICE_CS_PIN`, `POINTING_DEVICE_SDIO_PIN`, and `POINTING_DEVICE_SCLK_PIN` provide a convenient way to define a single pin that can be used for an interchangeable sensor config. This allows you to have a single config, without defining each device. Each sensor allows for this to be overridden with their own defines. 416The `POINTING_DEVICE_CS_PIN`, `POINTING_DEVICE_SDIO_PIN`, and `POINTING_DEVICE_SCLK_PIN` provide a convenient way to define a single pin that can be used for an interchangeable sensor config. This allows you to have a single config, without defining each device. Each sensor allows for this to be overridden with their own defines.
417 417
418::: warning 418::: warning
419Any pointing device with a lift/contact status can integrate inertial cursor feature into its driver, controlled by `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE`. e.g. PMW3360 can use Lift_Stat from Motion register. Note that `POINTING_DEVICE_MOTION_PIN` cannot be used with this feature; continuous polling of `get_report()` is needed to generate glide reports. 419Any pointing device with a lift/contact status can integrate inertial cursor feature into its driver, controlled by `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE`. e.g. PMW3360 can use Lift_Stat from Motion register. Note that `POINTING_DEVICE_MOTION_PIN` cannot be used with this feature; continuous polling of `get_report()` is needed to generate glide reports.
@@ -424,7 +424,7 @@ Any pointing device with a lift/contact status can integrate inertial cursor fea
424| Setting | Description | Default | 424| Setting | Description | Default |
425| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------- | 425| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------- |
426| `POINTING_DEVICE_HIRES_SCROLL_ENABLE` | (Optional) Enables high resolution scrolling. | _not defined_ | 426| `POINTING_DEVICE_HIRES_SCROLL_ENABLE` | (Optional) Enables high resolution scrolling. | _not defined_ |
427| `POINTING_DEVICE_HIRES_SCROLL_MULTIPLIER`| (Optional) Resolution mutiplier value used by high resolution scrolling. Must be between 1 and 127, inclusive. | `120` | 427| `POINTING_DEVICE_HIRES_SCROLL_MULTIPLIER`| (Optional) Resolution multiplier value used by high resolution scrolling. Must be between 1 and 127, inclusive. | `120` |
428| `POINTING_DEVICE_HIRES_SCROLL_EXPONENT` | (Optional) Resolution exponent value used by high resolution scrolling. Must be between 0 and 127, inclusive. | `0` | 428| `POINTING_DEVICE_HIRES_SCROLL_EXPONENT` | (Optional) Resolution exponent value used by high resolution scrolling. Must be between 0 and 127, inclusive. | `0` |
429 429
430The `POINTING_DEVICE_HIRES_SCROLL_ENABLE` setting enables smooth and continuous scrolling when using trackballs or high-end encoders as mouse wheels (as opposed to the typical stepped behavior of most mouse wheels). 430The `POINTING_DEVICE_HIRES_SCROLL_ENABLE` setting enables smooth and continuous scrolling when using trackballs or high-end encoders as mouse wheels (as opposed to the typical stepped behavior of most mouse wheels).
@@ -435,7 +435,7 @@ If even smoother scrolling than provided by this default value is desired, first
435The function `pointing_device_get_hires_scroll_resolution()` can be called to get the pre-computed resolution multiplier value as a `uint16_t`. 435The function `pointing_device_get_hires_scroll_resolution()` can be called to get the pre-computed resolution multiplier value as a `uint16_t`.
436 436
437::: warning 437::: warning
438High resolution scrolling usually results in larger and/or more frequent mouse reports. This can result in overflow errors and overloading of the host computer's input buffer. 438High resolution scrolling usually results in larger and/or more frequent mouse reports. This can result in overflow errors and overloading of the host computer's input buffer.
439To deal with these issues, define `WHEEL_EXTENDED_REPORT` and throttle the rate at which mouse reports are sent. 439To deal with these issues, define `WHEEL_EXTENDED_REPORT` and throttle the rate at which mouse reports are sent.
440::: 440:::
441 441
@@ -465,7 +465,7 @@ If there is a `_RIGHT` configuration option or callback, the [common configurati
465::: 465:::
466 466
467 467
468## Callbacks and Functions 468## Callbacks and Functions
469 469
470| Function | Description | 470| Function | Description |
471| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | 471| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
@@ -513,7 +513,7 @@ To manually manipulate the mouse reports outside of the `pointing_device_task_*`
513 513
514* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer 514* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer
515* `pointing_device_set_report(report_mouse_t mouse_report)` - Overrides and saves the report_mouse_t to be sent to the host computer 515* `pointing_device_set_report(report_mouse_t mouse_report)` - Overrides and saves the report_mouse_t to be sent to the host computer
516* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report. 516* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report.
517 517
518When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in `pointing_device_send()`, which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden. 518When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in `pointing_device_send()`, which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden.
519 519
@@ -548,7 +548,7 @@ Recall that the mouse report is set to zero (except the buttons) whenever it is
548 548
549### Drag Scroll or Mouse Scroll 549### Drag Scroll or Mouse Scroll
550 550
551A very common implementation is to use the mouse movement to scroll instead of moving the cursor on the system. This uses the `pointing_device_task_user` callback to intercept and modify the mouse report before it's sent to the host system. 551A very common implementation is to use the mouse movement to scroll instead of moving the cursor on the system. This uses the `pointing_device_task_user` callback to intercept and modify the mouse report before it's sent to the host system.
552 552
553```c 553```c
554enum custom_keycodes { 554enum custom_keycodes {
@@ -575,7 +575,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
575} 575}
576``` 576```
577 577
578This allows you to toggle between scrolling and cursor movement by pressing the DRAG_SCROLL key. 578This allows you to toggle between scrolling and cursor movement by pressing the DRAG_SCROLL key.
579 579
580### Advanced Drag Scroll 580### Advanced Drag Scroll
581 581
@@ -711,7 +711,7 @@ If you are having issues with pointing device drivers debug messages can be enab
711```c 711```c
712#define POINTING_DEVICE_DEBUG 712#define POINTING_DEVICE_DEBUG
713``` 713```
714 714
715::: tip 715::: tip
716The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](../faq_debug). 716The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](../faq_debug).
717::: 717:::
@@ -720,7 +720,7 @@ The messages will be printed out to the `CONSOLE` output. For additional informa
720--- 720---
721# Automatic Mouse Layer {#pointing-device-auto-mouse} 721# Automatic Mouse Layer {#pointing-device-auto-mouse}
722 722
723When using a pointing device combined with a keyboard the mouse buttons are often kept on a separate layer from the default keyboard layer, which requires pressing or holding a key to change layers before using the mouse. To make this easier and more efficient an additional pointing device feature may be enabled that will automatically activate a target layer as soon as the pointing device is active _(in motion, mouse button pressed etc.)_ and deactivate the target layer after a set time. 723When using a pointing device combined with a keyboard the mouse buttons are often kept on a separate layer from the default keyboard layer, which requires pressing or holding a key to change layers before using the mouse. To make this easier and more efficient an additional pointing device feature may be enabled that will automatically activate a target layer as soon as the pointing device is active _(in motion, mouse button pressed etc.)_ and deactivate the target layer after a set time.
724 724
725Additionally if any key that is defined as a mouse key is pressed then the layer will be held as long as the key is pressed and the timer will be reset on key release. When a non-mouse key is pressed then the layer is deactivated early _(with some exceptions see below)_. Mod, mod tap, and one shot mod keys are ignored _(i.e. don't hold or activate layer but do not deactivate the layer either)_ when sending a modifier keycode _(e.g. hold for mod tap)_ allowing for mod keys to be used with the mouse without activating the target layer when typing. 725Additionally if any key that is defined as a mouse key is pressed then the layer will be held as long as the key is pressed and the timer will be reset on key release. When a non-mouse key is pressed then the layer is deactivated early _(with some exceptions see below)_. Mod, mod tap, and one shot mod keys are ignored _(i.e. don't hold or activate layer but do not deactivate the layer either)_ when sending a modifier keycode _(e.g. hold for mod tap)_ allowing for mod keys to be used with the mouse without activating the target layer when typing.
726 726
@@ -754,8 +754,9 @@ void pointing_device_init_user(void) {
754} 754}
755``` 755```
756 756
757Because the auto mouse feature can be disabled/enabled during runtime and starts as disabled by default it must be enabled by calling `set_auto_mouse_enable(true);` somewhere in firmware before the feature will work. 757Because the auto mouse feature can be disabled/enabled during runtime and starts as disabled by default it must be enabled by calling `set_auto_mouse_enable(true);` somewhere in firmware before the feature will work.
758_Note: for setting the target layer during initialization either setting `AUTO_MOUSE_DEFAULT_LAYER` in `config.h` or calling `set_auto_mouse_layer(<mouse_layer>)` can be used._ 758
759_Note: for setting the target layer during initialization either setting `AUTO_MOUSE_DEFAULT_LAYER` in `config.h` or calling `set_auto_mouse_layer(<mouse_layer>)` can be used._
759 760
760 761
761## How to Customize: 762## How to Customize:
@@ -774,7 +775,7 @@ There are a few ways to control the auto mouse feature with both `config.h` opti
774 775
775### Adding mouse keys 776### Adding mouse keys
776 777
777While all default mouse keys and layer keys(for current mouse layer) are treated as mouse keys, additional Keyrecords can be added to mouse keys by adding them to the is_mouse_record_* stack. 778While all default mouse keys and layer keys(for current mouse layer) are treated as mouse keys, additional Keyrecords can be added to mouse keys by adding them to the is_mouse_record_* stack.
778 779
779#### Callbacks for setting up additional key codes as mouse keys: 780#### Callbacks for setting up additional key codes as mouse keys:
780| Callback | Description | 781| Callback | Description |
@@ -782,7 +783,7 @@ While all default mouse keys and layer keys(for current mouse layer) are treated
782| `bool is_mouse_record_kb(uint16_t keycode, keyrecord_t* record)` | keyboard level callback for adding mouse keys | 783| `bool is_mouse_record_kb(uint16_t keycode, keyrecord_t* record)` | keyboard level callback for adding mouse keys |
783| `bool is_mouse_record_user(uint16_t keycode, keyrecord_t* record)` | user/keymap level callback for adding mouse keys | 784| `bool is_mouse_record_user(uint16_t keycode, keyrecord_t* record)` | user/keymap level callback for adding mouse keys |
784 785
785##### To use the callback function to add mouse keys: 786##### To use the callback function to add mouse keys:
786 787
787The following code will cause the enter key and all of the arrow keys to be treated as mouse keys (hold target layer while they are pressed and reset active layer timer). 788The following code will cause the enter key and all of the arrow keys to be treated as mouse keys (hold target layer while they are pressed and reset active layer timer).
788```c 789```c
@@ -806,7 +807,7 @@ bool is_mouse_record_kb(uint16_t keycode, keyrecord_t* record) {
806 807
807There are several functions that allow for more advanced interaction with the auto mouse feature allowing for greater control. 808There are several functions that allow for more advanced interaction with the auto mouse feature allowing for greater control.
808 809
809### Functions to control auto mouse enable and target layer: 810### Functions to control auto mouse enable and target layer:
810| Function | Description | Aliases | Return type | 811| Function | Description | Aliases | Return type |
811| :--------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------- | --------------: | 812| :--------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------- | --------------: |
812| `set_auto_mouse_enable(bool enable)` | Enable or disable auto mouse (true:enable, false:disable) | | `void`(None) | 813| `set_auto_mouse_enable(bool enable)` | Enable or disable auto mouse (true:enable, false:disable) | | `void`(None) |
@@ -825,25 +826,27 @@ There are several functions that allow for more advanced interaction with the au
825| `get_auto_mouse_key_tracker(void)` | Gets the current count for the auto mouse key tracker. | | `int8_t` | 826| `get_auto_mouse_key_tracker(void)` | Gets the current count for the auto mouse key tracker. | | `int8_t` |
826| `set_auto_mouse_key_tracker(int8_t key_tracker)` | Sets/Overrides the current count for the auto mouse key tracker. | | `void`(None) | 827| `set_auto_mouse_key_tracker(int8_t key_tracker)` | Sets/Overrides the current count for the auto mouse key tracker. | | `void`(None) |
827 828
828_NOTES:_ 829_NOTES:_
829 - _Due to the nature of how some functions work, the `auto_mouse_trigger_reset`, and `auto_mouse_layer_off` functions should never be called in the `layer_state_set_*` stack as this can cause indefinite loops._ 830
830 - _It is recommended that `remove_auto_mouse_layer` is used in the `layer_state_set_*` stack of functions and `auto_mouse_layer_off` is used everywhere else_ 831- _Due to the nature of how some functions work, the `auto_mouse_trigger_reset`, and `auto_mouse_layer_off` functions should never be called in the `layer_state_set_*` stack as this can cause indefinite loops._
831 - _`remove_auto_mouse_layer(state, false)` or `auto_mouse_layer_off()` should be called before any instance of `set_auto_mouse_enabled(false)` or `set_auto_mouse_layer(layer)` to ensure that the target layer will be removed appropriately before disabling auto mouse or changing target to avoid a stuck layer_ 832- _It is recommended that `remove_auto_mouse_layer` is used in the `layer_state_set_*` stack of functions and `auto_mouse_layer_off` is used everywhere else_
832 833- _`remove_auto_mouse_layer(state, false)` or `auto_mouse_layer_off()` should be called before any instance of `set_auto_mouse_enabled(false)` or `set_auto_mouse_layer(layer)` to ensure that the target layer will be removed appropriately before disabling auto mouse or changing target to avoid a stuck layer_
833### Functions for handling custom key events: 834
835### Functions for handling custom key events:
834| Function | Description | Return type | 836| Function | Description | Return type |
835| :--------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------: | 837| :--------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------: |
836| `auto_mouse_keyevent(bool pressed)` | Auto mouse mouse key event (true: key down, false: key up) | `void`(None) | 838| `auto_mouse_keyevent(bool pressed)` | Auto mouse mouse key event (true: key down, false: key up) | `void`(None) |
837| `auto_mouse_trigger_reset(bool pressed)` | Reset auto mouse status on key down and start delay timer (non-mouse key event) | `void`(None) | 839| `auto_mouse_trigger_reset(bool pressed)` | Reset auto mouse status on key down and start delay timer (non-mouse key event) | `void`(None) |
838| `auto_mouse_toggle(void)` | Toggle on/off target toggle state (disables layer deactivation when true) | `void`(None) | 840| `auto_mouse_toggle(void)` | Toggle on/off target toggle state (disables layer deactivation when true) | `void`(None) |
839| `get_auto_mouse_toggle(void)` | Return value of toggling state variable | `bool` | 841| `get_auto_mouse_toggle(void)` | Return value of toggling state variable | `bool` |
842
840_NOTE: Generally it would be preferable to use the `is_mouse_record_*` functions to add any additional keys that should act as mouse keys rather than adding `auto_mouse_keyevent(record.event->pressed)` to `process_records_*`_ 843_NOTE: Generally it would be preferable to use the `is_mouse_record_*` functions to add any additional keys that should act as mouse keys rather than adding `auto_mouse_keyevent(record.event->pressed)` to `process_records_*`_
841 844
842### Advanced control examples 845### Advanced control examples
843 846
844#### Disable auto mouse on certain layers: 847#### Disable auto mouse on certain layers:
845 848
846The auto mouse feature can be disabled any time and this can be helpful if you want to disable the auto mouse feature under certain circumstances such as when particular layers are active. One issue however is the handling of the target layer, it needs to be removed appropriately **before** disabling auto mouse _(see notes under control functions above)_. The following function would disable the auto_mouse feature whenever the layers `_LAYER5` through `_LAYER7` are active as the top most layer _(ignoring target layer)_. 849The auto mouse feature can be disabled any time and this can be helpful if you want to disable the auto mouse feature under certain circumstances such as when particular layers are active. One issue however is the handling of the target layer, it needs to be removed appropriately **before** disabling auto mouse _(see notes under control functions above)_. The following function would disable the auto_mouse feature whenever the layers `_LAYER5` through `_LAYER7` are active as the top most layer _(ignoring target layer)_.
847 850
848```c 851```c
849// in keymap.c: 852// in keymap.c:
@@ -882,7 +885,7 @@ layer_state_t default_layer_state_set_user(layer_state_t state) {
882 auto_mouse_layer_off(); 885 auto_mouse_layer_off();
883 set_auto_mouse_layer(_MOUSE_LAYER_2); 886 set_auto_mouse_layer(_MOUSE_LAYER_2);
884 break; 887 break;
885 888
886 default: 889 default:
887 if((AUTO_MOUSE_TARGET_LAYER) == _MOUSE_LAYER_1) break; 890 if((AUTO_MOUSE_TARGET_LAYER) == _MOUSE_LAYER_1) break;
888 auto_mouse_layer_off(); 891 auto_mouse_layer_off();
@@ -892,9 +895,11 @@ layer_state_t default_layer_state_set_user(layer_state_t state) {
892} 895}
893``` 896```
894 897
895### Use custom keys to control auto mouse: 898### Use custom keys to control auto mouse:
896Custom key records could also be created that control the auto mouse feature. 899
897The code example below would create a custom key that would toggle the auto mouse feature on and off when pressed while also setting a bool that could be used to disable other code that may turn it on such as the layer code above. 900Custom key records could also be created that control the auto mouse feature.
901
902The code example below would create a custom key that would toggle the auto mouse feature on and off when pressed while also setting a bool that could be used to disable other code that may turn it on such as the layer code above.
898 903
899```c 904```c
900// in config.h: 905// in config.h:
@@ -923,11 +928,11 @@ bool process_record_user(uint16_t keycode, keyrecord_t* record) {
923 928
924## Customize Target Layer Activation 929## Customize Target Layer Activation
925 930
926Layer activation can be customized by overwriting the `auto_mouse_activation` function. This function is checked every time `pointing_device_task` is called when inactive and every `AUTO_MOUSE_DEBOUNCE` ms when active, and will evaluate pointing device level conditions that trigger target layer activation. When it returns true, the target layer will be activated barring the usual exceptions _(e.g. delay time has not expired)_. 931Layer activation can be customized by overwriting the `auto_mouse_activation` function. This function is checked every time `pointing_device_task` is called when inactive and every `AUTO_MOUSE_DEBOUNCE` ms when active, and will evaluate pointing device level conditions that trigger target layer activation. When it returns true, the target layer will be activated barring the usual exceptions _(e.g. delay time has not expired)_.
927 932
928By default it will return true if any of the `mouse_report` axes `x`,`y`,`h`,`v` are non zero, or if there is any mouse buttons active in `mouse_report`. 933By default it will return true if any of the `mouse_report` axes `x`,`y`,`h`,`v` are non zero, or if there is any mouse buttons active in `mouse_report`.
929_Note: The Cirque pinnacle track pad already implements a custom activation function that will activate on touchdown as well as movement all of the default conditions, currently this only works for the master side of split keyboards._ 934_Note: The Cirque pinnacle track pad already implements a custom activation function that will activate on touchdown as well as movement all of the default conditions, currently this only works for the master side of split keyboards._
930 935
931| Function | Description | Return type | 936| Function | Description | Return type |
932| :--------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------: | 937| :--------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------: |
933| `auto_mouse_activation(report_mouse_t mouse_report)` | Overwritable function that controls target layer activation (when true) | `bool` | 938| `auto_mouse_activation(report_mouse_t mouse_report)` | Overwritable function that controls target layer activation (when true) | `bool` |
@@ -939,12 +944,12 @@ When using a custom pointing device (overwriting `pointing_device_task`) the fol
939```c 944```c
940bool pointing_device_task(void) { 945bool pointing_device_task(void) {
941 //...Custom pointing device task code 946 //...Custom pointing device task code
942 947
943 // handle automatic mouse layer (needs report_mouse_t as input) 948 // handle automatic mouse layer (needs report_mouse_t as input)
944 pointing_device_task_auto_mouse(local_mouse_report); 949 pointing_device_task_auto_mouse(local_mouse_report);
945 950
946 //...More custom pointing device task code 951 //...More custom pointing device task code
947 952
948 return pointing_device_send(); 953 return pointing_device_send();
949} 954}
950``` 955```
diff --git a/docs/features/repeat_key.md b/docs/features/repeat_key.md
index 7f2bdc44e6..543dfd1008 100644
--- a/docs/features/repeat_key.md
+++ b/docs/features/repeat_key.md
@@ -5,7 +5,7 @@ Key after tapping the <kbd>Z</kbd> key types another "`z`." This is useful for
5typing doubled letters, like the `z` in "`dazzle`": a double tap on <kbd>Z</kbd> 5typing doubled letters, like the `z` in "`dazzle`": a double tap on <kbd>Z</kbd>
6can instead be a roll from <kbd>Z</kbd> to <kbd>Repeat</kbd>, which is 6can instead be a roll from <kbd>Z</kbd> to <kbd>Repeat</kbd>, which is
7potentially faster and more comfortable. The Repeat Key is also useful for 7potentially faster and more comfortable. The Repeat Key is also useful for
8hotkeys, like repeating Ctrl + Shift + Right Arrow to select by word. 8hotkeys, like repeating Ctrl + Shift + Right Arrow to select by word.
9 9
10Repeat Key remembers mods that were active with the last key press. These mods 10Repeat Key remembers mods that were active with the last key press. These mods
11are combined with any additional mods while pressing the Repeat Key. If the last 11are combined with any additional mods while pressing the Repeat Key. If the last
@@ -49,10 +49,10 @@ reduce firmware size, Alternate Repeat may be disabled by adding in config.h:
49 49
50The following alternate keys are defined by default. See 50The following alternate keys are defined by default. See
51`get_alt_repeat_key_keycode_user()` below for how to change or add to these 51`get_alt_repeat_key_keycode_user()` below for how to change or add to these
52definitions. Where it makes sense, these definitions also include combinations 52definitions. Where it makes sense, these definitions also include combinations
53with mods, like Ctrl + Left &harr; Ctrl + Right Arrow. 53with mods, like Ctrl + Left &harr; Ctrl + Right Arrow.
54 54
55**Navigation** 55**Navigation**
56 56
57|Keycodes |Description | 57|Keycodes |Description |
58|-----------------------------------|-----------------------------------| 58|-----------------------------------|-----------------------------------|
@@ -65,7 +65,7 @@ with mods, like Ctrl + Left &harr; Ctrl + Right Arrow.
65|`MS_WHLL` &harr; `MS_WHLR` | Mouse Wheel Left &harr; Right | 65|`MS_WHLL` &harr; `MS_WHLR` | Mouse Wheel Left &harr; Right |
66|`MS_WHLU` &harr; `MS_WHLD` | Mouse Wheel Up &harr; Down | 66|`MS_WHLU` &harr; `MS_WHLD` | Mouse Wheel Up &harr; Down |
67 67
68**Misc** 68**Misc**
69 69
70|Keycodes |Description | 70|Keycodes |Description |
71|-----------------------------------|-----------------------------------| 71|-----------------------------------|-----------------------------------|
@@ -73,7 +73,7 @@ with mods, like Ctrl + Left &harr; Ctrl + Right Arrow.
73|`KC_LBRC` &harr; `KC_RBRC` | `[` &harr; `]` | 73|`KC_LBRC` &harr; `KC_RBRC` | `[` &harr; `]` |
74|`KC_LCBR` &harr; `KC_RCBR` | `{` &harr; `}` | 74|`KC_LCBR` &harr; `KC_RCBR` | `{` &harr; `}` |
75 75
76**Media** 76**Media**
77 77
78|Keycodes |Description | 78|Keycodes |Description |
79|-----------------------------------|-----------------------------------| 79|-----------------------------------|-----------------------------------|
@@ -176,9 +176,9 @@ macro](../feature_macros). This way macros can be used without having to
176dedicate keys to them. The following defines a couple shortcuts. 176dedicate keys to them. The following defines a couple shortcuts.
177 177
178* Typing <kbd>K</kbd>, <kbd>Alt Repeat</kbd> produces "`keyboard`," with the 178* Typing <kbd>K</kbd>, <kbd>Alt Repeat</kbd> produces "`keyboard`," with the
179 initial "`k`" typed as usual and the "`eybord`" produced by the macro. 179 initial "`k`" typed as usual and the "`eybord`" produced by the macro.
180* Typing <kbd>.</kbd>, <kbd>Alt Repeat</kbd> produces "`../`," handy for "up 180* Typing <kbd>.</kbd>, <kbd>Alt Repeat</kbd> produces "`../`," handy for "up
181 directory" on the shell. Similary, <kbd>.</kbd> types the initial "`.`" and 181 directory" on the shell. Similarly, <kbd>.</kbd> types the initial "`.`" and
182 "`./`" is produced by the macro. 182 "`./`" is produced by the macro.
183 183
184```c 184```c
@@ -290,7 +290,7 @@ By default, pressing the Repeat Key will simply behave as if the last key
290were pressed again. This also works with macro keys with custom handlers, 290were pressed again. This also works with macro keys with custom handlers,
291invoking the macro again. In case fine-tuning is needed for sensible repetition, 291invoking the macro again. In case fine-tuning is needed for sensible repetition,
292you can handle how a key is repeated with `get_repeat_key_count()` within 292you can handle how a key is repeated with `get_repeat_key_count()` within
293`process_record_user()`. 293`process_record_user()`.
294 294
295The `get_repeat_key_count()` function returns a signed count of times the key 295The `get_repeat_key_count()` function returns a signed count of times the key
296has been repeated or alternate repeated. When a key is pressed as usual, 296has been repeated or alternate repeated. When a key is pressed as usual,
@@ -306,16 +306,16 @@ bool process_record_user(uint16_t keycode, keyrecord_t* record) {
306 if (get_repeat_key_count() > 0) { 306 if (get_repeat_key_count() > 0) {
307 // MY_MACRO is being repeated! 307 // MY_MACRO is being repeated!
308 if (record->event.pressed) { 308 if (record->event.pressed) {
309 SEND_STRING("repeat!"); 309 SEND_STRING("repeat!");
310 } 310 }
311 } else { 311 } else {
312 // MY_MACRO is being used normally. 312 // MY_MACRO is being used normally.
313 if (record->event.pressed) { 313 if (record->event.pressed) {
314 SEND_STRING("macro"); 314 SEND_STRING("macro");
315 } 315 }
316 } 316 }
317 return false; 317 return false;
318 318
319 // Other macros... 319 // Other macros...
320 } 320 }
321 return true; 321 return true;
@@ -347,19 +347,19 @@ bool process_record_user(uint16_t keycode, keyrecord_t* record) {
347 case MY_MACRO: 347 case MY_MACRO:
348 if (get_repeat_key_count() > 0) { // Repeating. 348 if (get_repeat_key_count() > 0) { // Repeating.
349 if (record->event.pressed) { 349 if (record->event.pressed) {
350 SEND_STRING("repeat!"); 350 SEND_STRING("repeat!");
351 } 351 }
352 } else if (get_repeat_key_count() < 0) { // Alternate repeating. 352 } else if (get_repeat_key_count() < 0) { // Alternate repeating.
353 if (record->event.pressed) { 353 if (record->event.pressed) {
354 SEND_STRING("alt repeat!"); 354 SEND_STRING("alt repeat!");
355 } 355 }
356 } else { // Used normally. 356 } else { // Used normally.
357 if (record->event.pressed) { 357 if (record->event.pressed) {
358 SEND_STRING("macro"); 358 SEND_STRING("macro");
359 } 359 }
360 } 360 }
361 return false; 361 return false;
362 362
363 // Other macros... 363 // Other macros...
364 } 364 }
365 return true; 365 return true;
@@ -377,7 +377,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t* record) {
377| `set_last_mods(mods)` | Set the mods to apply when repeating. | 377| `set_last_mods(mods)` | Set the mods to apply when repeating. |
378| `get_repeat_key_count()` | Signed count of times the key has been repeated or alternate repeated. | 378| `get_repeat_key_count()` | Signed count of times the key has been repeated or alternate repeated. |
379| `get_alt_repeat_key_keycode()` | Keycode to be used for alternate repeating. | 379| `get_alt_repeat_key_keycode()` | Keycode to be used for alternate repeating. |
380 380
381 381
382## Additional "Alternate" keys 382## Additional "Alternate" keys
383 383
@@ -437,7 +437,7 @@ static void process_altrep3(uint16_t keycode, uint8_t mods) {
437 437
438bool process_record_user(uint16_t keycode, keyrecord_t* record) { 438bool process_record_user(uint16_t keycode, keyrecord_t* record) {
439 switch (keycode) { 439 switch (keycode) {
440 case ALTREP2: 440 case ALTREP2:
441 if (record->event.pressed) { 441 if (record->event.pressed) {
442 process_altrep2(get_last_keycode(), get_last_mods()); 442 process_altrep2(get_last_keycode(), get_last_mods());
443 } 443 }
diff --git a/docs/features/rgb_matrix.md b/docs/features/rgb_matrix.md
index b0110b436b..95ee4c4896 100644
--- a/docs/features/rgb_matrix.md
+++ b/docs/features/rgb_matrix.md
@@ -125,13 +125,13 @@ enum rgb_matrix_effects {
125 RGB_MATRIX_CYCLE_SPIRAL, // Full gradient spinning spiral around center of keyboard 125 RGB_MATRIX_CYCLE_SPIRAL, // Full gradient spinning spiral around center of keyboard
126 RGB_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard 126 RGB_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard
127 RGB_MATRIX_RAINBOW_BEACON, // Full tighter gradient spinning around center of keyboard 127 RGB_MATRIX_RAINBOW_BEACON, // Full tighter gradient spinning around center of keyboard
128 RGB_MATRIX_RAINBOW_PINWHEELS, // Full dual gradients spinning two halfs of keyboard 128 RGB_MATRIX_RAINBOW_PINWHEELS, // Full dual gradients spinning two halves of keyboard
129 RGB_MATRIX_FLOWER_BLOOMING, // Full tighter gradient of first half scrolling left to right and second half scrolling right to left 129 RGB_MATRIX_FLOWER_BLOOMING, // Full tighter gradient of first half scrolling left to right and second half scrolling right to left
130 RGB_MATRIX_RAINDROPS, // Randomly changes a single key's hue 130 RGB_MATRIX_RAINDROPS, // Randomly changes a single key's hue
131 RGB_MATRIX_JELLYBEAN_RAINDROPS, // Randomly changes a single key's hue and saturation 131 RGB_MATRIX_JELLYBEAN_RAINDROPS, // Randomly changes a single key's hue and saturation
132 RGB_MATRIX_HUE_BREATHING, // Hue shifts up a slight ammount at the same time, then shifts back 132 RGB_MATRIX_HUE_BREATHING, // Hue shifts up a slight amount at the same time, then shifts back
133 RGB_MATRIX_HUE_PENDULUM, // Hue shifts up a slight ammount in a wave to the right, then back to the left 133 RGB_MATRIX_HUE_PENDULUM, // Hue shifts up a slight amount in a wave to the right, then back to the left
134 RGB_MATRIX_HUE_WAVE, // Hue shifts up a slight ammount and then back down in a wave to the right 134 RGB_MATRIX_HUE_WAVE, // Hue shifts up a slight amount and then back down in a wave to the right
135 RGB_MATRIX_PIXEL_FRACTAL, // Single hue fractal filled keys pulsing horizontally out to edges 135 RGB_MATRIX_PIXEL_FRACTAL, // Single hue fractal filled keys pulsing horizontally out to edges
136 RGB_MATRIX_PIXEL_FLOW, // Pulsing RGB flow along LED wiring with random hues 136 RGB_MATRIX_PIXEL_FLOW, // Pulsing RGB flow along LED wiring with random hues
137 RGB_MATRIX_PIXEL_RAIN, // Randomly light keys with random hues 137 RGB_MATRIX_PIXEL_RAIN, // Randomly light keys with random hues
@@ -240,7 +240,7 @@ In order to change the delay of temperature decrease define `RGB_MATRIX_TYPING_H
240 240
241As heatmap uses the physical position of the leds set in the g_led_config, you may need to tweak the following options to get the best effect for your keyboard. Note the size of this grid is `224x64`. 241As heatmap uses the physical position of the leds set in the g_led_config, you may need to tweak the following options to get the best effect for your keyboard. Note the size of this grid is `224x64`.
242 242
243Limit the distance the effect spreads to surrounding keys. 243Limit the distance the effect spreads to surrounding keys.
244 244
245```c 245```c
246#define RGB_MATRIX_TYPING_HEATMAP_SPREAD 40 246#define RGB_MATRIX_TYPING_HEATMAP_SPREAD 40
@@ -406,8 +406,8 @@ const char* effect_name = rgb_matrix_get_mode_name(rgb_matrix_get_mode());
406#define RGB_MATRIX_VAL_STEP 16 // The value by which to increment the brightness per adjustment action 406#define RGB_MATRIX_VAL_STEP 16 // The value by which to increment the brightness per adjustment action
407#define RGB_MATRIX_SPD_STEP 16 // The value by which to increment the animation speed per adjustment action 407#define RGB_MATRIX_SPD_STEP 16 // The value by which to increment the animation speed per adjustment action
408#define RGB_MATRIX_DEFAULT_FLAGS LED_FLAG_ALL // Sets the default LED flags, if none has been set 408#define RGB_MATRIX_DEFAULT_FLAGS LED_FLAG_ALL // Sets the default LED flags, if none has been set
409#define RGB_MATRIX_SPLIT { X, Y } // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right. 409#define RGB_MATRIX_SPLIT { X, Y } // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right.
410 // If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR 410 // If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR
411#define RGB_TRIGGER_ON_KEYDOWN // Triggers RGB keypress events on key down. This makes RGB control feel more responsive. This may cause RGB to not function properly on some boards 411#define RGB_TRIGGER_ON_KEYDOWN // Triggers RGB keypress events on key down. This makes RGB control feel more responsive. This may cause RGB to not function properly on some boards
412``` 412```
413 413
diff --git a/docs/features/space_cadet.md b/docs/features/space_cadet.md
index 0abdaebf33..66761f5a46 100644
--- a/docs/features/space_cadet.md
+++ b/docs/features/space_cadet.md
@@ -32,7 +32,7 @@ COMMAND_ENABLE = no
32 32
33## Configuration 33## Configuration
34 34
35By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifer` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `SC_LSPO` key with `KC_TRNS` as the `Tap Modifer`. 35By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifier` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `SC_LSPO` key with `KC_TRNS` as the `Tap Modifier`.
36 36
37|Define |Default |Description | 37|Define |Default |Description |
38|----------------|-------------------------------|---------------------------------------------------------------------------------| 38|----------------|-------------------------------|---------------------------------------------------------------------------------|
diff --git a/docs/features/split_keyboard.md b/docs/features/split_keyboard.md
index fbf5d3d3e2..4b299b14f8 100644
--- a/docs/features/split_keyboard.md
+++ b/docs/features/split_keyboard.md
@@ -1,12 +1,12 @@
1# Split Keyboard 1# Split Keyboard
2 2
3Many keyboards in the QMK Firmware repo are "split" keyboards. They use two controllers—one plugging into USB, and the second connected by a serial or an I<sup>2</sup>C connection over a TRRS or similar cable. 3Many keyboards in the QMK Firmware repo are "split" keyboards. They use two controllers—one plugging into USB, and the second connected by a serial or an I<sup>2</sup>C connection over a TRRS or similar cable.
4 4
5Split keyboards can have a lot of benefits, but there is some additional work needed to get them enabled. 5Split keyboards can have a lot of benefits, but there is some additional work needed to get them enabled.
6 6
7QMK Firmware has a generic implementation that is usable by any board, as well as numerous board specific implementations. 7QMK Firmware has a generic implementation that is usable by any board, as well as numerous board specific implementations.
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::: warning 11::: warning
12ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported. 12ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported.
@@ -29,33 +29,33 @@ Notes:
29 29
30## Hardware Configuration 30## Hardware Configuration
31 31
32This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves. 32This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves.
33 33
34### Required Hardware 34### Required Hardware
35 35
36Apart from diodes and key switches for the keyboard matrix in each half, you will need 2x TRRS sockets and 1x TRRS cable. 36Apart from diodes and key switches for the keyboard matrix in each half, you will need 2x TRRS sockets and 1x TRRS cable.
37 37
38Alternatively, you can use any sort of cable and socket that has at least 3 wires. 38Alternatively, you can use any sort of cable and socket that has at least 3 wires.
39 39
40If you want to use I<sup>2</sup>C to communicate between halves, you will need a cable with at least 4 wires and 2x 4.7kΩ pull-up resistors. 40If you want to use I<sup>2</sup>C to communicate between halves, you will need a cable with at least 4 wires and 2x 4.7kΩ pull-up resistors.
41 41
42#### Considerations 42#### Considerations
43 43
44The most commonly used connection is a TRRS cable and jacks. These provide 4 wires, making them very useful for split keyboards, and are easy to find. 44The most commonly used connection is a TRRS cable and jacks. These provide 4 wires, making them very useful for split keyboards, and are easy to find.
45 45
46However, since one of the wires carries VCC, this means that the boards are not hot pluggable. You should always disconnect the board from USB before unplugging and plugging in TRRS cables, or you can short the controller, or worse. 46However, since one of the wires carries VCC, this means that the boards are not hot pluggable. You should always disconnect the board from USB before unplugging and plugging in TRRS cables, or you can short the controller, or worse.
47 47
48Another option is to use phone cables (as in, old school RJ-11/RJ-14 cables). Make sure that you use one that actually supports 4 wires/lanes. 48Another option is to use phone cables (as in, old school RJ-11/RJ-14 cables). Make sure that you use one that actually supports 4 wires/lanes.
49 49
50However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers. 50However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers.
51 51
52::: warning 52::: warning
53Using USB cables for communication between the controllers works just fine, but the connector could be mistaken for a normal USB connection and potentially short out the keyboard, depending on how it's wired. For this reason, they are not recommended for connecting split keyboards. 53Using USB cables for communication between the controllers works just fine, but the connector could be mistaken for a normal USB connection and potentially short out the keyboard, depending on how it's wired. For this reason, they are not recommended for connecting split keyboards.
54::: 54:::
55 55
56### Serial Wiring 56### Serial Wiring
57 57
58The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0/D1/D2/D3 (aka PD0/PD1/PD2/PD3) between the two Pro Micros. 58The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0/D1/D2/D3 (aka PD0/PD1/PD2/PD3) between the two Pro Micros.
59 59
60::: tip 60::: tip
61Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below. 61Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below.
@@ -66,7 +66,7 @@ Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below.
66 66
67### I<sup>2</sup>C Wiring 67### I<sup>2</sup>C Wiring
68 68
69The 4 wires of the TRRS cable need to connect GND, VCC, and SCL and SDA (aka PD0/pin 3 and PD1/pin 2, respectively) between the two Pro Micros. 69The 4 wires of the TRRS cable need to connect GND, VCC, and SCL and SDA (aka PD0/pin 3 and PD1/pin 2, respectively) between the two Pro Micros.
70 70
71The pull-up resistors may be placed on either half. If you wish to use the halves independently, it is also possible to use 4 resistors and have the pull-ups in both halves. 71The pull-up resistors may be placed on either half. If you wish to use the halves independently, it is also possible to use 4 resistors and have the pull-ups in both halves.
72Note that the total resistance for the connected system should be within spec at 2.2k-10kOhm, with an 'ideal' at 4.7kOhm, regardless of the placement and number. 72Note that the total resistance for the connected system should be within spec at 2.2k-10kOhm, with an 'ideal' at 4.7kOhm, regardless of the placement and number.
@@ -75,13 +75,13 @@ Note that the total resistance for the connected system should be within spec at
75 75
76## Firmware Configuration 76## Firmware Configuration
77 77
78To enable the split keyboard feature, add the following to your `rules.mk`: 78To enable the split keyboard feature, add the following to your `rules.mk`:
79 79
80```make 80```make
81SPLIT_KEYBOARD = yes 81SPLIT_KEYBOARD = yes
82``` 82```
83 83
84If you're using a custom transport (communication method), then you will also need to add: 84If you're using a custom transport (communication method), then you will also need to add:
85 85
86```make 86```make
87SPLIT_TRANSPORT = custom 87SPLIT_TRANSPORT = custom
@@ -109,7 +109,7 @@ You can configure the firmware to read a pin on the controller to determine hand
109#define SPLIT_HAND_PIN B7 109#define SPLIT_HAND_PIN B7
110``` 110```
111 111
112This 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. 112This 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.
113 113
114This behaviour can be flipped by adding this to you `config.h` file: 114This behaviour can be flipped by adding this to you `config.h` file:
115 115
@@ -141,10 +141,10 @@ While `MATRIX_MASKED` isn't necessary to use `SPLIT_HAND_MATRIX_GRID` successful
141 141
142#### Handedness by EEPROM 142#### Handedness by EEPROM
143 143
144This method sets the keyboard's handedness by setting a flag in the persistent storage (`EEPROM`). This is checked when the controller first starts up, and determines what half the keyboard is, and how to orient the keyboard layout. 144This method sets the keyboard's handedness by setting a flag in the persistent storage (`EEPROM`). This is checked when the controller first starts up, and determines what half the keyboard is, and how to orient the keyboard layout.
145 145
146 146
147To enable this method, add the following to your `config.h` file: 147To enable this method, add the following to your `config.h` file:
148 148
149```c 149```c
150#define EE_HANDS 150#define EE_HANDS
@@ -176,7 +176,7 @@ Some controllers (e.g. Blackpill with DFU compatible bootloader) will need to be
176[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases/) can also be used to flash EEPROM handedness files. Place the controller in bootloader mode and select menu option Tools -> EEPROM -> Set Left/Right Hand 176[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases/) can also be used to flash EEPROM handedness files. Place the controller in bootloader mode and select menu option Tools -> EEPROM -> Set Left/Right Hand
177::: 177:::
178 178
179This setting is not changed when re-initializing the EEPROM using the `EE_CLR` key, or using the `eeconfig_init()` function. However, if you reset the EEPROM outside of the firmware's built in options (such as flashing a file that overwrites the `EEPROM`, like how the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases/)'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files. 179This setting is not changed when re-initializing the EEPROM using the `EE_CLR` key, or using the `eeconfig_init()` function. However, if you reset the EEPROM outside of the firmware's built in options (such as flashing a file that overwrites the `EEPROM`, like how the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases/)'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files.
180 180
181You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common). 181You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common).
182 182
@@ -208,13 +208,13 @@ Because not every split keyboard is identical, there are a number of additional
208#define USE_I2C 208#define USE_I2C
209``` 209```
210 210
211This configures the use of I<sup>2</sup>C support for split keyboard transport (AVR only). 211This configures the use of I<sup>2</sup>C support for split keyboard transport (AVR only).
212 212
213```c 213```c
214#define SOFT_SERIAL_PIN D0 214#define SOFT_SERIAL_PIN D0
215``` 215```
216 216
217This sets the pin to be used for serial communication. If you're not using serial, you shouldn't need to define this. 217This sets the pin to be used for serial communication. If you're not using serial, you shouldn't need to define this.
218 218
219However, if you are using serial and I<sup>2</sup>C on the board, you will need to set this, and to something other than D0 and D1 (as these are used for I<sup>2</sup>C communication). 219However, if you are using serial and I<sup>2</sup>C on the board, you will need to set this, and to something other than D0 and D1 (as these are used for I<sup>2</sup>C communication).
220 220
@@ -235,7 +235,7 @@ If you're having issues with serial communication, you can change this value, as
235#define FORCED_SYNC_THROTTLE_MS 100 235#define FORCED_SYNC_THROTTLE_MS 100
236``` 236```
237 237
238This 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. 238This 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.
239 239
240```c 240```c
241#define SPLIT_MAX_CONNECTION_ERRORS 10 241#define SPLIT_MAX_CONNECTION_ERRORS 10
@@ -249,7 +249,7 @@ Set to 0 to disable the disconnection check altogether.
249``` 249```
250How long (in milliseconds) the master part should block all connection attempts to the slave after the communication has been flagged as disconnected (see `SPLIT_MAX_CONNECTION_ERRORS` above). 250How long (in milliseconds) the master part should block all connection attempts to the slave after the communication has been flagged as disconnected (see `SPLIT_MAX_CONNECTION_ERRORS` above).
251 251
252One communication attempt will be allowed everytime this amount of time has passed since the last attempt. If that attempt succeeds, the communication is seen as working again. 252One communication attempt will be allowed every time this amount of time has passed since the last attempt. If that attempt succeeds, the communication is seen as working again.
253 253
254Set to 0 to disable this throttling of communications while disconnected. This can save you a couple of bytes of firmware size. 254Set to 0 to disable this throttling of communications while disconnected. This can save you a couple of bytes of firmware size.
255 255
@@ -280,7 +280,7 @@ This enables syncing of the Host LED status (caps lock, num lock, etc) between b
280#define SPLIT_MODS_ENABLE 280#define SPLIT_MODS_ENABLE
281``` 281```
282 282
283This enables transmitting modifier state (normal, weak, oneshot and oneshot locked) 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). 283This enables transmitting modifier state (normal, weak, oneshot and oneshot locked) to the non primary side of the split keyboard. The purpose of this feature is to support cosmetic use of modifier state (e.g. displaying status on an OLED screen).
284 284
285```c 285```c
286#define SPLIT_WPM_ENABLE 286#define SPLIT_WPM_ENABLE
@@ -304,7 +304,7 @@ This enables transmitting the current ST7565 on/off status to the slave side of
304#define SPLIT_POINTING_ENABLE 304#define SPLIT_POINTING_ENABLE
305``` 305```
306 306
307This enables transmitting the pointing device status to the master side of the split keyboard. The purpose of this feature is to enable use pointing devices on the slave side. 307This enables transmitting the pointing device status to the master side of the split keyboard. The purpose of this feature is to enable use pointing devices on the slave side.
308 308
309::: warning 309::: warning
310There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](pointing_device#split-keyboard-configuration). 310There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](pointing_device#split-keyboard-configuration).
@@ -401,7 +401,7 @@ By default, the inbound and outbound data is limited to a maximum of 32 bytes ea
401 401
402### Hardware Configuration Options 402### Hardware Configuration Options
403 403
404There are some settings that you may need to configure, based on how the hardware is set up. 404There are some settings that you may need to configure, based on how the hardware is set up.
405 405
406```c 406```c
407#define MATRIX_ROW_PINS_RIGHT { <row pins> } 407#define MATRIX_ROW_PINS_RIGHT { <row pins> }
@@ -433,7 +433,7 @@ This option enables synchronization of the RGB Light modes between the controlle
433#define RGBLED_SPLIT { 6, 6 } 433#define RGBLED_SPLIT { 6, 6 }
434``` 434```
435 435
436This sets how many LEDs are directly connected to each controller. The first number is the left side, and the second number is the right side. 436This sets how many LEDs are directly connected to each controller. The first number is the left side, and the second number is the right side.
437 437
438::: tip 438::: tip
439This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable it, if it's not. 439This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable it, if it's not.
@@ -479,7 +479,7 @@ This set the maximum slave timeout when waiting for communication from master wh
479 479
480Master/slave delegation is made either by detecting voltage on VBUS connection or waiting for USB communication (`SPLIT_USB_DETECT`). Pro Micro boards can use VBUS detection out of the box and be used with or without `SPLIT_USB_DETECT`. 480Master/slave delegation is made either by detecting voltage on VBUS connection or waiting for USB communication (`SPLIT_USB_DETECT`). Pro Micro boards can use VBUS detection out of the box and be used with or without `SPLIT_USB_DETECT`.
481 481
482Many ARM boards, but not all, do not support VBUS detection. Because it is common that ARM boards lack VBUS detection, `SPLIT_USB_DETECT` is automatically defined on ARM targets (technically when ChibiOS is targetted). 482Many ARM boards, but not all, do not support VBUS detection. Because it is common that ARM boards lack VBUS detection, `SPLIT_USB_DETECT` is automatically defined on ARM targets (technically when ChibiOS is targeted).
483 483
484### Teensy boards 484### Teensy boards
485 485
@@ -501,7 +501,7 @@ You may need to use the 5V pad from the regulator block above as the pads were t
501 501
502## Additional Resources 502## Additional Resources
503 503
504Nicinabox has a [very nice and detailed guide](https://github.com/nicinabox/lets-split-guide) for the Let's Split keyboard, that covers most everything you need to know, including troubleshooting information. 504Nicinabox has a [very nice and detailed guide](https://github.com/nicinabox/lets-split-guide) for the Let's Split keyboard, that covers most everything you need to know, including troubleshooting information.
505 505
506However, the RGB Light section is out of date, as it was written long before the RGB Split code was added to QMK Firmware. Instead, wire each strip up directly to the controller. 506However, the RGB Light section is out of date, as it was written long before the RGB Split code was added to QMK Firmware. Instead, wire each strip up directly to the controller.
507 507
diff --git a/docs/features/st7565.md b/docs/features/st7565.md
index de3e44d8e9..09a1efce30 100644
--- a/docs/features/st7565.md
+++ b/docs/features/st7565.md
@@ -182,12 +182,12 @@ void st7565_render(void);
182void st7565_set_cursor(uint8_t col, uint8_t line); 182void st7565_set_cursor(uint8_t col, uint8_t line);
183 183
184// Advances the cursor to the next page, writing ' ' if true 184// Advances the cursor to the next page, writing ' ' if true
185// Wraps to the begining when out of bounds 185// Wraps to the beginning when out of bounds
186void st7565_advance_page(bool clearPageRemainder); 186void st7565_advance_page(bool clearPageRemainder);
187 187
188// Moves the cursor forward 1 character length 188// Moves the cursor forward 1 character length
189// Advance page if there is not enough room for the next character 189// Advance page if there is not enough room for the next character
190// Wraps to the begining when out of bounds 190// Wraps to the beginning when out of bounds
191void st7565_advance_char(void); 191void st7565_advance_char(void);
192 192
193// Writes a single character to the buffer at current cursor position 193// Writes a single character to the buffer at current cursor position
diff --git a/docs/features/stenography.md b/docs/features/stenography.md
index 4176344b5a..b253890e13 100644
--- a/docs/features/stenography.md
+++ b/docs/features/stenography.md
@@ -102,7 +102,7 @@ STENO_ENABLE = yes
102STENO_PROTOCOL = all 102STENO_PROTOCOL = all
103``` 103```
104 104
105If you want to switch protocols programatically, as part of a custom macro for example, don't use `tap_code(QK_STENO_*)`, as `tap_code` only supports [basic keycodes](../keycodes_basic). Instead, you should use `steno_set_mode(STENO_MODE_*)`, whose valid arguments are `STENO_MODE_BOLT` and `STENO_MODE_GEMINI`. 105If you want to switch protocols programmatically, as part of a custom macro for example, don't use `tap_code(QK_STENO_*)`, as `tap_code` only supports [basic keycodes](../keycodes_basic). Instead, you should use `steno_set_mode(STENO_MODE_*)`, whose valid arguments are `STENO_MODE_BOLT` and `STENO_MODE_GEMINI`.
106 106
107The default protocol is Gemini PR but the last protocol used is stored in non-volatile memory so QMK will remember your choice between reboots of your keyboard &mdash; assuming that your keyboard features (emulated) EEPROM. 107The default protocol is Gemini PR but the last protocol used is stored in non-volatile memory so QMK will remember your choice between reboots of your keyboard &mdash; assuming that your keyboard features (emulated) EEPROM.
108 108
diff --git a/docs/hand_wire.md b/docs/hand_wire.md
index be21cf2cc4..492ca384b1 100644
--- a/docs/hand_wire.md
+++ b/docs/hand_wire.md
@@ -162,7 +162,7 @@ The pins you'll absolutely have to avoid, as with any controller, are: GND, VCC,
162 162
163Cut wires to the length of the distance from the a point on each column/row to the controller. You can solder anywhere along the row, as long as it's after the diode - soldering before the diode (on the keyswitch side) will cause that row not to work. 163Cut wires to the length of the distance from the a point on each column/row to the controller. You can solder anywhere along the row, as long as it's after the diode - soldering before the diode (on the keyswitch side) will cause that row not to work.
164 164
165Ribbon cable can be used to keep this extra tidy. You may also want to consider routing the wires beneath the exisiting columns/rows. 165Ribbon cable can be used to keep this extra tidy. You may also want to consider routing the wires beneath the existing columns/rows.
166 166
167<img src="https://i.imgur.com/z2QlKfB.jpg" alt="Ribbon Cable" width="350"/> 167<img src="https://i.imgur.com/z2QlKfB.jpg" alt="Ribbon Cable" width="350"/>
168 168
@@ -188,7 +188,7 @@ qmk import-kbfirmware /path/to/export.json
188For example: 188For example:
189 189
190``` 190```
191$ qmk import-kbfirmware ~/Downloads/gh62.json 191$ qmk import-kbfirmware ~/Downloads/gh62.json
192Ψ Importing gh62.json. 192Ψ Importing gh62.json.
193 193
194⚠ Support here is basic - Consider using 'qmk new-keyboard' instead 194⚠ Support here is basic - Consider using 'qmk new-keyboard' instead
@@ -227,16 +227,16 @@ If you've done all of these things, keep in mind that sometimes you might have h
227 227
228## Finishing up 228## Finishing up
229 229
230Once you have confirmed that the keyboard is working, if you have used a seperate (non handwire specific) controller you will want to secure it in place. This can be done in many different ways e.g. hot glue, double sided sticky tape, 3D printed caddy, electrical tape. 230Once you have confirmed that the keyboard is working, if you have used a separate (non handwire specific) controller you will want to secure it in place. This can be done in many different ways e.g. hot glue, double sided sticky tape, 3D printed caddy, electrical tape.
231 231
232If you found this fullfilling you could experiment by adding additional features such as [in switch LEDs](https://geekhack.org/index.php?topic=94258.0), [in switch RGB](https://www.reddit.com/r/MechanicalKeyboards/comments/5s1l5u/photoskeyboard_science_i_made_a_handwired_rgb/), [RGB underglow](https://medium.com/@DavidNZ/hand-wired-custom-keyboard-cdd14429c7b3#.7a1ovebsk) or even an [OLED display!](https://www.reddit.com/r/olkb/comments/5zy7og/adding_ssd1306_oled_display_to_your_build/) 232If you found this fulfilling you could experiment by adding additional features such as [in switch LEDs](https://geekhack.org/index.php?topic=94258.0), [in switch RGB](https://www.reddit.com/r/MechanicalKeyboards/comments/5s1l5u/photoskeyboard_science_i_made_a_handwired_rgb/), [RGB underglow](https://medium.com/@DavidNZ/hand-wired-custom-keyboard-cdd14429c7b3#.7a1ovebsk) or even an [OLED display!](https://www.reddit.com/r/olkb/comments/5zy7og/adding_ssd1306_oled_display_to_your_build/)
233 233
234There are a lot of possibilities inside the firmware - explore [the documentation](/) for a full feature list, and dive into the different keyboards to see how people use all of them. You can always stop by [the OLKB subreddit](https://reddit.com/r/olkb) or [QMK Discord](https://discord.gg/qmk) for help! 234There are a lot of possibilities inside the firmware - explore [the documentation](/) for a full feature list, and dive into the different keyboards to see how people use all of them. You can always stop by [the OLKB subreddit](https://reddit.com/r/olkb) or [QMK Discord](https://discord.gg/qmk) for help!
235 235
236## Links to Other Guides 236## Links to Other Guides
237 237
238- [matt3o's step by step guide (BrownFox build)](https://deskthority.net/viewtopic.php?f=7&t=6050) also his [website](https://matt3o.com/hand-wiring-a-custom-keyboard/) and [video guide](https://www.youtube.com/watch?v=LVzpsjFWPP4) 238- [matt3o's step by step guide (BrownFox build)](https://deskthority.net/viewtopic.php?f=7&t=6050) also his [website](https://matt3o.com/hand-wiring-a-custom-keyboard/) and [video guide](https://www.youtube.com/watch?v=LVzpsjFWPP4)
239- [Cribbit's "Modern hand wiring guide - stronger, cleaner, easier"](https://geekhack.org/index.php?topic=87689.0) 239- [Cribbit's "Modern hand wiring guide - stronger, cleaner, easier"](https://geekhack.org/index.php?topic=87689.0)
240- [Sasha Solomon's "Building my first Keyboard"](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) 240- [Sasha Solomon's "Building my first Keyboard"](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f)
241- [RoastPotatoes' "How to hand wire a Planck"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/) 241- [RoastPotatoes' "How to hand wire a Planck"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/)
242- [Masterzen's "Handwired keyboard build log"](https://www.masterzen.fr/2018/12/16/handwired-keyboard-build-log-part-1/) 242- [Masterzen's "Handwired keyboard build log"](https://www.masterzen.fr/2018/12/16/handwired-keyboard-build-log-part-1/)
diff --git a/docs/hardware_drivers.md b/docs/hardware_drivers.md
index 694d46971a..40a25d9fa7 100644
--- a/docs/hardware_drivers.md
+++ b/docs/hardware_drivers.md
@@ -24,7 +24,7 @@ Support for WS2811/WS2812{a,b,c} LED's. For more information see the [RGB Light]
24 24
25## IS31FL3731 25## IS31FL3731
26 26
27Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to individually address LEDs using I2C. This allows up to 144 same color LEDs or 32 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](features/rgb_matrix) page. 27Support for up to 2 drivers. Each driver implements 2 charlieplex matrices to individually address LEDs using I2C. This allows up to 144 same color LEDs or 32 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](features/rgb_matrix) page.
28 28
29## IS31FL3733 29## IS31FL3733
30 30
diff --git a/docs/quantum_painter_lvgl.md b/docs/quantum_painter_lvgl.md
index 40b3c3b2f1..0ff0e321ec 100644
--- a/docs/quantum_painter_lvgl.md
+++ b/docs/quantum_painter_lvgl.md
@@ -5,7 +5,7 @@ LVGL (Light and Versatile Graphics Library) is an open-source graphics library p
5LVGL integrates with [Quantum Painter's](quantum_painter) API and drivers to render to the display, the hardware supported by Quantum Painter is also supported by LVGL. 5LVGL integrates with [Quantum Painter's](quantum_painter) API and drivers to render to the display, the hardware supported by Quantum Painter is also supported by LVGL.
6 6
7::: tip 7::: tip
8Keep in mind that enabling the LVGL integration has a big impact in firmware size, it is recommeded to use a supported MCU with >256 kB of flash space. 8Keep in mind that enabling the LVGL integration has a big impact in firmware size, it is recommended to use a supported MCU with >256 kB of flash space.
9::: 9:::
10 10
11To learn more about LVGL and how to use it please take a look at their [official documentation](https://docs.lvgl.io/8.2/intro/) 11To learn more about LVGL and how to use it please take a look at their [official documentation](https://docs.lvgl.io/8.2/intro/)
@@ -35,7 +35,7 @@ static painter_device_t display;
35void keyboard_post_init_kb(void) { 35void keyboard_post_init_kb(void) {
36 display = qp_make_.......; // Create the display 36 display = qp_make_.......; // Create the display
37 qp_init(display, QP_ROTATION_0); // Initialise the display 37 qp_init(display, QP_ROTATION_0); // Initialise the display
38 38
39 if (qp_lvgl_attach(display)) { // Attach LVGL to the display 39 if (qp_lvgl_attach(display)) { // Attach LVGL to the display
40 ...Your code to draw // Run LVGL specific code to draw 40 ...Your code to draw // Run LVGL specific code to draw
41 } 41 }
diff --git a/docs/squeezing_avr.md b/docs/squeezing_avr.md
index c3f3d3c6e1..458b442d59 100644
--- a/docs/squeezing_avr.md
+++ b/docs/squeezing_avr.md
@@ -5,14 +5,14 @@ AVR is severely resource-constrained, and as QMK continues to grow, it is approa
5However, if you need to reduce the compiled size of your firmware to fit the controller's limited flash size, there are a number of options to do so. 5However, if you need to reduce the compiled size of your firmware to fit the controller's limited flash size, there are a number of options to do so.
6 6
7## `rules.mk` Settings 7## `rules.mk` Settings
8First and foremost is enabling link time optimization. To do so, add this to your rules.mk: 8First and foremost is enabling link time optimization. To do so, add this to your rules.mk:
9```make 9```make
10LTO_ENABLE = yes 10LTO_ENABLE = yes
11``` 11```
12This will cause the final step to take longer, but should get you a smaller compiled size. This also disables Action Functions, and Action Macros, both of which are deprecated. 12This will cause the final step to take longer, but should get you a smaller compiled size. This also disables Action Functions, and Action Macros, both of which are deprecated.
13This will get you the most savings, in most situations. 13This will get you the most savings, in most situations.
14 14
15From there, disabling extraneous systems will help -- e.g.: 15From there, disabling extraneous systems will help -- e.g.:
16```make 16```make
17CONSOLE_ENABLE = no 17CONSOLE_ENABLE = no
18COMMAND_ENABLE = no 18COMMAND_ENABLE = no
@@ -21,10 +21,10 @@ EXTRAKEY_ENABLE = no
21``` 21```
22This disables some of the functionality that you may not need. But note that extrakeys disables stuff like the media keys and system volume control. 22This disables some of the functionality that you may not need. But note that extrakeys disables stuff like the media keys and system volume control.
23 23
24If that isn't enough to get your firmware down to size, then there are some additional features that you can disable: 24If that isn't enough to get your firmware down to size, then there are some additional features that you can disable:
25```make 25```make
26SPACE_CADET_ENABLE = no 26SPACE_CADET_ENABLE = no
27GRAVE_ESC_ENABLE = no 27GRAVE_ESC_ENABLE = no
28MAGIC_ENABLE = no 28MAGIC_ENABLE = no
29``` 29```
30These features are enabled by default, but they may not be needed. Double check to make sure. The [Magic Keycodes](keycodes_magic) are the largest and control things like NKRO toggling, GUI and ALT/CTRL swapping, etc. Disabling them will disable those functions. See [Magic Functions](#magic-functions) for disabling related functions. 30These features are enabled by default, but they may not be needed. Double check to make sure. The [Magic Keycodes](keycodes_magic) are the largest and control things like NKRO toggling, GUI and ALT/CTRL swapping, etc. Disabling them will disable those functions. See [Magic Functions](#magic-functions) for disabling related functions.
@@ -51,7 +51,7 @@ Starting with Lock Key support. If you have a Cherry MX Lock switch (lucky you!)
51#undef LOCKING_SUPPORT_ENABLE 51#undef LOCKING_SUPPORT_ENABLE
52#undef LOCKING_RESYNC_ENABLE 52#undef LOCKING_RESYNC_ENABLE
53``` 53```
54Oneshots. If you're not using these, you can disable the feature by adding this to your `config.h`: 54Oneshots. If you're not using these, you can disable the feature by adding this to your `config.h`:
55```c 55```c
56#define NO_ACTION_ONESHOT 56#define NO_ACTION_ONESHOT
57``` 57```
@@ -61,7 +61,7 @@ The same with tapping keys (mod tap, layer tap, etc)
61``` 61```
62## Audio Settings 62## Audio Settings
63 63
64If you're using the Audio feature, by default that includes the music mode feature. This tranlates matrix positions into notes. It's neat for sure, but most likely, you're not using it. You can disable it by adding this to your `config.h`: 64If you're using the Audio feature, by default that includes the music mode feature. This translates matrix positions into notes. It's neat for sure, but most likely, you're not using it. You can disable it by adding this to your `config.h`:
65```c 65```c
66#define NO_MUSIC_MODE 66#define NO_MUSIC_MODE
67``` 67```
@@ -124,7 +124,7 @@ into this:
124 oled_write_P(PSTR("WPM: "), false); 124 oled_write_P(PSTR("WPM: "), false);
125 oled_write(get_u8_str(get_current_wpm(), ' '), false); 125 oled_write(get_u8_str(get_current_wpm(), ' '), false);
126``` 126```
127which outputs `WPM: 5`. Or this: 127which outputs `WPM: 5`. Or this:
128```c 128```c
129 // NEW CODE 129 // NEW CODE
130 oled_write_P(PSTR("WPM: "), false); 130 oled_write_P(PSTR("WPM: "), false);
diff --git a/docs/usb_nkro.txt b/docs/usb_nkro.txt
index d9f1d12292..5817291b6b 100644
--- a/docs/usb_nkro.txt
+++ b/docs/usb_nkro.txt
@@ -58,7 +58,7 @@ USB NKRO methods
58 58
59Report Format 59Report Format
60------------- 60-------------
61Other report formats than followings are possible, though these format are typical one. 61Other report formats than following are possible, though these format are typical one.
62 62
631. Standard 8bytes 631. Standard 8bytes
64 modifiers(bitmap) 1byte 64 modifiers(bitmap) 1byte