[jackhill/qmk/firmware.git] / docs / faq_debug.md

# Debugging FAQ

This page details various common questions people have about troubleshooting their keyboards.

# Debug Console

## `hid_listen` Can't Recognize Device
When debug console of your device is not ready you will see like this:

```
Waiting for device:.........
```

once the device is plugged in then *hid_listen* finds it you will get this message:

```
Waiting for new device:.........................
Listening:
```

If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes` in [Makefile]

You may need privilege to access the device on OS like Linux.
- try `sudo hid_listen`

## Can't Get Message on Console
Check:
- *hid_listen* finds your device. See above.
- Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
- set `debug_enable=true` usually in `matrix_init()` in **matrix.c**.
- try using 'print' function instead of debug print. See **common/print.h**.
- disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).

## Linux or UNIX Like System Requires Super User Privilege
Just use 'sudo' to execute *hid_listen* with privilege.
```
$ sudo hid_listen
```

Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system.

File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)
```
# tmk keyboard products     https://github.com/tmk/tmk_keyboard
SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
```

***

# Miscellaneous
## Safety Considerations

You probably don't want to "brick" your keyboard, making it impossible
to rewrite firmware onto it.  Here are some of the parameters to show
what things are (and likely aren't) too risky.

- If your keyboard map does not include RESET, then, to get into DFU
  mode, you will need to press the reset button on the PCB, which
  requires unscrewing the bottom.
- Messing with tmk_core / common files might make the keyboard
  inoperable
- Too large a .hex file is trouble; `make dfu` will erase the block,
  test the size (oops, wrong order!), which errors out, failing to
  flash the keyboard, leaving it in DFU mode.
  - To this end, note that the maximum .hex file size on Planck is
    7000h (28672 decimal)

```
Linking: .build/planck_rev4_cbbrowne.elf                                                            [OK]
Creating load file for Flash: .build/planck_rev4_cbbrowne.hex                                       [OK]

Size after:
   text    data     bss     dec     hex filename
      0   22396       0   22396    577c planck_rev4_cbbrowne.hex
```

  - The above file is of size 22396/577ch, which is less than
    28672/7000h
  - As long as you have a suitable alternative .hex file around, you
    can retry, loading that one
  - Some of the options you might specify in your keyboard's Makefile
    consume extra memory; watch out for BOOTMAGIC_ENABLE,
    MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
- DFU tools do /not/ allow you to write into the bootloader (unless
  you throw in extra fruit salad of options), so there is little risk
  there.
- EEPROM has around a 100000 write cycle.  You shouldn't rewrite the
  firmware repeatedly and continually; that'll burn the EEPROM
  eventually.
## NKRO Doesn't work
First you have to compile firmware with this build option `NKRO_ENABLE` in **Makefile**.

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.

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.

https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch


## TrackPoint Needs Reset Circuit (PS/2 Mouse Support)
Without reset circuit you will have inconsistent result due to improper initialize of the hardware. See circuit schematic of TPM754.

- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf


## Can't Read Column of Matrix Beyond 16
Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.

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`.

http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279


## Bootloader Jump Doesn't Work
Properly configure bootloader size in **Makefile**. With wrong section size bootloader won't probably start with **Magic command** and **Boot Magic**.
```
# 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
```
AVR Boot section size are defined by setting **BOOTSZ** fuse in fact. Consult with your MCU datasheet.
Note that **Word**(2 bytes) size and address are used in datasheet while TMK uses **Byte**.

AVR Boot section is located at end of Flash memory like the followings.
```
byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
0x0000   +---------------+               0x00000  +---------------+
         |               |                        |               |
         |               |                        |               |
         |  Application  |                        |  Application  |
         |               |                        |               |
         =               =                        =               =
         |               | 32KB-4KB               |               | 128KB-8KB
0x6000   +---------------+               0x1E000  +---------------+
         |  Bootloader   | 4KB                    |  Bootloader   | 8KB
0x7FFF   +---------------+               0x1FFFF  +---------------+


byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
0x0000   +---------------+               0x00000  +---------------+
         |               |                        |               |
         |               |                        |               |
         |  Application  |                        |  Application  |
         |               |                        |               |
         =               =                        =               =
         |               | 32KB-512B              |               | 128KB-2KB
0x7E00   +---------------+               0x1FC00  +---------------+
         |  Bootloader   | 512B                   |  Bootloader   | 2KB
0x7FFF   +---------------+               0x1FFFF  +---------------+
```

And see this discussion for further reference.
https://github.com/tmk/tmk_keyboard/issues/179

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.

## Special Extra Key Doesn't Work (System, Audio Control Keys)
You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.

```
EXTRAKEY_ENABLE = yes          # Audio control and System control
```

## Wakeup from Sleep Doesn't Work

In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.

Pressing any key during sleep should wake host.

## Using Arduino?

**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.

- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf

Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.


## Using PF4-7 Pins of USB AVR?
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 affected with this.

If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.

See this code.
```
    // JTAG disable for PORT F. write JTD bit twice within four cycles.
    MCUCR |= (1<<JTD);
    MCUCR |= (1<<JTD);
```
https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hbkb/matrix.c#L67

And read **26.5.1 MCU Control Register – MCUCR** of ATMega32U4 datasheet.


## Adding LED Indicators of Lock Keys
You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post.

http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560

## Program Arduino Micro/Leonardo
Push reset button and then run command like this within 8 seconds.

```
avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
```

Device name will vary depending on your system.

http://arduino.cc/en/Main/ArduinoBoardMicro
https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867


## USB 3 Compatibility
I heard some people have a problem with USB 3 port, try USB 2 port.


## Mac Compatibility
### OS X 10.11 and Hub
https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034


## Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles
Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).

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.

https://github.com/tmk/tmk_keyboard/issues/266
https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778


## FLIP Doesn't Work
### `AtLibUsbDfu.dll` Not Found
Remove current driver and reinstall one FLIP provides from DeviceManager.
http://imgur.com/a/bnwzy
Commit	Line	Data
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.
e6c638be	90	## NKRO Doesn't work
af37bb2f	91	First you have to compile firmware with this build option `NKRO_ENABLE` in Makefile.
e6c638be	92
	93	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.
	94
af37bb2f	95	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	96
	97	https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
	98
	99
7b0356d1	100	## TrackPoint Needs Reset Circuit (PS/2 Mouse Support)
af37bb2f	101	Without reset circuit you will have inconsistent result due to improper initialize of the hardware. See circuit schematic of TPM754.
e6c638be	102
	103	- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
	104	- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
	105
	106
7b0356d1	107	## Can't Read Column of Matrix Beyond 16
e6c638be	108	Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
e6c638be	109
af37bb2f	110	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	111
	112	http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
	113
	114
7b0356d1	115	## Bootloader Jump Doesn't Work
e6c638be	116	Properly configure bootloader size in Makefile. With wrong section size bootloader won't probably start with Magic command and Boot Magic.
	117	```
	118	# Size of Bootloaders in bytes:
bb53635f	119	# Atmel DFU loader(ATmega32U4) 4096
	120	# Atmel DFU loader(AT90USB128) 8192
	121	# LUFA bootloader(ATmega32U4) 4096
	122	# Arduino Caterina(ATmega32U4) 4096
	123	# USBaspLoader(ATmega***) 2048
	124	# Teensy halfKay(ATmega32U4) 512
e6c638be	125	# Teensy++ halfKay(AT90USB128) 2048
	126	OPT_DEFS += -DBOOTLOADER_SIZE=4096
	127	```
	128	AVR Boot section size are defined by setting BOOTSZ fuse in fact. Consult with your MCU datasheet.
	129	Note that Word(2 bytes) size and address are used in datasheet while TMK uses Byte.
	130
	131	AVR Boot section is located at end of Flash memory like the followings.
	132	```
	133	byte Atmel/LUFA(ATMega32u4) byte Atmel(AT90SUB1286)
	134	0x0000 +---------------+ 0x00000 +---------------+
	135	\| \| \| \|
	136	\| \| \| \|
	137	\| Application \| \| Application \|
bb53635f	138	\| \| \| \|
e6c638be	139	= = = =
	140	\| \| 32KB-4KB \| \| 128KB-8KB
	141	0x6000 +---------------+ 0x1E000 +---------------+
	142	\| Bootloader \| 4KB \| Bootloader \| 8KB
	143	0x7FFF +---------------+ 0x1FFFF +---------------+
	144
bb53635f	145
e6c638be	146	byte Teensy(ATMega32u4) byte Teensy++(AT90SUB1286)
	147	0x0000 +---------------+ 0x00000 +---------------+
	148	\| \| \| \|
	149	\| \| \| \|
	150	\| Application \| \| Application \|
	151	\| \| \| \|
	152	= = = =
	153	\| \| 32KB-512B \| \| 128KB-2KB
	154	0x7E00 +---------------+ 0x1FC00 +---------------+
	155	\| Bootloader \| 512B \| Bootloader \| 2KB
	156	0x7FFF +---------------+ 0x1FFFF +---------------+
	157	```
	158
	159	And see this discussion for further reference.
	160	https://github.com/tmk/tmk_keyboard/issues/179
	161
392121b1	162	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	163
7b0356d1	164	## Special Extra Key Doesn't Work (System, Audio Control Keys)
e6c638be	165	You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
	166
	167	```
	168	EXTRAKEY_ENABLE = yes # Audio control and System control
	169	```
	170
7b0356d1	171	## Wakeup from Sleep Doesn't Work
e6c638be	172
	173	In Windows check `Allow this device to wake the computer` setting in Power Management property tab of Device Manager. Also check BIOS setting.
	174
	175	Pressing any key during sleep should wake host.
	176
	177	## Using Arduino?
	178
	179	Note that Arduino pin naming is different from actual chip. For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
	180
	181	- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
	182	- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
	183
af37bb2f	184	Arduino Leonardo and micro have ATMega32U4 and can be used for TMK, though Arduino bootloader may be a problem.
e6c638be	185
e6c638be	186
7b0356d1	187	## Using PF4-7 Pins of USB AVR?
af37bb2f	188	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 ATMegaU or AT90USB* are affected with this.
e6c638be	189
	190	If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.
	191
	192	See this code.
	193	```
	194	// JTAG disable for PORT F. write JTD bit twice within four cycles.
	195	MCUCR \|= (1<<JTD);
	196	MCUCR \|= (1<<JTD);
	197	```
	198	https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hbkb/matrix.c#L67
	199
	200	And read 26.5.1 MCU Control Register – MCUCR of ATMega32U4 datasheet.
	201
	202
7b0356d1	203	## Adding LED Indicators of Lock Keys
e6c638be	204	You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post.
	205
	206	http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
	207
	208	## Program Arduino Micro/Leonardo
	209	Push reset button and then run command like this within 8 seconds.
	210
	211	```
	212	avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
	213	```
	214
	215	Device name will vary depending on your system.
	216
	217	http://arduino.cc/en/Main/ArduinoBoardMicro
	218	https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
	219
	220
7b0356d1	221	## USB 3 Compatibility
e6c638be	222	I heard some people have a problem with USB 3 port, try USB 2 port.
	223
	224
7b0356d1	225	## Mac Compatibility
e6c638be	226	### OS X 10.11 and Hub
	227	https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
	228
	229
7b0356d1	230	## Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles
e6c638be	231	Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).
e6c638be	232
bb53635f	233	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	234
	235	https://github.com/tmk/tmk_keyboard/issues/266
	236	https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
	237
	238
	239
7b0356d1	240	## FLIP Doesn't Work
7b0356d1	241	### `AtLibUsbDfu.dll` Not Found
e6c638be	242	Remove current driver and reinstall one FLIP provides from DeviceManager.
e6c638be	243	http://imgur.com/a/bnwzy