From 049c070b3a42463f5e9410f713e1eb9132c8e793 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com> Date: Tue, 13 Aug 2024 19:47:45 +0200 Subject: [PATCH] feat(docs): Minor improvements to the docs (#2411) --- docs/docs/config/index.md | 7 ++----- docs/docs/troubleshooting/connection-issues.mdx | 16 ++++++++++++++++ 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/docs/config/index.md b/docs/docs/config/index.md index a7c89b7b..409b1f04 100644 --- a/docs/docs/config/index.md +++ b/docs/docs/config/index.md @@ -37,11 +37,9 @@ ZMK will search for config files in: ...where `` is the name of the board and `` is the root directory of any [included module](../features/modules.mdx). These files describe the hardware of the board. -ZMK will search the board folder for the following config files: +ZMK will search the board folder for the following config files _in addition_ to [Zephyr board-defining files](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html#create-your-board-directory): -- `_defconfig` (Kconfig) - `.conf` (Kconfig) -- `.dts` (Devicetree) - `.keymap` (Devicetree, keyboards with onboard controllers only) Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in board folders. @@ -59,10 +57,9 @@ When building with a shield, ZMK will search for config files in: ...where `` is the name of the shield and `` is the root directory of any [included module](../features/modules.mdx). These files describe the hardware of the shield that the board is plugged into. -ZMK will search the shield folder for the following config files: +ZMK will search the shield folder for the following config files _in addition_ to [Zephyr shield-defining files](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html#shield-porting-and-configuration): - `.conf` (Kconfig) -- `.overlay` (Devicetree) - `.keymap` (Devicetree) Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in shield folders. diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index fe80326b..19d9f441 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -22,6 +22,10 @@ export const Uf2Tabs = (props) => ( ); +:::tip +[USB logging](../development/usb-logging.mdx) can be very helpful for diagnosing issues with ZMK. However, when connected to USB your ZMK device will output to USB by default. To troubleshoot wireless connection issues using logging, you will need to [change the preferred output endpoint](../behaviors/outputs.md). +::: + ## Split Keyboard Halves Unable to Pair [Split keyboard](../features/split-keyboards.md) halves will automatically pair with one another, but there are some cases where this breaks, and the pairing needs to be reset, for example: @@ -105,6 +109,18 @@ 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. +### Mitigating a Faulty Oscillator + +Rarely, due to a manufacturing error, a device may have a faulty oscillator. This prevents it from functioning correctly wirelessly and can be difficult to diagnose. Some microcontrollers such as the `nRF52840` allow for the usage of an internal oscillator instead of an external one. This results in increased power draw but can be a solution if your device does indeed have a faulty oscillator. + +For the `nRF52840`, the flag to set to use the internal oscillator is: + +``` +CONFIG_CLOCK_CONTROL_NRF_K32SRC_RC=y +``` + +Other microcontrollers may have similar configuration options [found in the Zephyr documentation](https://docs.zephyrproject.org/3.5.0/search.html?q=CONFIG_CLOCK_CONTROL&check_keywords=yes&area=default). Do note that not all microcontrollers allow for the use of an internal oscillator, though. + ## Issues While Connected ### Unreliable/Weak Connection