diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/feature_encoders.md | 2 | ||||
| -rw-r--r-- | docs/getting_started_introduction.md | 8 | ||||
| -rw-r--r-- | docs/i2c_driver.md | 29 | ||||
| -rw-r--r-- | docs/keycodes.md | 35 | ||||
| -rw-r--r-- | docs/reference_configurator_support.md | 2 | ||||
| -rw-r--r-- | docs/zh-cn/faq_build.md | 150 | ||||
| -rw-r--r-- | docs/zh-cn/faq_debug.md | 233 | ||||
| -rw-r--r-- | docs/zh-cn/faq_keymap.md | 212 |
8 files changed, 646 insertions, 25 deletions
diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index dd12c91ce..9ac97a9a1 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -38,7 +38,7 @@ or `keymap.c`: } else { tap_code(KC_PGUP); } - } else if (index == 1) { /* Second encoder + } else if (index == 1) { /* Second encoder */ if (clockwise) { tap_code(KC_UP); } else { diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md index 3b6a488ed..e183d77ee 100644 --- a/docs/getting_started_introduction.md +++ b/docs/getting_started_introduction.md @@ -12,11 +12,17 @@ Within the folder `users` is a directory for each user. This is a place for user ### Keyboard Project Structure -Within the folder `keyboards` and its subfolder `handwired` is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within it you'll find the following structure: +Within the folder `keyboards`, its subfolder `handwired` and its vendor and manufacture subdirectories e.g. `clueboard` is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard/2x1800`. Within it, you'll find the following structure: * `keymaps/`: Different keymaps that can be built * `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `rules.mk`. * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`. +* `info.json`: The file used for setting layout for QMK Configurator. See [Configurator Support](reference_configurator_support.md) for more information. +* `readme.md`: A brief overview of the keyboard. +* `<keyboardName>.h`: This file is where the keyboard layout is defined against the keyboard's switch matrix. +* `<keyboardName>.c`: This file is where you can find custom code for the keyboard. + +For more information on project structure, see [QMK Keyboard Guidelines](hardware_keyboard_guidelines.md). ### Keymap Structure diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md index bb1a2d74f..4a47a92b1 100644 --- a/docs/i2c_driver.md +++ b/docs/i2c_driver.md @@ -65,11 +65,30 @@ By default the I2C1 hardware driver is assumed to be used. If another hardware d STM32 MCUs allows a variety of pins to be configured as I2C pins depending on the hardware driver used. By default B6 and B7 are set to I2C. You can use these defines to set your i2c pins: -| Variable | Description | Default | -|-------------|----------------------------------------------|---------| -| `I2C1_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) | `GPIOB` | -| `I2C1_SCL` | The pin number for the SCL pin (0-9) | `6` | -| `I2C1_SDA` | The pin number for the SDA pin (0-9) | `7` | +| Variable | Description | Default | +|--------------------------|----------------------------------------------------------------------------------------------|---------| +| `I2C1_SCL_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SCL | `GPIOB` | +| `I2C1_SDA_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SDA | `GPIOB` | +| `I2C1_SCL` | The pin number for the SCL pin (0-9) | `6` | +| `I2C1_SDA` | The pin number for the SDA pin (0-9) | `7` | +| `I2C1_BANK` (deprecated) | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superceded by `I2C1_SCL_BANK`, `I2C1_SDA_BANK` | `GPIOB` | + +STM32 MCUs allow for different timing parameters when configuring I2C. These can be modified using the following parameters, using https://www.st.com/en/embedded-software/stsw-stm32126.html as a reference: + +| Variable | Default | +|-----------------------|---------| +| `I2C1_TIMINGR_PRESC` | `15U` | +| `I2C1_TIMINGR_SCLDEL` | `4U` | +| `I2C1_TIMINGR_SDADEL` | `2U` | +| `I2C1_TIMINGR_SCLH` | `15U` | +| `I2C1_TIMINGR_SCLL` | `21U` | + +STM32 MCUs allow for different "alternate function" modes when configuring GPIO pins. These are required to switch the pins used to I2C mode. See the respective datasheet for the appropriate values for your MCU. + +| Variable | Default | +|---------------------|---------| +| `I2C1_SCL_PAL_MODE` | `4` | +| `I2C1_SDA_PAL_MODE` | `4` | You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function: diff --git a/docs/keycodes.md b/docs/keycodes.md index e9cfd3425..3ff87856e 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -344,23 +344,24 @@ This is a reference only. Each group of keys links to the page documenting their ## [Mod-Tap Keys](feature_advanced_keycodes.md#mod-tap) -|Key |Aliases |Description | -|------------|-----------------------------------------------------------------|-------------------------------------------------------| -|`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped | -|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped | -|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped | -|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped | -|`RCTL_T(kc)`| |Right Control when held, `kc` when tapped | -|`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped | -|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped | -|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped | -|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | -|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | -|`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped | -|`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped | -|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped | -|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped| -|`HYPR_T(kc)`|`ALL_T(kc)` |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| +|Key |Aliases |Description | +|-------------|-----------------------------------------------------------------|-------------------------------------------------------| +|`MT(mod, kc)`| |`mod` when held, `kc` when tapped | +|`LCTL_T(kc)` |`CTL_T(kc)` |Left Control when held, `kc` when tapped | +|`LSFT_T(kc)` |`SFT_T(kc)` |Left Shift when held, `kc` when tapped | +|`LALT_T(kc)` |`ALT_T(kc)` |Left Alt when held, `kc` when tapped | +|`LGUI_T(kc)` |`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped | +|`RCTL_T(kc)` | |Right Control when held, `kc` when tapped | +|`RSFT_T(kc)` | |Right Shift when held, `kc` when tapped | +|`RALT_T(kc)` |`ALGR_T(kc)` |Right Alt when held, `kc` when tapped | +|`RGUI_T(kc)` |`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped | +|`SGUI_T(kc)` |`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | +|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | +|`LCAG_T(kc)` | |Left Control, Alt and GUI when held, `kc` when tapped | +|`RCAG_T(kc)` | |Right Control, Alt and GUI when held, `kc` when tapped | +|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped | +|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped| +|`HYPR_T(kc)` |`ALL_T(kc)` |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| ## [RGB Lighting](feature_rgblight.md) diff --git a/docs/reference_configurator_support.md b/docs/reference_configurator_support.md index a20a6c9ad..784c6d9f7 100644 --- a/docs/reference_configurator_support.md +++ b/docs/reference_configurator_support.md @@ -89,7 +89,7 @@ Once the layout is as desired, move to the Raw Data tab in KLE, and copy the con To convert this data into our JSON, go to the [QMK KLE-JSON Converter](https://qmk.fm/converter/), paste the Raw Data into the Input field, and click the Convert button. After a moment, our JSON data will appear in the Output field. Copy the contents to a new text document, and name the document `info.json`, saving it in the same folder that contains `numpad.h`. -Use the `keyboard_name` object to set the name of the keyboard. The `bootloader` object is deprecated, so it can be deleted. For instruction purposes, we will put each key's object on its own line. This is only to make the file more human-readable, and does not affect the Configurator's functionality. +Use the `keyboard_name` object to set the name of the keyboard. For instruction purposes, we will put each key's object on its own line. This is only to make the file more human-readable, and does not affect the Configurator's functionality. ```json { diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md new file mode 100644 index 000000000..60d902007 --- /dev/null +++ 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 new file mode 100644 index 000000000..ca8b3fd25 --- /dev/null +++ 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 diff --git a/docs/zh-cn/faq_keymap.md b/docs/zh-cn/faq_keymap.md new file mode 100644 index 000000000..ee8e3c06b --- /dev/null +++ b/docs/zh-cn/faq_keymap.md @@ -0,0 +1,212 @@ +# 布局常见问题 + +本页本页包含人们经常遇到的关于布局的问题。如果你觉得没什么问题，请先看[布局概览](keymap.md)。 + +## 我能用什么键码? +看[键码](keycodes.md)你可以找到你能用的键码索引。可以的话这些链接可以连接到更广泛的文档。 + +键码实际上定义在[common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h). + +## 默认的键码什么样? + +世界上有三种标准键盘设计，分别是：ANSI, ISO, and JIS. 主要是北美用ANSI(译者注：中国很多键盘使用这个), 欧洲和非洲主要使用ISO，日本使用JIS。未提及的区域通常使用ANSI或ISO。与这些设计对应的键代码如下所示： + +<!-- 该图片的来源: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a --> + + +## 我有一些键变成了其他功能或者不工作了 + +QMK有两个功能，Bootmagic和命令行，它允许您在运行中更改键盘的行为。该功能包括但不仅限于, 交换Ctrl/Caps，关闭界面，交换Alt/Gui，交换 Backspace/Backslash，禁用所有键，以及其他的行为改变。 + +快速解决方法是插入键盘时按住`Space`+`Backspace`。该操作将重置已保存设置，让这些键回复初始功能。这招不好用的话参阅下方： + +* [Bootmagic](feature_bootmagic.md) +* [命令](feature_command.md) + +## 菜单键不好用 + +现在大多数键盘 `KC_RGUI`和`KC_RCTL`中间的键子叫做`KC_APP`。这是因为在这个键子发明之前相关标准里就已经有键叫做`MENU(菜单)`了，所以微软叫他`APP(应用)`键。 + +## `KC_SYSREQ` 不工作 +使用抓屏的键码(`KC_PSCREEN`或`KC_PSCR`)而不用`KC_SYSREQ`。组合键'Alt + Print Screen'会被当作'System request'。 + +见[issue #168](https://github.com/tmk/tmk_keyboard/issues/168)和 +* http://en.wikipedia.org/wiki/Magic_SysRq_key +* http://en.wikipedia.org/wiki/System_request + +## 电源键不工作 + +这有点让人困惑,QMK有两个"Power(电源)"键码: `KC_POWER` 在键盘/小键盘的HID使用页面中，`KC_SYSTEM_POWER` (或者叫`KC_PWR`)在用户页。 + +前者只能被macOS识别，但是后者，即`KC_SLEP`和`KC_WAKE`三大主要操作系统全都支持，所以推荐使用这两个。Windows下这些键立即生效，macOS要长按直到弹出对话框。 + +## 自动大小写锁定 +可以解决'the'问题(正常应为The)。我经常在输入'The'时不慎输入了'the'或者'THe'。自动大小写锁定可以修正此类问题。详见下方链接。 +https://github.com/tmk/tmk_keyboard/issues/67 + +## 修改 键/层 卡住 +除非正确配置层切换，否则修改键或层可能会卡住。 +对于修改键和图层操作，必须把`KC_TRANS`放到目标层的相同位置，用于注销修改键或在释放事件时返回到上一层。 +* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching +* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604 +* https://github.com/tmk/tmk_keyboard/issues/248 + + +## 机械自锁开关支持Mechanical Lock Switch Support + +本功能用于*机械自锁开关*比如[this Alps one](http://deskthority.net/wiki/Alps_SKCL_Lock)。你可以通过向`config.h`添加以下宏来使能该功能： + +``` +#define LOCKING_SUPPORT_ENABLE +#define LOCKING_RESYNC_ENABLE +``` + +在使能该功能后，要在键盘中使用`KC_LCAP`, `KC_LNUM` 和 `KC_LSCR`这三个键码。 + +远古机械键盘偶尔会有自锁机械开关，现在几乎没有了。***大多数情况下你不需要使用该功能，且要使用`KC_CAPS`, `KC_NLCK`和`KC_SLCK`这三个键码。*** + +## 输入ASCII之外的特殊字符比如Cédille 'Ç' +没有在所有系统中输入这个的通用方法。你要定义针对你的特定操作系统或布局的**宏**。 + +比如看这个**宏**代码的文章。 + +http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620 +<!--翻译问题：下方维基百科链接应全部替换为中文链接，暂未找到全部--> +在**Windows**上，可以用`AltGr`键或**Alt码**。 +* http://en.wikipedia.org/wiki/AltGr_key +* https://zh.wikipedia.org/wiki/Alt%E7%A0%81 + +在**Mac OS**定义`Option`键组合。 +* https://zh.wikipedia.org/wiki/Option%E9%94%AE#%E6%9B%BF%E4%BB%A3%E9%94%AE%E7%9B%98%E8%BE%93%E5%85%A5 + +在**Xorg**可以改用`compose`键。 +* http://en.wikipedia.org/wiki/Compose_key + +下方链接查看**Unicode**输入。 +* http://en.wikipedia.org/wiki/Unicode_input + +## macOS上的`Fn` + +不像大多数FN键，苹果上那个有自己的键码...呃，基本上算吧。 他取缔了基本6键无冲HID报告的第六个键码 -- 所以苹果键盘其实是5键无冲的。 + +技术上说QMK可以发送这个键。但是，这样做需要修改报告格式以添加FN键的状态。这还不是最糟糕的，你的键盘的VID和PID和真的苹果键盘不一样的话还不会被识别。 +QMK官方支持这个会被律师函的，所以就当我没说过。 + +详见[issue#2179](https://github.com/qmk/qmk_firmware/issues/2179)。 + + +## Mac OSX的媒体控制键 +#### KC_MNXT 和 KC_MPRV 在Mac上不好用 +使用 `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) 和 `KC_MRWD`(`KC_MEDIA_REWIND`)，不要用 `KC_MNXT` 和 `KC_MPRV`. +详见 https://github.com/tmk/tmk_keyboard/issues/195 + + +## Mac OSX中支持那些键? +你可以从此源码中获知在OSX中支持哪些键码 + +`usb_2_adb_keymap` 阵列映射 键盘/小键盘 页用于ADB扫描码(OSX内部键码). + +https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c + +`IOHIDConsumer::dispatchConsumerEvent`会处理用户页面用法。 +<!--翻译问题：上面那两句翻译的不好-> handles Consumer page usages. --> +https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp + + +## Mac OSX中的JIS键 +岛国特别键比如`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)`OSX是不是别的。You can use **Seil** to enable those keys, try following options. +<!--翻译问题：以上“岛国特别键”没有任何地域歧视的意思 --> +* 在电脑键盘上使能NFER键 +* 在电脑键盘上使能XFER键 +* 在电脑键盘上使能KATAKAN键 + +https://pqrs.org/osx/karabiner/seil.html + + +## RN-42蓝牙模块与Karabiner不能有效协同工作 +Karabiner - Mac OSX的改键软件 - 默认RN-42模块是不会被响应的。想要Karabiner和你的键盘协同工作你要使能此选项： +https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237 + +此问题详见下方链接。 +https://github.com/tmk/tmk_keyboard/issues/213 +https://github.com/tekezo/Karabiner/issues/403 + + +## Esc 和 <code>`</code> 双功能键 + +请见[Grave Escape](feature_grave_esc.md)功能。 + +## 右侧双角色修改键(诸如Shift、Alt等有修改其他键作用的键)变箭头键 +右侧修改键单击时会变为箭头键，长按就还是修改键。在TMK中双角色键称之为**TAP**. +``` + +#include "keymap_common.h" + + +/* 用TMK双角色键功能实现右侧修改键改箭头键 + * + * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role + * https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys + */ +const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + /* 0: qwerty */ + [0] = LAYOUT( \ + ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \ + TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \ + LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \ + LSFT,NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,FN0, ESC, \ + FN4, LGUI,LALT, SPC, APP, FN2, FN1, FN3), + [1] = LAYOUT( \ + GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \ + TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\ + TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ + TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \ + TRNS,TRNS,TRNS, TRNS, TRNS,FN7, FN6, FN8), +}; + +const uint16_t PROGMEM fn_actions[] = { + [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP), + [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN), + [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT), + [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT), + [4] = ACTION_LAYER_MOMENTARY(1), + [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP), + [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN), + [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME), + [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END), +}; + +``` + +双角色键说明: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys + + +## Mac OSX的弹出键 +`KC_EJCT` 键码在OSX可以使用 https://github.com/tmk/tmk_keyboard/issues/250 +似乎Windows10会忽略该键码，Linux/Xorg可以识别该键码但默认不映射。 + +目前尚不清楚如何在真正的苹果键盘按出弹出键。HHKB使用`F20`用于弹出键(`Fn+f`)，该功能在MAC模式有效但不保证与苹果弹出键码相符。 + + +## `action_util.c`中的 `weak_mods`和`real_mods`是什么 +___待改善___ + +real_mods 用于保存实际(物理)修改键的实际状态。 +weak_mods 用于保存虚拟或临时修改键，它将不会影响实际修改键。 + +以按下左侧Shift键然后输入ACTION_MODS_KEY(LSHIFT, KC_A)为例， + +在weak_mods时， +* (1) 按下不抬起左Shift: real_mods |= MOD_BIT(LSHIFT) +* (2) 按 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT) +* (3) 抬起 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT) +real_mods 还是保持在修改状态。 + +在没有weak_mods时， +* (1) 按下不抬起左Shift: real_mods |= MOD_BIT(LSHIFT) +* (2) 按 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT) +* (3) 抬起 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT) +此时real_mods失去‘实际左Shift’的状态。 + +weak_mods和real_mods现已全部加入键盘数据包发送豪华套餐。 +https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57 |