From 829ccd3491ca43be79e110b12bdabe96d6e76b0f Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Sat, 20 Apr 2019 20:21:22 -0500 Subject: RGB Matrix docs update from mechmerlin discussion (#5667) * RGB Matrix docs update from mechmerlin discussion * alignment * Apply suggestions from code review Co-Authored-By: XScorpion2 --- docs/feature_rgb_matrix.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 05c1ebba81..acef4717dd 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -124,7 +124,7 @@ Configure the hardware via your `config.h`: --- -From this point forward the configuration is the same for all the drivers. +From this point forward the configuration is the same for all the drivers. The struct rgb_led array tells the system for each led, what key electrical matrix it represents, what the physical position is on the board, and if the led is for a modifier key or not. Here is a brief example: ```C const rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = { @@ -138,14 +138,14 @@ const rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = { } ``` -The format for the matrix position used in this array is `{row | (col << 4)}`. The `x` is between (inclusive) 0-224, and `y` is between (inclusive) 0-64. The easiest way to calculate these positions is: +The first part, `{row | col << 4}`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `{x=0..224, y=0..64}` represents the LED's physical position on the keyboard. The `x` is between (inclusive) 0-224, and `y` is between (inclusive) 0-64 as the effects are based on this range. 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 ) * ROW_POSITION -y = 64 / (NUMBER_OF_ROWS - 1 ) * COL_POSITION +x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION +y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION ``` -Where all variables are decimels/floats. +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. `modifier` is a boolean, whether or not a certain key is considered a modifier (used in some effects). -- cgit v1.2.3 From 066818f5f9cbee4ade1ea94ee167ee2df7d9e559 Mon Sep 17 00:00:00 2001 From: Erovia Date: Mon, 22 Apr 2019 17:26:41 +0200 Subject: Define RGB colors (#5300) * Define RGB colors Define RGB colors and pass them to the rgblight functions, instead of defining multiple macros. * Add new color definitions support for RGB Matrix * Add/clarify info about new color definitions in Docs * Add deprecation warning banner to rgblight_list.h --- docs/feature_rgb_matrix.md | 29 +++++++++++++++++++++++++++++ docs/feature_rgblight.md | 35 ++++++++++++++++++++++++++++++++++- 2 files changed, 63 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index acef4717dd..5309e749cb 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -236,6 +236,35 @@ void rgb_matrix_indicators_kb(void) { A similar function works in the keymap as `rgb_matrix_indicators_user`. + +## Colors + +These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. + +|RGB |HSV | +|-------------------|-------------------| +|`RGB_WHITE` |`HSV_WHITE` | +|`RGB_RED` |`HSV_RED` | +|`RGB_CORAL` |`HSV_CORAL` | +|`RGB_ORANGE` |`HSV_ORANGE` | +|`RGB_GOLDENROD` |`HSV_GOLDENROD` | +|`RGB_GOLD` |`HSV_GOLD` | +|`RGB_YELLOW` |`HSV_YELLOW` | +|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | +|`RGB_GREEN` |`HSV_GREEN` | +|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | +|`RGB_TURQUOISE` |`HSV_TURQUOISE` | +|`RGB_TEAL` |`HSV_TEAL` | +|`RGB_CYAN` |`HSV_CYAN` | +|`RGB_AZURE` |`HSV_AZURE` | +|`RGB_BLUE` |`HSV_BLUE` | +|`RGB_PURPLE` |`HSV_PURPLE` | +|`RGB_MAGENTA` |`HSV_MAGENTA` | +|`RGB_PINK` |`HSV_PINK` | + +These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list! + + ## Additional `config.h` Options ```C diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 97a9959946..48277373a5 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -191,7 +191,40 @@ If you need to change your RGB lighting in code, for example in a macro to chang |`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 | -Additionally, [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h) defines several predefined shortcuts for various colors. Feel free to add to this list! +## Colors + +These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. + +|RGB |HSV | +|-------------------|-------------------| +|`RGB_WHITE` |`HSV_WHITE` | +|`RGB_RED` |`HSV_RED` | +|`RGB_CORAL` |`HSV_CORAL` | +|`RGB_ORANGE` |`HSV_ORANGE` | +|`RGB_GOLDENROD` |`HSV_GOLDENROD` | +|`RGB_GOLD` |`HSV_GOLD` | +|`RGB_YELLOW` |`HSV_YELLOW` | +|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | +|`RGB_GREEN` |`HSV_GREEN` | +|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | +|`RGB_TURQUOISE` |`HSV_TURQUOISE` | +|`RGB_TEAL` |`HSV_TEAL` | +|`RGB_CYAN` |`HSV_CYAN` | +|`RGB_AZURE` |`HSV_AZURE` | +|`RGB_BLUE` |`HSV_BLUE` | +|`RGB_PURPLE` |`HSV_PURPLE` | +|`RGB_MAGENTA` |`HSV_MAGENTA` | +|`RGB_PINK` |`HSV_PINK` | + +```c +rgblight_setrgb(RGB_ORANGE); +rgblight_sethsv_noeeprom(HSV_GREEN); +rgblight_setrgb_at(RGB_GOLD, 3); +rgblight_sethsv_range(HSV_WHITE, 0, 6); +``` + +These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list! + ## Changing the order of the LEDs -- cgit v1.2.3 From b61baf4281bde34bfe28aaa1109bd5d5c6471116 Mon Sep 17 00:00:00 2001 From: Brice Figureau Date: Mon, 22 Apr 2019 11:34:13 -0400 Subject: Fix #3566 use an hardware timer for software PWM stability (#3615) With my XD60, I noticed that when typing the backlight was flickering. The XD60 doesn't have the backlight wired to a hardware PWM pin. I assumed it was a timing issue in the matrix scan that made the PWM lit the LED a bit too longer. I verified it because the more keys that were pressed, the more lighting I observed. This patch makes the software PWM be called during CPU interruptions. It works almost like the hardware PWM, except instead of using the CPU waveform generation, the CPU will fire interruption when the LEDs need be turned on or off. Using the same timer system as for hardware PWM, when the counter will reach OCRxx (the current backlight level), an Output Compare match interrupt will be fired and we'll turn the LEDs off. When the counter reaches its maximum value, an overflow interrupt will be triggered in which we turn the LEDs on. This way we replicate the hardware backlight PWM duty cycle. This gives a better time stability of the PWM computation than pure software PWM, leading to a flicker free backlight. Since this is reusing the hardware PWM code, software PWM also supports backlight breathing. Note that if timer1 is used for audio, backlight will use timer3, and if timer3 is used for audio backlight will use timer1. If both timers are used for audio, then this feature is disabled and we revert to the matrix scan based PWM computation. Signed-off-by: Brice Figureau --- docs/feature_backlight.md | 52 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index c7a1f131ed..048d75390d 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -30,7 +30,31 @@ You should then be able to use the keycodes below to change the backlight level. This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously use multiple different coloured LEDs on a keyboard. -Hardware PWM is only supported on certain pins of the MCU, so if the backlighting is not connected to one of them, a software implementation will be used, and backlight breathing will not be available. Currently the supported pins are `B5`, `B6`, `B7`, and `C6`. +Hardware PWM is only supported on certain pins of the MCU, so if the backlighting is not connected to one of them, a software PWM implementation triggered by hardware timer interrupts will be used. + +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 | + +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: + +| Audio Pin(s) | Audio Timer | Software PWM Timer | +|--------------|-------------|--------------------| +| `C4` | Timer 3 | Timer 1 | +| `C5` | Timer 3 | Timer 1 | +| `C6` | Timer 3 | Timer 1 | +| `B5` | Timer 1 | Timer 3 | +| `B6` | Timer 1 | Timer 3 | +| `B7` | Timer 1 | Timer 3 | +| `Bx` & `Cx` | Timer 1 & 3 | None | + +When all timers are in use for [audio](feature_audio.md), the backlight software PWM will not use a hardware timer, but instead will be triggered during the matrix scan. In this case the backlight doesn't support breathing and might show lighting artifacts (for instance flickering), because the PWM computation might not be called with enough timing precision. ## Configuration @@ -39,11 +63,26 @@ 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_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 hardware PWM is used | +|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported | |`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | +## Multiple backlight pins + +Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin). +In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle. +This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on. + +To activate multiple backlight pins, you need to add something like this to your user `config.h`: + +~~~c +#define BACKLIGHT_LED_COUNT 2 +#undef BACKLIGHT_PIN +#define BACKLIGHT_PINS { F5, B2 } +~~~ + ## Hardware PWM Implementation When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0. @@ -53,6 +92,15 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second. In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM. +## Software PWM Implementation + +When `BACKLIGHT_PIN` is not set to a hardware backlight pin, QMK will use a hardware timer configured to trigger software interrupts. This time will count up to `ICRx` (by default `0xFFFF`) before resetting to 0. +When resetting to 0, the CPU will fire an OVF (overflow) interrupt that will turn the LEDs on, starting the duty cycle. +The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the CPU will fire a Compare Output match interrupt, which will turn the LEDs off. +In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus the brightness, where `0x0000` is completely off and `0xFFFF` is completely on. + +The breathing effect is the same as in the hardware PWM implementation. + ## Backlight Functions |Function |Description | -- cgit v1.2.3 From bb52119a6dfe9c6f0314d1bcd948efda59626a70 Mon Sep 17 00:00:00 2001 From: M-AS Date: Mon, 22 Apr 2019 11:37:40 -0400 Subject: RGB Matrix Animations: Three/six new reactive effects (wide, cross, nexus) (#5602) * added 3 new RGB_Matrix effects * made cross effect behavior smoother * removed dead code * added effect descriptions --- docs/feature_rgb_matrix.md | 54 ++++++++++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 5309e749cb..f2168ab16e 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -189,6 +189,12 @@ enum rgb_matrix_effects { #if defined(RGB_MATRIX_KEYPRESSES) || defined(RGB_MATRIX_KEYRELEASES) RGB_MATRIX_SOLID_REACTIVE_SIMPLE, // Pulses keys hit to hue & value then fades value out RGB_MATRIX_SOLID_REACTIVE, // Static single hue, pulses keys hit to shifted hue then fades to current hue + RGB_MATRIX_SOLID_REACTIVE_WIDE // Hue & value pulse near a single key hit then fades value out + RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE // Hue & value pulse near multiple key hits then fades value out + RGB_MATRIX_SOLID_REACTIVE_CROSS // Hue & value pulse the same column and row of a single key hit then fades value out + RGB_MATRIX_SOLID_REACTIVE_MULTICROSS // Hue & value pulse the same column and row of multiple key hits then fades value out + RGB_MATRIX_SOLID_REACTIVE_NEXUS // Hue & value pulse away on the same column and row of a single key hit then fades value out + RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS // Hue & value pulse away on the same column and row of multiple key hits then fades value out RGB_MATRIX_SPLASH, // Full gradient & value pulse away from a single key hit then fades value out RGB_MATRIX_MULTISPLASH, // Full gradient & value pulse away from multiple key hits then fades value out RGB_MATRIX_SOLID_SPLASH, // Hue & value pulse away from a single key hit then fades value out @@ -201,27 +207,33 @@ enum rgb_matrix_effects { You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`: -|Define |Description | -|---------------------------------------------------|--------------------------------------------| -|`#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_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_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` | -|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Disables `RGB_MATRIX_RAINBOW_PINWHEELS` | -|`#define DISABLE_RGB_MATRIX_RAINDROPS` |Disables `RGB_MATRIX_RAINDROPS` | -|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS` | -|`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN` |Disables `RGB_MATRIX_DIGITAL_RAIN` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE` |Disables `RGB_MATRIX_SOLID_REACTIVE` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLEE`| -|`#define DISABLE_RGB_MATRIX_SPLASH` |Disables `RGB_MATRIX_SPLASH` | -|`#define DISABLE_RGB_MATRIX_MULTISPLASH` |Disables `RGB_MATRIX_MULTISPLASH` | -|`#define DISABLE_RGB_MATRIX_SOLID_SPLASH` |Disables `RGB_MATRIX_SOLID_SPLASH` | -|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` | +|Define |Description | +|-------------------------------------------------------|-----------------------------------------------| +|`#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_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_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` | +|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Disables `RGB_MATRIX_RAINBOW_PINWHEELS` | +|`#define DISABLE_RGB_MATRIX_RAINDROPS` |Disables `RGB_MATRIX_RAINDROPS` | +|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS` | +|`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN` |Disables `RGB_MATRIX_DIGITAL_RAIN` | +|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE` |Disables `RGB_MATRIX_SOLID_REACTIVE` | +|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` | +|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_WIDE` | +|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` | +|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_CROSS` | +|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`| +|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_NEXUS` | +|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`| +|`#define DISABLE_RGB_MATRIX_SPLASH` |Disables `RGB_MATRIX_SPLASH` | +|`#define DISABLE_RGB_MATRIX_MULTISPLASH` |Disables `RGB_MATRIX_MULTISPLASH` | +|`#define DISABLE_RGB_MATRIX_SOLID_SPLASH` |Disables `RGB_MATRIX_SOLID_SPLASH` | +|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` | ## Custom layer effects -- cgit v1.2.3 From 7ae2ded5901bedf2014e254db2b5292cdb72ffe4 Mon Sep 17 00:00:00 2001 From: ymzcdg <49898694+ymzcdg@users.noreply.github.com> Date: Wed, 24 Apr 2019 03:37:20 +0800 Subject: Translate docs into Chinese (#5693) * Docs translate Translate some docs to Standard Chinese for Chinese Developers. * fix translate fix translate --- docs/zh-cn/README.md | 32 +++++++++++++++ docs/zh-cn/_summary.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 docs/zh-cn/README.md create mode 100644 docs/zh-cn/_summary.md (limited to 'docs') diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md new file mode 100644 index 0000000000..9eb4ea777a --- /dev/null +++ b/docs/zh-cn/README.md @@ -0,0 +1,32 @@ +# QMK机械键盘固件 + +[![当前版本](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) +[![开发状态](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware) +[![异议](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh) +[![文档状态](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm) +[![GitHub贡献者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) +[![GitHub分支](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/) + +## 什么是 QMK 固件? + +QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包括 QMK 固件, QMK 工具箱, qmk.fm网站, 和这些文档。QMK 固件是一个基于[tmk\_keyboard](http://github.com/tmk/tmk_keyboard)的键盘固件，它在爱特梅尔AVR微控制器实现一些有用的功能,确切地说, 是在 [OLKB product line](http://olkb.com), 在 [ErgoDox EZ](http://www.ergodox-ez.com) 键盘, 和 [Clueboard product line](http://clueboard.co/). 上。它被移植到使用ChibiOS的ARM芯片上. 它可以在飞线键盘或定制PCB键盘中发挥功能. + +## 如何得到它 + +如果你打算贡献布局, 键盘, 或者其他QMK特性, 一下是最简单的方法：[从Github获得repo分支](https://github.com/qmk/qmk_firmware#fork-destination-box), 并克隆你的repo到本地进行编辑，推送，然后从你的分支打开 [Pull Request](https://github.com/qmk/qmk_firmware/pulls). + +此外, 你也可以直接下载 ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), 或者从git克隆 (`git@github.com:qmk/qmk_firmware.git`), 或 https (`https://github.com/qmk/qmk_firmware.git`). + +## 如何编译 + +在你能编译之前, 你需要[部署环境](getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: + + make planck/rev4:default + +这将建立 `planck`的`rev4` 修订版本并使用 `default`布局。并非所有键盘都有修订版本 (也叫做子项目或文件夹)，在此情况下，修订版本可以省略，如下: + + make preonic:default + +## 如何定制 + +QMK 有许多 [特性](features.md)来探索，也有很多 [参考文档](http://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](keymap.md)和[键码](keycodes.md)来利用许多特性。 diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md new file mode 100644 index 0000000000..df25a3ccd1 --- /dev/null +++ b/docs/zh-cn/_summary.md @@ -0,0 +1,106 @@ +* [完全菜鸟指南](newbs.md) + * [入门](newbs_getting_started.md) + * [构建你的第一个固件](newbs_building_firmware.md) + * [刷新固件](newbs_flashing.md) + * [测试和调试](newbs_testing_debugging.md) + * [Git最佳实践](newbs_best_practices.md) + * [学习资源](newbs_learn_more_resources.md) + +* [QMK基础](README.md) + * [QMK 简介](getting_started_introduction.md) + * [贡献 QMK](contributing.md) + * [如何使用Github](getting_started_github.md) + * [获得帮助](getting_started_getting_help.md) + +* [问题解答](faq.md) + * [一般问题](faq_general.md) + * [构建/编译QMK](faq_build.md) + * [调试/故障排除 QMK](faq_debug.md) + * [键盘布局](faq_keymap.md) + +* 详细指南 + * [安装构建工具](getting_started_build_tools.md) + * [流浪者指南](getting_started_vagrant.md) + * [构建/编译指令](getting_started_make_guide.md) + * [刷新固件](flashing.md) + * [定制功能](custom_quantum_functions.md) + * [布局概述](keymap.md) + +* [硬件](hardware.md) + * [AVR 处理器](hardware_avr.md) + * [驱动](hardware_drivers.md) + +* 参考 + * [键盘指南](hardware_keyboard_guidelines.md) + * [配置选项](config_options.md) + * [键码](keycodes.md) + * [记录最佳实践](documentation_best_practices.md) + * [文档指南](documentation_templates.md) + * [词汇表](reference_glossary.md) + * [单元测试](unit_testing.md) + * [有用的功能](ref_functions.md) + * [配置器支持](reference_configurator_support.md) + * [info.json 格式](reference_info_json.md) + +* [特性](features.md) + * [基本键码](keycodes_basic.md) + * [US ANSI 控制键](keycodes_us_ansi_shifted.md) + * [量子键码](quantum_keycodes.md) + * [高级键码](feature_advanced_keycodes.md) + * [音频](feature_audio.md) + * [自动控制](feature_auto_shift.md) + * [背光](feature_backlight.md) + * [蓝牙](feature_bluetooth.md) + * [Bootmagic](feature_bootmagic.md) + * [组合](feature_combo) + * [命令](feature_command.md) + * [动态宏指令](feature_dynamic_macros.md) + * [编码器](feature_encoders.md) + * [Grave Escape](feature_grave_esc.md) + * [键锁](feature_key_lock.md) + * [层](feature_layouts.md) + * [引导键](feature_leader_key.md) + * [LED 阵列](feature_led_matrix.md) + * [宏指令](feature_macros.md) + * [鼠标键](feature_mouse_keys.md) + * [一键功能](feature_advanced_keycodes.md#one-shot-keys) + * [指针设备](feature_pointing_device.md) + * [PS/2 鼠标](feature_ps2_mouse.md) + * [RGB 光](feature_rgblight.md) + * [RGB 矩阵](feature_rgb_matrix.md) + * [空格候补换挡](feature_space_cadet_shift.md) + * [空格候补换挡回车](feature_space_cadet_shift_enter.md) + * [速录机](feature_stenography.md) + * [换手](feature_swap_hands.md) + * [踢踏舞](feature_tap_dance.md) + * [终端](feature_terminal.md) + * [热敏打印机](feature_thermal_printer.md) + * [Unicode](feature_unicode.md) + * [用户空间](feature_userspace.md) + * [速度键](feature_velocikey.md) + +* 针对制造者和定制者 + * [飞线指南](hand_wire.md) + * [ISP 刷新指南](isp_flashing_guide.md) + * [ARM 调试指南](arm_debugging.md) + * [I2C 驱动](i2c_driver.md) + * [GPIO 控制器](internals_gpio_control.md) + * [Proton C 转换](proton_c_conversion.md) + +* 深入了解 + * [键盘如何工作](how_keyboards_work.md) + * [理解 QMK](understanding_qmk.md) + +* 其他话题 + * [使用Eclipse开发QMK](other_eclipse.md) + * [使用VSCode开发QMK](other_vscode.md) + * [支持](support.md) + +* QMK 内构 (正在编写) + * [定义](internals_defines.md) + * [输入回调寄存器](internals_input_callback_reg.md) + * [Midi 设备](internals_midi_device.md) + * [Midi 设备设置过程](internals_midi_device_setup_process.md) + * [Midi 工具库](internals_midi_util.md) + * [发送函数](internals_send_functions.md) + * [Sysex 工具](internals_sysex_tools.md) -- cgit v1.2.3 From 53c51f1d16b40fdd3e68a6afc5844917d3d58640 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Sun, 28 Apr 2019 09:42:16 +1000 Subject: A better new_project.sh (#5191) * A better new_project.sh * Fix docstrings * Use single quotes for anything not shown to user * Missed this docstring * Simplify get_git_username() Thanks @vomindoraan * chmod +x * Add docstring for print_error() * Break up git username call into multiple lines * Use with statement here * Conform to PEP 8 even more * Turn it back into a shell script * chmod +x again * Update docs to reflect new keyboard generator usage * Tweak wording slightly * Trim trailing whitespace * Don't actually need to escape the newlines here * As I suspected, you can pass shift a number * Prepend ./ to match the other code block * Minor syntax tweaks * The username token has changed * Replace name in the readme too * Make some reasonable assumptions about the presence of Git --- docs/hand_wire.md | 12 ++++++---- docs/hardware_avr.md | 28 +++++++++++++++------- ...keyboard_to_qmk_(arm_and_other_chibios_cpus).md | 24 +++++++++++++------ 3 files changed, 44 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/hand_wire.md b/docs/hand_wire.md index d2cba770e2..25db9341b8 100644 --- a/docs/hand_wire.md +++ b/docs/hand_wire.md @@ -198,15 +198,17 @@ From here, you should have a working keyboard once you program a firmware. Befor To start out, download [the firmware](https://github.com/qmk/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/) (paid) or [Visual Studio Code](https://code.visualstudio.com) (free). -The first thing we're going to do is create a new project using the script in the root directory of the firmware. In your terminal, run this command with `` replaced by the name of your project - it'll need to be different from any other project in the `keyboards/` folder: +The first thing we're going to do is create a new keyboard. In your terminal, run this command, which will ask you some questions and generate a basic keyboard project: ``` - util/new_project.sh +./util/new_keyboard.sh ``` You'll want to navigate to the `keyboards//` folder by typing, like the print-out from the script specifies: - cd keyboards/ +``` +cd keyboards/ +``` ### `config.h` @@ -326,7 +328,7 @@ Carefully flip your keyboard over, open up a new text document, and try typing - 2. Check the solder joints on the diode - if the diode is loose, part of your row may register, while the other may not. 3. Check the solder joints on the columns - if your column wiring is loose, part or all of the column may not work. 4. Check the solder joints on both sides of the wires going to/from the Teensy - the wires need to be fully soldered and connect to both sides. -5. Check the .h file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable. +5. Check the `.h` file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable. 6. Check to make sure you actually compiled the firmware and flashed the Teensy correctly. Unless you got error messages in the terminal, or a pop-up during flashing, you probably did everything correctly. If you've done all of these things, keep in mind that sometimes you might have had multiple things affecting the keyswitch, so it doesn't hurt to test the keyswitch by shorting it out at the end. @@ -335,4 +337,4 @@ If you've done all of these things, keep in mind that sometimes you might have h Now that you have a working board, it's time to get things in their permanent positions. I've often used liberal amounts of hot glue to secure and insulate things, so if that's your style, start spreading that stuff like butter. Otherwise, double-sided tape is always an elegant solution, and electrical tape is a distant second. Due to the nature of these builds, a lot of this part is up to you and how you planned (or didn't plan) things out. -There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different project (Planck, Clueboard, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb) +There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different keyboards (Planck, Clueboard, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb) diff --git a/docs/hardware_avr.md b/docs/hardware_avr.md index acf7088a39..7c28ab6dbc 100644 --- a/docs/hardware_avr.md +++ b/docs/hardware_avr.md @@ -6,14 +6,26 @@ If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_ ## Adding Your AVR Keyboard to QMK -QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started run the `util/new_project.sh` script: - -```bash -$ util/new_project.sh my_awesome_keyboard -###################################################### -# /keyboards/my_awesome_keyboard project created. To start -# working on things, cd into keyboards/my_awesome_keyboard -###################################################### +QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started, run the `util/new_keyboard.sh` script: + +``` +$ ./util/new_keyboard.sh +Generating a new QMK keyboard directory + +Keyboard Name: mycoolkb +Keyboard Type [avr]: +Your Name [John Smith]: + +Copying base template files... done +Copying avr template files... done +Renaming keyboard files... done +Replacing %KEYBOARD% with mycoolkb... done +Replacing %YOUR_NAME% with John Smith... done + +Created a new keyboard called mycoolkb. + +To start working on things, cd into keyboards/mycoolkb, +or open the directory in your favourite text editor. ``` This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard. diff --git a/docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md b/docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md index d8e084f466..979eafbc80 100644 --- a/docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md +++ b/docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md @@ -1,14 +1,24 @@ -Setting up your ARM based PCB is a little more involved than an Atmel MCU, but is easy enough. Start by using `util/new_project.sh ` to create a new project: +Setting up your ARM based PCB is a little more involved than an Atmel MCU, but is easy enough. Start by running `util/new_keyboard.sh`: ``` -$ util/new_project.sh simontester -###################################################### -# /keyboards/simontester project created. To start -# working on things, cd into keyboards/simontester -###################################################### -``` +$ ./util/new_keyboard.sh +Generating a new QMK keyboard directory + +Keyboard Name: mycoolkb +Keyboard Type [avr]: +Your Name [John Smith]: +Copying base template files... done +Copying avr template files... done +Renaming keyboard files... done +Replacing %KEYBOARD% with mycoolkb... done +Replacing %YOUR_NAME% with John Smith... done +Created a new keyboard called mycoolkb. + +To start working on things, cd into keyboards/mycoolkb, +or open the directory in your favourite text editor. +``` # END OF NEW ARM DOC, OLD ATMEL DOC FOLLOWS -- cgit v1.2.3 From 1d784f0f9575b70e35c9c8338b0ff80dc7316d7e Mon Sep 17 00:00:00 2001 From: Daniel Prilik Date: Mon, 29 Apr 2019 17:48:41 -0400 Subject: RGB Matrix: Custom effects on a kb/user level (#5338) * Revamped custom effects approach See docs for example usage * push-up RGB Matrix default mode Override default effect using RGB_MATRIX_STARTUP_MODE. Useful on boards without EEPROM support (*cough* Massdrop ALT/CTRL *cough*) * update docs --- docs/feature_rgb_matrix.md | 57 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 50 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index f2168ab16e..4ce9d15f0f 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -177,7 +177,7 @@ enum rgb_matrix_effects { 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_CYCLE_ALL, // Full keyboard solid hue cycling through full gradient - RGB_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right + RGB_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right RGB_MATRIX_CYCLE_UP_DOWN, // Full gradient scrolling top to bottom RGB_MATRIX_RAINBOW_MOVING_CHEVRON, // Full gradent Chevron shapped scrolling left to right RGB_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard @@ -203,7 +203,7 @@ enum rgb_matrix_effects { RGB_MATRIX_EFFECT_MAX }; ``` - + You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`: @@ -236,17 +236,60 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` | -## Custom layer effects +## Custom RGB Matrix Effects + +By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rule.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. + +To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks something like this: -Custom layer effects can be done by defining this in your `.c`: +`rgb_matrix_user.inc` should go in the root of the keymap directory. +`rgb_matrix_kb.inc` should go in the root of the keyboard directory. ```C -void rgb_matrix_indicators_kb(void) { - rgb_matrix_set_color(index, red, green, blue); +// !!! DO NOT ADD #pragma once !!! // + +// Step 1. +// Declare custom effects using the RGB_MATRIX_EFFECT macro +// (note the lack of semicolon after the macro!) +RGB_MATRIX_EFFECT(my_cool_effect) +RGB_MATRIX_EFFECT(my_cool_effect2) + +// Step 2. +// Define effects inside the `RGB_MATRIX_CUSTOM_EFFECT_IMPLS` ifdef block +#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS + +// e.g: A simple effect, self-contained within a single method +static bool my_cool_effect(effect_params_t* params) { + RGB_MATRIX_USE_LIMITS(led_min, led_max); + for (uint8_t i = led_min; i < led_max; i++) { + rgb_matrix_set_color(i, 0xff, 0xff, 0x00); + } + return led_max < DRIVER_LED_TOTAL; +} + +// e.g: A more complex effect, relying on external methods and state, with +// dedicated init and run methods +static uint8_t some_global_state; +static void my_cool_effect2_complex_init(effect_params_t* params) { + some_global_state = 1; } +static bool my_cool_effect2_complex_run(effect_params_t* params) { + RGB_MATRIX_USE_LIMITS(led_min, led_max); + for (uint8_t i = led_min; i < led_max; i++) { + rgb_matrix_set_color(i, 0xff, some_global_state++, 0xff); + } + + return led_max < DRIVER_LED_TOTAL; +} +static bool my_cool_effect2(effect_params_t* params) { + if (params->init) my_cool_effect2_complex_init(params); + return my_cool_effect2_complex_run(params); +} + +#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS ``` -A similar function works in the keymap as `rgb_matrix_indicators_user`. +For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/` ## Colors -- cgit v1.2.3 From a7113c8ed090d0ac647f30ee9b8ef41252e568ed Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Tue, 30 Apr 2019 00:18:50 +0200 Subject: Updated rgb_led struct field modifier to flags (#5619) Updated effects to test led flags Updated massdrop to use new flags field for led toggle --- docs/feature_rgb_matrix.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 4ce9d15f0f..91ec77ace0 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -127,13 +127,13 @@ Configure the hardware via your `config.h`: From this point forward the configuration is the same for all the drivers. The struct rgb_led array tells the system for each led, what key electrical matrix it represents, what the physical position is on the board, and if the led is for a modifier key or not. Here is a brief example: ```C -const rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = { +rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = { /* {row | col << 4} * | {x=0..224, y=0..64} - * | | modifier + * | | flags * | | | */ {{0|(0<<4)}, {20.36*0, 21.33*0}, 1}, - {{0|(1<<4)}, {20.36*1, 21.33*0}, 1}, + {{0|(1<<4)}, {20.36*1, 21.33*0}, 4}, .... } ``` @@ -147,7 +147,19 @@ 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. -`modifier` is a boolean, whether or not a certain key is considered a modifier (used in some effects). +`flags` 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. + +## Flags + +|Define |Description | +|------------------------------------|-------------------------------------------| +|`#define HAS_FLAGS(bits, flags)` |Returns true if `bits` has all `flags` set.| +|`#define HAS_ANY_FLAGS(bits, flags)`|Returns true if `bits` has any `flags` set.| +|`#define LED_FLAG_NONE 0x00` |If thes LED has no flags. | +|`#define LED_FLAG_ALL 0xFF` |If thes LED has all flags. | +|`#define LED_FLAG_MODIFIER 0x01` |If the Key for this LED is a modifier. | +|`#define LED_FLAG_UNDERGLOW 0x02` |If the LED is for underglow. | +|`#define LED_FLAG_KEYLIGHT 0x04` |If the LED is for key backlight. | ## Keycodes -- cgit v1.2.3 From c745d9b82e3f2047feb97a7a8937f27c6e989fd7 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Mon, 29 Apr 2019 22:21:46 -0500 Subject: Simple extended space cadet (#5277) * Simplifying and Extending Space Cadet to work on Ctrl and Alt keys * PR Review feedback * Reverting back to keycodes --- docs/_summary.md | 3 +- docs/feature_space_cadet.md | 59 +++++++++++++++++++++++++++++++++ docs/feature_space_cadet_shift.md | 37 --------------------- docs/feature_space_cadet_shift_enter.md | 31 ----------------- 4 files changed, 60 insertions(+), 70 deletions(-) create mode 100644 docs/feature_space_cadet.md delete mode 100644 docs/feature_space_cadet_shift.md delete mode 100644 docs/feature_space_cadet_shift_enter.md (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index c9d6c2bb14..d310870192 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -68,8 +68,7 @@ * [PS/2 Mouse](feature_ps2_mouse.md) * [RGB Lighting](feature_rgblight.md) * [RGB Matrix](feature_rgb_matrix.md) - * [Space Cadet Shift](feature_space_cadet_shift.md) - * [Space Cadet Shift Enter](feature_space_cadet_shift_enter.md) + * [Space Cadet](feature_space_cadet.md) * [Stenography](feature_stenography.md) * [Swap Hands](feature_swap_hands.md) * [Tap Dance](feature_tap_dance.md) diff --git a/docs/feature_space_cadet.md b/docs/feature_space_cadet.md new file mode 100644 index 0000000000..3e4665cde6 --- /dev/null +++ b/docs/feature_space_cadet.md @@ -0,0 +1,59 @@ +# Space Cadet: The Future, Built In + +Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds, and now even cooler supporting Control and Alt as well! + +## Usage + +Firstly, in your keymap, do one of the following: +- Replace the Left Shift key with `KC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `KC_RSPC` (Right Shift, Parenthesis Close). +- Replace the Left Control key with `KC_LCPO` (Left Control, Parenthesis Open), and Right Control with `KC_RCPC` (Right Control, Parenthesis Close). +- Replace the Left Alt key with `KC_LAPO` (Left Alt, Parenthesis Open), and Right Alt with `KC_RAPC` (Right Alt, Parenthesis Close). +- Replace any Shift key in your keymap with `KC_SFTENT` (Right Shift, Enter). + +## Keycodes + +|Keycode |Description | +|-----------|-------------------------------------------| +|`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 | + +## Caveats + +Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. See the [Command feature](feature_command.md) for info on how to change it, or make sure that Command is disabled in your `rules.mk` with: + +```make +COMMAND_ENABLE = no +``` + +## Configuration + +By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifer` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `KC_LSPO` key with `KC_TRNS` as the `Tap Modifer`. + +|Define |Default |Description | +|----------------|-------------------------------|---------------------------------------------------------------------------------| +|`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. | +|`RCPO_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. | +|`RAPO_KEYS` |`KC_RALT, KC_RALT, KC_0` |Send `KC_RALT` when held, the mod `KC_RALT` 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. | + + +## Obsolete Configuration + +These defines are used in the above defines internally to support backwards compatibility, so you may continue to use them, however the above defines open up a larger range of flexibility than before. As an example, say you want to not send any modifier when you tap just `KC_LSPO`, with the old defines you had an all or nothing choice of using the `DISABLE_SPACE_CADET_MODIFIER` define. Now you can define that key as: `#define KC_LSPO_KEYS KC_LSFT, KC_TRNS, KC_9`. This tells the system to set Left Shift if held or used with other keys, then on tap send no modifier (transparent) with the `KC_9` + +|Define |Default |Description | +|------------------------------|-------------|------------------------------------------------------------------| +|`LSPO_KEY` |`KC_9` |The keycode to send when Left Shift is tapped | +|`RSPC_KEY` |`KC_0` |The keycode to send when Right Shift is tapped | +|`LSPO_MOD` |`KC_LSFT` |The modifier to apply to `LSPO_KEY` | +|`RSPC_MOD` |`KC_RSFT` |The modifier to apply to `RSPC_KEY` | +|`SFTENT_KEY` |`KC_ENT` |The keycode to send when the Shift key is tapped | +|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet from applying a modifier | diff --git a/docs/feature_space_cadet_shift.md b/docs/feature_space_cadet_shift.md deleted file mode 100644 index 427d2a5812..0000000000 --- a/docs/feature_space_cadet_shift.md +++ /dev/null @@ -1,37 +0,0 @@ -# Space Cadet Shift: The Future, Built In - -Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds. - -## Usage - -Replace the Left Shift key in your keymap with `KC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `KC_RSPC` (Right Shift, Parenthesis Close). - -## Keycodes - -|Keycode |Description | -|---------|--------------------------------------| -|`KC_LSPO`|Left Shift when held, `(` when tapped | -|`KC_RSPC`|Right Shift when held, `)` when tapped| - -## Caveats - -Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. Make sure that Command is disabled in your `rules.mk` with: - -```make -COMMAND_ENABLE = no -``` - -## Configuration - -By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. -You can also disable the rollover, allowing you to use the opposite Shift key to cancel the Space Cadet state in the event of an erroneous press, instead of emitting a pair of parentheses when the keys are released. -Also, by default, the Space Cadet applies modifiers LSPO_MOD and RSPC_MOD to keys defined by LSPO_KEY and RSPC_KEY. You can override this behavior by redefining those variables in your `config.h`. You can also prevent the Space Cadet to apply a modifier by defining DISABLE_SPACE_CADET_MODIFIER in your `config.h`. - -|Define |Default |Description | -|------------------------------|-------------|--------------------------------------------------------------------------------| -|`LSPO_KEY` |`KC_9` |The keycode to send when Left Shift is tapped | -|`RSPC_KEY` |`KC_0` |The keycode to send when Right Shift is tapped | -|`LSPO_MOD` |`KC_LSFT` |The keycode to send when Left Shift is tapped | -|`RSPC_MOD` |`KC_RSFT` |The keycode to send when Right Shift is tapped | -|`DISABLE_SPACE_CADET_ROLLOVER`|*Not defined*|If defined, use the opposite Shift key to cancel Space Cadet | -|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet to apply a modifier to LSPO_KEY and RSPC_KEY| diff --git a/docs/feature_space_cadet_shift_enter.md b/docs/feature_space_cadet_shift_enter.md deleted file mode 100644 index 56a569b139..0000000000 --- a/docs/feature_space_cadet_shift_enter.md +++ /dev/null @@ -1,31 +0,0 @@ -# Space Cadet Shift Enter - -Based on the [Space Cadet Shift](feature_space_cadet_shift.md) feature. Tap the Shift key on its own, and it behaves like Enter. When held, the Shift functions as normal. - -## Usage - -Replace any Shift key in your keymap with `KC_SFTENT` (Shift, Enter), and you're done. - -## Keycodes - -|Keycode |Description | -|-----------|----------------------------------------| -|`KC_SFTENT`|Right Shift when held, Enter when tapped| - -## Caveats - -As with Space Cadet Shift, this feature may conflict with Command, so it should be disabled in your `rules.mk` with: - -```make -COMMAND_ENABLE = no -``` - -This feature also uses the same timers as Space Cadet Shift, so using them in tandem may produce strange results. - -## Configuration - -By default Space Cadet assumes a US ANSI layout, but if you'd like to use a different key for Enter, you can redefine it in your `config.h`: - -|Define |Default |Description | -|------------|--------|------------------------------------------------| -|`SFTENT_KEY`|`KC_ENT`|The keycode to send when the Shift key is tapped| -- cgit v1.2.3 From d67b99ff3c2cfca63add546ad6d052e2487aa26a Mon Sep 17 00:00:00 2001 From: Ryan Caltabiano Date: Tue, 30 Apr 2019 19:54:22 -0500 Subject: Added OLED Driver to the summary --- docs/_summary.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index d310870192..043943f1d8 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -63,6 +63,7 @@ * [LED Matrix](feature_led_matrix.md) * [Macros](feature_macros.md) * [Mouse Keys](feature_mouse_keys.md) + * [OLED Driver](feature_oled_driver) * [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 22ba36a4d86c06ce1b6049555525646eb16bb57a Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Wed, 1 May 2019 10:02:02 -0500 Subject: rgblight 255 hue (#5547) --- docs/feature_rgblight.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 48277373a5..8b0a45cb64 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -145,7 +145,7 @@ const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20}; const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31}; // These control which hues are selected for each of the "Static gradient" modes -const uint16_t RGBLED_GRADIENT_RANGES[] PROGMEM = {360, 240, 180, 120, 90}; +const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64}; ``` ## Functions -- cgit v1.2.3 From 3da8d46a07167fc862e90b6bb232812d5cb64651 Mon Sep 17 00:00:00 2001 From: Takeshi ISHII <2170248+mtei@users.noreply.github.com> Date: Thu, 2 May 2019 23:59:29 +0900 Subject: If RGBLIGHT_EFFECT_BREATHE_CENTER is undefined, use fixed breathe table instead of exp() and sin() (#5484) * If RGBLIGHT_EFFECT_BREATHE_CENTER is undefined, use fixed breathe table instead of exp() and sin() * Change rgblight breathing table size to be easily selectable. add RGBLIGHT_BREATHE_TABLE_SIZE macro for customize breathing effect. --- docs/feature_rgblight.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 8b0a45cb64..4572f45b26 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -114,7 +114,7 @@ The following options can be used to tweak the various animations: |`RGBLIGHT_EFFECT_RGB_TEST` |*Not defined*|If defined, enable RGB test animation mode. | |`RGBLIGHT_EFFECT_ALTERNATING` |*Not defined*|If defined, enable alternating animation mode. | |`RGBLIGHT_ANIMATIONS` |*Not defined*|If defined, enables all additional animation modes | -|`RGBLIGHT_EFFECT_BREATHE_CENTER` |`1.85` |Used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 | +|`RGBLIGHT_EFFECT_BREATHE_CENTER` |*Not defined*|If defined, used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 | |`RGBLIGHT_EFFECT_BREATHE_MAX` |`255` |The maximum brightness for the breathing mode. Valid values are 1 to 255 | |`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation | |`RGBLIGHT_EFFECT_KNIGHT_LENGTH` |`3` |The number of LEDs to light up for the "Knight" animation | -- cgit v1.2.3 From 7e655a207e58fb8e5c7d76bd5727558e6b4c8b0c Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Thu, 2 May 2019 08:03:42 -0700 Subject: Add option to enable LTO easily (#5674) * Add option to enable LTO easily and disable features that cause compiling errors with LTO * Add documentation about LTO option * Add to show_options --- 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 8f229a2cb8..3ef00394db 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -330,6 +330,8 @@ Use these to enable or disable building certain features. The more you have enab * Forces the keyboard to wait for a USB connection to be established before it starts up * `NO_USB_STARTUP_CHECK` * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master. +* `LINK_TIME_OPTIMIZATION_ENABLE` + = Enables Link Time Optimization (`LTO`) when compiling the keyboard. This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticable). However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION` ## USB Endpoint Limitations -- cgit v1.2.3 From db440f3e75f1d71e2c26499c7c7500cc48020047 Mon Sep 17 00:00:00 2001 From: ymzcdg <49898694+ymzcdg@users.noreply.github.com> Date: Fri, 3 May 2019 13:21:06 +0800 Subject: translate the first unit(newbs) (#5753) translate newbs_getting_started.md newbs_building_firmware.md newbs_flashing.md newbs_testing_debugging.md newbs_best_practices.md newbs_learn_more_resources.md into Mandarin Chinese --- docs/zh-cn/newbs_best_practices.md | 163 ++++++++++++++++ docs/zh-cn/newbs_building_firmware.md | 81 ++++++++ docs/zh-cn/newbs_flashing.md | 307 +++++++++++++++++++++++++++++++ docs/zh-cn/newbs_getting_started.md | 102 ++++++++++ docs/zh-cn/newbs_learn_more_resources.md | 15 ++ docs/zh-cn/newbs_testing_debugging.md | 43 +++++ 6 files changed, 711 insertions(+) create mode 100644 docs/zh-cn/newbs_best_practices.md create mode 100644 docs/zh-cn/newbs_building_firmware.md create mode 100644 docs/zh-cn/newbs_flashing.md create mode 100644 docs/zh-cn/newbs_getting_started.md create mode 100644 docs/zh-cn/newbs_learn_more_resources.md create mode 100644 docs/zh-cn/newbs_testing_debugging.md (limited to 'docs') diff --git a/docs/zh-cn/newbs_best_practices.md b/docs/zh-cn/newbs_best_practices.md new file mode 100644 index 0000000000..fa58dc75e8 --- /dev/null +++ b/docs/zh-cn/newbs_best_practices.md @@ -0,0 +1,163 @@ +# 最佳实践 + +## 或者说, "我应如何学会不再担心并开始爱上Git。" + +本文档旨在指导新手以最佳方式获得为QMK做出贡献的丝滑体验。我们将介绍为QMK做出贡献的过程，详细介绍使这项任务更容易的一些方法，然后我们将制造一些问题，来教你如何解决它们。 + +本文假设了一些内容: + +1. 一有个GitHub账户, 并[创建qmk_firmware仓库分叉](getting_started_github.md)到你的帐户. +2. 你已经[建立你的构建环境](newbs_getting_started.md?id=environment-setup). + + +## 你分叉的主分支: 一直在上传，但不要提交 + +十分推荐您在QMK开发过程中无论开发是否完成都要保持你的 `master` 分支更新，但是 ***一定不要*** 提交。相反，你应该在一个开发分叉中做出你所有修改并在开发时提交pull request。 + +减少合并冲突的可能性 — 两个或多个用户同时编辑文件的同一部分的实例 — 保持 `master` 分支最新，并创建一个新的分支来开始新的开发。 + +### 更新你的主分支 + +保持你的 `master` 更新, 推荐你添加QMK Firmware仓库作为Git的远程仓库，想这么做的话, 你可以打开你的Git命令行接口然后输入: + +``` +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +运行 `git remote -v`, 来确定这个仓库已经添加，以下是回显: + +``` +$ git remote -v +origin https://github.com//qmk_firmware.git (fetch) +origin https://github.com//qmk_firmware.git (push) +upstream https://github.com/qmk/qmk_firmware.git (fetch) +upstream https://github.com/qmk/qmk_firmware.git (push) +``` + +现在添加已完成，你可以用`git fetch upstream`来检查仓库的更新. 这会检索branches 和 tags — 统称为"refs" — 从QMK仓库, 也就是 `upstream`。我们可以比较我们的分叉和QMK的 `origin` 数据的不同。 + +要更新你的分叉的主分支，请运行以下命令，在每行之后按Enter键: + +``` +git checkout master +git fetch upstream +git pull upstream master +git push origin master +``` + +这回切换到你的`master` 分支, 检索你QMK仓库的refs, 下载当前QMK `master` 分支到你的电脑, 并上传到你的分叉. + +### 做改动 + +你可以输入以下命令来创建一个