diff options
Diffstat (limited to 'docs/zh-cn')
| -rw-r--r-- | docs/zh-cn/README.md | 4 | ||||
| -rw-r--r-- | docs/zh-cn/custom_quantum_functions.md | 324 | ||||
| -rw-r--r-- | docs/zh-cn/faq_build.md | 28 | ||||
| -rw-r--r-- | docs/zh-cn/faq_debug.md | 68 | ||||
| -rw-r--r-- | docs/zh-cn/faq_keymap.md | 63 | ||||
| -rw-r--r-- | docs/zh-cn/getting_started_github.md | 22 | ||||
| -rw-r--r-- | docs/zh-cn/getting_started_introduction.md | 2 |
7 files changed, 180 insertions, 331 deletions
diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md index 9eb4ea777a..bb7e0130f0 100644 --- a/docs/zh-cn/README.md +++ b/docs/zh-cn/README.md @@ -19,7 +19,7 @@ QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包 ## 如何编译 -在你能编译之前, 你需要[部署环境](getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: +在你能编译之前, 你需要[部署环境](zh-cn/getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: make planck/rev4:default @@ -29,4 +29,4 @@ QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包 ## 如何定制 -QMK 有许多 [特性](features.md)来探索，也有很多 [参考文档](http://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](keymap.md)和[键码](keycodes.md)来利用许多特性。 +QMK 有许多 [特性](zh-cn/features.md)来探索，也有很多 [参考文档](http://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](zh-cn/keymap.md)和[键码](zh-cn/keycodes.md)来利用许多特性。 diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md index 42ceba9cac..f2c6098dcb 100644 --- a/docs/zh-cn/custom_quantum_functions.md +++ b/docs/zh-cn/custom_quantum_functions.md @@ -1,31 +1,31 @@ -# ζ̵Ĺ +# 如何定制你键盘的功能 -ںܶ˵ƻ̿ɲֻĵԷ㰴Ǹô϶ʵֱȼͺӵĹܡQMKעĹ, ǹ, ⣬ԶڲͬµΪ +对于很多人来说客制化键盘可不只是向你的电脑发送你按了那个件这么简单。你肯定想实现比简单按键和宏更复杂的功能。QMK有能让你注入代码的钩子, 覆盖功能, 另外，还可以自定义键盘在不同情况下的行为。 -ҳٶκQMK֪ʶĶ[QMK](understanding_qmk.md)ڸIJⷢʲô +本页不假定任何特殊的QMK知识，但阅读[理解QMK](understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。 -## A Word on Core vs vs +## A Word on Core vs 键盘 vs 布局 -ǰqmk֯һνṹ +我们把qmk组织成一个层次结构： * Core (`_quantum`) * Keyboard/Revision (`_kb`) * Keymap (`_user`) -ÿһڶϼһ`_kb()` `_user()` ڼ/ʹ`_kb()`ڲֲʹ`_user()` +下面描述的每一个函数都可以在定义上加一个`_kb()`或 `_user()` 后缀。 建议在键盘/修订层使用`_kb()`后缀，在布局层使用`_user()`后缀。 -ڼ/㶨庯ʱ`_kb()`ִκδǰȵ`_user()`DZҪģȻֲ㺯ͲҪá -<!-- ⣺Ǿ䷭IJ̫--> -# Զ +在键盘/修订层定义函数时，`_kb()`在执行任何代码前先调用`_user()`是必要的，不然布局层函数就不要被调用。 +<!-- 翻译问题：上面那句翻译的不太好--> +# 自定义键码 -ĿǰΪֹǸмΪµļ롣ӴǶЩơ +到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。 -## һ¼ +## 定义一个新键码 -һöٳȫҲǸֲΨһֵQMKûֱֵСṩһ`SAFE_RANGE`ꡣöʱ`SAFE_RANGE`֤ȡΨһļֵ +创建键码第一步，先枚举出它全部，也就是给键码起个名字并分配唯一数值。QMK没有直接限制最大键码值大小，而是提供了一个`SAFE_RANGE`宏。你可以在枚举时用`SAFE_RANGE`来保证你取得了唯一的键码值。 -öӡӵ`keymap.c`Ļڲ`FOO``BAR`ˡ +这有枚举两个键码的例子。把这块加到`keymap.c`的话你就在布局中能用`FOO`和`BAR`了。 ```c enum my_keycodes { @@ -34,46 +34,46 @@ enum my_keycodes { }; ``` -## ΪΪ +## 为键码的行为编程 -㸲һѴڰΪʱΪ¼ʱҪ`process_record_kb()``process_record_user()`ڼʵ¼ǰQMKá`true`QMKķʽ롣ԺܷչĹܶ滻`false` QMKȻͼ̧ǰ¼ˡ +当你覆盖一个已存在按键的行为时，或将这个行为赋给新键时，你要用`process_record_kb()`和`process_record_user()`函数。这俩函数在键处理中真实键事件被处理前被QMK调用。如果这俩函数返回`true`，QMK将会用正常的方式处理键码。这样可以很方便的扩展键码的功能而不是替换它。如果函数返回`false` QMK会跳过正常键处理，然后发送键子抬起还是按下事件就由你决定了。 -ij»ͷʱᱻá +当某个键按下或释放时这俩函数会被调用。 -### process_record_user()`ʾʵ +### process_record_user()`函数示例实现 -¡Զһ`FOO`ļΪڰ»سʱ +这个例子做了两个事。自定义了一个叫做`FOO`的键码的行为，并补充了在按下回车时播放音符。 ```c bool process_record_user(uint16_t keycode, keyrecord_t *record) { switch (keycode) { case FOO: if (record->event.pressed) { - // ʱЩʲô + // 按下时做些什么 } else { - // ͷʱЩʲô + // 释放时做些什么 } - return false; // ˼нһ + return false; // 跳过此键的所有进一步处理 case KC_ENTER: - // »سʱ + // 当按下回车时播放音符 if (record->event.pressed) { PLAY_NOTE_ARRAY(tone_qwerty); } - return true; // QMKس/ͷ¼ + return true; // 让QMK触发回车按下/释放事件 default: - return true; // + return true; // 正常处理其他键码 } } ``` -### `process_record_*` ĵ +### `process_record_*` 函数文档 -* /: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` -* : `bool process_record_user(uint16_t keycode, keyrecord_t *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` Щ¼ +`keycode(键码)`参数是在布局上定义的，比如`MO(1)`, `KC_L`, 等等。 你要用 `switch...case` 块来处理这些事件。 -`record`ʵʰϢ +`record`参数含有实际按键的信息： ```c keyrecord_t record { @@ -88,9 +88,9 @@ keyrecord_t record { } ``` -# LED +# LED控制 -qmkṩ˶ȡHID淶5LEDķ: +qmk提供了读取HID规范包含的5个LED的方法。: * `USB_LED_NUM_LOCK` * `USB_LED_CAPS_LOCK` @@ -98,20 +98,20 @@ qmkṩ˶ȡHID淶5LEDķ: * `USB_LED_COMPOSE` * `USB_LED_KANA` -ӦLED״̬λλ -ַԻLED״̬ +这五个常量对应于主机LED状态的位置位。 +有两种方法可以获得主机LED状态： -* ִͨ `led_set_user()` -* ͨ `host_keyboard_leds()` +* 通过执行 `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״̬ +当5个LED中任何一个的状态需要改变时，此函数将被调用。此函数通过参数输入LED参数。 +使用`IS_LED_ON(usb_led, led_name)`和`IS_LED_OFF(usb_led, led_name)`这两个宏来检查LED状态。 -!> `host_keyboard_leds()`ܻ`led_set_user()`ǰֵ +!> `host_keyboard_leds()`可能会在`led_set_user()`被调用前返回新值。 -### `led_set_user()`ʾʵ +### `led_set_user()`函数示例实现 ```c void led_set_user(uint8_t usb_led) { @@ -143,59 +143,59 @@ void led_set_user(uint8_t usb_led) { } ``` -### `led_set_*`ĵ +### `led_set_*`函数文档 -* /: `void led_set_kb(uint8_t usb_led)` -* : `void led_set_user(uint8_t usb_led)` +* 键盘/修订: `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_set_*`之外读取LED状态时很有用，比如在[`matrix_scan_user()`](#矩阵扫描代码). +为了便捷，你可以用`IS_HOST_LED_ON(led_name)`和`IS_HOST_LED_OFF(led_name)` 宏，而不直接调用和检查`host_keyboard_leds()`。 -## LED״̬ +## 设置物理LED状态 -һЩʵΪLED״̬ṩ˷ķ +一些键盘实现了为设置物理LED的状态提供了方便的方法。 ### Ergodox Boards -Ergodoxʵṩ`ergodox_right_led_1`/`2`/`3_on`/`off()`ÿLED, Ҳ `ergodox_right_led_on`/`off(uint8_t led)` رǡ +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_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`(Ĭ). +Ergodox boards 同时定义了最低亮度级别`LED_BRIGHTNESS_LO`和最高亮度级别`LED_BRIGHTNESS_HI`(默认最高). -# ̳ʼ +# 键盘初始化代码 -̳ʼм衣ǸȡҪʲô +键盘初始化过程有几个步骤。你是用那个函数取决于你想要做什么。 -Ҫʼ˳г +有三个主要初始化函数，按调用顺序列出。 -* `keyboard_pre_init_*` - ڴǰСЩҪǰеӲʼ -* `matrix_init_*` - ڹ̼м䱻áʱӲѳʼδʼ -* `keyboard_post_init_*` - ڹ̼á£ġƻ붼Է +* `keyboard_pre_init_*` - 会在大多数其他东西运行前运行。适用于哪些需要提前运行的硬件初始化。 +* `matrix_init_*` - 在固件启动过程中间被调用。此时硬件已初始化，功能尚未初始化。 +* `keyboard_post_init_*` - 在固件启动过程最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。 -!> ڴ˵`keyboard_post_init_user`Ҫõĺ, ʱRGBƷ⡣ +!> 对于大多数人来说`keyboard_post_init_user`是你想要调用的函数。例如, 此时你可以设置RGB灯发光。 -## Ԥʼ +## 键盘预初始化代码 -뼫УUSBʼǰС +这代码极早运行，甚至都在USB初始化前运行。 -֮þͱʼˡ +在这之后不久矩阵就被初始化了。 -ڴû˵,òΪҪӲijʼ +对于大多数用户来说,这用不到，因为它主要是用于面向硬件的初始化。 -ӲʼĻٺò(ʼLEDһ). +但如果你有硬件初始化的话放在这里再好不过了(比如初始化LED引脚一类的). -### `keyboard_pre_init_user()`ʾʵ +### `keyboard_pre_init_user()`函数示例实现 -ڼ̼趨 B0, B1, B2, B3, B4 LEDš +本例中在键盘级别，设定 B0, B1, B2, B3, 和 B4 是LED引脚。 ```c void keyboard_pre_init_user(void) { - // üԤʼ + // 调用键盘预初始化代码 - // LEDΪģʽ + // 设置LED引脚为输出模式 setPinOutput(B0); setPinOutput(B1); setPinOutput(B2); @@ -204,73 +204,73 @@ void keyboard_pre_init_user(void) { } ``` -### `keyboard_pre_init_*` ĵ +### `keyboard_pre_init_*` 函数文档 -* /: `void keyboard_pre_init_kb(void)` -* : `void keyboard_pre_init_user(void)` +* 键盘/修订: `void keyboard_pre_init_kb(void)` +* 布局: `void keyboard_pre_init_user(void)` -## ʼ +## 矩阵初始化代码 -⽫ھʼʱãijЩӲúúһЩܱʼǰ +这将会在矩阵初始化时被调用，在某些硬件设置好后，但在一些功能被初始化前。 -طõĶʱãӲأҲλá +这在你设置其他地方会用到的东西的时候会很有用，但与硬件无关，也不依赖于它的启动位置。 -### `matrix_init_*`ĵ +### `matrix_init_*`函数文档 -* /: `void matrix_init_kb(void)` -* : `void matrix_init_user(void)` +* 键盘/修订: `void matrix_init_kb(void)` +* 布局: `void matrix_init_user(void)` -## ̺ʼ +## 键盘后初始化代码 -Ǽ̳ʼеһijЩԣãΪʱӦöǽгʼ +这是键盘初始化过程中的最后一个任务。如果您想更改某些特性，这会很有用，因为此时应该对它们进行初始化。 -### `keyboard_post_init_user()`ʾʵ +### `keyboard_post_init_user()`示例实现 -ʾгʼɺУRGBơ +本示例在所有初始化完成后运行，配置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); // ÿٺģʽ + // 调用后初始化代码 + rgblight_enable_noeeprom(); // 使能Rgb，不保存设置 + rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)不保存 + rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式不保存 } ``` -### `keyboard_post_init_*` ĵ +### `keyboard_post_init_*` 函数文档 -* /: `void keyboard_post_init_kb(void)` -* : `void keyboard_post_init_user(void)` +* 键盘/修订: `void keyboard_post_init_kb(void)` +* 布局: `void keyboard_post_init_user(void)` -# ɨ +# 矩阵扫描代码 -ܵĻҪ`process_record_*()`Զַ̣ʽӵ¼Уȷ벻Լ̲Ӱ졣Ȼڼ£бҪоɨ衣ЩҪرעܣΪÿٱ10Ρ +可能的话你要用`process_record_*()`自定义键盘，以这种方式连接到事件中，以确保代码不会对键盘产生负面的性能影响。然而，在极少数情况下，有必要进行矩阵扫描。在这些函数中要特别注意代码的性能，因为它每秒至少被调用10次。 -### `matrix_scan_*`ʾʵ +### `matrix_scan_*`示例实现 -ӱʡˡhookһܼе֮ǰӦ㹻˽qmkڲṹԱûʾ±дҪ[һissue](https://github.com/qmk/qmk_firmware/issues/new)[Discordǽ](https://discord.gg/Uq7gcHh). +这个例子被故意省略了。在hook这样一个对性能及其敏感的区域之前，您应该足够了解qmk的内部结构，以便在没有示例的情况下编写。如果你需要帮助，请[建立一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh). -### `matrix_scan_*` ĵ +### `matrix_scan_*` 函数文档 -* /: `void matrix_scan_kb(void)` -* : `void matrix_scan_user(void)` +* 键盘/修订: `void matrix_scan_kb(void)` +* 布局: `void matrix_scan_user(void)` -úÿξɨʱãMCUͬдҪΪкܶΡ +该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。 -ԶɨʱõҲԶ״̬(LEDƻĻ)ûҲ붨еĹܡ +你会在自定义矩阵扫描代码时用到这个函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户不输入你也想定期运行的功能。 -# / +# 键盘 空闲/唤醒 代码 -֧־ͿֹͨͣһƱﵽ""RGBƺͱǺܺõӡԽԼܺģҲ̷ζѡ +如果键盘支持就可以通过停止一大票功能来达到"空闲"。RGB灯和背光就是很好的例子。这可以节约能耗，也可能让你键盘风味更佳。 -: `suspend_power_down_*``suspend_wakeup_init_*`, ֱϵͳкͻʱá +用两个函数控制: `suspend_power_down_*`和`suspend_wakeup_init_*`, 分别在系统板空闲和唤醒时调用。 -### suspend_power_down_user()suspend_wakeup_init_user()ʾʵ +### suspend_power_down_user()和suspend_wakeup_init_user()示例实现 ```c @@ -283,18 +283,18 @@ void suspend_wakeup_init_user(void) { } ``` -### / ĵ +### 键盘 挂起/唤醒 函数文档 -* /: `void suspend_power_down_kb(void)` `void suspend_wakeup_init_user(void)` -* : `void suspend_power_down_kb(void)` `void suspend_wakeup_init_user(void)` +* 键盘/修订: `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_*` ʾʵ +### `layer_state_set_*` 示例实现 -ʹPlanckʾ [RGB](feature_rgblight.md)ʹ֮Ӧ +本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应 ```c uint32_t layer_state_set_user(uint32_t state) { @@ -318,31 +318,31 @@ uint32_t layer_state_set_user(uint32_t state) { return state; } ``` -### `layer_state_set_*` ĵ +### `layer_state_set_*` 函数文档 -* /: `uint32_t layer_state_set_kb(uint32_t state)` -* : `uint32_t layer_state_set_user(uint32_t state)` +* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)` +* 布局: `uint32_t layer_state_set_user(uint32_t state)` -`״̬`ǻbitmask, [ָ](keymap.md#ֵIJ״̬) +该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态) -# 籣 (EEPROM) +# 掉电保存配置 (EEPROM) -óڵıڼСЩñصEEPROM粻ʧ ÿ`eeconfig_read_kb``eeconfig_read_user`ȡ`eeconfig_update_kb``eeconfig_update_user`д롣ϣܹлĹܺ(лRGBָʾ⣬`eeconfig_init_kb``eeconfig_init_user`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存储和访问数据，并且并没有用哪种方法是“政治正确”的。你每个功能只有一个双字(四字节)空间。 -סEEPROMдġдܸߣDzֻдEEPROMСдƵMCU̡ +记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有设置写道EEPROM中。如果你写入频繁，你的MCU寿命将会变短。 -* ӣôϣʹԣΪ൱ӡ +* 如果您不理解这个例子，那么您可能希望避免使用这个特性，因为它相当复杂。 -### ʾʵ +### 示例实现 -ãҶдʹû֡һӵĺкܶҪʵϣʹ˺ܶ +本例讲解了如何添加设置，并且读写。本里使用了用户布局。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多上述函数来工作！ -keymap.cļУ´: +在你的keymap.c文件中，将以下代码添加至顶部: ```c typedef union { uint32_t raw; @@ -354,19 +354,19 @@ typedef union { user_config_t user_config; ``` -ϴ뽨һṹ壬ýṹԴ洢òдEEPROM㽫趨ΪڽṹȻ塣Ҫס`bool` ()ֵʹ1λ, `uint8_t`ʹ8λ, `uint16_t`ʹ16λԻϴʹã˳Ǵܻ鷳Ϊǻıддֵ +以上代码建立了一个结构体，该结构体可以存储设置并可用于写入EEPROM。如此这般将无需定义变量，因为在结构体中已然定义。要记住`bool` (布尔)值使用1位, `uint8_t`使用8位, `uint16_t`使用16位。你可以混合搭配使用，但是顺序记错可能会招致麻烦，因为那会改变写入写出的值。 - `layer_state_set_*`ʹ`rgb_layer_change`ʹ`keyboard_post_init_user``process_record_user`һС + `layer_state_set_*`函数中使用了`rgb_layer_change`，使用了`keyboard_post_init_user`和`process_record_user`来配置一切。 -Ҫʹ`keyboard_post_init_userҪ`eeconfig_read_user()`ոմĽṹ塣ȻʹṹIJеĹܡ +首先要使用`keyboard_post_init_user，你要加入`eeconfig_read_user()`来填充你刚刚创建的结构体。然后您可以立即使用这个结构来控制您的布局中的功能。就像这样： ```c void keyboard_post_init_user(void) { - // òּľʼ + // 调用布局级别的矩阵初始化 - // EEPROMû + // 从EEPROM读用户配置 user_config.raw = eeconfig_read_user(); - // ʹܣĬϲ + // 如使能，设置默认层 if (user_config.rgb_layer_change) { rgblight_enable_noeeprom(); rgblight_sethsv_noeeprom_cyan(); @@ -374,7 +374,7 @@ void keyboard_post_init_user(void) { } } ``` -ϺڶEEPROMúʹøĬϲRGBɫ"raw"ֵǴ"union"Ľṹתġ +以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。 ```c uint32_t layer_state_set_user(uint32_t state) { @@ -391,86 +391,86 @@ uint32_t layer_state_set_user(uint32_t state) { case _ADJUST: if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); } break; - default: // Ĭϲ + 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룬ʹʾرգ뽫Ϊ +这样仅在值使能时会改变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; // ˼Ľһ + return false; // 跳过此键的进一步处理 case KC_ENTER: - // ڰ»سʱ + // 在按下回车时播放音符 if (record->event.pressed) { PLAY_NOTE_ARRAY(tone_qwerty); } - return true; // QMKس/ͷ¼ - case RGB_LYR: // underglowΪָʾʹá + 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); // ô̸²ɫ + 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д + 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; // + return true; // 按其他键正常 } } ``` -Ҫ`eeconfig_init_user`ԵEEPROMʱָĬֵ, ԶǿEEPROM`EEP_RST`[Bootmagic](feature_bootmagic.md)磬ҪĬRGBָʾĬֵ +最后你要加入`eeconfig_init_user`函数，所以当EEPROM重置时，可以指定默认值, 甚至自定义操作。想强制重置EEPROM，请用`EEP_RST`键码或[Bootmagic](feature_bootmagic.md)函数。比如，如果要在默认情况下设置RGB层指示，并保存默认值 ```c -void eeconfig_init_user(void) { // EEPROM +void eeconfig_init_user(void) { // EEPROM正被重置 user_config.raw = 0; - user_config.rgb_layer_change = true; // ҪĬʹ - eeconfig_update_user(user_config.raw); // EEPROMдĬֵ + 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); // Ĭó + // use the non noeeprom versions, 还要向EEPROM写入这些值 + rgblight_enable(); // 默认使能RGB + rgblight_sethsv_cyan(); // 默认设置青色 + rgblight_mode(1); // 默认设置长亮 } ``` -ȻˡRGBָʾʱûһֱ棬¼̡ʹRGB룬ָʾʧܣˡ +然后就完事了。RGB层指示会在你想让它工作时工作。这个设置会一直保存，即便你拔下键盘。如果你使用其他RGB代码，层指示将失能，现在它可以做你所想了。 -### 'EECONFIG' ĵ +### '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)` +* 键盘/修订: `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λ(˫)ֵ +`val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会从EEPROM返回一个32位(双字)的值。 -# Զ-ٽֵ(TAPPING_TERM) -Ĭ,-ٽֵȫͳһģҲͨáڴû˵ܺáЩ£`LT`˵ʱ˫ܼΪЩļװסΪ˲ÿԶ룬ܿΪÿ`TAPPING_TERM` +# 自定义击键-长按临界值(TAPPING_TERM) +默认情况下,击键-长按临界值是全球统一的，并且不能通过键进行配置。对于大多数用户来说这很好。但是在有些情况下，对于`LT`键来说按键延时对双功能键的提升更大，可能是因为有些键比其他的键更容易按住。为了不给每个都自定义键码，本功能可以为每个键定义`TAPPING_TERM`。 -ʹܵĻ, Ҫ`config.h``#define TAPPING_TERM_PER_KEY` +想使能这个功能的话, 要先在`config.h`加上`#define TAPPING_TERM_PER_KEY`。 -## `get_tapping_term`ʾʵ +## `get_tapping_term`示例实现 -ҪĻڼ`TAPPING TERM`,Ҫ`keymap.c`ļ´: +想要修改基于键码的`TAPPING TERM`,你要向`keymap.c`文件添加如下代码: ```c uint16_t get_tapping_term(uint16_t keycode) { @@ -485,6 +485,6 @@ uint16_t get_tapping_term(uint16_t keycode) { } ``` -### `get_tapping_term` ĵ +### `get_tapping_term` 函数文档 -ƪ,Ҫquantum̼ĺֻҪûɡ +不像这篇的其他功能,这个不需要quantum或者键盘级别的函数，只要用户级函数即可。 diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md index 8fb449db30..0d9047bc59 100644 --- a/docs/zh-cn/faq_build.md +++ b/docs/zh-cn/faq_build.md @@ -56,11 +56,6 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" ?> 事实上没有一个驱动的最佳选择，有些选项就是和某些系统相辅相成。但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都没有问题，除了有极低的与其他产品发生冲突的可能性。 @@ -73,29 +68,6 @@ https://github.com/tmk/tmk_keyboard/issues/150 - 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注释错了。 diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md index a3cc7c510c..7eff7f2651 100644 --- a/docs/zh-cn/faq_debug.md +++ b/docs/zh-cn/faq_debug.md @@ -101,56 +101,6 @@ https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switc 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中使用它们。 @@ -173,24 +123,6 @@ EXTRAKEY_ENABLE = yes # 音频控制和系统控制 Arduino Leonardo和micro使用**ATMega32U4**，该芯片TMK可用，但Arduino的bootloader会导致问题。 -## 为锁定键添加指示灯 -你要自制CapsLock, ScrollLock 和 NumLock指示灯？见下文。 - -http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560 - -## 为Arduino Micro/Leonardo编程 -按下重置键然后在8秒内运行下方这样的命令。 - -``` -avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0 -``` - -设备名称因系统而异。 - -http://arduino.cc/en/Main/ArduinoBoardMicro -https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867 - - ## USB 3 兼容性 据传说有些人用USB3接口会有问题，用USB2的试试。 diff --git a/docs/zh-cn/faq_keymap.md b/docs/zh-cn/faq_keymap.md index ee8e3c06bf..7fb434b4c8 100644 --- a/docs/zh-cn/faq_keymap.md +++ b/docs/zh-cn/faq_keymap.md @@ -66,24 +66,8 @@ https://github.com/tmk/tmk_keyboard/issues/67 远古机械键盘偶尔会有自锁机械开关，现在几乎没有了。***大多数情况下你不需要使用该功能，且要使用`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**可以改用`compo |