Browse Source
update the Chinese translation based on the latest English version (#14924)
Co-authored-by: peepeetee <43021794+peepeetee@users.noreply.github.com> Co-authored-by: Joy Lee <chang.li@westberrytech.com> Co-authored-by: LitoMore <LitoMore@users.noreply.github.com> Co-authored-by: Dasky <32983009+daskygit@users.noreply.github.com>pull/15931/head
IskandarMa
2 years ago
committed by
GitHub
GitHub
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
51 changed files with 3937 additions and 1353 deletions
Split View
Diff Options
-
+1 -1docs/configurator_step_by_step.md
-
+2 -2docs/contributing.md
-
+1 -1docs/easy_maker.md
-
+1 -1docs/other_eclipse.md
-
+28 -17docs/zh-cn/README.md
-
+191 -131docs/zh-cn/_summary.md
-
+73 -0docs/zh-cn/api_docs.md
-
+20 -0docs/zh-cn/api_overview.md
-
+43 -0docs/zh-cn/cli.md
-
+503 -0docs/zh-cn/cli_commands.md
-
+126 -0docs/zh-cn/cli_configuration.md
-
+32 -0docs/zh-cn/cli_tab_complete.md
-
+66 -0docs/zh-cn/configurator_architecture.md
-
+198 -0docs/zh-cn/configurator_default_keymaps.md
-
+63 -0docs/zh-cn/configurator_step_by_step.md
-
+31 -0docs/zh-cn/configurator_troubleshooting.md
-
+79 -109docs/zh-cn/contributing.md
-
+177 -190docs/zh-cn/custom_quantum_functions.md
-
+102 -0docs/zh-cn/driver_installation_zadig.md
-
+37 -0docs/zh-cn/easy_maker.md
-
+0 -6docs/zh-cn/faq.md
-
+39 -88docs/zh-cn/faq_build.md
-
+94 -94docs/zh-cn/faq_debug.md
-
+49 -10docs/zh-cn/faq_general.md
-
+89 -83docs/zh-cn/faq_keymap.md
-
+108 -0docs/zh-cn/faq_misc.md
-
+39 -0docs/zh-cn/feature_grave_esc.md
-
+70 -0docs/zh-cn/feature_space_cadet.md
-
+329 -0docs/zh-cn/flashing.md
-
+75 -0docs/zh-cn/flashing_bootloadhid.md
-
+59 -0docs/zh-cn/getting_started_docker.md
-
+0 -15docs/zh-cn/getting_started_getting_help.md
-
+6 -1docs/zh-cn/getting_started_github.md
-
+7 -2docs/zh-cn/getting_started_introduction.md
-
+61 -0docs/zh-cn/getting_started_vagrant.md
-
+209 -0docs/zh-cn/keymap.md
-
+143 -0docs/zh-cn/mod_tap.md
-
+21 -15docs/zh-cn/newbs.md
-
+0 -163docs/zh-cn/newbs_best_practices.md
-
+37 -50docs/zh-cn/newbs_building_firmware.md
-
+18 -0docs/zh-cn/newbs_building_firmware_configurator.md
-
+67 -250docs/zh-cn/newbs_flashing.md
-
+158 -52docs/zh-cn/newbs_getting_started.md
-
+28 -8docs/zh-cn/newbs_learn_more_resources.md
-
+7 -39docs/zh-cn/newbs_testing_debugging.md
-
+200 -0docs/zh-cn/reference_configurator_support.md
-
+56 -25docs/zh-cn/reference_glossary.md
-
+22 -0docs/zh-cn/support.md
-
+77 -0docs/zh-cn/syllabus.md
-
+60 -0docs/zh-cn/translating.md
-
+35 -0docs/zh-cn/zh_cn_doc_status.sh
+ 1
- 1
docs/configurator_step_by_step.md
View File
+ 2
- 2
docs/contributing.md
View File
+ 1
- 1
docs/easy_maker.md
View File
+ 1
- 1
docs/other_eclipse.md
View File
+ 28
- 17
docs/zh-cn/README.md
View File
| @ -1,31 +1,42 @@ | |||
| # QMK机械键盘固件 | |||
| # Quantum Mechanical Keyboard固件 | |||
| [](https://github.com/qmk/qmk_firmware/tags) | |||
| [](https://discord.gg/Uq7gcHh) | |||
| [](https://docs.qmk.fm) | |||
| [](https://github.com/qmk/qmk_firmware/pulse/monthly) | |||
| [](https://github.com/qmk/qmk_firmware/) | |||
| <!--- | |||
| original document: 0.15.12:docs/README.md | |||
| git diff 0.15.12 HEAD -- docs/README.md | cat | |||
| --> | |||
| ## 什么是 QMK 固件? | |||
| QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包括 QMK 固件, QMK 工具箱, qmk.fm网站, 和这些文档。QMK 固件是一个基于[tmk\_keyboard](https://github.com/tmk/tmk_keyboard)的键盘固件，它在爱特梅尔AVR微控制器实现一些有用的功能,确切地说, 是在 [OLKB product line](https://olkb.com), 在 [ErgoDox EZ](https://www.ergodox-ez.com) 键盘, 和 [Clueboard product line](https://clueboard.co/). 上。它被移植到使用ChibiOS的ARM芯片上. 它可以在飞线键盘或定制PCB键盘中发挥功能. | |||
| QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的用于开发计算机输入设备的开源软件。社区专注像键盘，鼠标，MIDI设备的各种电子输入设备。社区内的核心小组成员维护[QMK固件](https://github.com/qmk/qmk_firmware)，[QMK配置器](https://config.qmk.fm)（QMK Configurator），[QMK工具箱](https://github.com/qmk/qmk_toolbox)（QMK Toolbox），[qmk.fm](https://qmk.fm)，并与各位社区成员维护这份文档。 | |||
| ## 如何得到它 | |||
| ## 如何入门 | |||
| 如果你打算贡献布局, 键盘, 或者其他QMK特性, 一下是最简单的方法：[从GitHub获得repo分支](https://github.com/qmk/qmk_firmware#fork-destination-box), 并克隆你的repo到本地进行编辑，推送，然后从你的分支打开 [Pull Request](https://github.com/qmk/qmk_firmware/pulls). | |||
| <div class="flex-container"> | |||
| 此外, 你也可以直接下载 ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), 或者从git克隆 (`git@github.com:qmk/qmk_firmware.git`), 或 https (`https://github.com/qmk/qmk_firmware.git`). | |||
| ?> **基础方式** [QMK配置器](zh-cn/newbs_building_firmware_configurator.md) <br> | |||
| 用户友好的图形界面工具，无需具备编程知识基础。 | |||
| ## 如何编译 | |||
| ?> **进阶方式** [基于源代码](zh-cn/newbs.md) <br> | |||
| 功能更强大，但门槛较高。 | |||
| 在你能编译之前, 你需要[部署环境](zh-cn/getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: | |||
| </div> | |||
| make planck/rev4:default | |||
| ## 个性化定制 | |||
| 这将建立 `planck`的`rev4` 修订版本并使用 `default`布局。并非所有键盘都有修订版本 (也叫做子项目或文件夹)，在此情况下，修订版本可以省略，如下: | |||
| QMK提供了很多功能，对应着很多可供浏览的配套文档。大部分功能都是通过修改[键映射](zh-cn/keymap.md)及[键码](zh-cn/keycodes.md)实现的。 | |||
| make preonic:default | |||
| ## 需要帮助？ | |||
| ## 如何定制 | |||
| 请查阅[寻求帮助页面](zh-cn/support.md)以了解如何获取QMK使用方法的帮助。 | |||
| QMK 有许多 [特性](zh-cn/features.md)来探索，也有很多 [参考文档](https://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](zh-cn/keymap.md)和[键码](zh-cn/keycodes.md)来利用许多特性。 | |||
| ## 回馈社区 | |||
| 有多种回馈社区的方法，最简单的方法是开始使用QMK并向你的朋友们推荐它。 | |||
| * 可以在我们的论坛及聊天室进行互助： | |||
| * [/r/olkb](https://www.reddit.com/r/olkb/) | |||
| * [Discord服务器](https://discord.gg/Uq7gcHh) | |||
| * 点击页面下方的“Edit This Page”，可以对文档提供贡献。 | |||
| * [将这份文档翻译为你的语言](zh-cn/translating.md) | |||
| * [上报bug](https://github.com/qmk/qmk_firmware/issues/new/choose) | |||
| * [发起Pull Request](zh-cn/contributing.md) | |||
+ 191
- 131
docs/zh-cn/_summary.md
View File
| @ -1,133 +1,193 @@ | |||
| * [完全菜鸟指南](zh-cn/newbs.md) | |||
| <!--for translators, see first: zh-cn/reference_glossary.md#terms-of-zh-cn-translate --> | |||
| * 新手教程 | |||
| * [介绍](zh-cn/newbs.md) | |||
| * [入门](zh-cn/newbs_getting_started.md) | |||
| * [构建你的第一个固件](zh-cn/newbs_building_firmware.md) | |||
| * [刷新固件](zh-cn/newbs_flashing.md) | |||
| * [测试和调试](zh-cn/newbs_testing_debugging.md) | |||
| * [Git最佳实践](zh-cn/newbs_git_best_practices.md) | |||
| * [使用你分叉(fork)的主分支(master)](zh-cn/newbs_git_using_your_master_branch.md) | |||
| * [解决合并冲突](zh-cn/newbs_git_resolving_merge_conflicts.md) | |||
| * [重新同步一个分支](zh-cn/newbs_git_resynchronize_a_branch.md) | |||
| * [学习资源](zh-cn/newbs_learn_more_resources.md) | |||
| * [QMK基础](zh-cn/README.md) | |||
| * [QMK简介](zh-cn/getting_started_introduction.md) | |||
| * [QMK命令行工具](zh-cn/cli.md) | |||
| * [QMK命令行工具配置](zh-cn/cli_configuration.md) | |||
| * [向QMK贡献代码](zh-cn/contributing.md) | |||
| * [如何使用GitHub](zh-cn/getting_started_github.md) | |||
| * [获得帮助](zh-cn/getting_started_getting_help.md) | |||
| * [非兼容性修改](zh-cn/breaking_changes.md) | |||
| * [我的PR已经被标记为非兼容性修改](zh-cn/breaking_changes_instructions.md) | |||
| * [2019年8月30日](zh-cn/ChangeLog/20190830.md) | |||
| * [问题与解答](zh-cn/faq.md) | |||
| * [一般问题](zh-cn/faq_general.md) | |||
| * [构建/编译](zh-cn/faq_build.md) | |||
| * [调试/故障排除](zh-cn/faq_debug.md) | |||
| * [布局](zh-cn/faq_keymap.md) | |||
| * [Zadig驱动安装](zh-cn/driver_installation_zadig.md) | |||
| * 详细指南 | |||
| * [安装构建工具](zh-cn/getting_started_build_tools.md) | |||
| * [vagrant指南](zh-cn/getting_started_vagrant.md) | |||
| * [构建/编译指南](zh-cn/getting_started_make_guide.md) | |||
| * [刷新固件](zh-cn/flashing.md) | |||
| * [定制功能](zh-cn/custom_quantum_functions.md) | |||
| * [布局概述](zh-cn/keymap.md) | |||
| * [硬件](zh-cn/hardware.md) | |||
| * [兼容的单片机](zh-cn/compatible_microcontrollers.md) | |||
| * [AVR处理器](zh-cn/hardware_avr.md) | |||
| * [驱动](zh-cn/hardware_drivers.md) | |||
| * 参考 | |||
| * [键盘指南](zh-cn/hardware_keyboard_guidelines.md) | |||
| * [配置选项](zh-cn/config_options.md) | |||
| * [键码](zh-cn/keycodes.md) | |||
| * [代码书写规范 - C](zh-cn/coding_conventions_c.md) | |||
| * [代码书写规范 - Python](zh-cn/coding_conventions_python.md) | |||
| * [文档书写规范](zh-cn/documentation_best_practices.md) | |||
| * [文档模板](zh-cn/documentation_templates.md) | |||
| * [构建第一个固件](zh-cn/newbs_building_firmware.md) | |||
| * [刷写固件](zh-cn/newbs_flashing.md) | |||
| * [寻求帮助](zh-cn/support.md) | |||
| * [其它资源](zh-cn/newbs_learn_more_resources.md) | |||
| * [QMK大纲](zh-cn/syllabus.md) | |||
| * FAQ | |||
| * [常规FAQ](zh-cn/faq_general.md) | |||
| * [构建/编译QMK](zh-cn/faq_build.md) | |||
| * [QMK问题排查](zh-cn/faq_misc.md) | |||
| * [调试QMK](zh-cn/faq_debug.md) | |||
| * [键映射FAQ](zh-cn/faq_keymap.md) | |||
| * [充分利用AVR的存储空间](zh-cn/squeezing_avr.md) | |||
| * [术语表](zh-cn/reference_glossary.md) | |||
| * [单元测试](zh-cn/unit_testing.md) | |||
| * [实用函数](zh-cn/ref_functions.md) | |||
| * [配置器支持](zh-cn/reference_configurator_support.md) | |||
| * [info.json 格式](zh-cn/reference_info_json.md) | |||
| * [Python 命令行开发](zh-cn/cli_development.md) | |||
| * [特性](zh-cn/features.md) | |||
| * [基本键码](zh-cn/keycodes_basic.md) | |||
| * [US ANSI控制码](zh-cn/keycodes_us_ansi_shifted.md) | |||
| * [量子键码](zh-cn/quantum_keycodes.md) | |||
| * [高级键码](zh-cn/feature_advanced_keycodes.md) | |||
| * [音频](zh-cn/feature_audio.md) | |||
| * [自动shift](zh-cn/feature_auto_shift.md) | |||
| * [背光](zh-cn/feature_backlight.md) | |||
| * [蓝牙](zh-cn/feature_bluetooth.md) | |||
| * [热改键](zh-cn/feature_bootmagic.md) | |||
| * [组合](zh-cn/feature_combo) | |||
| * [命令](zh-cn/feature_command.md) | |||
| * [消抖 API](zh-cn/feature_debounce_type.md) | |||
| * [拨动开关](zh-cn/feature_dip_switch.md) | |||
| * [动态宏指令](zh-cn/feature_dynamic_macros.md) | |||
| * [编码器](zh-cn/feature_encoders.md) | |||
| * [重音号Esc复合键](zh-cn/feature_grave_esc.md) | |||
| * [触摸反馈](zh-cn/feature_haptic_feedback.md) | |||
| * [HD44780 LCD控制器](zh-cn/feature_hd44780.md) | |||
| * [自锁键](zh-cn/feature_key_lock.md) | |||
| * [布局](zh-cn/feature_layouts.md) | |||
| * [前导键](zh-cn/feature_leader_key.md) | |||
| * [LED阵列](zh-cn/feature_led_matrix.md) | |||
| * [宏指令](zh-cn/feature_macros.md) | |||
| * [鼠标键](zh-cn/feature_mouse_keys.md) | |||
| * [OLED驱动](zh-cn/feature_oled_driver.md) | |||
| * [一键功能](zh-cn/one_shot_keys.md) | |||
| * [指针设备](zh-cn/feature_pointing_device.md) | |||
| * [PS/2鼠标](zh-cn/feature_ps2_mouse.md) | |||
| * [RGB灯光](zh-cn/feature_rgblight.md) | |||
| * [RGB矩阵](zh-cn/feature_rgb_matrix.md) | |||
| * [空格候补换挡](zh-cn/feature_space_cadet.md) | |||
| * [分体键盘](zh-cn/feature_split_keyboard.md) | |||
| * [速录机](zh-cn/feature_stenography.md) | |||
| * [换手](zh-cn/feature_swap_hands.md) | |||
| * [多击键](zh-cn/feature_tap_dance.md) | |||
| * [终端](zh-cn/feature_terminal.md) | |||
| * [热敏打印机](zh-cn/feature_thermal_printer.md) | |||
| * [Unicode](zh-cn/feature_unicode.md) | |||
| * [用户空间](zh-cn/feature_userspace.md) | |||
| * [速度键](zh-cn/feature_velocikey.md) | |||
| * 制造和定制者指南 | |||
| * [手工连线指南](zh-cn/hand_wire.md) | |||
| * [ISP刷新指南](zh-cn/isp_flashing_guide.md) | |||
| * [ARM调试指南](zh-cn/arm_debugging.md) | |||
| * [ADC设备](zh-cn/adc_driver.md) | |||
| * [I2C设备](zh-cn/i2c_driver.md) | |||
| * [SPI设备](zh-cn/spi_driver.md) | |||
| * [WS2812设备](zh-cn/ws2812_driver.md) | |||
| * [EEPROM设备](zh-cn/eeprom_driver.md) | |||
| * [GPIO控制](zh-cn/internals_gpio_control.md) | |||
| * [自定义键盘矩阵](zh-cn/custom_matrix.md) | |||
| * [Proton C转换](zh-cn/proton_c_conversion.md) | |||
| * 深入了解 | |||
| * [键盘工作原理](zh-cn/how_keyboards_work.md) | |||
| * [深入了解QMK](zh-cn/understanding_qmk.md) | |||
| * 其他话题 | |||
| * [使用Eclipse开发QMK](zh-cn/other_eclipse.md) | |||
| * [使用VSCode开发QMK](zh-cn/other_vscode.md) | |||
| * [支持](zh-cn/getting_started_getting_help.md) | |||
| * [翻译QMK文档](zh-cn/translating.md) | |||
| * QMK 内构 (正在编写) | |||
| * [定义](zh-cn/internals_defines.md) | |||
| * [输入回调寄存器](zh-cn/internals_input_callback_reg.md) | |||
| * [Midi设备](zh-cn/internals_midi_device.md) | |||
| * [Midi设备配置过程](zh-cn/internals_midi_device_setup_process.md) | |||
| * [Midi工具库](zh-cn/internals_midi_util.md) | |||
| * [发送函数](zh-cn/internals_send_functions.md) | |||
| * [Sysex工具](zh-cn/internals_sysex_tools.md) | |||
| <!--fromen:20200126-6:03AM(GMT+8)--> | |||
| <!--cn:20200211-11:04AM(GMT+8)--> | |||
| * 配置器(Configurator) | |||
| * [总览](zh-cn/newbs_building_firmware_configurator.md) | |||
| * [入门](zh-cn/configurator_step_by_step.md) | |||
| * [问题排查](zh-cn/configurator_troubleshooting.md) | |||
| * [框架](zh-cn/configurator_architecture.md) | |||
| * QMK API | |||
| * [总览](zh-cn/api_overview.md) | |||
| * [API文档](zh-cn/api_docs.md) | |||
| * [键盘支持](zh-cn/reference_configurator_support.md) | |||
| * [添加默认键映射](zh-cn/configurator_default_keymaps.md) | |||
| * CLI | |||
| * [总览](zh-cn/cli.md) | |||
| * [配置](zh-cn/cli_configuration.md) | |||
| * [命令](zh-cn/cli_commands.md) | |||
| * [Tab补全](zh-cn/cli_tab_complete.md) | |||
| * 使用QMK | |||
| * 导览 | |||
| * [功能定制](zh-cn/custom_quantum_functions.md) | |||
| * [利用Zadig安装驱动](zh-cn/driver_installation_zadig.md) | |||
| * [极简式制作](zh-cn/easy_maker.md) | |||
| * [键映射总览](zh-cn/keymap.md) | |||
| * 开发环境 | |||
| * [Docker指南](zh-cn/getting_started_docker.md) | |||
| * [Vagrant指南](zh-cn/getting_started_vagrant.md) | |||
| * 刷写(Flashing) | |||
| * [刷写](zh-cn/flashing.md) | |||
| * [刷写ATmega32A (ps2avrgb)](zh-cn/flashing_bootloadhid.md) | |||
| * IDE | |||
| * [在Eclipse中使用QMK](zh-cn/other_eclipse.md) | |||
| * [在VSCode中使用QMK](zh-cn/other_vscode.md) | |||
| * Git最佳实践 | |||
| * [介绍](zh-cn/newbs_git_best_practices.md) | |||
| * [你自己的副本](zh-cn/newbs_git_using_your_master_branch.md) | |||
| * [冲突合并](zh-cn/newbs_git_resolving_merge_conflicts.md) | |||
| * [基于你的分支修复](zh-cn/newbs_git_resynchronize_a_branch.md) | |||
| * 键盘组装 | |||
| * [飞线指南](zh-cn/hand_wire.md) | |||
| * [ISP刷写指南](zh-cn/isp_flashing_guide.md) | |||
| * 键码入门 | |||
| * [键码汇总](zh-cn/keycodes.md) | |||
| * [基础键码](zh-cn/keycodes_basic.md) | |||
| * [语言特定的键码](zh-cn/reference_keymap_extras.md) | |||
| * [修饰键](zh-cn/feature_advanced_keycodes.md) | |||
| * [原子键码](zh-cn/quantum_keycodes.md) | |||
| * [Magic键码](zh-cn/keycodes_magic.md) | |||
| * 键码进阶 | |||
| * [指令](zh-cn/feature_command.md) | |||
| * [动态宏](zh-cn/feature_dynamic_macros.md) | |||
| * [Grave Escape](zh-cn/feature_grave_esc.md) | |||
| * [前导键](zh-cn/feature_leader_key.md) | |||
| * [Mod-Tap](zh-cn/mod_tap.md) | |||
| * [宏](zh-cn/feature_macros.md) | |||
| * [鼠标键](zh-cn/feature_mouse_keys.md) | |||
| * [Space Cadet Shift](zh-cn/feature_space_cadet.md) | |||
| * [US ANSI上档键值](zh-cn/keycodes_us_ansi_shifted.md) | |||
| * 软件特性 | |||
| * [自动Shift](zh-cn/feature_auto_shift.md) | |||
| * [组合键](zh-cn/feature_combo.md) | |||
| * [防抖API](zh-cn/feature_debounce_type.md) | |||
| * [按键锁定](zh-cn/feature_key_lock.md) | |||
| * [按键重定义](zh-cn/feature_key_overrides.md) | |||
| * [层](zh-cn/feature_layers.md) | |||
| * [粘滞键](zh-cn/one_shot_keys.md) | |||
| * [光标设备](zh-cn/feature_pointing_device.md) | |||
| * [原生HID](zh-cn/feature_rawhid.md) | |||
| * [Sequencer](zh-cn/feature_sequencer.md) | |||
| * [换手](zh-cn/feature_swap_hands.md) | |||
| * [一键多用](zh-cn/feature_tap_dance.md) | |||
| * [点按配置](zh-cn/tap_hold.md) | |||
| * [终端](zh-cn/feature_terminal.md) | |||
| * [Unicode](zh-cn/feature_unicode.md) | |||
| * [用户空间](zh-cn/feature_userspace.md) | |||
| * [WPM计算](zh-cn/feature_wpm.md) | |||
| * 硬件特性 | |||
| * 显示 | |||
| * [HD44780 LCD控制器](zh-cn/feature_hd44780.md) | |||
| * [ST7565 LCD驱动](zh-cn/feature_st7565.md) | |||
| * [OLED驱动](zh-cn/feature_oled_driver.md) | |||
| * 灯效 | |||
| * [背光](zh-cn/feature_backlight.md) | |||
| * [LED矩阵](zh-cn/feature_led_matrix.md) | |||
| * [RGB灯光](zh-cn/feature_rgblight.md) | |||
| * [RGB矩阵](zh-cn/feature_rgb_matrix.md) | |||
| * [音频](zh-cn/feature_audio.md) | |||
| * [蓝牙](zh-cn/feature_bluetooth.md) | |||
| * [Bootmagic Lite](zh-cn/feature_bootmagic.md) | |||
| * [自定义矩阵](zh-cn/custom_matrix.md) | |||
| * [Digitizer](zh-cn/feature_digitizer.md) | |||
| * [拨动开关（DIP Switch）](zh-cn/feature_dip_switch.md) | |||
| * [编码器（旋钮）](zh-cn/feature_encoders.md) | |||
| * [触摸反馈](zh-cn/feature_haptic_feedback.md) | |||
| * [摇杆](zh-cn/feature_joystick.md) | |||
| * [LED指示](zh-cn/feature_led_indicators.md) | |||
| * [MIDI](zh-cn/feature_midi.md) | |||
| * [Proton C转换](zh-cn/proton_c_conversion.md) | |||
| * [PS/2鼠标](zh-cn/feature_ps2_mouse.md) | |||
| * [分体式键盘](zh-cn/feature_split_keyboard.md) | |||
| * [速记](zh-cn/feature_stenography.md) | |||
| * [热敏打印机](zh-cn/feature_thermal_printer.md) | |||
| * [Velocikey](zh-cn/feature_velocikey.md) | |||
| * QMK开发 | |||
| * [PR Checklist](zh-cn/pr_checklist.md) | |||
| * 打破兼容的改动 | |||
| * [总览](zh-cn/breaking_changes.md) | |||
| * [我的PR已打上标记](zh-cn/breaking_changes_instructions.md) | |||
| * [近期的变更日志(Changelog)](zh-cn/ChangeLog/20210529.md "QMK v0.13.0 - 2021 May 29") | |||
| * [更早期的不兼容改动](zh-cn/breaking_changes_history.md) | |||
| * C语言开发 | |||
| * [ARM调试指引](zh-cn/arm_debugging.md) | |||
| * [AVR处理器](zh-cn/hardware_avr.md) | |||
| * [C编码规范](zh-cn/coding_conventions_c.md) | |||
| * [兼容的微处理器](zh-cn/compatible_microcontrollers.md) | |||
| * [驱动](zh-cn/hardware_drivers.md) | |||
| * [ADC驱动](zh-cn/adc_driver.md) | |||
| * [Audio驱动](zh-cn/audio_driver.md) | |||
| * [I2C驱动](zh-cn/i2c_driver.md) | |||
| * [SPI驱动](zh-cn/spi_driver.md) | |||
| * [WS2812驱动](zh-cn/ws2812_driver.md) | |||
| * [EEPROM驱动](zh-cn/eeprom_driver.md) | |||
| * [串口驱动](zh-cn/serial_driver.md) | |||
| * [UART驱动](zh-cn/uart_driver.md) | |||
| * [操控GPIO](zh-cn/internals_gpio_control.md) | |||
| * [键盘开发指引](zh-cn/hardware_keyboard_guidelines.md) | |||
| * Python开发 | |||
| * [编码规范](zh-cn/coding_conventions_python.md) | |||
| * [QMK CLI开发](zh-cn/cli_development.md) | |||
| * 配置器开发 | |||
| * QMK API | |||
| * [开发环境](zh-cn/api_development_environment.md) | |||
| * [架构总览](zh-cn/api_development_overview.md) | |||
| * 硬件平台开发 | |||
| * Arm/ChibiOS | |||
| * [选择MCU](zh-cn/platformdev_selecting_arm_mcu.md) | |||
| * [启动引导](zh-cn/platformdev_chibios_earlyinit.md) | |||
| * QMK参考信息 | |||
| * [参与到QMK](zh-cn/contributing.md) | |||
| * [翻译QMK文档](zh-cn/translating.md)<!--but should we translate this? currently keep it fallback--> | |||
| * [配置](zh-cn/config_options.md) | |||
| * [数据驱动配置](zh-cn/data_driven_config.md) | |||
| * [Make指引](zh-cn/getting_started_make_guide.md) | |||
| * [编写文档的最佳实践](zh-cn/documentation_best_practices.md) | |||
| * [文档模板](zh-cn/documentation_templates.md) | |||
| * [贡献配列到社区](zh-cn/feature_layouts.md) | |||
| * [单元测试](zh-cn/unit_testing.md) | |||
| * [常用函数](zh-cn/ref_functions.md) | |||
| * [info.json参考资料](zh-cn/reference_info_json.md) | |||
| * 深入了解 | |||
| * [键盘工作原理](zh-cn/how_keyboards_work.md) | |||
| * [键盘矩阵原理](zh-cn/how_a_matrix_works.md) | |||
| * [了解QMK](zh-cn/understanding_qmk.md) | |||
| * QMK内部细节 (编辑中) | |||
| * [定义](zh-cn/internals_defines.md) | |||
| * [输入回调的注册](zh-cn/internals_input_callback_reg.md) | |||
| * [Midi设备](zh-cn/internals_midi_device.md) | |||
| * [Midi设备驱动流程](zh-cn/internals_midi_device_setup_process.md) | |||
| * [Midi辅助功能](zh-cn/internals_midi_util.md) | |||
| * [发送函数](zh-cn/internals_send_functions.md) | |||
| * [Sysex工具](zh-cn/internals_sysex_tools.md) | |||
| <!--fromen:20211014-12:00(GMT+8) commit 04cf161aa01fd433b5dae69d9fd31569ed5dca59--> | |||
+ 73
- 0
docs/zh-cn/api_docs.md
View File
| @ -0,0 +1,73 @@ | |||
| # QMK API | |||
| <!--- | |||
| original document: 0.15.12:docs/api_docs.md | |||
| git diff 0.15.12 HEAD -- docs/api_docs.md | cat | |||
| --> | |||
| 本章节详述了QMK API的使用方法，若您是应用开发者，使用这套API可以实现[QMK](https://qmk.fm)键盘固件的编译支持。 | |||
| ## 总览 | |||
| 本服务提供了一套用于编译自定义键映射的异步API，通过POST方式发送JSON参数到API，定期检查执行状态，待固件编译完成后，即可下载生成的固件文件和固件的源文件（如果需要的话）。 | |||
| #### 荷载JSON参数示例： | |||
| ```json | |||
| { | |||
| "keyboard": "clueboard/66/rev2", | |||
| "keymap": "my_awesome_keymap", | |||
| "layout": "LAYOUT_all", | |||
| "layers": [ | |||
| ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"], | |||
| ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"], | |||
| ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","RESET","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"] | |||
| ] | |||
| } | |||
| ``` | |||
| 如上可见，荷载参数里有用于生成固件文件的所有键盘信息。每一个层定义都包含了与键盘 `LAYOUT` 宏定义一致的QMK键码列表数据，若该键盘有多个支持的 `LAYOUT` 宏定义，也可以指定使用的是哪一个。 | |||
| ## 提交一个编译job | |||
| 若要将键映射配置编译成固件文件，仅需将JSON参数通过POST发送至 `/v1/compile` 节点。下面的示例中我们假设JSON荷载参数已存放在 `json_data` 文件中。 | |||
| ``` | |||
| $ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile | |||
| { | |||
| "enqueued": true, | |||
| "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6" | |||
| } | |||
| ``` | |||
| ## 检查状态 | |||
| 键映射配置提交后，可以简单地通过 HTTP GET 请求来查询job状态： | |||
| ``` | |||
| $ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6 | |||
| { | |||
| "created_at": "Sat, 19 Aug 2017 21:39:12 GMT", | |||
| "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT", | |||
| "id": "f5f9b992-73b4-479b-8236-df1deb37c163", | |||
| "status": "running", | |||
| "result": null | |||
| } | |||
| ``` | |||
| 这份信息告诉我们编译job已经提交到队列中且正在执行。job的状态有5种： | |||
| * **failed（失败）**: 编译服务出现问题。 | |||
| * **finished（完成）**: 编译已完成，`result` 字段中保存了编译结果。 | |||
| * **queued（排队中）**: 键映射job在等待可用的编译服务器。 | |||
| * **running（执行中）**: 编译进行中，应当很快就会结束。 | |||
| * **unknown（未知）**: 出现了较严重的错误，请给我们[提交一个bug](https://github.com/qmk/qmk_compiler/issues). | |||
| ## 确认编译产出 | |||
| 编译job完成后请查看 `result` 字段，该字段下保存了如下信息项的哈希表数据： | |||
| * `firmware_binary_url`: 用于刷写的固件文件URL列表 | |||
| * `firmware_keymap_url`: `keymap.c` 文件URL列表 | |||
| * `firmware_source_url`: 完整的固件源代码URL列表 | |||
| * `output`: 编译job的stdout及stderr输出信息，所有错误信息都会在这里。 | |||
+ 20
- 0
docs/zh-cn/api_overview.md
View File
| @ -0,0 +1,20 @@ | |||
| # QMK API | |||
| <!--- | |||
| original document: 0.15.12:docs/api_overview.md | |||
| git diff 0.15.12 HEAD -- docs/api_overview.md | cat | |||
| --> | |||
| QMK API提供了一套可用于Web及GUI工具可用的异步API，用于实现将任何[QMK](https://qmk.fm/)支持的键盘的键映射方案进行编译。已有的键映射模板支持所有的QMK键码并且不需要额外的C代码需求。键盘的维护团队可以提供新的模板来启用更多功能的支持。 | |||
| ## App开发者 | |||
| 若您是一位意愿将这套API引入您的程序中的移动端App开发者，请参阅[API使用指引](zh-cn/api_docs.md)。 | |||
| ## 键盘维护团队 | |||
| 若您希望强化您维护的键盘方案在QMK编译API中的支持，请参阅[键盘支持](zh-cn/reference_configurator_support.md)。 | |||
| ## 后端开发者 | |||
| 若您对这套API系统本身感兴趣，请参阅[开发环境](zh-cn/api_development_environment.md)搭建环境并继续深入探索[架构总览](zh-cn/api_development_overview.md)。 | |||
+ 43
- 0
docs/zh-cn/cli.md
View File
| @ -0,0 +1,43 @@ | |||
| # QMK CLI :id=qmk-cli | |||
| <!--- | |||
| original document: 0.15.12:docs/cli.md | |||
| git diff 0.15.12 HEAD -- docs/cli.md | cat | |||
| --> | |||
| ## 总览 :id=overview | |||
| QMK CLI可以让构建QMK键盘的过程更轻松一些，我们已提供的一批指令可用于简化及流式化地处理一些常见工作，如获取并编译QMK固件，创建新的键映射等。 | |||
| ### 依赖项 :id=requirements | |||
| QMK依赖Python 3.6或更高版本。我们已经尽力缩减依赖项，但在[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt)中的依赖项是需安装的包。在安装QMK CLI时这些依赖项也会自动完成安装。 | |||
| ### 通过 Homebrew 安装(macOS 及部分 Linux) :id=install-using-homebrew | |||
| 若已安装[Homebrew](https://brew.sh)，可以按如下方法安装QMK: | |||
| ``` | |||
| brew install qmk/qmk/qmk | |||
| export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径 | |||
| qmk setup # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境 | |||
| ``` | |||
| ### 通过 pip 安装 :id=install-using-easy_install-or-pip | |||
| 未在以上列出的操作系统可以手动安装QMK。首先确认已安装Python 3.6（或更高版本）及 pip，然后通过如下指令安装QMK： | |||
| ``` | |||
| python3 -m pip install qmk | |||
| export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径 | |||
| qmk setup # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境 | |||
| ``` | |||
| ### 其它操作系统的安装包 :id=packaging-for-other-operating-systems | |||
| 我们正在寻求可以制作维护更多操作系统下可用的 `qmk` 安装包的开发者，若您愿意为您的操作系统制作安装包，请遵循如下指引： | |||
| * 当该系统下的最佳实践与本指引冲突时，请遵循系统的最佳实践方案 | |||
| * 但请在注释中列明此处违反这份指引的原因 | |||
| * 在 virtualenv 下安装 | |||
| * 指引用户去设置 `QMK_HOME` 环境变量，使得固件源文件拉取路径不再是默认的 `~/qmk_firmware` | |||
+ 503
- 0
docs/zh-cn/cli_commands.md
View File
| @ -0,0 +1,503 @@ | |||
| # QMK CLI 命令 | |||
| <!--- | |||
| original document: 0.15.12:docs/cli_commands.md | |||
| git diff 0.15.12 HEAD -- docs/cli_commands.md | cat | |||
| --> | |||
| # 用户命令 | |||
| ## `qmk compile` | |||
| 该命令用于在指定目录下编译固件，可用于构建<https://config.qmk.fm>导出的JSON数据，代码库中的键映射，或是当前目录下的键盘。 | |||
| 该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 | |||
| **用于配置器导出的数据时**： | |||
| ``` | |||
| qmk compile [-c] <configuratorExport.json> | |||
| ``` | |||
| **用于键映射时**： | |||
| ``` | |||
| qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] -kb <keyboard_name> -km <keymap_name> | |||
| ``` | |||
| **在键盘目录下时**： | |||
| 须在存在默认键映射的键盘目录下执行，或是在键盘的键映射子目录下，否则须指定参数 `--keymap <keymap_name>` | |||
| ``` | |||
| qmk compile | |||
| ``` | |||
| **构建所有支持该键映射的键盘时**： | |||
| ``` | |||
| qmk compile -kb all -km <keymap_name> | |||
| ``` | |||
| **示例**： | |||
| ``` | |||
| $ qmk config compile.keymap=default | |||
| $ cd ~/qmk_firmware/keyboards/planck/rev6 | |||
| $ qmk compile | |||
| Ψ Compiling keymap with make planck/rev6:default | |||
| ... | |||
| ``` | |||
| 指定键映射参数时 | |||
| ``` | |||
| $ cd ~/qmk_firmware/keyboards/clueboard/66/rev4 | |||
| $ qmk compile -km 66_iso | |||
| Ψ Compiling keymap with make clueboard/66/rev4:66_iso | |||
| ... | |||
| ``` | |||
| 位于键盘目录下时 | |||
| ``` | |||
| $ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak | |||
| $ qmk compile | |||
| Ψ Compiling keymap with make make gh60/satan:colemak | |||
| ... | |||
| ``` | |||
| **在配列目录下时**： | |||
| 必须是在 `qmk_firmware/layouts/` 下的键映射目录下。 | |||
| ``` | |||
| qmk compile -kb <keyboard_name> | |||
| ``` | |||
| **示例**： | |||
| ``` | |||
| $ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi | |||
| $ qmk compile -kb dz60 | |||
| Ψ Compiling keymap with make dz60:mechmerlin-ansi | |||
| ... | |||
| ``` | |||
| **并行编译**： | |||
| 在编译时添加 `-j`/`--parallel` 开关可能有助于加快编译速度。 | |||
| ``` | |||
| qmk compile -j <num_jobs> -kb <keyboard_name> | |||
| ``` | |||
| `num_jobs` 用于指定并行的job上限，将其设置为0可以实现无限制的并行编译。 | |||
| ``` | |||
| qmk compile -j 0 -kb <keyboard_name> | |||
| ``` | |||
| ## `qmk flash` :id=qmk-flash | |||
| 该命令与 `qmk compile` 类似，但额外地可以指定bootloader。bootloader参数是可选的，默认会指定为 `:flash`。可通过 `-bl <bootloader>` 来指定bootloader。请查阅[刷写固件](zh-cn/flashing.md)指引以深入了解可用的bootloader信息。 | |||
| 该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 | |||
| **用于配置器导出的数据时**： | |||
| ``` | |||
| qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] <configuratorExport.json> | |||
| ``` | |||
| **用于键映射时**： | |||
| ``` | |||
| qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] | |||
| ``` | |||
| **列出所有bootloader** | |||
| ``` | |||
| qmk flash -b | |||
| ``` | |||
| ## `qmk config` | |||
| 该命令用于配置QMK功能，完整的 `qmk config` 文档参见[CLI配置](zh-cn/cli_configuration.md)。 | |||
| **使用方法**： | |||
| ``` | |||
| qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] | |||
| ``` | |||
| ## `qmk cd` | |||
| 该命令会启动一个新的 shell 会话并定位到 `qmk_firmware` 所在目录。 | |||
| 须留意如果你已经位于 `QMK_HOME` 下的某个位置（比如 `keyboards/` 目录中），该指令不会生效。 | |||
| 若要退回到原来的 shell 会话，只需要执行 `exit`。 | |||
| **使用方法**: | |||
| ``` | |||
| qmk cd | |||
| ``` | |||
| ## `qmk console` | |||
| 该命令用于连接键盘终端并展示调试信息。仅当键盘固件通过 `CONSOLE_ENABLE=yes` 编译时有效。 | |||
| **用法**： | |||
| ``` | |||
| qmk console [-d <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>] | |||
| ``` | |||
| **示例**： | |||
| 连接到所有可用的键盘并输出终端信息： | |||
| ``` | |||
| qmk console | |||
| ``` | |||
| 列出所有设备： | |||
| ``` | |||
| qmk console -l | |||
| ``` | |||
| 仅输出 clueboard/66/rev3 键盘的信息: | |||
| ``` | |||
| qmk console -d C1ED:2370 | |||
| ``` | |||
| 仅输出第二把 clueboard/66/rev3 键盘的信息: | |||
| ``` | |||
| qmk console -d C1ED:2370:2 | |||
| ``` | |||
| 输出时间戳及VID:PID以替代键盘名： | |||
| ``` | |||
| qmk console -n -t | |||
| ``` | |||
| 屏蔽bootloader的消息： | |||
| ``` | |||
| qmk console --no-bootloaders | |||
| ``` | |||
| ## `qmk doctor` | |||
| 该命令用以检查你的开发环境并对发现的潜在的构建及刷写问题进行提醒，如果您乐意，它也可以修复其中大部分问题。 | |||
| **用法**： | |||
| ``` | |||
| qmk doctor [-y] [-n] | |||
| ``` | |||
| **示例**： | |||
| 检查开发环境中的问题并提示是否修复： | |||
| qmk doctor | |||
| 检查开发环境中的问题并自动进行修复： | |||
| qmk doctor -y | |||
| 检查开发环境中的问题，仅生成报告： | |||
| qmk doctor -n | |||
| ## `qmk format-json` | |||
| 将JSON文件格式化为（尽量）便于阅读的形式。会自动分辨JSON结构类型（info.json还是keymap.json），必要时也可以通过 `--format` 指定。 | |||
| **用法**： | |||
| ``` | |||
| qmk format-json [-f FORMAT] <json_file> | |||
| ``` | |||
| ## `qmk info` | |||
| 展示QMK中的键盘及键映射信息，该命令用来获取键盘信息，输出配列，展示底层按键矩阵，及格式化地输出键映射JSON数据。 | |||
| **用法**： | |||
| ``` | |||
| qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD] | |||
| ``` | |||
| 该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 | |||
| **示例**： | |||
| 输出键盘的基础信息： | |||
| qmk info -kb planck/rev5 | |||
| 输出键盘的矩阵信息： | |||
| qmk info -kb ergodox_ez -m | |||
| 输出键盘的键映射JSON数据： | |||
| qmk info -kb clueboard/california -km default | |||
| ## `qmk json2c` | |||
| 从QMK配置器导出的数据中生成 keymap.c 文件 | |||
| Creates a keymap.c from a QMK Configurator export. | |||
| **用法**： | |||
| ``` | |||
| qmk json2c [-o OUTPUT] filename | |||
| ``` | |||
| ## `qmk c2json` | |||
| 从 keymap.c 文件中生成 keymap.json | |||
| **注意：** 解析C代码文件并不容易，该命令有可能无法对你的键映射文件生效，不使用C预处理代码有时可以解决问题。 | |||
| **用法**： | |||
| ``` | |||
| qmk c2json -km KEYMAP -kb KEYBOARD [-q] [--no-cpp] [-o OUTPUT] filename | |||
| ``` | |||
| ## `qmk lint` | |||
| 检查键盘及键映射数据并提示出常见错误与问题，以及不符合模板规范的地方。 | |||
| **用法**： | |||
| ``` | |||
| qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict] | |||
| ``` | |||
| 该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 | |||
| **示例**： | |||
| 基本的lint检查： | |||
| qmk lint -kb rominronin/katana60/rev2 | |||
| ## `qmk list-keyboards` | |||
| 该命令可以列出 `qmk_firmware` 中所有的键盘 | |||
| **用法**： | |||
| ``` | |||
| qmk list-keyboards | |||
| ``` | |||
| ## `qmk list-keymaps` | |||
| 该命令可以列出指定键盘（及指定版本）下的所有键映射。 | |||
| 该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 | |||
| **用法**： | |||
| ``` | |||
| qmk list-keymaps -kb planck/ez | |||
| ``` | |||
| ## `qmk new-keyboard` | |||
| 该命令可基于现有模板创建出新的键盘定义。 | |||
| 对于未给出的参数，会提示你输入，若未传入 `-u` 参数且 .gitconfig 中设置了 `user.name`，则会提示你使用该值作为默认用户名。 | |||
| **用法**： | |||
| ``` | |||
| qmk new-keyboard [-kb KEYBOARD] [-t {avr,ps2avrgb}] -u USERNAME | |||
| ``` | |||
| ## `qmk new-keymap` | |||
| 该命令可基于键盘已有的默认键映射创建新的键映射。 | |||
| 该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 | |||
| **用法**： | |||
| ``` | |||
| qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] | |||
| ``` | |||
| ## `qmk clean` | |||
| 该命令会清理 `.build` 目录，若传入 `--all` 开关，在 `qmk_firmware` 下的所有.hex及.bin文件也会一并删除。 | |||
| **用法**： | |||
| ``` | |||
| qmk clean [-a] | |||
| ``` | |||
| --- | |||
| # 面向开发者的命令 | |||
| ## `qmk format-text` | |||
| 该命令会重新格式化并统一文件的换行符。 | |||
| 代码库下所有的文件须使用Unix换行符（LF）。 | |||
| 若你在**Windows**下进行开发，必须确保文件中的换行符是正确的，才能让你的PR被允许合入。 | |||
| ``` | |||
| qmk format-text | |||
| ``` | |||
| ## `qmk format-c` | |||
| 该命令会使用clang-format来格式化C代码。 | |||
| 不带参数地执行该命令以用来格式化核心代码相关的改动，默认会通过 `git diff` 来检查 `origin/master`， 可以通过 `-b <分支名>` 来改变检查的分支。 | |||
| 带着 `-a` 开关执行命令会格式化所有的核心代码，也可以在命令行中传入文件名来指定格式化某个文件。 | |||
| **用以处理指定文件时**： | |||
| ``` | |||
| qmk format-c [file1] [file2] [...] [fileN] | |||
| ``` | |||
| **用以处理所有的核心代码时**： | |||
| ``` | |||
| qmk format-c -a | |||
| ``` | |||
| **用以处理 origin/master 下的所有改动时**： | |||
| ``` | |||
| qmk format-c | |||
| ``` | |||
| **用以处理指定分支下的所有改动时**： | |||
| ``` | |||
| qmk format-c -b branch_name | |||
| ``` | |||
| ## `qmk generate-compilation-database` | |||
| **用法**: | |||
| ``` | |||
| qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP] | |||
| ``` | |||
| 创建新 `compile_commands.json` 文件。 | |||
| 你的IDE/编辑器是否使用了“编程语言本地服务器”（language server）且 _总是_ 无法找到全部的包含文件（include files）？是不是很讨厌红色的波浪线？想不想让你的编辑器看得懂 `#include QMK_KEYBOARD_H`？你需要的是一个[编译数据库](https://clang.llvm.org/docs/JSONCompilationDatabase.html)！而 QMK 可以帮助你构建出一个。 | |||
| 该命令需要知道你在构建的是哪个键盘及键映射，它使用与 `qmk compile` 命令一样的选项：参数、当前目录以及配置文件。 | |||
| **示例：** | |||
| ``` | |||
| $ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak | |||
| $ qmk generate-compilation-database | |||
| Ψ Making clean | |||
| Ψ Gathering build instructions from make -n gh60/satan:colemak | |||
| Ψ Found 50 compile commands | |||
| Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json | |||
| ``` | |||
| 现在可以打开你的开发环境并享受没有波浪线的日子了。 | |||
| ## `qmk docs` | |||
| 该命令会在本地启动一个HTTP服务，从而你可以浏览及改进文档，默认端口号为8936，使用 `-b`/`--browser` 开关可以让该命令自动通过默认浏览器打开链接地址。 | |||
| **用法**： | |||
| ``` | |||
| qmk docs [-b] [-p PORT] | |||
| ``` | |||
| ## `qmk generate-docs` | |||
| 该命令可以在本地生成QMK文档，用以文档的常规浏览使用，或进行文档改进工作。可以使用类似[serve](https://www.npmjs.com/package/serve)这样的工具来浏览生成的文档文件。 | |||
| **用法**： | |||
| ``` | |||
| qmk generate-docs | |||
| ``` | |||
| ## `qmk generate-rgb-breathe-table` | |||
| 该命令可以生成用于[RGB灯光](zh-cn/feature_rgblight.md)的呼吸效果的查询表（LUT）头文件。将该文件命名为 `rgblight_breathe_table.h` 并放入键盘或键映射目录下，可以覆盖替换 `quantum/rgblight/` 下的默认LUT。 | |||
| **用法**： | |||
| ``` | |||
| qmk generate-rgb-breathe-table [-q] [-o OUTPUT] [-m MAX] [-c CENTER] | |||
| ``` | |||
| ## `qmk kle2json` | |||
| 该命令可以将KLE原始数据转换成QMK配置器的JSON数据，可接受的输入可以是文件绝对路径，或当前目录下的文件名。若 `info.json` 文件存在，默认不会进行覆盖，通过指定 `-f` 或 `--force` 开关可以允许覆盖。 | |||
| **用法**： | |||
| ``` | |||
| qmk kle2json [-f] <filename> | |||
| ``` | |||
| **示例**： | |||
| ``` | |||
| $ qmk kle2json kle.txt | |||
| ☒ File info.json already exists, use -f or --force to overwrite. | |||
| ``` | |||
| ``` | |||
| $ qmk kle2json -f kle.txt -f | |||
| Ψ Wrote out to info.json | |||
| ``` | |||
| ## `qmk format-python` | |||
| 该命令可以对 `qmk_firmware` 下的python代码进行格式化。 | |||
| **用法**： | |||
| ``` | |||
| qmk format-python | |||
| ``` | |||
| ## `qmk pytest` | |||
| 该命令会执行python测试框架，在你更改了python代码后，应确保该命令可以成功执行。 | |||
| **用法**： | |||
| ``` | |||
| qmk pytest | |||
| ``` | |||
| **示例**: | |||
| 执行全部的测试套件： | |||
| qmk pytest | |||
| 执行指定的测试用例组： | |||
| qmk pytest -t qmk.tests.test_cli_commands | |||
| 执行单个测试用例： | |||
| qmk pytest -t qmk.tests.test_cli_commands.test_c2json | |||
| qmk pytest -t qmk.tests.test_qmk_path | |||
+ 126
- 0
docs/zh-cn/cli_configuration.md
View File
| @ -0,0 +1,126 @@ | |||
| # QMK CLI 配置 | |||
| <!--- | |||
| original document: 0.15.12:docs/cli_configuration.md | |||
| git diff 0.15.12 HEAD -- docs/cli_configuration.md | cat | |||
| --> | |||
| 本文详述了 `qmk config` 功能及作用。 | |||
| # 介绍 | |||
| QMK CLI的配置系统是一套键/值（key/value）数据系统，每个键由一个子指令和一个参数名组成，通过点号（英文句号）分隔。这使得配置项可以简单直接地映射到命令行参数上。 | |||
| ## 简单示例 | |||
| 作为一个示例，对于指令 `qmk compile --keyboard clueboard/66/rev4 --keymap default` | |||
| 其存在两个命令行参数，可以通过如下方式从配置中读取： | |||
| * `compile.keyboard` | |||
| * `compile.keymap` | |||
| 可以这样设置： | |||
| ``` | |||
| $ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default | |||
| compile.keyboard: None -> clueboard/66/rev4 | |||
| compile.keymap: None -> default | |||
| Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' | |||
| ``` | |||
| 现在每次执行 `qmk compile` 时都不需要指定键盘及键映射参数了。 | |||
| ## 设置用户级的默认配置 | |||
| 当你需要在多个命令中使用一致的配置项时，比如很多命令都需要的 `--keyboard` 参数，相比于每次执行命令都去指定该参数值，你可以直接设置用户级的配置值，即可将该配置用于所有的命令。 | |||
| 示例： | |||
| ``` | |||
| $ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default | |||
| user.keyboard: None -> clueboard/66/rev4 | |||
| user.keymap: None -> default | |||
| Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' | |||
| ``` | |||
| # CLI文档 (`qmk config`) | |||
| `qmk config` 命令可以管理配置数据。当不带额外参数执行时，会输出所有已有配置。存在参数时这些参数将被视为配置项参数，其格式须满足如下形式且无空格分隔： | |||
| <subcommand|general|default>[.<key>][=<value>] | |||
| ## 设置配置值 | |||
| 在配置项的键后加 = 号进行值的设置，配置项的键必须是 `<section>.<key>` 的完整形式。 | |||
| 举例： | |||
| ``` | |||
| $ qmk config default.keymap=default | |||
| default.keymap: None -> default | |||
| Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' | |||
| ``` | |||
| ## 读取配置值 | |||
| 可以读取整个配置文件、单独配置键或是一整个配置系列，也可以同时指定读取多个配置项。 | |||
| ### 全量配置读取示例 | |||
| qmk config | |||
| ### 单系列配置读取示例 | |||
| qmk config compile | |||
| ### 单配置项读取示例 | |||
| qmk config compile.keyboard | |||
| ### 多配置项读取示例 | |||
| qmk config user compile.keyboard compile.keymap | |||
| ## 删除配置值 | |||
| 将配置值设置为 `None` 即可删除该配置值。 | |||
| 示例： | |||
| ``` | |||
| $ qmk config default.keymap=None | |||
| default.keymap: default -> None | |||
| Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' | |||
| ``` | |||
| ## 批量操作 | |||
| 一个指令中可以合并执行多个读写操作，将依序进行执行输出： | |||
| ``` | |||
| $ qmk config compile default.keymap=default compile.keymap=None | |||
| compile.keymap=skully | |||
| compile.keyboard=clueboard/66_hotswap/gen1 | |||
| default.keymap: None -> default | |||
| compile.keymap: skully -> None | |||
| Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' | |||
| ``` | |||
| # 用户配置相关的配置项 | |||
| | 配置项 | 默认值 | 描述 | | |||
| |-------|-------|------| | |||
| | user.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） | | |||
| | user.keymap | None | 键盘名称（举例：`default`） | | |||
| | user.name | None | 用户的Github用户名 | | |||
| # 所有配置项 | |||
| | 配置项 | 默认值 | 描述 | | |||
| |-------|-------|------| | |||
| | compile.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） | | |||
| | compile.keymap | None | 键盘名称（举例：`default`） | | |||
| | hello.name | None | 执行时展示的欢迎信息 | | |||
| | new_keyboard.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） | | |||
| | new_keyboard.keymap | None | 键盘名称（举例：`default`） | | |||
+ 32
- 0
docs/zh-cn/cli_tab_complete.md
View File
| @ -0,0 +1,32 @@ | |||
| # QMK Tab补全 | |||
| <!--- | |||
| original document: 0.15.12:docs/cli_tab_complete.md | |||
| git diff 0.15.12 HEAD -- docs/cli_tab_complete.md | cat | |||
| --> | |||
| 在使用Bash 4.2及更高版本、Zsh或FiSH时，可以启用QMK CLI的Tab补全功能，可以实现对 `qmk` 参数中的开关、键盘、文件等参数的自动补全。 | |||
| ## 设置 | |||
| 有以下几种启用Tab补全的方法。 | |||
| ### 仅当前用户生效 | |||
| 将以下内容添加到文件 `.profile` 或 `.bashrc` 的末尾: | |||
| source ~/qmk_firmware/util/qmk_tab_complete.sh | |||
| 若你的 `qmk_firmware` 存放在其它路径，以上路径也需要调整。 | |||
| ### 系统级的符号关联 | |||
| 若想让所有本地用户都可以实现Tab补全，可以按如下方法添加符号连接到 `qmk_tab_complete.sh` 脚本： | |||
| `ln -s ~/qmk_firmware/util/qmk_tab_complete.sh /etc/profile.d/qmk_tab_complete.sh` | |||
| ### 系统级的脚本拷贝 | |||
| 有时符号连接的方案无效，可以改用拷贝文件到指定位置的方案。但须留意该Tab补全脚本可能会不定时更新，你需要定期重新拷贝一次该脚本。 | |||
| cp util/qmk_tab_complete.sh /etc/profile.d | |||
+ 66
- 0
docs/zh-cn/configurator_architecture.md
View File
| @ -0,0 +1,66 @@ | |||
| # QMK配置器框架 | |||
| <!--- | |||
| original document: 0.15.12:docs/configurator_architecture.md | |||
| git diff 0.15.12 HEAD -- docs/configurator_architecture.md | cat | |||
| --> | |||
| 本章节提供了QMK配置器前端技术框架信息，若你对QMK配置器前端工程本身感兴趣，可以从[QMK配置器](https://github.com/qmk/qmk_configurator)代码库开始。 | |||
| # 总览 | |||
|  | |||
| # 详述 | |||
| QMK配置器基于[单页面框架](https://en.wikipedia.org/wiki/Single-page_application)实现，供使用者创建兼容QMK键盘的自定义键映射方案。键映射方案可以导出为JSON格式的数据，也可以编译出可通过[QMK工具箱](https://github.com/qmk/qmk_toolbox)刷写到键盘中的固件文件。 | |||
| 配置器从“键盘元数据仓库（Keyboard Metadata store）”获取键盘元数据，编译请求通过QMK API提交，编译产出放在S3兼容的数据仓库[Digital Ocean空间](https://www.digitalocean.com/products/spaces/)中。 | |||
| ## 配置器前端 | |||
| 地址：<https://config.qmk.fm> | |||
| [配置器前端](https://config.qmk.fm)会编译并产出一些静态文件并通过Github Pages托管，每当[QMK配置器 `master`](https://github.com/qmk/qmk_configurator)分支收到推送的提交时都会触发。可以通过[QMK配置器 actions页面](https://github.com/qmk/qmk_configurator/actions/workflows/build.yml)查看这些job的状态。 | |||
| ## 键盘元数据 | |||
| 地址：<https://keyboards.qmk.fm> | |||
| 每当[qmk_firmware](https://github.com/qmk/qmk_firmware)仓库中的键盘定义变化时，会生成JSON格式的键盘元数据，并上传到指定空间用于配置器生成每种键盘的UI展现。可以在[QMK固件 actions页面](https://github.com/qmk/qmk_firmware/actions/workflows/api.yml)查看相关job的状态。如果你是QMK开发团队成员（Collaborator），可以使用 `workflow_dispatch` 事件触发器来手动执行该job。 | |||
| ## QMK API | |||
| 地址：<http://api.qmk.fm> | |||
| QMK API接受 `keymap.json` 文件输入并进行编译，这和你在 `qmk compile` 和 `qmk flash` 中使用的文件一样。当 `keymap.json` 文件被提交后，浏览器中的页面将定时查看job状态（每2秒一次，有时更久一些）直到job完成。最终产出的JSON描述信息里包含了键映射方案的源文件，及编译出的二进制的可下载链接地址。 | |||
| 为遵循GPL协议，QMK API会确保源文件及编译产出总是同时提供的。 | |||
| API有3种非异常的回应状态- | |||
| 1. 编译job排队中 | |||
| 2. 编译job执行中 | |||
| 3. 编译job已完成 | |||
| ### 编译job排队中 | |||
| 此状态表明[QMK编译器](#QMK编译器)节点还未选中该job，在配置器页面此时会显示“等待一个可用的烤炉（Waiting for an oven）”。 | |||
| ### 编译job执行中 | |||
| 此状态说明编译job已经在执行中，配置器页面会显示为“烤制中”(Baking)。 | |||
| ### 编译job已完成 | |||
| 此状态说明编译job已经执行完毕，输出的JSON格式的状态信息里有源文件及编译产出的二进制文件的下载链接项。 | |||
| ## Redis/RQ | |||
| QMK API通过Redis队列分发job到可用的[QMK编译器](#QMK编译器)节点。接收到的 `keymap.json` 文件先送到RQ队列，而 `qmk_compiler` 节点则从中拉取执行。 | |||
| ## QMK编译器 | |||
| [QMK编译器](https://github.com/qmk/qmk_compiler)负责执行 `keymap.json` 文件的实际编译工作。它的工作逻辑是先拉取有请求的 `qmk_firmware` 分支代码，执行 `qmk compile keymap.json`，最后上传源文件及二进制产出到Digital Ocean空间中。 | |||
| 当用户需要下载源代码/二进制文件时，API会给出重定向后的已鉴权地址链接。 | |||
+ 198
- 0
docs/zh-cn/configurator_default_keymaps.md
View File
| @ -0,0 +1,198 @@ | |||
| # 向QMK配置器中添加默认键映射 :id=adding-default-keymaps | |||
| <!--- | |||
| original document: 0.15.12:docs/configurator_default_keymaps.md | |||
| git diff 0.15.12 HEAD -- docs/configurator_default_keymaps.md | cat | |||
| --> | |||
| 本章节描述了如何向QMK配置器中添加一款键盘的默认键映射 | |||
| ## 技术信息 :id=technical-information | |||
| QMK配置器使用JSON作为键映射的本地文件格式。我们尽力确保其行为与在 `qmk_firmware` 中 执行 `make <keyboard>:default` 时一致。 | |||
| 该目录下的键映射需要定义四个键值对： | |||
| * `keyboard` (字符串) | |||
| * 键盘名称，与执行 `make` 进行编译时使用的一致（如 `make 1upkeyboards/1up60rgb:default`）。 | |||
| * `keymap` (字符串) | |||
| * 应设置为 `default`. | |||
| * `layout` (字符串) | |||
| * 默认键映射应使用的配列宏定义。 | |||
| * `layers` (数组) | |||
| * 键映射数据。此键下的每行元素对应一个层定义，层定义中包含该层的键码组成信息。 | |||
| 额外地，大部分键映射中还有一个 `commit` 项，该项并不是QMK配置器后端服务API所需，而是用于告知配置器维护者这份JSON键映射数据来源于代码库中的哪个版本的键映射。该值为 `qmk_firmware` 代码库中最后一次修改键盘默认 `keymap.c` 文件提交的commit的SHA标记。该SHA值的获取方式是拉取[`qmk/qmk_firmware` 库的 `master`分支](https://github.com/qmk/qmk_firmware/tree/master/)后，执行 `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c`（若键盘有什么问题且存在 `keymap.json` 文件，则用之作为替代），执行结果应类似于： | |||
| ``` | |||
| f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625) | |||
| ``` | |||
| 本例中，`f14629ed1cd7c7ec9089604d64f29a99981558e8` 即应为 `commit` 的值。 | |||
| ## 示例 :id=example | |||
| 若某人想添加H87a Hineybush键盘的默认键映射方案，应到 `qmk_firmware` 下H87a的默认键映射下执行上述 `git log` 命令： | |||
| ``` | |||
| user ~/qmk_firmware (master) | |||
| $ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c | |||
| ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237) | |||
| ``` | |||
| 在我们获取了commit哈希值后，还需要键映射定义（为加强可读性进行了编辑处理）： | |||
| ```c | |||
| ... | |||
| #include QMK_KEYBOARD_H | |||
| const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { | |||
| [0] = LAYOUT_all( | |||
| KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_PSCR, KC_SLCK, KC_PAUS, | |||
| KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, KC_BSPC, KC_INS, KC_HOME, KC_PGUP, | |||
| KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_DEL, KC_END, KC_PGDN, | |||
| KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, | |||
| KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_TRNS, KC_UP, | |||
| KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_RGUI, KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT), | |||
| [1] = LAYOUT_all( | |||
| KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RGB_TOG, RGB_MOD, RGB_HUD, RGB_HUI, RGB_SAD, RGB_SAI, RGB_VAD, RGB_VAI, BL_TOGG, BL_DEC, BL_INC, | |||
| KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_VOLU, | |||
| KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RESET, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_MPLY, KC_MNXT, KC_VOLD, | |||
| KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, | |||
| KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, | |||
| KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS), | |||
| }; | |||
| ``` | |||
| 默认键映射使用了 `LAYOUT_all` 宏，最后其会成为 `layout` 项的值。编译为QMK配置器的JSON键映射数据后，输出文件应为： | |||
| ```json | |||
| { | |||
| "keyboard": "hineybush/h87a", | |||
| "keymap": "default", | |||
| "commit": "ef8878fba5d3786e3f9c66436da63a560cd36ac9", | |||
| "layout": "LAYOUT_all", | |||
| "layers": [ | |||
| [ | |||
| "KC_ESC", "KC_F1", "KC_F2", "KC_F3", "KC_F4", "KC_F5", "KC_F6", "KC_F7", "KC_F8", "KC_F9", "KC_F10", "KC_F11", "KC_F12", "KC_PSCR", "KC_SLCK", "KC_PAUS", | |||
| "KC_GRV", "KC_1", "KC_2", "KC_3", "KC_4", "KC_5", "KC_6", "KC_7", "KC_8", "KC_9", "KC_0", "KC_MINS", "KC_EQL", "KC_BSPC", "KC_BSPC", "KC_INS", "KC_HOME", "KC_PGUP", | |||
| "KC_TAB", "KC_Q", "KC_W", "KC_E", "KC_R", "KC_T", "KC_Y", "KC_U", "KC_I", "KC_O", "KC_P", "KC_LBRC", "KC_RBRC", "KC_BSLS", "KC_DEL", "KC_END", "KC_PGDN", | |||
| "KC_CAPS", "KC_A", "KC_S", "KC_D", "KC_F", "KC_G", "KC_H", "KC_J", "KC_K", "KC_L", "KC_SCLN", "KC_QUOT", "KC_NUHS", "KC_ENT", | |||
| "KC_LSFT", "KC_NUBS", "KC_Z", "KC_X", "KC_C", "KC_V", "KC_B", "KC_N", "KC_M", "KC_COMM", "KC_DOT", "KC_SLSH", "KC_RSFT", "KC_TRNS", "KC_UP", | |||
| "KC_LCTL", "KC_LGUI", "KC_LALT", "KC_SPC", "KC_RALT", "MO(1)", "KC_RGUI", "KC_RCTL", "KC_LEFT", "KC_DOWN", "KC_RGHT" | |||
| ], | |||
| [ | |||
| "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RGB_TOG", "RGB_MOD", "RGB_HUD", "RGB_HUI", "RGB_SAD", "RGB_SAI", "RGB_VAD", "RGB_VAI", "BL_TOGG", "BL_DEC", "BL_INC", | |||
| "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_VOLU", | |||
| "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RESET", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_MPLY", "KC_MNXT", "KC_VOLD", | |||
| "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", | |||
| "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", | |||
| "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS" | |||
| ] | |||
| ] | |||
| } | |||
| ``` | |||
| `layers` 数组中的空白区域不影响键映射功能，仅为了方便阅读。 | |||
| ## 附加说明 :id=caveats | |||
| ### 层定义只能通过序号进行引用 :id=layer-references | |||
| QMK中常见的一种做法是通过一系列 `#define` 或 `enum` 类型声明来对层定义进行命名： | |||
| ```c | |||
| enum layer_names { | |||
| _BASE, | |||
| _MEDIA, | |||
| _FN | |||
| }; | |||
| ``` | |||
| 对于C代码来讲可行，但对于配置器来讲，你*必须*使用层序号 - 上例中的`MO(_FN)` 应使用 `MO(2)`。 | |||
| ### 不支持任何形式的定制化代码 :id=custom-code | |||
| 需要在 keymap.c 文件中添加函数代码的功能，如Tap Dance或是Unicode，都*完全*无法在配置器中构建。即便是在 `qmk_firmware` 代码库中在键盘定义中设置了 `TAP_DANCE_ENABLE = yes`，也只会导致*任何*固件构建在配置器中行不通。这是由API及JSON格式的键映射数据同时造成的限制。 | |||
| ### 对自定义键码的不完全支持 :id=custom-keycodes | |||
| 仅有一个方案可以支持自定义键码：若自定义键码的逻辑实现是在 qmk_firmware 下的键盘定义中完成的，而非在键映射中，那么这个键码*可以*在配置器中使用且*可以*编译运行。（因此，）相对于在 `keymap.c` 中使用如下代码段： | |||
| ```c | |||
| enum custom_keycodes { | |||
| MACRO_1 = SAFE_RANGE, | |||
| MACRO_2, | |||
| MACRO_3 | |||
| }; | |||
| ... | |||
| bool process_record_user(uint16_t keycode, keyrecord_t *record) { | |||
| switch(keycode) { | |||
| case MACRO_1: | |||
| if (record->event.pressed) { | |||
| SEND_STRING("This is macro #1."); | |||
| } | |||
| return false; | |||
| case MACRO_2: | |||
| if (record->event.pressed) { | |||
| SEND_STRING("This is macro #2."); | |||
| } | |||
| return false; | |||
| case MACRO_3: | |||
| if (record->event.pressed) { | |||
| SEND_STRING("This is macro #3."); | |||
| } | |||
| return false; | |||
| } | |||
| return true; | |||
| }; | |||
| ``` | |||
| ... 请将键码的 `enum` 定义块添加到键盘的头文件（`<keyboard.h>`）中，例如（留意 `enum` 在这里命名为 `keyboard_keycodes`）： | |||
| ```c | |||
| enum keyboard_keycodes { | |||
| MACRO_1 = SAFE_RANGE, | |||
| MACRO_2, | |||
| MACRO_3, | |||
| NEW_SAFE_RANGE // 重要! | |||
| }; | |||
| ``` | |||
| ... 之后在 `<keyboard>.c` 中的 `process_record_kb()` 代码逻辑应为： | |||
| ```c | |||
| bool process_record_kb(uint16_t keycode, keyrecord_t *record) { | |||
| switch(keycode) { | |||
| case MACRO_1: | |||
| if (record->event.pressed) { | |||
| SEND_STRING("This is macro #1."); | |||
| } | |||
| return false; | |||
| case MACRO_2: | |||
| if (record->event.pressed) { | |||
| SEND_STRING("This is macro #2."); | |||
| } | |||
| return false; | |||
| case MACRO_3: | |||
| if (record->event.pressed) { | |||
| SEND_STRING("This is macro #3."); | |||
| } | |||
| return false; | |||
| } | |||
| return process_record_user(keycode, record); | |||
| }; | |||
| ``` | |||
| 注意最后的 `process_record_user()` 调用，若用户需要添加自定义键码到键映射中，须使用 `NEW_SAFE_RANGE` 替代 `SAFE_RANGE`，而其定义来自于上面键盘层定义中。 | |||
| ## 更多资料 :id=additional-reading | |||
| 为了让QMK配置器支持你的键盘，你的键盘定义必须存在于 `qmk_firmware` 代码库的 `master` 分支中。相关操作指引，请参见[在QMK配置器中支持你的键盘](zh-cn/reference_configurator_support.md). | |||
+ 63
- 0
docs/zh-cn/configurator_step_by_step.md
View File
| @ -0,0 +1,63 @@ | |||
| # QMK 配置器: 入门 | |||
| <!--- | |||
| original document: 0.15.12:docs/configurator_step_by_step.md | |||
| git diff 0.15.12 HEAD -- docs/configurator_step_by_step.md | cat | |||
| --> | |||
| 本章节描述了如何使用QMK配置器构建出固件文件的过程。 | |||
| ## 第一步：选择键盘 | |||
| 从下拉列表中选择一款用于创建键映射的键盘。 | |||
| ?> 当键盘有多个版本可选择时，请确保选择正确。 | |||
| 因为很重要，这里我再次说一遍： | |||
| !> **请选择正确的版本！** | |||
| 如果你的键盘声称是基于QMK的但未在列表中，可能是开发者还未提交给我们，或者提交还未被合并进来。若在[Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard)中没有找到请求支持该键盘的issue，请到[QMK固件](https://github.com/qmk/qmk_firmware/issues)提交一个issue。也有一些基于QMK的键盘是由制造商自己的GitHub账号在维护着，请也确认一下。 <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? --> | |||
| ## 第二部：选择键盘配列 | |||
| 选择最适合你要创建的键映射的配列，一些键盘的配列不完整或有问题，后续会逐渐支持。 | |||
| !> 有时会遇到没有特别适合的配列的情况，请选择 `LAYOUT_all`。 | |||
| ## 第三步：命名你的键映射 | |||
| 如何起名完全取决于你。 | |||
| ?> 如果编译时遇到了问题，可能是因为QMK固件代码库中已经有了同名项，可以尝试改一下名字。 | |||
| ## 第四步：设计你的键映射 | |||
| 以下三种方法可以添加键码： | |||
| 1. 拖拽 | |||
| 2. 点击布局上的空白项，再点击所需的键码 | |||
| 3. 点击布局上的空白项, 再点击你物理键盘上的按键 | |||
| ?> 鼠标在键上悬停时会有一个键码值的提示出现，详细描述信息请参见: | |||
| * [基础键码资料](zh-cn/keycodes_basic.md) | |||
| * [进阶键码资料](zh-cn/feature_advanced_keycodes.md) | |||
| !> 如果你选择的配列与物理实机有出入，请将不需要的按键留空。如果不清楚应该用哪个键，例如，你只需要一个退格键，但 `LAYOUT_all` 中有两个退格键，须将两个键都放上一样的键码。 | |||
| ## 第五步：保存键映射留待后续修订 | |||
| 当你调整完毕键映射方案，或打算以后继续编辑，点击 `导出Keymap JSON文件（Download this QMK Keymap JSON File）` 按钮，当前键映射方案将保存到你的计算机中，之后可以点击 `导入Keymap JSON文件(Upload a QMK Keymap JSON File)` 按钮导入后继续编辑。 | |||
| !> **注意：** 导出的.json文件与 kbfirmware.com 和其它工具软件生成的并不兼容，如果你将导出的数据放到那些工具中，或尝试导入那些工具生成的.json文件，是不可行的。 | |||
| ## 第六步：编译固件 | |||
| 点击绿色的 `编译（Compile）` 按钮。 | |||
| 编译完成后，可以点击绿色的 `固件（Download Firmware）` 下载固件文件。 | |||
| ## 下一步：刷写到键盘中 | |||
| 参见[刷写固件](zh-cn/newbs_flashing.md). | |||
+ 31
- 0
docs/zh-cn/configurator_troubleshooting.md
View File
| @ -0,0 +1,31 @@ | |||
| # 配置器问题排查 | |||
| <!--- | |||
| original document: 0.15.12:docs/configurator_troubleshooting.md | |||
| git diff 0.15.12 HEAD -- docs/configurator_troubleshooting.md | cat | |||
| --> | |||
| ## 我的 .json 文件不可用 | |||
| 如果该 .json 文件确实是QMK配置器中导出的，恭喜你遇到bug了，请在[QMK配置器](https://github.com/qmk/qmk_configurator/issues)库中提交一个issue。 | |||
| 如果不是……那么页面顶部加大加粗的提示让你不要使用其它 .json 文件，你是怎么错过的？ | |||
| ## 我的配列中有好多空格键，我应该怎么处理？ | |||
| 如果你是说有三个空格键栏，最好的做法是都放上空格键。这个处理方案也适用于退格键和Shift键。 | |||
| ## 用于...的键码是什么？ | |||
| 参见： | |||
| * [基础键码资料](zh-cn/keycodes_basic.md) | |||
| * [进阶键码资料](zh-cn/feature_advanced_keycodes.md) | |||
| ## 无法编译 | |||
| 请检查键映射中所有的层，确保没有随机（random）键。 | |||
| ## Bug及其它问题 | |||
| 我们很乐意倾听你的需求及bug报告，请到[QMK配置器](https://github.com/qmk/qmk_configurator/issues)代码库中提交吧。 | |||
+ 79
- 109
docs/zh-cn/contributing.md
View File
+ 177
- 190
docs/zh-cn/custom_quantum_functions.md
View File
+ 102
- 0
docs/zh-cn/driver_installation_zadig.md
View File
| @ -0,0 +1,102 @@ | |||
| # 利用Zadig安装Bootloader驱动 | |||
| <!--- | |||
| original document: 0.15.12:docs/driver_installation_zadig.md | |||
| git diff 0.15.12 HEAD -- docs/driver_installation_zadig.md | cat | |||
| --> | |||
| QMK在主机侧会展现为一台HID键盘设备，因此不需要额外的驱动。但若要在Windows下刷写键盘固件，重置主控板时出现的bootloader设备则通常需要一些驱动程序。 | |||
| 已知的特例有两个：常见于Pro Micro的Caterina bootloader，以及PJRC Teensys上的HalfKay bootloader, 会同时提供一个串行端口设备及一个HID设备，因此不需要额外的驱动。 | |||
| 这里我们推荐使用[Zadig](https://zadig.akeo.ie/)工具软件。若你在MSYS2中配置了开发环境，`qmk_install.sh` 脚本已经替你安装了相关驱动。 | |||
| ## 安装 | |||
| 将键盘重置为bootloader模式，点击 `RESET` 键码（可能在别的层中），或按一下通常在主控板背面上的重置开关，如果你的键盘上没有前两者，尝试在按住Esc键或空格+`B`键时插上键盘（更多信息参见[Bootmagic](zh-cn/feature_bootmagic.md)）。有些键盘使用[指令](zh-cn/feature_command.md)功能来代替Bootmagic，这种情况下，可以在键盘插入状态下点击 左Shift+右Shift+`B` 或 左Shift+右Shift+Esc组合键来进入bootloader模式。 | |||
| 也有一些键盘需要特别的操作才能进入bootloader状态。例如，[Bootmagic](zh-cn/feature_bootmagic.md)键（默认为：Esc键）在其它键上，比如左Control；或是指令组合键（默认为：左Shift+右Shift）为其它组合，如左Control+右Control。当不确定的时候，可以查阅一下主控板的README文件。 | |||
| 若要将USBaspLoader设备置为bootloader模式，请在按住 `BOOT` 按钮时点击 `RESET` 按钮，或是在按住 `BOOT` 按钮时插入USB线缆。 | |||
| Zadig可以自动检测到bootloader设备，但有时你需要在 **Options（选项） → List All Devices（列出所有设备）** 的下拉列表中选择正确的设备。 | |||
| !> 如果Zadig中列出的一个或多个设备为 `HidUsb` 驱动的，那么你的键盘应该没有进入bootloader模式，此时箭头会标记成橙色并会询问你确认是否要修改系统驱动，此时**不要**允许该操作。 | |||
| 如果箭头呈现绿色，选择所需的驱动，点击**Install Driver（安装驱动）**。如何选择正确的驱动进行安装请参见[已知驱动列表](#list-of-known-bootloaders)。 | |||
|  | |||
| 最后，重新拔插一次键盘，确认驱动可以正常加载。如果你在使用QMK工具箱进行刷写，记得也重启一下，因为有时它不会检测到驱动的变化。 | |||
| ## 从错误的驱动安装中恢复 | |||
| 如果你发现键盘无法输入了，应当是因为错误地替换了键盘本身的驱动，而不是bootloader的驱动，你的键盘没有进入bootloader模式就进行安装时就会遇到这个问题。在Zadig中很容易看出这个问题 - 正常的键盘在其所有的接口上都应该有 `HidUsb` 驱动： | |||
|  | |||
| 打开Device Manager（设备管理器），选择**View（查看） → Devices by container（依类型排序设备）**，并定位到你键盘名所在的节点。 | |||
|  | |||
| 在这些节点上右键，选择**Uninstall device（卸载）**。如果出现了**Delete the driver software for this device（同时卸载该设备驱动文件）**也请勾选上。 | |||
|  | |||
| 点击 **Action（操作） → Scan for hardware changes（扫描检测硬件改动）**。此时，键盘应该恢复可用状态了。再确认一下Zadig中键盘是否在使用 `HidUsb` 驱动，如果是，键盘即完全恢复可用状态了，如果不是，重复这一步直到Zadig中报告了正确的驱动。 | |||
| ?> 在这一步有时需要重启电脑，以便Windows可以选用新驱动文件。 | |||
| ## 卸载 | |||
| 卸载bootloadeer设备要比安装过程复杂一些。 | |||
| 打开设备管理器，选择**查看 → 依类型排序设备**，并找到bootloader设备，寻找USB VID和PID与Zadig的[该表格](#list-of-known-bootloaders)中一致的项。 | |||
| 在设备属性的详细信息tab中，找到 `Inf name（INF名称）` 值，通常该值类似于 `oemXX.inf`： | |||
|  | |||
| 之后使用管理员权限打开一个命令行窗口（在开始菜单处输出 `cmd` 并点击Ctrl+Shift+回车）。执行 `pnputil /enum-drivers` 并找到 `INF名称` 与 `Published Name（发布名称）` 一致的项： | |||
|  | |||
| 执行 `pnputil /delete-driver oemXX.inf /uninstall`，之后该驱动会被删除，相关设备也不再使用该驱动，但设备是不会被移除的。 | |||
| 与上一节相似，本流程也可能需要执行多次，因为一个设备可能会有多个可用的驱动。 | |||
| !> **警告：** 操作过程中*务必非常小心*！以免不小心卸载掉其它关键驱动。如果你对操作不是很确定，多次检查 `/enum-drivers`的输出信息，也可以考虑执行 `/delete-driver` 时不添加 `/uninstall` 开关\。 | |||
| ## 已知驱动列表 :id=list-of-known-bootloaders | |||
| 该表列出了已知的bootloader设备及其USB VID（厂商ID）和PID（产品ID），以及可用于QMK刷写固件的驱动。留意usbser及HidUsb驱动是随Windows附带的，无法通过Zadig安装 - 如果你的设备驱动不符，请参照上节来卸载这些驱动。 | |||
| 此处列出的设备名应与Zadig中的一致，但不一定与设备管理器及QMK工具箱展示的一致。 | |||
| |Bootloader |设备名 |VID/PID |驱动 | | |||
| |--------------|------------------------------|--------------|-------| | |||
| |`atmel-dfu` |ATmega16u2 DFU |`03EB:2FEF` |libusb0| | |||
| |`atmel-dfu` |ATmega32U2 DFU |`03EB:2FF0` |libusb0| | |||
| |`atmel-dfu` |ATm16U4 DFU V1.0.2 |`03EB:2FF3` |libusb0| | |||
| |`atmel-dfu` |ATm32U4DFU |`03EB:2FF4` |libusb0| | |||
| |`atmel-dfu` |*none* (AT90USB64) |`03EB:2FF9` |libusb0| | |||
| |`atmel-dfu` |AT90USB128 DFU |`03EB:2FFB` |libusb0| | |||
| |`qmk-dfu` |(键盘名) Bootloader |同`atmel-dfu` |libusb0| | |||
| |`halfkay` |*none* |`16C0:0478` |HidUsb | | |||
| |`caterina` |Pro Micro 3.3V |`1B4F:9203` |usbser | | |||
| |`caterina` |Pro Micro 5V |`1B4F:9205` |usbser | | |||
| |`caterina` |LilyPadUSB |`1B4F:9207` |usbser | | |||
| |`caterina` |Pololu A-Star 32U4 Bootloader |`1FFB:0101` |usbser | | |||
| |`caterina` |Arduino Leonardo |`2341:0036` |usbser | | |||
| |`caterina` |Arduino Micro |`2341:0037` |usbser | | |||
| |`caterina` |Adafruit Feather 32u4 |`239A:000C` |usbser | | |||
| |`caterina` |Adafruit ItsyBitsy 32u4 3V |`239A:000D` |usbser | | |||
| |`caterina` |Adafruit ItsyBitsy 32u4 5V |`239A:000E` |usbser | | |||
| |`caterina` |Arduino Leonardo |`2A03:0036` |usbser | | |||
| |`caterina` |Arduino Micro |`2A03:0037` |usbser | | |||
| |`bootloadhid` |HIDBoot |`16C0:05DF` |HidUsb | | |||
| |`usbasploader`|USBasp |`16C0:05DC` |libusbK| | |||
| |`apm32-dfu` |APM32 DFU ISP Mode |`314B:0106` |WinUSB | | |||
| |`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB | | |||
| |`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB | | |||
| |`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB | | |||
| |`qmk-hid` |(键盘名) Bootloader |`03EB:2067` |HidUsb | | |||
+ 37
- 0
docs/zh-cn/easy_maker.md
View File
| @ -0,0 +1,37 @@ | |||
| # 极简式制作 - 通过配置器进行一次性的工程构建 | |||
| <!--- | |||
| original document: 0.15.12:docs/easy_maker.md | |||
| git diff 0.15.12 HEAD -- docs/easy_maker.md | cat | |||
| --> | |||
| 你是否需要一种极简的控制器编程方案，类似Proton C或Teensy 2.0，以进行一次性的工程构建？QMK提供了极简制作器，通过QMK配置器可以在几分钟内制作一个固件。 | |||
| 有几种极简制作器，取决于你需要什么样的： | |||
| * [引脚直连](https://config.qmk.fm/#/?filter=ez_maker/direct) - 将每个开关独立直连到一个引脚 | |||
| * 引脚直连 + 背光 (即将可用) - 类似引脚直连，单独加一个引脚连接到[背光](zh-cn/feature_backlight.md)控制器上 | |||
| * 引脚直连 + 小键盘锁 (即将可用) - 类似引脚直连，单独加一个引脚连接到Numlock LED上 | |||
| * 引脚直连 + 大写锁 (即将可用) - 类似引脚直连， 单独加一个引脚连接到Capslock LED上 | |||
| * 引脚直连 + 编码器 (即将可用) - 类似引脚直连， 再加两个引脚用于连接一个旋钮编码器 | |||
| ## 快速指引 | |||
| 最简单的情况是使用一个引脚直连的主控板，将每个引脚连接到一个开关，另一端再接地即可，从以下键盘列表中可以选择一款支持的MCU： | |||
| * <https://config.qmk.fm/#/?filter=ez_maker/direct> | |||
| 更多信息请参见[引脚直连](#direct-pin)一节。 | |||
| # 引脚直连 :id=direct-pin | |||
| 与其名字表意相同，它的原理是一个引脚连接一个开关，每个开关的另一端接地（VSS或GND），不需要额外的部件，通常MCU内部自带上拉电阻，因此可以感知开关动作。 | |||
| 这里有一个示意图，展示了如何将一个按钮连接到ProMicro的A3引脚上： | |||
|  | |||
| 在开关连接到各自的引脚后，在键盘下拉列表中选择所使用的MCU，将键码指定到对应的引脚上即可构建出固件。以下链接仅展示支持引脚直连的极简式制作： | |||
| * <https://config.qmk.fm/#/?filter=ez_maker/direct> | |||
+ 0
- 6
docs/zh-cn/faq.md
View File
| @ -1,6 +0,0 @@ | |||
| # 常见问题 | |||
| * [一般问题](faq_general.md) | |||
| * [构建和编译QMK](faq_build.md) | |||
| * [QMK调试和故障排除](faq_debug.md) | |||
| * [布局问题](faq_keymap.md) | |||
+ 39
- 88
docs/zh-cn/faq_build.md
View File
| @ -1,122 +1,73 @@ | |||
| # 关于构建的常见问题 | |||
| # 常被问及的编译问题 | |||
| 本页所写是QMK构建的常见问题.如果你还没有进行过编译,就看一下[构建环境搭建](getting_started_build_tools.md) 和 [make的说明](getting_started_make_guide.md). | |||
| <!--- | |||
| original document: 0.15.12:docs/faq_build.md | |||
| git diff 0.15.12 HEAD -- docs/faq_build.md | cat | |||
| --> | |||
| ## 如果您不能在Linux上编程 | |||
| 您需要适当的权限才能操作设备。对于Linux用户, 请参阅下方有关`udev`规则的说明。如果您对`udev`有问题，解决方法是用`sudo`命令。如果您不熟悉此命令，使用`man sudo`查看其手册或[看这个网页](https://linux.die.net/man/8/sudo). | |||
| 本页涉及所有编译QMK的问题，如果你还没有试过，请先阅读[编译环境配置](zh-cn/getting_started_build_tools.md)及[Make指引](zh-cn/getting_started_make_guide.md)。 | |||
| 在你的主控是ATMega32u4时，以下是使用`sudo`命令的样例： | |||
| ## 无法在Linux下编程 | |||
| 操作设备需要足够的权限，对于Linux用户，请参阅下方有关 `udev` 的规则说明。如果你对 `udev` 有困惑，可以先试试 `sudo` 命令，如果你对这个命令不熟悉，可以通过 `man sudo` 或 [这个web页面](https://linux.die.net/man/8/sudo)进行了解。 | |||
| 一个使用 `sudo` 的示例，这里假设你的控制器是ATMega32u4: | |||
| $ 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 <keyboard>:<keymap>:flash | |||
| 使用`sudo`运行`make`一般来说**不**推荐，如果可能，尽量使用前一种方法之一。 | |||
| 但请留意，用 `sudo` 来执行 `make` 通常***不是***一个好主意，请尽量考虑使用上面的办法。 | |||
| ### Linux `udev` 规则 | |||
| 在Linux上，您需要适当的权限才能访问MCU。你也可以在刷新固件时使用 `sudo`，或把这些文件放到`/etc/udev/rules.d/`。 | |||
| ### Linux `udev` 规则 :id=linux-udev-rules | |||
| **/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" | |||
| ``` | |||
| 在linux下，需要足够的权限才能读写bootloader设备，可以使用 `sudo` 来刷写固件（不推荐），也可以将[这个文件](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules) 放到 `/etc/udev/rules.d/` 目录下。 | |||
| 放好后，执行： | |||
| **/etc/udev/rules.d/52-tmk-keyboard.rules:** | |||
| ``` | |||
| # tmk键盘产品 https://github.com/tmk/tmk_keyboard | |||
| SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" | |||
| sudo udevadm control --reload-rules | |||
| sudo udevadm trigger | |||
| ``` | |||
| **/etc/udev/rules.d/54-input-club-keyboard.rules:** | |||
| **注意：**在旧版ModeManager（<1.12）中，过滤功能仅在严格模式（strict mode）下可用，可以调整一下配置： | |||
| ``` | |||
| # Input Club keyboard bootloader | |||
| SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" | |||
| printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf | |||
| sudo systemctl daemon-reload | |||
| sudo systemctl restart ModemManager | |||
| ``` | |||
| ### 串行设备在Linux上检测不到bootloader模式 | |||
| 确保您的内核对您的设备有相应的支持。 如果你的设备是 USB ACM, 比如Pro Micro (Atmega32u4)，就要加上`CONFIG_USB_ACM=y`. 其他设备可能需要`USB_SERIAL` 及其任何子选项。 | |||
| ## DFU Bootloader的未知设备 | |||
| ### 在Linux下无法检测到bootloader模式下的串口设备 | |||
| 确认一下你的内核版本是否已配置为支持该设备。如果你的设备使用USB ACM，如Pro Micro（Atmega32u4），确认内核 配置中包含 `CONFIG_USB_ACM=y`，其它类型的设备可能需要 `USB_SERIAL` 及相关子配置的支持。 | |||
| 如果您在使用Windows来刷新键盘的时候碰到了问题，检查设备管理器。如果在键盘处于 "bootloader模式"时你看到 "未知设备"，说明你可能面临设备问题。 | |||
| ## DFU Bootloader显示为未知设备 | |||
| 重新运行MSYS2上的安装脚本或许会凑效（比如在MSYS2/WSL运行 `./util/qmk_install.sh`) 或者重新安装QMK工具箱也可能会解决你的问题。 | |||
| 在Windows下刷写键盘固件时很常见的一个问题。主要原因是安装了错误的驱动，或者压根没有装驱动。 | |||
| 如果以上方法还是短针攻疽，那您可能需要使用[Zadig Utility](https://zadig.akeo.ie/)。下载此程序, 找到设备问题, 然后选择 `WinUSB`选项, 然后点击"Reinstall driver"。完成后再试试刷新你的键盘。倘若依然徒劳无功，那就尝试所有选项直到好用为止。 | |||
| 要修复这个问题，可以尝试重新执行QMK安装脚本(位于MSYS2或WSL中的 `qmk_firmware` 目录下的 `./util/qmk_install.sh`)或重新安装QMK工具箱。此外，也可以尝试下载安装[QMK驱动安装包 `qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer)来修复。 | |||
| ?> 事实上没有一个驱动的最佳选择，有些选项就是和某些系统相辅相成。但libUSB和WinUSB似乎也算是这里的最佳选择了。 | |||
| 如果bootloader在设备列表中没有显示，你可能要使能 "List all devices"选项在选项菜单中`Options`，然后找到有问题的bootloader设备。(译者注：在win10中可能为 查看-显示隐藏的设备) | |||
| 如果问题依旧，可能是需要下载安装Zadig，具体请参考[通过Zadig安装bootloader驱动](zh-cn/driver_installation_zadig.md)。 | |||
| ## USB VID 和 PID | |||
| 你可以在编辑`config.h`时使用任何你想用的ID值。实际上，使用任何可能未使用的ID都没有问题，除了有极低的与其他产品发生冲突的可能性。 | |||
| 通过编辑 `config.h` 你可以自由指定ID，随便选一个看起来不常用的ID一般不会有什么问题，冲突的概率很低。 | |||
| 大多数QMK主板使用`0xFEED`作为vendor ID。您应该查看其他键盘，以确保选择了唯一的Product ID。 | |||
| 大部分QMK设备都选用 `0xFEED` 作为VID，选取PID前请先看一下其它键盘的情况再决定。 | |||
| 也要看看这个。 | |||
| 同时请阅读这个issue： | |||
| https://github.com/tmk/tmk_keyboard/issues/150 | |||
| 一也可以在下方链接购买一个唯一的VID:PID。不过个人使用似乎用不着这个。 | |||
| 你可以在以下地址购买唯一的VID:PID，但我觉得个人使用情况下没有必要。 | |||
| - https://www.obdev.at/products/vusb/license.html | |||
| - https://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=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@8 | |||
| brew link --force avr-gcc@8 | |||
| ``` | |||
| ### 我刷新了我的键盘但是键盘不工作/按键没有注册 - 而且还是ARM的 (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019) | |||
| 由于EEPROM在基于ARM的芯片上的工作原理，保存的设置可能不再有效。这会影响默认层，而且*或许*在某些情况下，会使键盘不好用，我们仍在调查这些情况。重置EEPROM将解决此问题。 | |||
| ### 在我刷写完键盘后就没响应了/点了没动静了 -- 设备是arm的（rev6 planck, clueboard 60, hs60v2等）(2019年2月) | |||
| 因为ARM平台下EEPROM特殊的工作模式，已保存的配置可能会失效。主要影响的是默认层，有概率在特定情况下会导致键盘不可用，我们还没有搞明白原因。这个问题可以在重置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) | |||
| [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) 以及键盘信息，以了解如何执行此操作的详细信息). | |||
| 也可以考虑使用bootmagic，只要它可以用。（参见[Bootmagic文档](zh-cn/feature_bootmagic.md)并结合键盘情况来了解如何操作） | |||
+ 94
- 94
docs/zh-cn/faq_debug.md
View File
| @ -1,136 +1,136 @@ | |||
| # 调试的常见问题 | |||
| # 调试 FAQ | |||
| 本篇详细介绍了人们在键盘故障排除时的各种常见问题。 | |||
| <!--- | |||
| original document: 0.15.12:docs/faq_debug.md | |||
| git diff 0.15.12 HEAD -- docs/faq_debug.md | cat | |||
| --> | |||
| # 调试控制台 | |||
| 此页面详细介绍了人们对键盘故障排除的各种常见问题。 | |||
| ## `hid_listen` 无法识别设备 | |||
| 当设备的调试控制台未就绪时，您将看到如下内容： | |||
| ## 调试 :id=debugging | |||
| ``` | |||
| Waiting for device:......... | |||
| ``` | |||
| 插入设备后，*hid_listen*找到该设备，您将收到以下消息： | |||
| 如果你在 `rules.mk` 中配置了 `CONSOLE_ENABLE = yes`，你的键盘将会输出调试信息。默认情况下输出很有限，可以启用调试模式来增加调试输出的丰富度。使用你的键映射方案中的 `DEBUG` 键码，或使用[指令](zh-cn/feature_command.md)功能来启动调试模式，或者将下面这段代码放到你的键映射中： | |||
| ``` | |||
| Waiting for new device:......................... | |||
| Listening: | |||
| ```c | |||
| void keyboard_post_init_user(void) { | |||
| // 通过调整这些值可以改变其表现 | |||
| debug_enable=true; | |||
| debug_matrix=true; | |||
| //debug_keyboard=true; | |||
| //debug_mouse=true; | |||
| } | |||
| ``` | |||
| 如果您无法获得这条“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)。 | |||
| ### 使用QMK工具箱调试 | |||
| ## Linux或UNIX这样的系统如何请求超级用户权限 | |||
| 用'sudo'来执行*hid_listen*就有权限了。 | |||
| ``` | |||
| $ sudo hid_listen | |||
| ``` | |||
| 在兼容的平台上，[QMK工具箱](https://github.com/qmk/qmk_toolbox)可以展示你的键盘的调试输出。 | |||
| 或者把一个文件放到规则文件夹来为TMK设备添加*udev规则*，不同系统的目录可能有所不同。 | |||
| ### 使用 QMK CLI 进行调试 | |||
| 文件: /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" | |||
| ``` | |||
| 倾向于在终端进行调试？使用 [QMK CLI 命令行](zh-cn/cli_commands.md#qmk-console)可以展示键盘输出的调试信息。 | |||
| *** | |||
| ### 使用hid_listen调试 | |||
| # 其他 | |||
| ## 安全注意事项 | |||
| 更喜欢使用终端的方案？PJRC提供的[hid_listen](https://www.pjrc.com/teensy/hid_listen.html)也可以用来展示调试信息，已有Windows、Linux及MacOS下预编译好的可执行文件。 | |||
| 你应该不想要把你的键盘变成"砖头"吧，就是变成没法重写固件的那种。 | |||
| 下面讲解一些参数来告诉你什么风险很大（其实也不是很大）。 | |||
| ## 发送自定义调试信息 :id=debug-api | |||
| - 假如你键盘表面没有设计重置键"RESET", 那你要进入bootloader的话就要按PCB上的RESET了。 | |||
| 按PCB上的RESET要拧开键盘底部。 | |||
| - 如果 tmk_core / common 里面的文件丢失键盘可能失灵。 | |||
| - .hex太大可能不太好; `make dfu` 会删除块，检验大小（咦?好像反了...）。 | |||
| 一但出错，刷新键盘失败的话就困在DFU出不去了。 | |||
| - 所以, 要知道大小限制。 Planck键盘上.hex文件最大大小是 is 7000h (十进制是28672) | |||
| 有时在[自定义代码](zh-cn/custom_quantum_functions.md)中输出调试信息非常有用，要做到这个功能也很简单，在代码文件头部包含 `print.h` 文件： | |||
| ```c | |||
| #include "print.h" | |||
| ``` | |||
| 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`。 | |||
| * `print("string")`: 字符串输出 | |||
| * `uprintf("%s string", var)`: 格式化字符串输出 | |||
| * `dprint("string")` 仅调试模式下，字符串输出 | |||
| * `dprintf("%s string", var)`: 仅调试模式下，格式化字符串输出 | |||
| 全键无冲还不好用的话试着用`Magic` **N** 命令(默认是`LShift+RShift+N`)。这个命令会在**全键无冲**和**六键无冲**之间临时切换。有些情况**全键无冲**不好用你就需要使用**六键无冲**模式，尤其是在BIOS中。 | |||
| ## 调试示例 | |||
| 以下列出了一些实际出现过的调试范例，更多资料参见[调试/定位QMK问题](zh-cn/faq_debug.md)。 | |||
| ## 指点杆需要复位电路(PS/2 鼠标支持) | |||
| 如果没有复位电路，由于硬件初始化不正确，您将得到不一致的结果。查看TPM754复位电路。 | |||
| ### 当前按下的键的矩阵坐标是什么？ | |||
| - https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447 | |||
| - https://www.mikrocontroller.net/attachment/52583/tpm754.pdf | |||
| 在移植或尝试诊断PCB问题时，确认按下的键被正确扫描到是很有用的排查步骤。要启用该场景的日志输出，请在 `keymap.c` 中添加： | |||
| ```c | |||
| bool process_record_user(uint16_t keycode, keyrecord_t *record) { | |||
| // If console is enabled, it will print the matrix position and status of each key pressed | |||
| #ifdef CONSOLE_ENABLE | |||
| 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); | |||
| #endif | |||
| return true; | |||
| } | |||
| ``` | |||
| ## 矩阵不可读16以上的列 | |||
| 当列超过16时[matrix.h]的`read_cols()`中，用`1UL<<16`而不要用`1<<16`。 | |||
| 在C语言中`1` 是一个[int] 类型的[16 bit]值，在AVR中你不能左移大于15次。如果你使用`1<<16`的话会得到意外的零。你要用 [unsigned long]类型，比如`1UL`。 | |||
| 输出示例 | |||
| ```text | |||
| Waiting for device:....... | |||
| Listening: | |||
| KL: kc: 169, col: 0, row: 0, pressed: 1 | |||
| KL: kc: 169, col: 0, row: 0, pressed: 0 | |||
| KL: kc: 174, col: 1, row: 0, pressed: 1 | |||
| KL: kc: 174, col: 1, row: 0, pressed: 0 | |||
| KL: kc: 172, col: 2, row: 0, pressed: 1 | |||
| KL: kc: 172, col: 2, row: 0, pressed: 0 | |||
| ``` | |||
| https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 | |||
| ### 扫描到一个键码需要多久？ | |||
| ## 特殊额外键不起作用(系统，音频控制键) | |||
| 你要在`rules.mk`定义`EXTRAKEY_ENABLE`在QMK中使用它们。 | |||
| 调试性能问题时，知晓开关矩阵的扫描频率是很有用的排查步骤。要启用该场景的日志输出，请在 `config.h` 中添加： | |||
| ```c | |||
| #define DEBUG_MATRIX_SCAN_RATE | |||
| ``` | |||
| EXTRAKEY_ENABLE = yes # 音频控制和系统控制 | |||
| ``` | |||
| ## 睡眠唤醒不好用 | |||
| 在Windows查看设备管理器中该键盘设备属性中电源管理选项卡中的`允许此设备唤醒计算机(O)`是否勾选。同时看一眼BIOS设置。 | |||
| 在主机睡眠时按下任何键都可以唤醒了。 | |||
| 输出示例 | |||
| ```text | |||
| > matrix scan frequency: 315 | |||
| > matrix scan frequency: 313 | |||
| > matrix scan frequency: 316 | |||
| > matrix scan frequency: 316 | |||
| > matrix scan frequency: 316 | |||
| > matrix scan frequency: 316 | |||
| ``` | |||
| ## 使用Arduino? | |||
| ## `hid_listen` 无法识别到设备 | |||
| **注意Arduino的针脚名字和主控芯片的不一样。** 比如, Arduino的`D0`并不是`PD0`。自己用原理图捋一下电路。 | |||
| 如果设备没有就绪，在命令行下调试会看到如下输出： | |||
| - https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf | |||
| - https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf | |||
| ``` | |||
| Waiting for device:......... | |||
| ``` | |||
| Arduino Leonardo和micro使用**ATMega32U4**，该芯片TMK可用，但Arduino的bootloader会导致问题。 | |||
| 当设备插入后，*hid_listen*可以发现设备，会有如下输出： | |||
| ## USB 3 兼容性 | |||
| 据传说有些人用USB3接口会有问题，用USB2的试试。 | |||
| ``` | |||
| Waiting for new device:......................... | |||
| Listening: | |||
| ``` | |||
| 若无法出现'Listening:'消息，尝试在[Makefile]中添加 `CONSOLE_ENABLE=yes` | |||
| ## Mac 兼容性 | |||
| ### OS X 10.11 和集线器 | |||
| https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034 | |||
| 在类Linux系统下，访问设备可能需要一定权限，尝试使用 `sudo hid_listen`。 | |||
| 此外，很多Linux发行版可以通过创建如下内容的文件 `/etc/udev/rules.d/70-hid-listen.rules` 来避免通过root权限执行hid_listen： | |||
| ## 对于BIOS (UEFI)/恢复(睡眠和唤醒)/重新启动 有问题 | |||
| 有人说他们的键盘在BIOS中，或许是恢复(睡眠和唤醒)后不工作. | |||
| ``` | |||
| SUBSYSTEM=="hidraw", ATTRS{idVendor}=="abcd", ATTRS{idProduct}=="def1", TAG+="uaccess", RUN{builtin}+="uaccess" | |||
| ``` | |||
| 截止至目前，其根本原因未知，不排除与某些构建选项有关。试着在Makefile中失能`CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE`这样的选项，也试试其他的。 | |||
| 使用设备的真实VID和PID替换上面的abcd和def1，留意必须全小写。其中 `RUN{builtin}+="uaccess"` 仅在较老的发行版中需要使用。 | |||
| https://github.com/tmk/tmk_keyboard/issues/266 | |||
| https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 | |||
| ## 命令行无法成功输出消息 | |||
| 请检查: | |||
| - *hid_listen*确实找到了设备，如前文所述。 | |||
| - 通过**Magic**+d命令启用调试模式，参见[Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands). | |||
| - 配置`debug_enable=true`. 参见[调试](#debugging) | |||
| - 尝试用 `print` 替代 `dprint`， 参见**common/print.h**. | |||
| - 拔出其它可能影响命令行的设备，参见[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97). | |||
+ 49
- 10
docs/zh-cn/faq_general.md
View File
| @ -1,19 +1,58 @@ | |||
| # 常见问题 | |||
| # 甯歌�闂��锛團AQ锛� | |||
| ## QMK是什么? | |||
| <!--- | |||
| original document: 0.15.12:docs/faq_general.md | |||
| git diff 0.15.12 HEAD -- docs/faq_general.md | cat | |||
| --> | |||
| [QMK](https://github.com/qmk), 是量子机械键盘(Quantum Mechanical Keyboard)的缩写，是一群开源爱好者为定制键盘开发的工具。我们从[QMK固件](https://github.com/qmk/qmk_firmware)开始，这是[TMK](https://github.com/tmk/tmk_keyboard)的魔改分叉。 | |||
| ## QMK鏄�粈涔�? | |||
| ### 为什么叫量子(Quantum)? | |||
| [QMK](https://github.com/qmk), 鏄�噺瀛愭満姊伴敭鐩橈紙Quantum Mechanical Keyboard锛夌殑缂╁啓, 鏄�埗浣滆嚜瀹氫箟閿�洏宸ュ叿鐨勪汉缁勬垚鐨勭粍缁囥€� 涓€鍒囧�浜嶽QMK鍥轰欢](https://github.com/qmk/qmk_firmware)椤圭洰, 鍙�互璁や负鏄痆TMK](https://github.com/tmk/tmk_keyboard)鐨勬敼杩涚増鏈�. | |||
| <!-- 待修复 译者吐槽：文档作者竟然也不知道为啥。。。 --> | |||
| ## 涓嶇煡閬撲粠鍝�紑濮嬫悶锛� | |||
| ## QMK和TMK有什么区别? | |||
| 杩欐牱鐨勮瘽寤鸿�浠嶽鏂版墜鎸囧紩](zh-cn/newbs.md)寮€濮嬨€傞偅閲屾湁浣犻渶瑕佺殑楂樿川閲忕殑鍏ラ棬淇℃伅銆� | |||
| TMK最初由[Jun Wako](https://github.com/tmk)设计和执行。QMK始于[Jack Humbert](https://github.com/jackhumbert)为Planck键盘创建的TMK分叉。一段时间后，Jack的分叉就和TMK相去甚远了，于是在2015年，Jack决定改名QMK。 | |||
| 濡傛灉杩樻槸鎼炰笉鎳傜殑璇濓紝鐩存帴璺冲埌[QMK閰嶇疆鍣╙(https://config.qmk.fm)鍚э紝浣犳牳蹇冮渶瑕佺殑涓滆タ閮藉湪閭ｉ噷銆� | |||
| 从技术观点来讲，QMK是TMK添加一些新功能而成的。尤其是QMK扩展了可用的键码，使高级功能进一步丰富比如 `S()`, `LCTL()`, 和 `MO()`。全部键码见[键码](keycodes.md). | |||
| ## 鎴戠殑鍥轰欢濡備綍鍒峰啓鍒扮‖浠朵笂锛� | |||
| 从工程的社区管理来讲TMK自己维护了所有官方支持的键盘，只有很小一部分社区支持。独立社区维护已存在分叉或为其他键盘创建的分叉。默认支持很少的键码，所以用户通常不会与他人分享布局。QMK鼓励通过集中管理仓库分享布局和键盘，我们会采纳所有符合质量标准的PR。这就极大的保证了社区维护，同时QMK小组也会在必要时给予帮助。 | |||
| 鍏堝弬鑰僛缂栬瘧/鍒峰啓鍥轰欢FAQ](zh-cn/faq_build.md)锛岄噷闈㈡湁鍏呰冻鐨勮祫鏂欙紝甯歌�鐨勯棶棰樹篃缁欏嚭浜嗚冻澶熷�鐨勮В鍐冲姙娉曘€� | |||
| 这两种方法都有其优点和缺点，并且代码在有意义时在TMK和QMK之间自由流动。 | |||
| ## 鎴戠殑闂��杩欓噷鎵句笉鍒扮浉鍏充俊鎭�€庝箞鍔烇紵 | |||
| 娌℃湁鍏崇郴锛岃�鍒癧GitHub涓婂彂issue](https://github.com/qmk/qmk_firmware/issues)鐪嬬湅鏄�惁鏈変汉閬囧埌浜嗙浉鍚岀殑闂��锛堢暀鎰忎竴瀹氭槸鐩稿悓鐨勯棶棰橈紝鑰屼笉鏄�浉浼肩殑锛夈€� | |||
| 濡傛灉杩樻槸鎵句笉鍒拌В鍐冲姙娉曪紝璇穂鏂板缓issue](https://github.com/qmk/qmk_firmware/issues/new)锛� | |||
| ## 鎴戝ソ鍍忔壘鍒颁簡bug锛� | |||
| 閭ｄ箞鏂板缓涓€涓猍issue](https://github.com/qmk/qmk_firmware/issues/new)鍚э紝濡傛灉浣犺繕鐭ラ亾鎬庝箞淇�紝甯︾潃淇��鏂规�鍙戜釜Pull Request鍚с€� | |||
| ## 浣嗘槸 `git` 鍜� `GitHub` 鎴戝疄鍦ㄦ槸鐜╀笉杞�紒 | |||
| 鍒�媴蹇冿紝杩欓噷鏈夊緢濂界殑[鍏ラ棬鎸囧紩](zh-cn/newbs_git_best_practices.md)鍙�互鏁欎綘鎬庝箞杞绘澗蹇�箰鍦颁娇鐢� `git` 鍜孏itHub杩涜�寮€鍙戙€� | |||
| 鏇村�鐨� `git` 鍜孏itHub鐭ヨ瘑锛屽弬鑰僛杩欓噷](zh-cn/newbs_learn_more_resources.md)銆� | |||
| ## 鎴戝彲浠ユ坊鍔犱竴涓�敮鎸佺殑閿�洏 | |||
| 澶��鍟︼紒璇峰彂Pull Request鍚э紝鍦ㄤ唬鐮佸�闃呭悗锛屾垜浠�細鍚堝苟杩涘幓锛� | |||
| ### 鎴戝彲浠ユ墦涓� `QMK` 鐨勬爣鍚�? | |||
| 寰堝ソ鍟婏紒鎴戜滑鐢氳嚦涔愭剰甯�綘杩欎箞鍋氾紒 | |||
| 鎴戜滑鏈塠涓€鏁撮〉](https://qmk.fm/powered/)鐨勮祫鏂欐棬鍦ㄥ府浣犲湪椤甸潰鍜岄敭鐩樹笂鎵撲笂QMK鐨勬爣锛岄噷闈㈡湁QMK瀹樻柟鎻愪緵鐨勬墍鏈夋敮鎻达紙淇℃伅鍙婂浘鐗囷級銆� | |||
| 濡傛灉浣犳湁浠讳綍鐤戦棶锛屽彲浠ュ彂issue鎴栭€氳繃[Discord](https://discord.gg/Uq7gcHh)鑱旂郴鎴戜滑銆� | |||
| ## QMK鍜孴MK鍖哄埆鏄�粈涔堬紵 | |||
| TMK鍘熷厛鏄�敱[Jun Wako](https://github.com/tmk)璁捐�瀹炵幇鐨勶紝QMK鏉ユ簮浜嶽Jack Humbert](https://github.com/jackhumbert)鐨凱lanck鐨凾MK fork銆備竴娈垫椂闂村悗锛孞ack鐨勮繖涓猣ork涓嶵MK娓愯�娓愯繙锛屽埌2015骞存椂锛孞ack鍐冲畾灏嗚繖浠絝ork閲嶅懡鍚嶄负QMK銆� | |||
| 鎶€鏈�笂璁睶MK绛夊悓浜庡熀浜嶵MK澧炲姞浜嗕竴浜涙柊鍔熻兘锛屾渶鏄捐憲鐨勬槸鍦ㄦ墿鍏呬簡鍙�敤閿�爜鍚庯紝瀹炵幇浜嗗緢澶氳�濡� `S()`, `LCTL()` 鍙� `MO()` 杩欐牱鐨勯珮绾у姛鑳斤紝鎵€鏈夎繖浜涢敭鐮佸彲浠ュ弬瑙乕閿�爜](zh-cn/keycodes.md)椤点€� | |||
| 浠庡伐绋嬮」鐩�強绀惧尯缁存姢瑙掑害鏉ョ湅锛孴MK缁存姢浜嗕竴浠藉畼鏂规敮鎸佺殑閿�洏鍙婂緢灏戦噺鐨勭ぞ鍖鸿础鐚�紝绀惧尯涓�悇鑷�淮鎶ょ潃鍚勮嚜鐨刦ork锛屼笖鍥犱负榛樿�閿�槧灏勫緢灏戯紝TMK鐨勪娇鐢ㄨ€呭熀鏈�笉浼氬叡浜�敭鏄犲皠銆俀MK閫氳繃缁熶竴鐨勯泦绾﹀紡浠撳簱锛坮epo锛夌�鐞嗘潵榧撳姳鍒嗕韩閿�洏鍙婇敭鏄犲皠锛屼换浣曠�鍚堣川閲忓熀绾跨殑pull request閮戒細琚�噰绾筹紝鍥犳�缁濆ぇ閮ㄥ垎璐＄尞閮芥潵婧愪簬绀惧尯锛孮MK灏忕粍浼氬湪蹇呰�鏃舵彁渚涙敮鎻淬€� | |||
| 涓ょ�妯″紡鍚勬湁鍒╁紛锛屽苟涓擳MK鍜孮MK涔嬮棿涔熶細鏈夊悎涔庣悊娉曠殑浠ｇ爜浜ゆ祦銆� | |||
+ 89
- 83
docs/zh-cn/faq_keymap.md
View File
| @ -1,151 +1,157 @@ | |||
| # 布局常见问题 | |||
| # 键映射FAQ | |||
| 本页本页包含人们经常遇到的关于布局的问题。如果你觉得没什么问题，请先看[布局概览](keymap.md)。 | |||
| <!--- | |||
| original document: 0.15.12:docs/faq_keymap.md | |||
| git diff 0.15.12 HEAD -- docs/faq_keymap.md | cat | |||
| --> | |||
| ## 我能用什么键码? | |||
| 看[键码](keycodes.md)你可以找到你能用的键码索引。可以的话这些链接可以连接到更广泛的文档。 | |||
| 本页包含人们经常遇到的关于键映射的问题，如果你还没阅读过[键映射概览](zh-cn/keymap.md)，请先阅读一下。 | |||
| 键码实际上定义在[common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h). | |||
| ## 我能使用的键码有哪些? | |||
| 所有可用键码收录在[键码](zh-cn/keycodes.md)页，在有更详尽的文档时，我们会更新这个链接。 | |||
| ## 默认的键码什么样? | |||
| 所有键码实际定义在[quantum/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h). | |||
| 世界上有三种标准键盘设计，分别是：ANSI, ISO, and JIS. 主要是北美用ANSI(译者注：中国很多键盘使用这个), 欧洲和非洲主要使用ISO，日本使用JIS。未提及的区域通常使用ANSI或ISO。与这些设计对应的键代码如下所示： | |||
| ## 默认键码是什么? | |||
| <!-- 该图片的来源: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a --> | |||
|  | |||
| 广为使用的键盘配列有三种——ANSI，ISO及JIS。北美主要使用ANSI，欧洲及非洲主要使用ISO，日本主要使用JIS，其它区域多为ANSI或ISO。这三种配列的键码可查阅： | |||
| ## 我有一些键变成了其他功能或者不工作了 | |||
| <!-- Source for this image: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a --> | |||
|  | |||
| QMK有两个功能，Bootmagic和命令行，它允许您在运行中更改键盘的行为。该功能包括但不仅限于, 交换Ctrl/Caps，关闭界面，交换Alt/Gui，交换 Backspace/Backslash，禁用所有键，以及其他的行为改变。 | |||
| ## 如何对复杂的键码指定自定义的名称？ | |||
| 快速解决方法是插入键盘时按住`Space`+`Backspace`。该操作将重置已保存设置，让这些键回复初始功能。这招不好用的话参阅下方： | |||
| 使用更容易理解的自定义的名字去指代一些键码有时很实用，通常我们使用 `#define` 来实现： | |||
| * [Bootmagic](feature_bootmagic.md) | |||
| * [命令](feature_command.md) | |||
| ```c | |||
| #define FN_CAPS LT(_FL, KC_CAPSLOCK) | |||
| #define ALT_TAB LALT(KC_TAB) | |||
| ``` | |||
| 这样键映射代码中就可以使用 `FN_CAPS` 和 `ALT_TAB` 了，可读性好得多。 | |||
| ## 一些按键发生了交换，或是不能用了 | |||
| QMK有两个功能系列，Bootmagic及指令，都可以让键盘随时变得灵活多变，功能包含但不限于交换Ctrl/Caps、锁定Gui键、交换Alt/Gui、交换Backspace/Backslash、禁用所有按键等。 | |||
| ## 菜单键不好用 | |||
| 快速恢复的办法是插入键盘时按住空格+`Backspace`键，这样会重置键盘内存储的设置信息，键盘就会恢复常态。如果问题依旧存在，请参考： | |||
| 现在大多数键盘 `KC_RGUI`和`KC_RCTL`中间的键子叫做`KC_APP`。这是因为在这个键子发明之前相关标准里就已经有键叫做`MENU(菜单)`了，所以微软叫他`APP(应用)`键。 | |||
| * [Bootmagic](zh-cn/feature_bootmagic.md) | |||
| * [指令](zh-cn/feature_command.md) | |||
| ## `KC_SYSREQ` 不工作 | |||
| 使用抓屏的键码(`KC_PSCREEN`或`KC_PSCR`)而不用`KC_SYSREQ`。组合键'Alt + Print Screen'会被当作'System request'。 | |||
| ## 菜单键（Menu）不可用 | |||
| 见[issue #168](https://github.com/tmk/tmk_keyboard/issues/168)和 | |||
| 现代键盘上，位于 `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)以及 | |||
| * https://en.wikipedia.org/wiki/Magic_SysRq_key | |||
| * https://en.wikipedia.org/wiki/System_request | |||
| ## 电源键不工作 | |||
| 这有点让人困惑,QMK有两个"Power(电源)"键码: `KC_POWER` 在键盘/小键盘的HID使用页面中，`KC_SYSTEM_POWER` (或者叫`KC_PWR`)在用户页。 | |||
| QMK有两个容易让人迷惑的“电源键”键码：HID键盘页的 `KC_POWER`，及用户页的 `KC_SYSTEM_POWER`（或 `KC_PWR`）。 | |||
| 前者只能被macOS识别，但是后者，即`KC_SLEP`和`KC_WAKE`三大主要操作系统全都支持，所以推荐使用这两个。Windows下这些键立即生效，macOS要长按直到弹出对话框。 | |||
| 前者只有macOS支持，后者连同 `KC_SLEP` 及 `KC_WAKE` 在所有主流操作系统上都支持，因此使用后者是推荐的做法。在Windows下，按下按键即刻就会生效，而macOS下必须按住直到系统弹出一个对话框。 | |||
| ## 自动大小写锁定 | |||
| 可以解决'the'问题(正常应为The)。我经常在输入'The'时不慎输入了'the'或者'THe'。自动大小写锁定可以修正此类问题。详见下方链接。 | |||
| ## 单发修饰键 | |||
| 用来解决我自己的’the‘麻烦，我总是会将’The‘错输入为’the‘或’THe‘，单发Shift键缓解了我的这个麻烦。 | |||
| https://github.com/tmk/tmk_keyboard/issues/67 | |||
| ## 修改 键/层 卡住 | |||
| 除非正确配置层切换，否则修改键或层可能会卡住。 | |||
| 对于修改键和图层操作，必须把`KC_TRANS`放到目标层的相同位置，用于注销修改键或在释放事件时返回到上一层。 | |||
| ## 修饰键/层 卡住了 | |||
| 层切换功能只有在正确配置的情况下，才不会出现卡住修饰键和层的问题。 | |||
| 对于修饰键和层切换操作来讲，必须确保 `KC_TRANS` 在切换到目标layer时正确置位，才能让修饰键正确释放。或者在释放动作中确保返回到了之前的层。 | |||
| * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching | |||
| * https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604 | |||
| * https://github.com/tmk/tmk_keyboard/issues/248 | |||
| ## 机械自锁开关支持Mechanical Lock Switch Support | |||
| ## 机械锁定式开关支持 | |||
| 本功能用于*机械自锁开关*比如[this Alps one](https://deskthority.net/wiki/Alps_SKCL_Lock)。你可以通过向`config.h`添加以下宏来使能该功能： | |||
| 该功能支持形如[Alps这款](https://deskthority.net/wiki/Alps_SKCL_Lock)的*机械锁定式开关*，启用该功能须在 `config.h` 中添加如下定义： | |||
| ``` | |||
| #define LOCKING_SUPPORT_ENABLE | |||
| #define LOCKING_RESYNC_ENABLE | |||
| ``` | |||
| 在使能该功能后，要在键盘中使用`KC_LCAP`, `KC_LNUM` 和 `KC_LSCR`这三个键码。 | |||
| 启用该功能后，在你的键映射中须改为使用 `KC_LCAP`，`KC_LNUM` 和 `KC_LSCR`。 | |||
| 远古机械键盘偶尔会有自锁机械开关，现在几乎没有了。***大多数情况下你不需要使用该功能，且要使用`KC_CAPS`, `KC_NLCK`和`KC_SLCK`这三个键码。*** | |||
| 旧式复古风（vintage style）键盘偶尔能见到锁定式开关，但在现代键盘中见不到了。***因此你基本不会需要这个功能的，直接使用 `KC_CAPS`，`KC_NLCK` 和 `KC_SLCK` 就好*** | |||
| ## 输入ASCII之外的特殊字符比如Cédille 'Ç' | |||
| ## 输入形如法语中软音'Ç'这样的非ASCII字符 | |||
| 请见[Unicode](feature_unicode.md)功能。 | |||
| 参见[Unicode](zh-cn/feature_unicode.md)功能. | |||
| ## macOS上的`Fn` | |||
| ## macOS系统下的 `Fn` | |||
| 不像大多数FN键，苹果上那个有自己的键码...呃，基本上算吧。 他取缔了基本6键无冲HID报告的第六个键码 -- 所以苹果键盘其实是5键无冲的。 | |||
| 和其它键盘不同，Apple键盘上的Fn有自己的键码...在某种程度上。其占用了基础6KRO HID事件上报中的第六个键码 —— 因此Apple键盘实际上只是5KRO（5键无冲）的。 | |||
| 技术上说QMK可以发送这个键。但是，这样做需要修改报告格式以添加FN键的状态。这还不是最糟糕的，你的键盘的VID和PID和真的苹果键盘不一样的话还不会被识别。 | |||
| QMK官方支持这个会被律师函的，所以就当我没说过。 | |||
| 技术上讲QMK确实能发送这种键码，但这么做需要修改上报事件中Fn键状态的格式。更麻烦的是，只有你的键盘的VID及PID与Apple键盘一致时才会生效。QMK对此提供官方支持可能会有法律风险，换句话说，我们不太可能去这么做的。 | |||
| 详见[issue#2179](https://github.com/qmk/qmk_firmware/issues/2179)。 | |||
| 具体信息请参见[这个issue](https://github.com/qmk/qmk_firmware/issues/2179)。 | |||
| ## Mac OSX下支持的键有哪些？ | |||
| 你可以通过查阅以下代码确认OSX下支持的键码。 | |||
| ## 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内部键码). | |||
| `usb_2_adb_keymap` 数组实现了从 Keyboard/Keypad 页到 ADB 扫描码（OSX内部使用的键码）的转换。 | |||
| https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c | |||
| `IOHIDConsumer::dispatchConsumerEvent`会处理用户页面用法。 | |||
| <!--翻译问题：上面那两句翻译的不好-> handles Consumer page usages. --> | |||
| 以及 `IOHIDConsumer::dispatchConsumerEvent` 负责处理用户页部分。 | |||
| 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键 | |||
| ## Mac OSX下的JIS键 | |||
| 日语体系的JIS键盘有些特殊键码：`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` 在OSX下无法被识别，可以尝试通过以下配置借助 **Seil** 来启用这些键。 | |||
| https://pqrs.org/osx/karabiner/seil.html | |||
| * 在PC键盘中启用NFER键 | |||
| * 在PC键盘中启用XFER键 | |||
| * 在PC键盘中启用KATAKANA键 | |||
| 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 | |||
| 此问题详见下方链接。 | |||
| ## RN-42蓝牙模块与Karabiner的兼容性问题 | |||
| Karabiner - Mac OSX系统下的键映射工具 - 默认会忽略RN-42模块的输入事件。须在Karabiner开启相关选项来支持你的键盘。 | |||
| https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559230 | |||
| 这个问题的其它详细信息参见 | |||
| https://github.com/tmk/tmk_keyboard/issues/213 | |||
| https://github.com/tekezo/Karabiner/issues/403 | |||
| ## Esc 和 <code>`</code> 双功能键 | |||
| 请见[Grave Escape](feature_grave_esc.md)功能。 | |||
| ## Esc和<code>`</code>位于同一个键位 | |||
| ## Mac OSX的弹出键 | |||
| `KC_EJCT` 键码在OSX可以使用 https://github.com/tmk/tmk_keyboard/issues/250 | |||
| 似乎Windows10会忽略该键码，Linux/Xorg可以识别该键码但默认不映射。 | |||
| 参见[Grave Escape](zh-cn/feature_grave_esc.md)功能. | |||
| 目前尚不清楚如何在真正的苹果键盘按出弹出键。HHKB使用`F20`用于弹出键(`Fn+f`)，该功能在MAC模式有效但不保证与苹果弹出键码相符。 | |||
| ## Mac OSX下的弹出功能 | |||
| `KC_EJCT` 在OSX下可用。 https://github.com/tmk/tmk_keyboard/issues/250 | |||
| Windows 10应该是忽略了这个键码，Linux/Xorg能识别到，但默认没有映射处理。 | |||
| 目前尚不清楚Apple键盘上弹出键到底是啥，HHKB在Mac模式下使用 `F20` 来作为弹出键（`Fn+f`），但应该和Apple的弹出键码不是一回事儿。 | |||
| ## `action_util.c`中的 `weak_mods`和`real_mods`是什么 | |||
| ___待改善___ | |||
| ## 在 `action_util.c` 中的 `weak_mods` 和 `real_mods` 是什么东西？ | |||
| ___待完善的内容___ | |||
| real_mods 用于保存实际(物理)修改键的实际状态。 | |||
| weak_mods 用于保存虚拟或临时修改键，它将不会影响实际修改键。 | |||
| real_mods保存的是现实的/物理上的修饰键状态，而weak_mods保存的是虚拟的或临时的修饰键状态，且不应该影响到真实的修饰键的状态。 | |||
| 以按下左侧Shift键然后输入ACTION_MODS_KEY(LSHIFT, KC_A)为例， | |||
| 例如你按住了物理键盘上的左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): 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时, | |||
| * (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现已全部加入键盘数据包发送豪华套餐。 | |||
| 在键盘事件发送时，weak_mods会与real_mods求逻辑或。 | |||
| https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57 | |||
+ 108
- 0
docs/zh-cn/faq_misc.md
View File
| @ -0,0 +1,108 @@ | |||
| # 其它 FAQ | |||
| <!--- | |||
| original document: 0.15.12:docs/faq_misc.md | |||
| git diff 0.15.12 HEAD -- docs/faq_misc.md | cat | |||
| --> | |||
| ## 怎么对键盘进行测试？ :id=testing | |||
| 测试键盘就简单直接，把每个按键按一遍后确认发送的是正确的就行。也可以使用[QMK配置器](https://config.qmk.fm/#/test/)的测试模式检查键盘，即便这键盘没有运行着QMK。 | |||
| ## 安全措施 | |||
| 你应该不想见到键盘变砖，变得不能再刷写固件。这里给出了一些非常危险（或相反不太危险）的因素。 | |||
| - 如果你的键盘没有RESET键，在你需要进入DFU模式时，不得不需要用螺丝刀打开后盖去按PCB上的RESET键。 | |||
| - 把 tmk_core/common 下的文件搞乱的话，容易导致键盘无法使用 | |||
| - .hex文件太大的话也会引起问题。`make dfu` 会先擦除存储块，再检查固件大小（哎呀，顺序错了），此时发现错误进而导致刷写失败，键盘停留在DFU模式下。 | |||
| - 因此，请留意.hex文件尺寸有大小限制，例如在Planck上是十六进制7000（十进制的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被覆写（除非你往DFU工具上塞自己的东西），这个风险不大。 | |||
| - EEPROM的写循环一般是 100000（100k）次，不应不停地持续重复地刷写固件，不然很快就烧毁了。 | |||
| ## NKRO 不好使 | |||
| 首先请确保在编译固件时有在**Makefile**中启用 `NKRO_ENABLE` | |||
| 如果依旧不行，尝试一下 `Magic` **N** 指令（默认是左Shift+右Shift+N），这个指令可以让键盘在**NKRO**和**6KRO**模式间临时切换。有的场景下**NKRO**无法工作必须切换到**6KRO**模式，比如在BIOS中操作时。 | |||
| 如果你的固件编译时指定了 `BOOTMAGIC_ENABLE` ，则需要使用 `BootMagic`**N** 指令（默认是空格+N）。这个配置保存在EEPROM中，断电也会留存。 | |||
| https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch | |||
| ## 轨迹球需要复位电路 (PS/2鼠标支持) | |||
| 缺失复位电路的情况下，由于不正确的硬件初始化，可能会导致设备不稳定，具体请参阅TPM754的电路原理图： | |||
| - https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447 | |||
| - https://www.mikrocontroller.net/attachment/52583/tpm754.pdf | |||
| ## 无法读到大于16的矩阵列 | |||
| 当列数大于16时，在 [matrix.h] 中的 `read_cols()` 中请用 `1UL<<16` 替代 `1<<16`。 | |||
| 在C语言中，对于AVR上的 `1`，会被视作一种[16位]的[整形(int)]类型，因此无法左移超过15位。因此 `1<<16` 的计算结果会错误地变成0。解决办法就是将类型改为[无符号长整形(unsigned long)]类型的 `1UL`。 | |||
| https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 | |||
| ## 有些额外的按键不好使（系统，音频控制键） | |||
| 在QMK的 `rules.mk` 中须定义 `EXTRAKEY_ENABLE` | |||
| ``` | |||
| EXTRAKEY_ENABLE = yes # 音频及系统控制 | |||
| ``` | |||
| ## 无法从休眠唤醒 | |||
| 在Windows的**电源管理**的**设备管理**中，检查 `允许该设备唤醒计算机` 选项，同时检查一下BIOS中的相关设置，任意一个按键都应该能将计算机从休眠状态唤醒。 | |||
| ## 在使用Arduino? | |||
| **注意Arduino的引脚编号与芯片的引脚编号是不同的**。例如，Arduino的 `D0` 引脚并不是 `PD0`，请对照其电路图检查电路。 | |||
| - https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf | |||
| - https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf | |||
| Arduino Leonardo 以及 micro 使用的是**ATMega32U4**因此可以用TMK，但bootloader可能会是个麻烦的问题。 | |||
| ## 启用JTAG | |||
| 默认情况下，键盘启动后JTAG调试接口就被禁用了。支持JTAG的MCU出场时会带着 `JTAGEN` 保险丝，而键盘因为需要这部分MCU的引脚去控制开关矩阵、LED等功能。 | |||
| 如果你希望启用JTAG，在 `config.h` 中添加定义： | |||
| ```c | |||
| #define NO_JTAG_DISABLE | |||
| ``` | |||
| ## USB 3兼容性问题 | |||
| 将设备从USB 3.x端口改插到USB 2.0端口能解决一些问题。 | |||
| ## Mac相关兼容性问题 | |||
| ### OS X 10.11 和 Hub | |||
| 参见: 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 | |||
+ 39
- 0
docs/zh-cn/feature_grave_esc.md
View File
| @ -0,0 +1,39 @@ | |||
| # Grave Escape | |||
| <!--- | |||
| original document: 0.15.12:docs/feature_grave_esc.md | |||
| git diff 0.15.12 HEAD -- docs/feature_grave_esc.md | cat | |||
| --> | |||
| *译注：Grave键即标准键盘中Tab键上方的 <code>`</code> 键，该符号用于英法语等西语体系，辅助调整发音，中文中没有对应概念；Escape即Esc键* | |||
| 若你使用60%或其它没有Fn键配列的键盘，会留意到没有独立的Escape键。Grave Escape功能可以让Grave键(<code>`</code>及`~`)与Escape共享一个按键 | |||
| ## 使用方法 | |||
| 在配列中使用 `KC_GESC` 替换 `KC_GRAVE` （一般都在`1`键左边）。默认点击会输出 `KC_ESC`，按下Shift或GUI键时，点击会输出 `KC_GRV` | |||
| ## 操作系统视角 | |||
| 假如翠花按下GESC键，系统接收到的是KC_ESC字符。若翠花按住Shift再按下GESC，将输出 `~` 或是反引号。若翠花按住GUI/CMD/Win键，将仅输出<code>`</code>字符 | |||
| ## 键码 | |||
| |键 |别名 |描述 | | |||
| |---------|-----------|------------------------------------------------------------------| | |||
| |`KC_GESC`|`GRAVE_ESC`|单击输出Escape, 按住Shift或GUI时输出<code>`</code> | | |||
| ### 须留意 | |||
| 在macOS上 Command+<code>`</code>默认行为是“移动焦点到下一个窗口”，因此不会输出反引号。另外，即便在键盘配置中更改过快捷键，终端程序(Terminal)也通常会将这个操作视为循环切换窗口 | |||
| ## 配置 | |||
| 有几种键组合可以变更这种行为，如Windows下的Control+Shift+Escape、macOS下的Command+Option+Escape。若要调整，可以在 `config.h` 中通过 `#define` 配置 | |||
| |定义 |描述 | | |||
| |--------------------------|-----------------------------------------| | |||
| |`GRAVE_ESC_ALT_OVERRIDE` |按住Alt时输出Escape | | |||
| |`GRAVE_ESC_CTRL_OVERRIDE` |按住Control时输出Escape | | |||
| |`GRAVE_ESC_GUI_OVERRIDE` |按住GUI时输出Escape | | |||
| |`GRAVE_ESC_SHIFT_OVERRIDE`|按住Shift时输出Escape | | |||
+ 70
- 0
docs/zh-cn/feature_space_cadet.md
View File
| @ -0,0 +1,70 @@ | |||
| # Space Cadet: The Future, Built In | |||
| <!-- Deliberately not translated, leave it to a suitable translation --> | |||
| <!--- | |||
| original document: 0.15.12:docs/feature_space_cadet.md | |||
| git diff 0.15.12 HEAD -- docs/feature_space_cadet.md | cat | |||
| --> | |||
| *译注：Space Cadet来源于(在西方早期程序员中)著名的键盘Space Cadet Keyboard，具体信息参见下面的链接或[维基百科](https://en.wikipedia.org/wiki/Space-cadet_keyboard)* | |||
| Steve Losh 在 [Space Cadet Shift](https://stevelosh.com/blog/2012/10/a-modern-space-cadet/) 详细地描述了该功能. 简而言之，点击左Shift时，会输出左括号；点击右Shift时，会输出右括号。如果按住Shift键，常规的Shift将正常工作。这功能实际上和听起来的一样爽，更爽的是现在连Control和Alt也支持！ | |||
| ## 使用指南 | |||
| 首先，在你的配列中完成以下任一项： | |||
| - 替换左Shift为 `KC_LSPO`（左Shift，左括号），替换右Shift为 `KC_RSPC`（右Shift，右括号）。 | |||
| - 替换左Control为 `KC_LCPO`（左Control，左括号），替换右Control为 `KC_RCPC`（右Control，右括号）。 | |||
| - 替换左Alt为 `KC_LAPO`（左Alt，左括号），替换右Alt为 `KC_RAPC`（右Alt，右括号）。 | |||
| - 替换任意一个Shift为 `KC_SFTENT`（右Shift，回车）。 | |||
| ## 键码 | |||
| |键码 |描述 | | |||
| |-----------|-----------------------------| | |||
| |`KC_LSPO` |按住时左Shift，点击时 `(` | | |||
| |`KC_RSPC` |按住时右Shift，点击时 `)` | | |||
| |`KC_LCPO` |按住时左Control，点击时 `(` | | |||
| |`KC_RCPC` |按住时右Control，点击时 `)` | | |||
| |`KC_LAPO` |按住时左Alt，点击时 `(` | | |||
| |`KC_RAPC` |按住时右Alt，点击时 `)` | | |||
| |`KC_SFTENT`|按住时右Shift，点击时回车 | | |||
| ## 须留意 | |||
| 同时按下两边的Shift键时会与Space Cadet功能冲突。请参见[指令功能](zh-cn/feature_command.md)以了解如何解决，也可以在 `rules.mk` 中禁用指令： | |||
| ```make | |||
| COMMAND_ENABLE = no | |||
| ``` | |||
| ## 配置 | |||
| 默认情况下Space Cadet假设键盘布局为US ANSI，如果你的布局使用不同的括号符，可以在 `config.h` 中重定义。可以修改修饰键点击时发送的字符，亦或阻止修饰键工作。这个新的配置项依次绑定了三个键码：按住或组合其它键使用时的修饰键；点击时发送的修饰键点击（`Tap Modifier`）（在 `KC_TRNS` 中没有修饰键时）；最后是点击时发送的键码。请记住，例如'KC_RSFT'按住时点击 `KC_KSPO` 及 `KC_TRNS` 时，修饰键依旧会对键码生效，即属于修饰键点击。 | |||
| |定义 |默认值 |描述 | | |||
| |----------------|-------------------------------|----------------------------------------------------------------| | |||
| |`LSPO_KEYS` |`KC_LSFT, LSPO_MOD, LSPO_KEY` |按住时发送`KC_LSFT`，点击时发送 `LSPO_MOD` 及 `LSPO_KEY` 定义的键码. | | |||
| |`RSPC_KEYS` |`KC_RSFT, RSPC_MOD, RSPC_KEY` |按住时发送`KC_RSFT`，点击时发送 `RSPC_MOD` 及 `RSPC_KEY` 定义的键码. | | |||
| |`LCPO_KEYS` |`KC_LCTL, KC_LSFT, KC_9` |按住时发送`KC_LCTL`，点击时发送 `KC_LSFT` 及 `KC_9`. | | |||
| |`RCPC_KEYS` |`KC_RCTL, KC_RSFT, KC_0` |按住时发送`KC_RCTL`，点击时发送 `KC_RSFT` 及 `KC_0`. | | |||
| |`LAPO_KEYS` |`KC_LALT, KC_LSFT, KC_9` |按住时发送`KC_LALT`，点击时发送 `KC_LSFT` 及 `KC_9`. | | |||
| |`RAPC_KEYS` |`KC_RALT, KC_RSFT, KC_0` |按住时发送`KC_RALT`，点击时发送 `KC_RSFT` 及 `KC_0`. | | |||
| |`SFTENT_KEYS` |`KC_RSFT, KC_TRNS, SFTENT_KEY` |按住时发送`KC_RSFT`，点击时发送 `SFTENT_KEY`. | | |||
| |`SPACE_CADET_MODIFIER_CARRYOVER` |*未定义* |在尝试触发其它修饰键的修饰键点击前，暂存目前的修饰键。这在尝试触发Space Cadet前频繁发生修饰键提前松开时会有用。(译注[^1]) | | |||
| ## 过时的配置项 | |||
| 以下是一些内部用于向后兼容的定义，目前仍可以使用，但上面的定义适用性要强得多。例如，若你点击 `KC_LSPO` 时不想按住修饰键，在旧定义中只有一个办法，使用 `DISABLE_SPACE_CADET_MODIFIER`。但现在可以定义为：`#define LSPO_KEYS KC_LSFT, KC_TRNS, KC_9`，效果是在按住按键时触发左Shift，点击则发送 `KC_9`。 | |||
| |定义 |默认值 |描述 | | |||
| |------------------------------|-------------|-------------------------------------| | |||
| |`LSPO_KEY` |`KC_9` |点击左Shift时发送的键码 | | |||
| |`RSPC_KEY` |`KC_0` |点击右Shift时发送的键码 | | |||
| |`LSPO_MOD` |`KC_LSFT` |应用在 `LSPO_KEY` 上的修饰键 | | |||
| |`RSPC_MOD` |`KC_RSFT` |应用在 `RSPC_KEY` 上的修饰键 | | |||
| |`SFTENT_KEY` |`KC_ENT` |点击Shift时发送的键码 | | |||
| |`DISABLE_SPACE_CADET_MODIFIER`|*未定义* |定义时将阻止修饰键应用在Space Cadet上 | | |||
| [^1]这句实在是绕，不能确保翻译到位，请参考英文文档 | |||
+ 329
- 0
docs/zh-cn/flashing.md
View File
| @ -0,0 +1,329 @@ | |||
| # 刷写指引及Bootloader资料 | |||
| <!--- | |||
| original document: 0.15.12:docs/flashing.md | |||
| git diff 0.15.12 HEAD -- docs/flashing.md | cat | |||
| --> | |||
| 用于键盘的bootloader有很多种，几乎每一种都在使用私有的刷写协议及工具。幸运的是，形如[QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)这样的工程目标就是尽量支持这些工具，本文会探讨各种bootloader的差异，以及可用的刷写方案。 | |||
| 针对基于AVR的键盘，QMK会自动检查所要刷写的 `.hex` 文件大小是否与在 `rules.mk` 中设置的 `BOOTLOADER` 值所匹配，同时会输出字节大小信息（及最大限制）。 | |||
| 同时也可以使用CLI工具刷写键盘，执行： | |||
| ``` | |||
| $ qmk flash -kb <keyboard> -km <keymap> | |||
| ``` | |||
| 更多信息参见文档[`qmk flash`](zh-cn/cli_commands.md#qmk-flash)。 | |||
| ## Atmel DFU | |||
| Atmel系列的DFU bootloader默认配备在所有USB AVR系列上（16/32U4RC除外），广泛用于一些PCB上具备私有集成电路模块（IC）的键盘上（老款OLKB、Clueboards等）。有些使用的是LUFA实现的DFU bootloader，或是QMK的分支版本（新款OLKB），后者对硬件功能进行了扩充加强。 | |||
| 为保证对DFU bootloader的兼容性，请确保在 `rules.mk` 中存在如下部分内容（可选的值还有 `lufa-dfu` 或 `qmk-dfu`）： | |||
| ```make | |||
| # 选择Bootloader | |||
| BOOTLOADER = atmel-dfu | |||
| ``` | |||
| 兼容的刷写工具： | |||
| * [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） | |||
| * [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / QMK中将构建目标设为 `:dfu`（推荐的命令行工具） | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式： | |||
| * 点击 `RESET` 键码 | |||
| * 如果PCB上有 `RESET` 键，点击之 | |||
| * 快速短接一下RST到GND | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 清空flash存储数据（如果使用QMK工具箱或CLI的 `make`会自动进行） | |||
| 4. 将.hex文件刷写进去 | |||
| 5. 重置设备进入应用模式（如上，会自动进行） | |||
| ### QMK DFU | |||
| QMK维护了[一个LUFA DFU bootloader的分支版本](https://github.com/qmk/lufa/tree/master/Bootloaders/DFU)，其可以进行一次矩阵扫描来退出bootloader进入应用模式，同时会让LED闪烁或蜂鸣器响一声。若要启用该功能，将以下定义添加到 `config.h`： | |||
| ```c | |||
| #define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW | |||
| #define QMK_ESC_INPUT D5 // ROW pin if COL2ROW | |||
| // 可选: | |||
| //#define QMK_LED E6 | |||
| //#define QMK_SPEAKER C6 | |||
| ``` | |||
| 目前来讲不推荐将 `QMK_ESC` 键设置成与[Bootmagic](zh-cn/feature_bootmagic.md)同一个键，否则按下该键时只会让MCU在bootloader模式上反复进出。 | |||
| 制造商及型号字符串自动从 `config.h` 中获取，并会在型号后追加 " Bootloader"。 | |||
| 要生成该bootloader，需指定 `bootloader` 构建目标，即 `make planck/rev4:default:bootloader`。要生成可部署到正式产品的.hex文件（同时包含QMK及bootloader），使用 `production` 构建目标，即 `make planck/rev4:default:production`。 | |||
| ### `make` 构建目标 | |||
| * `:dfu`: 每5秒检测一次直到发现可用的DFU设备，然后进行固件刷写。 | |||
| * `:dfu-split-left` 和 `:dfu-split-right`: 同 `:dfu` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Elite-C的分体式键盘这是理想的方法。 | |||
| ## Caterina | |||
| Arduino及其仿制板使用[Caterina bootloader](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina)或某种变体（使用Pro Micro或其仿制芯片、Pololu A-Star等构建的所有键盘），并基于虚拟串口使用AVR109协议进行通信。 | |||
| 为确保对Caterina bootloader的兼容性，请添加如下代码块至 `rules.mk`： | |||
| ```make | |||
| # 选择Bootloader | |||
| BOOTLOADER = caterina | |||
| ``` | |||
| 兼容的刷写工具： | |||
| * [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具） | |||
| * [avrdude](https://www.nongnu.org/avrdude/) QMK中须基于 `avr109` 编程器 / `:avrdude` 构建目标 （推荐的命令行工具） | |||
| * [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写；一些型号需要你在750ms内重置两次）： | |||
| * 点击 `RESET` 键码 | |||
| * 如果PCB上有 `RESET` 键，点击之 | |||
| * 快速短接一下RST到GND | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 将.hex文件刷写进去 | |||
| 4. 等待设备自动重置 | |||
| ### `make` 构建目标 | |||
| * `:avrdude`: 每5秒检测一次直到发现可用的Caterina设备（通过检测新COM端口），然后进行固件刷写。 | |||
| * `:avrdude-loop`: 同 `:avrdude` 一样刷写固件，但会在一个设备刷写完后再次尝试刷写。主要用于批量刷写设备。按 Ctrl+C 以终止循环检测。 | |||
| * `:avrdude-split-left` 和 `:avrdude-split-right`: 同 `:avrdude` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Pro Micro的分体式键盘这是理想的方法。 | |||
| ## HalfKay | |||
| HalfKay是一款由PJRC开发的超精简的bootloader，且呈现为HID设备（因此不需要额外的驱动），在所有的Teensys，即"the 2.0"，上已经预刷写过。该bootloader目前是闭源的，因此一旦覆写（即通过ISP刷入其它bootloader）掉，就无法复原了。 | |||
| 为确保对Halfkay bootloader的兼容性，请添加如下代码块至 `rules.mk`： | |||
| ```make | |||
| # 选择Bootloader | |||
| BOOTLOADER = halfkay | |||
| ``` | |||
| 兼容的刷写工具： | |||
| * [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） | |||
| * [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) / QMK中将构建目标设为 `:teensy`（推荐的命令行工具） | |||
| * [Teensy Loader](https://www.pjrc.com/teensy/loader.html) | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）： | |||
| * 点击 `RESET` 键码 | |||
| * 如果Teensy上或PCB上有 `RESET` 键，点击之 | |||
| * 快速短接一下RST到GND | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 将.hex文件刷写进去 | |||
| 4. 重置设备进入应用模式（可能会自动进行） | |||
| ## USBasploader | |||
| USBasploader是一款来源于[Objective Development](https://www.obdev.at/products/vusb/usbasploader.html)的bootloader。它通过模拟出一个USBasp ISP编程器来运行V-USB以用于一些形如ATmega328P这样的“非USB AVR芯片”。 | |||
| 为确保对USBasploader bootloader的兼容性，请添加如下代码块至 `rules.mk`： | |||
| ```make | |||
| # 选择Bootloader | |||
| BOOTLOADER = usbasploader | |||
| ``` | |||
| 兼容的刷写工具： | |||
| * [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） | |||
| * [avrdude](https://www.nongnu.org/avrdude/) QMK中须基于 `usbasp` 编程器 / `:usbasp` 构建目标（推荐的命令行工具） | |||
| * [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式： | |||
| * 点击 `RESET` 键码 | |||
| * 在按住 `BOOT` 按钮时，快速点击一下PCB上的 `RESET` | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 将.hex文件刷写进去 | |||
| 4. 点击PCB上的 `RESET` 按钮或将RST短接至GND一下。 | |||
| ## BootloadHID | |||
| BootloadHID是一款用于AVR微控制器的bootloader，其呈现为HID输入设备，和HalkKay很像，因此在Windows下也无需安装驱动。 | |||
| 为确保对bootloadHID bootloader的兼容性，请添加如下代码块至 `rules.mk`： | |||
| ```make | |||
| # 选择Bootloader | |||
| BOOTLOADER = bootloadhid | |||
| ``` | |||
| 兼容的刷写工具： | |||
| * [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） | |||
| * [bootloadHID CLI](https://www.obdev.at/products/vusb/bootloadhid.html) / QMK中将构建目标设为 `:bootloadhid`（推荐的命令行工具） | |||
| * [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式： | |||
| * 点击 `RESET` 键码 | |||
| * 在按住“盐键”（salt key）时插入键盘 - 在PS2AVRGB板上，通常在MCU的A0及B0引脚上有这个按键，否则请查看键盘的使用说明。 | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 将.hex文件刷写进去 | |||
| 4. 重置设备到应用模式（可能会自动进行） | |||
| ### QMK HID | |||
| QMK维护了[一个LUFA HID bootloader的分支版本](https://github.com/qmk/lufa/tree/master/Bootloaders/HID)，通过USB HID节点设备进行刷写，工作模式类似于PJRC的Teensy Loader刷写器以及HalfKay bootloader。其可以进行一次矩阵扫描来退出bootloader进入应用模式，同时会让LED闪烁或蜂鸣器响一声。 | |||
| 为确保对QMK HID bootloader的兼容性，请添加如下代码块至 `rules.mk`： | |||
| ```make | |||
| # 选择Bootloader | |||
| BOOTLOADER = qmk-hid | |||
| ``` | |||
| 要启用额外的功能支持，请添加如下定义至 `config.h`： | |||
| ```c | |||
| #define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW | |||
| #define QMK_ESC_INPUT D5 // ROW pin if COL2ROW | |||
| // 可选: | |||
| //#define QMK_LED E6 | |||
| //#define QMK_SPEAKER C6 | |||
| ``` | |||
| 目前来讲不推荐将 `QMK_ESC` 键设置成与[Bootmagic Lite](zh-cn/feature_bootmagic.md)同一个键，否则按下该键时只会让MCU在bootloader模式上反复进出。 | |||
| 制造商及型号字符串自动从 `config.h` 中获取，并会在型号后追加 " Bootloader"。 | |||
| 要生成该bootloader，需指定 `bootloader` 构建目标，即 `make planck/rev4:default:bootloader`。要生成可部署到正式产品的.hex文件（同时包含QMK及bootloader），使用 `production` 构建目标，即 `make planck/rev4:default:production`。 | |||
| 兼容的刷写工具： | |||
| * TBD | |||
| * 目前只能选择使用该 [Python脚本](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp_python), 或从LUFA仓库中构建[`hid_bootloader_cli`](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp)。Homebrew也许（即将）能直接支持（通过 `brew install qmk/qmk/hid_bootloader_cli`）。 | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式： | |||
| * 点击 `RESET` 键码 | |||
| * 如果PCB上有 `RESET` 键，点击之 | |||
| * 快速短接一下RST到GND | |||
| 2. 等待操作系统识别到设备 | |||
| 4. 将.hex文件刷写进去 | |||
| 5. 重置设备进入应用模式（可能会自动进行） | |||
| ### `make` 构建目标 | |||
| * `:qmk-hid`: 每5秒检测一次直到发现可用的DFU设备，然后进行固件刷写。 | |||
| ## STM32/APM32 DFU | |||
| 所有的STM32及APM32 MCU系列，除F103型号外（参见[STM32duino小节](#stm32duino)）都在出场时预装了bootloader且无法修改或删除。 | |||
| 为确保对STM32-DFU bootloader的兼容性，请添加如下代码块至 `rules.mk`（可选替代项为 `apm32-dfu`）： | |||
| ```make | |||
| # 选择Bootloader | |||
| BOOTLOADER = stm32-dfu | |||
| ``` | |||
| 兼容的刷写工具： | |||
| * [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具） | |||
| * [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具） | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）： | |||
| * 点击 `RESET` 键码（对STM32F042设备可能无效） | |||
| * 如果有重置电路，点击PCB上的 `RESET` 键；有些主控板上可能会有一个开关需要先打开 | |||
| * 否则，你需要将 `BOOT0` 接线到VCC（通过 `BOOT0` 按钮或跳线），短接 `RESET` 至GND（通过 `RESET` 按钮或条线），然后断开 `BOOT0` 的接线。 | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 将.bin文件刷写进去 | |||
| 4. 重置设备进入应用模式（可能会自动进行） | |||
| ### `make` 构建目标 | |||
| * `:dfu-util`: 每5秒检测一次直到发现可用的STM32 bootloader设备，然后进行固件刷写。 | |||
| * `:dfu-util-split-left` 和 `:dfu-util-split-right`: 同 `:avrdude` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Proton-C的分体式键盘这是理想的方法。 | |||
| * `:st-link-cli`: 通过ST-Link CLI工具集而非dfu-util进行刷写，需要有ST-Link电子狗。 | |||
| * `:st-flash`: 通过[STLink工具](https://github.com/stlink-org/stlink)内的 `st-flash` 工具而非dfu-util进行刷写，需要有ST-Link电子狗。 | |||
| ## STM32duino :id=stm32duino | |||
| 该bootloader几乎是STM32F103板专用，该型号出厂不带USB DFU bootloader。其源代码及预编译好的二进制文件[在这里](https://github.com/rogerclarkmelbourne/STM32duino-bootloader)。 | |||
| 为确保对STM32duino bootloader的兼容性，请添加如下代码块至 `rules.mk`： | |||
| ```make | |||
| # 选择Bootloader | |||
| BOOTLOADER = stm32duino | |||
| ``` | |||
| 兼容的刷写工具： | |||
| * [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具） | |||
| * [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具） | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）： | |||
| * 点击 `RESET` 键码（对STM32F042设备可能无效） | |||
| * 如果有重置电路，点击PCB上的 `RESET` 键；有些主控板上可能会有一个开关需要先打开 | |||
| * 否则，你需要将 `BOOT0` 接线到VCC（通过 `BOOT0` 按钮或跳线），短接 `RESET` 至GND（通过 `RESET` 按钮或条线），然后断开 `BOOT0` 的接线。 | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 将.bin文件刷写进去 | |||
| 4. 重置设备进入应用模式（可能会自动进行） | |||
| ## Kiibohd DFU | |||
| Input Club出品的键盘使用NXP Kinetis微控制器而非STM32，并使用了独有的[自制bootloader](https://github.com/kiibohd/controller/tree/master/Bootloader)，然而处理器 及协议上两者大部分是一致的。 | |||
| 在 `rules.mk` 中该bootloader的设置项为 `kiibohd`，但既然该bootloader仅用在Input Club主控板上，就不必要设置到键映射或是用户级<!--译：不清楚这里的“user level”是个啥……-->了。 | |||
| 兼容的刷写工具： | |||
| * [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） | |||
| * [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具） | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式： | |||
| * 点击 `RESET` 键码（有可能只能进入到“安全”bootloader模式，参见[这里](https://github.com/qmk/qmk_firmware/issues/6112)） | |||
| * 如果PCB上有 `RESET` 键，点击之 | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 将.bin文件刷写进去 | |||
| 4. 重置设备进入应用模式（可能会自动进行） | |||
| ## tinyuf2 | |||
| 键盘可以考虑支持tinyuf2 bootloader，目前唯一支持的设备是F401/F411 blackpill。 | |||
| 在 `rules.mk` 中该bootloader的设置项为 `tinyuf2`，也可指定到键映射及用户级中。 | |||
| 为确保对tinyuf2 bootloader的兼容性，请添加如下代码块至 `rules.mk`： | |||
| ```make | |||
| # 选择Bootloader | |||
| BOOTLOADER = tinyuf2 | |||
| ``` | |||
| 兼容的刷写工具： | |||
| * 任何具备文件拷贝能力的程序，如 _macOS Finder_ 或 _Windows Explorer_ *。 | |||
| 刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式： | |||
| * 点击 `RESET` 键码 | |||
| * 双击PCB上的 `nRST` 键 | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 将.uf2文件拷贝到新出现的USB存储设备上 | |||
| 4. 等待设备恢复可用状态 | |||
+ 75
- 0
docs/zh-cn/flashing_bootloadhid.md
View File
| @ -0,0 +1,75 @@ | |||
| # BootloadHID刷写指引及资料 | |||
| <!--- | |||
| original document: 0.15.12:docs/flashing_bootloadhid.md | |||
| git diff 0.15.12 HEAD -- docs/flashing_bootloadhid.md | cat | |||
| --> | |||
| ps2avr(GB)基于一片ATmega32A微控制器及特殊的bootloader，无法使用常规的QMK方法进行刷写。 | |||
| 常规刷写过程： | |||
| 1. 使用如下任一方式进入bootloader模式： | |||
| * 点击 `RESET` 键码（一些设备上不管用） | |||
| * 在按住“盐键”（salt key）时插入键盘（该键一般会在键盘使用说明上写明） | |||
| 2. 等待操作系统识别到设备 | |||
| 3. 将.hex文件刷写进去 | |||
| 4. 重置设备到应用模式（可能会自动进行） | |||
| ## 用于bootloadHID刷写的构建目标 | |||
| ?> 使用QMK安装脚本，具体[参见这里](zh-cn/newbs_getting_started.md)，所需的bootloadHID工具应自动被安装上。 | |||
| 若希望通过命令行进行刷写，通过如下命令指定 `:bootloadhid` 构建目标： | |||
| make <keyboard>:<keymap>:bootloadhid | |||
| ## 基于图形化界面的刷写方法 | |||
| ### Windows | |||
| 1. 下载[HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) | |||
| 2. 重置键盘 | |||
| 3. 确认VID为 `16c0` 且PID为 `05df` | |||
| 4. 点击 `查找设备（Find Device）` 并确认目标键盘可见 | |||
| 5. 点击 `打开.hex文件（Open .hex File）` 并定位到你创建的.hex文件 | |||
| 6. 点击 `刷写设备（Flash Device）` 并等待刷写完毕 | |||
| ## 在命令行中进行刷写 | |||
| 1. 重置键盘 | |||
| 2. 通过输入 `bootloadHID -r` 并追加 `.hex` 文件的路径进行主控板的刷写 | |||
| ### Windows系统上手动安装 | |||
| 针对MSYS2: | |||
| 1. 下载BootloadHID固件包：https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz | |||
| 2. 使用合适的工具解压，如7-Zip | |||
| 3. 将解压出的 `commandline/bootloadHID.exe` 拷贝至MSYS目录下，一般是 `C:\msys64\usr\bin` | |||
| 针对Windows本地环境刷写，`bootloadHID.exe` 可以直接在非MSYS2环境下执行。 | |||
| ### Linux系统上手动安装 | |||
| 1. 安装libusb开发依赖项： | |||
| ```bash | |||
| # 该操作具体取决于系统 - Debian下可以这样 | |||
| sudo apt-get install libusb-dev | |||
| ``` | |||
| 2. 下载BootloadHID固件包： | |||
| ``` | |||
| wget https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz -O - | tar -xz -C /tmp | |||
| ``` | |||
| 3. 构建bootloadHID可执行程序： | |||
| ``` | |||
| cd /tmp/bootloadHID.2012-12-08/commandline/ | |||
| make | |||
| sudo cp bootloadHID /usr/local/bin | |||
| ``` | |||
| ### MacOS系统上手动安装 | |||
| 1. 执行以下命令安装Homebrew： | |||
| ``` | |||
| /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" | |||
| ``` | |||
| 2. 安装以下包： | |||
| ``` | |||
| brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb | |||
| ``` | |||
+ 59
- 0
docs/zh-cn/getting_started_docker.md
View File
| @ -0,0 +1,59 @@ | |||
| # Docker快速上手指引 | |||
| <!--- | |||
| original document: 0.15.12:docs/getting_started_docker.md | |||
| git diff 0.15.12 HEAD -- docs/getting_started_docker.md | cat | |||
| --> | |||
| 本工程包含了一套Docker工作流，可以方便地在不更改你主系统环境情况下完成新固件文件的构建工作。这同时也保证了在你拉取该工程代码后的编译环境与其他人以及QMK开发者的一致。当你需要其他人协助你排查遇到的问题时会方便很多。 | |||
| ## 需求 | |||
| 核心需求是一个已安装的可用的 `docker` 或 `podman`。 | |||
| * [Docker CE](https://docs.docker.com/install/#supported-platforms) | |||
| * [Podman](https://podman.io/getting-started/installation) | |||
| ## 用法 | |||
| 拉取QMK仓库到本地（包括所有的子模块）： | |||
| ```bash | |||
| git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git | |||
| cd qmk_firmware | |||
| ``` | |||
| 执行以下命令构建键映射： | |||
| ```bash | |||
| util/docker_build.sh <keyboard>:<keymap> | |||
| # 例: util/docker_build.sh planck/rev6:default | |||
| ``` | |||
| 如上可以构建所需的键盘/键映射，可用于刷写的 `.hex` 及 `.bin` 输出文件存放在QMK目录下。如果省略了 `:keymap` 参数，所有的键映射都会被编译。留意编译参数格式与 `make` 构建时的一致。 | |||
| 同时也支持直接从Docker中编译和刷写，只需要指定 `target`： | |||
| ```bash | |||
| util/docker_build.sh keyboard:keymap:target | |||
| # 例: util/docker_build.sh planck/rev6:default:flash | |||
| ``` | |||
| 可以不带参数地执行该脚本，其会依次要求你输入这些参数，也许你会觉得这样更好用： | |||
| ```bash | |||
| util/docker_build.sh | |||
| # 从输入中读取参数 (留空则构建所有的键盘/键映射) | |||
| ``` | |||
| 可以通过设置环境变量 `RUNTIME` 为想使用的容器运行时的名称或路径来指定运行时，默认其会检测并自动选取docker或podman，相比于podman会更倾向于用docker。 | |||
| ```bash | |||
| RUNTIME="podman" util/docker_build.sh keyboard:keymap:target | |||
| ``` | |||
| ## FAQ | |||
| ### 为什么我无法在我的Windows/macOS下刷写固件 | |||
| 在Windows及macOS上，需要有[Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/)运行着，配置过程很繁琐，因此我们没有做推荐。请考虑使用[QMK工具箱](https://github.com/qmk/qmk_toolbox)。 | |||
| !> Windows下需要启用[Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v)才能运行Docker，这也意味着它无法运行在没有Hyper-V的Windows版本下，如Windows 7，Windows 8及**Windows 10家庭版**。 | |||
+ 0
- 15
docs/zh-cn/getting_started_getting_help.md
View File
| @ -1,15 +0,0 @@ | |||
| # 获得帮助 | |||
| 有很多方法来获得关于QMK的帮助. | |||
| ## 实时聊天 | |||
| 你可以在我们的主要[Discord服务器](https://discord.gg/Uq7gcHh)找到QMK的开发者和用户。有很多讨论固件的不同频道, 工具箱(Toolbox), 硬件,配置工具(configurator). | |||
| ## OLKB Subreddit | |||
| QMK的官方论坛是[/r/olkb](https://reddit.com/r/olkb) 在[reddit.com](https://reddit.com)上. | |||
| ## GitHub的Issue | |||
| 你可以在GitHub上 [提出issue](https://github.com/qmk/qmk_firmware/issues).当您的问题需要长期讨论或调试时，这尤其方便。 | |||
+ 6
- 1
docs/zh-cn/getting_started_github.md
View File
+ 7
- 2
docs/zh-cn/getting_started_introduction.md
View File
+ 61
- 0
docs/zh-cn/getting_started_vagrant.md
View File
| @ -0,0 +1,61 @@ | |||
| # Vagrant快速上手指引 | |||
| <!--- | |||
| original document: 0.15.12:docs/getting_started_vagrant.md | |||
| git diff 0.15.12 HEAD -- docs/getting_started_vagrant.md | cat | |||
| --> | |||
| 本工程包含一份 `Vagrantfile`，可以方便地在不更改你系统环境情况下完成新固件文件的构建工作。这同时也保证了在你拉取该工程代码后的编译环境与也使用Vagrantfile的其它人的一致。当你需要其他人协助你排查遇到的问题时会方便很多。 | |||
| ## 需求 | |||
| 本工程中的 `Vagrantfile` 需要安装[Vagrant](https://www.vagrantup.com/)以及可用的虚拟机服务： | |||
| * [VirtualBox](https://www.virtualbox.org/) (5.0.12及以后版本) | |||
| * 卖点是'最适用于Vagrant的平台' | |||
| * [VMware Workstation](https://www.vmware.com/products/workstation) 及 [Vagrant VMware插件](https://www.vagrantup.com/vmware) | |||
| * （付费购买的）VMware插件需要在经过正版授权的VMware Workstation/Fusion上运行 | |||
| * [Docker](https://www.docker.com/) | |||
| 安装了Vagrant之后，在安装合适的虚拟机服务后可能需要重启机器。拉取本工程后在工程目录下执行 'vagrant up' 将启动一个包含了所有本工程所需工具的构建环境（虚拟机或是容器）。最后会有一个vagrant启动提示告知你一切正常就绪，否则你也可以参考一下下面的构建文档。 | |||
| ## 刷写固件 | |||
| 比较“简单”的方案是在你的宿主系统上借助以下工具刷写固件： | |||
| * [QMK工具箱](https://github.com/qmk/qmk_toolbox) (推荐) | |||
| * [Teensy Loader](https://www.pjrc.com/teensy/loader.html) | |||
| 如果你希望通过命令行进行编程工作，可以在Vagrantfile中取消掉['modifyvm']的注释以允许USB直通到Linux环境，既可以使用dfu-util/dfu-programmer之类的命令行工具进行编程工作，或是安装Teensy的命令行版本。 | |||
| ## Vagrantfile概览 | |||
| 开发环境被配置为运行QMK Docker镜像 `qmkfm/qmk_cli`，不仅让各系统下的功能预期一致，也是我们CI环境的镜像。 | |||
| ## FAQ | |||
| ### 为什么我的VirtualBox环境会有问题？ | |||
| VirtualBox 5的某些版本与工程中Vagrantfile中指定的VirtualBox扩展存在兼容问题。如果你遇到了/vagrant挂载不成功的问题，请升级VirtualBox至5.0.12或更高版本。**或者，可以尝试执行如下命令：** | |||
| ```console | |||
| vagrant plugin install vagrant-vbguest | |||
| ``` | |||
| ### 如何移除一个现有环境？ | |||
| 不再需要这个环境了是吗？在本工程目录下的任何位置，执行： | |||
| ```console | |||
| vagrant destroy | |||
| ``` | |||
| ### 如果我是想直接用Docker呢？ | |||
| 想在不使用虚拟机技术的情况下也能使用Vagrant工作流？Vagrangfile已配置为允许绕过运行虚拟机，直接运行容器。通过如下方式执行命令可以强制使用Docker来启动环境： | |||
| ```console | |||
| vagrant up --provider=docker | |||
| ``` | |||
| ### 如何访问虚拟机环境而非Docker容器？ | |||
| 通过如下方法跳过 `vagrant` 的用户初始化过程以在QMK构建镜像中直接执行： | |||
| ```console | |||
| vagrant ssh -c 'sudo -i' | |||
| ``` | |||
+ 209
- 0
docs/zh-cn/keymap.md
View File
| @ -0,0 +1,209 @@ | |||
| # 键映射总览 | |||
| <!--- | |||
| original document: 0.15.12:docs/keymap.md | |||
| git diff 0.15.12 HEAD -- docs/keymap.md | cat | |||
| --> | |||
| QMK键映射定义在C源文件中，其数据结构上是一个容纳了数组的数组。外层数组容纳了各个层，内层各数组则为层内的键列表。基本所有键盘都通过定义 `LAYOUT()` 宏来创建该两级数组。 | |||
| ## 键映射与配列 :id=keymap-and-layers | |||
| 在QMK中, **`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`** 容纳了多个 **层**， 每个**层**下包含了由**16位**的**动作码**所组成的键映射信息。 最多可以定义**32个层**。 | |||
| 对于常规键的定义，其**动作码**的高8位皆为0，低8位保存了USB HID中使用的各个键对应的**键码**。 | |||
| 不同的层可以同时生效，层的编号从0至31，编号越高的层优先级越高。 | |||
| （译注：由于是ascii图，掺杂中文会导致排版错乱，各翻译标注在图下方。下同） | |||
| Keymap: 32 Layers Layer: action code matrix | |||
| ----------------- --------------------- | |||
| stack of layers array_of_action_code[row][column] | |||
| ____________ precedence _______________________ | |||
| / / | high / ESC / F1 / F2 / F3 .... | |||
| 31 /___________// | /-----/-----/-----/----- | |||
| 30 /___________// | / TAB / Q / W / E .... | |||
| 29 /___________/ | /-----/-----/-----/----- | |||
| : _:_:_:_:_:__ | : /LCtrl/ A / S / D .... | |||
| : / : : : : : / | : / : : : : | |||
| 2 /___________// | 2 `-------------------------- | |||
| 1 /___________// | 1 `-------------------------- | |||
| 0 /___________/ V low 0 `-------------------------- | |||
| 翻译： | |||
| |原文 |译文 | | |||
| |--------------------------|-------------| | |||
| |Keymap: 32 Layers | 键映射：32个层| | |||
| |stack of layers | 层堆栈 | | |||
| |precedence | 优先级 | | |||
| |high/low | 高/低 | | |||
| |layer: action code matrix | 层：动作码矩阵| | |||
| |row/column | 行/列 | | |||
| 有时，键映射中存储的动作码在一些文档中也被称作键码，主要是由TMK沿袭而来的习惯。 | |||
| ### 键映射的层状态 :id=keymap-layer-status | |||
| 键映射的层状态由两个32位参数决定： | |||
| * **`default_layer_state`** 指向一个总是可用的键映射层（0-31）（即默认层）。 | |||
| * **`layer_state`** 每一位标记对应层的启用/停用状态。 | |||
| 通常键映射中的'0'层为 `default_layer（默认层）`，其它层在启动时会被固件置为停用状态，不过这些可以通过 `config.h` 进行配置。当你换了一个按键布局时可用于更改 `default_layer`，比如从Qwerty布局切换到了Colemak布局。 | |||
| Initial state of Keymap Change base layout | |||
| ----------------------- ------------------ | |||
| 31 31 | |||
| 30 30 | |||
| 29 29 | |||
| : : | |||
| : : ____________ | |||
| 2 ____________ 2 / / | |||
| 1 / / ,->1 /___________/ | |||
| ,->0 /___________/ | 0 | |||
| | | | |||
| `--- default_layer = 0 `--- default_layer = 1 | |||
| layer_state = 0x00000001 layer_state = 0x00000002 | |||
| 翻译： | |||
| |原文 |译文 | | |||
| |-----------------------|-------------| | |||
| |Initial state of Keymap| 键映射原始状态| | |||
| |Change base layout | 更改了基础层 | | |||
| 另外，可以通过修改 `layer_state` 做到其他层对基础层的覆盖，以实现诸如导航键、功能键（F1-F12）、多媒体键等特殊动作。 | |||
| Overlay feature layer | |||
| --------------------- bit|status | |||
| ____________ ---+------ | |||
| 31 / / 31 | 0 | |||
| 30 /___________// -----> 30 | 1 | |||
| 29 /___________/ -----> 29 | 1 | |||
| : : | : | |||
| : ____________ : | : | |||
| 2 / / 2 | 0 | |||
| ,->1 /___________/ -----> 1 | 1 | |||
| | 0 0 | 0 | |||
| | + | |||
| `--- default_layer = 1 | | |||
| layer_state = 0x60000002 <-' | |||
| ### 层优先级及穿透 | |||
| 须记住**层堆栈中更高的层有着更高的优先级**。固件会从最高的活跃层开始向下找键码，一旦固件在活跃层上找到了一个非 `KC_TRNS`（穿透）键码，就会停止查找，再往下的层级不会被查看。 | |||
| ____________ | |||
| / / <--- 较高的层 | |||
| / KC_TRNS // | |||
| /___________// <--- 较低的层 (KC_A) | |||
| /___________/ | |||
| 这个场景中，较高层级中的非穿透键是可用的，如果定义为 `KC_TRNS`（及同等效果的），较低层级的键码 `KC_A` 将被采纳。 | |||
| **注意：** 在层中定义合法的穿透键的方法有： | |||
| * `KC_TRANSPARENT` | |||
| * `KC_TRNS`（别名） | |||
| * `_______`（别名） | |||
| 这些键码允许在搜索非穿透键码时可以穿透当前层下落到更低层去。 | |||
| ## `keymap.c` 文件解析 | |||
| 本例中我们将深入到[Clueboard 66%的一款旧版的默认键映射](https://github.com/qmk/qmk_firmware/blob/ca01d94005f67ec4fa9528353481faa622d949ae/keyboards/clueboard/keymaps/default/keymap.c)方案中去。将该文件在另一个浏览器窗口中打开，以便对照本文进行同步阅览。 | |||
| 在一个 `keymap.c` 文件中会有三个你可能会关心的部分： | |||
| * [预定义](#definitions) | |||
| * [层/键映射数据结构](#layers-and-keymaps) | |||
| * [自定义函数](#custom-functions)，若有的话 | |||
| ### 预定义 | |||
| 文件头部可以看到： | |||
| #include QMK_KEYBOARD_H | |||
| // Helpful defines | |||
| // 译：便捷性的宏定义 | |||
| #define GRAVE_MODS (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT)) | |||
| /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * | |||
| * You can use _______ in place for KC_TRNS (transparent) * | |||
| * Or you can use XXXXXXX for KC_NO (NOOP) * | |||
| * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ | |||
| // 译：可以用 _______ 替代 KC_TRNS（穿透），用 XXXXXXX 替代 KC_NO (空操作) | |||
| // Each layer gets a name for readability. | |||
| // The underscores don't mean anything - you can | |||
| // have a layer called STUFF or any other name. | |||
| // Layer names don't all need to be of the same | |||
| // length, and you can also skip them entirely | |||
| // and just use numbers. | |||
| // 译：每一层为了便于识别可以起一个名字，下划线没有实际意义 - 叫STUFF之类的也行的， | |||
| // 译：层名不需要都一样长，甚至不定义这些直接用层号也是可以的 | |||
| #define _BL 0 | |||
| #define _FL 1 | |||
| #define _CL 2 | |||
| 以上是一些便于编写键映射及自定义函数时可用的预定义，`GRAVE_MODS` 后续会用在自定义函数中，之后的 `_BL`, `_FL` 及 `_CL` 便于我们在代码中引用这些层。 | |||
| 注：在一些更早的键映射文件中，你可能会发现一些形如 `_______` 或 `XXXXXXX` 的定义，这些可以分别代替 `KC_TRNS` 及 `KC_NO`，这样可以更清楚地分辨出各层中定义了哪些键的键值。现在这些定义是不需要的，因为我们默认已经提供了这些定义。 | |||
| ### 层和键映射 | |||
| 这个文件中最主要的部分是 `keymaps[]` 定义，这里须列出你的层以及层中的内容。这一部分应该以如下定义起始： | |||
| const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { | |||
| 之后是一个LAYOUT()宏组成的列表，一个LAYOUT()下定义了一个层中的键列表，一般你需要至少一个“基础层”（如QWERTY、Dvorak或Colemak），之后是在其之上的多个“功能”层。受限于对层的处理顺序，较低的层无法覆盖在较高的层上。 | |||
| QMK在 `keymaps[][MATRIX_ROWS][MATRIX_COLS]` 中保存着16位的动作码（有些时候也被称作键码），对于与常规键一致的键码，其高字节为0，低字节为USB HID 键盘所使用的键码值。 | |||
| > QMK的前身TMK中使用 `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` 来存储8位的键码，一些键码被保留用于引用执行 `fn_actions[]` 数组中的特定功能。 | |||
| #### 基础层 | |||
| 以下示例是Clueboard的基础层定义： | |||
| /* Keymap _BL: Base Layer (Default Layer) | |||
| */ | |||
| [_BL] = LAYOUT( | |||
| F(0), KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_GRV, KC_BSPC, KC_PGUP, \ | |||
| KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_PGDN, \ | |||
| KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, \ | |||
| KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RO, KC_RSFT, KC_UP, \ | |||
| KC_LCTL, KC_LGUI, KC_LALT, KC_MHEN, KC_SPC,KC_SPC, KC_HENK, KC_RALT, KC_RCTL, MO(_FL), KC_LEFT, KC_DOWN, KC_RGHT), | |||
| 这里有一些值得留意的地方： | |||
| * 站在C语言源代码的角度看，这只是一个数组，但我们掺杂了大量括号使得每个键可以在视觉上与物理设备对齐。 | |||
| * 常规的键盘扫描码以KC_起始，而那些“特殊”键则不是。 | |||
| * 最左上的键可以触发自定义函数0（`F(0)`） | |||
| * "Fn"键定义为 `MO(_FL)`，当按住该键时会切换到 `_FL` 层。 | |||
| #### 功能覆盖层 | |||
| 对于功能层，从代码角度讲与基础层没有任何区别。但在概念上讲，应该将其作为覆盖层而非替代层来定义。对大部分人来讲这个区别不重要，但当你构建越来越复杂的层结构时，其重要性会越来越凸显。 | |||
| [_FL] = LAYOUT( | |||
| KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, _______, KC_DEL, BL_STEP, \ | |||
| _______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SLCK, KC_PAUS, _______, _______, _______, _______, \ | |||
| _______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, \ | |||
| _______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, KC_PGUP, \ | |||
| _______, _______, _______, _______, _______,_______, _______, _______, _______, MO(_FL), KC_HOME, KC_PGDN, KC_END), | |||
| 这里值得留意的有： | |||
| * 我们使用 `_______` 定义来替代 `KC_TRNS`， 以便凸显在该层中有变化的那些键。 | |||
| * 对于这一层来讲，如果点击的是一个 `_______` 键，实际生效的将是其下的活跃层中的键。 | |||
| # 核心细节 | |||
| 在阅读完本节后，你应该掌握了构建自己的键映射的基础能力，更多的资料请参见： | |||
| * [键码](zh-cn/keycodes.md) | |||
| * [键映射FAQ](zh-cn/faq_keymap.md) | |||
| 我们仍在优化这份文档，如果你有更好的优化建议，请[提交一份issue](https://github.com/qmk/qmk_firmware/issues/new)！ | |||
+ 143
- 0
docs/zh-cn/mod_tap.md
View File
| @ -0,0 +1,143 @@ | |||
| # Mod-Tap | |||
| <!--- | |||
| original document: 0.15.12:docs/mod_tap.md | |||
| git diff 0.15.12 HEAD -- docs/mod_tap.md | cat | |||
| --> | |||
| Mod-Tap键 `MT(mod, kc)` 在按住时功能为修饰键，在点击时则是常规键码。举例来讲，可以设计出一个按键，当点击时发送Escape，按下时则作为Control或Shift | |||
| 修饰键码及`OSM()`将会被缀以`MOD_`前缀，而非`KC_` | |||
| |修饰键码 |描述 | | |||
| |----------|------------------------------------------| | |||
| |`MOD_LCTL`|左Control | | |||
| |`MOD_LSFT`|左Shift | | |||
| |`MOD_LALT`|左Alt | | |||
| |`MOD_LGUI`|左GUI (Windows/Command/Meta键) | | |||
| |`MOD_RCTL`|右Control | | |||
| |`MOD_RSFT`|右Shift | | |||
| |`MOD_RALT`|右Alt (AltGr) | | |||
| |`MOD_RGUI`|右GUI (Windows/Command/Meta键) | | |||
| |`MOD_HYPR`|Hyper (左Control, Shift, Alt 及 GUI同时按下)| | |||
| |`MOD_MEH` |Meh (左Control, Shift, 及 Alt同时按下) | | |||
| 可以通过逻辑或进行组合： | |||
| ```c | |||
| MT(MOD_LCTL | MOD_LSFT, KC_ESC) | |||
| ``` | |||
| 此时按住该键将触发左Control及左Shift，点击将发送Escape。 | |||
| 为了方便配列，QMK已包含一些常见的Mod-Tap： | |||
| |键 |别名 |描述 | | |||
| |------------|-----------------------------------------------------------------|---------------------------------------------| | |||
| |`LCTL_T(kc)`|`CTL_T(kc)` |按住时为左Control，点击时为 `kc` | | |||
| |`LSFT_T(kc)`|`SFT_T(kc)` |按住时为左Shift，点击时为 `kc` | | |||
| |`LALT_T(kc)`|`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)` |按住时为左Alt，点击时为 `kc` | | |||
| |`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|按住时为左GUI，点击时为 `kc` | | |||
| |`RCTL_T(kc)`| |按住时为右 Control，点击时为 `kc` | | |||
| |`RSFT_T(kc)`| |按住时为右 Shift，点击时为 `kc` | | |||
| |`RALT_T(kc)`|`ROPT_T(kc)`, `ALGR_T(kc)` |按住时为右 Alt，点击时为 `kc` | | |||
| |`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |按住时为右 GUI，点击时为 `kc` | | |||
| |`LSG_T(kc)` |`SGUI_T(kc)`, `SCMD_T(kc)`, `SWIN_T(kc)` |按住时为左Shift及GUI，点击时为 `kc` | | |||
| |`LAG_T(kc)` | |按住时为左Alt及GUI，点击时为 `kc` | | |||
| |`RSG_T(kc)` | |按住时为右 Shift及GUI，点击时为 `kc` | | |||
| |`RAG_T(kc)` | |按住时为右 Alt及GUI，点击时为 `kc` | | |||
| |`LCA_T(kc)` | |按住时为左Control及Alt，点击时为 `kc` | | |||
| |`LSA_T(kc)` | |按住时为左Shift及Alt，点击时为 `kc` | | |||
| |`RSA_T(kc)` |`SAGR_T(kc)` |按住时为右 Shift及右 Alt (AltGr)，点击时为 `kc` | | |||
| |`RCS_T(kc)` | |按住时为右 Control及右 Shift，点击时为 `kc` | | |||
| |`LCAG_T(kc)`| |按住时为左Control，Alt及GUI，点击时为 `kc` | | |||
| |`RCAG_T(kc)`| |按住时为右 Control，Alt及GUI，点击时为 `kc` | | |||
| |`C_S_T(kc)` | |按住时为左Control及Shift，点击时为 `kc` | | |||
| |`MEH_T(kc)` | |按住时为左Control，Shift及Alt，点击时为 `kc` | | |||
| |`HYPR_T(kc)`|`ALL_T(kc)` |按住时为左Control，Shift，Alt及GUI，点击时为 `kc` - 更多[参见这里](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| | |||
| ## 注意 | |||
| 目前 `MT()` 的 `kc`参数限制在[基础键码集](zh-cn/keycodes_basic.md)中，因此不能使用 `LCTL()`，`KC_TILD` 及其它大于 `0xFF` 的键码。原因是，QMK使用16位的键码，其中3位是功能标记，1位标记左右修饰键，4位存储修饰键码，仅剩8位存储键码。当一次Mod-Tap触发时，只要有一个右修饰键被激发，其它的修饰键也都被视为右修饰键，因此无法混搭形如左Control+右Shift的形式，会被视为右Control+右Shift | |||
| 若展开讲就比较复杂了。迁移到32位的键码可以很大程度解决这个问题，但同时会招致配列矩阵大小翻倍，也可能会有其它未知问题。若是想用修饰键配合按键，可以考虑使用[Tap Dance/多击键](zh-cn/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) | |||
| 在使用Windows远程桌面时你可能会发现有些问题，这是因为远程桌面对键码响应过快。若要修复，可以打开远程桌面的“配置”，在“本地资源”页中的键盘属性，调整为“本地计算器”，此时功能即可恢复正常。另一个办法是加大[`TAP_CODE_DELAY`](zh-cn/config_options.md#behaviors-that-can-be-configured)。 | |||
| ## 截获Mod-Taps | |||
| ### 改变点击功能 | |||
| 若要在Mod-Tap中突破基础键码的限制，可以在 `process_record_user` 中实现。如，上档键码 `KC_DQUO` 无法与 `MT()` 共用，因为它实际上是 `LSFT(KC_QUOT)` 的别名，`KC_DQUO` 上的修饰键码会被 `MT()` 覆盖。但可以使用如下代码截获点击，手动发送 `KC_DQUO`： | |||
| ```c | |||
| bool process_record_user(uint16_t keycode, keyrecord_t *record) { | |||
| switch (keycode) { | |||
| case LCTL_T(KC_DQUO): | |||
| if (record->tap.count && record->event.pressed) { | |||
| tap_code16(KC_DQUO); // 点击时发送 KC_DQUO | |||
| return false; // 通过返回false阻止对该键的其它处理 | |||
| } | |||
| break; | |||
| } | |||
| return true; | |||
| } | |||
| ``` | |||
| ### 改变按住功能 | |||
| 类似地，同样可以使用这段自定义代码改变按住功能。下面的例子会在 `LT(0, kc)` （layer-tap键无实际意义，因为layer 0默认被激活）按住时对X，C和V键附加剪切，复制和粘贴功能： | |||
| ```c | |||
| bool process_record_user(uint16_t keycode, keyrecord_t *record) { | |||
| switch (keycode) { | |||
| case LT(0,KC_X): | |||
| if (record->tap.count && record->event.pressed) { | |||
| return true; // 返回true来发送常规键码 | |||
| } else if (record->event.pressed) { | |||
| tap_code16(C(KC_X)); // 截获按住功能来发送Ctrl-X | |||
| } | |||
| return false; | |||
| case LT(0,KC_C): | |||
| if (record->tap.count && record->event.pressed) { | |||
| return true; // 返回true来发送常规键码 | |||
| } else if (record->event.pressed) { | |||
| tap_code16(C(KC_C)); // 截获按住功能来发送Ctrl-C | |||
| } | |||
| return false; | |||
| case LT(0,KC_V): | |||
| if (record->tap.count && record->event.pressed) { | |||
| return true; // 返回true来发送常规键码 | |||
| } else if (record->event.pressed) { | |||
| tap_code16(C(KC_V)); // 截获按住功能来发送Ctrl-V | |||
| } | |||
| return false; | |||
| } | |||
| return true; | |||
| } | |||
| ``` | |||
| 在数字及字母键上使用Mod-Tap时推荐启用 `IGNORE_MOD_TAP_INTERRUPT`，以避免在快速按下下一个键时保持功能优先级。参见[忽略Mod Tap中断](zh-cn/tap_hold.md#ignore-mod-tap-interrupt)。 | |||
| ### 同时改变点击和按住功能 | |||
| 最后一个例子通过 `LT(0,KC_NO)` 实现了点击复制，按住粘贴的功能： | |||
| ```c | |||
| bool process_record_user(uint16_t keycode, keyrecord_t *record) { | |||
| switch (keycode) { | |||
| case LT(0,KC_NO): | |||
| if (record->tap.count && record->event.pressed) { | |||
| tap_code16(C(KC_C)); // 截获点击来发送Ctrl-C | |||
| } else if (record->event.pressed) { | |||
| tap_code16(C(KC_V)); // 截获按住功能来发送Ctrl-V | |||
| } | |||
| return false; | |||
| } | |||
| return true; | |||
| } | |||
| ``` | |||
| ## 其它信息 | |||
| 在[点按配置](zh-cn/tap_hold.md)中描述了影响Mod-Tap行为的标记。 | |||
+ 21
- 15
docs/zh-cn/newbs.md
View File
| @ -1,23 +1,29 @@ | |||
| # QMK菜鸟教程 | |||
| # QMK入门教程 | |||
| QMK是为你机械硬盘设计的的一个强大的开源固件。使用QMK可以很简单的让你的定制键盘变得强大。看完这篇文章，无论你是菜鸟还是大佬，都可以顺利的使用QMK来定制键盘。 | |||
| <!--- | |||
| original document: 0.15.12:docs/newbs.md | |||
| git diff 0.15.12 HEAD -- docs/newbs.md | cat | |||
| --> | |||
| 你是否为不知道你的键盘能不能运行QMK而苦恼? 如果你的机械键盘是你自己做的，那么这把键盘一般可以运行QMK。我们提供了[一大堆自制键盘](https://qmk.fm/keyboards/), 所以即便你的键盘不能运行QMK你也很容易能找到满足你需求的键盘。 | |||
| 就像计算机一样，每把键盘里也有一个处理器，它的职责是在你点击键盘时，检测到这个动作并反馈给计算机。QMK固件即是为了这个目的而设计的一种"软件"，负责检测点击，反馈给电脑。当你构建出一个自定义键映射时，就是在创建一个新的键盘"软件"。 | |||
| ## 概览 | |||
| QMK的愿景是提供强有力的功能，让不可能的事情变得可能，简单的事情依旧简单。即便是不会编程也可以创建强大的键映射方案。 | |||
| 这个教程有7个主要部分： | |||
| 想知道你的键盘是否能运行QMK？如果这个键盘是你自己组建的，那么很可能是可以的。我们[已经支持很多键盘](https://qmk.fm/keyboards/)，所以即便你的键盘不能运行QMK，你也很容易能买到满足要求的键盘。 | |||
| * [新手上路](newbs_getting_started.md) | |||
| * [用命令行构建你的第一个固件](newbs_building_firmware.md) | |||
| * [用在线界面构建你的第一个固件](newbs_building_firmware_configurator.md) | |||
| * [刷新固件](newbs_flashing.md) | |||
| * [测试和调试](newbs_testing_debugging.md) | |||
| * [Git最佳实践](newbs_best_practices.md) | |||
| * [其他学习资源](newbs_learn_more_resources.md) | |||
| ?> **这份指南适合于我吗？**<br> | |||
| 编程对你是个困难的话，可以看看我们的[在线GUI页面](zh-cn/newbs_building_firmware_configurator.md)。</div> | |||
| 这份教程旨在帮助没有固件构建经验的人，也是根据该目的做出选择和建议。这些程序有很多替代方法，大部分替代我们都支持。如果你对完成一个任务有疑问，可以[向我们寻求帮助](getting_started_getting_help.md). | |||
| ## 总览 | |||
| ## 其他资源 | |||
| 这份指南适用于想通过源代码编译出键盘固件的需求。对于程序员，全过程都会感觉很熟悉。教程主要分3部分： | |||
| * [Thomas Baart的 QMK基础博客](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 这是一个用户创建的博客，涵盖了为新手准备的使用QMK的基础知识。 | |||
| 1. [环境配置](zh-cn/newbs_getting_started.md) | |||
| 2. [构建第一个固件](zh-cn/newbs_building_firmware.md) | |||
| 3. [刷写固件](zh-cn/newbs_flashing.md) | |||
| 该指南的目的是帮助那些从未编译过软件的人，很多取舍及建议都是基于这个考量。完成一个目标可能有多种方案，我们尽量都去支持，如果你搞不明白你的目标如何实现，可以[向我们寻求帮助](zh-cn/support.md)。 | |||
| ## 更多资料 | |||
| 这份指南之外，也有一些其它能帮助你学习QMK的资料。我们归纳整理在[大纲](zh-cn/syllabus.md)页面和[学习资料](zh-cn/newbs_learn_more_resources.md)页面 | |||
+ 0
- 163
docs/zh-cn/newbs_best_practices.md
View File
| @ -1,163 +0,0 @@ | |||
| # 最佳实践 | |||
| ## 或者说, "我应如何学会不再担心并开始爱上Git。" | |||
| 本文档旨在指导新手以最佳方式获得为QMK做出贡献的丝滑体验。我们将介绍为QMK做出贡献的过程，详细介绍使这项任务更容易的一些方法，然后我们将制造一些问题，来教你如何解决它们。 | |||
| 本文假设了一些内容: | |||
| 1. 一有个GitHub账户, 并[创建qmk_firmware仓库分叉](getting_started_github.md)到你的帐户. | |||
| 2. 你已经[建立你的构建环境](newbs_getting_started.md?id=environment-setup). | |||
| ## 你分叉的主分支: 一直在上传，但不要提交 | |||
| 十分推荐您在QMK开发过程中无论开发是否完成都要保持你的 `master` 分支更新，但是 ***一定不要*** 提交。相反，你应该在一个开发分叉中做出你所有修改并在开发时提交pull request。 | |||
| 减少合并冲突的可能性 — 两个或多个用户同时编辑文件的同一部分的实例 — 保持 `master` 分支最新，并创建一个新的分支来开始新的开发。 | |||
| ### 更新你的主分支 | |||
| 保持你的 `master` 更新, 推荐你添加QMK Firmware仓库作为Git的远程仓库，想这么做的话, 你可以打开你的Git命令行接口然后输入: | |||
| ``` | |||
| git remote add upstream https://github.com/qmk/qmk_firmware.git | |||
| ``` | |||
| 运行 `git remote -v`, 来确定这个仓库已经添加，以下是回显: | |||
| ``` | |||
| $ git remote -v | |||
| origin https://github.com/<your_username>/qmk_firmware.git (fetch) | |||
| origin https://github.com/<your_username>/qmk_firmware.git (push) | |||
| upstream https://github.com/qmk/qmk_firmware.git (fetch) | |||
| upstream https://github.com/qmk/qmk_firmware.git (push) | |||
| ``` | |||
| 现在添加已完成，你可以用`git fetch upstream`来检查仓库的更新. 这会检索branches 和 tags — 统称为"refs" — 从QMK仓库, 也就是 `upstream`。我们可以比较我们的分叉和QMK的 `origin` 数据的不同。 | |||
| 要更新你的分叉的主分支，请运行以下命令，在每行之后按Enter键: | |||
| ``` | |||
| git checkout master | |||
| git fetch upstream | |||
| git pull upstream master | |||
| git push origin master | |||
| ``` | |||
| 这回切换到你的`master` 分支, 检索你QMK仓库的refs, 下载当前QMK `master` 分支到你的电脑, 并上传到你的分叉. | |||
| ### 做改动 | |||
| 你可以输入以下命令来创建一个新的分支来做改动: | |||
| ``` | |||
| git checkout -b dev_branch | |||
| git push --set-upstream origin dev_branch | |||
| ``` | |||
| 这回建立一个叫做 `dev_branch`的新分支, 检查一下, 然后想你的分叉保存分支. 使用 `--set-upstream` 参数来告诉git使用你的分叉并且当每次你对你的分支用`git push` 或 `git pull`时要使用`dev_branch`。 它仅需要在第一次push的时候使用；然后你就可以很安全的用 `git push` 或 `git pull`, 并不需要其他参数了。 | |||
| !> 使用 `git push`, 你可以用 `-u` 来代替 `--set-upstream` — `-u`是`--set-upstream`的简写。 | |||
| 您可以将您的分支命名为您想要的任何名称，但建议将其命名为与您要进行的更改相关的内容。 | |||
| 默认情况下 `git checkout -b` 在已经检出的分支上建立新的分支。您可以将新的分支建立在未检出的现有分支的基础上，方法是将现有分支的名称添加到命令： | |||
| ``` | |||
| git checkout -b dev_branch master | |||
| ``` | |||
| 现在您已经有了一个开发分支，那么就打开您的文本编辑器并进行您需要做的任何更改。建议对您的分支进行许多小的提交；这样，任何引起问题的更改都可以在需要时更容易地跟踪和撤消。要进行更改，编辑并保存任何需要更新的文件，请将它们添加到Git的 *staging area* ，然后将它们提交到您的分支： | |||
| ``` | |||
| git add path/to/updated_file | |||
| git commit -m "My commit message." | |||
| ``` | |||
| ` git add`添加已更改到Git的*临时区域*也就是Git的“加载区域”的文件。其中包含使用 `git commit` 命令 *提交* 的并已经保存到仓库的更改。建议您使用描述性的提交消息，这样您就可以一目了然地知道更改了什么。 | |||
| !> 如果你修改了很多文件，但所有的文件都是同一个更改的一部分，你可以用 `git add .` 来添加当前目录中所有已更改的文件而不是单独添加每个文件. | |||
| ### 发布更改 | |||
| 最后一步是将更改推送到您的分叉。 输入 `git push`来推送. 现在Git将`dev_branch`的当前状态发布到您的分叉。 | |||
| ## 解决合并冲突 | |||
| 有时，当您在某个分支中的工作需要很长时间才能完成时，其他人所做的更改与您在打开pull request时对该分支所做的更改相冲突。这称为*rebase* 即合并冲突，当多个人编辑同一文件的同一部分时会发生这种情况。 | |||
| ### 重新调整您的更改 | |||
| *rebase*是Git的一种方法，它获取在某一点上应用的更改，撤销它们，然后将相同的更改应用到另一点。在合并冲突的情况下，您可以重新设置您的分支以获取在创建分支时和当前时间之间的那段时间所做的更改。 | |||
| 运行以下命令来开始： | |||
| ``` | |||
| git fetch upstream | |||
| git rev-list --left-right --count HEAD...upstream/master | |||
| ``` | |||
| 这里的`git rev-list` 命令返回当前分支和qmk的主分支之间不同的提交数。我们首先运行`git fetch`，以确保我们有代表upstream仓库的refs。 `git rev-list` 命令的回显有两个数字： | |||
| ``` | |||
| $ git rev-list --left-right --count HEAD...upstream/master | |||
| 7 35 | |||
| ``` | |||
| 第一个数字表示自创建以来当前分支的提交数, 第二个数字是自创建当前分支以来对 `upstream/master` 进行的提交数, 因此, 当前分支中未记录变动。 | |||
| 既然知道当前分支和upstream仓库的当前状态，我们可以开始一个rebase操作： | |||
| ``` | |||
| git rebase upstream/master | |||
| ``` | |||
| 这就是让Git撤销当前分支上的提交，然后根据QMK的主分支重新应用它们。 | |||
| ``` | |||
| $ git rebase upstream/master | |||
| First, rewinding head to replay your work on top of it... | |||
| Applying: Commit #1 | |||
| Using index info to reconstruct a base tree... | |||
| M conflicting_file_1.txt | |||
| Falling back to patching base and 3-way merge... | |||
| Auto-merging conflicting_file_1.txt | |||
| CONFLICT (content): Merge conflict in conflicting_file_1.txt | |||
| error: Failed to merge in the changes. | |||
| hint: Use 'git am --show-current-patch' to see the failed patch | |||
| Patch failed at 0001 Commit #1 | |||
| Resolve all conflicts manually, mark them as resolved with | |||
| "git add/rm <conflicted_files>", then run "git rebase --continue". | |||
| You can instead skip this commit: run "git rebase --skip". | |||
| To abort and get back to the state before "git rebase", run "git rebase --abort". | |||
| ``` | |||
| 这告诉我们有一个合并冲突，并给出带有冲突的文件的名称。在文本编辑器中打开冲突的文件，在该文件的某个位置，您会发现如下内容： | |||
| ``` | |||
| <<<<<<< HEAD | |||
| <p>For help with any issues, email us at support@webhost.us.</p> | |||
| ======= | |||
| <p>Need help? Email support@webhost.us.</p> | |||
| >>>>>>> Commit #1 | |||
| ``` | |||
| `<<<<<<< HEAD`行标记合并冲突的开始, `>>>>>>> Commit #1` 行标记结束, 冲突选项被 `=======`分隔。`HEAD`那端的部分来自文件的qmk master版本，标记有commit消息的部分来自当前的分支持和提交。 | |||
| 因为Git跟踪 *对文件的更改* 而不是直接跟踪文件的内容，所以如果Git在提交之前找不到文件中的文本，它将不知道如何编辑该文件。重新编辑文件将解决冲突。进行更改，然后保存文件。 | |||
| ``` | |||
| <p>Need help? Email support@webhost.us.</p> | |||
| ``` | |||
| 现在运行: | |||
| ``` | |||
| git add conflicting_file_1.txt | |||
| git rebase --continue | |||
| ``` | |||
| Git记录对冲突文件的更改，并继续应用来自我们的分支的提交，直到它到达末尾。 | |||
+ 37
- 50
docs/zh-cn/newbs_building_firmware.md
View File
| @ -1,81 +1,68 @@ | |||
| # 构建第一个固件 | |||
| 现在您已经建立了构建环境，就可以开始构建自定义固件了。对于本指南的这一部分，我们将在3个程序之间切换——文件管理器、文本编辑器和终端窗口。请保持所有3个程序打开，直到您完成并对键盘固件满意。 | |||
| <!--- | |||
| original document: 0.15.12:docs/newbs_building_firmware.md | |||
| git diff 0.15.12 HEAD -- docs/newbs_building_firmware.md | cat | |||
| --> | |||
| 如果您在按照指南第一部分的操作之后关闭并重新打开了终端窗口，请不要忘记输入“cd qmk_firmware”，来使您的终端位于正确的目录。 | |||
| 现在您已经准备好了构建环境，就可以开始构建自定义固件了。在这节指南中，我们将在3个程序中开展工作——文件管理器、文本编辑器和终端。在做出心满意足的固件前，请不要关闭它们。 | |||
| ## 新建键映射 | |||
| ## 导航到您的keymaps文件夹 | |||
| 也许你会考虑从默认键映射复制一份来开始，如果你遵循编译环境配置指南到了最后，那么使用QMK命令行可以简单地做到： | |||
| 首先导航到键盘的 `keymaps` 文件夹. | |||
| qmk new-keymap | |||
| ?> 如果您使用的是MacOS或Windows，可以使用以下命令轻松地打开keymaps文件夹。 | |||
| 如果你的环境没有那样配置，或者你有多个键盘要做，可以指定键盘名： | |||
| ?> macOS: | |||
| qmk new-keymap -kb <keyboard_name> | |||
| open keyboards/<keyboard_folder>/keymaps | |||
| 检查命令行输出，应该类似于： | |||
| ?> Windows: | |||
| Ψ <github_username> keymap directory created in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username> | |||
| start .\\keyboards\\<keyboard_folder>\\keymaps | |||
| 上面就是创建出的新 `keymap.c` 文件的路径。 | |||
| ## 创建`default` 布局副本 | |||
| ## 使用趁手的编辑器打开 `keymap.c` | |||
| 打开`keymaps`文件夹后，您将需要创建`default`文件夹的副本。我们强烈建议您将文件夹命名为与GitHub用户名相同的名称，但您也可以使用任何您想使用的名称，只要它只包含小写字母、数字和下划线字符。 | |||
| 要自动执行此过程，您还可以选择运行`new_keymap.sh`脚本。 | |||
| 导航到`qmk_firmware/util` 目录然后输入以下命令： | |||
| ``` | |||
| ./new_keymap.sh <keyboard path> <username> | |||
| ``` | |||
| 例如，一个名字叫ymzcdg的用户要创建1up60hse的布局，他需要输入 | |||
| ``` | |||
| ./new_keymap.sh 1upkeyboards/1up60hse ymzcdg | |||
| ``` | |||
| ## 在你最钟爱的文本编辑器中打开`keymap.c` | |||
| 打开你的`keymap.c`. 在这个文件中，您可以找到控制键盘行为的结构。 在你的`keymap.c` 的顶部有一些让布局更易读的define和enum。在靠下的位置你会找到一行和下面这句很像的: | |||
| 在编辑器中打开 `keymap.c`，可以看到控制键盘所有功能的关键结构。`keymap.c` 文件头部的一些define和enum定义能让代码容易阅读一些，继续往下会找到这么一行： | |||
| const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { | |||
| 从这一行开始便是层列表。这行下面你会看到包括 `LAYOUT` 或 `KEYMAP`这两个词的几行, 从这些行开始就是层。在这一行下面是组成该特定层的键的列表。 | |||
| 这行是所有层定义的起点，往下能看到有 `LAYOUT` 的行，都是一个层定义的起始，其下方为该层的组成定义。 | |||
| !> 编辑您的keymap文件时，注意不要添加或删除任何逗号。如果这样做，您将阻止您的固件编译，并且您可能不容易找出多余的或缺少的逗号在哪里。 | |||
| !> 编辑时请非常留意不要错误增加/删除了逗号分隔符，否则很可能无法编译固件，且很难排查是哪里的逗号不对。 | |||
| ## 根据您的喜好自定义布局 | |||
| ## 按照个人喜好设计层级 | |||
| 如何完成这一步骤完全取决于您。改变一直困扰着你的问题，或者完全重做所有的事情。如果您不需要全部图层，可以删除图层，或者将图层总数增加到32个。查看以下文档，了解可以在此处定义的内容: | |||
| 这一步的目标完全取决于你，既可以去修复一个你不爽的问题，也可以完全重写一个新的。你可以删除不需要的层，或是增加层到32个的上限，QMK功能丰富，可以在左边的导航栏中寻找“使用QMK”一节，浏览完整的功能信息，也可以看看这些比较简单的： | |||
| * [键码](keycodes.md) | |||
| * [特性](features.md) | |||
| * [问题与解答](faq.md) | |||
| * [基础键码](zh-cn/keycodes_basic.md) | |||
| * [量子键码](zh-cn/quantum_keycodes.md) | |||
| * [Grave/Escape](zh-cn/feature_grave_esc.md) | |||
| * [鼠标键](zh-cn/feature_mouse_keys.md) | |||
| ?> 当你明白布局是怎么工作时，您也要让每次改变尽可能小。一次改变很大在调试时找出问题会十分困难。 | |||
| ?> 你大概理解了键映射如何工作的话，留心尽量少去做改动，改动越多出了问题越难排查。 | |||
| ## 构建你的固件 | |||
| ## 构建固件 :id=build-your-firmware | |||
| 完成对布局的更改后，您就要构建固件了。为此，请返回终端窗口并运行build命令: | |||
| 对键映射做完修改后，该编译固件了。回到终端中使用编译命令： | |||
| make <my_keyboard>:<my_keymap> | |||
| qmk compile | |||
| 例如，如果您的keymap名为“xyverz”，并且您正在为rev5 planck构建一个keymap，那么您将使用此命令： | |||
| 如果没有完整地配置环境，或你有多个目标键盘，可以指定键盘及键映射： | |||
| make planck/rev5:xyverz | |||
| qmk compile -kb <keyboard> -km <keymap> | |||
| 在编译过程中，你将看到屏幕上有很多输出，通知您正在编译哪些文件他应该以与下文类似的输出结束: | |||
| 编译完成后，会输出详尽的编译产出文件信息，其末尾应该看起来像这样： | |||
| ``` | |||
| Linking: .build/planck_rev5_xyverz.elf [OK] | |||
| Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] | |||
| Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] | |||
| Checking file size of planck_rev5_xyverz.hex [OK] | |||
| * File size is fine - 18392/28672 | |||
| Linking: .build/planck_rev5_default.elf [OK] | |||
| Creating load file for flashing: .build/planck_rev5_default.hex [OK] | |||
| Copying planck_rev5_default.hex to qmk_firmware folder [OK] | |||
| Checking file size of planck_rev5_default.hex [OK] | |||
| * The firmware size is fine - 27312/28672 (95%, 1360 bytes free) | |||
| ``` | |||
| ## 刷新你的固件 | |||
| ## 刷写固件 | |||
| 请移步 [Flashing Firmware](newbs_flashing.md) 来继续。 | |||
| 参阅[刷写固件](zh-cn/newbs_flashing.md)以了解如何将固件写入键盘主控。 | |||
+ 18
- 0
docs/zh-cn/newbs_building_firmware_configurator.md
View File
| @ -0,0 +1,18 @@ | |||
| # QMK配置器 | |||
| <!--- | |||
| original document: 0.15.12:docs/newbs_building_firmware_configurator.md | |||
| git diff 0.15.12 HEAD -- docs/newbs_building_firmware_configurator.md | cat | |||
| --> | |||
| [](https://config.qmk.fm/) | |||
| [QMK配置器](https://config.qmk.fm)是一个可用于生成`.hex`和`.bin`格式的QMK固件文件的在线交互页面。 | |||
| 这里有[视频教程](https://www.youtube.com/watch?v=-imgglzDMdY). 很多人给我们反馈该视频包含了足够多的知识可以用来开始编写自己的键盘程序。 | |||
| QMK配置器在Chrome及Firefox中工作良好。 | |||
| !> **来自于第三方工具的文件数据无法保证与QMK兼容，如Keyboard Layout Editor(KLE)或kbfirmware，请不要加载或导入这些文件。QMK配置器是一个独立的工具。** | |||
| 更多信息请参见[QMK配置器: 入门](zh-cn/configurator_step_by_step.md)。 | |||
+ 67
- 250
docs/zh-cn/newbs_flashing.md
View File
| @ -1,307 +1,124 @@ | |||
| # 刷新你的键盘 | |||
| # 刷写键盘固件 | |||
| 现在您已经构建了一个自定义固件文件，那么您就需要刷新键盘了。 | |||
| <!--- | |||
| original document: 0.15.12:docs/newbs_flashing.md | |||
| git diff 0.15.12 HEAD -- docs/newbs_flashing.md | cat | |||
| --> | |||
| ## 用QMK工具箱刷新键盘 | |||
| 在自定义的固件文件构建出来后，可以刷写到键盘中了。 | |||
| 刷新键盘的最简单方法是使用[QMK 工具箱](https://github.com/qmk/qmk_toolbox/releases). | |||
| ## 将键盘调至DFU（Bootloader）模式 | |||
| 但是，QMK工具箱目前仅适用于Windows和MacOS。如果您使用的是Linux（或者只是希望从命令行刷新固件），则必须使用 [方法概述](newbs_flashing.md#flash-your-keyboard-from-the-command-line). | |||
| 在你将自定义固件刷写到键盘前，键盘必须处于特有的刷写模式下。此时，键盘会处于不会响应点击等常规操作的状态，并且一定留意不要打断刷写工作，刷写固件过程中不可以把键盘拔下来。 | |||
| ### 将文件加载到QMK工具箱中 | |||
| 不同的键盘进入刷写模式的方法都是不同的，如果你的键盘运行的是QMK、TMK或PS2AVRGB(Bootmapper客户端)且没有写明特别的操作说明的话，可以依次尝试以下操作： | |||
| 首先打开QMK工具箱应用程序。您将要在访达或资源管理器中找到固件文件。您的键盘固件可能是两种格式之一`.hex`或`.bin`。qmk会尝试将键盘的相应文件复制到“qmk_firmware”根目录中。 | |||
| * 按住两边的Shift键，点击Pause | |||
| * 按住两边的Shift键，点击B | |||
| * 拔出键盘，同时按住“空格”键及B键，再插上键盘，等两秒后松开 | |||
| * 拔出键盘，按住键盘左上或左下的按键（一般来讲是Escape或左Control），在插上键盘 | |||
| * 按重置按键（Reset），一般在PCB背面 | |||
| * 在PCB上寻找导出的 `RESET` 和 `GND` 引脚，在插电的情况下短接一下 | |||
| ?> 如果您在Windows或MacOS上，可以使用以下命令轻松地在资源管理器或访达中打开当前固件文件夹。 | |||
| 如果上面的方法没有用，且键盘主板上的芯片是 `STM32` 系列，情况要复杂一些。通常在[Discord](https://discord.gg/Uq7gcHh)上寻求帮助是最好的办法，并且很可能需要你提供一些键盘主板的照片 —— 所以如果你能提前准备好，我们沟通起来会快得多。 | |||
| ?> Windows: | |||
| 如果没有遇到什么问题，你会在QMK工具箱的输出信息里找到类似下面的黄色文字的信息： | |||
| start . | |||
| ?> macOS: | |||
| open . | |||
| 固件文件始终遵循此命名格式: | |||
| ``` | |||
| *** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000) | |||
| ``` | |||
| <keyboard_name>_<keymap_name>.{bin,hex} | |||
| 已进入bootloader状态的设备也可以在设备管理器、系统信息或 `lsusb` 中看到。 | |||
| 例如，使用 `default` 布局的 `plank/rev5` 将使用以下名字： | |||
| ## 使用QMK工具箱刷写固件 | |||
| planck_rev5_default.hex | |||
| 使用[QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)刷写固件是最简单的方案。 | |||
| 找到固件文件后，将其拖到QMK工具箱中的“Local file”框中，或单击“Open”并导航到固件文件的存储位置。 | |||
| 然而该工具箱仅支持Windows及macOS，如果你在使用Linux环境（或是希望用命令行刷写固件），请参阅[在命令行中刷写固件](#使用命令行刷写固件)一节。 | |||
| ### 将键盘置于DFU（Bootloader）模式 | |||
| ### 加载固件到QMK工具箱 | |||
| 要刷新自定义固件，您必须将键盘置于特殊的刷新模式。在此模式下，您将无法键入或使用键盘。在写入固件时，不要拔下键盘插头或以其他方式中断刷新过程，这一点非常重要。 | |||
| 打开QMK工具箱，在Finder或文件管理器中找到固件文件。键盘固件文件名后缀通常是 `.hex` 或 `.bin`，QMK工具箱会尝试将正确的文件拷贝到qmk根目录 `qmk_firmware` 中。 | |||
| 不同的键盘有不同的方式进入这种特殊模式。如果您的键盘当前运行的是QMK或TMK，而您没有得到特定的指示，请按顺序尝试以下操作: | |||
| 在Windows或macOS上，使用下面的指令可以快速打开当前目录。 | |||
| * 按住两个shift键并按 `Pause` | |||
| * 按住两个shift键并按 `B` | |||
| * 拔下键盘插头, 同时按住空格键和 `B` , 插上键盘然后等一会再放开按键 | |||
| * 按下PCB底部的 `RESET` 物理键 | |||
| * 找到PCB上标记有 `BOOT0` 或 `RESET`的金属点, 在插入PCB的同时短接它们 | |||
| <!-- tabs:start --> | |||
| 成功后，您将在QMK工具箱中看到类似以下内容的消息: | |||
| #### ** Windows ** | |||
| ``` | |||
| *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 | |||
| *** DFU device connected | |||
| start . | |||
| ``` | |||
| ### 刷新你的键盘 | |||
| 单击QMK工具箱中的 `Flash` 按钮。您将看到类似以下内容的输出: | |||
| #### ** macOS ** | |||
| ``` | |||
| *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 | |||
| *** DFU device connected | |||
| *** Attempting to flash, please don't remove device | |||
| >>> dfu-programmer atmega32u4 erase --force | |||
| Erasing flash... Success | |||
| Checking memory from 0x0 to 0x6FFF... Empty. | |||
| >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex | |||
| Checking memory from 0x0 to 0x55FF... Empty. | |||
| 0% 100% Programming 0x5600 bytes... | |||
| [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success | |||
| 0% 100% Reading 0x7000 bytes... | |||
| [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success | |||
| Validating... Success | |||
| 0x5600 bytes written into 0x7000 bytes memory (76.79%). | |||
| >>> dfu-programmer atmega32u4 reset | |||
| *** DFU device disconnected | |||
| *** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390 | |||
| open . | |||
| ``` | |||
| ## 使用命令行刷新键盘 | |||
| 首先，您需要知道您的键盘使用的是哪个bootloader。通常是以下四个常见的bootloader。Pro-Micro 和 clones 使用 CATERINA, Teensy 使用 Halfkay, OLKB 键盘使用 QMK-DFU, 其他的atmega32u4芯片使用DFU。 | |||
| 您可以在以下文章中了解更多关于bootloader[刷新指令和Bootloader信息](flashing.md)。 | |||
| 如果您知道正在使用的bootloader是哪种，那么在编译固件时，可以向“make”命令里添加一些额外参数，以自动执行刷新过程。 | |||
| <!-- tabs:end --> | |||
| ### DFU | |||
| 固件文件的文件名格式为： | |||
| 对于DFU引导加载程序，当您准备好编译和刷新固件时，打开终端窗口并运行构建命令: | |||
| make <my_keyboard>:<my_keymap>:dfu | |||
| 例如，如果您的布局名为“xyverz”，并且您正在为rev5 planck构建一个布局，那么您可以使用此命令： | |||
| make planck/rev5:xyverz:dfu | |||
| ``` | |||
| <keyboard_name>_<keymap_name>.{bin,hex} | |||
| <键盘名>_<键映射名>.{bin,hex} | |||
| ``` | |||
| 编译完成后，应输出以下内容： | |||
| 例如， `planck/rev5` 的 `default` 键映射对应的文件名是： | |||
| ``` | |||
| Linking: .build/planck_rev5_xyverz.elf [OK] | |||
| Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] | |||
| Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] | |||
| Checking file size of planck_rev5_xyverz.hex | |||
| * File size is fine - 18574/28672 | |||
| ``` | |||
| planck_rev5_default.hex | |||
| ``` | |||
| 到了这个时候, 构建脚本将每隔5秒查找一次DFU。它将重复以下操作，直到找到设备或将其取消。 | |||
| 找到固件文件后，将其拖拽至QMK工具箱的"Local file"框，或点击“Open”并定位至固件文件。 | |||
| dfu-programmer: no device present. | |||
| Error: Bootloader not found. Trying again in 5s. | |||
| ### 刷写到键盘 | |||
| 一旦出现以上回显，您将需要重置控制器。然后，它应该显示与以下类似的输出： | |||
| 点击QMK工具箱的`Flash`，将看到如下输出信息： | |||
| ``` | |||
| *** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000) | |||
| *** Attempting to flash, please don't remove device | |||
| >>> dfu-programmer atmega32u4 erase --force | |||
| >>> dfu-programmer.exe atmega32u4 erase --force | |||
| Erasing flash... Success | |||
| Checking memory from 0x0 to 0x6FFF... Empty. | |||
| >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex | |||
| Checking memory from 0x0 to 0x55FF... Empty. | |||
| 0% 100% Programming 0x5600 bytes... | |||
| >>> dfu-programmer.exe atmega32u4 flash "D:\Git\qmk_firmware\gh60_satan_default.hex" | |||
| Checking memory from 0x0 to 0x3F7F... Empty. | |||
| 0% 100% Programming 0x3F80 bytes... | |||
| [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success | |||
| 0% 100% Reading 0x7000 bytes... | |||
| [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success | |||
| Validating... Success | |||
| 0x5600 bytes written into 0x7000 bytes memory (76.79%). | |||
| >>> dfu-programmer atmega32u4 reset | |||
| ``` | |||
| 如果您对此有任何问题，您可能需要这样做： | |||
| sudo make <my_keyboard>:<my_keymap>:dfu | |||
| #### DFU命令 | |||
| 有许多DFU命令可用于将固件下载到DFU设备： | |||
| * `:dfu` - 这是正常选项，等待DFU设备可用，然后刷新固件。这将每隔5秒检查一次，以查看是否出现了DFU设备。 | |||
| * `:dfu-ee` - 这将刷新一个`eep`文件，而不是普通的十六进制文件。这很不常见。 | |||
| * `:dfu-split-left` - 这将刷新正常固件，就像默认选项 (`:dfu`)一样. 但是，这也会刷新“左侧”EEPROM文件，用于分割键盘。 _这是基于Elite C的键盘的推荐选择。_ | |||
| * `:dfu-split-right` - 这将刷新正常固件，就像默认选项(`:dfu`). 但是，这也会刷新“右侧”EEPROM文件，用于分割键盘。 _这是基于Elite C的键盘的推荐选择。_ | |||
| ### Caterina | |||
| 对于Arduino板以及其克隆版来说(比如SparkFun和ProMicro), 准备好编译和刷新固件后，打开终端窗口并运行构建命令: | |||
| make <my_keyboard>:<my_keymap>:avrdude | |||
| 比如, 你的布局叫"xyverz"你要创建一个rev2 Lets Split的布局,你要用以下命令: | |||
| make lets_split/rev2:xyverz:avrdude | |||
| 固件完成编译后，它将输出类似以下的内容: | |||
| ``` | |||
| Linking: .build/lets_split_rev2_xyverz.elf [OK] | |||
| Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK] | |||
| Checking file size of lets_split_rev2_xyverz.hex [OK] | |||
| * File size is fine - 27938/28672 | |||
| Detecting USB port, reset your controller now.............. | |||
| ``` | |||
| 此时，复位，然后脚本将检测bootloader，然后刷新固件。输出应该像这样: | |||
| ``` | |||
| Detected controller on USB port at /dev/ttyS15 | |||
| Connecting to programmer: . | |||
| Found programmer: Id = "CATERIN"; type = S | |||
| Software Version = 1.0; No Hardware Version given. | |||
| Programmer supports auto addr increment. | |||
| Programmer supports buffered memory access with buffersize=128 bytes. | |||
| Programmer supports the following devices: | |||
| Device code: 0x44 | |||
| avrdude.exe: AVR device initialized and ready to accept instructions | |||
| Reading | ################################################## | 100% 0.00s | |||
| avrdude.exe: Device signature = 0x1e9587 (probably m32u4) | |||
| avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed | |||
| To disable this feature, specify the -D option. | |||
| avrdude.exe: erasing chip | |||
| avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex" | |||
| avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex | |||
| avrdude.exe: writing flash (27938 bytes): | |||
| Writing | ################################################## | 100% 2.40s | |||
| avrdude.exe: 27938 bytes of flash written | |||
| avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex: | |||
| avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex: | |||
| avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex | |||
| avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes | |||
| avrdude.exe: reading on-chip flash data: | |||
| Reading | ################################################## | 100% 0.43s | |||
| avrdude.exe: verifying ... | |||
| avrdude.exe: 27938 bytes of flash verified | |||
| avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF) | |||
| avrdude.exe done. Thank you. | |||
| 0x3F80 bytes written into 0x7000 bytes memory (56.70%). | |||
| >>> dfu-programmer.exe atmega32u4 reset | |||
| *** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000) | |||
| ``` | |||
| 如果您对此有任何问题，您可能需要这样做： | |||
| sudo make <my_keyboard>:<my_keymap>:avrdude | |||
| 此外，如果要刷新多个板，请使用以下命令： | |||
| ## 使用命令行刷写固件 | |||
| make <keyboard>:<keymap>:avrdude-loop | |||
| 现在已经没有以前那样繁琐了，在编译固件后需要刷写时，打开终端输入如下刷写指令： | |||
| 当你完成了刷新后，你需要按下ctrl+c或者其他正确的按键来让你的操作系统终止循环。 | |||
| qmk flash | |||
| 如果未通过命令行工具配置过键盘/键映射名，或有多个目标键盘，可以指定目标键盘和键映射： | |||
| ## HalfKay | |||
| qmk flash -kb <键盘名> -km <键映射名> | |||
| 对于PJRC设备（Teensy），当您准备好编译和刷新固件时，打开终端窗口并运行构建命令: | |||
| QMK将核查键盘配置，并尝试使用合适的bootloader进行刷写。也就是说，你不用关注应该使用什么bootloader，这些重活儿让qmk指令去承担就好。 | |||
| make <my_keyboard>:<my_keymap>:teensy | |||
| 但是，先决条件是键盘配置中已经设置了bootloader，如果未配置，或你的键盘板子不支持配置的刷写方式，你会看到这些错误信息： | |||
| 比如, 如果你的布局叫做"xyverz"你想创建Ergodox or Ergodox EZ的布局,你要使用以下命令: | |||
| WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time. | |||
| make erdogox_ez:xyverz:teensy | |||
| 固件完成编译后，它将输出如下内容： | |||
| ``` | |||
| Linking: .build/ergodox_ez_xyverz.elf [OK] | |||
| Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK] | |||
| Checking file size of ergodox_ez_xyverz.hex [OK] | |||
| * File size is fine - 25584/32256 | |||
| Teensy Loader, Command Line, Version 2.1 | |||
| Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage | |||
| Waiting for Teensy device... | |||
| (hint: press the reset button) | |||
| ``` | |||
| 此时，复位键盘。完成后，您将看到如下输出： | |||
| ``` | |||
| Found HalfKay Bootloader | |||
| Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage | |||
| Programming............................................................................................................................................................................ | |||
| ................................................... | |||
| Booting | |||
| ``` | |||
| 此时，只能退回到需要指定bootloader的方法，具体参见[刷写固件](zh-cn/flashing.md)指引。 | |||
| ## STM32 (ARM) | |||
| 对于大多数ARM板（包括Proton C、Planck Rev 6和Preonic Rev 3），当您准备好编译和刷新固件时，打开终端窗口并运行构建命令： | |||
| make <my_keyboard>:<my_keymap>:dfu-util | |||
| 例如，如果您的keymap被命名为“xyverz”，并且您正在为Planck Revision 6键盘构建一个布局，那么您需要使用以下命令，然后将键盘重新启动到bootloader（在完成编译之前）： | |||
| make planck/rev6:xyverz:dfu-util | |||
| 固件完成编译后，它将输出如下内容： | |||
| ``` | |||
| Linking: .build/planck_rev6_xyverz.elf [OK] | |||
| Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK] | |||
| Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK] | |||
| Size after: | |||
| text data bss dec hex filename | |||
| 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex | |||
| Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK] | |||
| dfu-util 0.9 | |||
| Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. | |||
| Copyright 2010-2016 Tormod Volden and Stefan Schmidt | |||
| This program is Free Software and has ABSOLUTELY NO WARRANTY | |||
| Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ | |||
| Invalid DFU suffix signature | |||
| A valid DFU suffix will be required in a future dfu-util release!!! | |||
| Opening DFU capable USB device... | |||
| ID 0483:df11 | |||
| Run-time device DFU version 011a | |||
| Claiming USB DFU Interface... | |||
| Setting Alternate Setting #0 ... | |||
| Determining device status: state = dfuERROR, status = 10 | |||
| dfuERROR, clearing status | |||
| Determining device status: state = dfuIDLE, status = 0 | |||
| dfuIDLE, continuing | |||
| DFU mode device DFU version 011a | |||
| Device returned transfer size 2048 | |||
| DfuSe interface name: "Internal Flash " | |||
| Downloading to address = 0x08000000, size = 41824 | |||
| Download [=========================] 100% 41824 bytes | |||
| Download done. | |||
| File downloaded successfully | |||
| Transitioning to dfuMANIFEST state | |||
| ``` | |||
| ## 上手试试键盘吧！ | |||
| ## 试一试吧! | |||
| 恭喜你，你的自定义固件成功刷写到键盘中了，快去试试吧！ | |||
| 恭喜您! 您的自定义固件已经刷写到您的键盘 | |||
| 运气不差的话一切都会是正常工作的，如果不幸遇到了些问题，有一些参考方案可以帮助你排查问题原因。 | |||
| 键盘测试就简单直接了，依次按一下各按键，检查它是不是发送了正确的输入。可以使用[QMK配置器](https://config.qmk.fm/#/test/)中的测试模式进行测试，即便你的键盘并不运行QMK。 | |||
| 试一试，确保一切按你想的方式进行。我们写了[测试和调试](newbs_testing_debugging.md)来完善新手引导。 因此，请前往那里了解如何排除自定义功能的故障。 | |||
| 还是不行吗？参阅一下FAQ或[通过Discord和我们聊聊](https://discord.gg/Uq7gcHh)吧。 | |||
+ 158
- 52
docs/zh-cn/newbs_getting_started.md
View File
+ 28
- 8
docs/zh-cn/newbs_learn_more_resources.md
View File
| @ -1,15 +1,35 @@ | |||
| # 学习资源 | |||
| 这些资源旨在让QMK社区的新成员更了解新成员文档中提供的信息。 | |||
| <!--- | |||
| original document: 0.15.12:docs/newbs_learn_more_resources.md | |||
| git diff 0.15.12 HEAD -- docs/newbs_learn_more_resources.md | cat | |||
| --> | |||
| Git 资源: | |||
| 这些资源旨在让QMK社区的新成员更了解新手教程中的基础知识。 | |||
| * [很好的通用教程](https://www.codecademy.com/learn/learn-git) | |||
| * [从例子中学习Git游戏](https://learngitbranching.js.org/) | |||
| * [了解有关GitHub的更多信息的Git资源](getting_started_github.md) | |||
| * [专门针对QMK的Git资源](contributing.md) | |||
| *译注：以下资料超出了QMK核心概念范畴，恕不另行翻译* | |||
| ### QMK参考资料 | |||
| 命令行资源: | |||
| * [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 一个站在新人视角，探讨如何使用QMK固件的个人博客。 | |||
| * [超棒的命令行通用教程](https://www.codecademy.com/learn/learn-the-command-line) | |||
| ### 命令行操作参考资料 :id=command-line-resources | |||
| * [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line) | |||
| * [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)<br> | |||
| * [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) | |||
| ### 文本编辑器相关参考资料 :id=text-editor-resources | |||
| 对文本编辑器有选择困难？ | |||
| * [a great introduction to the subject](https://learntocodewith.me/programming/basics/text-editors/) | |||
| 更适用于编程的文本编辑器： | |||
| * [Sublime Text](https://www.sublimetext.com/) | |||
| * [VS Code](https://code.visualstudio.com/) | |||
| ### Git参考资料 | |||
| * [Great General Tutorial](https://www.codecademy.com/learn/learn-git) | |||
| * [Flight Rules For Git](https://github.com/k88hudson/git-flight-rules) | |||
| * [Git Game To Learn From Examples](https://learngitbranching.js.org/) | |||
+ 7
- 39
docs/zh-cn/newbs_testing_debugging.md
View File
| @ -1,46 +1,14 @@ | |||
| # 测试和调试 | |||
| 使用自定义固件刷新键盘后，您就可以测试它了。如果您幸运，一切都会完美运行，但如果没有，这份文件将帮助您找出问题所在。 | |||
| <!--- | |||
| original document: 0.15.12:docs/newbs_testing_debugging.md | |||
| git diff 0.15.12 HEAD -- docs/newbs_testing_debugging.md | cat | |||
| --> | |||
| ## 测试 | |||
| 测试键盘通常非常简单。按下每一个键并确保它发送的是您期望的键。甚至有一些程序可以帮助您确保没有任何键失效。 | |||
| 注意：这些程序不是由QMK提供或认可的。 | |||
| * [QMK Configurator](https://config.qmk.fm/#/test/) (网页版) | |||
| * [Switch Hitter](https://web.archive.org/web/20190413233743/https://elitekeyboards.com/switchhitter.php) (仅Windows) | |||
| * [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (仅Mac) | |||
| * [Keyboard Tester](https://www.keyboardtester.com) (网页版) | |||
| * [Keyboard Checker](https://keyboardchecker.com) (网页版) | |||
| ## 使用QMK工具箱进行调试 | |||
| [QMK工具箱](https://github.com/qmk/qmk_toolbox) 将会在你的`rules.mk`中有`CONSOLE_ENABLE = yes`的时候显示你键盘发来的消息。 默认情况下，输出极为有限，不过您可以打开调试模式来增加输出信息量。使用你键盘布局中的`DEBUG`键码,使用 [命令](feature_command.md) 特性来使能调试模式, 或者向你的布局中添加以下代码。 | |||
| ```c | |||
| void keyboard_post_init_user(void) { | |||
| // Customise these values to desired behaviour | |||
| debug_enable=true; | |||
| debug_matrix=true; | |||
| //debug_keyboard=true; | |||
| //debug_mouse=true; | |||
| } | |||
| ``` | |||
| <!-- 需要修改之处:这里要添加调试回显。 --> | |||
| ## 发送您自己的调试消息 | |||
| 有时用[custom code](custom_quantum_functions.md)发送自定义调试信息很有用. 这么做很简单. 首先在你文件头部包含`print.h`: | |||
| [已移到这里](zh-cn/faq_misc.md#testing) | |||
| ```c | |||
| #include "print.h" | |||
| ``` | |||
| ## 调试 :id=debugging | |||
| 之后，您可以使用一些不同的打印功能: | |||
| [已移到这里](zh-cn/faq_debug.md#debugging) | |||
| * `print("string")`: 打印简单字符串. | |||
| * `uprintf("%s string", var)`: 打印格式化字符串 | |||
| * `dprint("string")`: 仅在调试模式使能时打印简单字符串 | |||
| * `dprintf("%s string", var)`: 仅在调试模式使能时打印格式化字符串 | |||
+ 200
- 0
docs/zh-cn/reference_configurator_support.md
View File
| @ -0,0 +1,200 @@ | |||
| # 在QMK配置器中支持您的键盘 | |||
| <!--- | |||
| original document: 0.15.12:docs/reference_configurator_support.md | |||
| git diff 0.15.12 HEAD -- docs/reference_configurator_support.md | cat | |||
| --> | |||
| 本章节详述了如何在[QMK配置器](https://config.qmk.fm/)中对键盘进行支持。 | |||
| ## 配置器如何理解键盘 | |||
| 若要了解配置器如何理解键盘，须先理解配列的宏定义。这里有一份练习，假设这里有一个17键的小键盘PCB方案，就叫做 `numpad`。 | |||
| ``` | |||
| |---------------| | |||
| |NLk| / | * | - | | |||
| |---+---+---+---| | |||
| |7 |8 |9 | + | | |||
| |---+---+---| | | |||
| |4 |5 |6 | | | |||
| |---+---+---+---| | |||
| |1 |2 |3 |Ent| | |||
| |-------+---| | | |||
| |0 | . | | | |||
| |---------------| | |||
| ``` | |||
| ?> 配列宏定义的更多资料，参见[理解QMK：矩阵扫描](zh-cn/understanding_qmk.md?id=matrix-scanning)及[理解QMK：矩阵到物理配列的映射](zh-cn/understanding_qmk.md?id=matrix-to-physical-layout-map)。 | |||
| 配置器的API会从 `qmk_firmware/keyboards/<keyboard>/<keyboard>.h` 中读取键盘定义的 `.h` 文件。在上面的小键盘示例中，对应文件应为 `qmk_firmware/keyboards/numpad/numpad.h`： | |||
| ```c | |||
| #pragma once | |||
| #define LAYOUT( \ | |||
| k00, k01, k02, k03, \ | |||
| k10, k11, k12, k13, \ | |||
| k20, k21, k22, \ | |||
| k30, k31, k32, k33, \ | |||
| k40, k42 \ | |||
| ) { \ | |||
| { k00, k01, k02, k03 }, \ | |||
| { k10, k11, k12, k13 }, \ | |||
| { k20, k21, k22, KC_NO }, \ | |||
| { k30, k31, k32, k33 }, \ | |||
| { k40, KC_NO, k42, KC_NO } \ | |||
| } | |||
| ``` | |||
| QMK使用 `KC_NO` 去标记开关矩阵中的空位。有时也会因方便或调试用途而使用 `XXX`，`___` 或 `____` 来替代。通产定义写在 `.h` 文件起始位置附近： | |||
| ```c | |||
| #pragma once | |||
| #define XXX KC_NO | |||
| #define LAYOUT( \ | |||
| k00, k01, k02, k03, \ | |||
| k10, k11, k12, k13, \ | |||
| k20, k21, k22, \ | |||
| k30, k31, k32, k33, \ | |||
| k40, k42 \ | |||
| ) { \ | |||
| { k00, k01, k02, k03 }, \ | |||
| { k10, k11, k12, k13 }, \ | |||
| { k20, k21, k22, XXX }, \ | |||
| { k30, k31, k32, k33 }, \ | |||
| { k40, XXX, k42, XXX } \ | |||
| } | |||
| ``` | |||
| !> 注意这里的使用模式与键映射中的宏完全不同，后者几乎都在用 `XXXXXXX`（7个大写X）替代 `KC_NO`，用 `_______`（7个下划线）替代 `KC_TRNS`。 | |||
| !> 为避免混淆，推荐使用 `KC_NO`。 | |||
| 配列宏定义描述该键盘有17个按键，分布在五行四列。我们将这些开关命名为 `k<行号><列号>`，从0计起。命名成什么不太重要，但须确保负责从键映射中接收键码的上半段，与描述矩阵中按键位置的下半段定义匹配一致。 | |||
| 为了能够重现键盘的物理组成样式，须构建并提供一份用于描述按键物理位置和尺寸与开关矩阵绑定关系的JSON文件，以告知配置器程序这些信息。 | |||
| ## 构建JSON文件 | |||
| 构建该JSON描述文件最简便的办法是使用[Keyboard Layout Editor](https://www.keyboard-layout-editor.com/) ("KLE"), 从中获取的原始数据（Raw Data）可以经QMK工具转换为配置器可用的JSON格式数据。由于KLE默认打开显示的是一个小键盘配列，请移除新手引导部分，从剩余部分开始使用。 | |||
| 在配列编辑完毕后，从KLE的原始数据（Raw Data tab）页中拷贝类似如下的内容： | |||
| ``` | |||
| ["Num Lock","/","*","-"], | |||
| ["7\nHome","8\n↑","9\nPgUp",{h:2},"+"], | |||
| ["4\n←","5","6\n→"], | |||
| ["1\nEnd","2\n↓","3\nPgDn",{h:2},"Enter"], | |||
| [{w:2},"0\nIns",".\nDel"] | |||
| ``` | |||
| 要将这份数据转换为我们可用的JSON格式，请跳转至[QMK KLE-JSON转换工具](https://qmk.fm/converter/)页面并粘贴到输入框，点击转换按钮。稍后输出框中即可看到所需的JSON数据。将输出数据拷贝到文本文档中，并命名为 `info.json`，保存到 `numpad.h` 所在目录。 | |||
| 可以通过 `keyboard_name` 元素来指定键盘名称。这里为了演示，会将每个按键独立分行，以更方便于阅读，这不影响配置器的功能。 | |||
| ```json | |||
| { | |||
| "keyboard_name": "Numpad", | |||
| "url": "", | |||
| "maintainer": "qmk", | |||
| "tags": { | |||
| "form_factor": "numpad" | |||
| }, | |||
| "layouts": { | |||
| "LAYOUT": { | |||
| "layout": [ | |||
| {"label":"Num Lock", "x":0, "y":0}, | |||
| {"label":"/", "x":1, "y":0}, | |||
| {"label":"*", "x":2, "y":0}, | |||
| {"label":"-", "x":3, "y":0}, | |||
| {"label":"7", "x":0, "y":1}, | |||
| {"label":"8", "x":1, "y":1}, | |||
| {"label":"9", "x":2, "y":1}, | |||
| {"label":"+", "x":3, "y":1, "h":2}, | |||
| {"label":"4", "x":0, "y":2}, | |||
| {"label":"5", "x":1, "y":2}, | |||
| {"label":"6", "x":2, "y":2}, | |||
| {"label":"1", "x":0, "y":3}, | |||
| {"label":"2", "x":1, "y":3}, | |||
| {"label":"3", "x":2, "y":3}, | |||
| {"label":"Enter", "x":3, "y":3, "h":2}, | |||
| {"label":"0", "x":0, "y":4, "w":2}, | |||
| {"label":".", "x":2, "y":4} | |||
| ] | |||
| } | |||
| } | |||
| } | |||
| ``` | |||
| `layouts` 对象描述了键盘的物理配列信息，其下的 `LAYOUT` 对象命名须与 `numpad.h` 中的一致，而 `LAYOUT` 下的 `layout` 对象，其下每个JSON对象描述了各物理按键，格式如下： | |||
| ``` | |||
| 按键名，不会在配置器中展现。 | |||
| | | |||
| | 按键的X坐标，从键盘左侧开始数。 | |||
| | | | |||
| | | | |||
| | | 按键的Y坐标，从键盘上侧（后视角）开始数。 | |||
| | | | | |||
| ↓ ↓ ↓ | |||
| {"label":"Num Lock", "x":0, "y":0}, | |||
| ``` | |||
| 部分对象包含 `"w"` 和 `"h"` 字段，用以描述按键的宽高值。 | |||
| ?> 关于 `info.json` 文件的详细信息，参见[`info.json` 文件格式](zh-cn/reference_info_json.md)。 | |||
| ## 配置器如何配置按键 | |||
| 配置器API基于配列宏定义及JSON描述文件创建出键盘的可视化展现，并将每个可视化元素依序绑定到指定的按键： | |||
| 配列宏定义中的键 | 所使用的JSON对象 | |||
| :---: | :---- | |||
| k00 | {"label":"Num Lock", "x":0, "y":0} | |||
| k01 | {"label":"/", "x":1, "y":0} | |||
| k02 | {"label":"*", "x":2, "y":0} | |||
| k03 | {"label":"-", "x":3, "y":0} | |||
| k10 | {"label":"7", "x":0, "y":1} | |||
| k11 | {"label":"8", "x":1, "y":1} | |||
| k12 | {"label":"9", "x":2, "y":1} | |||
| k13 | {"label":"+", "x":3, "y":1, "h":2} | |||
| k20 | {"label":"4", "x":0, "y":2} | |||
| k21 | {"label":"5", "x":1, "y":2} | |||
| k22 | {"label":"6", "x":2, "y":2} | |||
| k30 | {"label":"1", "x":0, "y":3} | |||
| k31 | {"label":"2", "x":1, "y":3} | |||
| k32 | {"label":"3", "x":2, "y":3} | |||
| k33 | {"label":"Enter", "x":3, "y":3, "h":2} | |||
| k40 | {"label":"0", "x":0, "y":4, "w":2} | |||
| k42 | {"label":".", "x":2, "y":4} | |||
| 当用户在配置器中选中左上角的按键，并赋予数字区锁定键（NumLock）时，配置器会将 `KC_NLCK` 作为第一个按键进行键映射文件的构建工作，其它按键逻辑类似。其中 `label` 键值未被用到，其用于用户在调试 `info.json` 文件时，可以参考辨认出各按键。 | |||
| ## 问题及副作用 | |||
| 目前配置器还不支持按键偏转及类似ISO回车键这种非矩形按键。另外，对于纵向上偏离其行的按键 — 特别是像[TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/)这种1800配列的键盘中的方向键 — 如果 `info.json` 文件的贡献者没有做出修正，KLE转JSON数据工具将会不知如何处理。 | |||
| ### 解决方案 | |||
| #### 非矩阵形状的按键 | |||
| 针对ISO回车键的情况，QMK会将其定制化显示成一个矩形键，宽1.25u高2u，按键矩阵的右边与字母区的右边对齐。 | |||
|  | |||
| *一款60% ISO配列的键盘, 在QMK配置器中的渲染样式。* | |||
| #### 纵向偏移的按键 | |||
| 对于纵向偏移的按键，将其视作未偏移的样子放入KLE，最后在转换后的JSON文件中，按需编辑其Y偏移值。 | |||
|  | |||
| *一款1800配列键盘在KLE中的渲染样式，方向键未进行纵向偏移移动。* | |||
|  | |||
| *这份Unix差异文件，展示了我们需要在JSON文件中进行的纵向偏移改动。* | |||
+ 56
- 25
docs/zh-cn/reference_glossary.md
View File
+ 22
- 0
docs/zh-cn/support.md
View File
| @ -0,0 +1,22 @@ | |||
| # 寻求帮助 | |||
| <!--- | |||
| original document: 0.15.12:docs/support.md | |||
| git diff 0.15.12 HEAD -- docs/support.md | cat | |||
| --> | |||
| 你可以从很多渠道获取QMK帮助。 | |||
| 在你前往社区进行沟通前，请先阅览我们的社区[行为守则](https://qmk.fm/coc/) | |||
| ## 实时沟通 | |||
| 在你需要帮助时，最便捷的办法是通过我们的[Discord服务器](https://discord.gg/Uq7gcHh)进行沟通，通常会有人在线，也有很多乐于助人的人。 | |||
| ## OLKB Subreddit | |||
| QMK的官方论坛是[reddit.com](https://reddit.com)上的[/r/olkb](https://reddit.com/r/olkb). | |||
| ## GitHub Issues | |||
| 你可以在[Github上发Issue](https://github.com/qmk/qmk_firmware/issues)，对于需要深入讨论或需要调试的问题，会方便得多。 | |||
+ 77
- 0
docs/zh-cn/syllabus.md
View File
| @ -0,0 +1,77 @@ | |||
| # QMK大纲 | |||
| <!--- | |||
| original document: 0.15.12:docs/syllabus.md | |||
| git diff 0.15.12 HEAD -- docs/syllabus.md | cat | |||
| --> | |||
| 这一页旨在帮你建立关于QMK的相关基础知识，并提供能引导你成为QMK大师所需的所有概念。 | |||
| # 基本概念 | |||
| 如果你还没有看其它部分，先阅读这一节吧。在阅读了[介绍](zh-cn/newbs.md)之后，你可以制作、编译、刷写一个简单的键映射了，以下文档可以助你充实各系列的知识。 | |||
| * **了解如何使用QMK** | |||
| * [介绍](zh-cn/newbs.md) | |||
| * [CLI](zh-cn/cli.md) | |||
| * [GIT](zh-cn/newbs_git_best_practices.md) | |||
| * **了解键映射** | |||
| * [层](zh-cn/feature_layers.md) | |||
| * [键码](zh-cn/keycodes.md) | |||
| * 含所有可用键码，一些会涉及进阶或高级的话题。 | |||
| * **配置IDE** - 可选的 | |||
| * [Eclipse](zh-cn/other_eclipse.md) | |||
| * [VS Code](zh-cn/other_vscode.md) | |||
| # 进阶话题 | |||
| 包含窥探QMK主要功能内部原理的话题。你可以不用阅读这些，然而，跳过这些话题的话，去看高级话题的时候会让你很迷惑。 | |||
| * **各功能的配置** | |||
| <!-- * Configuration Overview FIXME(skullydazed/anyone): write this document --> | |||
| * [音频](zh-cn/feature_audio.md) | |||
| * 灯光 | |||
| * [背光](zh-cn/feature_backlight.md) | |||
| * [LED矩阵](zh-cn/feature_led_matrix.md) | |||
| * [RGB灯光](zh-cn/feature_rgblight.md) | |||
| * [RGB矩阵](zh-cn/feature_rgb_matrix.md) | |||
| * [点按配置](zh-cn/tap_hold.md) | |||
| * [充分利用AVR的存储空间](zh-cn/squeezing_avr.md) | |||
| * **深入键映射** | |||
| * [键映射](zh-cn/keymap.md) | |||
| * [键码与自定义函数](zh-cn/custom_quantum_functions.md) | |||
| * 宏 | |||
| * [动态宏](zh-cn/feature_dynamic_macros.md) | |||
| * [宏](zh-cn/feature_macros.md) | |||
| * [Tap Dance](zh-cn/feature_tap_dance.md) | |||
| * [组合键](zh-cn/feature_combo.md) | |||
| * [用户空间](zh-cn/feature_userspace.md) | |||
| * [按键重定义](zh-cn/feature_key_overrides.md) | |||
| # 高级话题 | |||
| 这些话题需要较多基础知识，使用这些高级功能前，你应该对如何通过 `config.h` 和 `rules.mk` 来配置键盘选项非常熟悉。 | |||
| * **维护QMK键盘** | |||
| * [飞线指南](zh-cn/hand_wire.md) | |||
| * [键盘开发指引](zh-cn/hardware_keyboard_guidelines.md) | |||
| * [info.json参考资料](zh-cn/reference_info_json.md) | |||
| * [防抖API](zh-cn/feature_debounce_type.md) | |||
| * **高级功能** | |||
| * [Unicode](zh-cn/feature_unicode.md) | |||
| * [API](zh-cn/api_overview.md) | |||
| * [Bootmagic Lite](zh-cn/feature_bootmagic.md) | |||
| * **硬件相关** | |||
| * [键盘工作原理](zh-cn/how_keyboards_work.md) | |||
| * [键盘矩阵原理](zh-cn/how_a_matrix_works.md) | |||
| * [分体键盘](zh-cn/feature_split_keyboard.md) | |||
| * [速记](zh-cn/feature_stenography.md) | |||
| * [光标设备](zh-cn/feature_pointing_device.md) | |||
| * **开发核心知识** | |||
| * [C编码规范](zh-cn/coding_conventions_c.md) | |||
| * [兼容的微处理器](zh-cn/compatible_microcontrollers.md) | |||
| * [自定义矩阵](zh-cn/custom_matrix.md) | |||
| * [理解QMK](zh-cn/understanding_qmk.md) | |||
| * **CLI开发** | |||
| * [编码规范](zh-cn/coding_conventions_python.md) | |||
| * [CLI开发总览](zh-cn/cli_development.md) | |||
+ 60
- 0
docs/zh-cn/translating.md
View File
| @ -0,0 +1,60 @@ | |||
| # 翻译QMK文档 | |||
| <!--- | |||
| original document: 0.15.12:docs/translating.md | |||
| git diff 0.15.12 HEAD -- docs/translating.md | cat | |||
| --> | |||
| 根目录下（`docs/`）的所有文件应当是英语的 - 其它语言应使用 ISO 639-1 中定义的语言编码建立子目录，后跟随一个 `-` 以及必要的国家编码。[常见的语言编码可见这里](https://www.andiamo.co.uk/resources/iso-language-codes/)。如果此目录不存在，可以新建。每个翻译过的文件的文件名，都应保持与英语版本的一致，以确保超链接的退化兼容性。 | |||
| 文件夹下的 `_summary.md` 文件中，有链接向其它文件的地址，在翻译过的名称后，跟随的链接前应添加该语言的目录名： | |||
| ```markdown | |||
| * [QMK简介](zh-cn/getting_started_introduction.md) | |||
| ``` | |||
| 所有导向其它文档页面的链接也必须有语言目录名前缀，若还指向了页面指定位置（即特定的标题），必须使用标题的英文ID，如： | |||
| ```markdown | |||
| [建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment) | |||
| ## 建立你的环境 :id=set-up-your-environment | |||
| ``` | |||
| 在翻译后，以下文件也需要进行修改： | |||
| * [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md) | |||
| 中的每一行应包含该语言国家国旗的[GitHub emoji编码](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag)标志： | |||
| ```markdown | |||
| - [:cn: 中文](/zh-cn/) | |||
| ``` | |||
| * [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html) | |||
| `placeholder` 及 `noData` 对象应有一个指向对应语言的入口项： | |||
| ```js | |||
| '/zh-cn/': '没有结果!', | |||
| ``` | |||
| 用于 "QMK固件" 边栏标题链接的 `nameLink` 同样需要添加对应配置： | |||
| ```js | |||
| '/zh-cn/': '/#/zh-cn/', | |||
| ``` | |||
| 最后确保在 `fallbackLanguages` 列表中添加该语言项，这样未翻译的文档链接将回退到英文版，而不是出现404页面： | |||
| ```js | |||
| fallbackLanguages: [ | |||
| // ... | |||
| 'zh-cn', | |||
| // ... | |||
| ], | |||
| ``` | |||
| ## 预览你的翻译成果 | |||
| 请阅读[文档预览](zh-cn/contributing.md#previewing-the-documentation)来设置文档的本地预览 - 在页面右上角的 "Translations" 菜单中应当可以看到你翻译的语言的入口。 | |||
| 当你觉得一切就绪了，请发起pull request给我们吧！ | |||
+ 35
- 0
docs/zh-cn/zh_cn_doc_status.sh
View File
| @ -0,0 +1,35 @@ | |||
| #! /bin/sh | |||
| # | |||
| # Script to display Simplified Chinese translation status of documents | |||
| # Copied from the japanese one | |||
| # | |||
| if [ ! -d docs/zh-cn ]; then | |||
| echo "'docs/zh-cn' not found." | |||
| echo "do:" | |||
| echo " cd \$(QMK_TOP)" | |||
| echo " ./docs/zh-cn/zh-cn_doc_status.sh" | |||
| exit 1 | |||
| fi | |||
| en_docs=`cd docs;ls -1 [a-z]*.md` | |||
| zh_cn_docs=`cd docs/zh-cn;ls -1 [a-z]*.md` | |||
| en_count=`echo $en_docs | wc -w` | |||
| zh_cn_count=`echo $zh_cn_docs | wc -w` | |||
| echo "English documents $en_count files." | |||
| echo "Simplified Chinese documents $zh_cn_count files." | |||
| echo "Files that have not been translated yet:" | |||
| for docfile in $en_docs | |||
| do | |||
| if [ ! -f docs/zh-cn/$docfile ]; then | |||
| wc docs/$docfile | |||
| fi | |||
| done | sort | |||
| echo "Files that have not been updated yet:" | |||
| grep --no-filename "^[ ]*git diff" docs/zh-cn/*.md | while read cmd | |||
| do | |||
| cline=`echo $cmd | sh | wc -l` | |||
| if [ $cline -gt 0 ]; then | |||
| echo "$cline $cmd" | |||
| fi | |||
| done | sort | |||