<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2id="debugging-tools"tabindex="-1">Debugging Tools <aclass="header-anchor"href="#debugging-tools"aria-label="Permalink to "Debugging Tools""></a></h2><p>Various tools are available to debug your keyboard.</p><h3id="debugging-with-qmk-toolbox"tabindex="-1">Debugging With QMK Toolbox <aclass="header-anchor"href="#debugging-with-qmk-toolbox"aria-label="Permalink to "Debugging With QMK Toolbox""></a></h3><p>For compatible platforms, <ahref="https://github.com/qmk/qmk_toolbox"target="_blank"rel="noreferrer">QMK Toolbox</a> can be used to display debug messages from your keyboard.</p><h3id="debugging-with-qmk-cli"tabindex="-1">Debugging with QMK CLI <aclass="header-anchor"href="#debugging-with-qmk-cli"aria-label="Permalink to "Debugging with QMK CLI""></a></h3><p>Prefer a terminal based solution? The <ahref="./cli_commands#qmk-console">QMK CLI console command</a> can be used to display debug messages from your keyboard.</p><h3id="debugging-with-hid-listen"tabindex="-1">Debugging With hid_listen <aclass="header-anchor"href="#debugging-with-hid-listen"aria-label="Permalink to "Debugging With hid_listen""></a></h3><p>Something stand-alone? <ahref="https://www.pjrc.com/teensy/hid_listen.html"target="_blank"rel="noreferrer">hid_listen</a>, provided by PJRC, can also be used to display debug messages. Prebuilt binaries for Windows,Linux,and MacOS are available.</p><h2id="debug-api"tabindex="-1">Sending Your Own Debug Messages <aclass="header-anchor"href="#debug-api"aria-label="Permalink to "Sending Your Own Debug Messages {#debug-api}""></a></h2><p>Sometimes it's useful to print debug messages from within your <ahref="./custom_quantum_functions">custom code</a>. Doing so is pretty simple. Start by including <code>print.h</code> at the top of your file:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#include</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"print.h"</span></span></code></pre></div><p>After that you can use a few different print functions:</p><ul><li><code>print("string")</code>: Print a simple string.</li><li><code>uprintf("%s string", var)</code>: Print a formatted string</li><li><code>dprint("string")</code> Print a simple string, but only when debug mode is enabled</li><li><code>dprintf("%s string", var)</code>: Print a formatted string, but only when debug mode is enabled</li></ul><h2id="debug-examples"tabindex="-1">Debug Examples <aclass="header-anchor"href="#debug-examples"aria-label="Permalink to "Debug Examples""></a></h2><p>Below is a collection of real world debugging examples. For additional information, refer to <ahref="./faq_debug">Debugging/Troubleshooting QMK</a>.</p><h3id="which-matrix-position-is-this-keypress"tabindex="-1">Which matrix position is this keypress? <aclass="header-anchor"href="#which-matrix-position-is-this-keypress"aria-label="Permalink to "Which matrix position is this keypress?""></a></h3><p>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 <code>keymap.c</code></p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> process_record_user</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // If console is enabled, it will print the matrix position and status of each key pressed</span></span>
<spanclass="line"><span>KL: kc: 172, col: 2, row: 0, pressed: 0, time: 16411, int: 0, count: 0</span></span></code></pre></div><h3id="how-long-did-it-take-to-scan-for-a-keypress"tabindex="-1">How long did it take to scan for a keypress? <aclass="header-anchor"href="#how-long-did-it-take-to-scan-for-a-keypress"aria-label="Permalink to "How long did it take to scan for a keypress?""></a></h3><p>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 <code>config.h</code></p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> DEBUG_MATRIX_SCAN_RATE</span></span></code></pre></div><p>Example output</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>> matrix scan frequency: 315</span></span>
<spanclass="line"><span>> matrix scan frequency: 316</span></span></code></pre></div><h2id="hid-listen-can-t-recognize-device"tabindex="-1"><code>hid_listen</code> Can't Recognize Device <aclass="header-anchor"href="#hid-listen-can-t-recognize-device"aria-label="Permalink to "`hid_listen` Can't Recognize Device""></a></h2><p>When debug console of your device is not ready you will see like this:</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>Waiting for device:.........</span></span></code></pre></div><p>Once the device is plugged in then <em>hid_listen</em> finds it you will get this message:</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>Waiting for new device:.........................</span></span>
<spanclass="line"><span>Listening:</span></span></code></pre></div><p>If you can't get this 'Listening:' message try building with <code>CONSOLE_ENABLE=yes</code> in [Makefile]</p><p>You may need privileges to access the device an OS like Linux. Try <code>sudo hid_listen</code>.</p><p>On many Linux distros you can avoid having to run hid_listen as root by creating a file called <code>/etc/udev/rules.d/70-hid-listen.rules</code> with the following content:</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>SUBSYSTEM=="hidraw", ATTRS{idVendor}=="abcd", ATTRS{idProduct}=="def1", TAG+="uaccess", RUN{builtin}+="uaccess"</span></span></code></pre></div><p>Replace abcd and def1 with your keyboard's vendor and product id, letters must be lowercase. The <code>RUN{builtin}+="uaccess"</code> part is only needed for older distros.</p><h2id="can-t-get-message-on-console"tabindex="-1">Can't Get Message on Console <aclass="header-anchor"href="#can-t-get-message-on-console"aria-label="Permalink to "Can't Get Message on Console""></a></h2><p>Check:</p><ul><li><em>hid_listen</em> finds your device. See above.</li><li>Enable debug by pressing <strong>Magic</strong>+d. See <ahref="https://github.com/tmk/tmk_keyboard#magic-commands"target="_blank"rel="noreferrer">Magic Commands</a>.</li><li>Set <code>debug_enable=true</code>. See <ahref="#debugging">Debugging</a></li><li>Try using <code>print</code> function instead of debug print. See <strong>common/print.h</strong>.</li><li>Disconnect other devices with console function. See <ahref="https://github.com/tmk/tmk_keyboard/issues/97"target="_blank"rel="noreferrer">Issue #97</a>.</li><li>Ensure all strings end with a newline character (<code>\n</code>). QMK Toolbox prints console output on a per-line basis.</li></ul></div></div></main><footerclass="VPDocFooter"data-v-39a288b8data-v-09de1c0f><!--[--><!--]--><!----><navclass="prev-next"data-v-09de1c0f><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link prev"href="/faq_misc"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Previous page</span><spanclass="title"data-v-09de1c0f>Troubleshooting QMK</span><!--]--></a></div><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link next"href="/faq_keymap"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Next page</span><spanclass="title"data-v-09de1c0f>Keymap FAQ</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
