docs/zh-cn/faq_debug.md

   1 # 调试的常见问题
   2
   3 本篇详细介绍了人们在键盘故障排除时的各种常见问题。
   4
   5 # 调试控制台
   6
   7 ## `hid_listen` 无法识别设备
   8 当设备的调试控制台未就绪时，您将看到如下内容：
   9
  10 ```
  11 Waiting for device:.........
  12 ```
  13
  14 插入设备后，*hid_listen*找到该设备，您将收到以下消息：
  15
  16 ```
  17 Waiting for new device:.........................
  18 Listening:
  19 ```
  20
  21 如果您无法获得这条“Listening:”消息，请尝试在[Makefile]中使用 `CONSOLE_ENABLE=yes`
  22
  23 在Linux这样的操作系统上，你可能需要一些权限。
  24 - 使用`sudo hid_listen`
  25
  26 ## 控制台没有返回消息
  27 检查:
  28 - *hid_listen* 找到了你的设备。看前面。
  29 - 输入**Magic**+d打开调试。详见[Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands)。
  30 - 设置`debug_enable=true` ，一般存在于**matrix.c**的`matrix_init()`中。
  31 - 尝试使用'print'函数而不要用调试输出。详见**common/print.h**。
  32 - 断开其他有控制台功能的设备。 详见[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97)。
  33
  34 ## Linux或UNIX这样的系统如何请求超级用户权限
  35 用'sudo'来执行*hid_listen*就有权限了。
  36 ```
  37 $ sudo hid_listen
  38 ```
  39
  40 或者把一个文件放到规则文件夹来为TMK设备添加*udev规则*，不同系统的目录可能有所不同。
  41
  42 文件: /etc/udev/rules.d/52-tmk-keyboard.rules(在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 # 其他
  51 ## 安全注意事项
  52
  53 你应该不想要把你的键盘变成"砖头"吧，就是变成没法重写固件的那种。
  54 下面讲解一些参数来告诉你什么风险很大（其实也不是很大）。
  55
  56 - 假如你键盘表面没有设计重置键"RESET", 那你要进入bootloader的话就要按PCB上的RESET了。
  57   按PCB上的RESET要拧开键盘底部。
  58 - 如果 tmk_core / common 里面的文件丢失键盘可能失灵。
  59 - .hex太大可能不太好; `make dfu` 会删除块，检验大小（咦?好像反了...）。
  60   一但出错，刷新键盘失败的话就困在DFU出不去了。
  61   - 所以, 要知道大小限制。 Planck键盘上.hex文件最大大小是 is 7000h (十进制是28672)
  62
  63 ```
  64 Linking: .build/planck_rev4_cbbrowne.elf                                                            [OK]
  65 Creating load file for Flash: .build/planck_rev4_cbbrowne.hex                                       [OK]
  66
  67 Size after:
  68    text    data     bss     dec     hex filename
  69       0   22396       0   22396    577c planck_rev4_cbbrowne.hex
  70 ```
  71
  72   - 上面那个文件大小是 22396/577ch，比28672/7000h小
  73   - 当你有一个合适的.hex文件时，你就要重试加载那个了
  74   - 您在键盘Makefile中的某些选项可能消耗额外内存；注意以下这几个
  75     BOOTMAGIC_ENABLE, MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
  76 - DFU 工具/不/可以写入bootloader (unless you throw in extra fruit salad of options),
  77   所以还是有点危险的
  78 - EEPROM大概有100000次循环寿命。不要总是频繁重写固件；EEPROM会玩坏的。
  79 ## 全键无冲不好用
  80 首先你要在**Makefile**用如下命令编译固件`NKRO_ENABLE`。
  81
  82 全键无冲还不好用的话试着用`Magic` **N** 命令(默认是`LShift+RShift+N`)。这个命令会在**全键无冲**和**六键无冲**之间临时切换。有些情况**全键无冲**不好用你就需要使用**六键无冲**模式，尤其是在BIOS中。
  83
  84 如果你的固件使用`BOOTMAGIC_ENABLE`编译的你要用`BootMagic` **N** 命令(默认`Space+N`)打开开关。这个设置保存在EEPROM中并保存在电源循环中。
  85 <!--翻译问题：上面这句翻译的不贴切 -->
  86
  87 https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
  88
  89
  90 ## 指点杆需要复位电路(PS/2 鼠标支持)
  91 如果没有复位电路，由于硬件初始化不正确，您将得到不一致的结果。查看TPM754复位电路。
  92
  93 - http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
  94 - http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
  95
  96
  97 ## 矩阵不可读16以上的列
  98 当列超过16时[matrix.h]的`read_cols()`中，用`1UL<<16`而不要用`1<<16`。
  99
 100 在C语言中`1` 是一个[int] 类型的[16 bit]值，在AVR中你不能左移大于15次。如果你使用`1<<16`的话会得到意外的零。你要用 [unsigned long]类型，比如`1UL`。
 101
 102 http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
 103
 104
 105 ## Bootloader跳转不好用
 106 在**Makefile**中正确配置**Makefile**大小。如果分区大小不正确，引导加载程序可能无法从**Magic command**和**Boot Magic**加载。
 107 ```
 108 #   bootloader字节数：
 109 #   Atmel DFU loader(ATmega32U4)   4096
 110 #   Atmel DFU loader(AT90USB128)   8192
 111 #   LUFA bootloader(ATmega32U4)    4096
 112 #   Arduino Caterina(ATmega32U4)   4096
 113 #   USBaspLoader(ATmega***)        2048
 114 #   Teensy   halfKay(ATmega32U4)   512
 115 #   Teensy++ halfKay(AT90USB128)   2048
 116 OPT_DEFS += -DBOOTLOADER_SIZE=4096
 117 ```
 118 AVR引导大小是通过**BOOTSZ**熔丝位来设置的。查阅你单片机的datasheet。
 119 记住，datasheet用的是**Word**(2字节)表示大小和地址，TMK用的是**Byte**。
 120
 121 AVR引导部分位于闪存的末尾，如下所示（Application是应用区，Bootloader是引导区）。
 122 ```
 123 byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
 124 0x0000   +---------------+               0x00000  +---------------+
 125          |               |                        |               |
 126          |               |                        |               |
 127          |  Application  |                        |  Application  |
 128          |               |                        |               |
 129          =               =                        =               =
 130          |               | 32KB-4KB               |               | 128KB-8KB
 131 0x6000   +---------------+               0x1E000  +---------------+
 132          |  Bootloader   | 4KB                    |  Bootloader   | 8KB
 133 0x7FFF   +---------------+               0x1FFFF  +---------------+
 134
 135
 136 byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
 137 0x0000   +---------------+               0x00000  +---------------+
 138          |               |                        |               |
 139          |               |                        |               |
 140          |  Application  |                        |  Application  |
 141          |               |                        |               |
 142          =               =                        =               =
 143          |               | 32KB-512B              |               | 128KB-2KB
 144 0x7E00   +---------------+               0x1FC00  +---------------+
 145          |  Bootloader   | 512B                   |  Bootloader   | 2KB
 146 0x7FFF   +---------------+               0x1FFFF  +---------------+
 147 ```
 148
 149 详情请见下方issue。
 150 https://github.com/tmk/tmk_keyboard/issues/179
 151
 152 如果你使用TeensyUSB, 有一个[已知bug](https://github.com/qmk/qmk_firmware/issues/164)硬件重置按钮阻止软件定义重置键工作。重新插拔键盘就好了。
 153
 154 ## 特殊额外键不起作用(系统，音频控制键)
 155 你要在`rules.mk`定义`EXTRAKEY_ENABLE`在QMK中使用它们。
 156
 157 ```
 158 EXTRAKEY_ENABLE = yes          # 音频控制和系统控制
 159 ```
 160
 161 ## 睡眠唤醒不好用
 162
 163 在Windows查看设备管理器中该键盘设备属性中电源管理选项卡中的`允许此设备唤醒计算机(O)`是否勾选。同时看一眼BIOS设置。
 164
 165 在主机睡眠时按下任何键都可以唤醒了。
 166
 167 ## 使用Arduino?
 168
 169 **注意Arduino的针脚名字和主控芯片的不一样。** 比如, Arduino的`D0`并不是`PD0`。自己用原理图捋一下电路。
 170
 171 - http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
 172 - http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
 173
 174 Arduino Leonardo和micro使用**ATMega32U4**，该芯片TMK可用，但Arduino的bootloader会导致问题。
 175
 176
 177 ## 在USB AVR使用PF4-7针脚?
 178 你要置位MCUCR寄存器JTD位来将PF4-7设置为GPIO。这些针脚默认是JTAG功能。 像ATMega*U* or AT90USB*这样的MCU会受影响。
 179
 180 如果是用Teensy的话就不需要了。Tennsy自带JTAGEN位未编程来失能该功能。
 181 <!--翻译问题：上句可能有错，原文为：Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function. -->
 182 代码如下。
 183 ```
 184     // F接口JTAG失能。在四个周期内写入两次JTD位。
 185     MCUCR |= (1<<JTD);
 186     MCUCR |= (1<<JTD);
 187 ```
 188 https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hbkb/matrix.c#L67
 189
 190 阅读ATMega32U4的datasheet中的**26.5.1 MCU Control Register – MCUCR**。
 191
 192
 193 ## 为锁定键添加指示灯
 194 你要自制CapsLock, ScrollLock 和 NumLock指示灯？见下文。
 195
 196 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
 197
 198 ## 为Arduino Micro/Leonardo编程
 199 按下重置键然后在8秒内运行下方这样的命令。
 200
 201 ```
 202 avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
 203 ```
 204
 205 设备名称因系统而异。
 206
 207 http://arduino.cc/en/Main/ArduinoBoardMicro
 208 https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
 209
 210
 211 ## USB 3 兼容性
 212 据传说有些人用USB3接口会有问题，用USB2的试试。
 213
 214
 215 ## Mac 兼容性
 216 ### OS X 10.11 和集线器
 217 https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
 218
 219
 220 ## 对于BIOS (UEFI)/恢复(睡眠和唤醒)/重新启动 有问题
 221 有人说他们的键盘在BIOS中，或许是恢复(睡眠和唤醒)后不工作.
 222
 223 截止至目前，其根本原因未知，不排除与某些构建选项有关。试着在Makefile中失能`CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE`这样的选项，也试试其他的。
 224
 225 https://github.com/tmk/tmk_keyboard/issues/266
 226 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
 227
 228
 229
 230 ## FLIP 不工作
 231 ### `AtLibUsbDfu.dll` 未找到
 232 从设备管理器中删除当前驱动程序并在设备管理器重新安装一个FLIP提供的程序。
 233 http://imgur.com/a/bnwzy