diff options
Diffstat (limited to 'docs/zh-cn')
| -rw-r--r-- | docs/zh-cn/README.md | 32 | ||||
| -rw-r--r-- | docs/zh-cn/_summary.md | 106 | ||||
| -rw-r--r-- | docs/zh-cn/getting_started_introduction.md | 54 | ||||
| -rw-r--r-- | docs/zh-cn/newbs_best_practices.md | 163 | ||||
| -rw-r--r-- | docs/zh-cn/newbs_building_firmware.md | 81 | ||||
| -rw-r--r-- | docs/zh-cn/newbs_flashing.md | 307 | ||||
| -rw-r--r-- | docs/zh-cn/newbs_getting_started.md | 102 | ||||
| -rw-r--r-- | docs/zh-cn/newbs_learn_more_resources.md | 15 | ||||
| -rw-r--r-- | docs/zh-cn/newbs_testing_debugging.md | 43 |
9 files changed, 903 insertions, 0 deletions
diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md new file mode 100644 index 000000000..9eb4ea777 --- /dev/null +++ b/docs/zh-cn/README.md @@ -0,0 +1,32 @@ +# QMK机械键盘固件 + +[](https://github.com/qmk/qmk_firmware/tags) +[](https://travis-ci.org/qmk/qmk_firmware) +[](https://discord.gg/Uq7gcHh) +[](https://docs.qmk.fm) +[](https://github.com/qmk/qmk_firmware/pulse/monthly) +[](https://github.com/qmk/qmk_firmware/) + +## 什么是 QMK 固件? + +QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包括 QMK 固件, QMK 工具箱, qmk.fm网站, 和这些文档。QMK 固件是一个基于[tmk\_keyboard](http://github.com/tmk/tmk_keyboard)的键盘固件，它在爱特梅尔AVR微控制器实现一些有用的功能,确切地说, 是在 [OLKB product line](http://olkb.com), 在 [ErgoDox EZ](http://www.ergodox-ez.com) 键盘, 和 [Clueboard product line](http://clueboard.co/). 上。它被移植到使用ChibiOS的ARM芯片上. 它可以在飞线键盘或定制PCB键盘中发挥功能. + +## 如何得到它 + +如果你打算贡献布局, 键盘, 或者其他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`). + +## 如何编译 + +在你能编译之前, 你需要[部署环境](getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: + + make planck/rev4:default + +这将建立 `planck`的`rev4` 修订版本并使用 `default`布局。并非所有键盘都有修订版本 (也叫做子项目或文件夹)，在此情况下，修订版本可以省略，如下: + + make preonic:default + +## 如何定制 + +QMK 有许多 [特性](features.md)来探索，也有很多 [参考文档](http://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](keymap.md)和[键码](keycodes.md)来利用许多特性。 diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md new file mode 100644 index 000000000..df25a3ccd --- /dev/null +++ b/docs/zh-cn/_summary.md @@ -0,0 +1,106 @@ +* [完全菜鸟指南](newbs.md) + * [入门](newbs_getting_started.md) + * [构建你的第一个固件](newbs_building_firmware.md) + * [刷新固件](newbs_flashing.md) + * [测试和调试](newbs_testing_debugging.md) + * [Git最佳实践](newbs_best_practices.md) + * [学习资源](newbs_learn_more_resources.md) + +* [QMK基础](README.md) + * [QMK 简介](getting_started_introduction.md) + * [贡献 QMK](contributing.md) + * [如何使用Github](getting_started_github.md) + * [获得帮助](getting_started_getting_help.md) + +* [问题解答](faq.md) + * [一般问题](faq_general.md) + * [构建/编译QMK](faq_build.md) + * [调试/故障排除 QMK](faq_debug.md) + * [键盘布局](faq_keymap.md) + +* 详细指南 + * [安装构建工具](getting_started_build_tools.md) + * [流浪者指南](getting_started_vagrant.md) + * [构建/编译指令](getting_started_make_guide.md) + * [刷新固件](flashing.md) + * [定制功能](custom_quantum_functions.md) + * [布局概述](keymap.md) + +* [硬件](hardware.md) + * [AVR 处理器](hardware_avr.md) + * [驱动](hardware_drivers.md) + +* 参考 + * [键盘指南](hardware_keyboard_guidelines.md) + * [配置选项](config_options.md) + * [键码](keycodes.md) + * [记录最佳实践](documentation_best_practices.md) + * [文档指南](documentation_templates.md) + * [词汇表](reference_glossary.md) + * [单元测试](unit_testing.md) + * [有用的功能](ref_functions.md) + * [配置器支持](reference_configurator_support.md) + * [info.json 格式](reference_info_json.md) + +* [特性](features.md) + * [基本键码](keycodes_basic.md) + * [US ANSI 控制键](keycodes_us_ansi_shifted.md) + * [量子键码](quantum_keycodes.md) + * [高级键码](feature_advanced_keycodes.md) + * [音频](feature_audio.md) + * [自动控制](feature_auto_shift.md) + * [背光](feature_backlight.md) + * [蓝牙](feature_bluetooth.md) + * [Bootmagic](feature_bootmagic.md) + * [组合](feature_combo) + * [命令](feature_command.md) + * [动态宏指令](feature_dynamic_macros.md) + * [编码器](feature_encoders.md) + * [Grave Escape](feature_grave_esc.md) + * [键锁](feature_key_lock.md) + * [层](feature_layouts.md) + * [引导键](feature_leader_key.md) + * [LED 阵列](feature_led_matrix.md) + * [宏指令](feature_macros.md) + * [鼠标键](feature_mouse_keys.md) + * [一键功能](feature_advanced_keycodes.md#one-shot-keys) + * [指针设备](feature_pointing_device.md) + * [PS/2 鼠标](feature_ps2_mouse.md) + * [RGB 光](feature_rgblight.md) + * [RGB 矩阵](feature_rgb_matrix.md) + * [空格候补换挡](feature_space_cadet_shift.md) + * [空格候补换挡回车](feature_space_cadet_shift_enter.md) + * [速录机](feature_stenography.md) + * [换手](feature_swap_hands.md) + * [踢踏舞](feature_tap_dance.md) + * [终端](feature_terminal.md) + * [热敏打印机](feature_thermal_printer.md) + * [Unicode](feature_unicode.md) + * [用户空间](feature_userspace.md) + * [速度键](feature_velocikey.md) + +* 针对制造者和定制者 + * [飞线指南](hand_wire.md) + * [ISP 刷新指南](isp_flashing_guide.md) + * [ARM 调试指南](arm_debugging.md) + * [I2C 驱动](i2c_driver.md) + * [GPIO 控制器](internals_gpio_control.md) + * [Proton C 转换](proton_c_conversion.md) + +* 深入了解 + * [键盘如何工作](how_keyboards_work.md) + * [理解 QMK](understanding_qmk.md) + +* 其他话题 + * [使用Eclipse开发QMK](other_eclipse.md) + * [使用VSCode开发QMK](other_vscode.md) + * [支持](support.md) + +* QMK 内构 (正在编写) + * [定义](internals_defines.md) + * [输入回调寄存器](internals_input_callback_reg.md) + * [Midi 设备](internals_midi_device.md) + * [Midi 设备设置过程](internals_midi_device_setup_process.md) + * [Midi 工具库](internals_midi_util.md) + * [发送函数](internals_send_functions.md) + * [Sysex 工具](internals_sysex_tools.md) diff --git a/docs/zh-cn/getting_started_introduction.md b/docs/zh-cn/getting_started_introduction.md new file mode 100644 index 000000000..dcd0b72a5 --- /dev/null +++ b/docs/zh-cn/getting_started_introduction.md @@ -0,0 +1,54 @@ +# 介绍 + +本页解释了使用QMK项目所需的基本信息。它假定您能熟练使用Unix shell，但您不熟悉C语言也不熟悉使用make编译。 + +## 基本QMK结构 + +QMK是[Jun Wako](https://github.com/tmk)的[tmk_keyboard](https://github.com/tmk/tmk_keyboard)工程的一个分叉。经过更改的TMK原始代码放在`tmk` 文件夹中。 QMK增加的新东西可以在 `quantum` 文件夹中找到。 键盘项目可以在 `handwired`（手动飞线） 和 `keyboard`（PCB键盘）这两个文件夹找到。 + +### 用户空间结构 + +在`users`文件夹里面的目录是每个用户的目录。这个文件夹里面放的是用户们在不同键盘都能用到的代码。详见[用户空间特性](feature_userspace.md) + +### 键盘项目结构 + +在`keyboards`文件夹和他的子文件夹`handwired`中就是各个键盘的项目了，比如`qmk_firmware/keyboards/clueboard`。内部结构与如下: + +* `keymaps/`: 可以构建的不同布局 +* `rules.mk`: 用来设置 "make" 命令默认选项的文件。别直接编辑这个文件,你应该使用具体某个布局的 `rules.mk`. +* `config.h`: 用于设置默认编译选项的文件。别直接编辑这个文件, 你应该使用具体某个布局的 `config.h`. + +### 布局结构 + +在各个布局的文件夹，你能找到以下文件。只有 `keymap.c` 是必要的, 如果其他文件找不到就会直接选择默认选项。 + +* `config.h`: 配置布局的选项 +* `keymap.c`: 布局的全部代码, 必要文件 +* `rules.mk`: 使能的QMK特性 +* `readme.md`:介绍你的布局,告诉别人怎么使用，附上功能说明。请将图片上传到imgur等图床（译者注：imgur可能已被墙，为了方便国人访问，建议使用国内可以直接访问的图床）。 + +# `config.h` 文件 + +有三个重要的`config.h` 位置: + +* 键盘 (`/keyboards/<keyboard>/config.h`) +* 用户空间 (`/users/<user>/config.h`) +* 布局 (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`) + +构建系统按照上述顺序自动获取配置文件。如果要覆盖由上一个 `config.h` 所做的设置，您需要首先为要更改的设置包含一些样板代码。 + +``` +#pragma once +``` + +要覆盖上一个 `config.h` 所做的设置，你要先 `#undef` 然后再 `#define` 这个设置. + +样板代码和设置看起来像这样： + +``` +#pragma once + +// 像下面那样覆盖设置（MY_SETTING指的是你要覆盖的设置项）! +#undef MY_SETTING +#define MY_SETTING 4 +``` diff --git a/docs/zh-cn/newbs_best_practices.md b/docs/zh-cn/newbs_best_practices.md new file mode 100644 index 000000000..fa58dc75e --- /dev/null +++ b/docs/zh-cn/newbs_best_practices.md @@ -0,0 +1,163 @@ +# 最佳实践 + +## 或者说, "我应如何学会不再担心并开始爱上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记录对冲突文件的更改，并继续应用来自我们的分支的提交，直到它到达末尾。 diff --git a/docs/zh-cn/newbs_building_firmware.md b/docs/zh-cn/newbs_building_firmware.md new file mode 100644 index 000000000..31093f254 --- /dev/null +++ b/docs/zh-cn/newbs_building_firmware.md @@ -0,0 +1,81 @@ +# 构建第一个固件 + +现在您已经建立了构建环境，就可以开始构建自定义固件了。对于本指南的这一部分，我们将在3个程序之间切换——文件管理器、文本编辑器和终端窗口。请保持所有3个程序打开，直到您完成并对键盘固件满意。 + +如果您在按照指南第一部分的操作之后关闭并重新打开了终端窗口，请不要忘记输入“cd qmk_firmware”，来使您的终端位于正确的目录。 + +## 导航到您的keymaps文件夹 + +首先导航到键盘的 `keymaps` 文件夹. + +?> 如果您使用的是MacOS或Windows，可以使用以下命令轻松地打开keymaps文件夹。 + +?> macOS: + + open keyboards/<keyboard_folder>/keymaps + +?> Windows: + + start .\\keyboards\\<keyboard_folder>\\keymaps + +## 创建`default` 布局副本 + +打开`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。在靠下的位置你会找到一行和下面这句很像的: + + const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + +从这一行开始便是层列表。这行下面你会看到包括 `LAYOUT` 或 `KEYMAP`这两个词的几行, 从这些行开始就是层。在这一行下面是组成该特定层的键的列表。 + +!> 编辑您的keymap文件时，注意不要添加或删除任何逗号。如果这样做，您将阻止您的固件编译，并且您可能不容易找出多余的或缺少的逗号在哪里。 + +## 根据您的喜好自定义布局 + +如何完成这一步骤完全取决于您。改变一直困扰着你的问题，或者完全重做所有的事情。如果您不需要全部图层，可以删除图层，或者将图层总数增加到32个。查看以下文档，了解可以在此处定义的内容: + +* [键码](keycodes.md) +* [特性](features.md) +* [问题与解答](faq.md) + +?> 当你明白布局是怎么工作时，您也要让每次改变尽可能小。一次改变很大在调试时找出问题会十分困难。 + +## 构建你的固件 + +完成对布局的更改后，您就要构建固件了。为此，请返回终端窗口并运行build命令: + + make <my_keyboard>:<my_keymap> + +例如，如果您的keymap名为“xyverz”，并且您正在为rev5 planck构建一个keymap，那么您将使用此命令： + + make planck/rev5:xyverz + +在编译过程中，你将看到屏幕上有很多输出，通知您正在编译哪些文件他应该以与下文类似的输出结束: + +``` +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 +``` + +## 刷新你的固件 + +请移步 [Flashing Firmware](newbs_flashing.md) 来继续。 diff --git a/docs/zh-cn/newbs_flashing.md b/docs/zh-cn/newbs_flashing.md new file mode 100644 index 000000000..05a9eb55e --- /dev/null +++ b/docs/zh-cn/newbs_flashing.md @@ -0,0 +1,307 @@ +# 刷新你的键盘 + +现在您已经构建了一个自定义固件文件，那么您就需要刷新键盘了。 + +## 用QMK工具箱刷新键盘 + +刷新键盘的最简单方法是使用[QMK 工具箱](https://github.com/qmk/qmk_toolbox/releases). + +但是，QMK工具箱目前仅适用于Windows和MacOS。如果您使用的是Linux（或者只是希望从命令行刷新固件），则必须使用 [方法概述](newbs_flashing.md#flash-your-keyboard-from-the-command-line). + +### 将文件加载到QMK工具箱中 + +首先打开QMK工具箱应用程序。您将要在访达或资源管理器中找到固件文件。您的键盘固件可能是两种格式之一`.hex`或`.bin`。qmk会尝试将键盘的相应文件复制到“qmk_firmware”根目录中。 + +?> 如果您在Windows或MacOS上，可以使用以下命令轻松地在资源管理器或访达中打开当前固件文件夹。 + +?> Windows: + + start . + +?> macOS: + + open . + +固件文件始终遵循此命名格式: + + <keyboard_name>_<keymap_name>.{bin,hex} + +例如，使用 `default` 布局的 `plank/rev5` 将使用以下名字： + + planck_rev5_default.hex + +找到固件文件后，将其拖到QMK工具箱中的“Local file”框中，或单击“Open”并导航到固件文件的存储位置。 + +### 将键盘置于DFU（Bootloader）模式 + +要刷新自定义固件，您必须将键盘置于特殊的刷新模式。在此模式下，您将无法键入或使用键盘。在写入固件时，不要拔下键盘插头或以其他方式中断刷新过程，这一点非常重要。 + +不同的键盘有不同的方式进入这种特殊模式。如果您的键盘当前运行的是QMK或TMK，而您没有得到特定的指示，请按顺序尝试以下操作: + +* 按住两个shift键并按 `Pause` +* 按住两个shift键并按 `B` +* 拔下键盘插头, 同时按住空格键和 `B` , 插上键盘然后等一会再放开按键 +* 按下PCB底部的 `RESET` 物理键 +* 找到PCB上标记有 `BOOT0` 或 `RESET`的金属点, 在插入PCB的同时短接它们 + +成功后，您将在QMK工具箱中看到类似以下内容的消息: + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +``` + +### 刷新你的键盘 + +单击QMK工具箱中的 `Flash` 按钮。您将看到类似以下内容的输出: + +``` +*** 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 +``` + +## 使用命令行刷新键盘 + +首先，您需要知道您的键盘使用的是哪个bootloader。通常是以下四个常见的bootloader。Pro-Micro 和 clones 使用 CATERINA, Teensy 使用 Halfkay, OLKB 键盘使用 QMK-DFU, 其他的atmega32u4芯片使用DFU。 + +您可以在以下文章中了解更多关于bootloader[刷新指令和Bootloader信息](flashing.md)。 + +如果您知道正在使用的bootloader是哪种，那么在编译固件时，可以向“make”命令里添加一些额外参数，以自动执行刷新过程。 + +### DFU + +对于DFU引导加载程序，当您准备好编译和刷新固件时，打开终端窗口并运行构建命令: + + make <my_keyboard>:<my_keymap>:dfu + +例如，如果您的布局名为“xyverz”，并且您正在为rev5 planck构建一个布局，那么您可以使用此命令： + + make planck/rev5:xyverz:dfu + +编译完成后，应输出以下内容： + +``` +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 + ``` + +到了这个时候, 构建脚本将每隔5秒查找一次DFU。它将重复以下操作，直到找到设备或将其取消。 + + dfu-programmer: no device present. + Error: Bootloader not found. Trying again in 5s. + +一旦出现以上回显，您将需要重置控制器。然后，它应该显示与以下类似的输出： + +``` +*** 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 +``` + +如果您对此有任何问题，您可能需要这样做： + + 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. +``` +如果您对此有任何问题，您可能需要这样做： + + sudo make <my_keyboard>:<my_keymap>:avrdude + + +此外，如果要刷新多个板，请使用以下命令： + + make <keyboard>:<keymap>:avrdude-loop + +当你完成了刷新后，你需要按下ctrl+c或者其他正确的按键来让你的操作系统终止循环。 + + +## HalfKay + +对于PJRC设备（Teensy），当您准备好编译和刷新固件时，打开终端窗口并运行构建命令: + + make <my_keyboard>:<my_keymap>:teensy + +比如, 如果你的布局叫做"xyverz"你想创建Ergodox or Ergodox EZ的布局,你要使用以下命令: + + 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 +``` + +## 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 +``` + +## 试一试吧! + +恭喜您! 您的自定义固件已经刷写到您的键盘 + +试一试，确保一切按你想的方式进行。我们写了[测试和调试](newbs_testing_debugging.md)来完善新手引导。 因此，请前往那里了解如何排除自定义功能的故障。 diff --git a/docs/zh-cn/newbs_getting_started.md b/docs/zh-cn/newbs_getting_started.md new file mode 100644 index 000000000..4e7850201 --- /dev/null +++ b/docs/zh-cn/newbs_getting_started.md @@ -0,0 +1,102 @@ +# 介绍 + +你的电脑键盘里面包含一个处理器, 这个处理器和你电脑里面的不太一样。这个处理器负责运行一些特殊的软件，这些软件可以监测按钮按下并将按钮处于按下还是释放状态的数据发送出去。QMK就是这样一种软件，即监测按钮被按下并发送这样的信息到作为主机的计算机上。当你创建了你的布局, 你也就创建了你的键盘运行的的可执行程序。 + +QMK试图通过使简单的事情变得更简单，使使不可能成为可能来把大量的权力交给你。你不需要懂如何通过程序创建强大的布局——你只需要遵循简单的语法规则。 + +# 新手上路 + +在你能创建布局前,你要安装一些软件来建立你的开发环境。无论你想编译多少固件，这个操作都只需要进行一次。 + +如果您更喜欢图形化界面, 请考虑使用在线工具[QMK配置器](https://config.qmk.fm)。 请参考 [使用在线GUI构建您的第一个固件](newbs_building_firmware_configurator.md)。 + + +## 下载软件 + +### 文本编辑器 + +你需要一个可以编辑 **纯文本** 文件的程序。在Windows上你可以用Notepad, 在Linux上使用gedit，这两个都是简单又实用的文本编辑工具。 在macOS上, 请小心使用 “文本编辑” 这个默认软件: 如果你不明确的选择_格式_菜单中的 _制作纯文本_ 的话文本将不会被保存为纯文本。 + +你也可以下载并安装一个专用编辑器 [Sublime Text](https://www.sublimetext.com/) 或 [VS Code](https://code.visualstudio.com/)。 这大概是跨平台的最好方法了, 这些编辑器是专门为了编辑代码设计的。 + +?>搞不清用哪种编辑器? Laurence Bradford 写了篇关于编辑器选择的文章 [a great introduction](https://learntocodewith.me/programming/basics/text-editors/)。 + +### QMK 工具箱 + +QMK 工具箱 是一种可选的Windows和macOS下的图形化工具，它可以对你的定制键盘进行编程和调试。你可能会发现它就是你能简单的刷新你的键盘固件并查看调试信息的稀世珍宝。 + +[在这里下载最新发布版本](https://github.com/qmk/qmk_toolbox/releases/latest) + +* Windows用户: `qmk_toolbox.exe` (绿色版) 或 `qmk_toolbox_install.exe` (安装版) +* macOS用户: `QMK.Toolbox.app.zip` (绿色版) or `QMK.Toolbox.pkg` (安装版) + +## 建立你的环境 + +我们为了使QMK环境变得更容易建立已竭尽所能。你只需要准备Linux 或 Unix 环境, 然后让QMK安装剩余部分。 + +?> 如果你从未使用过Linux/Unix的命令行,有一些你需要学习的基础概念和命令，以下资料将教会您使用QMK环境的必要能力:<br> +[必会Linux命令](https://www.guru99.com/must-know-linux-commands.html)<br> +[一些基本的Unix命令](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) + +### Windows + +你需要安装MSYS2和Git. + +* 按照以下安装说明进行操作[MSYS2 主页](http://www.msys2.org)。 +* 关闭所有打开的MSYS2终端并打开新的MSYS2 MinGW 64-bit终端。 +* 使用以下命令安装Git: `pacman -S git`。 + +### macOS + +你需要安装Homebrew。按照以下说明进行操作 [Homebrew 主页](https://brew.sh)。 + +在Homebrew安装完成后, 继续 _同步QMK工程_. 这一步你将会通过运行一个脚本安装其他包。 + +### Linux + +你将需要安装Git.你很有可能已经安装,但若你尚未安装,可以使用以下命令进行安装: + +* Debian / Ubuntu / Devuan: `apt-get install git` +* Fedora / Red Hat / CentOS: `yum install git` +* Arch: `pacman -S git` + +?> 无论你使用哪种平台，Docker都可以是你的选择[点这里进一步了解](getting_started_build_tools.md#docker) + +## 同步QMK工程 + +当你建立Linux/Unix环境后,你就已经可以下载QMK了.下载时我们可以用Git来 "clone" QMK仓库. 打开一个终端或MSYS2 MinGW 窗口，在阅读剩余的指南时请保持窗口打开。在窗口里面运行以下两句命令: + +```shell +git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git +cd qmk_firmware +``` + +?> 如果您已经知道[如何使用GitHub](getting_started_github.md), 我们推荐您创建您自己的分支并克隆。 如果您不知道这是什么, 您完全可以忽略这句无关紧要的话。 + +QMK附带一个脚本，可帮助您设置剩余的所需内容.您可以通过输入此命令来运行它: + + util/qmk_install.sh + +## 测试你的开发环境 + +现在你的QMK环境已经建立完毕, 你可以为你的键盘创建固件了。开始试着创建键盘的默认固件吧。 你需要使用以下格式的命令创建固件: + + make <keyboard>:default + +比如, 制作一个Clueboard 66%的固件，需要用: + + make clueboard/66/rev3:default + +当完成后你要看到一些回显，尾部如下: + +``` +Linking: .build/clueboard_66_rev3_default.elf [OK] +Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK] +Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] +Checking file size of clueboard_66_rev3_default.hex [OK] + * The firmware size is fine - 26356/28672 (2316 bytes free) +``` + +# 创建你的布局 + +现在你可以创建属于你自己的布局了! 请移步 [构建你的第一个固件](newbs_building_firmware.md)来继续。 diff --git a/docs/zh-cn/newbs_learn_more_resources.md b/docs/zh-cn/newbs_learn_more_resources.md new file mode 100644 index 000000000..ccb4fa326 --- /dev/null +++ b/docs/zh-cn/newbs_learn_more_resources.md @@ -0,0 +1,15 @@ +# 学习资源 + +这些资源旨在让QMK社区的新成员更了解新成员文档中提供的信息。 + +Git 资源: + +* [很好的通用教程](https://www.codecademy.com/learn/learn-git) +* [从例子中学习Git游戏](https://learngitbranching.js.org/) +* [了解有关GitHub的更多信息的Git资源](getting_started_github.md) +* [专门针对QMK的Git资源](contributing.md) + + +命令行资源: + +* [超棒的命令行通用教程](https://www.codecademy.com/learn/learn-the-command-line) diff --git a/docs/zh-cn/newbs_testing_debugging.md b/docs/zh-cn/newbs_testing_debugging.md new file mode 100644 index 000000000..824f94b90 --- /dev/null +++ b/docs/zh-cn/newbs_testing_debugging.md @@ -0,0 +1,43 @@ +# 测试和调试 + +使用自定义固件刷新键盘后，您就可以测试它了。如果您幸运，一切都会完美运行，但如果没有，这份文件将帮助您找出问题所在。 + +## 测试 + +测试键盘通常非常简单。按下每一个键并确保它发送的是您期望的键。甚至有一些程序可以帮助您确保没有任何键失效。 + +注意：这些程序不是由QMK提供或认可的。 + +* [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (仅Windows) +* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (仅Mac) +* [Keyboard Tester](http://www.keyboardtester.com) (网页版) +* [Keyboard Checker](http://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`: + + #include <print.h> + +之后，您可以使用一些不同的打印功能: + +* `print("string")`: 打印简单字符串. +* `uprintf("%s string", var)`: 打印格式化字符串 +* `dprint("string")`: 仅在调试模式使能时打印简单字符串 +* `dprintf("%s string", var)`: 仅在调试模式使能时打印格式化字符串 |