From f6a7f4d4aca4a1808850e2dcd8cc223ae5202062 Mon Sep 17 00:00:00 2001 From: IskandarMa Date: Wed, 19 Jan 2022 02:24:02 +0800 Subject: 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 Co-authored-by: LitoMore Co-authored-by: Dasky <32983009+daskygit@users.noreply.github.com> --- docs/zh-cn/README.md | 45 +- docs/zh-cn/_summary.md | 322 +++++++------ docs/zh-cn/api_docs.md | 73 +++ docs/zh-cn/api_overview.md | 20 + docs/zh-cn/cli.md | 43 ++ docs/zh-cn/cli_commands.md | 503 +++++++++++++++++++++ docs/zh-cn/cli_configuration.md | 126 ++++++ docs/zh-cn/cli_tab_complete.md | 32 ++ docs/zh-cn/configurator_architecture.md | 66 +++ docs/zh-cn/configurator_default_keymaps.md | 198 ++++++++ docs/zh-cn/configurator_step_by_step.md | 63 +++ docs/zh-cn/configurator_troubleshooting.md | 31 ++ docs/zh-cn/contributing.md | 188 ++++---- docs/zh-cn/custom_quantum_functions.md | 367 ++++++++------- docs/zh-cn/driver_installation_zadig.md | 102 +++++ docs/zh-cn/easy_maker.md | 37 ++ docs/zh-cn/faq.md | 6 - docs/zh-cn/faq_build.md | 127 ++---- docs/zh-cn/faq_debug.md | 188 ++++---- docs/zh-cn/faq_general.md | 59 ++- docs/zh-cn/faq_keymap.md | 172 +++---- docs/zh-cn/faq_misc.md | 108 +++++ docs/zh-cn/feature_grave_esc.md | 39 ++ docs/zh-cn/feature_space_cadet.md | 70 +++ docs/zh-cn/flashing.md | 329 ++++++++++++++ docs/zh-cn/flashing_bootloadhid.md | 75 +++ docs/zh-cn/getting_started_docker.md | 59 +++ docs/zh-cn/getting_started_getting_help.md | 15 - docs/zh-cn/getting_started_github.md | 7 +- docs/zh-cn/getting_started_introduction.md | 9 +- docs/zh-cn/getting_started_vagrant.md | 61 +++ docs/zh-cn/keymap.md | 209 +++++++++ docs/zh-cn/mod_tap.md | 143 ++++++ docs/zh-cn/newbs.md | 36 +- docs/zh-cn/newbs_best_practices.md | 163 ------- docs/zh-cn/newbs_building_firmware.md | 87 ++-- docs/zh-cn/newbs_building_firmware_configurator.md | 18 + docs/zh-cn/newbs_flashing.md | 317 +++---------- docs/zh-cn/newbs_getting_started.md | 210 ++++++--- docs/zh-cn/newbs_learn_more_resources.md | 36 +- docs/zh-cn/newbs_testing_debugging.md | 46 +- docs/zh-cn/reference_configurator_support.md | 200 ++++++++ docs/zh-cn/reference_glossary.md | 81 +++- docs/zh-cn/support.md | 22 + docs/zh-cn/syllabus.md | 77 ++++ docs/zh-cn/translating.md | 60 +++ docs/zh-cn/zh_cn_doc_status.sh | 35 ++ 47 files changed, 3932 insertions(+), 1348 deletions(-) create mode 100644 docs/zh-cn/api_docs.md create mode 100644 docs/zh-cn/api_overview.md create mode 100644 docs/zh-cn/cli.md create mode 100644 docs/zh-cn/cli_commands.md create mode 100644 docs/zh-cn/cli_configuration.md create mode 100644 docs/zh-cn/cli_tab_complete.md create mode 100644 docs/zh-cn/configurator_architecture.md create mode 100644 docs/zh-cn/configurator_default_keymaps.md create mode 100644 docs/zh-cn/configurator_step_by_step.md create mode 100644 docs/zh-cn/configurator_troubleshooting.md create mode 100644 docs/zh-cn/driver_installation_zadig.md create mode 100644 docs/zh-cn/easy_maker.md delete mode 100644 docs/zh-cn/faq.md create mode 100644 docs/zh-cn/faq_misc.md create mode 100644 docs/zh-cn/feature_grave_esc.md create mode 100644 docs/zh-cn/feature_space_cadet.md create mode 100644 docs/zh-cn/flashing.md create mode 100644 docs/zh-cn/flashing_bootloadhid.md create mode 100644 docs/zh-cn/getting_started_docker.md delete mode 100644 docs/zh-cn/getting_started_getting_help.md create mode 100644 docs/zh-cn/getting_started_vagrant.md create mode 100644 docs/zh-cn/keymap.md create mode 100644 docs/zh-cn/mod_tap.md delete mode 100644 docs/zh-cn/newbs_best_practices.md create mode 100644 docs/zh-cn/newbs_building_firmware_configurator.md create mode 100644 docs/zh-cn/reference_configurator_support.md create mode 100644 docs/zh-cn/support.md create mode 100644 docs/zh-cn/syllabus.md create mode 100644 docs/zh-cn/translating.md create mode 100644 docs/zh-cn/zh_cn_doc_status.sh (limited to 'docs/zh-cn') diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md index b42818d582..93dfbf1eef 100644 --- a/docs/zh-cn/README.md +++ b/docs/zh-cn/README.md @@ -1,31 +1,42 @@ -# QMK机械键盘固件 +# Quantum Mechanical Keyboard固件 -[![当前版本](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) -[![异议](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh) -[![文档状态](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm) -[![GitHub贡献者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) -[![GitHub分支](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/) + ## 什么是 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). +
-此外, 你也可以直接下载 ([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)
+用户友好的图形界面工具，无需具备编程知识基础。 -## 如何编译 +?> **进阶方式** [基于源代码](zh-cn/newbs.md)
+功能更强大，但门槛较高。 -在你能编译之前, 你需要[部署环境](zh-cn/getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: +
- 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) diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md index cedcfbd525..8a710a9ec1 100644 --- a/docs/zh-cn/_summary.md +++ b/docs/zh-cn/_summary.md @@ -1,133 +1,193 @@ -* [完全菜鸟指南](zh-cn/newbs.md) + +* 新手教程 + * [介绍](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) - - + +* 配置器(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) + * [配置](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) + + diff --git a/docs/zh-cn/api_docs.md b/docs/zh-cn/api_docs.md new file mode 100644 index 0000000000..a2df9ec20a --- /dev/null +++ b/docs/zh-cn/api_docs.md @@ -0,0 +1,73 @@ +# QMK API + + + +本章节详述了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输出信息，所有错误信息都会在这里。 diff --git a/docs/zh-cn/api_overview.md b/docs/zh-cn/api_overview.md new file mode 100644 index 0000000000..a07cfb7427 --- /dev/null +++ b/docs/zh-cn/api_overview.md @@ -0,0 +1,20 @@ +# QMK API + + + +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)。 diff --git a/docs/zh-cn/cli.md b/docs/zh-cn/cli.md new file mode 100644 index 0000000000..22c2db92c8 --- /dev/null +++ b/docs/zh-cn/cli.md @@ -0,0 +1,43 @@ +# QMK CLI :id=qmk-cli + + + +## 总览 :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` diff --git a/docs/zh-cn/cli_commands.md b/docs/zh-cn/cli_commands.md new file mode 100644 index 0000000000..08d1cc7e79 --- /dev/null +++ b/docs/zh-cn/cli_commands.md @@ -0,0 +1,503 @@ +# QMK CLI 命令 + + + +# 用户命令 + +## `qmk compile` + +该命令用于在指定目录下编译固件，可用于构建导出的JSON数据，代码库中的键映射，或是当前目录下的键盘。 + +该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 + +**用于配置器导出的数据时**： + +``` +qmk compile [-c] +``` + +**用于键映射时**： + +``` +qmk compile [-c] [-e =] [-j ] -kb -km +``` + +**在键盘目录下时**： + +须在存在默认键映射的键盘目录下执行，或是在键盘的键映射子目录下，否则须指定参数 `--keymap ` +``` +qmk compile +``` + +**构建所有支持该键映射的键盘时**： + +``` +qmk compile -kb all -km +``` + +**示例**： +``` +$ 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 +``` + +**示例**： +``` +$ 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 -kb +``` +`num_jobs` 用于指定并行的job上限，将其设置为0可以实现无限制的并行编译。 +``` +qmk compile -j 0 -kb +``` + +## `qmk flash` :id=qmk-flash + +该命令与 `qmk compile` 类似，但额外地可以指定bootloader。bootloader参数是可选的，默认会指定为 `:flash`。可通过 `-bl ` 来指定bootloader。请查阅[刷写固件](zh-cn/flashing.md)指引以深入了解可用的bootloader信息。 + +该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 + +**用于配置器导出的数据时**： + +``` +qmk flash [-bl ] [-c] [-e =] [-j ] +``` + +**用于键映射时**： + +``` +qmk flash -kb -km [-bl ] [-c] [-e =] [-j ] +``` + +**列出所有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 :[:]] [-l] [-n] [-t] [-w ] +``` + +**示例**： + +连接到所有可用的键盘并输出终端信息： + +``` +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] +``` + +## `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] +``` + +**示例**： + +``` +$ 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 diff --git a/docs/zh-cn/cli_configuration.md b/docs/zh-cn/cli_configuration.md new file mode 100644 index 0000000000..d3bca4a338 --- /dev/null +++ b/docs/zh-cn/cli_configuration.md @@ -0,0 +1,126 @@ +# QMK CLI 配置 + + + +本文详述了 `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` 命令可以管理配置数据。当不带额外参数执行时，会输出所有已有配置。存在参数时这些参数将被视为配置项参数，其格式须满足如下形式且无空格分隔： + + [.][=] + +## 设置配置值 + +在配置项的键后加 = 号进行值的设置，配置项的键必须是 `
.` 的完整形式。 + +举例： + +``` +$ 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`） | diff --git a/docs/zh-cn/cli_tab_complete.md b/docs/zh-cn/cli_tab_complete.md new file mode 100644 index 0000000000..7a16e9766c --- /dev/null +++ b/docs/zh-cn/cli_tab_complete.md @@ -0,0 +1,32 @@ +# QMK Tab补全 + + + +在使用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 diff --git a/docs/zh-cn/configurator_architecture.md b/docs/zh-cn/configurator_architecture.md new file mode 100644 index 0000000000..386ebd6899 --- /dev/null +++ b/docs/zh-cn/configurator_architecture.md @@ -0,0 +1,66 @@ +# QMK配置器框架 + + + +本章节提供了QMK配置器前端技术框架信息，若你对QMK配置器前端工程本身感兴趣，可以从[QMK配置器](https://github.com/qmk/qmk_configurator)代码库开始。 + +# 总览 + +![QMK配置器技术框架图](./../configurator_diagram.svg) + +# 详述 + +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)会编译并产出一些静态文件并通过Github Pages托管，每当[QMK配置器 `master`](https://github.com/qmk/qmk_configurator)分支收到推送的提交时都会触发。可以通过[QMK配置器 actions页面](https://github.com/qmk/qmk_configurator/actions/workflows/build.yml)查看这些job的状态。 + +## 键盘元数据 + +地址： + +每当[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 + +地址： + +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会给出重定向后的已鉴权地址链接。 diff --git a/docs/zh-cn/configurator_default_keymaps.md b/docs/zh-cn/configurator_default_keymaps.md new file mode 100644 index 0000000000..135029b7e2 --- /dev/null +++ b/docs/zh-cn/configurator_default_keymaps.md @@ -0,0 +1,198 @@ +# 向QMK配置器中添加默认键映射 :id=adding-default-keymaps + + + +本章节描述了如何向QMK配置器中添加一款键盘的默认键映射 + + +## 技术信息 :id=technical-information + +QMK配置器使用JSON作为键映射的本地文件格式。我们尽力确保其行为与在 `qmk_firmware` 中 执行 `make :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//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` 定义块添加到键盘的头文件（``）中，例如（留意 `enum` 在这里命名为 `keyboard_keycodes`）： + +```c +enum keyboard_keycodes { + MACRO_1 = SAFE_RANGE, + MACRO_2, + MACRO_3, + NEW_SAFE_RANGE // 重要! +}; +``` + +... 之后在 `.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). diff --git a/docs/zh-cn/configurator_step_by_step.md b/docs/zh-cn/configurato