pwarren/zmk_mf68
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: Revise "Troubleshooting" for Zephyr 3.0 (#1214)

Browse source 
Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
Co-authored-by: Dom H <dom@hxy.io>
This commit is contained in:
Albert Y 2022-04-07 16:26:22 +08:00 committed by GitHub
parent b44410ac44
commit 6753d31ee9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 23 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
docs/docs/assets/troubleshooting/keymaps/errorscreen.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 182 KiB

BIN
docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 184 KiB

BIN
docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 183 KiB

5
docs/docs/behaviors/key-press.md
View file

@ -33,11 +33,6 @@ provided by ZMK near the top:
Doing so makes a set of defines such as `A`, `N1`, etc. available for use with these behaviors
### Improperly defined keymap - `dtlib.DTError: <board>.dts.pre.tmp:<line number>`
When compiling firmware from a keymap, it may be common to encounter an error in the form of a`dtlib.DTError: <board>.dts.pre.tmp:<line number>`.
For instructions to resolve such an error, click [here](../troubleshooting.md###Improperly-defined-keymap)
## Key Press
The "key press" behavior sends standard keycodes on press/release.

39
docs/docs/troubleshooting.md
View file

@ -26,28 +26,35 @@ Variations of the warnings shown below occur when flashing the `<firmware>.uf2`
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](../docs/development/setup.md#environment-variables).
### dtlib.DTError
### West Build Errors
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](../docs/assets/troubleshooting/keymaps/errorscreen.png) |
| :----------------------------------------------------------------------------------------------------------------: |
| 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](https://www.usb.org/document-library/hid-usage-tables-12).
West build errors usually indicate syntax problems in the `<keyboard>.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, the contents of `<board>.dts.pre.tmp` is output (with line numbers) in the next step of the build process.
If you are reviewing these errors in the GitHub Actions tab, they can be found in the `West Build` step of the build process.
:::
| ![Unhealthy Keymap Temp](../docs/assets/troubleshooting/keymaps/unhealthyEDIT.png) |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| An incorrectly defined keymap unable to compile. As shown in red, `&kp SPAC` is not a valid reference to the [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12) used for "Keyboard Spacebar" |
#### devicetree error
| ![Healthy Keymap Temp](../docs/assets/troubleshooting/keymaps/healthyEDIT.png) |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| A properly defined keymap with successful compilation. As shown in red, the corrected keycode (`&kp SPACE`) references the proper Usage ID defined in the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12) |
A `devicetree error` followed by a reference to the line number on `<keyboard>.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 ','
```
#### devicetree_unfixed.h error
A `devicetree_unfixed.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_unfixed.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.
:::note
Key positions are numbered starting from `0` at the top left key on the keymap, incrementing horizontally, row by row.
:::
### Split Keyboard Halves Unable to Pair