Jacob/zmk
1
0
Fork 0
forked from kofal.net/zmk
Code Pull Requests Activity

refactor(docs): Split up troubleshooting page into a section

Browse Source
This commit is contained in:
Cem Aksoylar
2024-06-09 21:32:26 -07:00
parent 308d6bce6e
commit e56db304ea
10 changed files with 251 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/docs/features/bluetooth.md
View File

@@ -47,52 +47,4 @@ Firmware changes that would modify the descriptor include the following:
While the descriptor refresh happens on boot for USB, hosts will frequently cache this descriptor for BLE devices.
In order to refresh this cache, you need to remove the keyboard from the host device, clear the profile associated with the host on the keyboard, then pair again.
For Windows systems you might need to follow the instructions in [this troubleshooting section](#windows-connected-but-not-working) below.
## 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:
```ini
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/3.5.0/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.
### 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:
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
For Windows systems you might need to follow the additional instructions in [the section on troubleshooting connection issues](troubleshooting/connection-issues.mdx#windows-connected-but-not-working).