From 62ba66d61821fec6a5ad3bdccdf738e15e082461 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Fri, 10 May 2019 18:55:02 -0500 Subject: Cleanup/rgb matrix (#5811) * clean up rgb matrix extern usage Moved rgb matrix boiler plate into macros Rebased onto typing heatmap pr * Fixing the reversed frame buffer access in digital rain * Fixing digital rain & typing heatmap if keyreactive effects are not enabled * Apply suggestions from code review Co-Authored-By: Drashna Jaelre * Adding parenthesizes to DRIVER_LED_TOTAL where necessary * Updated docs * added notes about parentheses --- docs/feature_rgb_matrix.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 1e43414676..e29433a4bf 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -30,9 +30,11 @@ Configure the hardware via your `config.h`: #define DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 25 #define DRIVER_2_LED_TOTAL 24 -#define DRIVER_LED_TOTAL DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL +#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` +!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. + Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations. Define these arrays listing all the LEDs in your `.c`: -- cgit v1.2.3 From fd23a0e909c8478f3d9103bce410548af2496f92 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Fri, 10 May 2019 21:56:16 -0500 Subject: RGB Matrix Effects: Cycle Out to In & Cycle Out to In Dual (#5812) --- docs/feature_rgb_matrix.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index e29433a4bf..8347660dfe 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -197,6 +197,8 @@ enum rgb_matrix_effects { RGB_MATRIX_CYCLE_ALL, // Full keyboard solid hue cycling through full gradient RGB_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right RGB_MATRIX_CYCLE_UP_DOWN, // Full gradient scrolling top to bottom + RGB_MATRIX_CYCLE_OUT_IN, // Full gradient scrolling out to in + RGB_MATRIX_CYCLE_OUT_IN_DUAL, // Full dual gradients scrolling out to in RGB_MATRIX_RAINBOW_MOVING_CHEVRON, // Full gradent Chevron shapped scrolling left to right RGB_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard RGB_MATRIX_RAINBOW_BEACON, // Full tighter gradient spinning around center of keyboard @@ -236,6 +238,8 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |`#define DISABLE_RGB_MATRIX_CYCLE_ALL` |Disables `RGB_MATRIX_CYCLE_ALL` | |`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT` | |`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Disables `RGB_MATRIX_CYCLE_UP_DOWN` | +|`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN` |Disables `RGB_MATRIX_CYCLE_OUT_IN` | +|`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Disables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` | |`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` | |`#define DISABLE_RGB_MATRIX_DUAL_BEACON` |Disables `RGB_MATRIX_DUAL_BEACON` | |`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON` |Disables `RGB_MATRIX_RAINBOW_BEACON` | -- cgit v1.2.3 From 7871a465d36d11c4f9216a9e862104e0e770c6f4 Mon Sep 17 00:00:00 2001 From: ymzcdg <49898694+ymzcdg@users.noreply.github.com> Date: Sun, 12 May 2019 00:22:16 +0800 Subject: translate docs into Mandarin Chinese (#5807) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * translate newbs.md into Madarin Chinese translate newbs.md into Madarin Chinese * translate docs into Mandarin Chinese translate getting_started_github.md into Mandarin Chinese * translate getting_started_getting_help.md into Mandarin Chinese translate getting_started_getting_help.md into Mandarin Chinese * contributing.md to Chinese Personify QMK as a girl named Q酱 . It can make more developer read this document and contribute QMK. * getting_started_introduction.md to Chinese getting_started_introduction.md to Chinese * faq.md to Chinese faq.md to Chinese * crlf2lf getting_started_introduction.md ending line fix getting_started_introduction.md * crlf2lf contributing.md crlf2lf contributing.md --- docs/zh-cn/contributing.md | 205 +++++++++++++++++++++++++++++ docs/zh-cn/faq.md | 6 + docs/zh-cn/getting_started_getting_help.md | 15 +++ docs/zh-cn/getting_started_github.md | 59 +++++++++ docs/zh-cn/newbs.md | 23 ++++ 5 files changed, 308 insertions(+) create mode 100644 docs/zh-cn/contributing.md create mode 100644 docs/zh-cn/faq.md create mode 100644 docs/zh-cn/getting_started_getting_help.md create mode 100644 docs/zh-cn/getting_started_github.md create mode 100644 docs/zh-cn/newbs.md (limited to 'docs') 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酱。 + + + +# 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///.[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/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/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": + +![从Github上分叉](http://i.imgur.com/8Toomz4.jpg) + +如果你是某组织成员，你将需要选择分叉到哪个账户。一般情况下, 你是想要分叉到你的私人账户下。当你完成分叉 (有时需要等一会), 点击"Clone or Download" 按钮: + +!从Github下载](http://i.imgur.com/N1NYcSz.jpg) + +你要选择 "HTTPS", 然后选择链接复制: + +![HTTPS链接](http://i.imgur.com/eGO0ohO.jpg) + +然后，在命令行输入`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": + +![新的 Pull Request](http://i.imgur.com/DxMHpJ8.jpg) + +现在你可以看到你所做的一切 - 如果看起来不错, 就可以点击 "Create Pull Request"定稿了: + +![创建Pull Request](http://i.imgur.com/Ojydlaj.jpg) + +提交后,我们会开跟你说你的改动,要求您进行更改, 并最终接受您的更改!感谢您为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的基础知识。 -- cgit v1.2.3 From c6184d2e7ed9695c22635431394e501b1d5e6271 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Sun, 12 May 2019 00:20:14 -0500 Subject: Added check for event pressed to clear space cadet (#5839) * Added check for pressed to clear space cadet * Found some docs to update * Update docs/quantum_keycodes.md Co-Authored-By: fauxpark * Changes from PR --- docs/feature_space_cadet.md | 10 +++++----- docs/keycodes.md | 5 +++++ docs/quantum_keycodes.md | 7 ++++++- 3 files changed, 16 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/feature_space_cadet.md b/docs/feature_space_cadet.md index 5c375c5184..075578522e 100644 --- a/docs/feature_space_cadet.md +++ b/docs/feature_space_cadet.md @@ -20,7 +20,7 @@ Firstly, in your keymap, do one of the following: |`KC_RCPC` |Right Control when held, `)` when tapped | |`KC_LAPO` |Left Alt when held, `(` when tapped | |`KC_RAPC` |Right Alt when held, `)` when tapped | -|`KC_SFTENT`|Right Shift when held, `Enter` when tapped | +|`KC_SFTENT`|Right Shift when held, Enter when tapped | ## Caveats @@ -38,10 +38,10 @@ By default Space Cadet assumes a US ANSI layout, but if your layout uses differe |----------------|-------------------------------|---------------------------------------------------------------------------------| |`LSPO_KEYS` |`KC_LSFT, LSPO_MOD, LSPO_KEY` |Send `KC_LSFT` when held, the mod and key defined by `LSPO_MOD` and `LSPO_KEY`. | |`RSPC_KEYS` |`KC_RSFT, RSPC_MOD, RSPC_KEY` |Send `KC_RSFT` when held, the mod and key defined by `RSPC_MOD` and `RSPC_KEY`. | -|`LCPO_KEYS` |`KC_LCTL, KC_LCTL, KC_9` |Send `KC_LCTL` when held, the mod `KC_LCTL` with the key `KC_9` when tapped. | -|`RCPC_KEYS` |`KC_RCTL, KC_RCTL, KC_0` |Send `KC_RCTL` when held, the mod `KC_RCTL` with the key `KC_0` when tapped. | -|`LAPO_KEYS` |`KC_LALT, KC_LALT, KC_9` |Send `KC_LALT` when held, the mod `KC_LALT` with the key `KC_9` when tapped. | -|`RAPC_KEYS` |`KC_RALT, KC_RALT, KC_0` |Send `KC_RALT` when held, the mod `KC_RALT` with the key `KC_0` when tapped. | +|`LCPO_KEYS` |`KC_LCTL, KC_LSFT, KC_9` |Send `KC_LCTL` when held, the mod `KC_LSFT` with the key `KC_9` when tapped. | +|`RCPC_KEYS` |`KC_RCTL, KC_RSFT, KC_0` |Send `KC_RCTL` when held, the mod `KC_RSFT` with the key `KC_0` when tapped. | +|`LAPO_KEYS` |`KC_LALT, KC_LSFT, KC_9` |Send `KC_LALT` when held, the mod `KC_LSFT` with the key `KC_9` when tapped. | +|`RAPC_KEYS` |`KC_RALT, KC_RSFT, KC_0` |Send `KC_RALT` when held, the mod `KC_RSFT` with the key `KC_0` when tapped. | |`SFTENT_KEYS` |`KC_RSFT, KC_TRNS, SFTENT_KEY` |Send `KC_RSFT` when held, no mod with the key `SFTENT_KEY` when tapped. | diff --git a/docs/keycodes.md b/docs/keycodes.md index c0e6aa5c63..e9cfd34252 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -216,6 +216,11 @@ This is a reference only. Each group of keys links to the page documenting their |`KC_GESC` |`GRAVE_ESC`|Escape when tapped, ` when pressed with Shift or GUI| |`KC_LSPO` | |Left Shift when held, `(` when tapped | |`KC_RSPC` | |Right Shift when held, `)` when tapped | +|`KC_LCPO` | |Left Control when held, `(` when tapped | +|`KC_RCPC` | |Right Control when held, `)` when tapped | +|`KC_LAPO` | |Left Alt when held, `(` when tapped | +|`KC_RAPC` | |Right Alt when held, `)` when tapped | +|`KC_SFTENT` | |Right Shift when held, Enter when tapped | |`KC_LEAD` | |The [Leader key](feature_leader_key.md) | |`KC_LOCK` | |The [Lock key](feature_key_lock.md) | |`FUNC(n)` |`F(n)` |Call `fn_action(n)` (deprecated) | diff --git a/docs/quantum_keycodes.md b/docs/quantum_keycodes.md index 90192e6324..a2ba34c32d 100644 --- a/docs/quantum_keycodes.md +++ b/docs/quantum_keycodes.md @@ -1,6 +1,6 @@ # Quantum Keycodes -Quantum keycodes allow for easier customisation of your keymap than the basic ones provide, without having to define custom actions. +Quantum keycodes allow for easier customization of your keymap than the basic ones provide, without having to define custom actions. All keycodes within quantum are numbers between `0x0000` and `0xFFFF`. Within your `keymap.c` it may look like you have functions and other special cases, but ultimately the C preprocessor will translate those into a single 4 byte integer. QMK has reserved `0x0000` through `0x00FF` for standard keycodes. These are keycodes such as `KC_A`, `KC_1`, and `KC_LCTL`, which are basic keys defined in the USB HID specification. @@ -16,6 +16,11 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are |`KC_GESC` |`GRAVE_ESC`|Escape when tapped, ` when pressed with Shift or GUI| |`KC_LSPO` | |Left Shift when held, `(` when tapped | |`KC_RSPC` | |Right Shift when held, `)` when tapped | +|`KC_LCPO` | |Left Control when held, `(` when tapped | +|`KC_RCPC` | |Right Control when held, `)` when tapped | +|`KC_LAPO` | |Left Alt when held, `(` when tapped | +|`KC_RAPC` | |Right Alt when held, `)` when tapped | +|`KC_SFTENT` | |Right Shift when held, Enter when tapped | |`KC_LEAD` | |The [Leader key](feature_leader_key.md) | |`KC_LOCK` | |The [Lock key](feature_key_lock.md) | |`FUNC(n)` |`F(n)` |Call `fn_action(n)` (deprecated) | -- cgit v1.2.3 From 670a9b7f83dacf2b0e9fb42756935a77598c6677 Mon Sep 17 00:00:00 2001 From: Takeshi ISHII <2170248+mtei@users.noreply.github.com> Date: Thu, 16 May 2019 13:11:28 +0900 Subject: Add effect range to rgblight.c (#5856) * add rgblight_set_effect_range() * implement effect range * Arrange the order of function list in rgblight.h . * update docs/feature_rgblight.md * fix RGBLIGHT_RAINBOW_SWIRL_RANGE default value * add example code about Utility Functions * add example code about direct operation functions * When RGBLIGHT_SPLIT is defined, the following function has no meaning and is invalidated. * rgblight_setrgb_master(r, g, b) * rgblight_setrgb_slave(r, g, b) * rgblight_sethsv_master(h, s, v) * rgblight_sethsv_slave(h, s, v) * add temporary test code for rgblight_set_effect_range * fix rgblight_effect_knight() bug * Test End. Revert "add temporary test code for rgblight_set_effect_range" This reverts commit 5680cddd012d68b2db75a532862a7fef250f8973. --- docs/feature_rgblight.md | 134 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 96 insertions(+), 38 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 1e0ce91473..be4ddfa729 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -129,7 +129,7 @@ The following options are used to tweak the various animations: |`RGBLIGHT_EFFECT_KNIGHT_LED_NUM` |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel | |`RGBLIGHT_EFFECT_KNIGHT_LENGTH` |`3` |The number of LEDs to light up for the "Knight" animation | |`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by | -|`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`360` |Range adjustment for the rainbow swirl effect to get different swirls | +|`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls | |`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation | ### Example Usage to Reduce Memory Footprint @@ -176,44 +176,100 @@ const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64}; If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include: -|Function |Description | -|--------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`rgblight_enable()` |Turn LEDs on, based on their previous state | -|`rgblight_enable_noeeprom()` |Turn LEDs on, based on their previous state (not written to EEPROM) | -|`rgblight_disable()` |Turn LEDs off | -|`rgblight_disable_noeeprom()` |Turn LEDs off (not written to EEPROM) | -|`rgblight_mode(x)` |Set the mode, if RGB animations are enabled | -|`rgblight_mode_noeeprom(x)` |Set the mode, if RGB animations are enabled (not written to EEPROM) | -|`rgblight_setrgb(r, g, b)` |Set all LEDs to the given RGB value where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | -|`rgblight_setrgb_at(r, g, b, led)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `led` is between 0 and `RGBLED_NUM` (not written to EEPROM) | +### Utility Functions +|Function |Description | +|--------------------------------------------|-------------------------------------------------------------------| +|`sethsv(hue, sat, val, ledbuf)` |Set ledbuf to the given HSV value | +|`sethsv_raw(hue, sat, val, ledbuf)` |Set ledbuf to the given HSV value without RGBLIGHT_LIMIT_VAL check | +|`setrgb(r, g, b, ledbuf)` |Set ledbuf to the given RGB value where `r`/`g`/`b` | + +### Low level Functions +|Function |Description | +|--------------------------------------------|-------------------------------------------| +|`rgblight_set()` |Flash out led buffers to LEDs | +|`rgblight_set_clipping_range(pos, num)` |Set clipping Range. see [Clipping Range](#clipping-range) | + +Example: +```c +sethsv(HSV_WHITE, (LED_TYPE *)&led[0]); // led 0 +sethsv(HSV_RED, (LED_TYPE *)&led[1]); // led 1 +sethsv(HSV_GREEN, (LED_TYPE *)&led[2]); // led 2 +rgblight_set(); // Utility functions do not call rgblight_set() automatically, so they need to be called explicitly. +``` + +### Effects and Animations Functions +#### effect range setting +|Function |Description | +|--------------------------------------------|------------------| +|`rgblight_set_effect_range(pos, num)` |Set Effects Range | + +#### direct operation +|Function |Description | +|--------------------------------------------|-------------| +|`rgblight_setrgb_at(r, g, b, index)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `index` is between 0 and `RGBLED_NUM` (not written to EEPROM) | +|`rgblight_sethsv_at(h, s, v, index)` |Set a single LED to the given HSV value, where `h`/`s`/`v` are between 0 and 255, and `index` is between 0 and `RGBLED_NUM` (not written to EEPROM) | |`rgblight_setrgb_range(r, g, b, start, end)`|Set a continuous range of LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `start`(included) and `stop`(excluded) are between 0 and `RGBLED_NUM` (not written to EEPROM)| -|`rgblight_setrgb_master(r, g, b)` |Set the LEDs on the master side to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | -|`rgblight_setrgb_slave(r, g, b)` |Set the LEDs on the slave side to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | -|`rgblight_sethsv(h, s, v)` |Set all LEDs to the given HSV value where `h` is between 0 and 360 and `s`/`v` are between 0 and 255 | -|`rgblight_sethsv_noeeprom(h, s, v)` |Set all LEDs to the given HSV value where `h` is between 0 and 360 and `s`/`v` are between 0 and 255 (not written to EEPROM) | -|`rgblight_sethsv_at(h, s, v, led)` |Set a single LED to the given HSV value, where `h` is between 0 and 360, `s`/`v` are between 0 and 255, and `led` is between 0 and `RGBLED_NUM` (not written to EEPROM)| -|`rgblight_sethsv_range(h, s, v, start, end)`|Set a continuous range of LEDs to the given HSV value, where `h` is between 0 and 360, `s`/`v` are between 0 and 255, and `start`(included) and `stop`(excluded) are between 0 and `RGBLED_NUM` (not written to EEPROM)| -|`rgblight_sethsv_master(h, s, v)` |Set the LEDs on the master side to the given HSV value, where `h` is between 0 and 360, `s`/`v` are between 0 and 255 (not written to EEPROM) | -|`rgblight_sethsv_slave(h, s, v)` |Set the LEDs on the slave side to the given HSV value, where `h` is between 0 and 360, `s`/`v` are between 0 and 255 (not written to EEPROM) | -|`rgblight_toggle()` |Toggle all LEDs between on and off | -|`rgblight_toggle_noeeprom()` |Toggle all LEDs between on and off (not written to EEPROM) | -|`rgblight_step()` |Change the mode to the next RGB animation in the list of enabled RGB animations | -|`rgblight_step_noeeprom()` |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) | -|`rgblight_step_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations | -|`rgblight_step_reverse_noeeprom()` |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) | -|`rgblight_increase_hue()` |Increase the hue for all LEDs. This wraps around at maximum hue | -|`rgblight_increase_hue_noeeprom()` |Increase the hue for all LEDs. This wraps around at maximum hue (not written to EEPROM) | -|`rgblight_decrease_hue()` |Decrease the hue for all LEDs. This wraps around at minimum hue | -|`rgblight_decrease_hue_noeeprom()` |Decrease the hue for all LEDs. This wraps around at minimum hue (not written to EEPROM) | -|`rgblight_increase_sat()` |Increase the saturation for all LEDs. This wraps around at maximum saturation | -|`rgblight_increase_sat_noeeprom()` |Increase the saturation for all LEDs. This wraps around at maximum saturation (not written to EEPROM) | -|`rgblight_decrease_sat()` |Decrease the saturation for all LEDs. This wraps around at minimum saturation | -|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for all LEDs. This wraps around at minimum saturation (not written to EEPROM) | -|`rgblight_increase_val()` |Increase the value for all LEDs. This wraps around at maximum value | -|`rgblight_increase_val_noeeprom()` |Increase the value for all LEDs. This wraps around at maximum value (not written to EEPROM) | -|`rgblight_decrease_val()` |Decrease the value for all LEDs. This wraps around at minimum value | -|`rgblight_decrease_val_noeeprom()` |Decrease the value for all LEDs. This wraps around at minimum value (not written to EEPROM) | -|`rgblight_set_clipping_range(pos, num)` |Set clipping Range | +|`rgblight_sethsv_range(h, s, v, start, end)`|Set a continuous range of LEDs to the given HSV value, where `h`/`s`/`v` are between 0 and 255, and `start`(included) and `stop`(excluded) are between 0 and `RGBLED_NUM` (not written to EEPROM)| +|`rgblight_setrgb(r, g, b)` |Set effect range LEDs to the given RGB value where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | +|`rgblight_setrgb_master(r, g, b)` |Set the LEDs on the master side to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | +|`rgblight_setrgb_slave(r, g, b)` |Set the LEDs on the slave side to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | +|`rgblight_sethsv_master(h, s, v)` |Set the LEDs on the master side to the given HSV value, where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | +|`rgblight_sethsv_slave(h, s, v)` |Set the LEDs on the slave side to the given HSV value, where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | + +Example: +```c +rgblight_sethsv(HSV_WHITE, 0); // led 0 +rgblight_sethsv(HSV_RED, 1); // led 1 +rgblight_sethsv(HSV_GREEN, 2); // led 2 +// The above functions automatically calls rgblight_set(), so there is no need to call it explicitly. +// Note that it is inefficient to call repeatedly. +``` + +#### effect mode change +|Function |Description | +|--------------------------------------------|-------------| +|`rgblight_mode(x)` |Set the mode, if RGB animations are enabled | +|`rgblight_mode_noeeprom(x)` |Set the mode, if RGB animations are enabled (not written to EEPROM) | +|`rgblight_step()` |Change the mode to the next RGB animation in the list of enabled RGB animations | +|`rgblight_step_noeeprom()` |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) | +|`rgblight_step_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations | +|`rgblight_step_reverse_noeeprom()` |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) | + +#### effects mode disable/enable +|Function |Description | +|--------------------------------------------|-------------| +|`rgblight_toggle()` |Toggle effect range LEDs between on and off | +|`rgblight_toggle_noeeprom()` |Toggle effect range LEDs between on and off (not written to EEPROM) | +|`rgblight_enable()` |Turn effect range LEDs on, based on their previous state | +|`rgblight_enable_noeeprom()` |Turn effect range LEDs on, based on their previous state (not written to EEPROM) | +|`rgblight_disable()` |Turn effect range LEDs off | +|`rgblight_disable_noeeprom()` |Turn effect range LEDs off (not written to EEPROM) | + +#### hue, sat, val change +|Function |Description | +|--------------------------------------------|-------------| +|`rgblight_increase_hue()` |Increase the hue for effect range LEDs. This wraps around at maximum hue | +|`rgblight_increase_hue_noeeprom()` |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) | +|`rgblight_decrease_hue()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue | +|`rgblight_decrease_hue_noeeprom()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) | +|`rgblight_increase_sat()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation | +|`rgblight_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation (not written to EEPROM) | +|`rgblight_decrease_sat()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation | +|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation (not written to EEPROM) | +|`rgblight_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value | +|`rgblight_increase_val_noeeprom()` |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) | +|`rgblight_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value | +|`rgblight_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) | +|`rgblight_sethsv(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 | +|`rgblight_sethsv_noeeprom(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | + +#### query +|Function |Description | +|-----------------------|-----------------| +|`rgblight_get_mode()` |Get current mode | +|`rgblight_get_hue()` |Get current hue | +|`rgblight_get_sat()` |Get current sat | +|`rgblight_get_val()` |Get current val | ## Colors @@ -324,4 +380,6 @@ In addition to setting the Clipping Range, you can use `RGBLIGHT_LED_MAP` togeth ``` clip mapped +## Hardware Modification + If your keyboard lacks onboard underglow LEDs, you may often be able to solder on an RGB LED strip yourself. You will need to find an unused pin to wire to the data pin of your LED strip. Some keyboards may break out unused pins from the MCU to make soldering easier. The other two pins, VCC and GND, must also be connected to the appropriate power pins. -- cgit v1.2.3 From b541369c45f13369c16de1b887f6ca5b7e589e6d Mon Sep 17 00:00:00 2001 From: Pavlos Vinieratos Date: Thu, 16 May 2019 17:21:51 +0200 Subject: [Docs] Fix typo in Userspace doc (#5871) * typo * Update docs/feature_userspace.md Co-Authored-By: fauxpark --- docs/feature_userspace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md index d82d43138d..2f119c8bde 100644 --- a/docs/feature_userspace.md +++ b/docs/feature_userspace.md @@ -110,7 +110,7 @@ QMK has a bunch of [functions](custom_quantum_functions.md) that have [`_quantum However, you can actually add support for keymap version, so that you can use it in both your userspace and your keymap! -For instance, lets looks at the `layer_state_set_user` function. Lets enable the [Tri Layer State](ref_functions.md#olkb-tri-layers) functionalitly to all of our boards, and then still have your `keymap.c` still able to use this functionality. +For instance, let's look at the `layer_state_set_user()` function. You can enable the [Tri Layer State](ref_functions.md#olkb-tri-layers) functionality on all of your boards, while also retaining the Tri Layer functionality in your `keymap.c` files. In your `` file, you'd want to add this: ```c -- cgit v1.2.3 From 48b01446ba6b74d7e0793f972873a10fceef2f62 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Thu, 16 May 2019 10:28:06 -0700 Subject: Make delay for Capslock in Hold-Tap functions configurable (#5497) * Increase delay for Hold-Tap register for CAPSLOCK Because it seems that the 80ms delay wasn't too much * Screw it, make the caps delay a define and make it configurable --- docs/config_options.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index 3ef00394db..cab3c0747a 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -171,6 +171,8 @@ If you define these options you will enable the associated feature, which may in * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined. * `#define TAP_CODE_DELAY 100` * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds. +* `#define TAP_HOLD_CAPS_DELAY 200` + * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 200ms if not defined. ## RGB Light Configuration -- cgit v1.2.3 From d85110b6ec5fcdf3ef88b41909ce739b017abbea Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 17 May 2019 16:48:53 -0400 Subject: Adds a configurable initial delay to the audio clicky feature (#4286) * Adding an AUDIO_CLICKY_DELAY_DURATION configurable value to the AUDIO_CLICKY feature. * Tweaking my community keymap to work better with my rev 4 planck. --- docs/feature_audio.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_audio.md b/docs/feature_audio.md index e1dd4c5a85..7511598bcf 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -175,8 +175,9 @@ You can configure the default, min and max frequencies, the stepping and built i | `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. | | `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). | | `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. | -| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. | +| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. This is a multiplicative factor. The default steps the frequency up/down by a musical minor third. | | `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. | +| `AUDIO_CLICKY_DELAY_DURATION` | 1 | An integer note duration where 1 is 1/16th of the tempo, or a sixty-fourth note (see `quantum/audio/musical_notes.h` for implementation details). The main clicky effect will be delayed by this duration. Adjusting this to values around 6-12 will help compensate for loud switches. | -- cgit v1.2.3 From 0099bbf9a64a0b4df1093f528481bff39af2c80d Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Sun, 19 May 2019 11:09:06 -0500 Subject: Single Color Band scrolling left to right effects (#5867) --- docs/feature_rgb_matrix.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 8347660dfe..df124ea0f5 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -194,6 +194,8 @@ enum rgb_matrix_effects { RGB_MATRIX_ALPHAS_MODS, // Static dual hue, speed is hue for secondary hue RGB_MATRIX_GRADIENT_UP_DOWN, // Static gradient top to bottom, speed controls how much gradient changes RGB_MATRIX_BREATHING, // Single hue brightness cycling animation + RGB_MATRIX_BAND_SAT, // Single hue band fading saturation scrolling left to right + RGB_MATRIX_BAND_VAL, // Single hue band fading brightness scrolling left to right RGB_MATRIX_CYCLE_ALL, // Full keyboard solid hue cycling through full gradient RGB_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right RGB_MATRIX_CYCLE_UP_DOWN, // Full gradient scrolling top to bottom @@ -235,6 +237,8 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |`#define DISABLE_RGB_MATRIX_ALPHAS_MODS` |Disables `RGB_MATRIX_ALPHAS_MODS` | |`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Disables `RGB_MATRIX_GRADIENT_UP_DOWN` | |`#define DISABLE_RGB_MATRIX_BREATHING` |Disables `RGB_MATRIX_BREATHING` | +|`#define DISABLE_RGB_MATRIX_BAND_SAT` |Disables `RGB_MATRIX_BAND_SAT` | +|`#define DISABLE_RGB_MATRIX_BAND_VAL` |Disables `RGB_MATRIX_BAND_VAL` | |`#define DISABLE_RGB_MATRIX_CYCLE_ALL` |Disables `RGB_MATRIX_CYCLE_ALL` | |`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT` | |`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Disables `RGB_MATRIX_CYCLE_UP_DOWN` | -- cgit v1.2.3 From 270b39b2eb44247cff75ddd216a8e67f8f264991 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Sun, 19 May 2019 11:19:46 -0500 Subject: Spirals, Pinwheels, and Documentation....Oh My! RGB Matrix Effects (#5877) * Spirals, Pinwheels, and Documentation....Oh My! * Spiral effect band thickness adjustments * Fixing animation spin directions --- docs/feature_rgb_matrix.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index df124ea0f5..18636776cd 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -196,12 +196,18 @@ enum rgb_matrix_effects { RGB_MATRIX_BREATHING, // Single hue brightness cycling animation RGB_MATRIX_BAND_SAT, // Single hue band fading saturation scrolling left to right RGB_MATRIX_BAND_VAL, // Single hue band fading brightness scrolling left to right + RGB_MATRIX_BAND_PINWHEEL_SAT, // Single hue 3 blade spinning pinwheel fades saturation + RGB_MATRIX_BAND_PINWHEEL_VAL, // Single hue 3 blade spinning pinwheel fades brightness + RGB_MATRIX_BAND_SPIRAL_SAT, // Single hue spinning spiral fades saturation + RGB_MATRIX_BAND_SPIRAL_VAL, // Single hue spinning spiral fades brightness RGB_MATRIX_CYCLE_ALL, // Full keyboard solid hue cycling through full gradient RGB_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right RGB_MATRIX_CYCLE_UP_DOWN, // Full gradient scrolling top to bottom RGB_MATRIX_CYCLE_OUT_IN, // Full gradient scrolling out to in RGB_MATRIX_CYCLE_OUT_IN_DUAL, // Full dual gradients scrolling out to in RGB_MATRIX_RAINBOW_MOVING_CHEVRON, // Full gradent Chevron shapped scrolling left to right + RGB_MATRIX_CYCLE_PINWHEEL, // Full gradient spinning pinwheel around center of keyboard + RGB_MATRIX_CYCLE_SPIRAL, // Full gradient spinning spiral around center of keyboard RGB_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard RGB_MATRIX_RAINBOW_BEACON, // Full tighter gradient spinning around center of keyboard RGB_MATRIX_RAINBOW_PINWHEELS, // Full dual gradients spinning two halfs of keyboard @@ -239,6 +245,10 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |`#define DISABLE_RGB_MATRIX_BREATHING` |Disables `RGB_MATRIX_BREATHING` | |`#define DISABLE_RGB_MATRIX_BAND_SAT` |Disables `RGB_MATRIX_BAND_SAT` | |`#define DISABLE_RGB_MATRIX_BAND_VAL` |Disables `RGB_MATRIX_BAND_VAL` | +|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_SAT` |Disables `RGB_MATRIX_BAND_PINWHEEL_SAT` | +|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_VAL` |Disables `RGB_MATRIX_BAND_PINWHEEL_VAL` | +|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_SAT` |Disables `RGB_MATRIX_BAND_SPIRAL_SAT` | +|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_VAL` |Disables `RGB_MATRIX_BAND_SPIRAL_VAL` | |`#define DISABLE_RGB_MATRIX_CYCLE_ALL` |Disables `RGB_MATRIX_CYCLE_ALL` | |`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT` | |`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Disables `RGB_MATRIX_CYCLE_UP_DOWN` | @@ -246,6 +256,8 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Disables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` | |`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` | |`#define DISABLE_RGB_MATRIX_DUAL_BEACON` |Disables `RGB_MATRIX_DUAL_BEACON` | +|`#define DISABLE_RGB_MATRIX_CYCLE_PINWHEEL` |Disables `RGB_MATRIX_CYCLE_PINWHEEL` | +|`#define DISABLE_RGB_MATRIX_CYCLE_SPIRAL` |Disables `RGB_MATRIX_CYCLE_SPIRAL` | |`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON` |Disables `RGB_MATRIX_RAINBOW_BEACON` | |`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Disables `RGB_MATRIX_RAINBOW_PINWHEELS` | |`#define DISABLE_RGB_MATRIX_RAINDROPS` |Disables `RGB_MATRIX_RAINDROPS` | -- cgit v1.2.3 From 5c7b37bbbde969eb056d531c897c1d5f80beeb58 Mon Sep 17 00:00:00 2001 From: Ryan Caltabiano Date: Wed, 15 May 2019 22:23:42 -0500 Subject: Added custom center point to rgb matrix --- docs/feature_rgb_matrix.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 18636776cd..8f0cd12b3c 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -144,14 +144,16 @@ const led_config_t g_led_config = { { } }; ``` -The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical position on the keyboard. The first value, `x`, is between 0-224 (inclusive), and the second value, `y`, is between 0-64 (inclusive). This range is due to effect that calculate the center or halves for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents x, y coordinate 0, 0 and the bottom right of your keyboard represents 224, 64. Using this as a basis, you can use the following formula to calculate the physical position: +The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical `{ x, y }` position on the keyboard. The default expected range of values for `{ x, y }` is the inclusive range `{ 0..224, 0..64 }`. This default expected range is due to effects that calculate the center of the keyboard for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents `{ x, y }` coordinate `{ 0, 0 }` and the bottom right of your keyboard represents `{ 224, 64 }`. Using this as a basis, you can use the following formula to calculate the physical position: ```C x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION ``` -Where NUMBER_OF_COLS, NUMBER_OF_ROWS, COL_POSITION, & ROW_POSITION are all based on the physical layout of your keyboard, not the electrical layout. +Where NUMBER_OF_COLS, NUMBER_OF_ROWS, COL_POSITION, & ROW_POSITION are all based on the physical layout of your keyboard, not the electrical layout. + +As mentioned earlier, the center of the keyboard by default is expected to be `{ 112, 32 }`, but this can be changed if you want to more accurately calculate the LED's physical `{ x, y }` positions. Keyboard designers can implement `#define RGB_MATRIX_CENTER { 112, 32 }` in their config.h file with the new center point of the keyboard, or where they want it to be allowing more possibilities for the `{ x, y }` values. Do note that the maximum value for x or y is 255, and the recommended maximum is 224 as this gives animations runoff room before they reset. `// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type. -- cgit v1.2.3 From 02787ac07f29ecb05a53dc986c215e177ee11d1d Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Tue, 21 May 2019 13:15:59 -0700 Subject: Add missing links to features page and sidebar section --- docs/_summary.md | 3 +++ docs/features.md | 5 +++++ 2 files changed, 8 insertions(+) (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 043943f1d8..1c3153b040 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -54,9 +54,12 @@ * [Bootmagic](feature_bootmagic.md) * [Combos](feature_combo) * [Command](feature_command.md) + * [Debounce API](feature_debuonce.md) * [Dynamic Macros](feature_dynamic_macros.md) * [Encoders](feature_encoders.md) * [Grave Escape](feature_grave_esc.md) + * [Haptic Feedback](feature_haptic_feedback.md) + * [HD44780 LED](feature_hd44780.md) * [Key Lock](feature_key_lock.md) * [Layouts](feature_layouts.md) * [Leader Key](feature_leader_key.md) diff --git a/docs/features.md b/docs/features.md index cb69df35d7..eb3f26d6a8 100644 --- a/docs/features.md +++ b/docs/features.md @@ -7,12 +7,15 @@ QMK has a staggering number of features for building your keyboard. It can take * [Audio](feature_audio.md) - Connect a speaker to your keyboard for audio feedback, midi support, and music mode. * [Auto Shift](feature_auto_shift.md) - Tap for the normal key, hold slightly longer for its shifted state. * [Backlight](feature_backlight.md) - LED lighting support for your keyboard. +* [Bluetooth](feature_bluetooth.md) - BlueTooth support for your keyboard. * [Bootmagic](feature_bootmagic.md) - Adjust the behavior of your keyboard using hotkeys. * [Combos](feature_combo.md) - Custom actions for multiple key holds. * [Command](feature_command.md) - Runtime version of bootmagic (Formerly known as "Magic"). +* [Debounce API](feature_debuonce.md) - Customization of debouncing algorithms, and the ability to add more/custom debouncing. * [Dynamic Macros](feature_dynamic_macros.md) - Record and playback macros from the keyboard itself. * [Encoders](feature_encoders.md) - Rotary encoders! * [Grave Escape](feature_grave_esc.md) - Lets you use a single key for Esc and Grave. +* [Haptic Feedback](feature_haptic_feedback.md) - Add haptic feedback drivers to your board. * [HD44780 LCD Display](feature_hd44780.md) - Support for LCD character displays using the HD44780 standard. * [Key Lock](feature_key_lock.md) - Lock a key in the "down" state. * [Layouts](feature_layouts.md) - Use one keymap with any keyboard that supports your layout. @@ -20,6 +23,7 @@ QMK has a staggering number of features for building your keyboard. It can take * [LED Matrix](feature_led_matrix.md) - LED Matrix single color lights for per key lighting (Single Color, not RGB). * [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key. * [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard. +* [OLED Driver](feature_oled_driver) - Add OLED screens to your keyboard. * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets hit a key rather than holding it. * [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard. * [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard. @@ -33,3 +37,4 @@ QMK has a staggering number of features for building your keyboard. It can take * [Thermal Printer](feature_thermal_printer.md) - Connect a thermal printer to your keyboard to be able to toggle on a printed log of everything you type. * [Unicode](feature_unicode.md) - Unicode input support. * [Userspace](feature_userspace.md) - Share code between different keymaps and keyboards. +* [Velocikey](feature_velocikey.md) - Allows changes in animation speed based on WPM/Typing speed. -- cgit v1.2.3 From 894010786c4a78b939df7114d1c3e70957a8a300 Mon Sep 17 00:00:00 2001 From: ymzcdg <49898694+ymzcdg@users.noreply.github.com> Date: Thu, 23 May 2019 05:33:10 +0800 Subject: translate docs into Mandarin Chinese (#5890) * translate docs into Mandarin Chinese translate faq_debug.md into Chinese * translate faq_build.md into Chinese translate faq_build.md into Chinese * faq_keymap.md to zh-cn faq_keymap.md to zh-cn --- docs/zh-cn/faq_build.md | 150 ++++++++++++++++++++++++++++++ docs/zh-cn/faq_debug.md | 233 +++++++++++++++++++++++++++++++++++++++++++++++ docs/zh-cn/faq_keymap.md | 212 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 595 insertions(+) create mode 100644 docs/zh-cn/faq_build.md create mode 100644 docs/zh-cn/faq_debug.md create mode 100644 docs/zh-cn/faq_keymap.md (limited to 'docs') diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md new file mode 100644 index 0000000000..60d902007c --- /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 ::dfu + +使用`sudo`运行`make`一般来说**不**推荐，如果可能，尽量使用前一种方法之一。 + +### Linux `udev` 规则 +在Linux上，您需要适当的权限才能访问MCU。你也可以在刷新固件时使用 `sudo`，或把这些文件放到`/etc/udev/rules.d/`。 + +**/etc/udev/rules.d/50-atmel-dfu.rules:** +``` +# Atmel ATMega32U4 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666" +# Atmel USBKEY AT90USB1287 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666" +# Atmel ATMega32U2 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666" +``` + +**/etc/udev/rules.d/52-tmk-keyboard.rules:** +``` +# tmk键盘产品 https://github.com/tmk/tmk_keyboard +SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" +``` +**/etc/udev/rules.d/54-input-club-keyboard.rules:** + +``` +# Input Club keyboard bootloader +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" +``` + +### 串行设备在Linux上检测不到bootloader模式 +确保您的内核对您的设备有相应的支持。 如果你的设备是 USB ACM, 比如Pro Micro (Atmega32u4)，就要加上`CONFIG_USB_ACM=y`. 其他设备可能需要`USB_SERIAL` 及其任何子选项。 + +## DFU Bootloader的未知设备 + +如果您在使用Windows来刷新键盘的时候碰到了问题，检查设备管理器。如果在键盘处于 "bootloader模式"时你看到 "未知设备"，说明你可能面临设备问题。 + +重新运行MSYS2上的安装脚本或许会凑效（比如在MSYS2/WSL运行 `./util/qmk_install.sh`) 或者重新安装QMK工具箱也可能会解决你的问题。 + +如果以上方法还是短针攻疽，那您可能需要使用[Zadig Utility](https://zadig.akeo.ie/)。下载此程序, 找到设备问题, 然后选择 `WinUSB`选项, 然后点击"Reinstall driver"。完成后再试试刷新你的键盘。倘若依然徒劳无功，那就尝试所有选项直到好用为止。 + +?> 事实上没有一个驱动的最佳选择，有些选项就是和某些系统相辅相成。但libUSB和WinUSB似乎也算是这里的最佳选择了。 +如果bootloader在设备列表中没有显示，你可能要使能 "List all devices"选项在选项菜单中`Options`，然后找到有问题的bootloader设备。(译者注：在win10中可能为 查看-显示隐藏的设备) + + +## WINAVR已淘汰 +不再推荐使用WINAVR，使用可能会导致问题 +详情请见[TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99). + +## USB VID 和 PID +你可以在编辑`config.h`时使用任何你想用的ID值。实际上，使用任何可能未使用的ID都没有问题，除了有极低的与其他产品发生冲突的可能性。 + +大多数QMK主板使用`0xFEED`作为vendor ID。您应该查看其他键盘，以确保选择了唯一的Product ID。 + +也要看看这个。 +https://github.com/tmk/tmk_keyboard/issues/150 + +一也可以在下方链接购买一个唯一的VID:PID。不过个人使用似乎用不着这个。 +- http://www.obdev.at/products/vusb/license.html +- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 + +## Cortex: `cstddef: No such file or directory` +在Ubuntu 14.04上的GCC 4.8 会出现这种问题需要用这个PPA升级到4.9。 +https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded + +https://github.com/tmk/tmk_keyboard/issues/212 +https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef +https://developer.mbed.org/forum/mbed/topic/5205/ + +## `clock_prescale_set` and `clock_div_1` Not Available +你的工具链太旧了不支持MCU。比如WinAVR 20100110就不支持ATMega32u2. + +``` +Compiling C: ../../tmk_core/protocol/lufa/lufa.c +avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8 -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o +../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu': +../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set' +../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function) +../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once +../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.) +make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1 +``` + + +## AVR的BOOTLOADER_SIZE +注意Teensy2.0++ bootloader的大小是2048字节。有些Makefile注释错了。 + +``` +# Boot Section Size in *bytes* +# Teensy halfKay 512 +# Teensy++ halfKay 2048 +# Atmel DFU loader 4096 (TMK Alt Controller) +# LUFA bootloader 4096 +# USBaspLoader 2048 +OPT_DEFS += -DBOOTLOADER_SIZE=2048 +``` + +## 在MacOS上 `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` +这是brew更新的问题，导致AVR GCC依赖的符号链接被损坏。 + +解决方案是移除并重新安装所有受影响的模块。 + +``` +brew rm avr-gcc +brew rm dfu-programmer +brew rm dfu-util +brew rm gcc-arm-none-eabi +brew rm avrdude +brew install avr-gcc +brew install dfu-programmer +brew install dfu-util +brew install gcc-arm-none-eabi +brew install avrdude +``` + +### avr-gcc 8.1 和 LUFA + +如果你把avr-gcc升级到7以上你可能会遇到关于LUFA的问题。比如: + +`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'` + +那你就需要在brew中把avr-gcc回退到7。 + +``` +brew uninstall --force avr-gcc +brew install avr-gcc@7 +brew link --force avr-gcc@7 +``` + +### 我刷新了我的键盘但是键盘不工作/按键没有注册 - 而且还是ARM的 (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019) +由于EEPROM在基于ARM的芯片上的工作原理，保存的设置可能不再有效。这会影响默认层，而且*或许*在某些情况下，会使键盘不好用，我们仍在调查这些情况。重置EEPROM将解决此问题。 + +[Planck rev6键盘重置EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) 是用于强制重置EEPROM的。刷入这个文件后，再次刷入正常固件，这会将键盘恢复到_正常_工作状态。 +[Preonic rev3键盘重置EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin) + +如果以任何形式启用了bootmagic， 那么您还需要(看[Bootmagic文档](feature_bootmagic.md) 以及键盘信息，以了解如何执行此操作的详细信息). diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md new file mode 100644 index 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位未编程来失能该功能。 + +代码如下。 +``` + // F接口JTAG失能。在四个周期内写入两次JTD位。 + MCUCR |= (1< +![键盘设计图](https://i.imgur.com/5wsh5wM.png) + +## 我有一些键变成了其他功能或者不工作了 + +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`会处理用户页面用法。 + +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 和 ` 双功能键 + +请见[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 -- cgit v1.2.3 From dcb274b2867adeb0f516eb709c7f651aa61774a6 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Wed, 22 May 2019 20:55:52 -0700 Subject: Fix links Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> --- docs/_summary.md | 4 ++-- docs/features.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 1c3153b040..02254a9d81 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -54,12 +54,12 @@ * [Bootmagic](feature_bootmagic.md) * [Combos](feature_combo) * [Command](feature_command.md) - * [Debounce API](feature_debuonce.md) + * [Debounce API](feature_debounce_type.md) * [Dynamic Macros](feature_dynamic_macros.md) * [Encoders](feature_encoders.md) * [Grave Escape](feature_grave_esc.md) * [Haptic Feedback](feature_haptic_feedback.md) - * [HD44780 LED](feature_hd44780.md) + * [HD44780 LCD Controller](feature_hd44780.md) * [Key Lock](feature_key_lock.md) * [Layouts](feature_layouts.md) * [Leader Key](feature_leader_key.md) diff --git a/docs/features.md b/docs/features.md index eb3f26d6a8..ac9aad3948 100644 --- a/docs/features.md +++ b/docs/features.md @@ -11,7 +11,7 @@ QMK has a staggering number of features for building your keyboard. It can take * [Bootmagic](feature_bootmagic.md) - Adjust the behavior of your keyboard using hotkeys. * [Combos](feature_combo.md) - Custom actions for multiple key holds. * [Command](feature_command.md) - Runtime version of bootmagic (Formerly known as "Magic"). -* [Debounce API](feature_debuonce.md) - Customization of debouncing algorithms, and the ability to add more/custom debouncing. +* [Debounce API](feature_debounce_type.md) - Customization of debouncing algorithms, and the ability to add more/custom debouncing. * [Dynamic Macros](feature_dynamic_macros.md) - Record and playback macros from the keyboard itself. * [Encoders](feature_encoders.md) - Rotary encoders! * [Grave Escape](feature_grave_esc.md) - Lets you use a single key for Esc and Grave. @@ -23,7 +23,7 @@ QMK has a staggering number of features for building your keyboard. It can take * [LED Matrix](feature_led_matrix.md) - LED Matrix single color lights for per key lighting (Single Color, not RGB). * [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key. * [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard. -* [OLED Driver](feature_oled_driver) - Add OLED screens to your keyboard. +* [OLED Driver](feature_oled_driver.md) - Add OLED screens to your keyboard. * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets hit a key rather than holding it. * [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard. * [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard. @@ -37,4 +37,4 @@ QMK has a staggering number of features for building your keyboard. It can take * [Thermal Printer](feature_thermal_printer.md) - Connect a thermal printer to your keyboard to be able to toggle on a printed log of everything you type. * [Unicode](feature_unicode.md) - Unicode input support. * [Userspace](feature_userspace.md) - Share code between different keymaps and keyboards. -* [Velocikey](feature_velocikey.md) - Allows changes in animation speed based on WPM/Typing speed. +* [Velocikey](feature_velocikey.md) - Allows changes in RGB animation speed based on WPM/Typing speed. -- cgit v1.2.3 From c97315dc5a355636e1f514a93c28ea2842002742 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Wed, 22 May 2019 20:59:01 -0700 Subject: Additional link fixes Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> --- docs/_summary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 02254a9d81..8a40ccd7f2 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -52,7 +52,7 @@ * [Backlight](feature_backlight.md) * [Bluetooth](feature_bluetooth.md) * [Bootmagic](feature_bootmagic.md) - * [Combos](feature_combo) + * [Combos](feature_combo.md) * [Command](feature_command.md) * [Debounce API](feature_debounce_type.md) * [Dynamic Macros](feature_dynamic_macros.md) @@ -66,7 +66,7 @@ * [LED Matrix](feature_led_matrix.md) * [Macros](feature_macros.md) * [Mouse Keys](feature_mouse_keys.md) - * [OLED Driver](feature_oled_driver) + * [OLED Driver](feature_oled_driver.md) * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) * [Pointing Device](feature_pointing_device.md) * [PS/2 Mouse](feature_ps2_mouse.md) -- cgit v1.2.3 From 36f427f40cc64fa2dcd6da4eae20d467e88c0bd9 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Thu, 23 May 2019 10:29:18 -0700 Subject: Fix typo --- docs/features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/features.md b/docs/features.md index ac9aad3948..f9ef51eae2 100644 --- a/docs/features.md +++ b/docs/features.md @@ -24,7 +24,7 @@ QMK has a staggering number of features for building your keyboard. It can take * [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key. * [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard. * [OLED Driver](feature_oled_driver.md) - Add OLED screens to your keyboard. -* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets hit a key rather than holding it. +* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets you hit a key rather than holding it. * [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard. * [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard. * [RGB Light](feature_rgblight.md) - RGB lighting for your keyboard. -- cgit v1.2.3 From fe8c2209ca9172352cb46cc6cf7800e4998849ea Mon Sep 17 00:00:00 2001 From: fauxpark Date: Sat, 25 May 2019 03:05:29 +1000 Subject: Document MT keycode in keycodes.md --- docs/keycodes.md | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) (limited to 'docs') diff --git a/docs/keycodes.md b/docs/keycodes.md index e9cfd34252..3ff87856e4 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -344,23 +344,24 @@ This is a reference only. Each group of keys links to the page documenting their ## [Mod-Tap Keys](feature_advanced_keycodes.md#mod-tap) -|Key |Aliases |Description | -|------------|-----------------------------------------------------------------|-------------------------------------------------------| -|`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped | -|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped | -|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped | -|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped | -|`RCTL_T(kc)`| |Right Control when held, `kc` when tapped | -|`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped | -|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped | -|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped | -|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | -|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | -|`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped | -|`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped | -|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped | -|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped| -|`HYPR_T(kc)`|`ALL_T(kc)` |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| +|Key |Aliases |Description | +|-------------|-----------------------------------------------------------------|-------------------------------------------------------| +|`MT(mod, kc)`| |`mod` when held, `kc` when tapped | +|`LCTL_T(kc)` |`CTL_T(kc)` |Left Control when held, `kc` when tapped | +|`LSFT_T(kc)` |`SFT_T(kc)` |Left Shift when held, `kc` when tapped | +|`LALT_T(kc)` |`ALT_T(kc)` |Left Alt when held, `kc` when tapped | +|`LGUI_T(kc)` |`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped | +|`RCTL_T(kc)` | |Right Control when held, `kc` when tapped | +|`RSFT_T(kc)` | |Right Shift when held, `kc` when tapped | +|`RALT_T(kc)` |`ALGR_T(kc)` |Right Alt when held, `kc` when tapped | +|`RGUI_T(kc)` |`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped | +|`SGUI_T(kc)` |`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | +|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | +|`LCAG_T(kc)` | |Left Control, Alt and GUI when held, `kc` when tapped | +|`RCAG_T(kc)` | |Right Control, Alt and GUI when held, `kc` when tapped | +|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped | +|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped| +|`HYPR_T(kc)` |`ALL_T(kc)` |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| ## [RGB Lighting](feature_rgblight.md) -- cgit v1.2.3 From 3ef425423a9b8399b02c8240b4f56c3713f984f6 Mon Sep 17 00:00:00 2001 From: Elliot Powell <32494740+e11i0t23@users.noreply.github.com> Date: Thu, 30 May 2019 16:53:43 +0100 Subject: Update feature_encoders.md Fix missing closing comment after second encoder --- docs/feature_encoders.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index dd12c91ce3..9ac97a9a16 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -38,7 +38,7 @@ or `keymap.c`: } else { tap_code(KC_PGUP); } - } else if (index == 1) { /* Second encoder + } else if (index == 1) { /* Second encoder */ if (clockwise) { tap_code(KC_UP); } else { -- cgit v1.2.3 From 9cc5841a91ff1bf95d6895254b43b097a0f365aa Mon Sep 17 00:00:00 2001 From: Elliot Powell <32494740+e11i0t23@users.noreply.github.com> Date: Fri, 31 May 2019 19:04:39 +0100 Subject: Update reference_configurator_support.md We no longer auto generate bootloader into info.json through the website therefore this can be removed --- docs/reference_configurator_support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/reference_configurator_support.md b/docs/reference_configurator_support.md index a20a6c9adb..784c6d9f75 100644 --- a/docs/reference_configurator_support.md +++ b/docs/reference_configurator_support.md @@ -89,7 +89,7 @@ Once the layout is as desired, move to the Raw Data tab in KLE, and copy the con To convert this data into our JSON, go to the [QMK KLE-JSON Converter](https://qmk.fm/converter/), paste the Raw Data into the Input field, and click the Convert button. After a moment, our JSON data will appear in the Output field. Copy the contents to a new text document, and name the document `info.json`, saving it in the same folder that contains `numpad.h`. -Use the `keyboard_name` object to set the name of the keyboard. The `bootloader` object is deprecated, so it can be deleted. For instruction purposes, we will put each key's object on its own line. This is only to make the file more human-readable, and does not affect the Configurator's functionality. +Use the `keyboard_name` object to set the name of the keyboard. For instruction purposes, we will put each key's object on its own line. This is only to make the file more human-readable, and does not affect the Configurator's functionality. ```json { -- cgit v1.2.3 From d3317a8a66e1a94de0dd795f5c9efe260e674475 Mon Sep 17 00:00:00 2001 From: Elliot Powell <32494740+e11i0t23@users.noreply.github.com> Date: Fri, 31 May 2019 22:44:27 +0100 Subject: [Docs] Update getting_started_introduction.md (#6037) * Update getting_started_introduction.md * Update docs/getting_started_introduction.md Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> * Update docs/getting_started_introduction.md Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> * Update docs/getting_started_introduction.md Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> * Update docs/getting_started_introduction.md Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> --- docs/getting_started_introduction.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md index 3b6a488ed6..e183d77eeb 100644 --- a/docs/getting_started_introduction.md +++ b/docs/getting_started_introduction.md @@ -12,11 +12,17 @@ Within the folder `users` is a directory for each user. This is a place for user ### Keyboard Project Structure -Within the folder `keyboards` and its subfolder `handwired` is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within it you'll find the following structure: +Within the folder `keyboards`, its subfolder `handwired` and its vendor and manufacture subdirectories e.g. `clueboard` is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard/2x1800`. Within it, you'll find the following structure: * `keymaps/`: Different keymaps that can be built * `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `rules.mk`. * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`. +* `info.json`: The file used for setting layout for QMK Configurator. See [Configurator Support](reference_configurator_support.md) for more information. +* `readme.md`: A brief overview of the keyboard. +* `.h`: This file is where the keyboard layout is defined against the keyboard's switch matrix. +* `.c`: This file is where you can find custom code for the keyboard. + +For more information on project structure, see [QMK Keyboard Guidelines](hardware_keyboard_guidelines.md). ### Keymap Structure -- cgit v1.2.3 From 155be34a1d2b782a73318cc507315b33cc86cc49 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Sun, 2 Jun 2019 09:04:09 +1000 Subject: Parameterise STM32 I2C pin modes and timing parameters. (#5671) I2C timing parameters were seemingly set up for an STM32F303 target MCU, at a specific clock speed. This commit allows specifying the timing parameters via config.h, allowing other STM32 MCUs to be targeted, potentially at different clock frequencies. Alternate function modes for the I2C pins are now also configurable, allowing for remapping to other pins. --- docs/i2c_driver.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md index bb1a2d74ff..4a47a92b11 100644 --- a/docs/i2c_driver.md +++ b/docs/i2c_driver.md @@ -65,11 +65,30 @@ By default the I2C1 hardware driver is assumed to be used. If another hardware d STM32 MCUs allows a variety of pins to be configured as I2C pins depending on the hardware driver used. By default B6 and B7 are set to I2C. You can use these defines to set your i2c pins: -| Variable | Description | Default | -|-------------|----------------------------------------------|---------| -| `I2C1_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) | `GPIOB` | -| `I2C1_SCL` | The pin number for the SCL pin (0-9) | `6` | -| `I2C1_SDA` | The pin number for the SDA pin (0-9) | `7` | +| Variable | Description | Default | +|--------------------------|----------------------------------------------------------------------------------------------|---------| +| `I2C1_SCL_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SCL | `GPIOB` | +| `I2C1_SDA_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SDA | `GPIOB` | +| `I2C1_SCL` | The pin number for the SCL pin (0-9) | `6` | +| `I2C1_SDA` | The pin number for the SDA pin (0-9) | `7` | +| `I2C1_BANK` (deprecated) | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superceded by `I2C1_SCL_BANK`, `I2C1_SDA_BANK` | `GPIOB` | + +STM32 MCUs allow for different timing parameters when configuring I2C. These can be modified using the following parameters, using https://www.st.com/en/embedded-software/stsw-stm32126.html as a reference: + +| Variable | Default | +|-----------------------|---------| +| `I2C1_TIMINGR_PRESC` | `15U` | +| `I2C1_TIMINGR_SCLDEL` | `4U` | +| `I2C1_TIMINGR_SDADEL` | `2U` | +| `I2C1_TIMINGR_SCLH` | `15U` | +| `I2C1_TIMINGR_SCLL` | `21U` | + +STM32 MCUs allow for different "alternate function" modes when configuring GPIO pins. These are required to switch the pins used to I2C mode. See the respective datasheet for the appropriate values for your MCU. + +| Variable | Default | +|---------------------|---------| +| `I2C1_SCL_PAL_MODE` | `4` | +| `I2C1_SDA_PAL_MODE` | `4` | You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function: -- cgit v1.2.3 From e0a0d80bd329b4a289e3c4f817c96857c25b0f16 Mon Sep 17 00:00:00 2001 From: ymzcdg <49898694+ymzcdg@users.noreply.github.com> Date: Wed, 5 Jun 2019 02:06:17 +0800 Subject: docs to Mandarin Chinese (#5960) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * faq_general.md to Chinese faq_general.md to Chinese faq finished * custom_quantum_functions.md to Chinese custom_quantum_functions.md to Chinese * custom_quantum_functions.md fix custom_quantum_functions.md fix * custom_quantum_functions.md fix translate custom_quantum_functions.md fix translate * !ver.English! _summary.md bug fix _summary.md bug fix of English doc. add".md" behind "feature_combo" * !ver.English! custom_quantum_functions.md fix#5869 custom_quantum_functions.md in English : delete redundant "is" . issue#5869 * !ver.English! how_keyboards_work.md link fix change https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input to https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_input "#Hexadecimal_code_input" not exist * !English! how_keyboards_work.md add missing "t" Tied to a specific OS a a time (need recompilation when changing OS); change to Tied to a specific OS at a time (need recompilation when changing OS); * _summary.md improve translation _summary.md improve translation * reference_glossary.md into Chinese reference_glossary.md into Chinese 术语表翻译，这个术语表英文版似乎不太全，应该补充英文版，并在中文版添加其他具有中国特色的术语。 --- docs/custom_quantum_functions.md | 2 +- docs/how_keyboards_work.md | 4 +- docs/zh-cn/_summary.md | 66 ++--- docs/zh-cn/custom_quantum_functions.md | 490 +++++++++++++++++++++++++++++++++ docs/zh-cn/faq_general.md | 19 ++ docs/zh-cn/reference_glossary.md | 170 ++++++++++++ 6 files changed, 715 insertions(+), 36 deletions(-) create mode 100644 docs/zh-cn/custom_quantum_functions.md create mode 100644 docs/zh-cn/faq_general.md create mode 100644 docs/zh-cn/reference_glossary.md (limited to 'docs') diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 6287b95309..7be82c650f 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -267,7 +267,7 @@ You should use this function if you need custom matrix scanning code. It can als If the board supports it, it can be "idled", by stopping a number of functions. A good example of this is RGB lights or backlights. This can save on power consumption, or may be better behavior for your keyboard. -This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system is board is idled and when it wakes up, respectively. +This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system board is idled and when it wakes up, respectively. ### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation diff --git a/docs/how_keyboards_work.md b/docs/how_keyboards_work.md index 0772f055d6..5697a21872 100644 --- a/docs/how_keyboards_work.md +++ b/docs/how_keyboards_work.md @@ -63,10 +63,10 @@ You may wonder why a keyboard layout containing all of Unicode is not devised th ## How to (Maybe) Enter Unicode Characters -You can have the firmware send *sequences of keys* to use the [software Unicode Input Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of the target operating system, thus effectively entering characters independently of the layout defined in the OS. +You can have the firmware send *sequences of keys* to use the [software Unicode Input Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_input) of the target operating system, thus effectively entering characters independently of the layout defined in the OS. Yet, it does come with multiple disadvantages: - - Tied to a specific OS a a time (need recompilation when changing OS); + - Tied to a specific OS at a time (need recompilation when changing OS); - Within a given OS, does not work in all software; - Limited to a subset of Unicode on some systems. 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/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ҪģȻֲ㺯ͲҪá + +# Զ + +ĿǰΪֹǸмΪ򴴽µļ롣ӴǶЩơ + +## һ¼ + +һöٳȫҲǸֲΨһֵ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淶5LEDķ: + +* `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()` + +5LEDκһ״̬Ҫıʱ˺á˺ͨ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_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)? + + + +## QMKTMKʲô? + +TMK[Jun Wako](https://github.com/tmk)ƺִСQMKʼ[Jack Humbert](https://github.com/jackhumbert)ΪPlanck̴TMKֲ档һʱJackķֲͺTMKȥԶˣ2015꣬JackQMK + +Ӽ۵QMKTMKһЩ¹ܶɵġQMKչ˿õļ룬ʹ߼ܽһḻ `S()`, `LCTL()`, `MO()`ȫ[](keycodes.md). + +ӹ̵TMKԼάйٷֵ֧ļֻ̣кСһ֧֡άѴڷֲΪ̴ķֲ档Ĭֺ֧ٵļ룬ûͨ˷֡QMKͨйֺֿͼ̣ǻз׼PRͼı֤άͬʱQMKСҲڱҪʱ + +ַŵȱ㣬ҴʱTMKQMK֮ 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帮我们添加需要添加的术语当然坠吼了:) -- cgit v1.2.3 From b2f7915994eb514a0348fdb864ead04c54c509c7 Mon Sep 17 00:00:00 2001 From: Alex Mayer Date: Wed, 5 Jun 2019 14:18:20 -0400 Subject: [Docs] Make Code Examples Consistent On Combo Page (#6078) --- docs/feature_combo.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_combo.md b/docs/feature_combo.md index 680adce2dc..4cb1bcda08 100644 --- a/docs/feature_combo.md +++ b/docs/feature_combo.md @@ -29,6 +29,7 @@ enum combos { AB_ESC, JK_TAB }; + const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END}; const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END}; @@ -44,7 +45,7 @@ For a more complicated implementation, you can use the `process_combo_event` fun enum combo_events { ZC_COPY, XV_PASTE - }; +}; const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END}; const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END}; -- cgit v1.2.3 From 4f2f2271cda85c3939deb3f61bbd9430e38a20fc Mon Sep 17 00:00:00 2001 From: Danny Nguyen Date: Wed, 5 Jun 2019 13:53:11 -0400 Subject: Change from avr-gcc@7 to @8 for Mac --- docs/faq_build.md | 4 ++-- docs/getting_started_build_tools.md | 6 +++--- docs/zh-cn/faq_build.md | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/faq_build.md b/docs/faq_build.md index 0c1bedd715..23d6a67021 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -140,8 +140,8 @@ For now, you need to rollback avr-gcc to 7 in brew. ``` brew uninstall --force avr-gcc -brew install avr-gcc@7 -brew link --force avr-gcc@7 +brew install avr-gcc@8 +brew link --force avr-gcc@8 ``` ### I just flashed my keyboard and it does nothing/keypresses don't register - it's also ARM (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019) diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md index 0e1acca66a..268cc94c38 100644 --- a/docs/getting_started_build_tools.md +++ b/docs/getting_started_build_tools.md @@ -62,14 +62,14 @@ If you're using [homebrew,](http://brew.sh/) you can use the following commands: brew tap osx-cross/avr brew tap PX4/homebrew-px4 brew update - brew install avr-gcc@7 - brew link --force avr-gcc@7 + brew install avr-gcc@8 + brew link --force avr-gcc@8 brew install dfu-programmer brew install dfu-util brew install gcc-arm-none-eabi brew install avrdude -This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of `avr-gcc@7` can take over 20 minutes and exhibit high CPU usage. +This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of `avr-gcc@8` can take over 20 minutes and exhibit high CPU usage. ## Windows with msys2 (recommended) diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md index 60d902007c..8fb449db30 100644 --- a/docs/zh-cn/faq_build.md +++ b/docs/zh-cn/faq_build.md @@ -137,8 +137,8 @@ brew install avrdude ``` brew uninstall --force avr-gcc -brew install avr-gcc@7 -brew link --force avr-gcc@7 +brew install avr-gcc@8 +brew link --force avr-gcc@8 ``` ### 我刷新了我的键盘但是键盘不工作/按键没有注册 - 而且还是ARM的 (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019) -- cgit v1.2.3 From 91b0c75045c38a9c770f7835b928b3b298a1ff8f Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Thu, 6 Jun 2019 01:01:24 -0400 Subject: Add meta tags for docs --- docs/index.html | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index d6fdbdbcc1..995d6b8f87 100644 --- a/docs/index.html +++ b/docs/index.html @@ -5,7 +5,11 @@ QMK Firmware - + + + + + -- cgit v1.2.3 From 834a8d1da18688eefe3e9e01f75f3e936f156e10 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Thu, 6 Jun 2019 01:07:54 -0400 Subject: add type:object to docs meta info (github uses it) --- docs/index.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index 995d6b8f87..77a8085bfc 100644 --- a/docs/index.html +++ b/docs/index.html @@ -7,7 +7,8 @@ - + + -- cgit v1.2.3 From fe6b8edd581c334a92a97c15faced95a12d5e882 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Thu, 6 Jun 2019 01:23:18 -0400 Subject: use twitter card large setting for larger previews --- docs/index.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index 77a8085bfc..8190450728 100644 --- a/docs/index.html +++ b/docs/index.html @@ -7,10 +7,11 @@ - + + -- cgit v1.2.3 From faaaa134fd436be400aa2c7841b38907899d49a6 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Thu, 6 Jun 2019 12:09:56 -0700 Subject: Replace DEBOUNCING_DELAY (deprecated) with DEBOUNCE (#5997) --- docs/config_options.md | 2 +- docs/feature_bootmagic.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index cab3c0747a..f4035809a7 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -83,7 +83,7 @@ This is a C header file that is one of the first things included, and will persi * enables backlight breathing (only works with backlight pins B5, B6 and B7) * `#define BREATHING_PERIOD 6` * the length of one backlight "breath" in seconds -* `#define DEBOUNCING_DELAY 5` +* `#define DEBOUNCE 5` * the delay when reading the value of the pin (5 is default) * `#define LOCKING_SUPPORT_ENABLE` * mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index 39e4e47f4e..225189ccb7 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -140,7 +140,7 @@ To replace the function, all you need to do is add something like this to your c ```c void bootmagic_lite(void) { matrix_scan(); - wait_ms(DEBOUNCING_DELAY * 2); + wait_ms(DEBOUNCE * 2); matrix_scan(); if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) { -- cgit v1.2.3 From 09968ba035f3bfa4df5b1d142dddfa669aefb2d7 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Fri, 7 Jun 2019 19:02:05 -0500 Subject: Fixing OLED Driver for 128x64 displays (#6085) --- docs/feature_oled_driver.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index fcc19515a9..144b695b76 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -108,10 +108,11 @@ void oled_task_user(void) { |`OLED_DISPLAY_CUSTOM` |*Not defined* |Changes the display defines for use with custom displays.
Requires user to implement the below defines. | |`OLED_DISPLAY_WIDTH` |`128` |The width of the OLED display. | |`OLED_DISPLAY_HEIGHT` |`32` |The height of the OLED display. | -|`OLED_MATRIX_SIZE` |`512` |The local buffer size to allocate.
`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`| -|`OLED_BLOCK_TYPE` |`uint16_t` |The unsigned integer type to use for dirty rendering.| -|`OLED_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.
`(sizeof(OLED_BLOCK_TYPE) * 8)`| -|`OLED_BLOCK_SIZE` |`32` |The size of each block for dirty rendering
`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`| +|`OLED_MATRIX_SIZE` |`512` |The local buffer size to allocate.
`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`. | +|`OLED_BLOCK_TYPE` |`uint16_t` |The unsigned integer type to use for dirty rendering. | +|`OLED_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.
`(sizeof(OLED_BLOCK_TYPE) * 8)`. | +|`OLED_BLOCK_SIZE` |`32` |The size of each block for dirty rendering
`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`. | +|`OLED_COM_PINS` |`COM_PINS_SEQ` |How the SSD1306 chip maps it's memory to display.
Options are `COM_PINS_SEQ`, `COM_PINS_ALT`, `COM_PINS_SEQ_LR`, & `COM_PINS_ALT_LR`. | |`OLED_SOURCE_MAP` |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering. | |`OLED_TARGET_MAP` |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering. | -- cgit v1.2.3 From bba5c09b23208f7c70b1062b695a5b3df492b329 Mon Sep 17 00:00:00 2001 From: Chris Scheib Date: Tue, 11 Jun 2019 17:42:53 -0400 Subject: [Docs] Update feature_rgb_matrix.md (#6117) * Update feature_rgb_matrix.md fix indentation on code comments * Update feature_rgb_matrix.md more formatting changes, missed these the first time --- docs/feature_rgb_matrix.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 8f0cd12b3c..916fcdce03 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -42,11 +42,11 @@ Define these arrays listing all the LEDs in your `.c`: ```C const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { /* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ + * driver + * | R location + * | | G location + * | | | B location + * | | | | */ {0, C1_3, C2_3, C3_3}, .... } @@ -93,11 +93,11 @@ Define these arrays listing all the LEDs in your `.c`: ```C const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { /* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ + * driver + * | R location + * | | G location + * | | | B location + * | | | | */ {0, B_1, A_1, C_1}, .... } -- cgit v1.2.3 From e6a81133dd3d0d4076a08be76340f905fdbf7c7f Mon Sep 17 00:00:00 2001 From: "Michael F. Lamb" Date: Tue, 11 Jun 2019 15:27:17 -0700 Subject: Add SH1106 OLED support (#5787) * modify oled_driver to support SH1106 also: - improve mechanism to specify which OLED IC we use - comment calc_bounds() - give OLED_COLUMN_OFFSET a default value - inline comment re: OLED MEMORY_MODE and SH1106 - update docs/feature_oled_driver.h for SH1106 support and related changes - docs: OLED: note we have tested SSD1306 on ARM boards (per @XScorpion2) - define out MEMORY_MODE when using SH1106 OLED driver * document that SSD1306 128x64 on AVR works Per @XScorpion2: https://github.com/qmk/qmk_firmware/pull/5787#discussion_r291837842 --- docs/feature_oled_driver.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index 144b695b76..155dfa9d29 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -2,7 +2,17 @@ ## OLED Supported Hardware -128x32 OLED modules using SSD1306 driver IC over I2C. Supported on AVR based keyboards. Possible but untested hardware includes ARM based keyboards and other sized OLED modules using SSD1306 over I2C, such as 128x64. +OLED modules using SSD1306 or SH1106 driver ICs, communicating over I2C. +Tested combinations: + +| IC driver | Size | Keyboard Platform | Notes | +|-----------|--------|-------------------|--------------------------| +| SSD1306 | 128x32 | AVR | Primary support | +| SSD1306 | 128x64 | AVR | Verified working | +| SSD1306 | 128x32 | ARM | | +| SH1106 | 128x64 | AVR | No rotation or scrolling | + +Hardware configurations using ARM-based microcontrollers or different sizes of OLED modules may be compatible, but are untested. !> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses i2c to communication between sides this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. @@ -86,17 +96,17 @@ void oled_task_user(void) { ## Basic Configuration -|Define |Default |Description | -|-----------------------|---------------|------------------------------------------------| -|`OLED_DISPLAY_ADDRESS` |`0x3C` |The i2c address of the OLED Display | -|`OLED_FONT_H` |`"glcdfont.c"` |The font code file to use for custom fonts | -|`OLED_FONT_START` |`0` |The starting characer index for custom fonts | -|`OLED_FONT_END` |`224` |The ending characer index for custom fonts | -|`OLED_FONT_WIDTH` |`6` |The font width | -|`OLED_FONT_HEIGHT` |`8` |The font height (untested) | -|`OLED_DISABLE_TIMEOUT` |*Not defined* |Disables the built in OLED timeout feature. Useful when implementing custom timeout rules.| - - +| Define | Default | Description | +|------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------| +| `OLED_DISPLAY_ADDRESS` | `0x3C` | The i2c address of the OLED Display | +| `OLED_FONT_H` | `"glcdfont.c"` | The font code file to use for custom fonts | +| `OLED_FONT_START` | `0` | The starting characer index for custom fonts | +| `OLED_FONT_END` | `224` | The ending characer index for custom fonts | +| `OLED_FONT_WIDTH` | `6` | The font width | +| `OLED_FONT_HEIGHT` | `8` | The font height (untested) | +| `OLED_DISABLE_TIMEOUT` | *Not defined* | Disables the built in OLED timeout feature. Useful when implementing custom timeout rules. | +| `OLED_IC` | `OLED_IC_SSD1306` | Set to `OLED_IC_SH1106` if you're using the SH1106 OLED controller. | +| `OLED_COLUMN_OFFSET` | `0` | (SH1106 only.) Shift output to the right this many pixels.
Useful for 128x64 displays centered on a 132x64 SH1106 IC. | ## 128x64 & Custom sized OLED Displays @@ -119,6 +129,8 @@ void oled_task_user(void) { ### 90 Degree Rotation - Technical Mumbo Jumbo +!> Rotation is unsupported on the SH1106. + ```C // OLED Rotation enum values are flags typedef enum { @@ -250,6 +262,8 @@ uint8_t oled_max_chars(void); uint8_t oled_max_lines(void); ``` +!> Scrolling and rotation are unsupported on the SH1106. + ## SSD1306.h driver conversion guide |Old API |Recommended New API | -- cgit v1.2.3 From 6bdcbfb25ae068d9f5351af0f7c6a03385020661 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Tue, 18 Jun 2019 12:37:17 +1000 Subject: Fix backlight breathing on C6 (#6102) * Fix backlight breathing on C6 * Account for ATmega32A's single TIMSK register (MT40) * Document hardware PWM on D4 for ATmega32A * Add C6 and D4 to BACKLIGHT_PIN description --- docs/config_options.md | 2 +- docs/feature_backlight.md | 15 ++++++++------- 2 files changed, 9 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index f4035809a7..55d25d4c88 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -76,7 +76,7 @@ This is a C header file that is one of the first things included, and will persi * `#define B7_AUDIO` * enables audio on pin B7 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO) * `#define BACKLIGHT_PIN B7` - * pin of the backlight - B5, B6, B7 use PWM, others use softPWM + * pin of the backlight - `B5`, `B6`, `B7` and `C6` (and `D4` on ATmega32A) use hardware PWM, others use software implementation * `#define BACKLIGHT_LEVELS 3` * number of levels your backlight will have (maximum 15 excluding off) * `#define BACKLIGHT_BREATHING` diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index 048d75390d..5a21a67901 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -34,13 +34,14 @@ Hardware PWM is only supported on certain pins of the MCU, so if the backlightin Hardware PWM is supported according to the following table: -| Backlight Pin | Hardware timer | -|---------------|----------------| -|`B5` | Timer 1 | -|`B6` | Timer 1 | -|`B7` | Timer 1 | -|`C6` | Timer 3 | -| other | Software PWM | +| Backlight Pin | Hardware timer | +|---------------|-------------------------| +|`B5` | Timer 1 | +|`B6` | Timer 1 | +|`B7` | Timer 1 | +|`C6` | Timer 3 | +|`D4` | Timer 1 (ATmega32A only)| +| other | Software PWM | The [audio feature](feature_audio.md) also uses hardware timers. Please refer to the following table to know what hardware timer the software PWM will use depending on the audio configuration: -- cgit v1.2.3 From 810c8db7706f40f0436555fdffbaf849dc0a5641 Mon Sep 17 00:00:00 2001 From: Danny Date: Thu, 20 Jun 2019 01:02:20 -0400 Subject: Set default I2C clock speed to 100kHz for split_common (#6161) * Set default I2C clock rate for split_common boards to 100kHz Default from I2C driver is 400kHz. * Update documentation for setting I2C clock speed --- docs/config_options.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index 55d25d4c88..7418e8dbf9 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -93,8 +93,8 @@ This is a C header file that is one of the first things included, and will persi * key combination that allows the use of magic commands (useful for debugging) * `#define USB_MAX_POWER_CONSUMPTION` * sets the maximum power (in mA) over USB for the device (default: 500) -* `#define SCL_CLOCK 100000L` - * sets the SCL_CLOCK speed for split keyboards. The default is `100000L` but some boards can be set to `400000L`. +* `#define F_SCL 100000L` + * sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`. ## Features That Can Be Disabled -- cgit v1.2.3 From 317b8095647e208a7ac1ecf6b110051ca46553a8 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 20 Jun 2019 15:33:39 +1000 Subject: Fix breathing always on for soft PWM (#5983) * Fix breathing always on for soft PWM * Remove reference to hardware PWM pins in BACKLIGHT_BREATHING description Now, breathing will only be unsupported when Timers 1 and 3 are both used by Audio * Document BACKLIGHT_ON_STATE and its purpose --- docs/config_options.md | 2 +- docs/feature_backlight.md | 10 ++++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index 7418e8dbf9..eb0a441ccc 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -80,7 +80,7 @@ This is a C header file that is one of the first things included, and will persi * `#define BACKLIGHT_LEVELS 3` * number of levels your backlight will have (maximum 15 excluding off) * `#define BACKLIGHT_BREATHING` - * enables backlight breathing (only works with backlight pins B5, B6 and B7) + * enables backlight breathing * `#define BREATHING_PERIOD 6` * the length of one backlight "breath" in seconds * `#define DEBOUNCE 5` diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index 5a21a67901..b06db89e4d 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -64,11 +64,17 @@ To change the behaviour of the backlighting, `#define` these in your `config.h`: |Define |Default |Description | |---------------------|-------------|-------------------------------------------------------------------------------------------------------------| |`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this| -|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information| +|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information | |`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 15 excluding off) | |`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) | -|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported | +|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported | |`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | +|`BACKLIGHT_ON_STATE` |`0` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low | + +## Backlight On State + +Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *low*. +Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case you must `#define BACKLIGHT_ON_STATE 1`, so that when the transistor is on, the pin is driven *high* instead. ## Multiple backlight pins -- cgit v1.2.3 From 1a442f9989c825cb42b41845658874f7f9e90ba7 Mon Sep 17 00:00:00 2001 From: lf Date: Mon, 24 Jun 2019 01:23:27 -0600 Subject: [Docs] Reword confusing description of `TO(layer)` (#6174) * Reword confusing description of `TO(layer)` * Update docs/keycodes.md Co-Authored-By: Drashna Jaelre --- docs/keycodes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/keycodes.md b/docs/keycodes.md index 3ff87856e4..bd4dd61a5b 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -298,7 +298,7 @@ This is a reference only. Each group of keys links to the page documenting their |`LM(layer, mod)`|Momentarily turn on `layer` (like MO) with `mod` active as well. Where `mod` is a mods_bit. Mods can be viewed [here](https://docs.qmk.fm/#/feature_advanced_keycodes?id=mod-tap). Example Implementation: `LM(LAYER_1, MOD_LALT)`| |`LT(layer, kc)` |Turn on `layer` when held, `kc` when tapped | |`TG(layer)` |Toggle `layer` on or off | -|`TO(layer)` |Turn on `layer` when pressed | +|`TO(layer)` |Turns on `layer` and turns off all other layers, except the default layer | |`TT(layer)` |Normally acts like MO unless it's tapped multiple times, which toggles `layer` on | ## [Mouse Keys](feature_mouse_keys.md) -- cgit v1.2.3 From c1c0cf73ce0ed4301d7f3d7af0b352d9385da896 Mon Sep 17 00:00:00 2001 From: shela Date: Mon, 1 Jul 2019 15:32:59 +0900 Subject: fix typo --- docs/feature_advanced_keycodes.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index a6ddf458cc..f748ccd70c 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -256,10 +256,10 @@ If you press a Mod Tap key, tap another key (press and release) and then release For Instance: -- `SHFT_T(KC_A)` Down +- `SFT_T(KC_A)` Down - `KC_X` Down - `KC_X` Up -- `SHFT_T(KC_A)` Up +- `SFT_T(KC_A)` Up Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`). @@ -279,9 +279,9 @@ Setting `Ignore Mod Tap Interrupt` requires holding both keys for the `TAPPING_ For Instance: -- `SHFT_T(KC_A)` Down +- `SFT_T(KC_A)` Down - `KC_X` Down -- `SHFT_T(KC_A)` Up +- `SFT_T(KC_A)` Up - `KC_X` Up Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output `X` (`SHIFT`+`x`). @@ -303,11 +303,11 @@ When the user holds a key after tap, this repeats the tapped key rather to hold Example: -- SHFT_T(KC_A) Down -- SHFT_T(KC_A) Up -- SHFT_T(KC_A) Down +- SFT_T(KC_A) Down +- SFT_T(KC_A) Up +- SFT_T(KC_A) Down - wait more than tapping term... -- SHFT_T(KC_A) Up +- SFT_T(KC_A) Up With default settings, `a` will be sent on the first release, then `a` will be sent on the second press allowing the computer to trigger its auto repeat function. -- cgit v1.2.3 From d16db6936715a98b6ae769463d5ccafab25b7203 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Sat, 6 Jul 2019 23:00:05 -0500 Subject: Added mod carry over from press to release. (#5866) Update docs/feature_space_cadet.md Co-Authored-By: fauxpark --- docs/feature_space_cadet.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/feature_space_cadet.md b/docs/feature_space_cadet.md index 075578522e..41a44627e3 100644 --- a/docs/feature_space_cadet.md +++ b/docs/feature_space_cadet.md @@ -43,6 +43,7 @@ By default Space Cadet assumes a US ANSI layout, but if your layout uses differe |`LAPO_KEYS` |`KC_LALT, KC_LSFT, KC_9` |Send `KC_LALT` when held, the mod `KC_LSFT` with the key `KC_9` when tapped. | |`RAPC_KEYS` |`KC_RALT, KC_RSFT, KC_0` |Send `KC_RALT` when held, the mod `KC_RSFT` with the key `KC_0` when tapped. | |`SFTENT_KEYS` |`KC_RSFT, KC_TRNS, SFTENT_KEY` |Send `KC_RSFT` when held, no mod with the key `SFTENT_KEY` when tapped. | +|`SPACE_CADET_MODIFIER_CARRYOVER` |*Not defined* |Store current modifiers before the hold mod is pressed and use them with the tap mod and keycode. Useful for when you frequently release a modifier before triggering Space Cadet. | ## Obsolete Configuration -- cgit v1.2.3 From 6e6d079dd21f766191f60db062fae8889623ded1 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Mon, 8 Jul 2019 08:28:31 -0500 Subject: Updated OLED Docs with notes about screen timeout. (#6276) * Updated OLED Docs with notes about screen timeout. * Update docs/feature_oled_driver.md Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com> --- docs/feature_oled_driver.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index 155dfa9d29..503e438288 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -14,7 +14,7 @@ Tested combinations: Hardware configurations using ARM-based microcontrollers or different sizes of OLED modules may be compatible, but are untested. -!> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses i2c to communication between sides this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. +!> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses I2C to communicate between sides, this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. In addition, the display timeout system to reduce OLED burn-in also uses split common to detect keypresses, so you will need to implement custom timeout logic for non-split common keyboards. ## Usage -- cgit v1.2.3 From ecf0612cc8ed9458e30f7feafe6b3f7bb6985788 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Fri, 12 Jul 2019 04:33:55 +1000 Subject: [Docs] Clarify the rules.mk setup for Unicode (#6286) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Clarify the rules.mk setup for Unicode * code point Co-Authored-By: Konstantin Đorđević * Remove "your" Co-Authored-By: Konstantin Đorđević * Undo a line change Co-Authored-By: Konstantin Đorđević * dot the comma Co-Authored-By: Konstantin Đorđević * Update docs/feature_unicode.md Co-Authored-By: Konstantin Đorđević --- docs/feature_unicode.md | 68 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 45 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/feature_unicode.md b/docs/feature_unicode.md index 778cdc69cb..bd1f4fa5ae 100644 --- a/docs/feature_unicode.md +++ b/docs/feature_unicode.md @@ -1,28 +1,44 @@ # Unicode Support -There are three Unicode keymap definition methods available in QMK: +Unicode characters can be input straight from your keyboard! There are some limitations, however. -## `UNICODE_ENABLE` +QMK has three different methods for enabling Unicode input and defining keycodes: -Supports Unicode up to `0x7FFF`. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji. The keycode function is `UC(c)` in the keymap, where _c_ is the code point's number (preferably hexadecimal, up to 4 digits long). For example: `UC(0x45B)`, `UC(0x30C4)`. +## Basic Unicode -## `UNICODEMAP_ENABLE` +This method supports Unicode code points up to `0x7FFF`. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji. -Supports Unicode up to `0x10FFFF` (all possible code points). You need to maintain a separate mapping table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file. The keycode function is `X(i)`, where _i_ is an array index into the mapping table. The table may contain at most 16384 entries. +Add the following to your `rules.mk`: -You may want to have an enum to make referencing easier. So, you could add something like this to your keymap file: +```make +UNICODE_ENABLE = yes +``` + +Then add `UC(c)` keycodes to your keymap, where _c_ is the code point (preferably in hexadecimal, up to 4 digits long). For example: `UC(0x45B)`, `UC(0x30C4)`. + +## Unicode Map + +This method supports all possible code points (up to `0x10FFFF`); however, you need to maintain a separate mapping table in your keymap file, which may contain at most 16384 entries. + +Add the following to your `rules.mk`: + +```make +UNICODEMAP_ENABLE = yes +``` + +Then add `X(i)` keycodes to your keymap, where _i_ is an array index into the mapping table: ```c enum unicode_names { - BANG, - IRONY, - SNEK, + BANG, + IRONY, + SNEK }; const uint32_t PROGMEM unicode_map[] = { - [BANG] = 0x203D, // ‽ - [IRONY] = 0x2E2E, // ⸮ - [SNEK] = 0x1F40D, // 🐍 + [BANG] = 0x203D, // ‽ + [IRONY] = 0x2E2E, // ⸮ + [SNEK] = 0x1F40D, // 🐍 }; ``` @@ -30,27 +46,33 @@ Then you can use `X(BANG)`, `X(SNEK)` etc. in your keymap. ### Lower and Upper Case -Characters often come in lower and upper case pairs, for example: å, Å. To make inputting these characters easier, you can use `XP(i, j)` in your keymap, where _i_ and _j_ are the mapping table indices of the lower and upper case character, respectively. If you're holding down Shift or have Caps Lock turned on when you press the key, the second (upper case) character will be inserted; otherwise, the first (lower case) version will appear. +Characters often come in lower and upper case pairs, such as å and Å. To make inputting these characters easier, you can use `XP(i, j)` in your keymap, where _i_ and _j_ are the mapping table indices of the lower and upper case character, respectively. If you're holding down Shift or have Caps Lock turned on when you press the key, the second (upper case) character will be inserted; otherwise, the first (lower case) version will appear. -This is most useful when creating a keymap for an international layout with special characters. Instead of having to put the lower and upper case versions of a character on separate keys, you can have them both on the same key by using `XP`. This blends Unicode keys in with regular alphas. +This is most useful when creating a keymap for an international layout with special characters. Instead of having to put the lower and upper case versions of a character on separate keys, you can have them both on the same key by using `XP()`. This helps blend Unicode keys in with regular alphas. Due to keycode size constraints, _i_ and _j_ can each only refer to one of the first 128 characters in your `unicode_map`. In other words, 0 ≤ _i_ ≤ 127 and 0 ≤ _j_ ≤ 127. This is enough for most use cases, but if you'd like to customize the index calculation, you can override the [`unicodemap_index()`](https://github.com/qmk/qmk_firmware/blob/71f640d47ee12c862c798e1f56392853c7b1c1a8/quantum/process_keycode/process_unicodemap.c#L40) function. This also allows you to, say, check Ctrl instead of Shift/Caps. -## `UCIS_ENABLE` +## UCIS + +This method also supports all possible code points. As with the Unicode Map method, you need to maintain a mapping table in your keymap file. However, there are no built-in keycodes for this feature — you have to create a custom keycode or function that invokes this functionality. -Supports Unicode up to `0x10FFFF` (all possible code points). As with `UNICODEMAP`, you need to maintain a mapping table in your keymap file. However, there are no built-in keycodes for this feature — you have to add a keycode or function that calls `qk_ucis_start()`. Once this function has been called, you can type the corresponding mnemonic for your character, then hit Space or Enter to complete it, or Esc to cancel. If the mnemonic matches an entry in your table, the typed text will automatically be erased and the corresponding Unicode character inserted. +Add the following to your `rules.mk`: + +```make +UCIS_ENABLE = yes +``` -For instance, you could define a table like this in your keymap file: +Then define a table like this in your keymap file: ```c const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE( - UCIS_SYM("poop", 0x1F4A9), // 💩 - UCIS_SYM("rofl", 0x1F923), // 🤣 - UCIS_SYM("kiss", 0x1F619) // 😙 + UCIS_SYM("poop", 0x1F4A9), // 💩 + UCIS_SYM("rofl", 0x1F923), // 🤣 + UCIS_SYM("kiss", 0x1F619) // 😙 ); ``` -To use it, call `qk_ucis_start()`, then type "rofl" and hit Enter. QMK should erase the "rofl" text and insert the laughing emoji. +To use it, call `qk_ucis_start()`. Then, type the mnemonic for the character (such as "rofl"), and hit Space or Enter. QMK should erase the "rofl" text and insert the laughing emoji. ### Customization @@ -68,7 +90,7 @@ Unicode input in QMK works by inputting a sequence of characters to the OS, sort The following input modes are available: -* **`UC_OSX`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with `UNICODEMAP`). +* **`UC_OSX`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with Unicode Map). To enable, go to _System Preferences > Keyboard > Input Sources_, add _Unicode Hex Input_ to the list (it's under _Other_), then activate it from the input dropdown in the Menu Bar. By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_OSX`](#input-key-configuration) with another keycode. @@ -112,7 +134,7 @@ You can also switch the input mode by calling `set_unicode_input_mode(x)` in you ```c void eeconfig_init_user(void) { - set_unicode_input_mode(UC_LNX); + set_unicode_input_mode(UC_LNX); } ``` -- cgit v1.2.3 From 663ca6ba9db59e05f1ba057ad4c0e3ff3cb0cff1 Mon Sep 17 00:00:00 2001 From: Phil Schalm Date: Fri, 12 Jul 2019 05:42:21 -0700 Subject: Documentation: Newbs Flashing: Hightlight that sudo may be needed (#6300) * Hightlight that sudo may be needed Also added "dfu-programmer: no device present" in so that anyone searching for that particular error can hopefully find the page. * Use new style of indicating a warning * Indicate that the FAQ should be read instead of blindly using sudo --- docs/newbs_flashing.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/newbs_flashing.md b/docs/newbs_flashing.md index a985e5d2b2..fa0a5e2ba5 100644 --- a/docs/newbs_flashing.md +++ b/docs/newbs_flashing.md @@ -127,9 +127,7 @@ Once it does this, you'll want to reset the controller. It should then show out >>> dfu-programmer atmega32u4 reset ``` -If you have any issues with this, you may need to this: - - sudo make ::dfu +?> If you have any issues with this - such as `dfu-programmer: no device present` - please see the [Frequently Asked Build Questions](faq_build.md). #### DFU commands -- cgit v1.2.3