Merge branch 'main' into leader-key
This commit is contained in:
Nick Conway
commit
4b7c1e76dc
4 changed files with 58 additions and 15 deletions
|
|
@ -133,6 +133,23 @@ See the following example, which uses a hold-tap behavior definition, configured
|
|||
By default, `hold-trigger-key-positions` are evaluated upon the first _key press_ after
|
||||
the hold-tap. For homerow mods, this is not always ideal, because it prevents combining multiple modifiers unless they are included in `hold-trigger-key-positions`. To overwrite this behavior, one can set `hold-trigger-on-release`. If set to true, the evaluation of `hold-trigger-key-positions` gets delayed until _key release_. This allows combining multiple modifiers when the next key is _held_, while still deciding the hold-tap in favor of a tap when the next key is _tapped_.
|
||||
|
||||
#### Using different behavior types with hold-taps
|
||||
|
||||
You can create instances of hold-taps invoking most [behavior types](../features/keymaps.md#behaviors) for hold or tap actions, by referencing their node labels in the `bindings` value.
|
||||
The two parameters that are passed to the hold-tap in your keymap will be forwarded to the referred behaviors, first one to the hold behavior and second one to the tap.
|
||||
|
||||
If you use behaviors that accept no parameters such as [mod-morphs](mod-morph.md) or [macros](macros.md), you can pass a dummy parameter value such as `0` to the hold-tap when you use it in your keymap.
|
||||
For instance, a hold-tap with node label `caps` and `bindings = <&kp>, <&caps_word>;` can be used in the keymap as below to send the caps lock keycode on hold and invoke the [caps word behavior](caps-word.md) on tap:
|
||||
|
||||
```
|
||||
&caps CAPS 0
|
||||
```
|
||||
|
||||
:::info
|
||||
You cannot use behaviors that expect more than one parameter such as [`&bt`](bluetooth.md) and [`&rgb_ug`](underglow.md) with hold-taps, due to the limitations of the [devicetree keymap format](../config/index.md#devicetree-files).
|
||||
One workaround is to create a [macro](macros.md) that invokes those behaviors and use the macro as the hold or tap action.
|
||||
:::
|
||||
|
||||
### Example Use-Cases
|
||||
|
||||
<Tabs
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ A macro definition looks like:
|
|||
|
||||
:::note
|
||||
The text before the colon (`:`) in the declaration of the macro node is the "node label", and is the text
|
||||
used to reference the macro in your keymap
|
||||
used to reference the macro in your keymap.
|
||||
:::
|
||||
|
||||
The macro can then be bound in your keymap by referencing it by the label `&zed_em_kay`, e.g.:
|
||||
|
|
@ -44,6 +44,11 @@ The macro can then be bound in your keymap by referencing it by the label `&zed_
|
|||
};
|
||||
```
|
||||
|
||||
:::note
|
||||
For use cases involving sending a single keycode with modifiers, for instance ctrl+tab, the [key press behavior](key-press.md)
|
||||
with [modifier functions](../codes/modifiers.mdx#modifier-functions) can be used instead of a macro.
|
||||
:::
|
||||
|
||||
### Bindings
|
||||
|
||||
Like [hold-taps](/docs/behaviors/hold-tap), macros are created by composing other behaviors, and any of those behaviors can
|
||||
|
|
|
|||
|
|
@ -38,6 +38,24 @@ Management of the bluetooth in ZMK is accomplished using the [`&bt` behavior](..
|
|||
|
||||
## Troubleshooting
|
||||
|
||||
### Connectivity Issues
|
||||
|
||||
Some users may experience a poor connection between the keyboard and the host. This might be due to poor quality BLE hardware, a metal enclosure on the keyboard or host, or the distance between them. Increasing the transmit power of the keyboard's BLE radio may reduce the severity of this problem. To do this, set the `CONFIG_BT_CTLR_TX_PWR_PLUS_8` configuration value in the `.conf` file of your user config directory as such:
|
||||
|
||||
```
|
||||
CONFIG_BT_CTLR_TX_PWR_PLUS_8=y
|
||||
```
|
||||
|
||||
For the `nRF52840`, the value `PLUS_8` can be set to any multiple of four between `MINUS_20` and `PLUS_8`. The default value for this config is `0`, but if you are having connection issues it is recommended to set it to `PLUS_8` because the power consumption difference is negligible. For more information on changing the transmit power of your BLE device, please refer to [the Zephyr docs.](https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_BT_CTLR_TX_PWR)
|
||||
|
||||
:::info
|
||||
This setting can also improve the connection strength between the keyboard halves for split keyboards.
|
||||
:::
|
||||
|
||||
### Using bluetooth output with USB power
|
||||
|
||||
If you want to test bluetooth output on your keyboard and are powering it through the USB connection rather than a battery, you will be able to pair with a host device but may not see keystrokes sent. In this case you need to use the [output selection behavior](../behaviors/outputs.md) to prefer sending keystrokes over bluetooth rather than USB. This might be necessary even if you are not powering from a device capable of receiving USB inputs, such as a USB charger.
|
||||
|
||||
## Known Issues
|
||||
|
||||
There are a few known issues related to BLE and ZMK:
|
||||
|
|
@ -57,3 +75,18 @@ If you attempt to pair a ZMK keyboard from macOS in a way that causes a bonding
|
|||
1. Remove the keyboard from macOS using the Bluetooth control panel.
|
||||
1. Invoke `&bt BT_CLR` on the keyboard while the profile associated with the macOS device is active, by pressing the correct keys for your particular keymap.
|
||||
1. Try connecting again from macOS.
|
||||
|
||||
### Windows Connected But Not Working
|
||||
|
||||
Occasionally pairing the keyboard to a Windows device might result in a state where the keyboard is connected but does not send any key strokes.
|
||||
If this occurs:
|
||||
|
||||
1. Remove the keyboard from Windows using the Bluetooth settings.
|
||||
1. Invoke `&bt BT_CLR` on the keyboard while the profile associated with the Windows device is active, by pressing the correct keys for your particular keymap.
|
||||
1. Turn off Bluetooth from Windows settings, then turn it back on.
|
||||
1. Pair the keyboard to the Windows device.
|
||||
|
||||
If this doesn't help, try following the procedure above but replace step 3 with one of the following:
|
||||
|
||||
- Restart the Windows device
|
||||
- Open "Device Manager," turn on "Show hidden devices" from the "View" menu, then find and delete the keyboard under the "Bluetooth" item
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ sidebar_title: Troubleshooting
|
|||
|
||||
The following page provides suggestions for common errors that may occur during firmware compilation or other issues with keyboard usage. If the information provided is insufficient to resolve the issue, feel free to seek out help from the [ZMK Discord](https://zmk.dev/community/discord/invite).
|
||||
|
||||
Please also see [the troubleshooting section](features/bluetooth.md#troubleshooting) under the Bluetooth feature page for issues related to bluetooth.
|
||||
|
||||
### File Transfer Error
|
||||
|
||||
Variations of the warnings shown below occur when flashing the `<firmware>.uf2` onto the microcontroller. This is because the microcontroller resets itself before the OS receives confirmation that the file transfer is complete. Errors like this are normal and can generally be ignored. Verification of a functional board can be done by attempting to pair your newly flashed keyboard to your computer via Bluetooth or plugging in a USB cable if `ZMK_USB` is enabled in your Kconfig.defconfig.
|
||||
|
|
@ -100,17 +102,3 @@ Perform the following steps to reset both halves of your split keyboard:
|
|||
1. Flash the actual image for each half of the split keyboard (e.g `my_board_left.uf2` to the left half, `my_board_right.uf2` to the right half).
|
||||
|
||||
After completing these steps, pair the halves of the split keyboard together by resetting them at the same time. Most commonly, this is done by grounding the reset pins for each of your keyboard's microcontrollers or pressing the reset buttons at the same time.
|
||||
|
||||
### Connectivity Issues
|
||||
|
||||
Some users may experience a poor connection between the keyboard and the host. This might be due to poor quality BLE hardware, a metal enclosure on the keyboard or host, or the distance between them. Increasing the transmit power of the keyboard's BLE radio may reduce the severity of this problem. To do this, set the `CONFIG_BT_CTLR_TX_PWR_PLUS_8` configuration value in the `.conf` file of your user config directory as such:
|
||||
|
||||
```
|
||||
CONFIG_BT_CTLR_TX_PWR_PLUS_8=y
|
||||
```
|
||||
|
||||
For the `nRF52840`, the value `PLUS_8` can be set to any multiple of four between `MINUS_20` and `PLUS_8`. The default value for this config is `0`, but if you are having connection issues it is recommended to set it to `PLUS_8` because the power consumption difference is negligible. For more information on changing the transmit power of your BLE device, please refer to [the Zephyr docs.](https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_BT_CTLR_TX_PWR)
|
||||
|
||||
### Other notes and warnings
|
||||
|
||||
- If you want to test bluetooth output on your keyboard and are powering it through the USB connection rather than a battery, you will be able to pair with a host device but may not see keystrokes sent. In this case you need to use the [output selection behavior](../docs/behaviors/outputs.md) to prefer sending keystrokes over bluetooth rather than USB. This might be necessary even if you are not powering from a device capable of receiving USB inputs, such as a USB charger.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue