From a2af74f5ab4d2d7142791ae55cab11d59b29bc4d Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Mon, 29 May 2023 21:25:12 -0700 Subject: [PATCH 1/7] feat(docs): Add note on modifier functions to macros --- docs/docs/behaviors/macros.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/docs/behaviors/macros.md b/docs/docs/behaviors/macros.md index 1648892e..1628e0cb 100644 --- a/docs/docs/behaviors/macros.md +++ b/docs/docs/behaviors/macros.md @@ -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 From 0508718d6ce8b40adbe932b0bd9bb30ee5e0bbf5 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Mon, 29 May 2023 21:52:16 -0700 Subject: [PATCH 2/7] feat(docs): Add behavior types section for hold-tap --- docs/docs/behaviors/hold-tap.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/docs/behaviors/hold-tap.md b/docs/docs/behaviors/hold-tap.md index f0096606..2a8489a1 100644 --- a/docs/docs/behaviors/hold-tap.md +++ b/docs/docs/behaviors/hold-tap.md @@ -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 Date: Mon, 29 May 2023 22:03:24 -0700 Subject: [PATCH 3/7] feat(docs): Add troubleshooting for Windows issue --- docs/docs/features/bluetooth.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/docs/features/bluetooth.md b/docs/docs/features/bluetooth.md index f1a3e241..ff182398 100644 --- a/docs/docs/features/bluetooth.md +++ b/docs/docs/features/bluetooth.md @@ -57,3 +57,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 From 30ba4b08aed896d77fb7ade96ef0334d8f30af5d Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Mon, 29 May 2023 22:06:09 -0700 Subject: [PATCH 4/7] feat(docs): Add pointer to Bluetooth page in troubleshooting --- docs/docs/troubleshooting.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index 96f729b9..e8a05b6b 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -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. + ### File Transfer Error Variations of the warnings shown below occur when flashing the `.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. From a9ad11f91e82e214d91cf9bf1586431060759f06 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Fri, 2 Jun 2023 18:42:50 -0700 Subject: [PATCH 5/7] refactor(docs): Move BT troubleshooting items to BT page --- docs/docs/features/bluetooth.md | 14 ++++++++++++++ docs/docs/troubleshooting.md | 16 +--------------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/docs/features/bluetooth.md b/docs/docs/features/bluetooth.md index ff182398..386ad70e 100644 --- a/docs/docs/features/bluetooth.md +++ b/docs/docs/features/bluetooth.md @@ -38,6 +38,20 @@ 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) + +### 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](../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. + ## Known Issues There are a few known issues related to BLE and ZMK: diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index e8a05b6b..d47671bc 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -5,7 +5,7 @@ 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. +Please also see [the troubleshooting section](features/bluetooth.md#troubleshooting) under the Bluetooth feature page for issues related to bluetooth. ### File Transfer Error @@ -102,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. From 0682bc3aa6d9b9deac48b5aa6c781241075819b3 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Fri, 2 Jun 2023 18:45:15 -0700 Subject: [PATCH 6/7] feat(docs): Note split connectivity improvement with TX power --- docs/docs/features/bluetooth.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/docs/features/bluetooth.md b/docs/docs/features/bluetooth.md index 386ad70e..9637c4d0 100644 --- a/docs/docs/features/bluetooth.md +++ b/docs/docs/features/bluetooth.md @@ -48,6 +48,10 @@ 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](../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. From ace11e327fbfb4c4c894bb66328156d4d0b7eda0 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Fri, 2 Jun 2023 20:46:13 -0700 Subject: [PATCH 7/7] fix(docs): Fix broken link in BT troubleshooting --- docs/docs/features/bluetooth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/features/bluetooth.md b/docs/docs/features/bluetooth.md index 9637c4d0..b75b8953 100644 --- a/docs/docs/features/bluetooth.md +++ b/docs/docs/features/bluetooth.md @@ -54,7 +54,7 @@ This setting can also improve the connection strength between the keyboard halve ### 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](../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. +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