diff options
Diffstat (limited to 'docs/zh-cn')
| -rw-r--r-- | docs/zh-cn/_summary.md | 66 | ||||
| -rw-r--r-- | docs/zh-cn/contributing.md | 205 | ||||
| -rw-r--r-- | docs/zh-cn/custom_quantum_functions.md | 490 | ||||
| -rw-r--r-- | docs/zh-cn/faq.md | 6 | ||||
| -rw-r--r-- | docs/zh-cn/faq_build.md | 150 | ||||
| -rw-r--r-- | docs/zh-cn/faq_debug.md | 233 | ||||
| -rw-r--r-- | docs/zh-cn/faq_general.md | 19 | ||||
| -rw-r--r-- | docs/zh-cn/faq_keymap.md | 212 | ||||
| -rw-r--r-- | docs/zh-cn/getting_started_getting_help.md | 15 | ||||
| -rw-r--r-- | docs/zh-cn/getting_started_github.md | 59 | ||||
| -rw-r--r-- | docs/zh-cn/newbs.md | 23 | ||||
| -rw-r--r-- | docs/zh-cn/reference_glossary.md | 170 |
12 files changed, 1615 insertions, 33 deletions
diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md index df25a3ccd1..b0d9f1c068 100644 --- a/docs/zh-cn/_summary.md +++ b/docs/zh-cn/_summary.md @@ -7,27 +7,27 @@ * [学习资源](newbs_learn_more_resources.md) * [QMK基础](README.md) - * [QMK 简介](getting_started_introduction.md) - * [贡献 QMK](contributing.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) + * [构建/编译](faq_build.md) + * [调试/故障排除](faq_debug.md) + * [键盘映射](faq_keymap.md) * 详细指南 * [安装构建工具](getting_started_build_tools.md) - * [流浪者指南](getting_started_vagrant.md) + * [vagrant指南](getting_started_vagrant.md) * [构建/编译指令](getting_started_make_guide.md) * [刷新固件](flashing.md) * [定制功能](custom_quantum_functions.md) - * [布局概述](keymap.md) + * [映射概述](keymap.md) * [硬件](hardware.md) - * [AVR 处理器](hardware_avr.md) + * [AVR处理器](hardware_avr.md) * [驱动](hardware_drivers.md) * 参考 @@ -35,8 +35,8 @@ * [配置选项](config_options.md) * [键码](keycodes.md) * [记录最佳实践](documentation_best_practices.md) - * [文档指南](documentation_templates.md) - * [词汇表](reference_glossary.md) + * [文档模板](documentation_templates.md) + * [术语表](reference_glossary.md) * [单元测试](unit_testing.md) * [有用的功能](ref_functions.md) * [配置器支持](reference_configurator_support.md) @@ -44,35 +44,35 @@ * [特性](features.md) * [基本键码](keycodes_basic.md) - * [US ANSI 控制键](keycodes_us_ansi_shifted.md) + * [US ANSI控制码](keycodes_us_ansi_shifted.md) * [量子键码](quantum_keycodes.md) * [高级键码](feature_advanced_keycodes.md) * [音频](feature_audio.md) - * [自动控制](feature_auto_shift.md) + * [自动shift](feature_auto_shift.md) * [背光](feature_backlight.md) * [蓝牙](feature_bluetooth.md) - * [Bootmagic](feature_bootmagic.md) + * [热改键](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) + * [重音号Esc复合键](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) + * [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_tap_dance.md) * [终端](feature_terminal.md) * [热敏打印机](feature_thermal_printer.md) * [Unicode](feature_unicode.md) @@ -80,16 +80,16 @@ * [速度键](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) + * [手工连线指南](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) + * [理解QMK](understanding_qmk.md) * 其他话题 * [使用Eclipse开发QMK](other_eclipse.md) @@ -99,8 +99,8 @@ * 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) + * [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) + * [Sysex工具](internals_sysex_tools.md) diff --git a/docs/zh-cn/contributing.md b/docs/zh-cn/contributing.md new file mode 100644 index 0000000000..62b956b619 --- /dev/null +++ b/docs/zh-cn/contributing.md @@ -0,0 +1,205 @@ +# 如何做贡献 + +👍🎉 首先感谢各位百忙之中抽空阅读本文档,并为我们无私奉献。给您点赞啦! 🎉👍 + +第三方的帮助让Q酱成长了许多呢,Q酱也从你们那学到了不少新东西。Q酱希望每一个想帮助我的人都能很方便的做出有用的贡献。在这里我给摩拳擦掌的你们写了一点引导,让你们的代码在不对我做重大改动的情况下都能成功的被采纳哦。 + +* [项目概况](#项目概况) +* [代码规范](#代码规范) +* [一般教程](#一般教程) +* [行为守则对于我来说有何意义?](#行为守则对于我来说有何意义?) + +## 这文章巨长无比不想读啊! 我就想问个问题而已! + +您要是想问关于Q酱的问题的话可以在[OLKB Subreddit](https://reddit.com/r/olkb)或者是[Discord](https://discord.gg/Uq7gcHh)随意问。 + +请记住: + +* 维护Q酱的小可爱有的时候可能会有点忙,不能及时回答您的问题,耐心等等,他们都是很nice的人呀。 +* 维护Q酱的人都是很无私的善良的人。无论是贡献代码还是回答问题,都是义务的。有时见到他们努力回答各种问题,解决各种BUG,Q酱也是很心疼的。 +* 您可以看看下面的教程,可以让您的问题浅显易懂,更容易回答: + * https://opensource.com/life/16/10/how-ask-technical-questions + * http://www.catb.org/esr/faqs/smart-questions.html + +# 项目概况 + +Q酱很大一部分是用C语言组成的,不过有一小部分特性是C++的。怎么说呢,都是我的一部分,两个我都爱。Q酱一般是在键盘上的嵌入式处理器那里工作的,尤其与AVR([LUFA](http://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](http://www.chibios.com))两小哥哥搭配,干活不累,嘻嘻。如果您精通Arduino的话您会发现很多熟悉的概念,但也有点不爽,因为您以前的经验可能没法用来帮助Q酱。 + +<!-- 需要修正: 这里放些学习C语言的资源。另外感谢修正的小可爱。谢谢您了。--> + +# Q酱,我在哪能帮助你嘞? + +您要是有问题的话可以 [提出一个issue](https://github.com/qmk/qmk_firmware/issues) 或 [在Discord上交流一下](https://discord.gg/Uq7gcHh). + +# Q酱,我如何帮助你? + +您以前是否没为开源贡献过代码,而又想知道帮助Q酱是怎么一回事? 稍安勿躁,咱给您总结一下! + +0. 先注册一个 [GitHub](https://github.com) 账户。 +1. 做好一个你要贡献的布局,那就要 [找一个你想解决的问题](https://github.com/qmk/qmk_firmware/issues),或者 [找一个你想添加的特性](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)。 +2. 把关联着问题的仓库分叉(fork)到你的仓库。这样你在`你的GitHub用户名/qmk_firmware`就有一个仓库备份啦。 +3. 使用 `git clone https://github.com/此处添GitHub用户名/此处添仓库名.git`这个命令把仓库同步到你的电脑中。 +4. 您要是想开发一个新特性的话可以先创建一个issue和Q酱的维护者讨论一下您要做什么。 +5. 使用`git checkout -b 此处写分支名字(别用汉字)`命令来创建一个分支(branch)用于开发。 +6. 对要解决的问题或要添加的特性进行适当的更改。 +7. 使用 `git add 把改变的文件的目录写这里` 可以添加改变的文件内容到git用于管理工程状态的索引(快照)里。 +8. 使用 `git commit -m "这里写修改的相关信息"` 来描述你做出了什么修改。 +9. 使用 `git push origin 此处写分支名字`来把你的更改同步到GitHub库里(反正不是打篮球那个库里)。 +10. 提交一个[QMK 固件的pull request](https://github.com/qmk/qmk_firmware/pull/new/master)。 +11. 给你的pull request拟一个标题,包括简短的描述和问题或错误代码。比如, 你可以起一个这样的"Added more log outputting to resolve #4352"(最好用英语,毕竟Q酱的中文也不是那么的溜,有可能会看不懂中文)。 +12. 在描述(description)里面写你做了哪些更改,你的代码里还存在什么问题, 或者你想问维护的小可爱们的问题。你的your pull request有点小问题无伤大雅(本来也没有完美的代码嘛), 维护的小可爱们会竭尽全力帮您改进的! +13. 维护人员审查代码可能需要一些时间。 +14. 维护人员会通知您要更改什么地方,然后您就按照建议改一改。 +15. 预祝您合并成功! + +# 代码规范 + +其实也没有什么特别严格的规范啦,但是俗话说的好:没有规矩,不成方圆。您可以看一下您的要改动的代码周围的画风,然后保持队形。如果你感觉周围都不知道是什么牛鬼蛇神的话就看看下面的建议: + +* 我们用肆(4)个空格来缩进(软件中也可以设置到Tab键) +* 我们使用改良的1TBS(允许单行样式) + * 左大括号: 在开放性语句块那行的末尾 + * 右大括号: 和开放性语句块第一个字母对齐 + * Else If: 将右大括号放在行的开头,下一个左大括号放在同一行的结尾 + * 可选大括号: 可选大括号是必选的 + * 应该这样: if (condition) { return false; } + * 不应该这样: if (condition) return false; +* 建议使用C语言风格的注释: `/* */` + * 把注释想象成一个描述特征的故事 + * 充分使用注释来描述你为何这样修改 + * 有些公认的东西就不要写到注释里面了 + * 如果你不知道注释是否多余,看下面 +* 一般不要主动换行,主动换行的话每行不要超过76列 +* 要把 `#pragma once` 放到头文件的开始哦,抛弃老土的(`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)吧 +* 下面两种预处理命令都可以用: `#ifdef DEFINED` 还有 `#if defined(DEFINED)` + * 以上那句对处女座不是很友好哈,处女座的朋友们就别纠结了,直接 `#if defined(DEFINED)` 。 + * 还有就是选好一种风格就一直用,一直用一直爽,不要朝三暮四, 除非你要变化到多重条件的 `#if`。 + * `#` 和 `if`要挨在一起哦,再让本空格在中间冒充电灯泡本空格会生气的。 + * 以下是缩进规则: + * 首先考虑可读性,强迫症的朋友们总想要保持代码的高一致性,这样可不好。 + * 保证文件已有风格不变。如果代码本来就是杂糅风格,那就见机行事,让你的修改更有意义些。 + * 其实你也可以在缩进的时候看看周围其他代码,然后范水模山,预处理命令可以有自己的缩进风格。 + +可以参照下面: + +```c +/* foo 的 Enums*/ +enum foo_state { + FOO_BAR, + FOO_BAZ, +}; + +/* 有返回值的情况 */ +int foo(void) { + if (some_condition) { + return FOO_BAR; + } else { + return -1; + } +} +``` + +# Clang-format的自动格式化 +[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) 是LLVM的一部分,可以帮你自动格式化代码。我们给你准备好了一个适用于以上规范的配置文件,会帮你调整缩进和换行,你只需要写好括号就好。有了它,你再也不用担心调整代码格式太耗时,没有时间陪伴自己(虚构)的另一半了。 + +使用[LLVM 完整安装](http://llvm.org/builds/)可以在Windows上安装clang-format, Ubuntu用户要用`sudo apt install clang-format`。 + +命令行的朋友们, 加上 `-style=file`选项就会自动在QMK的根目录寻找.clang-format配置文件了。 + +VSCode用户, 标准的 C/C++ 插件就支持clang-format, 或者可以用[独立扩展](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat)也行。 + +有些东西(比如LAYOUT宏) 会被clang-format打乱,所以那些文件就别用clang-format了,这里就教您一个小窍门,在`// clang-format off` 和 `//clang-format on`之间装上会被搞乱的代码就好了。 + +# 一般教程 + +你可以给Q酱的不同部分添砖加瓦,但也要用不同的方法严谨检查。不论你修改哪里最好还是看看下边。 + +* 将PR(pull request)分成一个个的逻辑单元。 比如,不要一次将两个新特性PR出去。要添加的特性排好队,一个一个来。 +* 提交之前看一眼,`git diff --check`的空格一定要写对了 +* 确定你的代码能通过编译 + * 布局: 确定`make keyboard:your_new_keymap` 不返回错误 + * 键盘: 确定 `make keyboard:all` 不返回错误 + * 核心代码: 确定 `make all` 不返回错误 +* 提交的信息尽量明确。第一行写点简短介绍(每行不多于70个英文字母), 第二行空着,第三行和后面就要写些必要的细节了。最好用英文写,比如: + +``` +Adjust the fronzlebop for the kerpleplork + +The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations. + +Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure. +``` + +## 文档 + +想帮助Q酱当然是先看文档最简单了。找到这个文档哪里错了然后改正它对于你来说超级简单! 我们也对有写文档能力的人求贤若渴,如果你是对的人[点这个](#Q酱,我在哪能帮助你嘞?)! + +文档呢,都静静的放在`qmk_firmware/docs` 目录里, 也或者您想为网页做贡献的话也是可以的哦。 + +在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 把enums的名字都改成像`my_layers`或者`my_keycodes`来防止名字不一致的enums被当作特务枪毙: + +```c +enum my_layers { + _FIRST_LAYER, + _SECOND_LAYER +}; + +enum my_keycodes { + FIRST_LAYER = SAFE_RANGE, + SECOND_LAYER +}; +``` + +## 布局 + +大多数QMK新手都从创建一个自己的布局开始。我们尽力保证布局规范宽松 (毕竟布局是个性的体现) 不过建议遵守以下准则,这样可以让别人更好理解你的代码 + +* 用 [模板](documentation_templates.md)写个`readme.md`。 +* 所有的布局PR都会被squash, 如果你想知道你的提交是怎么被squash的那你就自己来吧 +* 不要把新特性和布局一起PR。可以分别PR他们 +* 布局文件夹就不要放`Makefile`了,这个操作都过时啦 +* 更新文件头部的copyrights(看`%YOUR_NAME%`那) + +## 键盘 + +QMK的最终归宿是键盘。有些键盘是社区维护的,有一些是制作这些键盘的人维护的。`readme.md`会告诉你是谁维护了这个键盘,如果你对某个键盘有疑问,可以 [创建一个Issue](https://github.com/qmk/qmk_firmware/issues) 来问一问维护者。 + +我们建议你按下面的来操作: + +* 用[模板](documentation_templates.md)写`readme.md`。 +* 提交数量尽量合理,不然我们可就要把你的PR给squash了。 +* 不要把新特性和新键盘一起PR。可以分别PR他们 +* 用父文件夹的名字命名 `.c`/`.h`文件, 比如`/keyboards/<kb1>/<kb2>/<kb2>.[ch]` +* 键盘文件夹就不要放`Makefile`了,这个操作都过时啦 +* 更新文件头部的copyrights(看`%YOUR_NAME%`那) + +## Quantum/TMK 核心 + +在您废寝忘食地开发Q酱新特性或者帮Q酱驱虫之前,一定要确保你的工作是有意义的。看看[了解QMK](understanding_qmk.md)你会对Q酱有更深的了解,这个文档将带你领略QMK的程序流程。现在你应该和维护团对谈谈来了解实现你想法的最佳方法了。一下渠道都可以: + +* [在Discord交流](https://discord.gg/Uq7gcHh) +* [建立一个Issue](https://github.com/qmk/qmk_firmware/issues/new) + +新特性和BUG的修复影响所有键盘。开发组也在翻修QMK。所以,在实施重大返修之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR,而且你的选择与维护团队的计划方向不符,那你可能要面临大改了。 + +修复BUG或者开发新特性之前看看这个: + +* **默认不启用** - QMK运行的芯片多数内存有限,所以首要考虑的还应该是布局不要被破坏,于是特性默认是不启用的。你喜欢什么特性的话就打开它,如果你觉得有些特性应该默认开启或者你能帮助缩减代码,那就联系维护组吧。 +* **提交之前在本地编译** - 这个简直就是家喻户晓了,但是也确实需要编译啊! 我们的Travis系统会发现一切问题,但是自己编译一下可要比在线等快多了。 +* **注意版本和芯片平台** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。试着写一个能AVR和ARM两个平台运行的特性,或者在不支持的平台自动禁用。 +* **解释你的新特性** - 在`docs/`写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来,其他人就无法从你的努力中获益。 + +也可以看看以下建议: + +* 提交数量尽量合理,不然我们可就要把你的PR给squash了。 +* 不要把新特性、布局和键盘一起PR。可以分别PR他们。 +* 给你的特性写[单元测试](unit_testing.md)。 +* 你编辑的文件风格要一致,如果风格不明确或者是混搭风的,你就要先看看[代码规范](#代码规范)确认情况。 + +## 重构 + +为了保持QMK脉络清晰,Q酱打算深入规划重构一下自己,然后让合作者进行修改。如果你有重构的思路或建议[创建一个issue](https://github.com/qmk/qmk_firmware/issues), Q酱很乐意讨论一下怎么改进一下。 + +# 行为守则对于我来说有何意义? + +我们的[行为守则](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) 是说明您有责任尊重和礼貌地对待项目中的每个人,无论他们的身份如何。 如果你是我们行为准则所描述的不当行为的受害者,我们将站在你这边,并按照行为准则对施暴者进行适当谴责。 diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md new file mode 100644 index 0000000000..42ceba9cac --- /dev/null +++ b/docs/zh-cn/custom_quantum_functions.md @@ -0,0 +1,490 @@ +# ��ζ�������̵Ĺ��� + +���ںܶ�����˵���ƻ����̿ɲ�ֻ������ĵ��Է����㰴���Ǹ�����ô����϶���ʵ�ֱȼ����ͺ�����ӵĹ��ܡ�QMK��������ע�����Ĺ���, ���ǹ���, ���⣬�������Զ�������ڲ�ͬ����µ���Ϊ�� + +��ҳ���ٶ��κ������QMK֪ʶ�����Ķ�[����QMK](understanding_qmk.md)�����ڸ������IJ���������ⷢ����ʲô�� + +## A Word on Core vs ���� vs ���� + +���ǰ�qmk��֯��һ����νṹ�� + +* Core (`_quantum`) + * Keyboard/Revision (`_kb`) + * Keymap (`_user`) + +����������ÿһ�������������ڶ����ϼ�һ��`_kb()`�� `_user()` ���� �����ڼ���/����ʹ��`_kb()`�����ڲ��ֲ�ʹ��`_user()`���� + +�ڼ���/���㶨�庯��ʱ��`_kb()`��ִ���κδ���ǰ�ȵ���`_user()`�DZ�Ҫ�ģ���Ȼ���ֲ㺯���Ͳ�Ҫ�����á� +<!-- �������⣺�����Ǿ䷭��IJ�̫��--> +# �Զ������ + +��ĿǰΪֹ������������Ǹ������м������Ϊ���µļ��롣�Ӵ���Ƕ�������Щ�����������ơ� + +## ����һ���¼��� + +���������һ������ö�ٳ���ȫ����Ҳ���Ǹ�����������ֲ�����Ψһ��ֵ��QMKû��ֱ������������ֵ��С�������ṩ��һ��`SAFE_RANGE`�ꡣ�������ö��ʱ��`SAFE_RANGE`����֤��ȡ����Ψһ�ļ���ֵ�� + + +����ö��������������ӡ������ӵ�`keymap.c`�Ļ�����ڲ���������`FOO`��`BAR`�ˡ� + +```c +enum my_keycodes { + FOO = SAFE_RANGE, + BAR +}; +``` + +## Ϊ�������Ϊ��� + +���㸲��һ���Ѵ��ڰ�������Ϊʱ���������Ϊ�����¼�ʱ����Ҫ��`process_record_kb()`��`process_record_user()`���������������ڼ���������ʵ���¼�������ǰ��QMK���á����������������`true`��QMK�����������ķ�ʽ�������롣�������Ժܷ������չ����Ĺ��ܶ������滻���������������`false` QMK������������������Ȼ���ͼ���̧���ǰ����¼�����������ˡ� + +��ij�������»��ͷ�ʱ���������ᱻ���á� + +### process_record_user()`����ʾ��ʵ�� + +����������������¡��Զ�����һ������`FOO`�ļ������Ϊ�����������ڰ��»س�ʱ���������� + +```c +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case FOO: + if (record->event.pressed) { + // ����ʱ��Щʲô + } else { + // �ͷ�ʱ��Щʲô + } + return false; // �����˼������н�һ������ + case KC_ENTER: + // �����»س�ʱ�������� + if (record->event.pressed) { + PLAY_NOTE_ARRAY(tone_qwerty); + } + return true; // ��QMK�����س�����/�ͷ��¼� + default: + return true; // ���������������� + } +} +``` + +### `process_record_*` �����ĵ� + +* ����/��: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` +* ����: `bool process_record_user(uint16_t keycode, keyrecord_t *record)` + +`keycode(����)`�������ڲ����϶���ģ�����`MO(1)`, `KC_L`, �ȵȡ� ��Ҫ�� `switch...case` ����������Щ�¼��� + +`record`��������ʵ�ʰ�������Ϣ�� + +```c +keyrecord_t record { + keyevent_t event { + keypos_t key { + uint8_t col + uint8_t row + } + bool pressed + uint16_t time + } +} +``` + +# LED���� + +qmk�ṩ�˶�ȡHID�淶������5��LED�ķ�����: + +* `USB_LED_NUM_LOCK` +* `USB_LED_CAPS_LOCK` +* `USB_LED_SCROLL_LOCK` +* `USB_LED_COMPOSE` +* `USB_LED_KANA` + +�����������Ӧ������LED״̬��λ��λ�� +�����ַ������Ի������LED״̬�� + +* ͨ��ִ�� `led_set_user()` +* ͨ������ `host_keyboard_leds()` + +## `led_set_user()` + +��5��LED���κ�һ����״̬��Ҫ�ı�ʱ���˺����������á��˺���ͨ����������LED������ +ʹ��`IS_LED_ON(usb_led, led_name)`��`IS_LED_OFF(usb_led, led_name)`�������������LED״̬�� + +!> `host_keyboard_leds()`���ܻ���`led_set_user()`������ǰ������ֵ�� + +### `led_set_user()`����ʾ��ʵ�� + +```c +void led_set_user(uint8_t usb_led) { + if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) { + writePinLow(B0); + } else { + writePinHigh(B0); + } + if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) { + writePinLow(B1); + } else { + writePinHigh(B1); + } + if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) { + writePinLow(B2); + } else { + writePinHigh(B2); + } + if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) { + writePinLow(B3); + } else { + writePinHigh(B3); + } + if (IS_LED_ON(usb_led, USB_LED_KANA)) { + writePinLow(B4); + } else { + writePinHigh(B4); + } +} +``` + +### `led_set_*`�����ĵ� + +* ����/��: `void led_set_kb(uint8_t usb_led)` +* ����: `void led_set_user(uint8_t usb_led)` + +## `host_keyboard_leds()` + +������������᷵������յ���LED״̬�����������`led_set_*`֮���ȡLED״̬ʱ�����ã�������[`matrix_scan_user()`](#����ɨ�����). +Ϊ�˱�ݣ��������`IS_HOST_LED_ON(led_name)`��`IS_HOST_LED_OFF(led_name)` �꣬����ֱ�ӵ��úͼ��`host_keyboard_leds()`�� + +## ��������LED״̬ + +һЩ����ʵ����Ϊ��������LED��״̬�ṩ�˷���ķ����� + +### Ergodox Boards + +Ergodoxʵ�����ṩ`ergodox_right_led_1`/`2`/`3_on`/`off()`����ÿ��LED�����, Ҳ������ `ergodox_right_led_on`/`off(uint8_t led)` ��������ر����ǡ� + +���⣬������ʹ��`ergodox_led_all_set(uint8_t n)`ָ������LED�����ȼ������ÿ��LED��`ergodox_right_led_1`/`2`/`3_set(uint8_t n)`��ʹ�������Ļ���`ergodox_right_led_set(uint8_t led, uint8_t n)`�� + +Ergodox boards ͬʱ������������ȼ���`LED_BRIGHTNESS_LO`��������ȼ���`LED_BRIGHTNESS_HI`(Ĭ�����). + +# ���̳�ʼ������ + +���̳�ʼ�������м������衣�������Ǹ�����ȡ��������Ҫ��ʲô�� + +��������Ҫ��ʼ��������������˳���г��� + +* `keyboard_pre_init_*` - ���ڴ����������������ǰ���С���������Щ��Ҫ��ǰ���е�Ӳ����ʼ���� +* `matrix_init_*` - �ڹ̼����������м䱻���á���ʱӲ���ѳ�ʼ����������δ��ʼ���� +* `keyboard_post_init_*` - �ڹ̼�������������á����������£���ġ����ƻ������붼���Է������ + +!> ���ڴ��������˵`keyboard_post_init_user`������Ҫ���õĺ���������, ��ʱ���������RGB�Ʒ��⡣ + +## ����Ԥ��ʼ������ + +����뼫�����У���������USB��ʼ��ǰ���С� + +����֮�þ���ͱ���ʼ���ˡ� + +���ڴ�����û���˵,���ò�������Ϊ����Ҫ����������Ӳ���ij�ʼ���� + +���������Ӳ����ʼ���Ļ����������ٺò�����(�����ʼ��LED����һ���). + +### `keyboard_pre_init_user()`����ʾ��ʵ�� + +�������ڼ��̼����趨 B0, B1, B2, B3, �� B4 ��LED���š� + +```c +void keyboard_pre_init_user(void) { + // ���ü���Ԥ��ʼ������ + + // ����LED����Ϊ���ģʽ + setPinOutput(B0); + setPinOutput(B1); + setPinOutput(B2); + setPinOutput(B3); + setPinOutput(B4); +} +``` + +### `keyboard_pre_init_*` �����ĵ� + +* ����/��: `void keyboard_pre_init_kb(void)` +* ����: `void keyboard_pre_init_user(void)` + +## �����ʼ������ + +�⽫���ھ����ʼ��ʱ�����ã���ijЩӲ�����úú���һЩ���ܱ���ʼ��ǰ�� + +���������������ط����õ��Ķ�����ʱ�������ã�����Ӳ���أ�Ҳ����������������λ�á� + + +### `matrix_init_*`�����ĵ� + +* ����/��: `void matrix_init_kb(void)` +* ����: `void matrix_init_user(void)` + + +## ���̺��ʼ������ + +���Ǽ��̳�ʼ�������е����һ����������������ijЩ���ԣ��������ã���Ϊ��ʱӦ�ö����ǽ��г�ʼ���� + + +### `keyboard_post_init_user()`ʾ��ʵ�� + +��ʾ�������г�ʼ����ɺ����У�����RGB�ơ� + +```c +void keyboard_post_init_user(void) { + // ���ú��ʼ������ + rgblight_enable_noeeprom(); // ʹ��Rgb������������ + rgblight_sethsv_noeeprom(180, 255, 255); // ����ɫ���õ�����ɫ(��ɫ)������ + rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // ���ÿ��ٺ���ģʽ������ +} +``` + +### `keyboard_post_init_*` �����ĵ� + +* ����/��: `void keyboard_post_init_kb(void)` +* ����: `void keyboard_post_init_user(void)` + +# ����ɨ����� + +���ܵĻ���Ҫ��`process_record_*()`�Զ�����̣������ַ�ʽ���ӵ��¼��У���ȷ�����벻��Լ��̲������������Ӱ�졣Ȼ�����ڼ���������£��б�Ҫ���о���ɨ�衣����Щ������Ҫ�ر�ע���������ܣ���Ϊ��ÿ�����ٱ�����10�Ρ� + +### `matrix_scan_*`ʾ��ʵ�� + +������ӱ�����ʡ���ˡ���hook����һ�������ܼ������е�����֮ǰ����Ӧ���㹻�˽�qmk���ڲ��ṹ���Ա���û��ʾ��������±�д���������Ҫ��������[����һ��issue](https://github.com/qmk/qmk_firmware/issues/new)��[��Discord�������ǽ���](https://discord.gg/Uq7gcHh). + +### `matrix_scan_*` �����ĵ� + +* ����/��: `void matrix_scan_kb(void)` +* ����: `void matrix_scan_user(void)` + +�ú�����ÿ�ξ���ɨ��ʱ�����ã��������MCU��������������ͬ��������д����Ҫ��������Ϊ�������кܶ�Ρ� + +������Զ������ɨ�����ʱ�õ������������Ҳ���������Զ���״̬���(����LED�ƻ�����Ļ)�������������û���������Ҳ�붨�����еĹ��ܡ� + + +# ���� ����/���� ���� + +�������֧�־Ϳ���ͨ��ֹͣһ��Ʊ�������ﵽ"����"��RGB�ƺͱ�����Ǻܺõ����ӡ�����Խ�Լ�ܺģ�Ҳ����������̷�ζ���ѡ� + +��������������: `suspend_power_down_*`��`suspend_wakeup_init_*`, �ֱ���ϵͳ����кͻ���ʱ���á� + + +### suspend_power_down_user()��suspend_wakeup_init_user()ʾ��ʵ�� + + +```c +void suspend_power_down_user(void) { + rgb_matrix_set_suspend_state(true); +} + +void suspend_wakeup_init_user(void) { + rgb_matrix_set_suspend_state(false); +} +``` + +### ���� ����/���� �����ĵ� + +* ����/��: `void suspend_power_down_kb(void)` ��`void suspend_wakeup_init_user(void)` +* ����: `void suspend_power_down_kb(void)` �� `void suspend_wakeup_init_user(void)` + +# ��ı���� + +ÿ����ı���������д��롣����ڲ�ָʾ���Զ���㴦�������á� + +### `layer_state_set_*` ʾ��ʵ�� + +����ʹ����Planck����ʾ����������� [RGB�����](feature_rgblight.md)ʹ֮����Ӧ + +```c +uint32_t layer_state_set_user(uint32_t state) { + switch (biton32(state)) { + case _RAISE: + rgblight_setrgb (0x00, 0x00, 0xFF); + break; + case _LOWER: + rgblight_setrgb (0xFF, 0x00, 0x00); + break; + case _PLOVER: + rgblight_setrgb (0x00, 0xFF, 0x00); + break; + case _ADJUST: + rgblight_setrgb (0x7A, 0x00, 0xFF); + break; + default: // for any other layers, or the default layer + rgblight_setrgb (0x00, 0xFF, 0xFF); + break; + } + return state; +} +``` +### `layer_state_set_*` �����ĵ� + +* ����/��: `uint32_t layer_state_set_kb(uint32_t state)` +* ����: `uint32_t layer_state_set_user(uint32_t state)` + + +��`״̬`�ǻ���bitmask, ���[���ָ���](keymap.md#���ֵIJ�״̬) + + +# ���籣������ (EEPROM) + +�����������ó��ڵı����ڼ����С���Щ���ñ����������ص�EEPROM����粻����ʧ�� ���ÿ�����`eeconfig_read_kb`��`eeconfig_read_user`��ȡ��������`eeconfig_update_kb`��`eeconfig_update_user`д�롣�������ϣ���ܹ��л��Ĺ��ܺ�����(�����л�RGB��ָʾ�����⣬�������`eeconfig_init_kb`��`eeconfig_init_user`������EEPROMĬ��ֵ�� + +��ӵIJ��ֿ����ǣ��кܶ������ͨ��EEPROM�洢�ͷ������ݣ����Ҳ�û�������ַ����ǡ�������ȷ���ġ���ÿ������ֻ��һ��˫��(���ֽ�)�ռ䡣 + +��סEEPROM����д�������ġ�����д�������ܸߣ����Dz�����ֻ������д��EEPROM�С������д��Ƶ�������MCU���������̡� + +* �����������������ӣ���ô������ϣ������ʹ��������ԣ���Ϊ���൱���ӡ� + +### ʾ��ʵ�� + +��������������������ã����Ҷ�д������ʹ�����û����֡�����һ�����ӵĺ������кܶ�����Ҫ����ʵ���ϣ���ʹ���˺ܶ����������������� + + +�����keymap.c�ļ��У������´�������������: +```c +typedef union { + uint32_t raw; + struct { + bool rgb_layer_change :1; + }; +} user_config_t; + +user_config_t user_config; +``` + +���ϴ��뽨����һ���ṹ�壬�ýṹ����Դ洢���ò�������д��EEPROM�������㽫���趨���������Ϊ�ڽṹ������Ȼ���塣Ҫ��ס`bool` (����)ֵʹ��1λ, `uint8_t`ʹ��8λ, `uint16_t`ʹ��16λ������Ի�ϴ���ʹ�ã�����˳��Ǵ����ܻ������鷳����Ϊ�ǻ�ı�д��д����ֵ�� + + `layer_state_set_*`������ʹ����`rgb_layer_change`��ʹ����`keyboard_post_init_user`��`process_record_user`������һ�С� + +����Ҫʹ��`keyboard_post_init_user����Ҫ����`eeconfig_read_user()`�������ոմ����Ľṹ�塣Ȼ������������ʹ������ṹ���������IJ����еĹ��ܡ����������� +```c +void keyboard_post_init_user(void) { + // ���ò��ּ���ľ����ʼ�� + + // ��EEPROM���û����� + user_config.raw = eeconfig_read_user(); + + // ��ʹ�ܣ�����Ĭ�ϲ� + if (user_config.rgb_layer_change) { + rgblight_enable_noeeprom(); + rgblight_sethsv_noeeprom_cyan(); + rgblight_mode_noeeprom(1); + } +} +``` +���Ϻ������ڶ�EEPROM���ú�����ʹ�ø�����������Ĭ�ϲ�RGB��ɫ��"raw"��ֵ�Ǵ����������"union"�����Ľṹ����ת�����ġ� + +```c +uint32_t layer_state_set_user(uint32_t state) { + switch (biton32(state)) { + case _RAISE: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } + break; + case _LOWER: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); } + break; + case _PLOVER: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); } + break; + case _ADJUST: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); } + break; + default: // ����������Ĭ�ϲ� + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); } + break; + } + return state; +} +``` +��������ֵʹ��ʱ��ı�RGB����ơ������������ֵ, Ϊ`process_record_user`����һ���¼������`RGB_LYR`������Ҫȷ�������ʹ��������RGB���룬ʹ�������ʾ������رգ��뽫������Ϊ�� +```c + +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case FOO: + if (record->event.pressed) { + // ����ʱ����ʲô + } else { + // �ͷ�ʱ����ʲô + } + return false; // �����˼��Ľ�һ������ + case KC_ENTER: + // �ڰ��»س�ʱ�������� + if (record->event.pressed) { + PLAY_NOTE_ARRAY(tone_qwerty); + } + return true; // ��QMK�����س�����/�ͷ��¼� + case RGB_LYR: // ������underglow��Ϊ��ָʾ��������ʹ�á� + if (record->event.pressed) { + user_config.rgb_layer_change ^= 1; // �л�״̬ + eeconfig_update_user(user_config.raw); // ��EEPROMд����״̬ + if (user_config.rgb_layer_change) { // �����״̬��ʹ�� + layer_state_set(layer_state); // ��ô���̸��²���ɫ + } + } + return false; break; + case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // �������е�RGB���� (see quantum_keycodes.h, L400 ���Բο�) + if (record->event.pressed) { //����ʧ�ܲ�ָʾ��������ı����������Ҫ�������� + if (user_config.rgb_layer_change) { // ����ʹ��ʱ + user_config.rgb_layer_change = false; // ʧ�ܣ�Ȼ�� + eeconfig_update_user(user_config.raw); // ��EEPROMд������ + } + } + return true; break; + default: + return true; // ������������ + } +} +``` +�����Ҫ����`eeconfig_init_user`���������Ե�EEPROM����ʱ������ָ��Ĭ��ֵ, �����Զ����������ǿ������EEPROM������`EEP_RST`�����[Bootmagic](feature_bootmagic.md)���������磬���Ҫ��Ĭ�����������RGB��ָʾ��������Ĭ��ֵ + +```c +void eeconfig_init_user(void) { // EEPROM�������� + user_config.raw = 0; + user_config.rgb_layer_change = true; // ������ҪĬ��ʹ�� + eeconfig_update_user(user_config.raw); // ��EEPROMд��Ĭ��ֵ + + // use the non noeeprom versions, ��Ҫ��EEPROMд����Щֵ + rgblight_enable(); // Ĭ��ʹ��RGB + rgblight_sethsv_cyan(); // Ĭ��������ɫ + rgblight_mode(1); // Ĭ�����ó��� +} +``` + +Ȼ��������ˡ�RGB��ָʾ����������������ʱ������������û�һֱ���棬��������¼��̡������ʹ������RGB���룬��ָʾ��ʧ�ܣ��������������������ˡ� + +### 'EECONFIG' �����ĵ� + +* ����/��: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`��`void eeconfig_update_kb(uint32_t val)` +* ����: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)`��`void eeconfig_update_user(uint32_t val)` + +`val` ������д��EEPROM��ֵ��`eeconfig_read_*`�������EEPROM����һ��32λ(˫��)��ֵ�� + +# �Զ������-�����ٽ�ֵ(TAPPING_TERM) +Ĭ�������,����-�����ٽ�ֵ��ȫ��ͳһ�ģ����Ҳ���ͨ�����������á����ڴ�����û���˵��ܺá���������Щ����£�����`LT`����˵������ʱ��˫���ܼ�����������������Ϊ��Щ���������ļ������װ�ס��Ϊ�˲���ÿ�����Զ�����룬�����ܿ���Ϊÿ��������`TAPPING_TERM`�� + +��ʹ��������ܵĻ�, Ҫ����`config.h`����`#define TAPPING_TERM_PER_KEY`�� + + +## `get_tapping_term`ʾ��ʵ�� + +��Ҫ�Ļ��ڼ����`TAPPING TERM`,��Ҫ��`keymap.c`�ļ��������´���: + +```c +uint16_t get_tapping_term(uint16_t keycode) { + switch (keycode) { + case SFT_T(KC_SPC): + return TAPPING_TERM + 1250; + case LT(1, KC_GRV): + return 130; + default: + return TAPPING_TERM; + } +} +``` + +### `get_tapping_term` �����ĵ� + +������ƪ����������,�������Ҫquantum�����̼���ĺ�����ֻҪ�û����������ɡ� diff --git a/docs/zh-cn/faq.md b/docs/zh-cn/faq.md new file mode 100644 index 0000000000..3d0b65c6fd --- /dev/null +++ b/docs/zh-cn/faq.md @@ -0,0 +1,6 @@ +# 常见问题 + +* [一般问题](faq_general.md) +* [构建和编译QMK](faq_build.md) +* [QMK调试和故障排除](faq_debug.md) +* [布局问题](faq_keymap.md) diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md new file mode 100644 index 0000000000..8fb449db30 --- /dev/null +++ b/docs/zh-cn/faq_build.md @@ -0,0 +1,150 @@ +# 关于构建的常见问题 + +本页所写是QMK构建的常见问题.如果你还没有进行过编译,就看一下[构建环境搭建](getting_started_build_tools.md) 和 [make的说明](getting_started_make_guide.md). + +## 如果您不能在Linux上编程 +您需要适当的权限才能操作设备。对于Linux用户, 请参阅下方有关`udev`规则的说明。如果您对`udev`有问题,解决方法是用`sudo`命令。如果您不熟悉此命令,使用`man sudo`查看其手册或[看这个网页](https://linux.die.net/man/8/sudo). + +在你的主控是ATMega32u4时,以下是使用`sudo`命令的样例: + + $ sudo dfu-programmer atmega32u4 erase --force + $ sudo dfu-programmer atmega32u4 flash your.hex + $ sudo dfu-programmer atmega32u4 reset + +或只用; + + $ sudo make <keyboard>:<keymap>:dfu + +使用`sudo`运行`make`一般来说**不**推荐,如果可能,尽量使用前一种方法之一。 + +### Linux `udev` 规则 +在Linux上,您需要适当的权限才能访问MCU。你也可以在刷新固件时使用 `sudo`,或把这些文件放到`/etc/udev/rules.d/`。 + +**/etc/udev/rules.d/50-atmel-dfu.rules:** +``` +# Atmel ATMega32U4 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666" +# Atmel USBKEY AT90USB1287 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666" +# Atmel ATMega32U2 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666" +``` + +**/etc/udev/rules.d/52-tmk-keyboard.rules:** +``` +# tmk键盘产品 https://github.com/tmk/tmk_keyboard +SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" +``` +**/etc/udev/rules.d/54-input-club-keyboard.rules:** + +``` +# Input Club keyboard bootloader +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" +``` + +### 串行设备在Linux上检测不到bootloader模式 +确保您的内核对您的设备有相应的支持。 如果你的设备是 USB ACM, 比如Pro Micro (Atmega32u4),就要加上`CONFIG_USB_ACM=y`. 其他设备可能需要`USB_SERIAL` 及其任何子选项。 + +## DFU Bootloader的未知设备 + +如果您在使用Windows来刷新键盘的时候碰到了问题,检查设备管理器。如果在键盘处于 "bootloader模式"时你看到 "未知设备",说明你可能面临设备问题。 + +重新运行MSYS2上的安装脚本或许会凑效(比如在MSYS2/WSL运行 `./util/qmk_install.sh`) 或者重新安装QMK工具箱也可能会解决你的问题。 + +如果以上方法还是短针攻疽,那您可能需要使用[Zadig Utility](https://zadig.akeo.ie/)。下载此程序, 找到设备问题, 然后选择 `WinUSB`选项, 然后点击"Reinstall driver"。完成后再试试刷新你的键盘。倘若依然徒劳无功,那就尝试所有选项直到好用为止。 + +?> 事实上没有一个驱动的最佳选择,有些选项就是和某些系统相辅相成。但libUSB和WinUSB似乎也算是这里的最佳选择了。 +如果bootloader在设备列表中没有显示,你可能要使能 "List all devices"选项在选项菜单中`Options`,然后找到有问题的bootloader设备。(译者注:在win10中可能为 查看-显示隐藏的设备) + + +## WINAVR已淘汰 +不再推荐使用WINAVR,使用可能会导致问题 +详情请见[TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99). + +## USB VID 和 PID +你可以在编辑`config.h`时使用任何你想用的ID值。实际上,使用任何可能未使用的ID都没有问题,除了有极低的与其他产品发生冲突的可能性。 + +大多数QMK主板使用`0xFEED`作为vendor ID。您应该查看其他键盘,以确保选择了唯一的Product ID。 + +也要看看这个。 +https://github.com/tmk/tmk_keyboard/issues/150 + +一也可以在下方链接购买一个唯一的VID:PID。不过个人使用似乎用不着这个。 +- http://www.obdev.at/products/vusb/license.html +- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 + +## Cortex: `cstddef: No such file or directory` +在Ubuntu 14.04上的GCC 4.8 会出现这种问题需要用这个PPA升级到4.9。 +https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded + +https://github.com/tmk/tmk_keyboard/issues/212 +https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef +https://developer.mbed.org/forum/mbed/topic/5205/ + +## `clock_prescale_set` and `clock_div_1` Not Available +你的工具链太旧了不支持MCU。比如WinAVR 20100110就不支持ATMega32u2. + +``` +Compiling C: ../../tmk_core/protocol/lufa/lufa.c +avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8 -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o +../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu': +../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set' +../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function) +../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once +../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.) +make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1 +``` + + +## AVR的BOOTLOADER_SIZE +注意Teensy2.0++ bootloader的大小是2048字节。有些Makefile注释错了。 + +``` +# Boot Section Size in *bytes* +# Teensy halfKay 512 +# Teensy++ halfKay 2048 +# Atmel DFU loader 4096 (TMK Alt Controller) +# LUFA bootloader 4096 +# USBaspLoader 2048 +OPT_DEFS += -DBOOTLOADER_SIZE=2048 +``` + +## 在MacOS上 `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` +这是brew更新的问题,导致AVR GCC依赖的符号链接被损坏。 + +解决方案是移除并重新安装所有受影响的模块。 + +``` +brew rm avr-gcc +brew rm dfu-programmer +brew rm dfu-util +brew rm gcc-arm-none-eabi +brew rm avrdude +brew install avr-gcc +brew install dfu-programmer +brew install dfu-util +brew install gcc-arm-none-eabi +brew install avrdude +``` + +### avr-gcc 8.1 和 LUFA + +如果你把avr-gcc升级到7以上你可能会遇到关于LUFA的问题。比如: + +`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'` + +那你就需要在brew中把avr-gcc回退到7。 + +``` +brew uninstall --force avr-gcc +brew install avr-gcc@8 +brew link --force avr-gcc@8 +``` + +### 我刷新了我的键盘但是键盘不工作/按键没有注册 - 而且还是ARM的 (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019) +由于EEPROM在基于ARM的芯片上的工作原理,保存的设置可能不再有效。这会影响默认层,而且*或许*在某些情况下,会使键盘不好用,我们仍在调查这些情况。重置EEPROM将解决此问题。 + +[Planck rev6键盘重置EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) 是用于强制重置EEPROM的。刷入这个文件后,再次刷入正常固件,这会将键盘恢复到_正常_工作状态。 +[Preonic rev3键盘重置EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin) + +如果以任何形式启用了bootmagic, 那么您还需要(看[Bootmagic文档](feature_bootmagic.md) 以及键盘信息,以了解如何执行此操作的详细信息). diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md new file mode 100644 index 0000000000..ca8b3fd25d --- /dev/null +++ b/docs/zh-cn/faq_debug.md @@ -0,0 +1,233 @@ +# 调试的常见问题 + +本篇详细介绍了人们在键盘故障排除时的各种常见问题。 + +# 调试控制台 + +## `hid_listen` 无法识别设备 +当设备的调试控制台未就绪时,您将看到如下内容: + +``` +Waiting for device:......... +``` + +插入设备后,*hid_listen*找到该设备,您将收到以下消息: + +``` +Waiting for new device:......................... +Listening: +``` + +如果您无法获得这条“Listening:”消息,请尝试在[Makefile]中使用 `CONSOLE_ENABLE=yes` + +在Linux这样的操作系统上,你可能需要一些权限。 +- 使用`sudo hid_listen` + +## 控制台没有返回消息 +检查: +- *hid_listen* 找到了你的设备。看前面。 +- 输入**Magic**+d打开调试。详见[Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands)。 +- 设置`debug_enable=true` ,一般存在于**matrix.c**的`matrix_init()`中。 +- 尝试使用'print'函数而不要用调试输出。详见**common/print.h**。 +- 断开其他有控制台功能的设备。 详见[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97)。 + +## Linux或UNIX这样的系统如何请求超级用户权限 +用'sudo'来执行*hid_listen*就有权限了。 +``` +$ sudo hid_listen +``` + +或者把一个文件放到规则文件夹来为TMK设备添加*udev规则*,不同系统的目录可能有所不同。 + +文件: /etc/udev/rules.d/52-tmk-keyboard.rules(在Ubuntu系统的情况下) +``` +# tmk keyboard products https://github.com/tmk/tmk_keyboard +SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" +``` + +*** + +# 其他 +## 安全注意事项 + +你应该不想要把你的键盘变成"砖头"吧,就是变成没法重写固件的那种。 +下面讲解一些参数来告诉你什么风险很大(其实也不是很大)。 + +- 假如你键盘表面没有设计重置键"RESET", 那你要进入bootloader的话就要按PCB上的RESET了。 + 按PCB上的RESET要拧开键盘底部。 +- 如果 tmk_core / common 里面的文件丢失键盘可能失灵。 +- .hex太大可能不太好; `make dfu` 会删除块,检验大小(咦?好像反了...)。 + 一但出错,刷新键盘失败的话就困在DFU出不去了。 + - 所以, 要知道大小限制。 Planck键盘上.hex文件最大大小是 is 7000h (十进制是28672) + +``` +Linking: .build/planck_rev4_cbbrowne.elf [OK] +Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK] + +Size after: + text data bss dec hex filename + 0 22396 0 22396 577c planck_rev4_cbbrowne.hex +``` + + - 上面那个文件大小是 22396/577ch,比28672/7000h小 + - 当你有一个合适的.hex文件时,你就要重试加载那个了 + - 您在键盘Makefile中的某些选项可能消耗额外内存;注意以下这几个 + BOOTMAGIC_ENABLE, MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE +- DFU 工具/不/可以写入bootloader (unless you throw in extra fruit salad of options), + 所以还是有点危险的 +- EEPROM大概有100000次循环寿命。不要总是频繁重写固件;EEPROM会玩坏的。 +## 全键无冲不好用 +首先你要在**Makefile**用如下命令编译固件`NKRO_ENABLE`。 + +全键无冲还不好用的话试着用`Magic` **N** 命令(默认是`LShift+RShift+N`)。这个命令会在**全键无冲**和**六键无冲**之间临时切换。有些情况**全键无冲**不好用你就需要使用**六键无冲**模式,尤其是在BIOS中。 + +如果你的固件使用`BOOTMAGIC_ENABLE`编译的你要用`BootMagic` **N** 命令(默认`Space+N`)打开开关。这个设置保存在EEPROM中并保存在电源循环中。 +<!--翻译问题:上面这句翻译的不贴切 --> + +https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch + + +## 指点杆需要复位电路(PS/2 鼠标支持) +如果没有复位电路,由于硬件初始化不正确,您将得到不一致的结果。查看TPM754复位电路。 + +- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447 +- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf + + +## 矩阵不可读16以上的列 +当列超过16时[matrix.h]的`read_cols()`中,用`1UL<<16`而不要用`1<<16`。 + +在C语言中`1` 是一个[int] 类型的[16 bit]值,在AVR中你不能左移大于15次。如果你使用`1<<16`的话会得到意外的零。你要用 [unsigned long]类型,比如`1UL`。 + +http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 + + +## Bootloader跳转不好用 +在**Makefile**中正确配置**Makefile**大小。如果分区大小不正确,引导加载程序可能无法从**Magic command**和**Boot Magic**加载。 +``` +# bootloader字节数: +# Atmel DFU loader(ATmega32U4) 4096 +# Atmel DFU loader(AT90USB128) 8192 +# LUFA bootloader(ATmega32U4) 4096 +# Arduino Caterina(ATmega32U4) 4096 +# USBaspLoader(ATmega***) 2048 +# Teensy halfKay(ATmega32U4) 512 +# Teensy++ halfKay(AT90USB128) 2048 +OPT_DEFS += -DBOOTLOADER_SIZE=4096 +``` +AVR引导大小是通过**BOOTSZ**熔丝位来设置的。查阅你单片机的datasheet。 +记住,datasheet用的是**Word**(2字节)表示大小和地址,TMK用的是**Byte**。 + +AVR引导部分位于闪存的末尾,如下所示(Application是应用区,Bootloader是引导区)。 +``` +byte Atmel/LUFA(ATMega32u4) byte Atmel(AT90SUB1286) +0x0000 +---------------+ 0x00000 +---------------+ + | | | | + | | | | + | Application | | Application | + | | | | + = = = = + | | 32KB-4KB | | 128KB-8KB +0x6000 +---------------+ 0x1E000 +---------------+ + | Bootloader | 4KB | Bootloader | 8KB +0x7FFF +---------------+ 0x1FFFF +---------------+ + + +byte Teensy(ATMega32u4) byte Teensy++(AT90SUB1286) +0x0000 +---------------+ 0x00000 +---------------+ + | | | | + | | | | + | Application | | Application | + | | | | + = = = = + | | 32KB-512B | | 128KB-2KB +0x7E00 +---------------+ 0x1FC00 +---------------+ + | Bootloader | 512B | Bootloader | 2KB +0x7FFF +---------------+ 0x1FFFF +---------------+ +``` + +详情请见下方issue。 +https://github.com/tmk/tmk_keyboard/issues/179 + +如果你使用TeensyUSB, 有一个[已知bug](https://github.com/qmk/qmk_firmware/issues/164)硬件重置按钮阻止软件定义重置键工作。重新插拔键盘就好了。 + +## 特殊额外键不起作用(系统,音频控制键) +你要在`rules.mk`定义`EXTRAKEY_ENABLE`在QMK中使用它们。 + +``` +EXTRAKEY_ENABLE = yes # 音频控制和系统控制 +``` + +## 睡眠唤醒不好用 + +在Windows查看设备管理器中该键盘设备属性中电源管理选项卡中的`允许此设备唤醒计算机(O)`是否勾选。同时看一眼BIOS设置。 + +在主机睡眠时按下任何键都可以唤醒了。 + +## 使用Arduino? + +**注意Arduino的针脚名字和主控芯片的不一样。** 比如, Arduino的`D0`并不是`PD0`。自己用原理图捋一下电路。 + +- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf +- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf + +Arduino Leonardo和micro使用**ATMega32U4**,该芯片TMK可用,但Arduino的bootloader会导致问题。 + + +## 在USB AVR使用PF4-7针脚? +你要置位MCUCR寄存器JTD位来将PF4-7设置为GPIO。这些针脚默认是JTAG功能。 像ATMega*U* or AT90USB*这样的MCU会受影响。 + +如果是用Teensy的话就不需要了。Tennsy自带JTAGEN位未编程来失能该功能。 +<!--翻译问题:上句可能有错,原文为:Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function. --> +代码如下。 +``` + // F接口JTAG失能。在四个周期内写入两次JTD位。 + MCUCR |= (1<<JTD); + MCUCR |= (1<<JTD); +``` +https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hbkb/matrix.c#L67 + +阅读ATMega32U4的datasheet中的**26.5.1 MCU Control Register – MCUCR**。 + + +## 为锁定键添加指示灯 +你要自制CapsLock, ScrollLock 和 NumLock指示灯?见下文。 + +http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560 + +## 为Arduino Micro/Leonardo编程 +按下重置键然后在8秒内运行下方这样的命令。 + +``` +avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0 +``` + +设备名称因系统而异。 + +http://arduino.cc/en/Main/ArduinoBoardMicro +https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867 + + +## USB 3 兼容性 +据传说有些人用USB3接口会有问题,用USB2的试试。 + + +## Mac 兼容性 +### OS X 10.11 和集线器 +https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034 + + +## 对于BIOS (UEFI)/恢复(睡眠和唤醒)/重新启动 有问题 +有人说他们的键盘在BIOS中,或许是恢复(睡眠和唤醒)后不工作. + +截止至目前,其根本原因未知,不排除与某些构建选项有关。试着在Makefile中失能`CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE`这样的选项,也试试其他的。 + +https://github.com/tmk/tmk_keyboard/issues/266 +https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 + + + +## FLIP 不工作 +### `AtLibUsbDfu.dll` 未找到 +从设备管理器中删除当前驱动程序并在设备管理器重新安装一个FLIP提供的程序。 +http://imgur.com/a/bnwzy diff --git a/docs/zh-cn/faq_general.md b/docs/zh-cn/faq_general.md new file mode 100644 index 0000000000..4949acb8c9 --- /dev/null +++ b/docs/zh-cn/faq_general.md @@ -0,0 +1,19 @@ +# �������� + +## QMK��ʲô? + +[QMK](https://github.com/qmk), �����ӻ�е����(Quantum Mechanical Keyboard)����д����һȺ��Դ������Ϊ���Ƽ��̿����Ĺ��ߡ����Ǵ�[QMK�̼�](https://github.com/qmk/qmk_firmware)��ʼ������[TMK](https://github.com/tmk/tmk_keyboard)��ħ�ķֲ档 + +### Ϊʲô������(Quantum)? + +<!-- ���� �����²ۣ��ĵ����߾�ȻҲ��֪��Ϊɶ������ --> + +## QMK��TMK��ʲô����? + +TMK�����[Jun Wako](https://github.com/tmk)��ƺ�ִ�С�QMKʼ��[Jack Humbert](https://github.com/jackhumbert)ΪPlanck���̴�����TMK�ֲ档һ��ʱ���Jack�ķֲ�ͺ�TMK��ȥ��Զ�ˣ�������2015�꣬Jack��������QMK�� + +�Ӽ����۵�������QMK��TMK����һЩ�¹��ܶ��ɵġ�������QMK��չ�˿��õļ��룬ʹ�����ܽ�һ���ḻ���� `S()`, `LCTL()`, �� `MO()`��ȫ�������[����](keycodes.md). + +�ӹ��̵�������������TMK�Լ�ά�������йٷ�֧�ֵļ��̣�ֻ�к�Сһ��������֧�֡���������ά���Ѵ��ڷֲ��Ϊ�������̴����ķֲ档Ĭ��֧�ֺ��ٵļ��룬�����û�ͨ�����������˷������֡�QMK����ͨ�����й����ֿ�������ֺͼ��̣����ǻ�������з�����������PR����ͼ���ı�֤������ά����ͬʱQMKС��Ҳ���ڱ�Ҫʱ��������� + +�����ַ����������ŵ��ȱ�㣬���Ҵ�����������ʱ��TMK��QMK֮������������ diff --git a/docs/zh-cn/faq_keymap.md b/docs/zh-cn/faq_keymap.md new file mode 100644 index 0000000000..ee8e3c06bf --- /dev/null +++ b/docs/zh-cn/faq_keymap.md @@ -0,0 +1,212 @@ +# 布局常见问题 + +本页本页包含人们经常遇到的关于布局的问题。如果你觉得没什么问题,请先看[布局概览](keymap.md)。 + +## 我能用什么键码? +看[键码](keycodes.md)你可以找到你能用的键码索引。可以的话这些链接可以连接到更广泛的文档。 + +键码实际上定义在[common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h). + +## 默认的键码什么样? + +世界上有三种标准键盘设计,分别是:ANSI, ISO, and JIS. 主要是北美用ANSI(译者注:中国很多键盘使用这个), 欧洲和非洲主要使用ISO,日本使用JIS。未提及的区域通常使用ANSI或ISO。与这些设计对应的键代码如下所示: + +<!-- 该图片的来源: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a --> + + +## 我有一些键变成了其他功能或者不工作了 + +QMK有两个功能,Bootmagic和命令行,它允许您在运行中更改键盘的行为。该功能包括但不仅限于, 交换Ctrl/Caps,关闭界面,交换Alt/Gui,交换 Backspace/Backslash,禁用所有键,以及其他的行为改变。 + +快速解决方法是插入键盘时按住`Space`+`Backspace`。该操作将重置已保存设置,让这些键回复初始功能。这招不好用的话参阅下方: + +* [Bootmagic](feature_bootmagic.md) +* [命令](feature_command.md) + +## 菜单键不好用 + +现在大多数键盘 `KC_RGUI`和`KC_RCTL`中间的键子叫做`KC_APP`。这是因为在这个键子发明之前相关标准里就已经有键叫做`MENU(菜单)`了,所以微软叫他`APP(应用)`键。 + +## `KC_SYSREQ` 不工作 +使用抓屏的键码(`KC_PSCREEN`或`KC_PSCR`)而不用`KC_SYSREQ`。组合键'Alt + Print Screen'会被当作'System request'。 + +见[issue #168](https://github.com/tmk/tmk_keyboard/issues/168)和 +* http://en.wikipedia.org/wiki/Magic_SysRq_key +* http://en.wikipedia.org/wiki/System_request + +## 电源键不工作 + +这有点让人困惑,QMK有两个"Power(电源)"键码: `KC_POWER` 在键盘/小键盘的HID使用页面中,`KC_SYSTEM_POWER` (或者叫`KC_PWR`)在用户页。 + +前者只能被macOS识别,但是后者,即`KC_SLEP`和`KC_WAKE`三大主要操作系统全都支持,所以推荐使用这两个。Windows下这些键立即生效,macOS要长按直到弹出对话框。 + +## 自动大小写锁定 +可以解决'the'问题(正常应为The)。我经常在输入'The'时不慎输入了'the'或者'THe'。自动大小写锁定可以修正此类问题。详见下方链接。 +https://github.com/tmk/tmk_keyboard/issues/67 + +## 修改 键/层 卡住 +除非正确配置层切换,否则修改键或层可能会卡住。 +对于修改键和图层操作,必须把`KC_TRANS`放到目标层的相同位置,用于注销修改键或在释放事件时返回到上一层。 +* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching +* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604 +* https://github.com/tmk/tmk_keyboard/issues/248 + + +## 机械自锁开关支持Mechanical Lock Switch Support + +本功能用于*机械自锁开关*比如[this Alps one](http://deskthority.net/wiki/Alps_SKCL_Lock)。你可以通过向`config.h`添加以下宏来使能该功能: + +``` +#define LOCKING_SUPPORT_ENABLE +#define LOCKING_RESYNC_ENABLE +``` + +在使能该功能后,要在键盘中使用`KC_LCAP`, `KC_LNUM` 和 `KC_LSCR`这三个键码。 + +远古机械键盘偶尔会有自锁机械开关,现在几乎没有了。***大多数情况下你不需要使用该功能,且要使用`KC_CAPS`, `KC_NLCK`和`KC_SLCK`这三个键码。*** + +## 输入ASCII之外的特殊字符比如Cédille 'Ç' +没有在所有系统中输入这个的通用方法。你要定义针对你的特定操作系统或布局的**宏**。 + +比如看这个**宏**代码的文章。 + +http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620 +<!--翻译问题:下方维基百科链接应全部替换为中文链接,暂未找到全部--> +在**Windows**上,可以用`AltGr`键或**Alt码**。 +* http://en.wikipedia.org/wiki/AltGr_key +* https://zh.wikipedia.org/wiki/Alt%E7%A0%81 + +在**Mac OS**定义`Option`键组合。 +* https://zh.wikipedia.org/wiki/Option%E9%94%AE#%E6%9B%BF%E4%BB%A3%E9%94%AE%E7%9B%98%E8%BE%93%E5%85%A5 + +在**Xorg**可以改用`compose`键。 +* http://en.wikipedia.org/wiki/Compose_key + +下方链接查看**Unicode**输入。 +* http://en.wikipedia.org/wiki/Unicode_input + +## macOS上的`Fn` + +不像大多数FN键,苹果上那个有自己的键码...呃,基本上算吧。 他取缔了基本6键无冲HID报告的第六个键码 -- 所以苹果键盘其实是5键无冲的。 + +技术上说QMK可以发送这个键。但是,这样做需要修改报告格式以添加FN键的状态。这还不是最糟糕的,你的键盘的VID和PID和真的苹果键盘不一样的话还不会被识别。 +QMK官方支持这个会被律师函的,所以就当我没说过。 + +详见[issue#2179](https://github.com/qmk/qmk_firmware/issues/2179)。 + + +## Mac OSX的媒体控制键 +#### KC_MNXT 和 KC_MPRV 在Mac上不好用 +使用 `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) 和 `KC_MRWD`(`KC_MEDIA_REWIND`),不要用 `KC_MNXT` 和 `KC_MPRV`. +详见 https://github.com/tmk/tmk_keyboard/issues/195 + + +## Mac OSX中支持那些键? +你可以从此源码中获知在OSX中支持哪些键码 + +`usb_2_adb_keymap` 阵列映射 键盘/小键盘 页用于ADB扫描码(OSX内部键码). + +https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c + +`IOHIDConsumer::dispatchConsumerEvent`会处理用户页面用法。 +<!--翻译问题:上面那两句翻译的不好-> handles Consumer page usages. --> +https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp + + +## Mac OSX中的JIS键 +岛国特别键比如`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)`OSX是不是别的。You can use **Seil** to enable those keys, try following options. +<!--翻译问题:以上“岛国特别键”没有任何地域歧视的意思 --> +* 在电脑键盘上使能NFER键 +* 在电脑键盘上使能XFER键 +* 在电脑键盘上使能KATAKAN键 + +https://pqrs.org/osx/karabiner/seil.html + + +## RN-42蓝牙模块与Karabiner不能有效协同工作 +Karabiner - Mac OSX的改键软件 - 默认RN-42模块是不会被响应的。想要Karabiner和你的键盘协同工作你要使能此选项: +https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237 + +此问题详见下方链接。 +https://github.com/tmk/tmk_keyboard/issues/213 +https://github.com/tekezo/Karabiner/issues/403 + + +## Esc 和 <code>`</code> 双功能键 + +请见[Grave Escape](feature_grave_esc.md)功能。 + +## 右侧双角色修改键(诸如Shift、Alt等有修改其他键作用的键)变箭头键 +右侧修改键单击时会变为箭头键,长按就还是修改键。在TMK中双角色键称之为**TAP**. +``` + +#include "keymap_common.h" + + +/* 用TMK双角色键功能实现右侧修改键改箭头键 + * + * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role + * https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys + */ +const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + /* 0: qwerty */ + [0] = LAYOUT( \ + ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \ + TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \ + LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \ + LSFT,NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,FN0, ESC, \ + FN4, LGUI,LALT, SPC, APP, FN2, FN1, FN3), + [1] = LAYOUT( \ + GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \ + TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\ + TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ + TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \ + TRNS,TRNS,TRNS, TRNS, TRNS,FN7, FN6, FN8), +}; + +const uint16_t PROGMEM fn_actions[] = { + [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP), + [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN), + [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT), + [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT), + [4] = ACTION_LAYER_MOMENTARY(1), + [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP), + [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN), + [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME), + [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END), +}; + +``` + +双角色键说明: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys + + +## Mac OSX的弹出键 +`KC_EJCT` 键码在OSX可以使用 https://github.com/tmk/tmk_keyboard/issues/250 +似乎Windows10会忽略该键码,Linux/Xorg可以识别该键码但默认不映射。 + +目前尚不清楚如何在真正的苹果键盘按出弹出键。HHKB使用`F20`用于弹出键(`Fn+f`),该功能在MAC模式有效但不保证与苹果弹出键码相符。 + + +## `action_util.c`中的 `weak_mods`和`real_mods`是什么 +___待改善___ + +real_mods 用于保存实际(物理)修改键的实际状态。 +weak_mods 用于保存虚拟或临时修改键,它将不会影响实际修改键。 + +以按下左侧Shift键然后输入ACTION_MODS_KEY(LSHIFT, KC_A)为例, + +在weak_mods时, +* (1) 按下不抬起左Shift: real_mods |= MOD_BIT(LSHIFT) +* (2) 按 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT) +* (3) 抬起 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT) +real_mods 还是保持在修改状态。 + +在没有weak_mods时, +* (1) 按下不抬起左Shift: real_mods |= MOD_BIT(LSHIFT) +* (2) 按 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT) +* (3) 抬起 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT) +此时real_mods失去‘实际左Shift’的状态。 + +weak_mods和real_mods现已全部加入键盘数据包发送豪华套餐。 +https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57 diff --git a/docs/zh-cn/getting_started_getting_help.md b/docs/zh-cn/getting_started_getting_help.md new file mode 100644 index 0000000000..cf770a7708 --- /dev/null +++ b/docs/zh-cn/getting_started_getting_help.md @@ -0,0 +1,15 @@ +# 获得帮助 + +有很多方法来获得关于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).当您的问题需要长期讨论或调试时,这尤其方便。 diff --git a/docs/zh-cn/getting_started_github.md b/docs/zh-cn/getting_started_github.md new file mode 100644 index 0000000000..0400eea643 --- /dev/null +++ b/docs/zh-cn/getting_started_github.md @@ -0,0 +1,59 @@ +# 如何在QMK中使用Github + +Github can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK. + +?> 本教程假设您已安装GitHub,并且您喜欢使用命令行工作。 + +首先 [Github上的QMK页面](https://github.com/qmk/qmk_firmware), 您能看到右上方有个按钮写着"Fork": + + + +如果你是某组织成员,你将需要选择分叉到哪个账户。一般情况下, 你是想要分叉到你的私人账户下。当你完成分叉 (有时需要等一会), 点击"Clone or Download" 按钮: + +!从Github下载](http://i.imgur.com/N1NYcSz.jpg) + +你要选择 "HTTPS", 然后选择链接复制: + + + +然后,在命令行输入`git clone `,然后粘贴你的链接: + +``` +user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git +Cloning into 'qmk_firmware'... +remote: Counting objects: 46625, done. +remote: Compressing objects: 100% (2/2), done. +remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623 +Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done. +Resolving deltas: 100% (29362/29362), done. +Checking out files: 100% (2799/2799), done. +``` + +现在你本地计算机有QMK的分叉了,你可以添加你的布局了, 为你的键盘编译并刷新固件吧。如果你觉得你的修改很不错, 你可以添加,提交,然后想你的分叉推出(pull)你的改变,像这样: + +``` +user@computer:~$ git add . +user@computer:~$ git commit -m "adding my keymap" +[master cccb1608] adding my keymap + 1 file changed, 1 insertion(+) + create mode 100644 keyboards/planck/keymaps/mine/keymap.c +user@computer:~$ git push +Counting objects: 1, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (1/1), done. +Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done. +Total 1 (delta 1), reused 0 (delta 0) +remote: Resolving deltas: 100% (1/1), completed with 1 local objects. +To https://github.com/whoeveryouare/qmk_firmware.git + + 20043e64...7da94ac5 master -> master +``` + +现在你的改动已经在你Github上的分支中了 - 如果你回到这 (`https://github.com/你的GitHub账户名/qmk_firmware`) ,你可以点击下方所示按钮创建 "New Pull Request": + + + +现在你可以看到你所做的一切 - 如果看起来不错, 就可以点击 "Create Pull Request"定稿了: + + + +提交后,我们会开跟你说你的改动,要求您进行更改, 并最终接受您的更改!感谢您为QMK做的贡献 :) diff --git a/docs/zh-cn/newbs.md b/docs/zh-cn/newbs.md new file mode 100644 index 0000000000..8c36b0d24b --- /dev/null +++ b/docs/zh-cn/newbs.md @@ -0,0 +1,23 @@ +# QMK菜鸟教程 + +QMK是为你机械硬盘设计的的一个强大的开源固件。使用QMK可以很简单的让你的定制键盘变得强大。看完这篇文章,无论你是菜鸟还是大佬,都可以顺利的使用QMK来定制键盘。 + +你是否为不知道你的键盘能不能运行QMK而苦恼? 如果你的机械键盘是你自己做的,那么这把键盘一般可以运行QMK。我们提供了[一大堆自制键盘](http://qmk.fm/keyboards/), 所以即便你的键盘不能运行QMK你也很容易能找到满足你需求的键盘。 + +## 概览 + +这个教程有7个主要部分: + +* [新手上路](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) + +这份教程旨在帮助没有固件构建经验的人,也是根据该目的做出选择和建议。这些程序有很多替代方法,大部分替代我们都支持。如果你对完成一个任务有疑问,可以[向我们寻求帮助](getting_started_getting_help.md). + +## 其他资源 + +* [Thomas Baart的 QMK基础博客](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 这是一个用户创建的博客,涵盖了为新手准备的使用QMK的基础知识。 diff --git a/docs/zh-cn/reference_glossary.md b/docs/zh-cn/reference_glossary.md new file mode 100644 index 0000000000..7b9adcc2a7 --- /dev/null +++ b/docs/zh-cn/reference_glossary.md @@ -0,0 +1,170 @@ +# QMK术语表 + +## ARM +多家公司生产的32位单片机系列,例如Atmel, Cypress, Kinetis, NXP, ST, 和 TI等公司。 + +## AVR +[Atmel](http://www.microchip.com/)公司的单片机系列。 AVR是TMK的初始支持平台。 + +## AZERTY +Français (法国)标准键盘布局。用键盘的前六个字母命名。 + +## Backlight(背光) +键盘上照明的通称。背光通常是一组LED灯,通过键帽或者按轴发光,但也不总是这样。 + +## Bluetooth(蓝牙) +一种短距离点对点无线协议。许多多无线键盘使用此协议。 + +## Bootloader(引导加载程序) +一种写到你单片机的保护区的特殊的程序,该程序可以使单片机升级自己的固件,通常是通过USB来升级。 + +## Bootmagic(热改键) +允许各种键盘行为动态变化的功能,如交换或禁用常用键。 + +## C +一种适用于系统代码的低级编程语言。大多数qmk代码是用C编写的。 + +## Colemak +一种流行的键盘布局。 + +## Compile(编译) +把人可读的代码转换成你的单片机可以运行的机器代码的过程。 + +## Dvorak +一个由August Dvorak博士在20世纪30年代创建的布局。Dvorak简化键盘(Dvorak Simplified Keyboard)的缩写。 + +## Dynamic Macro(动态宏) +一种记录在键盘上的宏,当键盘拔出或计算机重新启动时,宏将丢失。 + +* [动态宏文档](feature_dynamic_macros.md) + +## Eclipse +是一种受C语言开发者追捧的集成开发环境(IDE)。 + +* [Eclipse安装说明](eclipse.md) + +## Firmware(固件) +用来控制单片机的软件。 + +## FLIP +爱特梅尔(Atmel)提供的AVR器件刷写软件。我们一般推荐 [QMK刷写工具](https://github.com/qmk/qmk_flasher),但是对于一些高级用例,需要FLIP。 + +## git +命令行版本控制软件 + +## GitHub +负责大多数QMK项目的网站。它是Git、问题跟踪和其他帮助我们运行qmk的功能的集成平台。 + +## ISP(在系统编程) +在系统编程(In-system programming), 使用外部硬件和JTAG管脚对AVR芯片进行编程的一种方法。 + +## hid_listen +从键盘接收调试消息的接口。 您可以使用[QMK Flasher](https://github.com/qmk/qmk_flasher)或[PJRC's hid_listen](https://www.pjrc.com/teensy/hid_listen.html)查看这些消息 + +## Keycode(键码) +表示特定键的2字节数据。`0x00`-`0xFF`用于[基本键码](keycodes_basic.md)而`0x100`-`0xFFFF`用于[量子键码](quantum_keycodes.md). + +## Key Down +一个键按下尚未抬起时触发的事件。 + +## Key Up +一个键抬起时触发的事件。 + +## Keymap(键映射) +映射到物理键盘布局的一组键码,在按键和按键释放时进行处理。有时翻译为布局,意为软件上表示的布局,即映射。 + +## Layer(层) +为了让一个键实现多个功能的抽象结构。最高活动层有限。 + +## Leader Key(前导键、设置菜单键) +本功能允许您点击前导键,然后按顺序按1-3个键子来激活按键或其他量子功能。 + +* [前导键文档](feature_leader_key.md) + +## LED +发光二极管,键盘上最常用的指示灯装置。 + +## Make +用于编译所有源文件的软件包。可以使用`make`命令和其他参数来编译你的固件。 + +## Matrix(矩阵) +一种由列和行组成的接线模式,使单片机能够用较少的引脚检测按键。矩阵通常包含二极管,以达到全键无冲。 + +## Macro(宏) +本功能可以在敲击单个键后发送多个按键事件(hid报告)。 + +* [宏文档](feature_macros.md) + +## MCU(单片机、微控制单元) +微控制单元,键盘的处理器。 + +## Modifier(修改键、修饰键、功能键) +按住该键将会改变其他键的功能,修饰键包括 Ctrl, Alt, 和 Shift。 + +## Mousekeys(鼠标键) +本功能在您敲击键盘时会控制鼠标光标。 + +* [鼠标键文档](feature_mouse_keys.md) + +## N-Key Rollover (NKRO、全键无冲) +一种术语,适用于能够同时报告任意数量按键的键盘。 + +## Oneshot Modifier(粘滞键) +一种能让你的功能键一直保持按下,直到你按下其他键的功能。它叫做粘滞键或叫做粘连键,该功能由软件实现而非机械结构。 + +## ProMicro +一种低成本AVR开发板。这种板子很容易在购物网站找到(价格不到20RMB),但是据说刷写pro micro有点令人抓狂。 + +## Pull Request(拉请求、PR) +向QMK请求提交代码。我们鼓励所有用户提交你们自己的键盘的代码。 + +## QWERTY +标准英文键盘,通常也用于其他语言,例如中文。是用键盘前6个字母命名的。 + +## QWERTZ +标准Deutsche(德语)键盘布局。使用前6个字母明名。 + +## Rollover(允许翻转、无冲形式) +该术语表示在一个键已按下时按下另一个键。形式包括2KRO(双键无冲),6KRO(6键无冲),和NKRO(全键无冲),无冲表示可同时按下而不产生冲突的键的数量。 + +## Scancode(扫描码) +HID报告中的一个1字节的数字,表示一个键子。这些数字在下列文档中[HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf)该文档发布于[USB-IF](http://www.usb.org/)。 + +## Space Cadet键盘的shift键 +一种特使的shift设置,能让你通过敲击左或右shift一次或多次键入不同的括号。 + +* [Space Cadet键盘文档](feature_space_cadet.md) + +## Tap(敲击、单击) +按下并释放一个键。在某些情况下您需要区分键按下和键抬起,但是单击把两个事件都包括了。 + +## Tap Dance(多击键) +本功能允许向同一个键子分配多个键码,并根据按键次数区分。 + +* [多击键文档](feature_tap_dance.md) + +## Teensy +一种低成本AVR开发板<!--译者吐槽:我怎么感觉成本不低。好吧,我穷。 -->,通常用于手工连线键盘。这个teensy是有点小贵但是halfkay bootloader会让它刷写十分简单,所以也很常用。 + +## Underlight(背光) +用于照亮电路板底面的LED的总称。这些LED通常从印刷电路板的底部向键盘所在的表面发光。 + +## Unicode +在较大的计算机世界中,Unicode是一组编码方案,用于表示任何语言中的字符。 与qmk相关的是,它意味着使用各种操作系统方案来发送Unicode代码点,而不是扫描码。 + +* [Unicode文档](feature_unicode.md) + +## Unit Testing(单元测试) +针对qmk的自动运行测试框架。单元测试帮助我们确信我们的更改不会破坏任何东西。 + +* [单元测试文档](unit_testing.md) + +## USB +通用串行总线,键盘最常见的有线接口。 + +## USB 主机 (或简易主机) +USB诸暨市你的电脑,或者你的键盘所插的任何设备。 + +# 并没有找到你想找到的术语? + +[建立一个issue](https://github.com/qmk/qmk_firmware/issues) ,想好你的问题,或许你所问的术语就会添加到这里。创建一个PR帮我们添加需要添加的术语当然坠吼了:) |
