From e56db304ea857732ffc4720b848b326189506c9c Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Sun, 9 Jun 2024 21:32:26 -0700 Subject: [PATCH] refactor(docs): Split up troubleshooting page into a section --- docs/blog/2023-10-05-zmk-sotf-6.md | 2 +- docs/docs/customization.md | 2 +- docs/docs/features/bluetooth.md | 50 +----- docs/docs/troubleshooting.md | 143 ------------------ docs/docs/troubleshooting/building-issues.md | 54 +++++++ .../troubleshooting/connection-issues.mdx | 140 +++++++++++++++++ docs/docs/troubleshooting/flashing-issues.md | 29 ++++ docs/docs/troubleshooting/index.mdx | 10 ++ docs/docs/user-setup.mdx | 2 +- docs/sidebars.js | 15 +- 10 files changed, 251 insertions(+), 196 deletions(-) delete mode 100644 docs/docs/troubleshooting.md create mode 100644 docs/docs/troubleshooting/building-issues.md create mode 100644 docs/docs/troubleshooting/connection-issues.mdx create mode 100644 docs/docs/troubleshooting/flashing-issues.md create mode 100644 docs/docs/troubleshooting/index.mdx diff --git a/docs/blog/2023-10-05-zmk-sotf-6.md b/docs/blog/2023-10-05-zmk-sotf-6.md index fb8dc131d21..bd818cf67dc 100644 --- a/docs/blog/2023-10-05-zmk-sotf-6.md +++ b/docs/blog/2023-10-05-zmk-sotf-6.md @@ -105,7 +105,7 @@ Note that documentation is still lacking for utilizing more than one peripheral [petejohanson] contributed a fix to release held keys on peripheral disconnect [#1340](https://github.com/zmkfirmware/zmk/pull/1340), which makes scenarios where a split disconnects unexpectedly less painful. -[petejohanson] also improved [the `settings_reset` shield](/docs/troubleshooting#split-keyboard-halves-unable-to-pair) by making it clear bonds more reliably, and allow it to build for all boards in [#1879](https://github.com/zmkfirmware/zmk/pull/1879). +[petejohanson] also improved [the `settings_reset` shield](/docs/troubleshooting/connection-issues#split-keyboard-halves-unable-to-pair) by making it clear bonds more reliably, and allow it to build for all boards in [#1879](https://github.com/zmkfirmware/zmk/pull/1879). [petejohanson] and [xudongzheng] contributed additional split connectivity improvements, via using directed advertising in [#1913](https://github.com/zmkfirmware/zmk/pull/1913) and improving the robustness of central scanning in [#1912](https://github.com/zmkfirmware/zmk/pull/1912). diff --git a/docs/docs/customization.md b/docs/docs/customization.md index 96b5e4ea9a0..87d78a22b1c 100644 --- a/docs/docs/customization.md +++ b/docs/docs/customization.md @@ -50,7 +50,7 @@ It is also possible to build firmware locally on your computer by following the For normal keyboards, follow the same flashing instructions as before to flash your updated firmware. For split keyboards, only the central (left) side will need to be reflashed if you are just updating your keymap. -More troubleshooting information for split keyboards can be found [here](troubleshooting.md#split-keyboard-halves-unable-to-pair). +More troubleshooting information for split keyboards can be found [here](troubleshooting/connection-issues.mdx#split-keyboard-halves-unable-to-pair). ## Building Additional Keyboards diff --git a/docs/docs/features/bluetooth.md b/docs/docs/features/bluetooth.md index 28ba21367d1..d148acd82db 100644 --- a/docs/docs/features/bluetooth.md +++ b/docs/docs/features/bluetooth.md @@ -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). diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md deleted file mode 100644 index 876cbb9b4d2..00000000000 --- a/docs/docs/troubleshooting.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Troubleshooting -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 `.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. - -| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/windows.png) | -| :------------------------------------------------------------------------------: | -| An example of the file transfer error on Windows 10 | - -| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/linux.png) | -| :----------------------------------------------------------------------------: | -| An example of the file transfer error on Linux | - -| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/mac.png) | -| :--------------------------------------------------------------------------: | -| An example of the file transfer error on macOS | - -### macOS Ventura error - -macOS 13.0 (Ventura) Finder may report an error code 100093 when copying `.uf2` files into microcontrollers. This bug is limited to the operating system's Finder. You can work around it by copying on Terminal command line or use a third party file manager. Issue is fixed in macOS version 13.1. - -### macOS Sonoma error - -macOS 14.x (Sonoma) Finder may report an "Error code -36" when copying `.uf2` files into microcontrollers. A similar "fcopyfile failed: Input/output error" will also be reported when copying is performed using Terminal command line. These errors can be ignored because they are reported when the bootloader disconnects automatically after the uf2 file is copied successfully. - -### CMake Error - -An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined. -For more information, see [Zephyr's CMake Package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html). - -### West Build Errors - -West build errors usually indicate syntax problems in the `.keymap` file during the compilation process. The following are some examples and root causes. - -:::note -If you are reviewing these errors in the GitHub Actions tab, they can be found in the `West Build` step of the build process. -::: - -#### Keymap error - -If you get an error stating `Keymap node not found, check a keymap is available and is has compatible = "zmk,keymap" set` this is an indication that the build process cannot find the keymap. Double check that the `.keymap` file is present and has been discovered by the build process. This can be checked by looking for a line in the build log stating `-- Using keymap file: /path/to/keymap/file/.keymap`. Inside the keymap file ensure the keymap node has `compatible = zmk,keymap` and it's not misspelled. For more information see the [Keymap](features/keymaps.mdx) and [Config](config/index.md) documentation. - -#### Devicetree errors - -A `devicetree error` followed by a reference to the line number on `.keymap` refers to an issue at the exact line position in that file. For example, below error message indicates a missing `;` at line 109 of the `cradio.keymap` file: - -``` -devicetree error: /__w/zmk-config/zmk-config/config/cradio.keymap:109 (column 4): parse error: expected ';' or ',' -``` - -A `devicetree error` followed by an `empty_file.c` reference with `lacks #binding-cells` string indicates possible problems with improper parameters for specific bindings: - -``` -devicetree error: lacks #binding-cells -``` - -This error can be triggered by incorrect binding syntax such as `&kp BT_SEL 0` instead of `&bt BT_SEL 0`. - -A `devicetree_generated.h` error that follows with an "undeclared here" string indicates a problem with key bindings, like behavior nodes (e.g. `&kp` or `&mt`) with incorrect number of parameters: - -``` -/__w/zmk-config/zmk-config/build/zephyr/include/generated/devicetree_generated.h:3756:145: error: 'DT_N_S_keymap_S_symbol_layer_P_bindings_IDX_12_PH_P_label' undeclared here (not in a function); did you mean 'DT_N_S_keymap_S_symbol_layer_P_bindings_IDX_16_PH'? -``` - -In this example, the error string `DT_N_S_keymap_S_symbol_layer_P_bindings_IDX_12_PH_P_label` indicates a problem with the key binding in position `12` in the `symbol_layer` of the keymap. - -:::info -Key positions are numbered starting from `0` at the top left key on the keymap, incrementing horizontally, row by row. -::: - -:::tip -A common mistake that leads to this error is to use [key press keycodes](behaviors/key-press.md) without the leading `&kp` binding. That is, having entries such as `SPACE` that should have been `&kp SPACE`. -::: - -### Split Keyboard Halves Unable to Pair - -Split keyboard halves will automatically pair with one another, but there are some cases where this breaks, and the pairing needs to be reset, for example: - -- Switching which halves are the central/peripheral. -- Replacing the controller for one of the halves. - -These issues can be resolved by flashing a settings reset firmware to both controllers. - -:::warning - -This procedure will erase all settings, such as Bluetooth profiles, output selection, RGB underglow color, etc. - -::: - -First, acquire the reset UF2 image file with one of the following options: - -#### Option 1: Build Reset UF2 in 'zmk-config' - -Find the `build.yaml` file in your `zmk-config` folder and add an additional settings reset build for the board used by your split keyboard. For example assuming that the config repo is setup for nice!nano v2 with Corne, append the `settings_reset` shield to the `build.yaml` file as follows: - -```yml -include: - - board: nice_nano_v2 - shield: corne_left - - board: nice_nano_v2 - shield: corne_right - - board: nice_nano_v2 - shield: settings_reset -``` - -Save the file, commit the changes and push them to GitHub. Download the new firmware zip file build by the latest GitHub Actions job. In it you will find an additional `settings_reset` UF2 image file. - -#### Option 2: Download Reset UF2 from ZMK's Workflow - -1. [Open the GitHub `Actions` tab and select the `Build` workflow](https://github.com/zmkfirmware/zmk/actions?query=workflow%3ABuild+branch%3Amain+event%3Apush). -1. Find one of the 'results' for which the core-coverage job was successfully run, indicated by a green checkmark in the core-coverage bubble like the image example below. -1. From the next page under "Artifacts", download and unzip the `-settings_reset-zmk` zip file for the UF2 image. - -| ![Successful core-coverage Job](../docs/assets/troubleshooting/splitpairing/corecoverage.png) | -| :-------------------------------------------------------------------------------------------: | -| An example of a successful core-coverage job which will produce a settings_reset firmware. | - -#### Reset Split Keyboard Procedure - -Perform the following steps to reset both halves of your split keyboard: - -1. Put each half of the split keyboard into bootloader mode. -1. Flash one of the halves of the split with the downloaded settings reset UF2 image. -1. Repeat step 2 with the other half of the 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. - -Once this is done, you can remove/forget the keyboard on each host device and pair it again. - -:::info - -The settings reset firmware has Bluetooth disabled to prevent the two sides from automatically re-pairing until you are done resetting them both. You will not be able to pair your keyboard or see it in any Bluetooth device lists until you have flashed the normal firmware again. - -::: diff --git a/docs/docs/troubleshooting/building-issues.md b/docs/docs/troubleshooting/building-issues.md new file mode 100644 index 00000000000..e37d3934d79 --- /dev/null +++ b/docs/docs/troubleshooting/building-issues.md @@ -0,0 +1,54 @@ +--- +title: Building Issues +sidebar_label: Building Issues +description: Troubleshooting issues when compiling ZMK firmware. +--- + +## CMake Error + +An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined. +For more information, see [Zephyr's CMake Package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html). + +## West Build Errors + +West build errors usually indicate syntax problems in the `.keymap` file during the compilation process. The following are some examples and root causes. + +:::note +If you are reviewing these errors in the GitHub Actions tab, they can be found in the `West Build` step of the build process. +::: + +### Keymap Error + +If you get an error stating `Keymap node not found, check a keymap is available and is has compatible = "zmk,keymap" set` this is an indication that the build process cannot find the keymap. Double check that the `.keymap` file is present and has been discovered by the build process. This can be checked by looking for a line in the build log stating `-- Using keymap file: /path/to/keymap/file/.keymap`. Inside the keymap file ensure the keymap node has `compatible = zmk,keymap` and it's not misspelled. For more information see the [Keymap](features/keymaps.mdx) and [Config](config/index.md) documentation. + +### Devicetree Errors + +A `devicetree error` followed by a reference to the line number on `.keymap` refers to an issue at the exact line position in that file. For example, below error message indicates a missing `;` at line 109 of the `cradio.keymap` file: + +``` +devicetree error: /__w/zmk-config/zmk-config/config/cradio.keymap:109 (column 4): parse error: expected ';' or ',' +``` + +A `devicetree error` followed by an `empty_file.c` reference with `lacks #binding-cells` string indicates possible problems with improper parameters for specific bindings: + +``` +devicetree error: lacks #binding-cells +``` + +This error can be triggered by incorrect binding syntax such as `&kp BT_SEL 0` instead of `&bt BT_SEL 0`. + +A `devicetree_generated.h` error that follows with an "undeclared here" string indicates a problem with key bindings, like behavior nodes (e.g. `&kp` or `&mt`) with incorrect number of parameters: + +``` +/__w/zmk-config/zmk-config/build/zephyr/include/generated/devicetree_generated.h:3756:145: error: 'DT_N_S_keymap_S_symbol_layer_P_bindings_IDX_12_PH_P_label' undeclared here (not in a function); did you mean 'DT_N_S_keymap_S_symbol_layer_P_bindings_IDX_16_PH'? +``` + +In this example, the error string `DT_N_S_keymap_S_symbol_layer_P_bindings_IDX_12_PH_P_label` indicates a problem with the key binding in position `12` in the `symbol_layer` of the keymap. + +:::info +Key positions are numbered starting from `0` at the top left key on the keymap, incrementing horizontally, row by row. +::: + +:::tip +A common mistake that leads to this error is to use [key press keycodes](behaviors/key-press.md) without the leading `&kp` binding. That is, having entries such as `SPACE` that should have been `&kp SPACE`. +::: diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx new file mode 100644 index 00000000000..59a6a20811d --- /dev/null +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -0,0 +1,140 @@ +--- +title: Connection Issues +sidebar_label: Connection Issues +description: Troubleshooting wireless connection issues of ZMK devices. +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +export const Uf2Tabs = (props) => ( + + {/* eslint-disable-next-line */} + {props.children} + + +); + +## Split Keyboard Halves Unable to Pair + +Split keyboard halves will automatically pair with one another, but there are some cases where this breaks, and the pairing needs to be reset, for example: + +- Switching which halves are the central/peripheral. +- Replacing the controller for one of the halves. + +These issues can be resolved by flashing a settings reset firmware to both controllers. + +:::warning + +This procedure will erase all settings, such as Bluetooth profiles, output selection, RGB underglow color, etc. + +::: + +### Acquiring a Reset UF2 + +First, acquire the reset UF2 image file with one of the following options: + + + + +Find the `build.yaml` file in your `zmk-config` folder and add an additional settings reset build for the board used by your split keyboard. For example assuming that the config repo is setup for nice!nano v2 with Corne, append the `settings_reset` shield to the `build.yaml` file as follows: + +```yml +include: + - board: nice_nano_v2 + shield: corne_left + - board: nice_nano_v2 + shield: corne_right + - board: nice_nano_v2 + shield: settings_reset +``` + +Save the file, commit the changes and push them to GitHub. Download the new firmware zip file build by the latest GitHub Actions job. In it you will find an additional `settings_reset` UF2 image file. + + + + +1. [Open the GitHub `Actions` tab and select the `Build` workflow](https://github.com/zmkfirmware/zmk/actions?query=workflow%3ABuild+branch%3Amain+event%3Apush). +1. Find one of the 'results' for which the core-coverage job was successfully run, indicated by a green checkmark in the core-coverage bubble like the image example below. +1. From the next page under "Artifacts", download and unzip the `-settings_reset-zmk` zip file for the UF2 image. + +| ![Successful core-coverage Job](../../docs/assets/troubleshooting/splitpairing/corecoverage.png) | +| :----------------------------------------------------------------------------------------------: | +| An example of a successful core-coverage job which will produce a settings_reset firmware. | + + + + +### Reset Split Keyboard Procedure + +Perform the following steps to reset **_both_** halves of your split keyboard: + +1. Put each half of the split keyboard into bootloader mode. +1. Flash one of the halves of the split with the downloaded settings reset UF2 image. +1. Repeat step 2 with the other half of the 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. + +Once this is done, you can remove/forget the keyboard on each host device and pair it again. + +:::info + +The settings reset firmware has Bluetooth disabled to prevent the two sides from automatically re-pairing until you are done resetting them both. You will not be able to pair your keyboard or see it in any Bluetooth device lists until you have flashed the normal firmware again. + +::: + +## Issues While Connected + +### Unreliable/Weak Connection + +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 diff --git a/docs/docs/troubleshooting/flashing-issues.md b/docs/docs/troubleshooting/flashing-issues.md new file mode 100644 index 00000000000..699555d5f92 --- /dev/null +++ b/docs/docs/troubleshooting/flashing-issues.md @@ -0,0 +1,29 @@ +--- +title: Flashing Issues +sidebar_label: Flashing Issues +description: Troubleshooting issues when flashing ZMK firmware to devices. +--- + +## 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. + +| ![Example Error Screen](../../docs/assets/troubleshooting/filetransfer/windows.png) | +| :---------------------------------------------------------------------------------: | +| An example of the file transfer error on Windows 10 | + +| ![Example Error Screen](../../docs/assets/troubleshooting/filetransfer/linux.png) | +| :-------------------------------------------------------------------------------: | +| An example of the file transfer error on Linux | + +| ![Example Error Screen](../../docs/assets/troubleshooting/filetransfer/mac.png) | +| :-----------------------------------------------------------------------------: | +| An example of the file transfer error on macOS | + +## macOS Ventura Error + +macOS 13.0 (Ventura) Finder may report an error code 100093 when copying `.uf2` files into microcontrollers. This bug is limited to the operating system's Finder. You can work around it by copying on Terminal command line or use a third party file manager. Issue is fixed in macOS version 13.1. + +## macOS Sonoma Error + +macOS 14.x (Sonoma) Finder may report an "Error code -36" when copying `.uf2` files into microcontrollers. A similar "fcopyfile failed: Input/output error" will also be reported when copying is performed using Terminal command line. These errors can be ignored because they are reported when the bootloader disconnects automatically after the uf2 file is copied successfully. diff --git a/docs/docs/troubleshooting/index.mdx b/docs/docs/troubleshooting/index.mdx new file mode 100644 index 00000000000..45a93191b16 --- /dev/null +++ b/docs/docs/troubleshooting/index.mdx @@ -0,0 +1,10 @@ +--- +title: Troubleshooting +sidebar_label: Troubleshooting +--- + +import DocCardList from "@theme/DocCardList"; + +The following pages provide suggestions for common errors that may occur while setting up or using devices running ZMK. If the information provided is insufficient to resolve an issue, feel free to seek out additional help from the [ZMK Discord](https://zmk.dev/community/discord/invite). + + diff --git a/docs/docs/user-setup.mdx b/docs/docs/user-setup.mdx index 355fc51d5e2..78d4362857e 100644 --- a/docs/docs/user-setup.mdx +++ b/docs/docs/user-setup.mdx @@ -225,7 +225,7 @@ For split keyboards, after flashing each half individually you can connect them :::note If you have issues connecting the halves, make sure that both sides are getting powered properly through USB or batteries, then follow the -[recommended troubleshooting procedure](troubleshooting.md#split-keyboard-halves-unable-to-pair). This is typically necessary if you +[recommended troubleshooting procedure](troubleshooting/connection-issues.mdx#split-keyboard-halves-unable-to-pair). This is typically necessary if you swapped firmware sides between controllers, like flashing left side firmware to the same controller after flashing the right, or vice versa. ::: diff --git a/docs/sidebars.js b/docs/sidebars.js index a3b4ea2ce74..e8c715c8c76 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -6,7 +6,20 @@ module.exports = { "faq", "user-setup", "customization", - "troubleshooting", + { + type: "category", + label: "Troubleshooting", + link: { + type: "doc", + id: "troubleshooting/index", + }, + collapsed: true, + items: [ + "troubleshooting/building-issues", + "troubleshooting/flashing-issues", + "troubleshooting/connection-issues", + ], + }, ], Features: [ "features/keymaps",