<p>When debug console of your device is not ready you will see like this:</p>
<pre><code>Waiting for device:.........
</code></pre>
<p>once the device is plugged in then <em>hid_listen</em> finds it you will get this message:</p>
<pre><code>Waiting for new device:.........................
Listening:
</code></pre>
<p>If you can't get this 'Listening:' message try building with <code>CONSOLE_ENABLE=yes</code> in [Makefile]</p>
<p>You may need privilege to access the device on OS like Linux.</p>
<ul>
<li>try <code>sudo hid_listen</code>
</li>
</ul>
<h2id="page_Can-t-Get-Message-on-Console">Can't Get Message on Console</h2>
<p>Check:</p>
<ul>
<li>
<em>hid_listen</em> finds your device. See above.</li>
<li>Enable debug with pressing <strong>Magic</strong>+d. See <ahref="https://github.com/tmk/tmk_keyboard#magic-commands"class="Link--external">Magic Commands</a>.</li>
<li>set <code>debug_enable=true</code> usually in <code>matrix_init()</code> in <strong>matrix.c</strong>.</li>
<li>try using 'print' 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"class="Link--external">Issue #97</a>.</li>
</ul>
<h2id="page_Linux-or-UNIX-Like-System-Requires-Super-User-Privilege">Linux or UNIX Like System Requires Super User Privilege</h2>
<p>Just use 'sudo' to execute <em>hid_listen</em> with privilege.</p>
<pre><code>$ sudo hid_listen
</code></pre>
<p>Or add an <em>udev rule</em> for TMK devices with placing a file in rules directory. The directory may vary on each system.</p>
<p>File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)</p>
<p>First you have to compile firmware with this build option <code>NKRO_ENABLE</code> in <strong>Makefile</strong>.</p>
<p>Try <code>Magic</code><strong>N</strong> command(<code>LShift+RShift+N</code> by default) when <strong>NKRO</strong> still doesn't work. You can use this command to toggle between <strong>NKRO</strong> and <strong>6KRO</strong> mode temporarily. In some situations <strong>NKRO</strong> doesn't work you need to switch to <strong>6KRO</strong> mode, in particular when you are in BIOS.</p>
<p>If your firmware built with <code>BOOTMAGIC_ENABLE</code> you need to turn its switch on by <code>BootMagic</code><strong>N</strong> command(<code>Space+N</code> by default). This setting is stored in EEPROM and kept over power cycles.</p>
<h2id="page_Can-t-Read-Column-of-Matrix-Beyond-16">Can't Read Column of Matrix Beyond 16</h2>
<p>Use <code>1UL<<16</code> instead of <code>1<<16</code> in <code>read_cols()</code> in [matrix.h] when your columns goes beyond 16.</p>
<p>In C <code>1</code> means one of [int] type which is [16 bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say <code>1<<16</code>. You have to use [unsigned long] type with <code>1UL</code>.</p>
<p>Properly configure bootloader size in <strong>Makefile</strong>. With wrong section size bootloader won't probably start with <strong>Magic command</strong> and <strong>Boot Magic</strong>.</p>
<pre><code># Size of Bootloaders in bytes:
# Atmel DFU loader(ATmega32U4) 4096
# Atmel DFU loader(AT90USB128) 8192
# LUFA bootloader(ATmega32U4) 4096
# Arduino Caterina(ATmega32U4) 4096
# USBaspLoader(ATmega***) 2048
# Teensy halfKay(ATmega32U4) 512
# Teensy++ halfKay(AT90USB128) 2048
OPT_DEFS += -DBOOTLOADER_SIZE=4096
</code></pre>
<p>AVR Boot section size are defined by setting <strong>BOOTSZ</strong> fuse in fact. Consult with your MCU datasheet.
Note that <strong>Word</strong>(2 bytes) size and address are used in datasheet while TMK uses <strong>Byte</strong>.</p>
<p>AVR Boot section is located at end of Flash memory like the followings.</p>
<p>If you are using a TeensyUSB, there is a <ahref="https://github.com/qmk/qmk_firmware/issues/164"class="Link--external">known bug</a> in which the hardware reset button prevents the RESET key from working. Unplugging the keyboard and plugging it back in should resolve the problem.</p>
<h2id="page_Special-Extra-Key-Doesn-t-Work-System-Audio-Control-Keys">Special Extra Key Doesn't Work (System, Audio Control Keys)</h2>
<p>You need to define <code>EXTRAKEY_ENABLE</code> in <code>rules.mk</code> to use them in QMK.</p>
<pre><code>EXTRAKEY_ENABLE = yes # Audio control and System control
</code></pre>
<h2id="page_Wakeup-from-Sleep-Doesn-t-Work">Wakeup from Sleep Doesn't Work</h2>
<p>In Windows check <code>Allow this device to wake the computer</code> setting in Power <strong>Management property</strong> tab of <strong>Device Manager</strong>. Also check BIOS setting.</p>
<p>Pressing any key during sleep should wake host.</p>
<h2id="page_Using-Arduino">Using Arduino?</h2>
<p><strong>Note that Arduino pin naming is different from actual chip.</strong> For example, Arduino pin <code>D0</code> is not <code>PD0</code>. Check circuit with its schematics yourself.</p>
<p>Arduino Leonardo and micro have <strong>ATMega32U4</strong> and can be used for TMK, though Arduino bootloader may be a problem.</p>
<h2id="page_Using-PF4-7-Pins-of-USB-AVR">Using PF4-7 Pins of USB AVR?</h2>
<p>You need to set JTD bit of MCUCR yourself to use PF4-7 as GPIO. Those pins are configured to serve JTAG function by default. MCUs like ATMega<em>U</em> or AT90USB* are affected with this.</p>
<p>If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.</p>
<p>See this code.</p>
<pre><code> // JTAG disable for PORT F. write JTD bit twice within four cycles.
<h2id="page_Problem-on-BIOS-UEFI-Resume-Sleep-Wake-Power-Cycles">Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles</h2>
<p>Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).</p>
<p>As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like <code>CONSOLE_ENABLE</code>, <code>NKRO_ENABLE</code>, <code>SLEEP_LED_ENABLE</code> and/or others.</p>
