e6c638be |
1 | # Debugging FAQ |
2 | |
3 | This page details various common questions people have about troubleshooting their keyboards. |
4 | |
5 | # Debug Console |
6 | |
7b0356d1 |
7 | ## `hid_listen` Can't Recognize Device |
e6c638be |
8 | When debug console of your device is not ready you will see like this: |
9 | |
10 | ``` |
11 | Waiting for device:......... |
12 | ``` |
13 | |
af37bb2f |
14 | once the device is plugged in then *hid_listen* finds it you will get this message: |
e6c638be |
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 | |
7b0356d1 |
26 | ## Can't Get Message on Console |
e6c638be |
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 | |
7b0356d1 |
34 | ## Linux or UNIX Like System Requires Super User Privilege |
e6c638be |
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 |
9d1a08e3 |
51 | ## Safety Considerations |
52 | |
53 | You probably don't want to "brick" your keyboard, making it impossible |
54 | to rewrite firmware onto it. Here are some of the parameters to show |
55 | what things are (and likely aren't) too risky. |
56 | |
57 | - If your keyboard map does not include RESET, then, to get into DFU |
58 | mode, you will need to press the reset button on the PCB, which |
59 | requires unscrewing the bottom. |
60 | - Messing with tmk_core / common files might make the keyboard |
61 | inoperable |
62 | - Too large a .hex file is trouble; `make dfu` will erase the block, |
63 | test the size (oops, wrong order!), which errors out, failing to |
64 | flash the keyboard, leaving it in DFU mode. |
65 | - To this end, note that the maximum .hex file size on Planck is |
66 | 7000h (28672 decimal) |
67 | |
68 | ``` |
69 | Linking: .build/planck_rev4_cbbrowne.elf [OK] |
70 | Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK] |
71 | |
72 | Size after: |
73 | text data bss dec hex filename |
74 | 0 22396 0 22396 577c planck_rev4_cbbrowne.hex |
75 | ``` |
76 | |
77 | - The above file is of size 22396/577ch, which is less than |
78 | 28672/7000h |
79 | - As long as you have a suitable alternative .hex file around, you |
80 | can retry, loading that one |
81 | - Some of the options you might specify in your keyboard's Makefile |
82 | consume extra memory; watch out for BOOTMAGIC_ENABLE, |
83 | MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE |
84 | - DFU tools do /not/ allow you to write into the bootloader (unless |
af37bb2f |
85 | you throw in extra fruit salad of options), so there is little risk |
9d1a08e3 |
86 | there. |
87 | - EEPROM has around a 100000 write cycle. You shouldn't rewrite the |
88 | firmware repeatedly and continually; that'll burn the EEPROM |
89 | eventually. |
42112521 |
90 | |
e6c638be |
91 | ## NKRO Doesn't work |
af37bb2f |
92 | First you have to compile firmware with this build option `NKRO_ENABLE` in **Makefile**. |
e6c638be |
93 | |
94 | 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. |
95 | |
af37bb2f |
96 | If your firmware 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 kept over power cycles. |
e6c638be |
97 | |
98 | https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch |
99 | |
100 | |
7b0356d1 |
101 | ## TrackPoint Needs Reset Circuit (PS/2 Mouse Support) |
af37bb2f |
102 | Without reset circuit you will have inconsistent result due to improper initialize of the hardware. See circuit schematic of TPM754. |
e6c638be |
103 | |
104 | - http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447 |
105 | - http://www.mikrocontroller.net/attachment/52583/tpm754.pdf |
106 | |
107 | |
7b0356d1 |
108 | ## Can't Read Column of Matrix Beyond 16 |
e6c638be |
109 | Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16. |
110 | |
af37bb2f |
111 | In C `1` 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 `1<<16`. You have to use [unsigned long] type with `1UL`. |
e6c638be |
112 | |
113 | http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 |
114 | |
115 | |
7b0356d1 |
116 | ## Bootloader Jump Doesn't Work |
e6c638be |
117 | Properly configure bootloader size in **Makefile**. With wrong section size bootloader won't probably start with **Magic command** and **Boot Magic**. |
118 | ``` |
119 | # Size of Bootloaders in bytes: |
bb53635f |
120 | # Atmel DFU loader(ATmega32U4) 4096 |
121 | # Atmel DFU loader(AT90USB128) 8192 |
122 | # LUFA bootloader(ATmega32U4) 4096 |
123 | # Arduino Caterina(ATmega32U4) 4096 |
124 | # USBaspLoader(ATmega***) 2048 |
125 | # Teensy halfKay(ATmega32U4) 512 |
e6c638be |
126 | # Teensy++ halfKay(AT90USB128) 2048 |
127 | OPT_DEFS += -DBOOTLOADER_SIZE=4096 |
128 | ``` |
129 | AVR Boot section size are defined by setting **BOOTSZ** fuse in fact. Consult with your MCU datasheet. |
130 | Note that **Word**(2 bytes) size and address are used in datasheet while TMK uses **Byte**. |
131 | |
132 | AVR Boot section is located at end of Flash memory like the followings. |
133 | ``` |
134 | byte Atmel/LUFA(ATMega32u4) byte Atmel(AT90SUB1286) |
135 | 0x0000 +---------------+ 0x00000 +---------------+ |
136 | | | | | |
137 | | | | | |
138 | | Application | | Application | |
bb53635f |
139 | | | | | |
e6c638be |
140 | = = = = |
141 | | | 32KB-4KB | | 128KB-8KB |
142 | 0x6000 +---------------+ 0x1E000 +---------------+ |
143 | | Bootloader | 4KB | Bootloader | 8KB |
144 | 0x7FFF +---------------+ 0x1FFFF +---------------+ |
145 | |
bb53635f |
146 | |
e6c638be |
147 | byte Teensy(ATMega32u4) byte Teensy++(AT90SUB1286) |
148 | 0x0000 +---------------+ 0x00000 +---------------+ |
149 | | | | | |
150 | | | | | |
151 | | Application | | Application | |
152 | | | | | |
153 | = = = = |
154 | | | 32KB-512B | | 128KB-2KB |
155 | 0x7E00 +---------------+ 0x1FC00 +---------------+ |
156 | | Bootloader | 512B | Bootloader | 2KB |
157 | 0x7FFF +---------------+ 0x1FFFF +---------------+ |
158 | ``` |
159 | |
160 | And see this discussion for further reference. |
161 | https://github.com/tmk/tmk_keyboard/issues/179 |
162 | |
392121b1 |
163 | If you are using a TeensyUSB, there is a [known bug](https://github.com/qmk/qmk_firmware/issues/164) in which the hardware reset button prevents the RESET key from working. Unplugging the keyboard and plugging it back in should resolve the problem. |
e6c638be |
164 | |
7b0356d1 |
165 | ## Special Extra Key Doesn't Work (System, Audio Control Keys) |
e6c638be |
166 | You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK. |
167 | |
168 | ``` |
169 | EXTRAKEY_ENABLE = yes # Audio control and System control |
170 | ``` |
171 | |
7b0356d1 |
172 | ## Wakeup from Sleep Doesn't Work |
e6c638be |
173 | |
174 | In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting. |
175 | |
176 | Pressing any key during sleep should wake host. |
177 | |
178 | ## Using Arduino? |
179 | |
180 | **Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself. |
181 | |
182 | - http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf |
183 | - http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf |
184 | |
af37bb2f |
185 | Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem. |
e6c638be |
186 | |
f2c179de |
187 | ## Enabling JTAG |
e6c638be |
188 | |
f2c179de |
189 | By default, the JTAG debugging interface is disabled as soon as the keyboard starts up. JTAG-capable MCUs come from the factory with the `JTAGEN` fuse set, and it takes over certain pins of the MCU that the board may be using for the switch matrix, LEDs, etc. |
e6c638be |
190 | |
f2c179de |
191 | If you would like to keep JTAG enabled, just add the following to your `config.h`: |
e6c638be |
192 | |
f2c179de |
193 | ```c |
194 | #define NO_JTAG_DISABLE |
e6c638be |
195 | ``` |
e6c638be |
196 | |
7b0356d1 |
197 | ## Adding LED Indicators of Lock Keys |
e6c638be |
198 | You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post. |
199 | |
200 | http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560 |
201 | |
202 | ## Program Arduino Micro/Leonardo |
203 | Push reset button and then run command like this within 8 seconds. |
204 | |
205 | ``` |
206 | avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0 |
207 | ``` |
208 | |
209 | Device name will vary depending on your system. |
210 | |
211 | http://arduino.cc/en/Main/ArduinoBoardMicro |
212 | https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867 |
213 | |
214 | |
7b0356d1 |
215 | ## USB 3 Compatibility |
e6c638be |
216 | I heard some people have a problem with USB 3 port, try USB 2 port. |
217 | |
218 | |
7b0356d1 |
219 | ## Mac Compatibility |
e6c638be |
220 | ### OS X 10.11 and Hub |
221 | https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034 |
222 | |
223 | |
7b0356d1 |
224 | ## Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles |
e6c638be |
225 | Some people reported their keyboard stops working on BIOS and/or after resume(power cycles). |
226 | |
bb53635f |
227 | 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. |
e6c638be |
228 | |
229 | https://github.com/tmk/tmk_keyboard/issues/266 |
230 | https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 |
231 | |
232 | |
233 | |
7b0356d1 |
234 | ## FLIP Doesn't Work |
235 | ### `AtLibUsbDfu.dll` Not Found |
e6c638be |
236 | Remove current driver and reinstall one FLIP provides from DeviceManager. |
237 | http://imgur.com/a/bnwzy |