xenua
/
zmk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
805 Commits
1 Branch
0 Tags
14 MiB
 
 
 
 
 
Tree: 307a8d09db
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '307a8d09db'
${ noResults }
zmk/docs/docs/troubleshooting.md

4.1 KiB
Raw Blame History

id title sidebar_title
troubleshooting Troubleshooting Troubleshooting

Summary

The following page provides suggestions for common errors that may occur during firmware compilation. If the information provided is insufficient to resolve the issue, feel free to seek out help from the ZMK Discord.

File Transfer Error

Variations of the warnings shown below occur when flashing the <firmware>.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
An example of the file transfer error on Windows 10
Example Error Screen
An example of the file transfer error on Linux

CMake Error

CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:28 (message):
  CONFIG_USB_DEVICE_VID has default value 0x2FE3.
 
  This value is only for testing and MUST be configured for USB products.
 
 
CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:34 (message):
  CONFIG_USB_DEVICE_PID has default value 0x100.
 
  This value is only for testing and MUST be configured for USB products.

CMake Warnings shown above during west build are normal occurrences. They should not negatively affect the firmware's ability to function as normal.

On the other hand, 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, click here.

dtlib.DTError

An error along the lines of dtlib.DTError: <board>.dts.pre.tmp:<line number> during firmware compilation indicates an issue within the <shield>.keymap file. This can be verified by checking the file in question, found in mkdir/app/build.

Example Error Screen
An example of the dtlib.DTError when compiling an iris with the nice!nano while the keymap is not properly defined

After opening the <board>.dts.pre.tmp:<line number> and scrolling down to the referenced line, one can locate errors within their shield's keymap by checking if the referenced keycodes were properly converted into the correct USB HID Usage ID.

Unhealthy Keymap Temp
An incorrectly defined keymap unable to compile. As shown in red, &kp SPAC is not a valid reference to the USB HID Usage ID used for "Keyboard Spacebar"
Healthy Keymap Temp
A properly defined keymap with successful compilation. As shown in red, the corrected keycode (&kp SPC) references the proper Usage ID defined in the USB HID Usage Tables