docs/newbs_testing_debugging.md

   1 # Testing and Debugging
   2
   3 Once 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
   6
   7 Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. There are even programs that will help you make sure that no key is missed.
   8
   9 Note: These programs are not provided by or endorsed by QMK.
  10
  11 * [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (Windows Only)
  12 * [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Mac Only)
  13 * [Keyboard Tester](http://www.keyboardtester.com) (Web Based)
  14 * [Keyboard Checker](http://keyboardchecker.com) (Web Based)
  15
  16 ## Debugging
  17
  18 Your 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.
  19
  20 ```c
  21 void keyboard_post_init_user(void) {
  22   // Customise these values to desired behaviour
  23   debug_enable=true;
  24   debug_matrix=true;
  25   //debug_keyboard=true;
  26   //debug_mouse=true;
  27 }
  28 ```
  29
  30 ### Debugging With QMK Toolbox
  31
  32 For compatible platforms, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) can be used to display debug messages from your keyboard.
  33
  34 ### Debugging With hid_listen
  35
  36 Prefer 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.
  37
  38 <!-- FIXME: Describe the debugging messages here. -->
  39
  40 ## Sending Your Own Debug Messages
  41
  42 Sometimes 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:
  43
  44     #include <print.h>
  45
  46 After that you can use a few different print functions:
  47
  48 * `print("string")`: Print a simple string.
  49 * `uprintf("%s string", var)`: Print a formatted string
  50 * `dprint("string")` Print a simple string, but only when debug mode is enabled
  51 * `dprintf("%s string", var)`: Print a formatted string, but only when debug mode is enabled
  52
  53 ## Debug Examples
  54
  55 Below is a collection of real world debugging examples. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug.md).
  56
  57 ### Which matrix position is this keypress?
  58
  59 When 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`
  60
  61 ```c
  62 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
  63   // If console is enabled, it will print the matrix position and status of each key pressed
  64 #ifdef CONSOLE_ENABLE
  65     uprintf("KL: kc: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed);
  66 #endif
  67   return true;
  68 }
  69 ```
  70
  71 Example output
  72 ```text
  73 Waiting for device:.......
  74 Listening:
  75 KL: kc: 169, col: 0, row: 0, pressed: 1
  76 KL: kc: 169, col: 0, row: 0, pressed: 0
  77 KL: kc: 174, col: 1, row: 0, pressed: 1
  78 KL: kc: 174, col: 1, row: 0, pressed: 0
  79 KL: kc: 172, col: 2, row: 0, pressed: 1
  80 KL: kc: 172, col: 2, row: 0, pressed: 0
  81 ```
  82
  83 ### How long did it take to scan for a keypress?
  84
  85 When 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`
  86
  87 ```c
  88 #define DEBUG_MATRIX_SCAN_RATE
  89 ```
  90
  91 Example output
  92 ```text
  93   > matrix scan frequency: 315
  94   > matrix scan frequency: 313
  95   > matrix scan frequency: 316
  96   > matrix scan frequency: 316
  97   > matrix scan frequency: 316
  98   > matrix scan frequency: 316
  99 ```