aboutsummaryrefslogtreecommitdiff
path: root/docs/newbs_testing_debugging.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/newbs_testing_debugging.md')
-rw-r--r--docs/newbs_testing_debugging.md91
1 files changed, 2 insertions, 89 deletions
diff --git a/docs/newbs_testing_debugging.md b/docs/newbs_testing_debugging.md
index 834fed716..c3550489e 100644
--- a/docs/newbs_testing_debugging.md
+++ b/docs/newbs_testing_debugging.md
@@ -1,96 +1,9 @@
1# Testing and Debugging 1# Testing and Debugging
2 2
3Once you've flashed your keyboard with a custom firmware you're ready to test it out. With a little bit of luck everything will work perfectly, but if not this document will help you figure out what's wrong.
4
5## Testing 3## Testing
6 4
7Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. You can use [QMK Configurator](https://config.qmk.fm/#/test/)'s test mode to check your keyboard, even if it doesn't run QMK. 5[Moved here](faq_misc.md#testing)
8 6
9## Debugging :id=debugging 7## Debugging :id=debugging
10 8
11Your keyboard will output debug information if you have `CONSOLE_ENABLE = yes` in your `rules.mk`. By default the output is very limited, but you can turn on debug mode to increase the amount of debug output. Use the `DEBUG` keycode in your keymap, use the [Command](feature_command.md) feature to enable debug mode, or add the following code to your keymap. 9[Moved here](faq_debug.md#debugging)
12
13```c
14void keyboard_post_init_user(void) {
15 // Customise these values to desired behaviour
16 debug_enable=true;
17 debug_matrix=true;
18 //debug_keyboard=true;
19 //debug_mouse=true;
20}
21```
22
23## Debugging Tools
24
25There are two different tools you can use to debug your keyboard.
26
27### Debugging With QMK Toolbox
28
29For compatible platforms, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) can be used to display debug messages from your keyboard.
30
31### Debugging With hid_listen
32
33Prefer a terminal based solution? [hid_listen](https://www.pjrc.com/teensy/hid_listen.html), provided by PJRC, can also be used to display debug messages. Prebuilt binaries for Windows,Linux,and MacOS are available.
34
35## Sending Your Own Debug Messages
36
37Sometimes it's useful to print debug messages from within your [custom code](custom_quantum_functions.md). Doing so is pretty simple. Start by including `print.h` at the top of your file:
38
39```c
40#include "print.h"
41```
42
43After that you can use a few different print functions:
44
45* `print("string")`: Print a simple string.
46* `uprintf("%s string", var)`: Print a formatted string
47* `dprint("string")` Print a simple string, but only when debug mode is enabled
48* `dprintf("%s string", var)`: Print a formatted string, but only when debug mode is enabled
49
50## Debug Examples
51
52Below is a collection of real world debugging examples. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug.md).
53
54### Which matrix position is this keypress?
55
56When porting, or when attempting to diagnose pcb issues, it can be useful to know if a keypress is scanned correctly. To enable logging for this scenario, add the following code to your keymaps `keymap.c`
57
58```c
59bool process_record_user(uint16_t keycode, keyrecord_t *record) {
60 // If console is enabled, it will print the matrix position and status of each key pressed
61#ifdef CONSOLE_ENABLE
62 uprintf("KL: kc: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed);
63#endif
64 return true;
65}
66```
67
68Example output
69```text
70Waiting for device:.......
71Listening:
72KL: kc: 169, col: 0, row: 0, pressed: 1
73KL: kc: 169, col: 0, row: 0, pressed: 0
74KL: kc: 174, col: 1, row: 0, pressed: 1
75KL: kc: 174, col: 1, row: 0, pressed: 0
76KL: kc: 172, col: 2, row: 0, pressed: 1
77KL: kc: 172, col: 2, row: 0, pressed: 0
78```
79
80### How long did it take to scan for a keypress?
81
82When testing performance issues, it can be useful to know the frequency at which the switch matrix is being scanned. To enable logging for this scenario, add the following code to your keymaps `config.h`
83
84```c
85#define DEBUG_MATRIX_SCAN_RATE
86```
87
88Example output
89```text
90 > matrix scan frequency: 315
91 > matrix scan frequency: 313
92 > matrix scan frequency: 316
93 > matrix scan frequency: 316
94 > matrix scan frequency: 316
95 > matrix scan frequency: 316
96```