mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-02-27 01:56:43 +00:00
16 lines
15 KiB
JavaScript
16 lines
15 KiB
JavaScript
import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.DyMmIvSC.js";
|
||
const __pageData = JSON.parse('{"title":"Debugging FAQ","description":"","frontmatter":{},"headers":[],"relativePath":"faq_debug.md","filePath":"faq_debug.md"}');
|
||
const _sfc_main = { name: "faq_debug.md" };
|
||
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="debugging-faq" tabindex="-1">Debugging FAQ <a class="header-anchor" href="#debugging-faq" aria-label="Permalink to "Debugging FAQ""></a></h1><p>This page details various common questions people have about troubleshooting their keyboards.</p><h2 id="debugging" tabindex="-1">Debugging <a class="header-anchor" href="#debugging" aria-label="Permalink to "Debugging {#debugging}""></a></h2><p>Your keyboard will output debug information if you have <code>CONSOLE_ENABLE = yes</code> in your <code>rules.mk</code>. By default the output is very limited, but you can turn on debug mode to increase the amount of debug output. Use the <code>DB_TOGG</code> keycode in your keymap, use the <a href="./features/command">Command</a> feature to enable debug mode, or add the following code to your keymap.</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">void</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> keyboard_post_init_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Customise these values to desired behaviour</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> debug_enable</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> debug_matrix</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> //debug_keyboard=true;</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> //debug_mouse=true;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="debugging-tools" tabindex="-1">Debugging Tools <a class="header-anchor" href="#debugging-tools" aria-label="Permalink to "Debugging Tools""></a></h2><p>Various tools are available to debug your keyboard.</p><h3 id="debugging-with-qmk-toolbox" tabindex="-1">Debugging With QMK Toolbox <a class="header-anchor" href="#debugging-with-qmk-toolbox" aria-label="Permalink to "Debugging With QMK Toolbox""></a></h3><p>For compatible platforms, <a href="https://github.com/qmk/qmk_toolbox" target="_blank" rel="noreferrer">QMK Toolbox</a> can be used to display debug messages from your keyboard.</p><h3 id="debugging-with-qmk-cli" tabindex="-1">Debugging with QMK CLI <a class="header-anchor" href="#debugging-with-qmk-cli" aria-label="Permalink to "Debugging with QMK CLI""></a></h3><p>Prefer a terminal based solution? The <a href="./cli_commands#qmk-console">QMK CLI console command</a> can be used to display debug messages from your keyboard.</p><h3 id="debugging-with-hid-listen" tabindex="-1">Debugging With hid_listen <a class="header-anchor" href="#debugging-with-hid-listen" aria-label="Permalink to "Debugging With hid_listen""></a></h3><p>Something stand-alone? <a href="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><h2 id="debug-api" tabindex="-1">Sending Your Own Debug Messages <a class="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 <a href="./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><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#include</span><span style="--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><h2 id="debug-examples" tabindex="-1">Debug Examples <a class="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 <a href="./faq_debug">Debugging/Troubleshooting QMK</a>.</p><h3 id="which-matrix-position-is-this-keypress" tabindex="-1">Which matrix position is this keypress? <a class="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><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> process_record_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">uint16_t</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> keycode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">keyrecord_t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">record</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // If console is enabled, it will print the matrix position and status of each key pressed</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#ifdef</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> CONSOLE_ENABLE</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> uprintf</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"KL: kc: 0x</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%04X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">, col: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%2u</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">, row: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%2u</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">, pressed: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%u</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">, time: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%5u</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">, int: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%u</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">, count: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%u\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, keycode, record->event.key.col, record->event.key.row, record->event.pressed, record->event.time, record->tap.interrupted, record->tap.count);</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#endif</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Example output</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span>Waiting for device:.......</span></span>\n<span class="line"><span>Listening:</span></span>\n<span class="line"><span>KL: kc: 169, col: 0, row: 0, pressed: 1, time: 15505, int: 0, count: 0</span></span>\n<span class="line"><span>KL: kc: 169, col: 0, row: 0, pressed: 0, time: 15510, int: 0, count: 0</span></span>\n<span class="line"><span>KL: kc: 174, col: 1, row: 0, pressed: 1, time: 15703, int: 0, count: 0</span></span>\n<span class="line"><span>KL: kc: 174, col: 1, row: 0, pressed: 0, time: 15843, int: 0, count: 0</span></span>\n<span class="line"><span>KL: kc: 172, col: 2, row: 0, pressed: 1, time: 16303, int: 0, count: 0</span></span>\n<span class="line"><span>KL: kc: 172, col: 2, row: 0, pressed: 0, time: 16411, int: 0, count: 0</span></span></code></pre></div><h3 id="how-long-did-it-take-to-scan-for-a-keypress" tabindex="-1">How long did it take to scan for a keypress? <a class="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><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> DEBUG_MATRIX_SCAN_RATE</span></span></code></pre></div><p>Example output</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span> > matrix scan frequency: 315</span></span>\n<span class="line"><span> > matrix scan frequency: 313</span></span>\n<span class="line"><span> > matrix scan frequency: 316</span></span>\n<span class="line"><span> > matrix scan frequency: 316</span></span>\n<span class="line"><span> > matrix scan frequency: 316</span></span>\n<span class="line"><span> > matrix scan frequency: 316</span></span></code></pre></div><h2 id="hid-listen-can-t-recognize-device" tabindex="-1"><code>hid_listen</code> Can't Recognize Device <a class="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><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="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><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span>Waiting for new device:.........................</span></span>\n<span class="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><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="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><h2 id="can-t-get-message-on-console" tabindex="-1">Can't Get Message on Console <a class="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 <a href="https://github.com/tmk/tmk_keyboard#magic-commands" target="_blank" rel="noreferrer">Magic Commands</a>.</li><li>Set <code>debug_enable=true</code>. See <a href="#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 <a href="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>', 43);
|
||
const _hoisted_44 = [
|
||
_hoisted_1
|
||
];
|
||
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
||
return openBlock(), createElementBlock("div", null, _hoisted_44);
|
||
}
|
||
const faq_debug = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
||
export {
|
||
__pageData,
|
||
faq_debug as default
|
||
};
|