docs/faq_debug.md

   1 # Debugging FAQ
   2
   3 This page details various common questions people have about troubleshooting their keyboards.
   4
   5 # Debug Console
   6
   7 ## hid_listen can't recognize device
   8 When debug console of your device is not ready you will see like this:
   9
  10 ```
  11 Waiting for device:.........
  12 ```
  13
  14 once the device is pluged in then *hid_listen* finds it you will get this message:
  15
  16 ```
  17 Waiting for new device:.........................
  18 Listening:
  19 ```
  20
  21 If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes` in [Makefile]
  22
  23 You may need privilege to access the device on OS like Linux.
  24 - try `sudo hid_listen`
  25
  26 ## Can't get message on console
  27 Check:
  28 - *hid_listen* finds your device. See above.
  29 - Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
  30 - set `debug_enable=true` usually in `matrix_init()` in **matrix.c**.
  31 - try using 'print' function instead of debug print. See **common/print.h**.
  32 - disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
  33
  34 ## Linux or UNIX like system requires Super User privilege
  35 Just use 'sudo' to execute *hid_listen* with privilege.
  36 ```
  37 $ sudo hid_listen
  38 ```
  39
  40 Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system.
  41
  42 File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)
  43 ```
  44 # tmk keyboard products     https://github.com/tmk/tmk_keyboard
  45 SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
  46 ```
  47
  48 ***
  49
  50 # Miscellaneous
  51 ## NKRO Doesn't work
  52 First you have to compile frimware with this build option `NKRO_ENABLE` in **Makefile**.
  53
  54 Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work you need to switch to **6KRO** mode, in particular when you are in BIOS.
  55
  56 If your firmeare built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and keeped over power cycles.
  57
  58 https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
  59
  60
  61 ## TrackPoint needs reset circuit(PS/2 mouse support)
  62 Without reset circuit you will have inconsistent reuslt due to improper initialize of the hardware. See circuit schematic of TPM754.
  63
  64 - http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
  65 - http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
  66
  67
  68 ## Can't read column of matrix beyond 16
  69 Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
  70
  71 In C `1` means one of [int] type which is [16bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say `1<<16`. You have to use [unsigned long] type with `1UL`.
  72
  73 http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
  74
  75
  76 ## Bootloader jump doesn't work
  77 Properly configure bootloader size in **Makefile**. With wrong section size bootloader won't probably start with **Magic command** and **Boot Magic**.
  78 ```
  79 # Size of Bootloaders in bytes:
  80 #   Atmel DFU loader(ATmega32U4)   4096
  81 #   Atmel DFU loader(AT90USB128)   8192
  82 #   LUFA bootloader(ATmega32U4)    4096
  83 #   Arduino Caterina(ATmega32U4)   4096
  84 #   USBaspLoader(ATmega***)        2048
  85 #   Teensy   halfKay(ATmega32U4)   512
  86 #   Teensy++ halfKay(AT90USB128)   2048
  87 OPT_DEFS += -DBOOTLOADER_SIZE=4096
  88 ```
  89 AVR Boot section size are defined by setting **BOOTSZ** fuse in fact. Consult with your MCU datasheet.
  90 Note that **Word**(2 bytes) size and address are used in datasheet while TMK uses **Byte**.
  91
  92 AVR Boot section is located at end of Flash memory like the followings.
  93 ```
  94 byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
  95 0x0000   +---------------+               0x00000  +---------------+
  96          |               |                        |               |
  97          |               |                        |               |
  98          |  Application  |                        |  Application  |
  99          |               |                        |               |
 100          =               =                        =               =
 101          |               | 32KB-4KB               |               | 128KB-8KB
 102 0x6000   +---------------+               0x1E000  +---------------+
 103          |  Bootloader   | 4KB                    |  Bootloader   | 8KB
 104 0x7FFF   +---------------+               0x1FFFF  +---------------+
 105
 106
 107 byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
 108 0x0000   +---------------+               0x00000  +---------------+
 109          |               |                        |               |
 110          |               |                        |               |
 111          |  Application  |                        |  Application  |
 112          |               |                        |               |
 113          =               =                        =               =
 114          |               | 32KB-512B              |               | 128KB-2KB
 115 0x7E00   +---------------+               0x1FC00  +---------------+
 116          |  Bootloader   | 512B                   |  Bootloader   | 2KB
 117 0x7FFF   +---------------+               0x1FFFF  +---------------+
 118 ```
 119
 120 And see this discussion for further reference.
 121 https://github.com/tmk/tmk_keyboard/issues/179
 122
 123
 124 ## Special Extra key doesn't work(System, Audio control keys)
 125 You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
 126
 127 ```
 128 EXTRAKEY_ENABLE = yes          # Audio control and System control
 129 ```
 130
 131 ## Wakeup from sleep doesn't work
 132
 133 In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.
 134
 135 Pressing any key during sleep should wake host.
 136
 137 ## Using Arduino?
 138
 139 **Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
 140
 141 - http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
 142 - http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
 143
 144 Arduino leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
 145
 146
 147 ## Using PF4-7 pins of USB AVR?
 148 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*U* or AT90USB* are affeteced with this.
 149
 150 If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.
 151
 152 See this code.
 153 ```
 154     // JTAG disable for PORT F. write JTD bit twice within four cycles.
 155     MCUCR |= (1<<JTD);
 156     MCUCR |= (1<<JTD);
 157 ```
 158 https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hbkb/matrix.c#L67
 159
 160 And read **26.5.1 MCU Control Register – MCUCR** of ATMega32U4 datasheet.
 161
 162
 163 ## Adding LED indicators of Lock keys
 164 You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post.
 165
 166 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
 167
 168 ## Program Arduino Micro/Leonardo
 169 Push reset button and then run command like this within 8 seconds.
 170
 171 ```
 172 avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
 173 ```
 174
 175 Device name will vary depending on your system.
 176
 177 http://arduino.cc/en/Main/ArduinoBoardMicro
 178 https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
 179
 180
 181 ## USB 3 compatibility
 182 I heard some people have a problem with USB 3 port, try USB 2 port.
 183
 184
 185 ## Mac compatibility
 186 ### OS X 10.11 and Hub
 187 https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
 188
 189
 190 ## Problem on BIOS(UEFI)/Resume(Sleep&Wake)/Power cycles
 191 Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).
 192
 193 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 `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
 194
 195 https://github.com/tmk/tmk_keyboard/issues/266
 196 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
 197
 198
 199
 200 ## FLIP doesn't work
 201 ### AtLibUsbDfu.dll not found
 202 Remove current driver and reinstall one FLIP provides from DeviceManager.
 203 http://imgur.com/a/bnwzy