translate docs into Mandarin Chinese (qmk#5890)

* translate docs into Mandarin Chinese translate faq_debug.md into Chinese * translate faq_build.md into Chinese translate faq_build.md into Chinese * faq_keymap.md to zh-cn faq_keymap.md to zh-cn
akatrevorjay · May 22, 2019 · 8940107 · 8940107
1 parent eb75691
commit 8940107
Show file tree

Hide file tree

Showing 3 changed files with 595 additions and 0 deletions.
diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md
@@ -0,0 +1,150 @@
+# 关于构建的常见问题
+
+本页所写是QMK构建的常见问题.如果你还没有进行过编译,就看一下[构建环境搭建](getting_started_build_tools.md) 和 [make的说明](getting_started_make_guide.md).
+
+## 如果您不能在Linux上编程
+您需要适当的权限才能操作设备。对于Linux用户, 请参阅下方有关`udev`规则的说明。如果您对`udev`有问题，解决方法是用`sudo`命令。如果您不熟悉此命令，使用`man sudo`查看其手册或[看这个网页](https://linux.die.net/man/8/sudo).
+
+在你的主控是ATMega32u4时，以下是使用`sudo`命令的样例：
+
+    $ sudo dfu-programmer atmega32u4 erase --force
+    $ sudo dfu-programmer atmega32u4 flash your.hex
+    $ sudo dfu-programmer atmega32u4 reset
+
+或只用；
+
+    $ sudo make <keyboard>:<keymap>:dfu
+
+使用`sudo`运行`make`一般来说**不**推荐，如果可能，尽量使用前一种方法之一。
+
+### Linux `udev` 规则
+在Linux上，您需要适当的权限才能访问MCU。你也可以在刷新固件时使用 `sudo`，或把这些文件放到`/etc/udev/rules.d/`。
+
+**/etc/udev/rules.d/50-atmel-dfu.rules:**
+```
+# Atmel ATMega32U4
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
+# Atmel USBKEY AT90USB1287
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
+# Atmel ATMega32U2
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
+```
+
+**/etc/udev/rules.d/52-tmk-keyboard.rules:**
+```
+# tmk键盘产品     https://github.com/tmk/tmk_keyboard
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
+```
+**/etc/udev/rules.d/54-input-club-keyboard.rules:**
+
+```
+# Input Club keyboard bootloader
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
+```
+
+### 串行设备在Linux上检测不到bootloader模式
+确保您的内核对您的设备有相应的支持。 如果你的设备是 USB ACM, 比如Pro Micro (Atmega32u4)，就要加上`CONFIG_USB_ACM=y`. 其他设备可能需要`USB_SERIAL` 及其任何子选项。
+
+## DFU Bootloader的未知设备
+
+如果您在使用Windows来刷新键盘的时候碰到了问题，检查设备管理器。如果在键盘处于 "bootloader模式"时你看到 "未知设备"，说明你可能面临设备问题。
+
+重新运行MSYS2上的安装脚本或许会凑效（比如在MSYS2/WSL运行 `./util/qmk_install.sh`) 或者重新安装QMK工具箱也可能会解决你的问题。
+
+如果以上方法还是短针攻疽，那您可能需要使用[Zadig Utility](https://zadig.akeo.ie/)。下载此程序, 找到设备问题, 然后选择 `WinUSB`选项, 然后点击"Reinstall driver"。完成后再试试刷新你的键盘。倘若依然徒劳无功，那就尝试所有选项直到好用为止。
+
+?> 事实上没有一个驱动的最佳选择，有些选项就是和某些系统相辅相成。但libUSB和WinUSB似乎也算是这里的最佳选择了。
+如果bootloader在设备列表中没有显示，你可能要使能 "List all devices"选项在选项菜单中`Options`，然后找到有问题的bootloader设备。(译者注：在win10中可能为 查看-显示隐藏的设备)
+
+
+## WINAVR已淘汰
+不再推荐使用WINAVR，使用可能会导致问题
+详情请见[TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
+
+## USB VID 和 PID
+你可以在编辑`config.h`时使用任何你想用的ID值。实际上，使用任何可能未使用的ID都没有问题，除了有极低的与其他产品发生冲突的可能性。
+
+大多数QMK主板使用`0xFEED`作为vendor ID。您应该查看其他键盘，以确保选择了唯一的Product ID。
+
+也要看看这个。
+https://github.com/tmk/tmk_keyboard/issues/150
+
+一也可以在下方链接购买一个唯一的VID:PID。不过个人使用似乎用不着这个。
+- http://www.obdev.at/products/vusb/license.html
+- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
+
+## Cortex: `cstddef: No such file or directory`
+在Ubuntu 14.04上的GCC 4.8 会出现这种问题需要用这个PPA升级到4.9。
+https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded
+
+https://github.com/tmk/tmk_keyboard/issues/212
+https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef
+https://developer.mbed.org/forum/mbed/topic/5205/
+
+## `clock_prescale_set` and `clock_div_1` Not Available
+你的工具链太旧了不支持MCU。比如WinAVR 20100110就不支持ATMega32u2.
+
+```
+Compiling C: ../../tmk_core/protocol/lufa/lufa.c
+avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8  -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d  ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o
+../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu':
+../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set'
+../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function)
+../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once
+../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.)
+make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1
+```
+
+
+## AVR的BOOTLOADER_SIZE
+注意Teensy2.0++ bootloader的大小是2048字节。有些Makefile注释错了。
+
+```
+# Boot Section Size in *bytes*
+#   Teensy halfKay   512
+#   Teensy++ halfKay 2048
+#   Atmel DFU loader 4096       (TMK Alt Controller)
+#   LUFA bootloader  4096
+#   USBaspLoader     2048
+OPT_DEFS += -DBOOTLOADER_SIZE=2048
+```
+
+## 在MacOS上 `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` 
+这是brew更新的问题，导致AVR GCC依赖的符号链接被损坏。
+
+解决方案是移除并重新安装所有受影响的模块。
+
+```
+brew rm avr-gcc
+brew rm dfu-programmer
+brew rm dfu-util
+brew rm gcc-arm-none-eabi
+brew rm avrdude
+brew install avr-gcc
+brew install dfu-programmer
+brew install dfu-util
+brew install gcc-arm-none-eabi
+brew install avrdude
+```
+
+### avr-gcc 8.1 和 LUFA
+
+如果你把avr-gcc升级到7以上你可能会遇到关于LUFA的问题。比如:
+
+`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
+
+那你就需要在brew中把avr-gcc回退到7。
+
+```
+brew uninstall --force avr-gcc
+brew install avr-gcc@7
+brew link --force avr-gcc@7
+```
+
+### 我刷新了我的键盘但是键盘不工作/按键没有注册 - 而且还是ARM的 (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019)
+由于EEPROM在基于ARM的芯片上的工作原理，保存的设置可能不再有效。这会影响默认层，而且*或许*在某些情况下，会使键盘不好用，我们仍在调查这些情况。重置EEPROM将解决此问题。
+
+[Planck rev6键盘重置EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) 是用于强制重置EEPROM的。刷入这个文件后，再次刷入正常固件，这会将键盘恢复到_正常_工作状态。
+[Preonic rev3键盘重置EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin)
+
+如果以任何形式启用了bootmagic， 那么您还需要(看[Bootmagic文档](feature_bootmagic.md) 以及键盘信息，以了解如何执行此操作的详细信息).
diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md
@@ -0,0 +1,233 @@
+# 调试的常见问题
+
+本篇详细介绍了人们在键盘故障排除时的各种常见问题。
+
+# 调试控制台
+
+## `hid_listen` 无法识别设备
+当设备的调试控制台未就绪时，您将看到如下内容：
+
+```
+Waiting for device:.........
+```
+
+插入设备后，*hid_listen*找到该设备，您将收到以下消息：
+
+```
+Waiting for new device:.........................
+Listening:
+```
+
+如果您无法获得这条“Listening:”消息，请尝试在[Makefile]中使用 `CONSOLE_ENABLE=yes`
+
+在Linux这样的操作系统上，你可能需要一些权限。
+- 使用`sudo hid_listen`
+
+## 控制台没有返回消息
+检查:
+- *hid_listen* 找到了你的设备。看前面。
+- 输入**Magic**+d打开调试。详见[Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands)。
+- 设置`debug_enable=true` ，一般存在于**matrix.c**的`matrix_init()`中。
+- 尝试使用'print'函数而不要用调试输出。详见**common/print.h**。
+- 断开其他有控制台功能的设备。 详见[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97)。
+
+## Linux或UNIX这样的系统如何请求超级用户权限
+用'sudo'来执行*hid_listen*就有权限了。
+```
+$ sudo hid_listen
+```
+
+或者把一个文件放到规则文件夹来为TMK设备添加*udev规则*，不同系统的目录可能有所不同。
+
+文件: /etc/udev/rules.d/52-tmk-keyboard.rules(在Ubuntu系统的情况下)
+```
+# tmk keyboard products     https://github.com/tmk/tmk_keyboard
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
+```
+
+***
+
+# 其他
+## 安全注意事项
+
+你应该不想要把你的键盘变成"砖头"吧，就是变成没法重写固件的那种。
+下面讲解一些参数来告诉你什么风险很大（其实也不是很大）。
+
+- 假如你键盘表面没有设计重置键"RESET", 那你要进入bootloader的话就要按PCB上的RESET了。
+  按PCB上的RESET要拧开键盘底部。
+- 如果 tmk_core / common 里面的文件丢失键盘可能失灵。
+- .hex太大可能不太好; `make dfu` 会删除块，检验大小（咦?好像反了...）。
+  一但出错，刷新键盘失败的话就困在DFU出不去了。
+  - 所以, 要知道大小限制。 Planck键盘上.hex文件最大大小是 is 7000h (十进制是28672)
+
+```
+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
+```
+
+  - 上面那个文件大小是 22396/577ch，比28672/7000h小
+  - 当你有一个合适的.hex文件时，你就要重试加载那个了
+  - 您在键盘Makefile中的某些选项可能消耗额外内存；注意以下这几个
+    BOOTMAGIC_ENABLE, MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
+- DFU 工具/不/可以写入bootloader (unless you throw in extra fruit salad of options), 
+  所以还是有点危险的
+- EEPROM大概有100000次循环寿命。不要总是频繁重写固件；EEPROM会玩坏的。
+## 全键无冲不好用
+首先你要在**Makefile**用如下命令编译固件`NKRO_ENABLE`。
+
+全键无冲还不好用的话试着用`Magic` **N** 命令(默认是`LShift+RShift+N`)。这个命令会在**全键无冲**和**六键无冲**之间临时切换。有些情况**全键无冲**不好用你就需要使用**六键无冲**模式，尤其是在BIOS中。
+
+如果你的固件使用`BOOTMAGIC_ENABLE`编译的你要用`BootMagic` **N** 命令(默认`Space+N`)打开开关。这个设置保存在EEPROM中并保存在电源循环中。
+<!--翻译问题：上面这句翻译的不贴切 -->
+
+https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
+
+
+## 指点杆需要复位电路(PS/2 鼠标支持)
+如果没有复位电路，由于硬件初始化不正确，您将得到不一致的结果。查看TPM754复位电路。
+
+- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
+- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
+
+
+## 矩阵不可读16以上的列
+当列超过16时[matrix.h]的`read_cols()`中，用`1UL<<16`而不要用`1<<16`。
+
+在C语言中`1` 是一个[int] 类型的[16 bit]值，在AVR中你不能左移大于15次。如果你使用`1<<16`的话会得到意外的零。你要用 [unsigned long]类型，比如`1UL`。
+
+http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
+
+
+## Bootloader跳转不好用
+在**Makefile**中正确配置**Makefile**大小。如果分区大小不正确，引导加载程序可能无法从**Magic command**和**Boot Magic**加载。
+```
+#   bootloader字节数：
+#   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引导大小是通过**BOOTSZ**熔丝位来设置的。查阅你单片机的datasheet。
+记住，datasheet用的是**Word**(2字节)表示大小和地址，TMK用的是**Byte**。
+
+AVR引导部分位于闪存的末尾，如下所示（Application是应用区，Bootloader是引导区）。
+```
+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  +---------------+
+```
+
+详情请见下方issue。
+https://github.com/tmk/tmk_keyboard/issues/179
+
+如果你使用TeensyUSB, 有一个[已知bug](https://github.com/qmk/qmk_firmware/issues/164)硬件重置按钮阻止软件定义重置键工作。重新插拔键盘就好了。
+
+## 特殊额外键不起作用(系统，音频控制键)
+你要在`rules.mk`定义`EXTRAKEY_ENABLE`在QMK中使用它们。
+
+```
+EXTRAKEY_ENABLE = yes          # 音频控制和系统控制
+```
+
+## 睡眠唤醒不好用
+
+在Windows查看设备管理器中该键盘设备属性中电源管理选项卡中的`允许此设备唤醒计算机(O)`是否勾选。同时看一眼BIOS设置。
+
+在主机睡眠时按下任何键都可以唤醒了。
+
+## 使用Arduino?
+
+**注意Arduino的针脚名字和主控芯片的不一样。** 比如, Arduino的`D0`并不是`PD0`。自己用原理图捋一下电路。
+
+- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
+- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
+
+Arduino Leonardo和micro使用**ATMega32U4**，该芯片TMK可用，但Arduino的bootloader会导致问题。
+
+
+## 在USB AVR使用PF4-7针脚?
+你要置位MCUCR寄存器JTD位来将PF4-7设置为GPIO。这些针脚默认是JTAG功能。 像ATMega*U* or AT90USB*这样的MCU会受影响。
+
+如果是用Teensy的话就不需要了。Tennsy自带JTAGEN位未编程来失能该功能。
+<!--翻译问题：上句可能有错，原文为：Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function. -->
+代码如下。
+```
+    // F接口JTAG失能。在四个周期内写入两次JTD位。
+    MCUCR |= (1<<JTD);
+    MCUCR |= (1<<JTD);
+```
+https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hbkb/matrix.c#L67
+
+阅读ATMega32U4的datasheet中的**26.5.1 MCU Control Register – MCUCR**。
+
+
+## 为锁定键添加指示灯
+你要自制CapsLock, ScrollLock 和 NumLock指示灯？见下文。
+
+http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
+
+## 为Arduino Micro/Leonardo编程
+按下重置键然后在8秒内运行下方这样的命令。
+
+```
+avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
+```
+
+设备名称因系统而异。
+
+http://arduino.cc/en/Main/ArduinoBoardMicro
+https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
+
+
+## USB 3 兼容性
+据传说有些人用USB3接口会有问题，用USB2的试试。
+
+
+## Mac 兼容性
+### OS X 10.11 和集线器
+https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
+
+
+## 对于BIOS (UEFI)/恢复(睡眠和唤醒)/重新启动 有问题
+有人说他们的键盘在BIOS中，或许是恢复(睡眠和唤醒)后不工作.
+
+截止至目前，其根本原因未知，不排除与某些构建选项有关。试着在Makefile中失能`CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE`这样的选项，也试试其他的。
+
+https://github.com/tmk/tmk_keyboard/issues/266
+https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
+
+
+
+## FLIP 不工作
+### `AtLibUsbDfu.dll` 未找到
+从设备管理器中删除当前驱动程序并在设备管理器重新安装一个FLIP提供的程序。
+http://imgur.com/a/bnwzy