From a3c1857df4c298020392cf287a7a2348bfb9020d Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Mon, 22 Jul 2024 17:43:21 +0200 Subject: [PATCH 1/7] Added a note on experimental bluetooth settings under connectivity troubleshooting. --- docs/docs/troubleshooting/connection-issues.mdx | 5 +++++ zmk-modules | 1 + 2 files changed, 6 insertions(+) create mode 160000 zmk-modules diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index 5fdd1c836a0..51aed63b82a 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -91,6 +91,11 @@ The settings reset firmware has Bluetooth disabled to prevent the two sides from ::: + +## Unable to Connect to Device + +Some devices and operating systems may have additional security/protocol settings that they require be met before allowing a bluetooth peripheral to pair with them. If your keyboard is visible to your host but you are having trouble connecting or no input is registered, this might be the cause. You can try enabling some of ZMK's [experimental bluetooth settings](../config/bluetooth.md) to resolve the issue. + ## Issues While Connected ### Unreliable/Weak Connection diff --git a/zmk-modules b/zmk-modules new file mode 160000 index 00000000000..29bb9d40bb4 --- /dev/null +++ b/zmk-modules @@ -0,0 +1 @@ +Subproject commit 29bb9d40bb46b4a9ed6099fef108e58e70cad0d6 From d9e3e1dd21cb47bde4432985a1666960b77199dc Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Mon, 22 Jul 2024 18:25:16 +0200 Subject: [PATCH 2/7] prettier --- docs/docs/troubleshooting/connection-issues.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index 51aed63b82a..36d79290c6a 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -91,7 +91,6 @@ The settings reset firmware has Bluetooth disabled to prevent the two sides from ::: - ## Unable to Connect to Device Some devices and operating systems may have additional security/protocol settings that they require be met before allowing a bluetooth peripheral to pair with them. If your keyboard is visible to your host but you are having trouble connecting or no input is registered, this might be the cause. You can try enabling some of ZMK's [experimental bluetooth settings](../config/bluetooth.md) to resolve the issue. From c0e90597c7cafb78e3baaf783e1c655301bd50c9 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Mon, 22 Jul 2024 20:37:41 +0200 Subject: [PATCH 3/7] made adjustments --- docs/docs/troubleshooting/connection-issues.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index 36d79290c6a..6e3f055b2e9 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -93,7 +93,10 @@ The settings reset firmware has Bluetooth disabled to prevent the two sides from ## Unable to Connect to Device -Some devices and operating systems may have additional security/protocol settings that they require be met before allowing a bluetooth peripheral to pair with them. If your keyboard is visible to your host but you are having trouble connecting or no input is registered, this might be the cause. You can try enabling some of ZMK's [experimental bluetooth settings](../config/bluetooth.md) to resolve the issue. +Some devices and operating systems may have additional restrictions that they require be met before allowing a bluetooth peripheral to pair with them. If your keyboard is visible to your host but you are having issues trouble connecting or no input is registered, this might be the cause. Some of ZMK's [experimental bluetooth settings](../config/bluetooth.md) may suffice to resolve the issue. In particular: + +- Disabling PHY 2Mbps ([`CONFIG_BT_CTLR_PHY_2M`](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_CTLR_PHY_2M)) helps to pair and connect for certain wireless chipset firmware versions, particularly on Windows (Realtek and Intel chips) and older Intel Macs with Broadcom chipsets. +- Enabling passkey entry ([`CONFIG_ZMK_BLE_PASSKEY_ENTRY`](../config/bluetooth.md)) helps for certain Windows computers (work-managed ones in particular). This may also manifest in not sending keystrokes. ## Issues While Connected @@ -142,3 +145,5 @@ If this doesn't help, try following the procedure above but replace step 3 with - 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 + +Some Windows devices may also require passkey entry, described under [Unable to Connect to Device](#unable-to-connect-to-device). From 514639fc8ea78bdfff0a60ff3e075f690607f319 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Mon, 22 Jul 2024 20:44:20 +0200 Subject: [PATCH 4/7] removed zmk-modules --- zmk-modules | 1 - 1 file changed, 1 deletion(-) delete mode 160000 zmk-modules diff --git a/zmk-modules b/zmk-modules deleted file mode 160000 index 29bb9d40bb4..00000000000 --- a/zmk-modules +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 29bb9d40bb46b4a9ed6099fef108e58e70cad0d6 From c09079c5e07795f43e82bca178935a1ce13746a9 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com> Date: Mon, 22 Jul 2024 23:33:02 +0200 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Cem Aksoylar --- docs/docs/troubleshooting/connection-issues.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index 6e3f055b2e9..472e1478cd4 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -95,8 +95,8 @@ The settings reset firmware has Bluetooth disabled to prevent the two sides from Some devices and operating systems may have additional restrictions that they require be met before allowing a bluetooth peripheral to pair with them. If your keyboard is visible to your host but you are having issues trouble connecting or no input is registered, this might be the cause. Some of ZMK's [experimental bluetooth settings](../config/bluetooth.md) may suffice to resolve the issue. In particular: -- Disabling PHY 2Mbps ([`CONFIG_BT_CTLR_PHY_2M`](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_CTLR_PHY_2M)) helps to pair and connect for certain wireless chipset firmware versions, particularly on Windows (Realtek and Intel chips) and older Intel Macs with Broadcom chipsets. -- Enabling passkey entry ([`CONFIG_ZMK_BLE_PASSKEY_ENTRY`](../config/bluetooth.md)) helps for certain Windows computers (work-managed ones in particular). This may also manifest in not sending keystrokes. +- Disabling PHY 2Mbps ([`CONFIG_BT_CTLR_PHY_2M=n`](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_CTLR_PHY_2M)) helps to pair and connect for certain wireless chipset firmware versions, particularly on Windows (Realtek and Intel chips) and older Intel Macs with Broadcom chipsets. +- Enabling passkey entry ([`CONFIG_ZMK_BLE_PASSKEY_ENTRY=y`](../config/bluetooth.md)) helps for certain Windows computers (work-managed ones in particular). This may also manifest in not sending keystrokes. ## Issues While Connected @@ -146,4 +146,4 @@ If this doesn't help, try following the procedure above but replace step 3 with - 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 -Some Windows devices may also require passkey entry, described under [Unable to Connect to Device](#unable-to-connect-to-device). +Some Windows devices may also require passkey entry, described under ["Unable to Connect to Device"](#unable-to-connect-to-device). From 7069ec455b3b864b8ca58d1a4b13bcabcd1117a4 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Mon, 22 Jul 2024 23:40:01 +0200 Subject: [PATCH 6/7] Requested adjustments --- docs/docs/config/bluetooth.md | 14 +++++++------- docs/docs/troubleshooting/connection-issues.mdx | 13 ++++++++----- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/docs/config/bluetooth.md b/docs/docs/config/bluetooth.md index 02d203510dd..83fb9ec09d8 100644 --- a/docs/docs/config/bluetooth.md +++ b/docs/docs/config/bluetooth.md @@ -9,10 +9,10 @@ See [Configuration Overview](index.md) for instructions on how to change these s ## Kconfig -| Option | Type | Description | Default | -| -------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -| `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` | bool | Enables a combination of settings that are planned to be default in future versions of ZMK to improve connection stability. This includes changes to timing on BLE pairing initiation, restores use of the updated/new LLCP implementation, and disables 2M PHY support. | n | -| `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC` | bool | Enables a combination of settings that are planned to be officially supported in the future. This includes enabling BT Secure Connection passkey entry, and allows overwrite of keys from previously paired hosts. | n | -| `CONFIG_ZMK_BLE_EXPERIMENTAL_FEATURES` | bool | Aggregate config that enables both `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` and `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC`. | n | -| `CONFIG_ZMK_BLE_PASSKEY_ENTRY` | bool | Enable passkey entry during pairing for enhanced security. (Note: After enabling this, you will need to re-pair all previously paired hosts.) | n | -| `CONFIG_BT_GATT_ENFORCE_SUBSCRIPTION` | bool | Low level setting for GATT subscriptions. Set to `n` to work around an annoying Windows bug with battery notifications. | y | +| Option | Type | Description | Default | +| -------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | +| `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` | bool | Enables a combination of settings that are planned to be default in future versions of ZMK to improve connection stability. Currently this only disables 2M PHY support. | n | +| `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC` | bool | Enables a combination of settings that are planned to be officially supported in the future. This includes enabling BT Secure Connection passkey entry, and allows overwrite of keys from previously paired hosts. | n | +| `CONFIG_ZMK_BLE_EXPERIMENTAL_FEATURES` | bool | Aggregate config that enables both `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` and `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC`. | n | +| `CONFIG_ZMK_BLE_PASSKEY_ENTRY` | bool | Enable passkey entry during pairing for enhanced security. (Note: After enabling this, you will need to re-pair all previously paired hosts.) | n | +| `CONFIG_BT_GATT_ENFORCE_SUBSCRIPTION` | bool | Low level setting for GATT subscriptions. Set to `n` to work around an annoying Windows bug with battery notifications. | y | diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index 472e1478cd4..775b455693a 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -93,11 +93,19 @@ The settings reset firmware has Bluetooth disabled to prevent the two sides from ## Unable to Connect to Device +### Additional Bluetooth Options + Some devices and operating systems may have additional restrictions that they require be met before allowing a bluetooth peripheral to pair with them. If your keyboard is visible to your host but you are having issues trouble connecting or no input is registered, this might be the cause. Some of ZMK's [experimental bluetooth settings](../config/bluetooth.md) may suffice to resolve the issue. In particular: - Disabling PHY 2Mbps ([`CONFIG_BT_CTLR_PHY_2M=n`](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_CTLR_PHY_2M)) helps to pair and connect for certain wireless chipset firmware versions, particularly on Windows (Realtek and Intel chips) and older Intel Macs with Broadcom chipsets. - Enabling passkey entry ([`CONFIG_ZMK_BLE_PASSKEY_ENTRY=y`](../config/bluetooth.md)) helps for certain Windows computers (work-managed ones in particular). This may also manifest in not sending keystrokes. +### Issues With Dual Boot Setups + +Since ZMK associates pairing/bond keys with hardware addresses of hosts, you cannot pair to two different operating systems in a dual boot system at the same time. +While you can find [documented workarounds](https://wiki.archlinux.org/title/bluetooth#Dual_boot_pairing) that involve copying pairing keys across operating systems and use both OS with a single profile, they can be fairly involved and should be followed with caution. + + ## Issues While Connected ### Unreliable/Weak Connection @@ -118,11 +126,6 @@ This setting can also improve the connection strength between the keyboard halve 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. -### Issues With Dual Boot Setups - -Since ZMK associates pairing/bond keys with hardware addresses of hosts, you cannot pair to two different operating systems in a dual boot system at the same time. -While you can find [documented workarounds](https://wiki.archlinux.org/title/bluetooth#Dual_boot_pairing) that involve copying pairing keys across operating systems and use both OS with a single profile, they can be fairly involved and should be followed with caution. - ### macOS Connected but Not Working If you attempt to pair a ZMK keyboard from macOS in a way that causes a bonding issue, macOS may report the keyboard as connected, but fail to actually work. If this occurs: From 8ec65b782ddebd58032952c28181a4ce753fae4a Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Mon, 22 Jul 2024 23:40:45 +0200 Subject: [PATCH 7/7] prettier --- docs/docs/troubleshooting/connection-issues.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index 775b455693a..f077702c5bb 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -105,7 +105,6 @@ Some devices and operating systems may have additional restrictions that they re Since ZMK associates pairing/bond keys with hardware addresses of hosts, you cannot pair to two different operating systems in a dual boot system at the same time. While you can find [documented workarounds](https://wiki.archlinux.org/title/bluetooth#Dual_boot_pairing) that involve copying pairing keys across operating systems and use both OS with a single profile, they can be fairly involved and should be followed with caution. - ## Issues While Connected ### Unreliable/Weak Connection