Merge pull request #165 from kurtis-lew/troubleshooting

Troubleshooting - Revised Copy of PR 150

6 files changed, 39 insertions, 1 deletions

diff --git a/docs/docs/assets/troubleshooting/keymaps/errorscreen.png b/docs/docs/assets/troubleshooting/keymaps/errorscreen.png
new file mode 100644
index 0000000000..73b5b58487
--- /dev/null
+++ b/docs/docs/assets/troubleshooting/keymaps/errorscreen.png
diff --git a/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png b/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png
new file mode 100644
index 0000000000..50d2c73669
--- /dev/null
+++ b/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png
diff --git a/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png b/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png
new file mode 100644
index 0000000000..3fd8dc70fb
--- /dev/null
+++ b/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png
diff --git a/docs/docs/behavior/key-press.md b/docs/docs/behavior/key-press.md
index f58225d76f..d427f9d2c9 100644
--- a/docs/docs/behavior/key-press.md
+++ b/docs/docs/behavior/key-press.md
@@ -27,6 +27,11 @@ There is an [open issue](https://github.com/zmkfirmware/zmk/issues/21) to provid
 complete set of defines for the full keypad and consumer usage pages in the future for ZMK.
 :::
 
+### 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###Improperly-defined-keymap)
+
 ## Keypad Key Press
 
 The "keypad key press" behavior sends standard keypad keycodes on press/release.
@@ -59,4 +64,4 @@ Example:
 
 ```
 &cp M_PREV
-```
+```
\ No newline at end of file
diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md
new file mode 100644
index 0000000000..cd8bfd642e
--- /dev/null
+++ b/docs/docs/troubleshooting.md
@@ -0,0 +1,32 @@
+---
+id: troubleshooting
+title: Troubleshooting
+sidebar_title: 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](https://zmkfirmware.dev/community/discord/invite).
+
+### 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, click [here](../docs/dev-setup#environment-variables).
+
+### 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](../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).
+
+|       ![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"         |
+
+|  ![Healthy Keymap Temp](../docs/assets/troubleshooting/keymaps/healthyEDIT.png)  |
+| :-------------------------------------------------------------------------------: |
+|  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](https://www.usb.org/document-library/hid-usage-tables-12)|
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 7df5e12af8..6bd3aa40e8 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -7,6 +7,7 @@ module.exports = {
       "user-setup",
       "customization",
       "bond-reset",
+      "troubleshooting"
     ],
     Features: [
       "feature/keymaps",