aboutsummaryrefslogtreecommitdiff
path: root/docs/zh-cn/faq_debug.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/zh-cn/faq_debug.md')
-rw-r--r--docs/zh-cn/faq_debug.md188
1 files changed, 94 insertions, 94 deletions
diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md
index 4dba44c27..63d688ed9 100644
--- a/docs/zh-cn/faq_debug.md
+++ b/docs/zh-cn/faq_debug.md
@@ -1,136 +1,136 @@
1# 调试的常见问题 1# 调试 FAQ
2 2
3本篇详细介绍了人们在键盘故障排除时的各种常见问题。 3<!---
4 original document: 0.15.12:docs/faq_debug.md
5 git diff 0.15.12 HEAD -- docs/faq_debug.md | cat
6-->
4 7
5# 8此页面细介绍了人们对键盘障除的种见问题。
6 9
7## `hid_listen` 无法识别设备 10## 调试 :id=debugging
8当设备的调试控制台未就绪时，您将看到如下内容：
9 11
10``` 12如果你在 `rules.mk` 中配置了 `CONSOLE_ENABLE = yes`，你的键盘将会输出调试信息。默认情况下输出很有限，可以启用调试模式来增加调试输出的丰富度。使用你的键映射方案中的 `DEBUG` 键码，或使用[指令](zh-cn/feature_command.md)功能来启动调试模式，或者将下面这段代码放到你的键映射中：
11Waiting for device:.........
12```
13
14插入设备后，*hid_listen*找到该设备，您将收到以下消息：
15 13
16``` 14```c
17Waiting for new device:......................... 15void keyboard_post_init_user(void) {
18Listening: 16 // 通过调整这些值可以改变其表现
17 debug_enable=true;
18 debug_matrix=true;
19 //debug_keyboard=true;
20 //debug_mouse=true;
21}
19``` 22```
20 23
21如果您无法得这条“Listening:”消息，请试[Makefile]中使用 `CONSOLE_ENABLE=yes` 24## 试具
22 25
23在Linux这样的操作系统上，你可能需要一些权限。 26有多种可用于调试的工具。
24- 使用`sudo hid_listen`
25 27
26## 控制台没有返回消息 28### 使用QMK工具箱调试
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 29
34## Linux或UNIX这样的系统如何请求超级用户权限 30在兼容的平台上，[QMK工具箱](https://github.com/qmk/qmk_toolbox)可以展示你的键盘的调试输出。
35用'sudo'来执行*hid_listen*就有权限了。
36```
37$ sudo hid_listen
38```
39 31
40或者把个文件到规则文件夹来为TMK备添加*udev则*不同系统的目录可有所不同。 32### QMK CLI 试
41 33
42文件: /etc/udev/rules.d/52-tmk-keyboard.rules(在Ubuntu系统的情况下) 34倾向于在终端进行调试？使用 [QMK CLI 命令行](zh-cn/cli_commands.md#qmk-console)可以展示键盘输出的调试信息。
43```
44# tmk keyboard products https://github.com/tmk/tmk_keyboard
45SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
46```
47 35
48*** 36### 使用hid_listen调试
49 37
50# 其他 38更喜欢使用终端的方案？PJRC提供的[hid_listen](https://www.pjrc.com/teensy/hid_listen.html)也可以用来展示调试信息，已有Windows、Linux及MacOS下预编译好的可执行文件。
51## 安全注意事项
52 39
53你应该不想要把你的键盘变成"砖头"吧，就是变成没法重写固件的那种。 40## 发送自定义调试信息 :id=debug-api
54下面讲解一些参数来告诉你什么风险很大（其实也不是很大）。
55 41
56- 假如你键盘表面没有设计重置键"RESET", 那你要进入bootloader的话就要按PCB上的RESET了。 42有时在[自定义代码](zh-cn/custom_quantum_functions.md)中输出调试信息非常有用，要做到这个功能也很简单，在代码文件头部包含 `print.h` 文件：
57 按PCB上的RESET要拧开键盘底部。
58- 如果 tmk_core / common 里面的文件丢失键盘可能失灵。
59- .hex太大可能不太好; `make dfu` 会删除块，检验大小（咦?好像反了...）。
60 一但出错，刷新键盘失败的话就困在DFU出不去了。
61 - 所以, 要知道大小限制。 Planck键盘上.hex文件最大大小是 is 7000h (十进制是28672)
62 43
44```c
45#include "print.h"
63``` 46```
64Linking: .build/planck_rev4_cbbrowne.elf [OK]
65Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
66 47
67Size after: 48然后可以使用以下输出函数：
68 text data bss dec hex filename
69 0 22396 0 22396 577c planck_rev4_cbbrowne.hex
70```
71 49
72 - 上面那个文件大小是 22396/577ch，比28672/7000h小 50* `print("string")`: 字符串输出
73 - 当你有一个合适的.hex文件时，你就要重试加载那个了 51* `uprintf("%s string", var)`: 格式化字符串输出
74 - 您在键盘Makefile中的某些选项可能消耗额外内存；注意以下这几个 52* `dprint("string")` 仅调试模式下，字符串输出
75 BOOTMAGIC_ENABLE, MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE 53* `dprintf("%s string", var)`: 仅调试模式下，格式化字符串输出
76- DFU 工具/不/可以写入bootloader (unless you throw in extra fruit salad of options),
77 所以还是有点危险的
78- EEPROM大概有100000次循环寿命。不要总是频繁重写固件；EEPROM会玩坏的。
79## 全键无冲不好用
80首先你要在**Makefile**用如下命令编译固件`NKRO_ENABLE`。
81 54
82全键无冲还不好用的话试着用`Magic` **N** 命令(默认是`LShift+RShift+N`)。这个命令会在**全键无冲**和**六键无冲**之间临时切换。有些情况**全键无冲**不好用你就需要使用**六键无冲**模式，尤其是在BIOS中。 55## 调试示例
83 56
57以下列出了一些实际出现过的调试范例，更多资料参见[调试/定位QMK问题](zh-cn/faq_debug.md)。
84 58
85## 指点杆需要复位电路(PS/2 鼠标支持) 59### 当前按下的键的矩阵坐标是什么？
86如果没有复位电路，由于硬件初始化不正确，您将得到不一致的结果。查看TPM754复位电路。
87 60
88- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447 61在移植或尝试诊断PCB问题时，确认按下的键被正确扫描到是很有用的排查步骤。要启用该场景的日志输出，请在 `keymap.c` 中添加：
89- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf
90 62
63```c
64bool process_record_user(uint16_t keycode, keyrecord_t *record) {
65 // If console is enabled, it will print the matrix position and status of each key pressed
66#ifdef CONSOLE_ENABLE
67 uprintf("KL: kc: 0x%04X, col: %u, row: %u, pressed: %b, time: %u, interrupt: %b, count: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed, record->event.time, record->tap.interrupted, record->tap.count);
68#endif
69 return true;
70}
71```
91 72
92## 矩阵不可读16以上的列 73输出示例
93当列超过16时[matrix.h]的`read_cols()`中，用`1UL<<16`而不要用`1<<16`。 74```text
94 75Waiting for device:.......
95在C语言中`1` 是一个[int] 类型的[16 bit]值，在AVR中你不能左移大于15次。如果你使用`1<<16`的话会得到意外的零。你要用 [unsigned long]类型，比如`1UL`。 76Listening:
77KL: kc: 169, col: 0, row: 0, pressed: 1
78KL: kc: 169, col: 0, row: 0, pressed: 0
79KL: kc: 174, col: 1, row: 0, pressed: 1
80KL: kc: 174, col: 1, row: 0, pressed: 0
81KL: kc: 172, col: 2, row: 0, pressed: 1
82KL: kc: 172, col: 2, row: 0, pressed: 0
83```
96 84
97https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 85### 扫描到一个键码需要多久？
98 86
99## 特殊额外键不起作用(系统，音频控制键) 87调试性能问题时，知晓开关矩阵的扫描频率是很有用的排查步骤。要启用该场景的日志输出，请在 `config.h` 中添加：
100你要在`rules.mk`定义`EXTRAKEY_ENABLE`在QMK中使用它们。
101 88
89```c
90#define DEBUG_MATRIX_SCAN_RATE
102``` 91```
103EXTRAKEY_ENABLE = yes # 音频控制和系统控制
104```
105
106## 睡眠唤醒不好用
107
108在Windows查看设备管理器中该键盘设备属性中电源管理选项卡中的`允许此设备唤醒计算机(O)`是否勾选。同时看一眼BIOS设置。
109 92
110在主机睡眠时按下任何键都可以唤醒了。 93输出示例
94```text
95 > matrix scan frequency: 315
96 > matrix scan frequency: 313
97 > matrix scan frequency: 316
98 > matrix scan frequency: 316
99 > matrix scan frequency: 316
100 > matrix scan frequency: 316
101```
111 102
112## 使用Arduino? 103## `hid_listen` 无法识别到设备
113 104
114**注意Arduino的针脚名字和主控芯片的不一样。** 比如, Arduino的`D0`并不是`PD0`。自己用原理图捋一下电路。 105如果设备没有就绪，在命令行下调试会看到如下输出：
115 106
116- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf 107```
117- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf 108Waiting for device:.........
109```
118 110
119Arduino Leonardo和micro使用**ATMega32U4**，芯片TMK，Arduino的bootloader问题。 111设备入后*hid_listen*设备，会有下：
120 112
121## USB 3 兼容性 113```
122据传说有些人用USB3接口会有问题，用USB2的试试。 114Waiting for new device:.........................
115Listening:
116```
123 117
118若无法出现'Listening:'消息，尝试在[Makefile]中添加 `CONSOLE_ENABLE=yes`
124 119
125## Mac 兼容性 120在类Linux系统下，访问设备可能需要一定权限，尝试使用 `sudo hid_listen`。
126### OS X 10.11 和集线器
127https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
128 121
122此外，很多Linux发行版可以通过创建如下内容的文件 `/etc/udev/rules.d/70-hid-listen.rules` 来避免通过root权限执行hid_listen：
129 123
130## 对于BIOS (UEFI)/恢复(睡眠和唤醒)/重新启动 有问题 124```
131有人说他们的键盘在BIOS中，或许是恢复(睡眠和唤醒)后不工作. 125SUBSYSTEM=="hidraw", ATTRS{idVendor}=="abcd", ATTRS{idProduct}=="def1", TAG+="uaccess", RUN{builtin}+="uaccess"
126```
132 127
133截止至目前，其根本原因未知，不排除与某些构建选项有关。试着在Makefile中失能`CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE`这样的选项，也试试其他的。 128使用设备的真实VID和PID替换上面的abcd和def1，留意必须全小写。其中 `RUN{builtin}+="uaccess"` 仅在较老的发行版中需要使用。
134 129
135https://github.com/tmk/tmk_keyboard/issues/266 130## 命令行无法成功输出消息
136https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 131请检查:
132- *hid_listen*确实找到了设备，如前文所述。
133- 通过**Magic**+d命令启用调试模式，参见[Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
134- 配置`debug_enable=true`. 参见[调试](#debugging)
135- 尝试用 `print` 替代 `dprint`， 参见**common/print.h**.
136- 拔出其它可能影响命令行的设备，参见[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-04 17:38:41 +0000