ahoneybun/qmk_firmware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge remote-tracking branch 'origin/develop' into xap

Browse source
This commit is contained in:
zvecr 2022-03-15 13:27:35 +00:00
commit b96b862ef9
389 changed files with 12110 additions and 1362 deletions
Download patch file Download diff file Expand all files Collapse all files

29
docs/feature_bootmagic.md
View file

@ -23,14 +23,35 @@ And to trigger the bootloader, you hold this key down when plugging the keyboard
## Split Keyboards
When handedness is predetermined via an option like `SPLIT_HAND_PIN`, you might need to configure a different key between halves. To do so, add these entries to your `config.h` file:
When [handedness](feature_split_keyboard.md#setting-handedness) is predetermined via options like `SPLIT_HAND_PIN` or `EE_HANDS`, you might need to configure a different key between halves. To identify the correct key for the right half, examine the split key matrix defined in the `<keyboard>.h` file, e.g.:
```c
#define LAYOUT_split_3x5_2( \
L01, L02, L03, L04, L05, R01, R02, R03, R04, R05, \
L06, L07, L08, L09, L10, R06, R07, R08, R09, R10, \
L11, L12, L13, L14, L15, R11, R12, R13, R14, R15, \
L16, L17, R16, R17 \
) \
{ \
{ L01, L02, L03, L04, L05 }, \
{ L06, L07, L08, L09, L10 }, \
{ L11, L12, L13, L14, L15 }, \
{ L16, L17, KC_NO, KC_NO, KC_NO }, \
{ R01, R02, R03, R04, R05 }, \
{ R06, R07, R08, R09, R10 }, \
{ R11, R12, R13, R14, R15 }, \
{ R16, R17, KC_NO, KC_NO, KC_NO } \
}
```
If 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 Lite trigger, add these entries to your `config.h` file:
```c
#define BOOTMAGIC_LITE_ROW_RIGHT 4
#define BOOTMAGIC_LITE_COLUMN_RIGHT 1
#define BOOTMAGIC_LITE_COLUMN_RIGHT 4
```
By default, these values are not set.
?> These values are not set by default.
## Advanced Bootmagic Lite
@ -51,7 +72,7 @@ void bootmagic_lite(void) {
}
```
You can additional feature here. For instance, resetting the EEPROM or requiring additional keys to be pressed to trigger Bootmagic Lite. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
You can define additional logic here. For instance, resetting the EEPROM or requiring additional keys to be pressed to trigger Bootmagic Lite. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
## Addenda

3
docs/feature_pointing_device.md
View file

@ -325,7 +325,8 @@ report_mouse_t pointing_device_task_user(report_mouse_t mouse_report) {
if (set_scrolling) {
mouse_report.h = mouse_report.x;
mouse_report.v = mouse_report.y;
mouse_report.x = mouse_report.y = 0
mouse_report.x = 0;
mouse_report.y = 0;
}
return mouse_report;
}

92
docs/isp_flashing_guide.md
View file

@ -4,7 +4,7 @@ In order to flash a microcontroller over USB, it needs something called a bootlo
However, it can sometimes happen that the bootloader becomes corrupted and needs reflashing, or you may want to change the bootloader to another one. It's not possible to do this with the existing bootloader, because, of course, it is already running, and cannot overwrite itself. Instead, you will need to ISP flash the microcontroller.
There are several different kinds of bootloaders available for AVR microcontrollers. Most STM32 ARM-based microcontrollers already have a USB-capable bootloader in ROM, so generally do not need to be ISP flashed.
There are several different kinds of bootloaders available for AVR microcontrollers. Most STM32 ARM-based microcontrollers already have a USB-capable bootloader in ROM, so generally do not need to be ISP flashed. The one current exception is the [STM32F103](#flashing-stm32duino-bootloader).
## Hardware
@ -260,3 +260,93 @@ For mass production purposes, it is possible to join the bootloader and QMK firm
4. Save it as a new file, for example `<keyboard>_<keymap>_production.hex`.
You can then ISP flash this combined firmware instead, which allows you to skip the extra step of flashing the QMK firmware over USB.
## Flashing STM32Duino Bootloader
As mentioned above, *most* supported STM32 devices already possess a USB DFU bootloader which cannot be overwritten, however the ROM bootloader in the STM32F103 used on the Bluepill is not USB capable. In this case an ST-Link V2 dongle is required to upload the STM32Duino bootloader to the device. These can be readily purchased for relatively cheap on eBay and other places.
This bootloader is a descendant of the Maple bootloader by Leaflabs, and is compatible with dfu-util.
### Software
To communicate with the ST-Link, you must install the following packages:
* **macOS:** `brew install stlink openocd`
* **Windows (MSYS2):** `pacman -S mingw-w64-x86_64-stlink mingw-w64-x86_64-openocd`
* **Linux:** will vary by distribution, but will likely be `stlink` and `openocd` through your particular package manager
Additionally, you may need to update the ST-Link's firmware with the [`STSW-LINK007`](https://www.st.com/en/development-tools/stsw-link007.html) application. Note you will be asked to provide your name and email address if you do not have an ST.com account (this does not create one).
Finally, the bootloader binary itself can be downloaded from [here](https://github.com/rogerclarkmelbourne/STM32duino-bootloader/blob/master/bootloader_only_binaries/generic_boot20_pc13.bin).
### Wiring
Connect the four-pin header on the end of the Bluepill to the matching pins on the ST-Link (the pinout will usually be printed on the side):
|ST-Link |Bluepill|
|-------------|--------|
|`GND` (6) |`GND` |
|`SWCLK` (2) |`DCLK` |
|`SWDIO` (4) |`DIO` |
|`3.3V` (8) |`3.3` |
### Flashing
Firstly, make sure both jumpers on the Bluepill are set to 0.
Check that the ST-Link can talk to the Bluepill by running `st-info --probe`:
```
Found 1 stlink programmers
version: V2J37S7
serial: 2C1219002B135937334D4E00
flash: 65536 (pagesize: 1024)
sram: 20480
chipid: 0x0410
descr: F1xx Medium-density
```
If the reported `chipid` is `0x0410`, everything is working. If it is `0x0000`, check your wiring, and try swapping the `SWDIO` and `SWCLK` pins, as some ST-Link dongles may have incorrect pinouts.
Next, run the following command:
```
st-flash --reset --format binary write <path-to-bootloader> 0x08000000
```
where `<path-to-bootloader>` is the path to the bootloader `.bin` file above. You can run this command from the directory you downloaded it to, so that you can simply pass in the filename.
If all goes well, you should get output similar to the following:
```
st-flash 1.7.0
2022-03-08T12:16:30 INFO common.c: F1xx Medium-density: 20 KiB SRAM, 64 KiB flash in at least 1 KiB pages.
file generic_boot20_pc13.bin md5 checksum: 333c30605e739ce9bedee5999fdaf81b, stlink checksum: 0x0008e534
2022-03-08T12:16:30 INFO common.c: Attempting to write 7172 (0x1c04) bytes to stm32 address: 134217728 (0x8000000)
2022-03-08T12:16:30 INFO common.c: Flash page at addr: 0x08000000 erased
2022-03-08T12:16:30 INFO common.c: Flash page at addr: 0x08000400 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08000800 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08000c00 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001000 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001400 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001800 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001c00 erased
2022-03-08T12:16:31 INFO common.c: Finished erasing 8 pages of 1024 (0x400) bytes
2022-03-08T12:16:31 INFO common.c: Starting Flash write for VL/F0/F3/F1_XL
2022-03-08T12:16:31 INFO flash_loader.c: Successfully loaded flash loader in sram
2022-03-08T12:16:31 INFO flash_loader.c: Clear DFSR
8/ 8 pages written
2022-03-08T12:16:31 INFO common.c: Starting verification of write complete
2022-03-08T12:16:31 INFO common.c: Flash written and verified! jolly good!
2022-03-08T12:16:31 WARN common.c: NRST is not connected
```
Otherwise, if you receive an `Unknown memory region` error, run the following command to unlock the STM32F103:
```
openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c "init; reset halt; stm32f1x unlock 0; reset halt; exit"
```
Then re-plug the ST-Link and try again.
After all of this, unplug the Bluepill from the ST-Link and connect it to USB. It should now be ready to flash using dfu-util, the QMK CLI or Toolbox.

115
docs/tap_hold.md
View file

@ -126,6 +126,61 @@ The code which decides between the tap and hold actions of dual-role keys suppor
Note that until the tap-or-hold decision completes (which happens when either the dual-role key is released, or the tapping term has expired, or the extra condition for the selected decision mode is satisfied), key events are delayed and not transmitted to the host immediately. The default mode gives the most delay (if the dual-role key is held down, this mode always waits for the whole tapping term), and the other modes may give less delay when other keys are pressed, because the hold action may be selected earlier.
### Default Mode
Example sequence 1 (the `L` key is also mapped to `KC_RGHT` on layer 2):
```
TAPPING_TERM
+---------------|--------------------+
| +-------------|-------+ |
| | LT(2, KC_A) | | |
| +-------------|-------+ |
| | +--------------+ |
| | | KC_L | |
| | +--------------+ |
+---------------|--------------------+
```
The above sequence would send a `KC_RGHT`, since `LT(2, KC_A)` is held longer than the `TAPPING_TERM`.
---
Example sequence 2 (the `L` key is also mapped to `KC_RGHT` on layer 2):
```
TAPPING_TERM
+-----------------------------|------+
| +---------------+ | |
| | LT(2, KC_A) | | |
| +---------------+ | |
| +--------------+ | |
| | KC_L | | |
| +--------------+ | |
+-----------------------------|------+
```
The above sequence will not send `KC_RGHT` but `KC_A` `KC_L` instead, since `LT(2, KC_A)` is not held longer than the `TAPPING_TERM`.
---
Example sequence 3 (Mod Tap):
```
TAPPING_TERM
+---------------------------|--------+
| +-------------+ | |
| | SFT_T(KC_A) | | |
| +-------------+ | |
| +--------------+ | |
| | KC_X | | |
| +--------------+ | |
+---------------------------|--------+
```
Based previous examples, you might have expected the output of the above sequence to be `KC_A` `KC_X`
since `SFT_T(KC_A)` is NOT held longer than the `TAPPING_TERM`.
However, the actual output would be capital `X` (`SHIFT` + `x`) due to reasons
explained under [Ignore Mod Tap Interrupt](#ignore-mod-tap-interrupt).
### Permissive Hold
The “permissive hold” mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`:
@ -145,6 +200,18 @@ An example of a sequence which is affected by the “permissive hold” mode:
- `KC_L` Up
- `LT(2, KC_A)` Up
```
TAPPING_TERM
+---------------------------|--------+
| +----------------------+ | |
| | LT(2, KC_A) | | |
| +----------------------+ | |
| +--------------+ | |
| | KC_L | | |
| +--------------+ | |
+---------------------------|--------+
```
Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `PERMISSIVE_HOLD` option enabled, the Layer Tap key is considered as a layer switch if another key is tapped, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2). We could describe this sequence as a “nested press” (the modified key's key down and key up events are “nested” between the dual-role key's key down and key up events).
However, this slightly different sequence will not be affected by the “permissive hold” mode:
@ -154,6 +221,18 @@ However, this slightly different sequence will not be affected by the “permiss
- `LT(2, KC_A)` Up
- `KC_L` Up
```
TAPPING_TERM
+---------------------------|--------+
| +-------------+ | |
| | LT(2, KC_A) | | |
| +-------------+ | |
| +--------------+ | |
| | KC_L | | |
| +--------------+ | |
+---------------------------|--------+
```
In the sequence above the dual-role key is released before the other key is released, and if that happens within the tapping term, the “permissive hold” mode will still choose the tap action for the dual-role key, and the sequence will be registered as `al` by the host. We could describe this as a “rolling press” (the two keys' key down and key up events behave as if you were rolling a ball across the two keys, first pressing each key down in sequence and then releasing them in the same order).
?> The `PERMISSIVE_HOLD` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers both the “nested press” and “rolling press” sequences like shown above as a modifier hold, not the tap action. If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `PERMISSIVE_HOLD` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host.
@ -198,6 +277,18 @@ An example of a sequence which is affected by the “hold on other key press”
- `LT(2, KC_A)` Up
- `KC_L` Up
```
TAPPING_TERM
+---------------------------|--------+
| +-------------+ | |
| | LT(2, KC_A) | | |
| +-------------+ | |
| +--------------+ | |
| | KC_L | | |
| +--------------+ | |
+---------------------------|--------+
```
Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `HOLD_ON_OTHER_KEY_PRESS` option enabled, the Layer Tap key is considered as a layer switch if another key is pressed, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2).
?> The `HOLD_ON_OTHER_KEY_PRESS` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers the “rolling press” sequence like shown above as a modifier hold, not the tap action. If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `HOLD_ON_OTHER_KEY_PRESS` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host.
@ -245,6 +336,18 @@ An example of a sequence which will be affected by the `IGNORE_MOD_TAP_INTERRUPT
- `SFT_T(KC_A)` Up
- `KC_X` Up
```
TAPPING_TERM
+---------------------------|--------+
| +-------------+ | |
| | SFT_T(KC_A) | | |
| +-------------+ | |
| +--------------+ | |
| | KC_X | | |
| +--------------+ | |
+---------------------------|--------+
```
Normally, this would send a capital `X` (`SHIFT`+`x`), even if the sequence is performed faster than the `TAPPING_TERM`. However, if the `IGNORE_MOD_TAP_INTERRUPT` option is enabled, the `SFT_T(KC_A)` key must be held longer than the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold will still output a capital `X` (`SHIFT`+`x`).
However, if the `HOLD_ON_OTHER_KEY_PRESS` option is enabled in addition to `IGNORE_MOD_TAP_INTERRUPT`, the above sequence will again send a capital `X` (`SHIFT`+`x`) even if performed faster that the `TAPPING_TERM`. The difference from the default configuration is that by default the host will receive the key events only after the `SFT_T(KC_A)` key is released, but with the `HOLD_ON_OTHER_KEY_PRESS` option the host will start receiving key events when the `KC_X` key is pressed.
@ -327,6 +430,18 @@ Holding and releasing a dual function key without pressing another key will resu
For instance, holding and releasing `LT(2, KC_SPC)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPC` instead.
```
TAPPING_TERM
+-----------------|------------------+
| +---------------|-------+ |
| | LT(2, KC_SPC) | | |
| +---------------|-------+ |
| | |
| | |
| | |
+-----------------|------------------+
```
For more granular control of this feature, you can add the following to your `config.h`:
```c