ahoneybun/qmk_firmware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge remote-tracking branch 'upstream/develop' into xap

Browse source
This commit is contained in:
Nick Brassel 2021-11-28 12:56:26 +11:00
commit bf66b91433
5591 changed files with 131128 additions and 54530 deletions
Download patch file Download diff file Expand all files Collapse all files

457
docs/ChangeLog/20211127.md Normal file
View file

@ -0,0 +1,457 @@
# QMK Breaking Changes - 2021 November 27 Changelog
## 2000 keyboards! :id=qmk-2000th-keyboard
QMK had it's 2000th keyboard submitted during this breaking changes cycle.... and it only _just_ made the cut-off!
```shell
% qmk list-keyboards | wc -l
2003
```
From the whole QMK team, a major thankyou to the community for embracing QMK as your preferred keyboard firmware!
## Notable Features :id=notable-features
### Expanded Pointing Device support ([#14343](https://github.com/qmk/qmk_firmware/pull/14343)) :id=expanded-pointing-device
Pointing device support has been reworked and reimplemented to allow for easier integration of new peripherals.
Usages of `POINTING_DEVICE_ENABLE = yes` in `rules.mk` files now need to be accompanied by a corresponding `POINTING_DEVICE_DRIVER = ???` line, specifying which driver to use during the build. Existing keyboards have already been migrated across to the new usage pattern, so most likely no change is required by users.
QMK now has core-supplied support for the following pointing device peripherals:
| `rules.mk` line | Supported device |
|------------------------------------------------|-----------------------------------------|
| `POINTING_DEVICE_DRIVER = analog_joystick` | Analog joysticks, such as PSP joysticks |
| `POINTING_DEVICE_DRIVER = adns5050` | ADNS 5050 sensor |
| `POINTING_DEVICE_DRIVER = adns9800` | ADNS 9800 laser sensor |
| `POINTING_DEVICE_DRIVER = cirque_pinnacle_i2c` | Cirque touchpad, I2C mode |
| `POINTING_DEVICE_DRIVER = cirque_pinnacle_spi` | Cirque Touchpad, SPI mode |
| `POINTING_DEVICE_DRIVER = pimoroni_trackball` | Pimoroni Trackball |
| `POINTING_DEVICE_DRIVER = pmw3360` | PMW 3360 |
See the new documentation for the [Pointing Device](../feature_pointing_device.md) feature for more information on specific configuration for each driver.
### Dynamic Tapping Term ([#11036](https://github.com/qmk/qmk_firmware/pull/11036)) :id=dynamic-tapping-term
For people who are starting out with tapping keys, or for people who think tapping keys don't "feel right", it's sometimes quite difficult to determine what duration of tapping term to use to make things seem natural.
If you're in this stage of discovery, you can now add `DYNAMIC_TAPPING_TERM_ENABLE = yes` to your `rules.mk`, which enables the use of the following keycodes in your keymap:
| Key | Description |
|-----------|-------------------------------------------------------------------------------|
| `DT_PRNT` | "Dynamic Tapping Term Print": Types the current tapping term, in milliseconds |
| `DT_UP` | "Dynamic Tapping Term Up": Increases the current tapping term by 5ms |
| `DT_DOWN` | "Dynamic Tapping Term Down": Decreases the current tapping term by 5ms |
Coupled with the use of `qmk console` or QMK Toolbox to show console output from your keyboard, you can tweak the tapping term dynamically in order to narrow down what "feels right" to you. Once you're happy, drop in the resulting number into your keymap's `config.h` and you're good to go!
### Macros in JSON keymaps ([#14374](https://github.com/qmk/qmk_firmware/pull/14374)) :id=macros-in-keymap-json
You can now define up to 32 macros in your `keymap.json` file, as used by [QMK Configurator](newbs_building_firmware_configurator.md), and `qmk compile`. You can define these macros in a list under the `macros` keyword, like this:
```json
{
"keyboard": "handwired/my_macropad",
"keymap": "my_keymap",
"macros": [
[ // first listed is MACRO_0...
{"action":"down", "keycodes": ["LSFT"]},
"hello world1",
{"action": "up","keycodes": ["LSFT"]}
],
[ // ...then MACRO_1...
{"action":"tap", "keycodes": ["LCTL", "LALT", "DEL"]}
],
[ // ...then MACRO_2...
"ding!",
{"action":"beep"}
],
[ // ...and MACRO_3.
{"action":"tap", "keycodes": ["F1"]},
{"action":"delay", "duration": "1000"},
{"action":"tap", "keycodes": ["PGDN"]}
]
],
"layout": "LAYOUT_all",
"layers": [
["MACRO_0", "MACRO_1", "MACRO_2", "MACRO_3"]
]
}
```
In due course, [QMK Configurator](https://config.qmk.fm/) will pick up support for defining these in its UI, but for now the json is the only way to define macros.
## Changes Requiring User Action :id=changes-requiring-user-action
### Updated Keyboard Codebases :id=updated-keyboard-codebases
The following keyboards have had their source moved within QMK:
| Old Keyboard Name | New Keyboard Name |
|------------------------|---------------------------------|
| aozora/hotswap | aozora |
| gskt00 | kapcave/gskt00 |
| handwired/dtisaac01 | dtisaac/dtisaac01 |
| kprepublic/bm60poker | kprepublic/bm60hsrgb_poker/rev1 |
| kprepublic/bm60rgb | kprepublic/bm60hsrgb/rev1 |
| kprepublic/bm60rgb_iso | kprepublic/bm60hsrgb_iso/rev1 |
| kprepublic/bm65iso | kprepublic/bm65hsrgb_iso |
| kprepublic/bm68rgb | kprepublic/bm68hsrgb |
| paladin64 | kapcave/paladin64 |
| portal_66 | portal_66/soldered |
| signum/3_0/elitec | signum/3_0 |
| tgr/jane | tgr/jane/v2 |
### Squeezing space out of AVR ([#15243](https://github.com/qmk/qmk_firmware/pull/15243)) :id=squeezing-space-from-avr
The AVR platform has been problematic for some time, in the sense that it is severely resource-constrained -- this makes life difficult for anyone attempting to add new functionality such as display panels to their keymap code. The illustrious Drashna has contributed some newer documentation on how to attempt to free up some space on AVR-based keyboards that are in short supply.
Of course, there are much fewer constraints with ARM chips... ;)
### Require explicit enabling of RGB Matrix modes ([#15018](https://github.com/qmk/qmk_firmware/pull/15018)) :id=explicit-rgb-modes
Related to the previous section -- RGB Matrix modes have now been made to be opt-in, rather than opt-out. As these animations are now opt-in, you may find that your keyboard no longer has all the RGB modes you're expecting -- you may need to configure and recompile your firmware and enable your animations of choice... with any luck they'll still fit in the space available.
Most keyboards keep their original functionality, but over time the QMK maintainers have found that removal of animations ends up being the quickest way to free up space... and some keyboards have had animations such as reactive effects disabled by default in order to still fit within the flash space available.
The full list of configurables to turn specific animations back on can be found at on the [RGB Matrix documentation](feature_rgb_matrix.md#rgb-matrix-effects) page.
### OLED task refactoring ([#14864](https://github.com/qmk/qmk_firmware/pull/14864)) :id=oled-task-refactor
OLED display code was traditionally difficult to override in keymaps as they did not follow the standard pattern of `bool *_kb()` deferring to `bool *_user()` functions, allowing signalling to the higher level that processing had already been done.
This changes the standard OLED drawing function model to allow for a base implementation to be provided by a keyboard, but also still allow for keymap-level overrides without needing to modify the keyboard's code.
The old keymap code went something like this:
```c
void oled_task_user(void) {
// keymap drawing code
}
```
...but the new keymap code looks like this:
```c
bool oled_task_user(void) {
// keymap drawing code
return false;
}
```
Keyboard designers should now structure their keyboard-level drawing routines like the following, in order to allow for keymap overrides:
```c
bool oled_task_kb(void) {
// Defer to the keymap if they want to override
if(!oled_task_user()) { return false; }
// default keyboard drawing code
return false;
}
```
### Bootmagic Full Removal ([#15002](https://github.com/qmk/qmk_firmware/pull/15002)) :id=bootmagic-full-removal
As noted during previous breaking changes cycles, QMK decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option.
This removal is now complete!
This pull request changes the behavior of `BOOTMAGIC_ENABLE` such that specifying `lite` or `full` results in an error, allowing only `yes` or `no`, with `yes` mirroring historical `lite` functionality.
All use of the `lite` keyword within the repository has been migrated to `yes` -- any new submissions using `lite` will now fail to build and should be updated accordingly.
#### Bootmagic Full Deprecation Schedule: Complete!
This is the historical timeline for the behavior of `BOOTMAGIC_ENABLE`:
- (done) From 2021 May 29, setting `BOOTMAGIC_ENABLE = yes` will enable Bootmagic Lite instead of full Bootmagic.
- (done) From 2021 Aug 28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail.
- (now) From 2021 Nov 27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail.
### Remove QWIIC_DRIVERS ([#14174](https://github.com/qmk/qmk_firmware/pull/14174)) :id=remove-qwiic
Due to minimal QWIIC adoption and other options for similar functionality, the QWIIC drivers were removed from QMK. Existing OLED usages have been migrated across to the normal QMK OLED driver instead.
## Notable core changes :id=notable-core
### New MCU Support :id=new-mcu-support
QMK firmware picked up support for a handful of new MCU families, potentially making it a bit easier to source components.
QMK firmware is now no longer limited to AVR and ARM - it also picked up support for our first RISC-V chip, the GD32VF103.
* Add support for RISC-V builds and GD32VF103 MCU ([#12508](https://github.com/qmk/qmk_firmware/pull/12508))
* Add HT32 support to core ([#14388](https://github.com/qmk/qmk_firmware/pull/14388))
* Westberrytech pr ([#14422](https://github.com/qmk/qmk_firmware/pull/14422))
* Initial pass of F405 support ([#14584](https://github.com/qmk/qmk_firmware/pull/14584))
### EEPROM Changes :id=eeprom-changes
There were a few EEPROM-related changes that landed during this breaking changes cycle, most prominently the long-awaited ability for the Drop boards to gain persistent storage. Any users of the Drop CTRL or Drop ALT should update QMK Toolbox as well -- coupled with a QMK firmware update settings should now be saved.
* massdrop alt/ctrl: support saving into nvm ([#6068](https://github.com/qmk/qmk_firmware/pull/6068))
* Implement F4 eeprom ([#14195](https://github.com/qmk/qmk_firmware/pull/14195))
* make the full 4096 bytes of EEPROM work on Teensy 3.6 ([#12947](https://github.com/qmk/qmk_firmware/pull/12947))
* Further tidy up of STM32 eeprom emulation ([#14591](https://github.com/qmk/qmk_firmware/pull/14591))
* Enable eeprom with F401xE ld ([#14752](https://github.com/qmk/qmk_firmware/pull/14752))
### Compilation Database :id=compile-commands
A clang-compatible compilation database generator has been added as an option in order to help development environments such as Visual Studio Code.
Running `qmk generate-compilation-database -kb <yourkb> -km <yourkeymap>` from within the QMK firmware directory will generate a `compile_commands.json` file -- using a compatible IDE will likely see this and correctly start detecting the correct locations for source files as well as type and function information that are relevant to your build.
Do note that switching keyboards will require re-generation of this file.
* New CLI subcommand to create clang-compatible compilation database (`compile_commands.json`) ([#14370](https://github.com/qmk/qmk_firmware/pull/14370))
* compiledb: query include paths from gcc directly. ([#14462](https://github.com/qmk/qmk_firmware/pull/14462))
### Codebase restructure and cleanup :id=codebase-restructure
QMK continues on its restructuring journey, in order to make it easier to integrate newer features and add support for new hardware. This quarter's batch of changes include:
* add 'include keyboard_features.mk' into build_keyboard.mk ([#8422](https://github.com/qmk/qmk_firmware/pull/8422))
* Infer more when building features ([#13890](https://github.com/qmk/qmk_firmware/pull/13890))
* Move `tmk_core/common/<plat>` ([#13918](https://github.com/qmk/qmk_firmware/pull/13918))
* Move feature suspend logic out of platform specific code ([#14210](https://github.com/qmk/qmk_firmware/pull/14210))
* Remove bin/qmk ([#14231](https://github.com/qmk/qmk_firmware/pull/14231))
* Move Audio drivers from quantum to platform drivers folder ([#14308](https://github.com/qmk/qmk_firmware/pull/14308))
* Remove Arduino-style `analogRead()` ([#14348](https://github.com/qmk/qmk_firmware/pull/14348))
* Remove unreferenced IBM4704, Sony NEWS, NeXT keyboard code. ([#14380](https://github.com/qmk/qmk_firmware/pull/14380))
* Move Bluetooth config to common_features.mk ([#14404](https://github.com/qmk/qmk_firmware/pull/14404))
* Relocate Adafruit BLE code ([#14530](https://github.com/qmk/qmk_firmware/pull/14530))
* Change `MK66F18` -> `MK66FX1M0` ([#14659](https://github.com/qmk/qmk_firmware/pull/14659))
* Remove sysex API ([#14723](https://github.com/qmk/qmk_firmware/pull/14723))
* Basic keycode overhaul ([#14726](https://github.com/qmk/qmk_firmware/pull/14726))
* Remove SERIAL_LINK feature ([#14727](https://github.com/qmk/qmk_firmware/pull/14727))
* Move converter specific tmk_core protocols ([#14743](https://github.com/qmk/qmk_firmware/pull/14743))
* Align PS/2 GPIO defines ([#14745](https://github.com/qmk/qmk_firmware/pull/14745))
* Clean up LED/RGB Matrix driver config ([#14760](https://github.com/qmk/qmk_firmware/pull/14760))
* Update UART driver API ([#14839](https://github.com/qmk/qmk_firmware/pull/14839))
* Tidy up LCD_ENABLE/visualizer references ([#14855](https://github.com/qmk/qmk_firmware/pull/14855))
* Remove legacy Makefile functionality ([#14858](https://github.com/qmk/qmk_firmware/pull/14858))
* Begin to carve out platform/protocol API - Migrate keyboard_* calls ([#14888](https://github.com/qmk/qmk_firmware/pull/14888))
* Rename platform SRC variable ([#14894](https://github.com/qmk/qmk_firmware/pull/14894))
* Relocate PS2 code ([#14895](https://github.com/qmk/qmk_firmware/pull/14895))
* Move USE_CCACHE logic to common location ([#14899](https://github.com/qmk/qmk_firmware/pull/14899))
* Migrate makefile utilities to sub-directory ([#14917](https://github.com/qmk/qmk_firmware/pull/14917))
* Remove SERIAL_MOUSE ([#14969](https://github.com/qmk/qmk_firmware/pull/14969))
* Relocate protocol files within tmk_core/common/ ([#14972](https://github.com/qmk/qmk_firmware/pull/14972))
* More platform/protocol alignment ([#14976](https://github.com/qmk/qmk_firmware/pull/14976))
* Fix uart function prototypes ([#15162](https://github.com/qmk/qmk_firmware/pull/15162))
* Remove deprecated KEYMAP alias ([#15037](https://github.com/qmk/qmk_firmware/pull/15037))
* Move non-assignment code to post_rules.mk ([#14207](https://github.com/qmk/qmk_firmware/pull/14207))
* Helix use `post_rules.mk` ([#14216](https://github.com/qmk/qmk_firmware/pull/14216))
* Make ChibiOS PAL interactions less STM32 specific - Round 2 ([#14456](https://github.com/qmk/qmk_firmware/pull/14456))
---
## Full changelist
Core:
* massdrop alt/ctrl: support saving into nvm ([#6068](https://github.com/qmk/qmk_firmware/pull/6068))
* Made AVR backlight pwm resolution configurable ([#7521](https://github.com/qmk/qmk_firmware/pull/7521))
* add 'include keyboard_features.mk' into build_keyboard.mk ([#8422](https://github.com/qmk/qmk_firmware/pull/8422))
* New feature: `DYNAMIC_TAPPING_TERM_ENABLE` ([#11036](https://github.com/qmk/qmk_firmware/pull/11036))
* Add Retro Shift (Auto Shift for Tap Hold via Retro Tapping) and Custom Auto Shifts ([#11059](https://github.com/qmk/qmk_firmware/pull/11059))
* Add support for RISC-V builds and GD32VF103 MCU ([#12508](https://github.com/qmk/qmk_firmware/pull/12508))
* Add Fractal RGB matrix effects ([#12670](https://github.com/qmk/qmk_firmware/pull/12670))
* Added power tracking api ([#12691](https://github.com/qmk/qmk_firmware/pull/12691))
* haptic: Feature to disable it when usb port is not configured or suspended. ([#12692](https://github.com/qmk/qmk_firmware/pull/12692))
* make the full 4096 bytes of EEPROM work on Teensy 3.6 ([#12947](https://github.com/qmk/qmk_firmware/pull/12947))
* Add Support for USB programmable buttons ([#12950](https://github.com/qmk/qmk_firmware/pull/12950))
* [Tests] Increase QMK test coverage ([#13789](https://github.com/qmk/qmk_firmware/pull/13789))
* Add support for ISSI drivers on both sides of a split keyboard ([#13842](https://github.com/qmk/qmk_firmware/pull/13842))
* Infer more when building features ([#13890](https://github.com/qmk/qmk_firmware/pull/13890))
* Reimplements WPM feature to be smaller & precise ([#13902](https://github.com/qmk/qmk_firmware/pull/13902))
* Move `tmk_core/common/<plat>` ([#13918](https://github.com/qmk/qmk_firmware/pull/13918))
* Improvements to handling of disconnected split keyboards. ([#14033](https://github.com/qmk/qmk_firmware/pull/14033))
* Add Pixel Rain RGB Matrix effect ([#14155](https://github.com/qmk/qmk_firmware/pull/14155))
* Remove QWIIC_DRIVERS ([#14174](https://github.com/qmk/qmk_firmware/pull/14174))
* Add LM() keys to the list of keys disabled by NO_HAPTIC_MOD ([#14181](https://github.com/qmk/qmk_firmware/pull/14181))
* Implement F4 eeprom ([#14195](https://github.com/qmk/qmk_firmware/pull/14195))
* define to AUTO_SHIFT_DISABLED_AT_STARTUP ([#14201](https://github.com/qmk/qmk_firmware/pull/14201))
* Move feature suspend logic out of platform specific code ([#14210](https://github.com/qmk/qmk_firmware/pull/14210))
* Remove bin/qmk ([#14231](https://github.com/qmk/qmk_firmware/pull/14231))
* Change keyboard level include guards to `pragma once` ([#14248](https://github.com/qmk/qmk_firmware/pull/14248))
* i2c_master: Add support for reading/writing to 16-bit registers ([#14289](https://github.com/qmk/qmk_firmware/pull/14289))
* Move Audio drivers from quantum to platform drivers folder ([#14308](https://github.com/qmk/qmk_firmware/pull/14308))
* Add RGBW support to PWM and SPI drivers for ChibiOS ([#14327](https://github.com/qmk/qmk_firmware/pull/14327))
* Rework and expand Pointing Device support ([#14343](https://github.com/qmk/qmk_firmware/pull/14343))
* Remove Arduino-style `analogRead()` ([#14348](https://github.com/qmk/qmk_firmware/pull/14348))
* Macros in JSON keymaps ([#14374](https://github.com/qmk/qmk_firmware/pull/14374))
* Remove unreferenced IBM4704, Sony NEWS, NeXT keyboard code. ([#14380](https://github.com/qmk/qmk_firmware/pull/14380))
* Add HT32 support to core ([#14388](https://github.com/qmk/qmk_firmware/pull/14388))
* Align ChibiOS I2C defs with other drivers ([#14399](https://github.com/qmk/qmk_firmware/pull/14399))
* Move Bluetooth config to common_features.mk ([#14404](https://github.com/qmk/qmk_firmware/pull/14404))
* Westberrytech pr ([#14422](https://github.com/qmk/qmk_firmware/pull/14422))
* Refactor use of STM32_SYSCLK ([#14430](https://github.com/qmk/qmk_firmware/pull/14430))
* Migrate STM32_EEPROM_ENABLE to use EEPROM_DRIVER ([#14433](https://github.com/qmk/qmk_firmware/pull/14433))
* Refactor use of _STM32_ defines ([#14439](https://github.com/qmk/qmk_firmware/pull/14439))
* Add i2c defaults for Convert to Proton C ([#14470](https://github.com/qmk/qmk_firmware/pull/14470))
* Use opendrain pin with external pullup again ([#14474](https://github.com/qmk/qmk_firmware/pull/14474))
* Add ability to use numpad digits for unicode mode UC_WIN ([#14496](https://github.com/qmk/qmk_firmware/pull/14496))
* Enable de-ghosting for RGB/LED matrix on all ISSI LED drivers ([#14508](https://github.com/qmk/qmk_firmware/pull/14508))
* Relocate Adafruit BLE code ([#14530](https://github.com/qmk/qmk_firmware/pull/14530))
* Initial pass of F405 support ([#14584](https://github.com/qmk/qmk_firmware/pull/14584))
* Further tidy up of STM32 eeprom emulation ([#14591](https://github.com/qmk/qmk_firmware/pull/14591))
* Remove GCC version check from song list inclusion ([#14600](https://github.com/qmk/qmk_firmware/pull/14600))
* Change `MK66F18` -> `MK66FX1M0` ([#14659](https://github.com/qmk/qmk_firmware/pull/14659))
* Add ifndef to WS2812 timing constraints ([#14678](https://github.com/qmk/qmk_firmware/pull/14678))
* Reuse of EEPROM debounce logic ([#14699](https://github.com/qmk/qmk_firmware/pull/14699))
* Remove sysex API ([#14723](https://github.com/qmk/qmk_firmware/pull/14723))
* Basic keycode overhaul ([#14726](https://github.com/qmk/qmk_firmware/pull/14726))
* Remove SERIAL_LINK feature ([#14727](https://github.com/qmk/qmk_firmware/pull/14727))
* Enable CLI flashing via mdloader ([#14729](https://github.com/qmk/qmk_firmware/pull/14729))
* Correct the Turkish F '?' keycode (TR_QUES) ([#14740](https://github.com/qmk/qmk_firmware/pull/14740))
* Move converter specific tmk_core protocols ([#14743](https://github.com/qmk/qmk_firmware/pull/14743))
* Align PS/2 GPIO defines ([#14745](https://github.com/qmk/qmk_firmware/pull/14745))
* Improve Adafruit BLE configuration defines ([#14749](https://github.com/qmk/qmk_firmware/pull/14749))
* Enable eeprom with F401xE ld ([#14752](https://github.com/qmk/qmk_firmware/pull/14752))
* Clean up LED/RGB Matrix driver config ([#14760](https://github.com/qmk/qmk_firmware/pull/14760))
* Initial USB2422 driver ([#14835](https://github.com/qmk/qmk_firmware/pull/14835))
* Update UART driver API ([#14839](https://github.com/qmk/qmk_firmware/pull/14839))
* Split out arm_atsam shift register logic ([#14848](https://github.com/qmk/qmk_firmware/pull/14848))
* Split out HAPTIC_ENABLE to have separate DRIVER option ([#14854](https://github.com/qmk/qmk_firmware/pull/14854))
* Tidy up LCD_ENABLE/visualizer references ([#14855](https://github.com/qmk/qmk_firmware/pull/14855))
* Remove legacy Makefile functionality ([#14858](https://github.com/qmk/qmk_firmware/pull/14858))
* Add support for deferred executors. ([#14859](https://github.com/qmk/qmk_firmware/pull/14859))
* Change OLED task function to be boolean ([#14864](https://github.com/qmk/qmk_firmware/pull/14864))
* Add a new led driver for Keychron's keyboards. ([#14872](https://github.com/qmk/qmk_firmware/pull/14872))
* Begin to carve out platform/protocol API - Migrate keyboard_* calls ([#14888](https://github.com/qmk/qmk_firmware/pull/14888))
* Rename platform SRC variable ([#14894](https://github.com/qmk/qmk_firmware/pull/14894))
* Relocate PS2 code ([#14895](https://github.com/qmk/qmk_firmware/pull/14895))
* Move USE_CCACHE logic to common location ([#14899](https://github.com/qmk/qmk_firmware/pull/14899))
* Migrate makefile utilities to sub-directory ([#14917](https://github.com/qmk/qmk_firmware/pull/14917))
* Remove legacy handling for ErgoDox Infinity handedness ([#14919](https://github.com/qmk/qmk_firmware/pull/14919))
* Align usbasp flashing behaviour ([#14928](https://github.com/qmk/qmk_firmware/pull/14928))
* Optimize matrix scanning by removing variable shifts ([#14947](https://github.com/qmk/qmk_firmware/pull/14947))
* Stop-gap forward-port Drop LED features for CTRL and ALT ([#14967](https://github.com/qmk/qmk_firmware/pull/14967))
* Remove SERIAL_MOUSE ([#14969](https://github.com/qmk/qmk_firmware/pull/14969))
* Relocate protocol files within tmk_core/common/ ([#14972](https://github.com/qmk/qmk_firmware/pull/14972))
* Move LTO logic from common.mk ([#14973](https://github.com/qmk/qmk_firmware/pull/14973))
* More platform/protocol alignment ([#14976](https://github.com/qmk/qmk_firmware/pull/14976))
* Add support to persist MD LED framework settings ([#14980](https://github.com/qmk/qmk_firmware/pull/14980))
* Enable configuration of PWM frequency for IS31FL3733B ([#14983](https://github.com/qmk/qmk_firmware/pull/14983))
* Remove `BOOTMAGIC_ENABLE = lite` option ([#15002](https://github.com/qmk/qmk_firmware/pull/15002))
* Manually format develop ([#15003](https://github.com/qmk/qmk_firmware/pull/15003))
* Require explicit enabling of RGB Matrix modes ([#15018](https://github.com/qmk/qmk_firmware/pull/15018))
* Remove deprecated KEYMAP alias ([#15037](https://github.com/qmk/qmk_firmware/pull/15037))
* Fix uart function prototypes ([#15162](https://github.com/qmk/qmk_firmware/pull/15162))
* Rename RGB fractal ([#15174](https://github.com/qmk/qmk_firmware/pull/15174))
* Format code according to conventions ([#15195](https://github.com/qmk/qmk_firmware/pull/15195))
* Format code according to conventions ([#15196](https://github.com/qmk/qmk_firmware/pull/15196))
* Add uint to char functions ([#15244](https://github.com/qmk/qmk_firmware/pull/15244))
* [Tests] Increase QMK test coverage take 2 ([#15269](https://github.com/qmk/qmk_firmware/pull/15269))
* Tidy up adjustable ws2812 timing ([#15299](https://github.com/qmk/qmk_firmware/pull/15299))
* Add script for performing compilation size regression investigations. ([#15303](https://github.com/qmk/qmk_firmware/pull/15303))
* WB32F3G71 config migration with removal of unnecessary items. ([#15309](https://github.com/qmk/qmk_firmware/pull/15309))
* Re-add encoder tests ([#15312](https://github.com/qmk/qmk_firmware/pull/15312))
CLI:
* Add check for non-assignment code in rules.mk ([#12108](https://github.com/qmk/qmk_firmware/pull/12108))
* Export list of `develop` PRs to be merged into `master` ([#13944](https://github.com/qmk/qmk_firmware/pull/13944))
* remove qmk console, which is now part of the global cli ([#14206](https://github.com/qmk/qmk_firmware/pull/14206))
* New CLI subcommand to create clang-compatible compilation database (`compile_commands.json`) ([#14370](https://github.com/qmk/qmk_firmware/pull/14370))
* compiledb: query include paths from gcc directly. ([#14462](https://github.com/qmk/qmk_firmware/pull/14462))
Submodule updates:
* Update to ChibiOS 20.3.4, support builds against trunk ([#14208](https://github.com/qmk/qmk_firmware/pull/14208))
* Update ChibiOS-Contrib ([#14408](https://github.com/qmk/qmk_firmware/pull/14408))
* Update ChibiOS-Contrib ([#14419](https://github.com/qmk/qmk_firmware/pull/14419))
* Purge uGFX. ([#14720](https://github.com/qmk/qmk_firmware/pull/14720))
Keyboards:
* Add support for PaladinPad, Arya pcb and move keyboards by KapCave into their own directory ([#14194](https://github.com/qmk/qmk_firmware/pull/14194))
* Move non-assignment code to post_rules.mk ([#14207](https://github.com/qmk/qmk_firmware/pull/14207))
* Helix use `post_rules.mk` ([#14216](https://github.com/qmk/qmk_firmware/pull/14216))
* handwired/symmetric70_proto use post_rules.mk ([#14235](https://github.com/qmk/qmk_firmware/pull/14235))
* Add Adelais PCB. Adelais RGB rev.3, Adelais rev. 4 APM32F103, Adelais AVR rev. 1 ([#14252](https://github.com/qmk/qmk_firmware/pull/14252))
* GMMK Pro keymap ([#14389](https://github.com/qmk/qmk_firmware/pull/14389))
* Migrate boston_meetup/2019 away from QWIIC_DRIVERS ([#14413](https://github.com/qmk/qmk_firmware/pull/14413))
* Migrate hadron away from QWIIC_DRIVERS ([#14415](https://github.com/qmk/qmk_firmware/pull/14415))
* Enable Proton C defaults for SplitKB Kyria ([#14490](https://github.com/qmk/qmk_firmware/pull/14490))
* Set USB max power consumption of kint* controllers to 100mA ([#14546](https://github.com/qmk/qmk_firmware/pull/14546))
* Remove complex `fn_actions` macros ([#14662](https://github.com/qmk/qmk_firmware/pull/14662))
* New Keyboard: TGR Jane CE ([#14713](https://github.com/qmk/qmk_firmware/pull/14713))
* Migrate satisfaction75 away from QWIIC_DRIVERS ([#14747](https://github.com/qmk/qmk_firmware/pull/14747))
* add Lefty keyboard ([#14898](https://github.com/qmk/qmk_firmware/pull/14898))
* overnumpad controller: Add support for turning off solenoid enable in low power. ([#15021](https://github.com/qmk/qmk_firmware/pull/15021))
* Reduce compile size for melgeek mach80 ([#15034](https://github.com/qmk/qmk_firmware/pull/15034))
* Update updated KPrepublic boards to be prepared for the update ([#15040](https://github.com/qmk/qmk_firmware/pull/15040))
* rename kprepublic bm keyboards to have a standardized naming format ([#15047](https://github.com/qmk/qmk_firmware/pull/15047))
* matrix/abelx - Update ChibiOS conf files ([#15130](https://github.com/qmk/qmk_firmware/pull/15130))
* Disable console on Keebio foldkb and iris rev3 ([#15260](https://github.com/qmk/qmk_firmware/pull/15260))
* Disable console on Sofle default keymap ([#15261](https://github.com/qmk/qmk_firmware/pull/15261))
* Disable features on SplitKB boards to fit under size ([#15262](https://github.com/qmk/qmk_firmware/pull/15262))
* Enable LTO on viktus/sp_mini via keymap ([#15263](https://github.com/qmk/qmk_firmware/pull/15263))
Keyboard fixes:
* Fix number of elements in info.json does not match errors ([#14213](https://github.com/qmk/qmk_firmware/pull/14213))
* Fix typos from 14248 ([#14261](https://github.com/qmk/qmk_firmware/pull/14261))
* Stream cheap via fixes/updates ([#14325](https://github.com/qmk/qmk_firmware/pull/14325))
* Map `PRODUCT` define to `keyboard_name` ([#14372](https://github.com/qmk/qmk_firmware/pull/14372))
* Fix BT rules for dosa40rgb ([#14497](https://github.com/qmk/qmk_firmware/pull/14497))
* Fix typo in mechloving adelais header files ([#14590](https://github.com/qmk/qmk_firmware/pull/14590))
* Fix for mechlovin/adelais/standard_led/arm/rev4 ([#14639](https://github.com/qmk/qmk_firmware/pull/14639))
* Fix OLED timeout on recent qwiic migrations ([#14775](https://github.com/qmk/qmk_firmware/pull/14775))
* Fix OLED timeout on satisfaction75 after migration from QWIIC ([#14780](https://github.com/qmk/qmk_firmware/pull/14780))
* Fix Compile issues for lefty ([#14982](https://github.com/qmk/qmk_firmware/pull/14982))
* Fix missing return for oled task on Lefty ([#15010](https://github.com/qmk/qmk_firmware/pull/15010))
* Fix missing return for oled task on Arabica37 ([#15011](https://github.com/qmk/qmk_firmware/pull/15011))
* Fix missing return for oled task in drashna userspace ([#15012](https://github.com/qmk/qmk_firmware/pull/15012))
* Fix size issues on pistachio pro via keymap ([#15017](https://github.com/qmk/qmk_firmware/pull/15017))
* Fix keycode collision in craftwalk keymap ([#15055](https://github.com/qmk/qmk_firmware/pull/15055))
* Fix compilation issues for yanghu Unicorne ([#15068](https://github.com/qmk/qmk_firmware/pull/15068))
* Fixup broken build after #15040 ([#15073](https://github.com/qmk/qmk_firmware/pull/15073))
* Fix compilation issues for Lime ([#15116](https://github.com/qmk/qmk_firmware/pull/15116))
* Fix additional board sizes for RGB Matrix ([#15170](https://github.com/qmk/qmk_firmware/pull/15170))
* Fix bandominedoni via keymap compilation ([#15171](https://github.com/qmk/qmk_firmware/pull/15171))
* Fix handful of boards compiling too large due to RGB matrix changes ([#15184](https://github.com/qmk/qmk_firmware/pull/15184))
* Fix oled_task_user for ffkeebs/puca ([#15185](https://github.com/qmk/qmk_firmware/pull/15185))
* More headroom. ([#15301](https://github.com/qmk/qmk_firmware/pull/15301))
* More headroom. ([#15302](https://github.com/qmk/qmk_firmware/pull/15302))
Others:
* Clean up some code block languages ([#14434](https://github.com/qmk/qmk_firmware/pull/14434))
* Clarify "nested" and "rolling" key sequences ([#14655](https://github.com/qmk/qmk_firmware/pull/14655))
* CI: Create GitHub Actions unit test workflow ([#15223](https://github.com/qmk/qmk_firmware/pull/15223))
* Squeezing space out of AVR ([#15243](https://github.com/qmk/qmk_firmware/pull/15243))
Bugs:
* Fix parallel builds w/ LTO on systems where make is not GNU make. ([#13955](https://github.com/qmk/qmk_firmware/pull/13955))
* fix automatic directory for qmk lint ([#14215](https://github.com/qmk/qmk_firmware/pull/14215))
* RN42 Bluetooth typo fix ([#14421](https://github.com/qmk/qmk_firmware/pull/14421))
* fix typo in backlight code from #14439 ([#14442](https://github.com/qmk/qmk_firmware/pull/14442))
* fix compilation issues with USB programmable buttons ([#14454](https://github.com/qmk/qmk_firmware/pull/14454))
* Fix descriptor for USB Programmable Buttons ([#14455](https://github.com/qmk/qmk_firmware/pull/14455))
* Make ChibiOS PAL interactions less STM32 specific - Round 2 ([#14456](https://github.com/qmk/qmk_firmware/pull/14456))
* fix logical minimum in Programmable Button rdesc ([#14464](https://github.com/qmk/qmk_firmware/pull/14464))
* Fix i2c_readReg16 ([#14730](https://github.com/qmk/qmk_firmware/pull/14730))
* Put back eeconfig_update_ functions ([#14751](https://github.com/qmk/qmk_firmware/pull/14751))
* Fix misplaced endif in led_matrix_drivers.c ([#14785](https://github.com/qmk/qmk_firmware/pull/14785))
* Fix builds for ChibiOS + Cortex-M0[+] ([#14879](https://github.com/qmk/qmk_firmware/pull/14879))
* Fix ccache default ([#14906](https://github.com/qmk/qmk_firmware/pull/14906))
* Fix issues with Oneshot disabling ([#14934](https://github.com/qmk/qmk_firmware/pull/14934))
* Fix develop after recent changes ([#14975](https://github.com/qmk/qmk_firmware/pull/14975))
* Fix up issues shown by clang-format of vusb ([#15004](https://github.com/qmk/qmk_firmware/pull/15004))
* Fix unterminated ifdef in ISSI 3733 driver ([#15014](https://github.com/qmk/qmk_firmware/pull/15014))
* Fix build failures caused by #12947. ([#15019](https://github.com/qmk/qmk_firmware/pull/15019))
* Fixup LED matrix. ([#15020](https://github.com/qmk/qmk_firmware/pull/15020))
* Revert to old init order for host driver ([#15029](https://github.com/qmk/qmk_firmware/pull/15029))
* Fixup #15029 ([#15031](https://github.com/qmk/qmk_firmware/pull/15031))
* RISC-V toolchain and picolibc fixes ([#15109](https://github.com/qmk/qmk_firmware/pull/15109))
* gcc10 LTO - Only specify adhlns assembler options at link time ([#15115](https://github.com/qmk/qmk_firmware/pull/15115))
* Add needed include to pointing_device.c ([#15167](https://github.com/qmk/qmk_firmware/pull/15167))
* Fix missing variable for Backlight Breathing ([#15199](https://github.com/qmk/qmk_firmware/pull/15199))
* Revert backlight pins on function call ([#15205](https://github.com/qmk/qmk_firmware/pull/15205))
* Fix timer include in override_wiring.c ([#15221](https://github.com/qmk/qmk_firmware/pull/15221))
* fix broken macro in transport.h ([#15239](https://github.com/qmk/qmk_firmware/pull/15239))
* Short term bodge for PRODUCT warning ([#15240](https://github.com/qmk/qmk_firmware/pull/15240))
* Remove use of __flash due to LTO issues ([#15268](https://github.com/qmk/qmk_firmware/pull/15268))
* Documentation typo fix ([#15298](https://github.com/qmk/qmk_firmware/pull/15298))
* [Core] Hotfix for HOLD_ON_OTHER_KEY_PRESS after #11059 ([#15307](https://github.com/qmk/qmk_firmware/pull/15307))
* Fix call to pointing_device_handle_buttons ([#15313](https://github.com/qmk/qmk_firmware/pull/15313))
* [Develop] Fix ploopy readme typos ([#15316](https://github.com/qmk/qmk_firmware/pull/15316))

2
docs/_langs.md
View file

@ -3,7 +3,7 @@
- [:cn: 中文](/zh-cn/)
- [:es: Español](/es/)
- [:fr: Français](/fr-fr/)
- [:he: עברית](/he-il/)
- [:israel: עברית](/he-il/)
- [:brazil: Português](/pt-br/)
- [:ru: Русский](/ru-ru/)
- [:jp: 日本語](/ja/)

3
docs/_summary.md
View file

@ -13,6 +13,7 @@
* [Troubleshooting QMK](faq_misc.md)
* [Debugging QMK](faq_debug.md)
* [Keymap FAQ](faq_keymap.md)
* [Squeezing Space from AVR](squeezing_avr.md)
* [Glossary](reference_glossary.md)
* Configurator
@ -128,7 +129,7 @@
* Breaking Changes
* [Overview](breaking_changes.md)
* [My Pull Request Was Flagged](breaking_changes_instructions.md)
* [Most Recent ChangeLog](ChangeLog/20210529.md "QMK v0.13.0 - 2021 May 29")
* [Most Recent ChangeLog](ChangeLog/20211127.md "QMK v0.15.0 - 2021 Nov 27")
* [Past Breaking Changes](breaking_changes_history.md)
* C Development

32
docs/breaking_changes.md
View file

@ -2,10 +2,13 @@
This document describes QMK's Breaking Change process. A Breaking Change is any change which modifies how QMK behaves in a way that in incompatible or potentially dangerous. We limit these changes so that users can have confidence that updating their QMK tree will not break their keymaps.
This also includes any keyboard moves within the repository.
The breaking change period is when we will merge PR's that change QMK in dangerous or unexpected ways. There is a built-in period of testing so we are confident that any problems caused are rare or unable to be predicted.
## What has been included in past Breaking Changes?
* [2021 Nov 27](ChangeLog/20211127.md)
* [2021 Aug 28](ChangeLog/20210828.md)
* [2021 May 29](ChangeLog/20210529.md)
* [2021 Feb 27](ChangeLog/20210227.md)
@ -17,16 +20,17 @@ The breaking change period is when we will merge PR's that change QMK in dangero
## When is the next Breaking Change?
The next Breaking Change is scheduled for August 28, 2021.
The next Breaking Change is scheduled for February 26, 2022.
### Important Dates
* [x] 2021 Aug 29 - `develop` is created. Each push to `master` is subsequently merged to `develop`
* [ ] 2021 Oct 31 - `develop` closed to new PR's.
* [ ] 2021 Oct 31 - Call for testers.
* [ ] 2021 Nov 26 - `master` is locked, no PR's merged.
* [ ] 2021 Nov 28 - Merge `develop` to `master`.
* [ ] 2021 Nov 28 - `master` is unlocked. PR's can be merged again.
* [x] 2022 Nov 27 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
* [ ] 2022 Jan 31 - `develop` closed to new PR's.
* [ ] 2022 Jan 31 - Call for testers.
* [ ] 2022 Feb 12 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
* [ ] 2022 Feb 24 - `master` is locked, no PR's merged.
* [ ] 2022 Feb 26 - Merge `develop` to `master`.
* [ ] 2022 Feb 26 - `master` is unlocked. PR's can be merged again.
## What changes will be included?
@ -36,8 +40,10 @@ If you want your breaking change to be included in this round you need to create
Criteria for acceptance:
* PR is complete and ready to merge
* PR has a ChangeLog
* The PR is complete and ready to merge
* The PR has a ChangeLog file describing the changes under `<qmk_firmware>/docs/Changelog/20220226`.
* This should be in Markdown format, with a name in the format `PR12345.md`, substituting the digits for your PR's ID.
* One strong recommendation that the ChangeLog document matches the PR description on GitHub, so as to ensure traceability.
# Checklists
@ -68,6 +74,14 @@ This happens immediately after the previous `develop` branch is merged.
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
## 2 Weeks Before Merge
* `develop` is now closed to existing PR merges, only bugfixes for previous merges may be included
* Post call for testers
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
## 1 Week Before Merge
* Announce that master will be closed from <2 Days Before> to <Day of Merge>

1
docs/breaking_changes_history.md
View file

@ -2,6 +2,7 @@
This page links to all previous changelogs from the QMK Breaking Changes process.
* [2021 Nov 27](ChangeLog/20211127.md) - version 0.15.0
* [2021 Aug 28](ChangeLog/20210828.md) - version 0.14.0
* [2021 May 29](ChangeLog/20210529.md) - version 0.13.0
* [2021 Feb 27](ChangeLog/20210227.md) - version 0.12.0

23
docs/chibios_upgrade_instructions.md
View file

@ -14,10 +14,10 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra
* First time around this will take several hours
* Subsequent updates will be incremental only
* Tagging example (work out which version first!):
* `git tag -a ver20.3.3 -m ver20.3.3 svn/tags/ver20.3.3`
* `git push qmk ver20.3.3`
* `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN svn/tags/ver20.3.3`
* `git push qmk breaking_YYYY_qN`
* `git tag -a ver20.3.4 -m ver20.3.4 svn/tags/ver20.3.4`
* `git push qmk ver20.3.4`
* `git tag -a develop_YYYY_qN -m develop_YYYY_qN svn/tags/ver20.3.4`
* `git push qmk develop_YYYY_qN`
## Getting ChibiOS-Contrib
@ -30,8 +30,8 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra
* `git checkout chibios-20.3.x`
* `git pull --ff-only`
* `git push origin chibios-20.3.x`
* `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN chibios-20.3.x`
* `git push origin breaking_YYYY_qN`
* `git tag -a develop_YYYY_qN -m develop_YYYY_qN chibios-20.3.x`
* `git push origin develop_YYYY_qN`
## Updating submodules
@ -42,15 +42,18 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra
* `git checkout -b chibios-version-bump`
* `cd lib/chibios`
* `git fetch --all --tags --prune`
* `git checkout breaking_YYYY_qN`
* `git checkout develop_YYYY_qN`
* `cd ../chibios-contrib`
* `git fetch --all --tags --prune`
* `git checkout breaking_YYYY_qN`
* `git checkout develop_YYYY_qN`
* Update ChibiOS configs within QMK
* `cd $QMK_FIRMWARE`
* `./util/chibios_conf_updater.sh`
* Build everything
* `cd $QMK_FIRMWARE`
* `qmk multibuild -j4`
* Make sure there are no errors
* Push to the repo
* `git commit -am 'Update ChibiOS to XXXXXXXXX'`
* `git commit -am 'Update ChibiOS to 99.9.9'`
* `git push --set-upstream origin chibios-version-bump`
* Make a PR to qmk_firmware with the new branch
* Make a PR to qmk_firmware with the new branch

91
docs/cli_commands.md
View file

@ -118,6 +118,68 @@ This command lets you configure the behavior of QMK. For the full `qmk config` d
qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
```
## `qmk cd`
This command opens a new shell in your `qmk_firmware` directory.
Note that if you are already somewhere within `QMK_HOME` (for example, the `keyboards/` folder), nothing will happen.
To exit out into the parent shell, simply type `exit`.
**Usage**:
```
qmk cd
```
## `qmk console`
This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLE=yes`.
**Usage**:
```
qmk console [-d <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>]
```
**Examples**:
Connect to all available keyboards and show their console messages:
```
qmk console
```
List all devices:
```
qmk console -l
```
Show only messages from clueboard/66/rev3 keyboards:
```
qmk console -d C1ED:2370
```
Show only messages from the second clueboard/66/rev3:
```
qmk console -d C1ED:2370:2
```
Show timestamps and VID:PID instead of names:
```
qmk console -n -t
```
Disable bootloader messages:
```
qmk console --no-bootloaders
```
## `qmk doctor`
This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to.
@ -320,11 +382,40 @@ qmk format-c
qmk format-c -b branch_name
```
## `qmk generate-compilation-database`
**Usage**:
```
qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP]
```
Creates a `compile_commands.json` file.
Does your IDE/editor use a language server but doesn't _quite_ find all the necessary include files? Do you hate red squigglies? Do you wish your editor could figure out `#include QMK_KEYBOARD_H`? You might need a [compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)! The qmk tool can build this for you.
This command needs to know which keyboard and keymap to build. It uses the same configuration options as the `qmk compile` command: arguments, current directory, and config files.
**Example:**
```
$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
$ qmk generate-compilation-database
Ψ Making clean
Ψ Gathering build instructions from make -n gh60/satan:colemak
Ψ Found 50 compile commands
Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json
```
Now open your dev environment and live a squiggly-free life.
## `qmk docs`
This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
Use the `-b`/`--browser` flag to automatically open the local webserver in your default browser.
This command runs `docsify serve` if `docsify-cli` is installed (which provides live reload), otherwise Python's builtin HTTP server module will be used.
**Usage**:
```

2
docs/cli_tab_complete.md
View file

@ -18,7 +18,7 @@ If you put `qmk_firmware` into another location you will need to adjust this pat
If you want the tab completion available to all users of the system you can add a symlink to the `qmk_tab_complete.sh` script:
`ln -s ~/qmk_firmware/util/qmk_tab_complete.sh /etc/profile.d/qmk_tab_complete.sh`
ln -s ~/qmk_firmware/util/qmk_tab_complete.sh /etc/profile.d/qmk_tab_complete.sh
### System Wide Copy

2
docs/coding_conventions_python.md
View file

@ -2,7 +2,7 @@
Most of our style follows PEP8 with some local modifications to make things less nit-picky.
* We target Python 3.6 for compatability with all supported platforms.
* We target Python 3.7 for compatability with all supported platforms.
* We indent using four (4) spaces (soft tabs)
* We encourage liberal use of comments
* Think of them as a story describing the feature

12
docs/compatible_microcontrollers.md
View file

@ -27,6 +27,7 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s
* [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
* [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
* [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html)
* [STM32F405](https://www.st.com/en/microcontrollers-microprocessors/stm32f405-415.html)
* [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html)
* [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html)
* [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html)
@ -36,13 +37,24 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s
* [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
* [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
* [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
### WestBerryTech (WB32)
* [WB32F3G71xx](http://www.westberrytech.com)
### NXP (Kinetis)
* [MKL26Z64](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/kl-series-cortex-m0-plus/kinetis-kl2x-72-96-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x)
* [MK20DX128](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-50-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-based-on-arm-cortex-m4-core:K20_50)
* [MK20DX256](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)
* [MK66FX1M0](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k6x-ethernet/kinetis-k66-180-mhz-dual-high-speed-full-speed-usbs-2mb-flash-microcontrollers-mcus-based-on-arm-cortex-m4-core:K66_180)
## Atmel ATSAM
There is limited support for one of Atmel's ATSAM microcontrollers, that being the [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) used by the [Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop).
## RISC-V
### GigaDevice
[ChibiOS-Contrib](https://github.com/ChibiOS/ChibiOS-Contrib) has support for the GigaDevice [GD32VF103 series](https://www.gigadevice.com/products/microcontrollers/gd32/risc-v/mainstream-line/gd32vf103-series/) microcontrollers and provides configurations for the [SiPeed Longan Nano](https://longan.sipeed.com/en/) development board that uses this microcontroller. It is largely pin and feature compatible with STM32F103 and STM32F303 microcontrollers.

12
docs/config_options.md
View file

@ -206,7 +206,7 @@ If you define these options you will enable the associated feature, which may in
* `#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 80`
* 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 80 ms if not defined. For macOS, you may want to set this to 200 or higher.
* Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPS_LOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher.
* `#define KEY_OVERRIDE_REPEAT_DELAY 500`
* Sets the key repeat interval for [key overrides](feature_key_overrides.md).
@ -404,8 +404,10 @@ However, this will automatically disable the legacy TMK Macros and Functions fea
Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU.
* `MAGIC_ENABLE`
* MAGIC actions (BOOTMAGIC without the boot)
* `BOOTMAGIC_ENABLE`
* Virtual DIP switch configuration
* Enable Bootmagic Lite
* `MOUSEKEY_ENABLE`
* Mouse keys
* `EXTRAKEY_ENABLE`
@ -418,6 +420,8 @@ Use these to enable or disable building certain features. The more you have enab
* Key combo feature
* `NKRO_ENABLE`
* USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
* `RING_BUFFERED_6KRO_REPORT_ENABLE`
* USB 6-Key Rollover - Instead of stopping any new input once 6 keys are pressed, the oldest key is released and the new key is pressed.
* `AUDIO_ENABLE`
* Enable the audio subsystem.
* `KEY_OVERRIDE_ENABLE`
@ -442,6 +446,10 @@ 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.
* `DEFERRED_EXEC_ENABLE`
* Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information.
* `DYNAMIC_TAPPING_TERM_ENABLE`
* Allows to configure the global tapping term on the fly.
## USB Endpoint Limitations

4
docs/configurator_default_keymaps.md
View file

@ -46,7 +46,7 @@ Now that we have the commit hash, we need the keymap (edited for readability):
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT_all(
KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_PSCR, KC_SLCK, KC_PAUS,
KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_PSCR, KC_SCRL, KC_PAUS,
KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, KC_BSPC, KC_INS, KC_HOME, KC_PGUP,
KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_DEL, KC_END, KC_PGDN,
KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT,
@ -74,7 +74,7 @@ The default keymap uses the `LAYOUT_all` macro, so that will be the value of the
"layout": "LAYOUT_all",
"layers": [
[
"KC_ESC", "KC_F1", "KC_F2", "KC_F3", "KC_F4", "KC_F5", "KC_F6", "KC_F7", "KC_F8", "KC_F9", "KC_F10", "KC_F11", "KC_F12", "KC_PSCR", "KC_SLCK", "KC_PAUS",
"KC_ESC", "KC_F1", "KC_F2", "KC_F3", "KC_F4", "KC_F5", "KC_F6", "KC_F7", "KC_F8", "KC_F9", "KC_F10", "KC_F11", "KC_F12", "KC_PSCR", "KC_SCRL", "KC_PAUS",
"KC_GRV", "KC_1", "KC_2", "KC_3", "KC_4", "KC_5", "KC_6", "KC_7", "KC_8", "KC_9", "KC_0", "KC_MINS", "KC_EQL", "KC_BSPC", "KC_BSPC", "KC_INS", "KC_HOME", "KC_PGUP",
"KC_TAB", "KC_Q", "KC_W", "KC_E", "KC_R", "KC_T", "KC_Y", "KC_U", "KC_I", "KC_O", "KC_P", "KC_LBRC", "KC_RBRC", "KC_BSLS", "KC_DEL", "KC_END", "KC_PGDN",
"KC_CAPS", "KC_A", "KC_S", "KC_D", "KC_F", "KC_G", "KC_H", "KC_J", "KC_K", "KC_L", "KC_SCLN", "KC_QUOT", "KC_NUHS", "KC_ENT",

74
docs/custom_quantum_functions.md
View file

@ -148,8 +148,8 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw
* GPIO pin initialisation: `void matrix_init_pins(void)`
* This needs to perform the low-level initialisation of all row and column pins. By default this will initialise the input/output state of each of the GPIO pins listed in `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no initialisation of pin state will occur within QMK itself, instead deferring to the keyboard's override.
* `COL2ROW`-based row reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)`
* `ROW2COL`-based column reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
* `COL2ROW`-based row reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
* `ROW2COL`-based column reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col, matrix_row_t row_shifter)`
* `DIRECT_PINS`-based reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
* These three functions need to perform the low-level retrieval of matrix state of relevant input pins, based on the matrix type. Only one of the functions should be implemented, if needed. By default this will iterate through `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, configuring the inputs and outputs based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no manipulation of matrix GPIO pin state will occur within QMK itself, instead deferring to the keyboard's override.
@ -214,11 +214,11 @@ This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_
```c
void suspend_power_down_user(void) {
rgb_matrix_set_suspend_state(true);
// code will run multiple times while keyboard is suspended
}
void suspend_wakeup_init_user(void) {
rgb_matrix_set_suspend_state(false);
// code will run on keyboard wakeup
}
```
@ -405,3 +405,69 @@ And you're done. The RGB layer indication will only work if you want it to. And
* Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`
The `val` is the value of the data that you want to write to EEPROM. And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM.
### Deferred Execution :id=deferred-execution
QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers.
#### Deferred executor callbacks
All _deferred executor callbacks_ have a common function signature and look like:
```c
uint32_t my_callback(uint32_t trigger_time, void *cb_arg) {
/* do something */
bool repeat = my_deferred_functionality();
return repeat ? 500 : 0;
}
```
The first argument `trigger_time` is the intended time of execution. If other delays prevent executing at the exact trigger time, this allows for "catch-up" or even skipping intervals, depending on the required behaviour.
The second argument `cb_arg` is the same argument passed into `defer_exec()` below, and can be used to access state information from the original call context.
The return value is the number of milliseconds to use if the function should be repeated -- if the callback returns `0` then it's automatically unregistered. In the example above, a hypothetical `my_deferred_functionality()` is invoked to determine if the callback needs to be repeated -- if it does, it reschedules for a `500` millisecond delay, otherwise it informs the deferred execution background task that it's done, by returning `0`.
?> Note that the returned delay will be applied to the intended trigger time, not the time of callback invocation. This allows for generally consistent timing even in the face of occasional late execution.
#### Deferred executor registration
Once a callback has been defined, it can be scheduled using the following API:
```c
deferred_token my_token = defer_exec(1500, my_callback, NULL);
```
The first argument is the number of milliseconds to wait until executing `my_callback` -- in the case above, `1500` milliseconds, or 1.5 seconds.
The third parameter is the `cb_arg` that gets passed to the callback at the point of execution. This value needs to be valid at the time the callback is invoked -- a local function value will be destroyed before the callback is executed and should not be used. If this is not required, `NULL` should be used.
The return value is a `deferred_token` that can consequently be used to cancel the deferred executor callback before it's invoked. If a failure occurs, the returned value will be `INVALID_DEFERRED_TOKEN`. Usually this will be as a result of supplying `0` to the delay, or a `NULL` for the callback. The other failure case is if there are too many deferred executions "in flight" -- this can be increased by changing the limit, described below.
#### Extending a deferred execution
The `deferred_token` returned by `defer_exec()` can be used to extend a the duration a pending execution waits before it gets invoked:
```c
// This will re-delay my_token's future execution such that it is invoked 800ms after the current time
extend_deferred_exec(my_token, 800);
```
#### Cancelling a deferred execution
The `deferred_token` returned by `defer_exec()` can be used to cancel a pending execution before it gets invoked:
```c
// This will cancel my_token's future execution
cancel_deferred_exec(my_token);
```
Once a token has been canceled, it should be considered invalid. Reusing the same token is not supported.
#### Deferred callback limits
There are a maximum number of deferred callbacks that can be scheduled, controlled by the value of the define `MAX_DEFERRED_EXECUTORS`.
If registrations fail, then you can increase this value in your keyboard or keymap `config.h` file, for example to 16 instead of the default 8:
```c
#define MAX_DEFERRED_EXECUTORS 16
```

1
docs/driver_installation_zadig.md
View file

@ -93,6 +93,7 @@ The device name here is the name that appears in Zadig, and may not be what the
|`usbasploader`|USBasp |`16C0:05DC` |libusbK|
|`apm32-dfu` |APM32 DFU ISP Mode |`314B:0106` |WinUSB |
|`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB |
|`gd32v-dfu` |GD32V BOOTLOADER |`28E9:0189` |WinUSB |
|`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB |
|`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB |
|`qmk-hid` |(keyboard name) Bootloader |`03EB:2067` |HidUsb |

4
docs/es/hardware_drivers.md
View file

@ -18,10 +18,6 @@ Soporte para direccionar pines en el ProMicro por su nombre Arduino en lugar de
Soporte para pantallas OLED basadas en SSD1306. Para obtener más información consulta la página de [Característica de Controlador OLED](feature_oled_driver.md).
## uGFX
Puedes hacer uso de uGFX dentro de QMK para manejar LCDs de caracteres y gráficos, matrices de LED, OLED, TFT, y otras tecnologías de visualización. Esto necesita ser mejor documentado. Si estás tratando de hacer esto y leer el código no ayuda por favor [abre una issue](https://github.com/qmk/qmk_firmware/issues/new) y podemos ayudarte por el proceso.
## WS2812 (Solo AVR)
Soporte para LEDs WS2811/WS2812{a,b,c}. Para obtener más información consulta la página de [Luz RGB](feature_rgblight.md).

2
docs/es/hardware_keyboard_guidelines.md
View file

@ -142,8 +142,6 @@ El año debe ser el primer año en que se crea el archivo. Si el trabajo se hizo
El núcleo de QMC está licenciado bajo la [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). Si estás enviando binarios para los procesadores AVR puedes elegir cualquiera [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) o [GPLv3](https://www.gnu.org/licenses/gpl.html). Si estás enviando binarios para ARM procesadores debes elegir [GPL Versión 3](https://www.gnu.org/licenses/gpl.html) para cumplir con los [ChibiOS](https://www.chibios.org) licencia GPLv3.
Si tu teclado hace uso de la [uGFX](https://gfx.io) características dentro de QMK debes cumplir con la [Licencia de uGFX](https://ugfx.io/license.html), que requiere una licencia comercial separada antes de vender un dispositivo que contiene uGFX.
## Detalles técnicos
Si estás buscando más información sobre cómo hacer que su teclado funcione con QMK, [echa un vistazo a la sección hardware](hardware.md)!

12
docs/faq_keymap.md
View file

@ -19,7 +19,7 @@ There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JI
Sometimes, for readability's sake, it's useful to define custom names for some keycodes. People often define custom names using `#define`. For example:
```c
#define FN_CAPS LT(_FL, KC_CAPSLOCK)
#define FN_CAPS LT(_FL, KC_CAPS)
#define ALT_TAB LALT(KC_TAB)
```
@ -38,8 +38,8 @@ As a quick fix try holding down `Space`+`Backspace` while you plug in your keybo
The key found on most modern keyboards that is located between `KC_RGUI` and `KC_RCTL` is actually called `KC_APP`. This is because when that key was invented there was already a key named `MENU` in the relevant standards, so MS chose to call that the `APP` key.
## `KC_SYSREQ` Isn't Working
Use keycode for Print Screen(`KC_PSCREEN` or `KC_PSCR`) instead of `KC_SYSREQ`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
## `KC_SYSTEM_REQUEST` Isn't Working
Use keycode for Print Screen (`KC_PRINT_SCREEN`/`KC_PSCR`) instead of `KC_SYSTEM_REQUEST`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
* https://en.wikipedia.org/wiki/Magic_SysRq_key
@ -47,7 +47,7 @@ See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
## Power Keys Aren't Working
Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_POWER` in the Keyboard/Keypad HID usage page, and `KC_SYSTEM_POWER` (or `KC_PWR`) in the Consumer page.
Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_KB_POWER` in the Keyboard/Keypad HID usage page, and `KC_SYSTEM_POWER` (or `KC_PWR`) in the Consumer page.
The former is only recognized on macOS, while the latter, `KC_SLEP` and `KC_WAKE` are supported by all three major operating systems, so it is recommended to use those instead. Under Windows, these keys take effect immediately, however on macOS they must be held down until a dialog appears.
@ -57,7 +57,7 @@ https://github.com/tmk/tmk_keyboard/issues/67
## Modifier/Layer Stuck
Modifier keys or layers can be stuck unless layer switching is configured properly.
For Modifier keys and layer actions you have to place `KC_TRANS` on same position of destination layer to unregister the modifier key or return to previous layer on release event.
For Modifier keys and layer actions you have to place `KC_TRNS` on same position of destination layer to unregister the modifier key or return to previous layer on release event.
* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
@ -75,7 +75,7 @@ This feature is for *mechanical lock switch* like [this Alps one](https://deskth
After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in your keymap instead.
Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `KC_CAPS`, `KC_NLCK` and `KC_SLCK`.***
Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `KC_CAPS`, `KC_NUM` and `KC_SCRL`.***
## Input Special Characters Other Than ASCII like Cédille 'Ç'

6
docs/faq_misc.md
View file

@ -36,7 +36,7 @@ Size after:
can retry, loading that one
- Some of the options you might specify in your keyboard's Makefile
consume extra memory; watch out for BOOTMAGIC_ENABLE,
MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE
- DFU tools do /not/ allow you to write into the bootloader (unless
you throw in an extra fruit salad of options), so there is little risk
there.
@ -49,10 +49,6 @@ First you have to compile firmware with the build option `NKRO_ENABLE` in **Make
Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work and you will need to switch to **6KRO** mode, in particular when you are in BIOS.
If your firmware was built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and kept over power cycles.
https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
## TrackPoint Needs Reset Circuit (PS/2 Mouse Support)
Without reset circuit you will have inconsistent result due to improper initialization of the hardware. See circuit schematic of TPM754:

178
docs/feature_auto_shift.md
View file

@ -26,20 +26,26 @@ down will repeat the shifted key, though this can be disabled with
once then immediately (within `TAPPING_TERM`) hold it down again (this works
with the shifted value as well if auto-repeat is disabled).
There are also the `get_auto_shift_repeat` and `get_auto_shift_no_auto_repeat`
functions for more granular control. Neither will have an effect unless
`AUTO_SHIFT_REPEAT_PER_KEY` or `AUTO_SHIFT_NO_AUTO_REPEAT_PER_KEY` respectively
are defined.
## Are There Limitations to Auto Shift?
Yes, unfortunately.
You will have characters that are shifted when you did not intend on shifting, and
other characters you wanted shifted, but were not. This simply comes down to
practice. As we get in a hurry, we think we have hit the key long enough for a
shifted version, but we did not. On the other hand, we may think we are tapping
the keys, but really we have held it for a little longer than anticipated.
Additionally, with keyrepeat the desired shift state can get mixed up. It will
always 'belong' to the last key pressed. For example, keyrepeating a capital
and then tapping something lowercase (whether or not it's an Auto Shift key)
will result in the capital's *key* still being held, but shift not.
1. You will have characters that are shifted when you did not intend on shifting, and
other characters you wanted shifted, but were not. This simply comes down to
practice. As we get in a hurry, we think we have hit the key long enough for a
shifted version, but we did not. On the other hand, we may think we are tapping
the keys, but really we have held it for a little longer than anticipated.
2. Additionally, with keyrepeat the desired shift state can get mixed up. It will
always 'belong' to the last key pressed. For example, keyrepeating a capital
and then tapping something lowercase (whether or not it's an Auto Shift key)
will result in the capital's *key* still being held, but shift not.
3. Auto Shift does not apply to Tap Hold keys. For automatic shifting of Tap Hold
keys see [Retro Shift](#retro-shift).
## How Do I Enable Auto Shift?
@ -96,6 +102,34 @@ quicker than normal and you will be set.
?> Auto Shift has three special keys that can help you get this value right very quick. See "Auto Shift Setup" for more details!
For more granular control of this feature, you can add the following to your `config.h`:
```c
#define AUTO_SHIFT_TIMEOUT_PER_KEY
```
You can then add the following function to your keymap:
```c
uint16_t get_autoshift_timeout(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
case AUTO_SHIFT_NUMERIC:
return 2 * get_generic_autoshift_timeout();
case AUTO_SHIFT_SPECIAL:
return get_generic_autoshift_timeout() + 50;
case AUTO_SHIFT_ALPHA:
default:
return get_generic_autoshift_timeout();
}
}
```
Note that you cannot override individual keys that are in one of those groups
if you are using them; trying to add a case for `KC_A` in the above example will
not compile as `AUTO_SHIFT_ALPHA` is there. A possible solution is a second switch
above to handle individual keys with no default case and only referencing the
groups in the below fallback switch.
### NO_AUTO_SHIFT_SPECIAL (simple define)
Do not Auto Shift special keys, which include -\_, =+, [{, ]}, ;:, '", ,<, .>,
@ -109,11 +143,24 @@ Do not Auto Shift numeric keys, zero through nine.
Do not Auto Shift alpha characters, which include A through Z.
### Auto Shift Per Key
### Auto Shift Per Key
This is a function that allows you to determine which keys shold be autoshifted, much like the tap-hold keys.
There are functions that allows you to determine which keys shold be autoshifted, much like the tap-hold keys.
The default function looks like this:
The first of these, used to simply add a key to Auto Shift, is `get_custom_auto_shifted_key`:
```c
bool get_custom_auto_shifted_key(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
case KC_DOT:
return true;
default:
return false;
}
}
```
For more granular control, there is `get_auto_shifted_key`. The default function looks like this:
```c
bool get_auto_shifted_key(uint16_t keycode, keyrecord_t *record) {
@ -127,13 +174,14 @@ bool get_auto_shifted_key(uint16_t keycode, keyrecord_t *record) {
# ifndef NO_AUTO_SHIFT_SPECIAL
case KC_TAB:
case KC_MINUS ... KC_SLASH:
case KC_NONUS_BSLASH:
case KC_NONUS_BACKSLASH:
# endif
return true;
}
return false;
return get_custom_auto_shifted_key(keycode, record);
}
```
This functionality is enabled by default, and does not need a define.
### AUTO_SHIFT_REPEAT (simple define)
@ -144,6 +192,106 @@ Enables keyrepeat.
Disables automatically keyrepeating when `AUTO_SHIFT_TIMEOUT` is exceeded.
## Custom Shifted Values
Especially on small keyboards, the default shifted value for many keys is not
optimal. To provide more customizability, there are two user-definable
functions, `autoshift_press/release_user`. These register or unregister the
correct value for the passed key. Below is an example adding period to Auto
Shift and making its shifted value exclamation point. Make sure to use weak
mods - setting real would make any keys following it use their shifted values
as if you were holding the key. Clearing of modifiers is handled by Auto Shift,
and the OS-sent shift value if keyrepeating multiple keys is always that of
the last key pressed (whether or not it's an Auto Shift key).
You can also have non-shifted keys for the shifted values (or even no shifted
value), just don't set a shift modifier!
```c
bool get_custom_auto_shifted_key(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
case KC_DOT:
return true;
default:
return false;
}
}
void autoshift_press_user(uint16_t keycode, bool shifted, keyrecord_t *record) {
switch(keycode) {
case KC_DOT:
register_code16((!shifted) ? KC_DOT : KC_EXLM);
break;
default:
if (shifted) {
add_weak_mods(MOD_BIT(KC_LSFT));
}
// & 0xFF gets the Tap key for Tap Holds, required when using Retro Shift
register_code16((IS_RETRO(keycode)) ? keycode & 0xFF : keycode);
}
}
void autoshift_release_user(uint16_t keycode, bool shifted, keyrecord_t *record) {
switch(keycode) {
case KC_DOT:
unregister_code16((!shifted) ? KC_DOT : KC_EXLM);
break;
default:
// & 0xFF gets the Tap key for Tap Holds, required when using Retro Shift
// The IS_RETRO check isn't really necessary here, always using
// keycode & 0xFF would be fine.
unregister_code16((IS_RETRO(keycode)) ? keycode & 0xFF : keycode);
}
}
```
## Retro Shift
Holding and releasing a Tap Hold key without pressing another key will ordinarily
result in only the hold. With `retro shift` enabled this action will instead
produce a shifted version of the tap keycode on release.
It does not require [Retro Tapping](tap_hold.md#retro-tapping) to be enabled, and
if both are enabled the state of `retro tapping` will only apply if the tap keycode
is not matched by Auto Shift. `RETRO_TAPPING_PER_KEY` and its corresponding
function, however, are checked before `retro shift` is applied.
To enable `retro shift`, add the following to your `config.h`:
```c
#define RETRO_SHIFT
```
If `RETRO_SHIFT` is defined to a value, hold times greater than that value will
not produce a tap on release for Mod Taps, and instead triggers the hold action.
This enables modifiers to be held for combining with mouse clicks without
generating taps on release. For example:
```c
#define RETRO_SHIFT 500
```
This value (if set) must be greater than one's `TAPPING_TERM`, as the key press
must be designated as a 'hold' by `process_tapping` before we send the modifier.
There is no such limitation in regards to `AUTO_SHIFT_TIMEOUT` for normal keys.
### Retro Shift and Tap Hold Configurations
Tap Hold Configurations work a little differently when using Retro Shift.
Referencing `TAPPING_TERM` makes little sense, as holding longer would result in
shifting one of the keys.
`IGNORE_MOD_TAP_INTERRUPT` changes *only* rolling from a mod tap (releasing it
first), sending both keys instead of the modifier on the second. Its effects on
nested presses are ignored.
As nested taps were changed to act as though `PERMISSIVE_HOLD` is set unless only
`IGNORE_MOD_TAP_INTERRUPT` is (outside of Retro Shift), and Retro Shift ignores
`IGNORE_MOD_TAP_INTERRUPT`, `PERMISSIVE_HOLD` has no effect on Mod Taps.
Nested taps will *always* act as though the `TAPPING_TERM` was exceeded for both
Mod and Layer Tap keys.
## Using Auto Shift Setup
This will enable you to define three keys temporarily to increase, decrease and report your `AUTO_SHIFT_TIMEOUT`.

6
docs/feature_bluetooth.md
View file

@ -17,9 +17,9 @@ Not Supported Yet but possible:
### Adafruit BLE SPI Friend
Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit SPI Friend. It's a Nordic nRF5182 based chip running Adafruit's custom firmware. Data is transmitted via Adafruit's SDEP over Hardware SPI. The [Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) is supported as it's an AVR mcu connected via SPI to the Nordic BLE chip with Adafruit firmware. If Building a custom board with the SPI friend it would be easiest to just use the pin selection that the 32u4 feather uses but you can change the pins in the config.h options with the following defines:
* #define AdafruitBleResetPin D4
* #define AdafruitBleCSPin B4
* #define AdafruitBleIRQPin E6
* `#define ADAFRUIT_BLE_RST_PIN D4`
* `#define ADAFRUIT_BLE_CS_PIN B4`
* `#define ADAFRUIT_BLE_IRQ_PIN E6`
A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip.

2
docs/feature_bootmagic.md
View file

@ -8,8 +8,6 @@ On some keyboards Bootmagic Lite is disabled by default. If this is the case, it
BOOTMAGIC_ENABLE = yes
```
?> You may see `lite` being used in place of `yes`.
Additionally, you may want to specify which key to use. This is especially useful for keyboards that have unusual matrices. To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
```c

4
docs/feature_combo.md
View file

@ -56,7 +56,7 @@ combo_t key_combos[COMBO_COUNT] = {
[AB_ESC] = COMBO(ab_combo, KC_ESC),
[JK_TAB] = COMBO(jk_combo, KC_TAB),
[QW_SFT] = COMBO(qw_combo, KC_LSFT)
[SD_LAYER] = COMBO(layer_combo, MO(_LAYER)),
[SD_LAYER] = COMBO(sd_combo, MO(_LAYER)),
};
```
@ -173,7 +173,7 @@ uint16_t get_combo_term(uint16_t index, combo_t *combo) {
// i.e. the exact array of keys you defined for the combo.
// This can be useful if your combos have a common key and you want to apply the
// same combo term for all of them.
if (combo->keys[0] == KC_ENTER) { // if first key in the array is KC_ENTER
if (combo->keys[0] == KC_ENT) { // if first key in the array is Enter
return 150;
}

2
docs/feature_encoders.md
View file

@ -81,7 +81,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) {
tap_code(KC_UP);
}
}
return true;
return false;
}
```

2
docs/feature_grave_esc.md
View file

@ -4,7 +4,7 @@ If you're using a 60% keyboard, or any other layout with no F-row, you will have
## Usage
Replace the `KC_GRAVE` key in your keymap (usually to the left of the `1` key) with `KC_GESC`. Most of the time this key will output `KC_ESC` when pressed. However, when Shift or GUI are held down it will output `KC_GRV` instead.
Replace the `KC_GRV` key in your keymap (usually to the left of the `1` key) with `KC_GESC`. Most of the time this key will output `KC_ESC` when pressed. However, when Shift or GUI are held down it will output `KC_GRV` instead.
## What Your OS Sees

29
docs/feature_haptic_feedback.md
View file

@ -4,9 +4,22 @@
The following options are currently available for haptic feedback in `rules.mk`:
`HAPTIC_ENABLE += DRV2605L`
```
HAPTIC_ENABLE = yes
`HAPTIC_ENABLE += SOLENOID`
HAPTIC_DRIVER += DRV2605L
HAPTIC_DRIVER += SOLENOID
```
The following `config.h` settings are available for all types of haptic feedback:
| Settings | Default | Description |
|--------------------------------------|---------------|---------------------------------------------------------------------------------------------------------------|
|`HAPTIC_ENABLE_PIN` | *Not defined* |Configures a pin to enable a boost converter for some haptic solution, often used with solenoid drivers. |
|`HAPTIC_ENABLE_PIN_ACTIVE_LOW` | *Not defined* |If defined then the haptic enable pin is active-low. |
|`HAPTIC_ENABLE_STATUS_LED` | *Not defined* |Configures a pin to reflect the current enabled/disabled status of haptic feedback. |
|`HAPTIC_ENABLE_STATUS_LED_ACTIVE_LOW` | *Not defined* |If defined then the haptic status led will be active-low. |
|`HAPTIC_OFF_IN_LOW_POWER` | `0` |If set to `1`, haptic feedback is disabled before the device is configured, and while the device is suspended. |
## Known Supported Hardware
@ -45,6 +58,7 @@ First you will need a build a circuit to drive the solenoid through a mosfet as
| Settings | Default | Description |
|----------------------------|----------------------|-------------------------------------------------------|
|`SOLENOID_PIN` | *Not defined* |Configures the pin that the Solenoid is connected to. |
|`SOLENOID_PIN_ACTIVE_LOW` | *Not defined* |If defined then the solenoid trigger pin is active low.|
|`SOLENOID_DEFAULT_DWELL` | `12` ms |Configures the default dwell time for the solenoid. |
|`SOLENOID_MIN_DWELL` | `4` ms |Sets the lower limit for the dwell. |
|`SOLENOID_MAX_DWELL` | `100` ms |Sets the upper limit for the dwell. |
@ -168,10 +182,17 @@ This mode sets continuous haptic feedback with the option to increase or decreas
The Haptic Exclusion is implemented as `__attribute__((weak)) bool get_haptic_enabled_key(uint16_t keycode, keyrecord_t *record)` in haptic.c. This allows a re-definition at the required level with the specific requirement / exclusion.
### NO_HAPTIC_MOD
With the entry of `#define NO_HAPTIC_MOD` in config.h, modifiers from Left Control to Right GUI will not trigger a feedback. This also includes modifiers in a Mod Tap configuration.
With the entry of `#define NO_HAPTIC_MOD` in config.h, the following keys will not trigger feedback:
* Usual modifier keys such as Control/Shift/Alt/Gui (For example `KC_LCTL`)
* `MO()` momentary keys. See also [Layers](feature_layers.md).
* `LM()` momentary keys with mod active.
* `LT()` layer tap keys, when held to activate a layer. However when tapped, and the key is quickly released, and sends a keycode, haptic feedback is still triggered.
* `TT()` layer tap toggle keys, when held to activate a layer. However when tapped `TAPPING_TOGGLE` times to permanently toggle the layer, on the last tap haptic feedback is still triggered.
* `MT()` mod tap keys, when held to keep a usual modifier key pressed. However when tapped, and the key is quickly released, and sends a keycode, haptic feedback is still triggered. See also [Mod-Tap](mod_tap.md).
### NO_HAPTIC_FN
With the entry of `#define NO_HAPTIC_FN` in config.h, layer keys will not rigger a feedback.
With the entry of `#define NO_HAPTIC_FN` in config.h, deprecated `fn_actions` type function keys will not trigger a feedback.
### NO_HAPTIC_ALPHA
With the entry of `#define NO_HAPTIC_ALPHA` in config.h, none of the alpha keys (A ... Z) will trigger a feedback.

6
docs/feature_key_overrides.md
View file

@ -39,7 +39,7 @@ For more customization possibilities, you may directly create a `key_override_t`
This shows how the mentioned example of sending `delete` when `shift` + `backspace` are pressed is realized:
```c
const key_override_t delete_key_override = ko_make_basic(MOD_MASK_SHIFT, KC_BSPACE, KC_DELETE);
const key_override_t delete_key_override = ko_make_basic(MOD_MASK_SHIFT, KC_BSPC, KC_DEL);
// This globally defines all key overrides to be used
const key_override_t **key_overrides = (const key_override_t *[]){
@ -107,10 +107,10 @@ The [Grave Escape feature](feature_grave_esc.md) is limited in its configurabili
```c
// Shift + esc = ~
const key_override_t tilde_esc_override = ko_make_basic(MOD_MASK_SHIFT, KC_ESC, S(KC_GRAVE));
const key_override_t tilde_esc_override = ko_make_basic(MOD_MASK_SHIFT, KC_ESC, S(KC_GRV));
// GUI + esc = `
const key_override_t grave_esc_override = ko_make_basic(MOD_MASK_GUI, KC_ESC, KC_GRAVE);
const key_override_t grave_esc_override = ko_make_basic(MOD_MASK_GUI, KC_ESC, KC_GRV);
const key_override_t **key_overrides = (const key_override_t *[]){
&tilde_esc_override,

2
docs/feature_layers.md
View file

@ -45,7 +45,7 @@ Once you have a good feel for how layers work and what you can do, you can get m
Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem.
Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h).
Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/action_layer.h).
## Functions :id=functions

58
docs/feature_led_matrix.md
View file

@ -49,10 +49,12 @@ Here is an example using 2 drivers.
!> Note the parentheses, this is so when `LED_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() % (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL)` will give very different results than `rand() % LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL`.
For split keyboards using `LED_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `DRIVER_ADDR_1` for one and `DRIVER_ADDR_2` for the other one. Then, in `g_is31_leds`, fill out the correct driver index (0 or 1). If using one address, use `DRIVER_ADDR_1` for both, and use index 0 for `g_is31_leds`.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | LED address
@ -164,26 +166,26 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
|Define |Description |
|-------------------------------------------------------|-----------------------------------------------|
|`#define DISABLE_LED_MATRIX_ALPHAS_MODS` |Disables `LED_MATRIX_ALPHAS_MODS` |
|`#define DISABLE_LED_MATRIX_BREATHING` |Disables `LED_MATRIX_BREATHING` |
|`#define DISABLE_LED_MATRIX_BAND` |Disables `LED_MATRIX_BAND` |
|`#define DISABLE_LED_MATRIX_BAND_PINWHEEL` |Disables `LED_MATRIX_BAND_PINWHEEL` |
|`#define DISABLE_LED_MATRIX_BAND_SPIRAL` |Disables `LED_MATRIX_BAND_SPIRAL` |
|`#define DISABLE_LED_MATRIX_CYCLE_LEFT_RIGHT` |Disables `LED_MATRIX_CYCLE_LEFT_RIGHT` |
|`#define DISABLE_LED_MATRIX_CYCLE_UP_DOWN` |Disables `LED_MATRIX_CYCLE_UP_DOWN` |
|`#define DISABLE_LED_MATRIX_CYCLE_OUT_IN` |Disables `LED_MATRIX_CYCLE_OUT_IN` |
|`#define DISABLE_LED_MATRIX_DUAL_BEACON` |Disables `LED_MATRIX_DUAL_BEACON` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `LED_MATRIX_SOLID_REACTIVE_SIMPLE` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_WIDE` |Disables `LED_MATRIX_SOLID_REACTIVE_WIDE` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_CROSS` |Disables `LED_MATRIX_SOLID_REACTIVE_CROSS` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTICROSS`|
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_NEXUS` |Disables `LED_MATRIX_SOLID_REACTIVE_NEXUS` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
|`#define DISABLE_LED_MATRIX_SOLID_SPLASH` |Disables `LED_MATRIX_SOLID_SPLASH` |
|`#define DISABLE_LED_MATRIX_SOLID_MULTISPLASH` |Disables `LED_MATRIX_SOLID_MULTISPLASH` |
|`#define DISABLE_LED_MATRIX_WAVE_LEFT_RIGHT` |Disables `LED_MATRIX_WAVE_LEFT_RIGHT` |
|`#define DISABLE_LED_MATRIX_WAVE_UP_DOWN` |Disables `LED_MATRIX_WAVE_UP_DOWN` |
|`#define ENABLE_LED_MATRIX_ALPHAS_MODS` |Enables `LED_MATRIX_ALPHAS_MODS` |
|`#define ENABLE_LED_MATRIX_BREATHING` |Enables `LED_MATRIX_BREATHING` |
|`#define ENABLE_LED_MATRIX_BAND` |Enables `LED_MATRIX_BAND` |
|`#define ENABLE_LED_MATRIX_BAND_PINWHEEL` |Enables `LED_MATRIX_BAND_PINWHEEL` |
|`#define ENABLE_LED_MATRIX_BAND_SPIRAL` |Enables `LED_MATRIX_BAND_SPIRAL` |
|`#define ENABLE_LED_MATRIX_CYCLE_LEFT_RIGHT` |Enables `LED_MATRIX_CYCLE_LEFT_RIGHT` |
|`#define ENABLE_LED_MATRIX_CYCLE_UP_DOWN` |Enables `LED_MATRIX_CYCLE_UP_DOWN` |
|`#define ENABLE_LED_MATRIX_CYCLE_OUT_IN` |Enables `LED_MATRIX_CYCLE_OUT_IN` |
|`#define ENABLE_LED_MATRIX_DUAL_BEACON` |Enables `LED_MATRIX_DUAL_BEACON` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE` |Enables `LED_MATRIX_SOLID_REACTIVE_SIMPLE` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_WIDE` |Enables `LED_MATRIX_SOLID_REACTIVE_WIDE` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Enables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_CROSS` |Enables `LED_MATRIX_SOLID_REACTIVE_CROSS` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTICROSS` |Enables `LED_MATRIX_SOLID_REACTIVE_MULTICROSS`|
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_NEXUS` |Enables `LED_MATRIX_SOLID_REACTIVE_NEXUS` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Enables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
|`#define ENABLE_LED_MATRIX_SOLID_SPLASH` |Enables `LED_MATRIX_SOLID_SPLASH` |
|`#define ENABLE_LED_MATRIX_SOLID_MULTISPLASH` |Enables `LED_MATRIX_SOLID_MULTISPLASH` |
|`#define ENABLE_LED_MATRIX_WAVE_LEFT_RIGHT` |Enables `LED_MATRIX_WAVE_LEFT_RIGHT` |
|`#define ENABLE_LED_MATRIX_WAVE_UP_DOWN` |Enables `LED_MATRIX_WAVE_UP_DOWN` |
## Custom LED Matrix Effects :id=custom-led-matrix-effects
@ -219,7 +221,7 @@ static bool my_cool_effect(effect_params_t* params) {
for (uint8_t i = led_min; i < led_max; i++) {
led_matrix_set_value(i, 0xFF);
}
return led_max < DRIVER_LED_TOTAL;
return led_matrix_check_finished_leds(led_max);
}
// e.g: A more complex effect, relying on external methods and state, with
@ -233,8 +235,7 @@ static bool my_cool_effect2_complex_run(effect_params_t* params) {
for (uint8_t i = led_min; i < led_max; i++) {
led_matrix_set_value(i, some_global_state++);
}
return led_max < DRIVER_LED_TOTAL;
return led_matrix_check_finished_leds(led_max);
}
static bool my_cool_effect2(effect_params_t* params) {
if (params->init) my_cool_effect2_complex_init(params);
@ -244,14 +245,7 @@ static bool my_cool_effect2(effect_params_t* params) {
#endif // LED_MATRIX_CUSTOM_EFFECT_IMPLS
```
For inspiration and examples, check out the built-in effects under `quantum/led_matrix_animations/`
For inspiration and examples, check out the built-in effects under `quantum/led_matrix/animations/`.
## Additional `config.h` Options :id=additional-configh-options

136
docs/feature_macros.md
View file

@ -4,7 +4,107 @@ Macros allow you to send multiple keystrokes when pressing just one key. QMK has
!> **Security Note**: While it is possible to use macros to send passwords, credit card numbers, and other sensitive information it is a supremely bad idea to do so. Anyone who gets a hold of your keyboard will be able to access that information by opening a text editor.
## `SEND_STRING()` & `process_record_user`
## Using Macros In JSON Keymaps
You can define up to 32 macros in a `keymap.json` file, as used by [Configurator](newbs_building_firmware_configurator.md), and `qmk compile`. You can define these macros in a list under the `macros` keyword, like this:
```json
{
"keyboard": "handwired/my_macropad",
"keymap": "my_keymap",
"macros": [
[
{"action":"down", "keycodes": ["LSFT"]},
"hello world1",
{"action": "up","keycodes": ["LSFT"]}
],
[
{"action":"tap", "keycodes": ["LCTL", "LALT", "DEL"]}
],
[
"ding!",
{"action":"beep"}
],
[
{"action":"tap", "keycodes": ["F1"]},
{"action":"delay", "duration": "1000"},
{"action":"tap", "keycodes": ["PGDN"]}
]
],
"layout": "LAYOUT_all",
"layers": [
["MACRO_0", "MACRO_1", "MACRO_2", "MACRO_3"]
]
}
```
### Selecting Your Host Keyboard Layout
If you type in a language other than English, or use a non-QWERTY layout like Colemak, Dvorak, or Workman, you may have set your computer's input language to match this layout. This presents a challenge when creating macros- you may need to type different keys to get the same letters! To address this you can add the `host_language` key to your keymap.json, like so:
```json
{
"keyboard": "handwired/my_macropad",
"keymap": "my_keymap",
"host_layout": "dvorak",
"macros": [
["Hello, World!"]
],
"layout": "LAYOUT_all",
"layers": [
["MACRO_0"]
]
}
```
The current list of available languages is:
| belgian | bepo | br_abnt2 | canadian_multilingual |
|:-------:|:----:|:--------:|:---------------------:|
| **colemak** | **croatian** | **czech** | **danish** |
| **dvorak_fr** | **dvorak** | **dvp** | **estonian** |
| **finnish** | **fr_ch** | **french_afnor** | **french** |
| **french_osx** | **german_ch** | **german** | **german_osx** |
| **hungarian** | **icelandic** | **italian** | **italian_osx_ansi** |
| **italian_osx_iso** | **jis** | **latvian** | **lithuanian_azerty** |
| **lithuanian_qwerty** | **norman** | **norwegian** | **portuguese** |
| **portuguese_osx_iso** | **romanian** | **serbian_latin** | **slovak** |
| **slovenian** | **spanish_dvorak** | **spanish** | **swedish** |
| **turkish_f** | **turkish_q** | **uk** | **us_international** |
| **workman** | **workman_zxcvm** |
### Macro Basics
Each macro is an array consisting of strings and objects (dictionaries.) Strings are typed to your computer while objects allow you to control how your macro is typed out.
#### Object Format
All objects have one required key: `action`. This tells QMK what the object does. There are currently 5 actions: beep, delay, down, tap, up
Only basic keycodes (prefixed by `KC_`) are supported. Do not include the `KC_` prefix when listing keycodes.
* `beep`
* Play a bell if the keyboard has [audio enabled](feature_audio.md).
* Example: `{"action": "beep"}`
* `delay`
* Pause macro playback. Duration is specified in milliseconds (ms).
* Example: `{"action": "delay", "duration": 500}`
* `down`
* Send a key down event for one or more keycodes.
* Example, single key: `{"action":"down", "keycodes": ["LSFT"]}`
* Example, multiple keys: `{"action":"down", "keycodes": ["CTRL", "LSFT"]}`
* `tap`
* Type a chord, which sends a down event for each key followed by an up event for each key.
* Example, single key: `{"action":"tap", "keycodes": ["F13"]}`
* Example, multiple keys: `{"action":"tap", "keycodes": ["CTRL", "LALT", "DEL"]}`
* `up`
* Send a key up event for one or more keycodes.
* Example, single key: `{"action":"up", "keycodes": ["LSFT"]}`
* Example, multiple keys: `{"action":"up", "keycodes": ["CTRL", "LSFT"]}`
## Using Macros in C Keymaps
### `SEND_STRING()` & `process_record_user`
Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`).
@ -91,7 +191,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
};
```
### Advanced Macros
#### Advanced Macros
In addition to the `process_record_user()` function, is the `post_process_record_user()` function. This runs after `process_record` and can be used to do things after a keystroke has been sent. This is useful if you want to have a key pressed before and released after a normal key, for instance.
@ -118,7 +218,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case KC_A ... KC_F21: //notice how it skips over F22
case KC_F23 ... KC_EXSEL: //exsel is the last one before the modifier keys
case KC_F23 ... KC_EXSL: //exsel is the last one before the modifier keys
if (!record->event.pressed) {
f22_tracker--;
if (!f22_tracker) {
@ -131,7 +231,7 @@ void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
```
### TAP, DOWN and UP
#### TAP, DOWN and UP
You may want to use keys in your macros that you can't write down, such as `Ctrl` or `Home`.
You can send arbitrary keycodes by wrapping them in:
@ -178,7 +278,7 @@ They can be used like this:
Which would send Left Control+`a` (Left Control down, `a`, Left Control up) - notice that they take strings (eg `"k"`), and not the `X_K` keycodes.
### Alternative Keymaps
#### Alternative Keymaps
By default, it assumes a US keymap with a QWERTY layout; if you want to change that (e.g. if your OS uses software Colemak), include this somewhere in your keymap:
@ -186,7 +286,7 @@ By default, it assumes a US keymap with a QWERTY layout; if you want to change t
#include "sendstring_colemak.h"
```
### Strings in Memory
#### Strings in Memory
If for some reason you're manipulating strings and need to print out something you just generated (instead of being a literal, constant string), you can use `send_string()`, like this:
@ -205,13 +305,13 @@ SEND_STRING(".."SS_TAP(X_END));
```
## Advanced Macro Functions
### Advanced Macro Functions
There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
?> You can also use the functions described in [Useful function](ref_functions.md) and [Checking modifier state](feature_advanced_keycodes#checking-modifier-state) for additional functionality. For example, `reset_keyboard()` allows you to reset the keyboard as part of a macro and `get_mods() & MOD_MASK_SHIFT` lets you check for the existence of active shift modifiers.
### `record->event.pressed`
#### `record->event.pressed`
This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
@ -223,15 +323,15 @@ This is a boolean value that can be tested to see if the switch is being pressed
}
```
### `register_code(<kc>);`
#### `register_code(<kc>);`
This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`.
### `unregister_code(<kc>);`
#### `unregister_code(<kc>);`
Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent.
### `tap_code(<kc>);`
#### `tap_code(<kc>);`
Sends `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
@ -239,31 +339,31 @@ If `TAP_CODE_DELAY` is defined (default 0), this function waits that many millis
If the keycode is `KC_CAPS`, it waits `TAP_HOLD_CAPS_DELAY` milliseconds instead (default 80), as macOS prevents accidental Caps Lock activation by waiting for the key to be held for a certain amount of time.
### `tap_code_delay(<kc>, <delay>);`
#### `tap_code_delay(<kc>, <delay>);`
Like `tap_code(<kc>)`, but with a `delay` parameter for specifying arbitrary intervals before sending the unregister event.
### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);`
#### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);`
These functions work similar to their regular counterparts, but allow you to use modded keycodes (with Shift, Alt, Control, and/or GUI applied to them).
Eg, you could use `register_code16(S(KC_5));` instead of registering the mod, then registering the keycode.
### `clear_keyboard();`
#### `clear_keyboard();`
This will clear all mods and keys currently pressed.
### `clear_mods();`
#### `clear_mods();`
This will clear all mods currently pressed.
### `clear_keyboard_but_mods();`
#### `clear_keyboard_but_mods();`
This will clear all keys besides the mods currently pressed.
## Advanced Example:
### Advanced Example:
### Super ALT↯TAB
#### Super ALT↯TAB
This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows.

16
docs/feature_oled_driver.md
View file

@ -38,7 +38,7 @@ Then in your `keymap.c` file, implement the OLED task call. This example assumes
```c
#ifdef OLED_ENABLE
void oled_task_user(void) {
bool oled_task_user(void) {
// Host Keyboard Layer Status
oled_write_P(PSTR("Layer: "), false);
@ -62,6 +62,8 @@ void oled_task_user(void) {
oled_write_P(led_state.num_lock ? PSTR("NUM ") : PSTR(" "), false);
oled_write_P(led_state.caps_lock ? PSTR("CAP ") : PSTR(" "), false);
oled_write_P(led_state.scroll_lock ? PSTR("SCR ") : PSTR(" "), false);
return false;
}
#endif
```
@ -133,19 +135,25 @@ oled_rotation_t oled_init_user(oled_rotation_t rotation) {
return rotation;
}
void oled_task_user(void) {
bool oled_task_user(void) {
if (is_keyboard_master()) {
render_status(); // Renders the current keyboard state (layer, lock, caps, scroll, etc)
} else {
render_logo(); // Renders a static logo
oled_scroll_left(); // Turns on scrolling
}
return false;
}
#endif
```
## Basic Configuration
These configuration options should be placed in `config.h`. Example:
```c
#define OLED_BRIGHTNESS 128
```
|Define |Default |Description |
|---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------|
|`OLED_DISPLAY_ADDRESS` |`0x3C` |The i2c address of the OLED Display |
@ -237,6 +245,7 @@ bool oled_init(oled_rotation_t rotation);
// Called at the start of oled_init, weak function overridable by the user
// rotation - the value passed into oled_init
// Return new oled_rotation_t if you want to override default rotation
oled_rotation_t oled_init_kb(oled_rotation_t rotation);
oled_rotation_t oled_init_user(oled_rotation_t rotation);
// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
@ -328,7 +337,8 @@ uint8_t oled_get_brightness(void);
void oled_task(void);
// Called at the start of oled_task, weak function overridable by the user
void oled_task_user(void);
bool oled_task_kb(void);
bool oled_task_user(void);
// Set the specific 8 lines rows of the screen to scroll.
// 0 is the default for start, and 7 for end, which is the entire

202
docs/feature_pointing_device.md
View file

@ -1,6 +1,6 @@
# Pointing Device :id=pointing-device
Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you.
Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and hardware driven. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you.
To enable Pointing Device, uncomment the following line in your rules.mk:
@ -8,12 +8,198 @@ To enable Pointing Device, uncomment the following line in your rules.mk:
POINTING_DEVICE_ENABLE = yes
```
To manipulate the mouse report, you can use the following functions:
## Sensor Drivers
* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer
* `pointing_device_set_report(report_mouse_t newMouseReport)` - Overrides and saves the report_mouse_t to be sent to the host computer
There are a number of sensors that are supported by default. Note that only one sensor can be enabled by `POINTING_DEVICE_DRIVER` at a time. If you need to enable more than one sensor, then you need to implement it manually.
Keep in mind that a report_mouse_t (here "mouseReport") has the following properties:
### ADNS 5050 Sensor
To use the ADNS 5050 sensor, add this to your `rules.mk`
```make
POINTING_DEVICE_DRIVER = adns5050
```
The ADNS 5050 sensor uses a serial type protocol for communication, and requires an additional light source.
| Setting | Description |
|--------------------|---------------------------------------------------------------------|
|`ADNS5050_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor. |
|`ADNS5050_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor. |
|`ADNS5050_CS_PIN` | (Required) The pin connected to the cable select pin of the sensor. |
The CPI range is 125-1375, in increments of 125. Defaults to 500 CPI.
### ADSN 9800 Sensor
To use the ADNS 9800 sensor, add this to your `rules.mk`
```make
POINTING_DEVICE_DRIVER = adns9800
```
The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surface tracking.
| Setting | Description | Default |
|------------------------|------------------------------------------------------------------------|---------------|
|`ADNS9800_CLOCK_SPEED` | (Optional) Sets the clock speed that the sensor runs at. | `2000000` |
|`ADNS9800_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false` |
|`ADNS9800_SPI_MODE` | (Optional) Sets the SPI Mode for the sensor. | `3` |
|`ADNS9800_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ |
|`ADNS9800_CS_PIN` | (Required) Sets the Cable Select pin connected to the sensor. | _not defined_ |
The CPI range is 800-8200, in increments of 200. Defaults to 1800 CPI.
### Analog Joystick
To use an analog joystick to control the pointer, add this to your `rules.mk`
```make
POINTING_DEVICE_DRIVER = analog_joystick
```
The Analog Joystick is an analog (ADC) driven sensor. There are a variety of joysticks that you can use for this.
| Setting | Description | Default |
|----------------------------------|----------------------------------------------------------------------------|---------------|
|`ANALOG_JOYSTICK_X_AXIS_PIN` | (Required) The pin used for the vertical/X axis. | _not defined_ |
|`ANALOG_JOYSTICK_Y_AXIS_PIN` | (Required) The pin used for the horizontal/Y axis. | _not defined_ |
|`ANALOG_JOYSTICK_AXIS_MIN` | (Optional) Sets the lower range to be considered movement. | `0` |
|`ANALOG_JOYSTICK_AXIS_MAX` | (Optional) Sets the upper range to be considered movement. | `1023` |
|`ANALOG_JOYSTICK_SPEED_REGULATOR` | (Optional) The divisor used to slow down movement. (lower makes it faster) | `20` |
|`ANALOG_JOYSTICK_READ_INTERVAL` | (Optional) The interval in milliseconds between reads. | `10` |
|`ANALOG_JOYSTICK_SPEED_MAX` | (Optional) The maxiumum value used for motion. | `2` |
|`ANALOG_JOYSTICK_CLICK_PIN` | (Optional) The pin wired up to the press switch of the analog stick. | _not defined_ |
### Cirque Trackpad
To use the Cirque Trackpad sensor, add this to your `rules.mk`:
```make
POINTING_DEVICE_DRIVER = cirque_pinnacle_i2c
```
or
```make
POINTING_DEVICE_DRIVER = cirque_pinnacle_spi
```
This supports the Cirque Pinnacle 1CA027 Touch Controller, which is used in the TM040040, TM035035 and the TM023023 trackpads. These are I2C or SPI compatible, and both configurations are supported.
| Setting | Description | Default |
|---------------------------------|---------------------------------------------------------------------------------|-----------------------|
|`CIRQUE_PINNACLE_X_LOWER` | (Optional) The minimum reachable X value on the sensor. | `127` |
|`CIRQUE_PINNACLE_X_UPPER` | (Optional) The maximum reachable X value on the sensor. | `1919` |
|`CIRQUE_PINNACLE_Y_LOWER` | (Optional) The minimum reachable Y value on the sensor. | `63` |
|`CIRQUE_PINNACLE_Y_UPPER` | (Optional) The maximum reachable Y value on the sensor. | `1471` |
|`CIRQUE_PINNACLE_TAPPING_TERM` | (Optional) Length of time that a touch can be to be considered a tap. | `TAPPING_TERM`/`200` |
|`CIRQUE_PINNACLE_TOUCH_DEBOUNCE` | (Optional) Length of time that a touch can be to be considered a tap. | `TAPPING_TERM`/`200` |
| I2C Setting | Description | Default |
|--------------------------|---------------------------------------------------------------------------------|---------|
|`CIRQUE_PINNACLE_ADDR` | (Required) Sets the I2C Address for the Cirque Trackpad | `0x2A` |
|`CIRQUE_PINNACLE_TIMEOUT` | (Optional) The timeout for i2c communication with the trackpad in milliseconds. | `20` |
| SPI Setting | Description | Default |
|-------------------------------|------------------------------------------------------------------------|---------------|
|`CIRQUE_PINNACLE_CLOCK_SPEED` | (Optional) Sets the clock speed that the sensor runs at. | `1000000` |
|`CIRQUE_PINNACLE_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false` |
|`CIRQUE_PINNACLE_SPI_MODE` | (Optional) Sets the SPI Mode for the sensor. | `1` |
|`CIRQUE_PINNACLE_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ |
|`CIRQUE_PINNACLE_SPI_CS_PIN` | (Required) Sets the Cable Select pin connected to the sensor. | _not defined_ |
Default Scaling/CPI is 1024.
### Pimoroni Trackball
To use the Pimoroni Trackball module, add this to your `rules.mk`:
```make
POINTING_DEVICE_DRIVER = pimoroni_trackball
```
The Pimoroni Trackball module is a I2C based breakout board with an RGB enable trackball.
| Setting | Description | Default |
|-------------------------------------|------------------------------------------------------------------------------------|---------|
|`PIMORONI_TRACKBALL_ADDRESS` | (Required) Sets the I2C Address for the Pimoroni Trackball. | `0x0A` |
|`PIMORONI_TRACKBALL_TIMEOUT` | (Optional) The timeout for i2c communication with the trackpad in milliseconds. | `100` |
|`PIMORONI_TRACKBALL_INTERVAL_MS` | (Optional) The update/read interval for the sensor in milliseconds. | `8` |
|`PIMORONI_TRACKBALL_SCALE` | (Optional) The multiplier used to generate reports from the sensor. | `5` |
|`PIMORONI_TRACKBALL_DEBOUNCE_CYCLES` | (Optional) The number of scan cycles used for debouncing on the ball press. | `20` |
|`PIMORONI_TRACKBALL_ERROR_COUNT` | (Optional) Specifies the number of read/write errors until the sensor is disabled. | `10` |
### PMW 3360 Sensor
To use the PMW 3360 sensor, add this to your `rules.mk`
```make
POINTING_DEVICE_DRIVER = pmw3360
```
The PMW 3360 is an SPI driven optical sensor, that uses a built in IR LED for surface tracking.
| Setting | Description | Default |
|-----------------------------|--------------------------------------------------------------------------------------------|---------------|
|`PMW3360_CS_PIN` | (Required) Sets the Cable Select pin connected to the sensor. | _not defined_ |
|`PMW3360_CLOCK_SPEED` | (Optional) Sets the clock speed that the sensor runs at. | `2000000` |
|`PMW3360_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false` |
|`PMW3360_SPI_MODE` | (Optional) Sets the SPI Mode for the sensor. | `3` |
|`PMW3360_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ |
|`ROTATIONAL_TRANSFORM_ANGLE` | (Optional) Allows for the sensor data to be rotated +/- 30 degrees directly in the sensor. | `0` |
The CPI range is 100-12000, in increments of 100. Defaults to 1600 CPI.
### Custom Driver
If you have a sensor type that isn't supported here, you can manually implement it, by adding these functions (with the correct implementation for your device):
```c
void pointing_device_driver_init(void) {}
report_mouse_t pointing_device_driver_get_report(report_mouse_t mouse_report) { return mouse_report; }
uint16_t pointing_device_driver_get_cpi(void) { return 0; }
void pointing_device_driver_set_cpi(uint16_t cpi) {}
```
!> Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/pointing_device_drivers.c`, but there may be cases where it's very specific to the hardware. So these functions are provided, just in case.
## Common Configuration
| Setting | Description | Default |
|-------------------------------|-----------------------------------------------------------------------|---------------|
|`POINTING_DEVICE_ROTATION_90` | (Optional) Rotates the X and Y data by 90 degrees. | _not defined_ |
|`POINTING_DEVICE_ROTATION_180` | (Optional) Rotates the X and Y data by 180 degrees. | _not defined_ |
|`POINTING_DEVICE_ROTATION_270` | (Optional) Rotates the X and Y data by 270 degrees. | _not defined_ |
|`POINTING_DEVICE_INVERT_X` | (Optional) Inverts the X axis report. | _not defined_ |
|`POINTING_DEVICE_INVERT_Y` | (Optional) Inverts the Y axis report. | _not defined_ |
|`POINTING_DEVICE_MOTION_PIN` | (Optional) If supported, will only read from sensor if pin is active. | _not defined_ |
## Callbacks and Functions
| Function | Description |
|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| `pointing_device_init_kb(void)` | Callback to allow for keyboard level initialization. Useful for additional hardware sensors. |
| `pointing_device_init_user(void)` | Callback to allow for user level initialization. Useful for additional hardware sensors. |
| `pointing_device_task_kb(mouse_report)` | Callback that sends sensor data, so keyboard code can intercept and modify the data. Returns a mouse report. |
| `pointing_device_task_user(mouse_report)` | Callback that sends sensor data, so user coe can intercept and modify the data. Returns a mouse report. |
| `pointing_device_handle_buttons(buttons, pressed, button)` | Callback to handle hardware button presses. Returns a `uint8_t`. |
| `pointing_device_get_cpi(void)` | Gets the current CPI/DPI setting from the sensor, if supported. |
| `pointing_device_set_cpi(uint16_t)` | Sets the CPI/DPI, if supported. |
| `pointing_device_get_report(void)` | Returns the current mouse report (as a `mouse_report_t` data structure). |
| `pointing_device_set_report(mouse_report)` | Sets the mouse report to the assigned `mouse_report_t` data structured passed to the function. |
| `pointing_device_send(void)` | Sends the current mouse report to the host system. Function can be replaced. |
| `has_mouse_report_changed(old, new)` | Compares the old and new `mouse_report_t` data and returns true only if it has changed. |
# Manipulating Mouse Reports
The report_mouse_t (here "mouseReport") has the following properties:
* `mouseReport.x` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ to the right, - to the left) on the x axis.
* `mouseReport.y` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ upward, - downward) on the y axis.
@ -21,8 +207,10 @@ Keep in mind that a report_mouse_t (here "mouseReport") has the following proper
* `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left).
* `mouseReport.buttons` - this is a uint8_t in which all 8 bits are used. These bits represent the mouse button state - bit 0 is mouse button 1, and bit 7 is mouse button 8.
Once you have made the necessary changes to the mouse report, you need to send it:
To manually manipulate the mouse reports outside of the `pointing_device_task_*` functions, you can use:
* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer
* `pointing_device_set_report(report_mouse_t newMouseReport)` - Overrides and saves the report_mouse_t to be sent to the host computer
* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report.
When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in `pointing_device_send()`, which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden.
@ -31,6 +219,8 @@ Additionally, by default, `pointing_device_send()` will only send a report when
Also, you use the `has_mouse_report_changed(new, old)` function to check to see if the report has changed.
## Example
In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function. Listen, this is an example:
```c

34
docs/feature_ps2_mouse.md
View file

@ -39,14 +39,8 @@ In your keyboard config.h:
```c
#ifdef PS2_USE_BUSYWAIT
# define PS2_CLOCK_PORT PORTD
# define PS2_CLOCK_PIN PIND
# define PS2_CLOCK_DDR DDRD
# define PS2_CLOCK_BIT 1
# define PS2_DATA_PORT PORTD
# define PS2_DATA_PIN PIND
# define PS2_DATA_DDR DDRD
# define PS2_DATA_BIT 2
# define PS2_CLOCK_PIN D1
# define PS2_DATA_PIN D2
#endif
```
@ -65,14 +59,8 @@ In your keyboard config.h:
```c
#ifdef PS2_USE_INT
#define PS2_CLOCK_PORT PORTD
#define PS2_CLOCK_PIN PIND
#define PS2_CLOCK_DDR DDRD
#define PS2_CLOCK_BIT 2
#define PS2_DATA_PORT PORTD
#define PS2_DATA_PIN PIND
#define PS2_DATA_DDR DDRD
#define PS2_DATA_BIT 5
#define PS2_CLOCK_PIN D2
#define PS2_DATA_PIN D5
#define PS2_INT_INIT() do { \
EICRA |= ((1<<ISC21) | \
@ -102,8 +90,8 @@ PS2_USE_INT = yes
In your keyboard config.h:
```c
#define PS2_CLOCK A8
#define PS2_DATA A9
#define PS2_CLOCK_PIN A8
#define PS2_DATA_PIN A9
```
And in the chibios specifig halconf.h:
@ -127,14 +115,8 @@ In your keyboard config.h:
```c
#ifdef PS2_USE_USART
#define PS2_CLOCK_PORT PORTD
#define PS2_CLOCK_PIN PIND
#define PS2_CLOCK_DDR DDRD
#define PS2_CLOCK_BIT 5
#define PS2_DATA_PORT PORTD
#define PS2_DATA_PIN PIND
#define PS2_DATA_DDR DDRD
#define PS2_DATA_BIT 2
#define PS2_CLOCK_PIN D5
#define PS2_DATA_PIN D2
/* synchronous, odd parity, 1-bit stop, 8-bit data, sample at falling edge */
/* set DDR of CLOCK as input to be slave */

178
docs/feature_rgb_matrix.md
View file

@ -21,6 +21,7 @@ You can use between 1 and 4 IS31FL3731 IC's. Do not specify `DRIVER_ADDR_<N>` de
|----------|-------------|---------|
| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
| `ISSI_3731_DEGHOST` | (Optional) Set this define to enable de-ghosting by halving Vcc during blanking time | |
| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | |
| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | |
@ -49,10 +50,12 @@ Here is an example using 2 drivers.
!> 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`.
For split keyboards using `RGB_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `DRIVER_ADDR_1` for one and `DRIVER_ADDR_2` for the other one. Then, in `g_is31_leds`, fill out the correct driver index (0 or 1). If using one address, use `DRIVER_ADDR_1` for both, and use index 0 for `g_is31_leds`.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | R location
@ -82,6 +85,9 @@ You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_<N>` de
|----------|-------------|---------|
| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
| `ISSI_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3733B only | 0 |
| `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) |
| `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) |
| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | |
| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | |
@ -93,6 +99,18 @@ You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_<N>` de
| `DRIVER_SYNC_3` | (Optional) Sync configuration for the third RGB driver | 0 |
| `DRIVER_SYNC_4` | (Optional) Sync configuration for the fourth RGB driver | 0 |
The IS31FL3733 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`ISSI_SWPULLUP`/`ISSI_CSPULLUP` are given the value of`PUR_0R`), the values that can be set to enable de-ghosting are as follows:
| `ISSI_SWPULLUP/ISSI_CSPULLUP` | Description |
|----------------------|-------------|
| `PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting |
| `PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) |
| `PUR_3KR` | The 3k Ohm resistor used at all times |
| `PUR_4KR` | The 4k Ohm resistor used at all times |
| `PUR_8KR` | The 8k Ohm resistor used at all times |
| `PUR_16KR` | The 16k Ohm resistor used at all times |
| `PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) |
Here is an example using 2 drivers.
```c
@ -122,7 +140,7 @@ Currently only 4 drivers are supported, but it would be trivial to support all 8
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | R location
@ -153,11 +171,25 @@ Configure the hardware via your `config.h`:
|----------|-------------|---------|
| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
| `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) |
| `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) |
| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | |
| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | |
| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | |
The IS31FL3737 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`ISSI_SWPULLUP`/`ISSI_CSPULLUP` are given the value of`PUR_0R`), the values that can be set to enable de-ghosting are as follows:
| `ISSI_SWPULLUP/ISSI_CSPULLUP` | Description |
|----------------------|-------------|
| `PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting |
| `PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) |
| `PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) |
| `PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) |
| `PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) |
| `PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) |
| `PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) |
| `PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) |
Here is an example using 2 drivers.
@ -181,12 +213,12 @@ Here is an example using 2 drivers.
```
!> 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.
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 `<keyboard>.c`:
```c
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | R location
@ -287,7 +319,7 @@ Here is an example using 2 drivers.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const aw_led __flash g_aw_leds[DRIVER_LED_TOTAL] = {
const aw_led PROGMEM g_aw_leds[DRIVER_LED_TOTAL] = {
/* Each AW20216 channel is controlled by a register at some offset between 0x00
* and 0xD7 inclusive.
* See drivers/awinic/aw20216.h for the mapping between register offsets and
@ -340,7 +372,7 @@ 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.
@ -383,7 +415,7 @@ All RGB keycodes are currently shared with the RGBLIGHT system:
* `RGB_MODE_*` keycodes will generally work, but not all of the modes are currently mapped to the correct effects for the RGB Matrix system.
`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MATRIX_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped.
`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MATRIX_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped.
!> By default, if you have both the [RGB Light](feature_rgblight.md) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
@ -420,7 +452,9 @@ enum rgb_matrix_effects {
RGB_MATRIX_JELLYBEAN_RAINDROPS, // Randomly changes a single key's hue and saturation
RGB_MATRIX_HUE_BREATHING, // Hue shifts up a slight ammount at the same time, then shifts back
RGB_MATRIX_HUE_PENDULUM, // Hue shifts up a slight ammount in a wave to the right, then back to the left
RGB_MATRIX_HUE_WAVE, // Hue shifts up a slight ammount and then back down in a wave to the right
RGB_MATRIX_HUE_WAVE, // Hue shifts up a slight ammount and then back down in a wave to the right
RGB_MATRIX_PIXEL_FRACTAL, // Single hue fractal filled keys pulsing horizontally out to edges
RGB_MATRIX_PIXEL_RAIN, // Randomly light keys with random hues
#if define(RGB_MATRIX_FRAMEBUFFER_EFFECTS)
RGB_MATRIX_TYPING_HEATMAP, // How hot is your WPM!
RGB_MATRIX_DIGITAL_RAIN, // That famous computer simulation
@ -443,51 +477,66 @@ enum rgb_matrix_effects {
};
```
You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`:
You can enable a single effect by defining `ENABLE_[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_GRADIENT_LEFT_RIGHT` |Disables `MATRIX_GRADIENT_LEFT_RIGHT` |
|`#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` |
|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |
|`#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_CYCLE_PINWHEEL` |Disables `RGB_MATRIX_CYCLE_PINWHEEL` |
|`#define DISABLE_RGB_MATRIX_CYCLE_SPIRAL` |Disables `RGB_MATRIX_CYCLE_SPIRAL` |
|`#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_HUE_BREATHING` |Disables `RGB_MATRIX_HUE_BREATHING` |
|`#define DISABLE_RGB_MATRIX_HUE_PENDULUM` |Disables `RGB_MATRIX_HUE_PENDULUM` |
|`#define DISABLE_RGB_MATRIX_HUE_WAVE ` |Disables `RGB_MATRIX_HUE_WAVE ` |
|`#define DISABLE_RGB_MATRIX_TYPING_HEATMAP` |Disables `RGB_MATRIX_TYPING_HEATMAP` |
|`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN` |Disables `RGB_MATRIX_DIGITAL_RAIN` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE` |Disables `RGB_MATRIX_SOLID_REACTIVE` |
|`#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` |
|Define |Description |
|------------------------------------------------------|----------------------------------------------|
|`#define ENABLE_RGB_MATRIX_ALPHAS_MODS` |Enables `RGB_MATRIX_ALPHAS_MODS` |
|`#define ENABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Enables `RGB_MATRIX_GRADIENT_UP_DOWN` |
|`#define ENABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT` |Enables `RGB_MATRIX_GRADIENT_LEFT_RIGHT` |
|`#define ENABLE_RGB_MATRIX_BREATHING` |Enables `RGB_MATRIX_BREATHING` |
|`#define ENABLE_RGB_MATRIX_BAND_SAT` |Enables `RGB_MATRIX_BAND_SAT` |
|`#define ENABLE_RGB_MATRIX_BAND_VAL` |Enables `RGB_MATRIX_BAND_VAL` |
|`#define ENABLE_RGB_MATRIX_BAND_PINWHEEL_SAT` |Enables `RGB_MATRIX_BAND_PINWHEEL_SAT` |
|`#define ENABLE_RGB_MATRIX_BAND_PINWHEEL_VAL` |Enables `RGB_MATRIX_BAND_PINWHEEL_VAL` |
|`#define ENABLE_RGB_MATRIX_BAND_SPIRAL_SAT` |Enables `RGB_MATRIX_BAND_SPIRAL_SAT` |
|`#define ENABLE_RGB_MATRIX_BAND_SPIRAL_VAL` |Enables `RGB_MATRIX_BAND_SPIRAL_VAL` |
|`#define ENABLE_RGB_MATRIX_CYCLE_ALL` |Enables `RGB_MATRIX_CYCLE_ALL` |
|`#define ENABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Enables `RGB_MATRIX_CYCLE_LEFT_RIGHT` |
|`#define ENABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Enables `RGB_MATRIX_CYCLE_UP_DOWN` |
|`#define ENABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Enables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |
|`#define ENABLE_RGB_MATRIX_CYCLE_OUT_IN` |Enables `RGB_MATRIX_CYCLE_OUT_IN` |
|`#define ENABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Enables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` |
|`#define ENABLE_RGB_MATRIX_CYCLE_PINWHEEL` |Enables `RGB_MATRIX_CYCLE_PINWHEEL` |
|`#define ENABLE_RGB_MATRIX_CYCLE_SPIRAL` |Enables `RGB_MATRIX_CYCLE_SPIRAL` |
|`#define ENABLE_RGB_MATRIX_DUAL_BEACON` |Enables `RGB_MATRIX_DUAL_BEACON` |
|`#define ENABLE_RGB_MATRIX_RAINBOW_BEACON` |Enables `RGB_MATRIX_RAINBOW_BEACON` |
|`#define ENABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Enables `RGB_MATRIX_RAINBOW_PINWHEELS` |
|`#define ENABLE_RGB_MATRIX_RAINDROPS` |Enables `RGB_MATRIX_RAINDROPS` |
|`#define ENABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Enables `RGB_MATRIX_JELLYBEAN_RAINDROPS` |
|`#define ENABLE_RGB_MATRIX_HUE_BREATHING` |Enables `RGB_MATRIX_HUE_BREATHING` |
|`#define ENABLE_RGB_MATRIX_HUE_PENDULUM` |Enables `RGB_MATRIX_HUE_PENDULUM` |
|`#define ENABLE_RGB_MATRIX_HUE_WAVE` |Enables `RGB_MATRIX_HUE_WAVE ` |
|`#define ENABLE_RGB_MATRIX_PIXEL_FRACTAL` |Enables `RGB_MATRIX_PIXEL_FRACTAL` |
|`#define ENABLE_RGB_MATRIX_PIXEL_RAIN` |Enables `RGB_MATRIX_PIXEL_RAIN` |
?> These modes don't require any additional defines.
|Framebuffer Defines |Description |
|------------------------------------------------------|----------------------------------------------|
|`#define ENABLE_RGB_MATRIX_TYPING_HEATMAP` |Enables `RGB_MATRIX_TYPING_HEATMAP` |
|`#define ENABLE_RGB_MATRIX_DIGITAL_RAIN` |Enables `RGB_MATRIX_DIGITAL_RAIN` |
?> These modes also require the `RGB_MATRIX_FRAMEBUFFER_EFFECTS` define to be available.
|Reactive Defines |Description |
|------------------------------------------------------|----------------------------------------------|
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Enables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE` |Enables `RGB_MATRIX_SOLID_REACTIVE` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE` |Enables `RGB_MATRIX_SOLID_REACTIVE_WIDE` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS` |Enables `RGB_MATRIX_SOLID_REACTIVE_CROSS` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`|
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS` |Enables `RGB_MATRIX_SOLID_REACTIVE_NEXUS` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
|`#define ENABLE_RGB_MATRIX_SPLASH` |Enables `RGB_MATRIX_SPLASH` |
|`#define ENABLE_RGB_MATRIX_MULTISPLASH` |Enables `RGB_MATRIX_MULTISPLASH` |
|`#define ENABLE_RGB_MATRIX_SOLID_SPLASH` |Enables `RGB_MATRIX_SOLID_SPLASH` |
|`#define ENABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Enables `RGB_MATRIX_SOLID_MULTISPLASH` |
?> These modes also require the `RGB_MATRIX_KEYPRESSES` or `RGB_MATRIX_KEYRELEASES` define to be available.
### RGB Matrix Effect Typing Heatmap :id=rgb-matrix-effect-typing-heatmap
@ -537,7 +586,7 @@ static bool my_cool_effect(effect_params_t* params) {
for (uint8_t i = led_min; i < led_max; i++) {
rgb_matrix_set_color(i, 0xff, 0xff, 0x00);
}
return led_max < DRIVER_LED_TOTAL;
return rgb_matrix_check_finished_leds(led_max);
}
// e.g: A more complex effect, relying on external methods and state, with
@ -551,8 +600,7 @@ static bool my_cool_effect2_complex_run(effect_params_t* params) {
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;
return rgb_matrix_check_finished_leds(led_max);
}
static bool my_cool_effect2(effect_params_t* params) {
if (params->init) my_cool_effect2_complex_init(params);
@ -562,7 +610,7 @@ static bool my_cool_effect2(effect_params_t* params) {
#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
```
For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animations/`
For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix/animations/`.
## Colors :id=colors
@ -694,7 +742,7 @@ Where `28` is an unused index from `eeconfig.h`.
### Indicators :id=indicators
If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, you can use the `rgb_matrix_indicators_kb` or `rgb_matrix_indicators_user` function for that:
If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, you can use the `rgb_matrix_indicators_kb` or `rgb_matrix_indicators_user` function for that:
```c
void rgb_matrix_indicators_kb(void) {
rgb_matrix_set_color(index, red, green, blue);
@ -749,18 +797,18 @@ This example sets the modifiers to be a specific color based on the layer state.
```c
void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
HSV hsv = {0, 255, 255};
if (layer_state_is(layer_state, 2)) {
hsv = {130, 255, 255};
} else {
hsv = {30, 255, 255};
}
if (hsv.v > rgb_matrix_get_val()) {
hsv.v = rgb_matrix_get_val();
}
RGB rgb = hsv_to_rgb(hsv);
for (uint8_t i = led_min; i <= led_max; i++) {
if (HAS_FLAGS(g_led_config.flags[i], 0x01)) { // 0x01 == LED_FLAG_MODIFIER
rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b);
@ -769,7 +817,7 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
}
```
If you want to indicate a Host LED status (caps lock, num lock, etc), you can use something like this to light up the caps lock key:
If you want to indicate a Host LED status (caps lock, num lock, etc), you can use something like this to light up the caps lock key:
```c
void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
@ -780,3 +828,13 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
}
}
```
#### Indicators without RGB Matrix Effect
If you want to just use RGB indicators without RGB matrix effect, it is not possible to disable the latter because toggling RGB off will disable everything. You can workaround it with solid effect and colors off using this init function:
```c
void keyboard_post_init_user(void) {
rgb_matrix_mode_noeeprom(RGB_MATRIX_SOLID_COLOR);
rgb_matrix_sethsv_noeeprom(HSV_OFF);
}
```

7
docs/feature_stenography.md
View file

@ -40,8 +40,8 @@ MOUSEKEY_ENABLE = no
In your keymap create a new layer for Plover. You will need to include `keymap_steno.h`. See `planck/keymaps/steno/keymap.c` for an example. Remember to create a key to switch to the layer as well as a key for exiting the layer. If you would like to switch modes on the fly you can use the keycodes `QK_STENO_BOLT` and `QK_STENO_GEMINI`. If you only want to use one of the protocols you may set it up in your initialization function:
```c
void matrix_init_user() {
steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT
void eeconfig_init_user() {
steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT
}
```
@ -129,7 +129,8 @@ As defined in `keymap_steno.h`.
|`STN_RES2`||(GeminiPR only)|
|`STN_PWR`||(GeminiPR only)|
If you do not want to hit two keys with one finger combined keycodes can be used. These are also defined in `keymap_steno.h`, and causes both keys to be reported as pressed or released. To use these keycodes define `STENO_COMBINEDMAP` in your `config.h` file
If you do not want to hit two keys with one finger combined keycodes can be used. These are also defined in `keymap_steno.h`, and causes both keys to be reported as pressed or released. To use these keycodes define `STENO_COMBINEDMAP` in your `config.h` file.
|Combined key | Key1 | Key 2 |
|---------------|--------|----------|
|STN_S3 | STN_S1 | STN_S2 |

12
docs/feature_tap_dance.md
View file

@ -29,7 +29,7 @@ After this, you'll want to use the `tap_dance_actions` array to specify what act
* `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
* ~~`ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`~~: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`.
* This is deprecated in favor of the Per Key Tapping Term functionality, as outlined [here](custom_quantum_functions.md#Custom_Tapping_Term). You'd want to check for the specific `TD()` macro that you want to use (such as `TD(TD_ESC_CAPS)`) instead of using this specific Tap Dance function.
* This is deprecated in favor of the Per Key Tapping Term functionality, as outlined [here](tap_hold.md#tapping-term). You'd want to check for the specific `TD()` macro that you want to use (such as `TD(TD_ESC_CAPS)`) instead of using this specific Tap Dance function.
The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise.
@ -299,7 +299,7 @@ void x_finished(qk_tap_dance_state_t *state, void *user_data) {
xtap_state.state = cur_dance(state);
switch (xtap_state.state) {
case TD_SINGLE_TAP: register_code(KC_X); break;
case TD_SINGLE_HOLD: register_code(KC_LCTRL); break;
case TD_SINGLE_HOLD: register_code(KC_LCTL); break;
case TD_DOUBLE_TAP: register_code(KC_ESC); break;
case TD_DOUBLE_HOLD: register_code(KC_LALT); break;
// Last case is for fast typing. Assuming your key is `f`:
@ -312,7 +312,7 @@ void x_finished(qk_tap_dance_state_t *state, void *user_data) {
void x_reset(qk_tap_dance_state_t *state, void *user_data) {
switch (xtap_state.state) {
case TD_SINGLE_TAP: unregister_code(KC_X); break;
case TD_SINGLE_HOLD: unregister_code(KC_LCTRL); break;
case TD_SINGLE_HOLD: unregister_code(KC_LCTL); break;
case TD_DOUBLE_TAP: unregister_code(KC_ESC); break;
case TD_DOUBLE_HOLD: unregister_code(KC_LALT);
case TD_DOUBLE_SINGLE_TAP: unregister_code(KC_X);
@ -393,6 +393,9 @@ void altlp_finished(qk_tap_dance_state_t *state, void *user_data) {
case TD_DOUBLE_SINGLE_TAP: // Allow nesting of 2 parens `((` within tapping term
tap_code16(KC_LPRN);
register_code16(KC_LPRN);
break;
default:
break;
}
}
@ -406,6 +409,9 @@ void altlp_reset(qk_tap_dance_state_t *state, void *user_data) {
break;
case TD_DOUBLE_SINGLE_TAP:
unregister_code16(KC_LPRN);
break;
default:
break;
}
}

2
docs/feature_userspace.md
View file

@ -252,4 +252,4 @@ Also, holding Shift will add the flash target (`:flash`) to the command. Holdin
And for the boards that lack a shift key, or that you want to always attempt the flashing part, you can add `FLASH_BOOTLOADER = yes` to the `rules.mk` of that keymap.
?> This should flash the newly compiled firmware automatically, using the correct utility, based on the bootloader settings (or default to just generating the HEX file). However, it should be noted that this may not work on all systems. AVRDUDE doesn't work on WSL, namely. And this doesn't support BootloadHID or mdloader.
?> This should flash the newly compiled firmware automatically, using the correct utility, based on the bootloader settings (or default to just generating the HEX file). However, it should be noted that this may not work on all systems. AVRDUDE doesn't work on WSL, namely.

1
docs/feature_velocikey.md
View file

@ -6,7 +6,6 @@ Velocikey is a feature that lets you control the speed of lighting effects (like
For Velocikey to take effect, there are two steps. First, when compiling your keyboard, you'll need to set `VELOCIKEY_ENABLE=yes` in `rules.mk`, e.g.:
```
BOOTMAGIC_ENABLE = no
MOUSEKEY_ENABLE = no
STENO_ENABLE = no
EXTRAKEY_ENABLE = yes

24
docs/feature_wpm.md
View file

@ -10,11 +10,23 @@ For split keyboards using soft serial, the computed WPM score will be available
## Configuration
|Define |Default | Description |
|-----------------------------|--------------|------------------------------------------------------------------------------------------|
|`WPM_SMOOTHING` |`0.0487` | Sets the smoothing to about 40 keystrokes |
|`WPM_ESTIMATED_WORD_SIZE` |`5` | This is the value used when estimating average word size (for regression and normal use) |
|`WPM_ALLOW_COUNT_REGRESSOIN` |_Not defined_ | If defined allows the WPM to be decreased when hitting Delete or Backspace |
| Define | Default | Description |
|------------------------------|---------------|------------------------------------------------------------------------------------------|
| `WPM_ESTIMATED_WORD_SIZE` | `5` | This is the value used when estimating average word size (for regression and normal use) |
| `WPM_ALLOW_COUNT_REGRESSION` | _Not defined_ | If defined allows the WPM to be decreased when hitting Delete or Backspace |
| `WPM_UNFILTERED` | _Not defined_ | If undefined (the default), WPM values will be smoothed to avoid sudden changes in value |
| `WPM_SAMPLE_SECONDS` | `5` | This defines how many seconds of typing to average, when calculating WPM |
| `WPM_SAMPLE_PERIODS` | `50` | This defines how many sampling periods to use when calculating WPM |
| `WPM_LAUNCH_CONTROL` | _Not defined_ | If defined, WPM values will be calculated using partial buffers when typing begins |
'WPM_UNFILTERED' is potentially useful if you're filtering data in some other way (and also because it reduces the code required for the WPM feature), or if reducing measurement latency to a minimum is important for you.
Increasing 'WPM_SAMPLE_SECONDS' will give more smoothly changing WPM values at the expense of slightly more latency to the WPM calculation.
Increasing 'WPM_SAMPLE_PERIODS' will improve the smoothness at which WPM decays once typing stops, at a cost of approximately this many bytes of firmware space.
If 'WPM_LAUNCH_CONTROL' is defined, whenever WPM drops to zero, the next time typing begins WPM will be calculated based only on the time since that typing began, instead of the whole period of time specified by WPM_SAMPLE_SECONDS. This results in reaching an accurate WPM value much faster, even when filtering is enabled and a large WPM_SAMPLE_SECONDS value is specified.
## Public Functions
|Function |Description |
@ -35,7 +47,7 @@ bool wpm_keycode_user(uint16_t keycode) {
} else if (keycode > 0xFF) {
keycode = 0;
}
if ((keycode >= KC_A && keycode <= KC_0) || (keycode >= KC_TAB && keycode <= KC_SLASH)) {
if ((keycode >= KC_A && keycode <= KC_0) || (keycode >= KC_TAB && keycode <= KC_SLSH)) {
return true;
}

4
docs/fr-fr/faq_debug.md
View file

@ -85,10 +85,6 @@ Premièrement, vous devez compiler le firmware avec l'option de compilation `NKR
Essayez la commande `Magic` **N** (`LShift+RShift+N` par défaut) si **NKRO** ne fonctionne toujours pas. Vous pouvez utiliser cette commande pour basculer temporairement entre le mode **NKRO** et **6KRO**. Sous certaines conditions, **NKRO** ne fonctionnera pas et vous devrez basculer en **6KRO**, en particulier lorsque vous êtes dans le BIOS.
Si votre firmware est compilé avec `BOOTMAGIC_ENABLE` vous devrez l'activer avec la commande `BootMagic` **N** (`Espace+N` par défaut). Cette option est enregistrée dans l'EEPROM et sera gardé entre deux cycles de démarrage.
https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
## Le TrackPoint a besoin Circuit de réinitialisation (Support de souris PS/2)
Sans circuit de réinitialisation vous allez avoir des résultats inconsistants à cause de la mauvaise initialisation du matériel. Regardez le schéma du circuit du TPM754.

2
docs/fr-fr/faq_keymap.md
View file

@ -6,7 +6,7 @@ Cette page couvre les questions souvent posées à propos des keymaps. Si vous n
Regardez [Keycodes](keycodes.md) pour une liste des keycodes disponibles. Certains keycodes spécifiques ont des documentations plus complètes de disponible.
Les keycodes sont définies dans [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
Les keycodes sont définies dans [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h).
## Quels sont les keycodes par défaut ?

1
docs/fr-fr/getting_started_github.md
View file

@ -32,7 +32,6 @@ Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca
Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
```
Vous avez maintenant votre fork QMK sur votre machine locale, vous pouvez ajouter votre keymap, la compiler et la flasher sur votre board. Une fois heureux avec vos changements, vous pouvez les ajouter, commit, et pousser vers votre fork comme suit:

1
docs/getting_started_github.md
View file

@ -32,7 +32,6 @@ Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca
Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
```
You now have your QMK fork on your local machine, and you can add your keymap, compile it and flash it to your board. Once you're happy with your changes, you can add, commit, and push them to your fork like this:

10
docs/getting_started_make_guide.md
View file

@ -55,7 +55,7 @@ Set these variables to `no` to disable them, and `yes` to enable them.
`BOOTMAGIC_ENABLE`
This allows you to hold a key and the salt key (space by default) and have access to a various EEPROM settings that persist over power loss. It's advised you keep this disabled, as the settings are often changed by accident, and produce confusing results that makes it difficult to debug. It's one of the more common problems encountered in help sessions.
This allows you to hold a key (usually Escape by default) to reset the EEPROM settings that persist over power loss and ready your keyboard to accept new firmware.
`MOUSEKEY_ENABLE`
@ -125,10 +125,6 @@ This allows you output audio on the C6 pin (needs abstracting). See the [audio p
Use this to debug changes to variable values, see the [tracing variables](unit_testing.md#tracing-variables) section of the Unit Testing page for more information.
`API_SYSEX_ENABLE`
This enables using the Quantum SYSEX API to send strings (somewhere?)
`KEY_LOCK_ENABLE`
This enables [key lock](feature_key_lock.md).
@ -149,6 +145,10 @@ Lets you replace the default matrix scanning routine with your own code. For fur
Lets you replace the default key debouncing routine with an alternative one. If `custom` you will need to provide your own implementation.
`DEFERRED_EXEC_ENABLE`
Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information.
## Customizing Makefile Options on a Per-Keymap Basis
If your keymap directory has a file called `rules.mk` any options you set in that file will take precedence over other `rules.mk` options for your particular keyboard.

4
docs/hardware_drivers.md
View file

@ -18,10 +18,6 @@ Support for addressing pins on the ProMicro by their Arduino name rather than th
Support for SSD1306 based OLED displays. For more information see the [OLED Driver Feature](feature_oled_driver.md) page.
## uGFX
You can make use of uGFX within QMK to drive character and graphic LCDs, LED arrays, OLED, TFT, and other display technologies. This needs to be better documented, if you are trying to do this and reading the code doesn't help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) and we can help you through the process.
## WS2812
Support for WS2811/WS2812{a,b,c} LED's. For more information see the [RGB Light](feature_rgblight.md) page.

2
docs/hardware_keyboard_guidelines.md
View file

@ -255,8 +255,6 @@ The year should be the first year the file is created. If work was done to that
The core of QMK is licensed under the [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). If you are shipping binaries for AVR processors you may choose either [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) or [GPLv3](https://www.gnu.org/licenses/gpl.html). If you are shipping binaries for ARM processors you must choose [GPL Version 3](https://www.gnu.org/licenses/gpl.html) to comply with the [ChibiOS](https://www.chibios.org) GPLv3 license.
If your keyboard makes use of the [uGFX](https://ugfx.io) features within QMK you must comply with the [uGFX License](https://ugfx.io/license.html), which requires a separate commercial license before selling a device containing uGFX.
## Technical Details
If you're looking for more information on making your keyboard work with QMK, [check out the hardware section](hardware.md)!

1
docs/he-il/getting_started_github.md
View file

@ -35,7 +35,6 @@ Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca
Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
```
</div>

48
docs/i2c_driver.md
View file

@ -187,7 +187,7 @@ Receive multiple bytes from the selected SPI device.
### `i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)`
Writes to a register on the I2C device.
Writes to a register with an 8-bit address on the I2C device.
#### Arguments
@ -208,9 +208,32 @@ Writes to a register on the I2C device.
---
### `i2c_status_t i2c_writeReg16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)`
Writes to a register with a 16-bit address (big endian) on the I2C device.
#### Arguments
- `uint8_t devaddr`
The 7-bit I2C address of the device.
- `uint16_t regaddr`
The register address to write to.
- `uint8_t *data`
A pointer to the data to transmit.
- `uint16_t length`
The number of bytes to write. Take care not to overrun the length of `data`.
- `uint16_t timeout`
The time in milliseconds to wait for a response from the target device.
#### Return Value
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
---
### `i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)`
Reads from a register on the I2C device.
Reads from a register with an 8-bit address on the I2C device.
#### Arguments
@ -229,6 +252,27 @@ Reads from a register on the I2C device.
---
### `i2c_status_t i2c_readReg16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)`
Reads from a register with a 16-bit address (big endian) on the I2C device.
#### Arguments
- `uint8_t devaddr`
The 7-bit I2C address of the device.
- `uint16_t regaddr`
The register address to read from.
- `uint16_t length`
The number of bytes to read. Take care not to overrun the length of `data`.
- `uint16_t timeout`
The time in milliseconds to wait for a response from the target device.
#### Return Value
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
---
### `i2c_status_t i2c_stop(void)`
Stop the current I2C transaction.

2
docs/internals_gpio_control.md
View file

@ -4,7 +4,7 @@ QMK has a GPIO control abstraction layer which is microcontroller agnostic. This
## Functions :id=functions
The following functions can provide basic control of GPIOs and are found in `quantum/quantum.h`.
The following functions provide basic control of GPIOs and are found in `platforms/<platform>/gpio.h`.
|Function |Description | Old AVR Examples | Old ChibiOS/ARM Examples |
|------------------------|--------------------------------------------------|-------------------------------------------------|-------------------------------------------------|

425
docs/isp_flashing_guide.md
View file

@ -1,263 +1,242 @@
# ISP Flashing Guide
ISP flashing (also known as ICSP flashing) is the process of programming a microcontroller directly. This allows you to replace the bootloader, or change the "fuses" on the controller, which control a number of hardware- and software-related functions, such as the speed of the controller, how it boots, and other options.
In order to flash a microcontroller over USB, it needs something called a bootloader. This bootloader lives in a specific section of the flash memory, and allows you to load the actual application firmware (in this case, QMK) into the rest of the flash.
The main use of ISP flashing for QMK is flashing or replacing the bootloader on your AVR-based controller (Pro Micros, or V-USB chips).
However, it can sometimes happen that the bootloader becomes corrupted and needs reflashing, or you may want to change the bootloader to another one. It's not possible to do this with the existing bootloader, because, of course, it is already running, and cannot overwrite itself. Instead, you will need to ISP flash the microcontroller.
?> This is only for programming AVR based boards, such as the Pro Micro or other ATmega controllers. It is not for Arm controllers, such as the Proton C.
There are several different kinds of bootloaders available for AVR microcontrollers. Most STM32 ARM-based microcontrollers already have a USB-capable bootloader in ROM, so generally do not need to be ISP flashed.
## Dealing with Corrupted Bootloaders
## Hardware
If you're having trouble flashing/erasing your board, and running into cryptic error messages like any of the following for a DFU based controller:
One of the following devices is required to perform the ISP flashing. The product links are to the official versions, however you can certainly source them elsewhere.
libusb: warning [darwin_transfer_status] transfer error: timed out
dfu.c:844: -ETIMEDOUT: Transfer timed out, NAK 0xffffffc4 (-60)
atmel.c:1627: atmel_flash: flash data dfu_download failed.
atmel.c:1629: Expected message length of 1072, got -60.
atmel.c:1434: Error flashing the block: err -2.
ERROR
Memory write error, use debug for more info.
commands.c:360: Error writing memory data. (err -4)
You'll also need some jumper wires to connect the ISP flasher and the target board. Some boards have an ISP header with the necessary pins broken out. If not, then you will need to temporarily solder the wires to the PCB -- usually to switch pins or directly to the MCU.
The wiring is fairly straightforward; for the most part, you'll be connecting like to like. Refer to the target MCU's datasheet for the exact `RESET`, `SCLK`, `MOSI` and `MISO` pins.
dfu.c:844: -EPIPE: a) Babble detect or b) Endpoint stalled 0xffffffe0 (-32)
Device is write protected.
dfu.c:252: dfu_clear_status( 0x7fff4fc2ea80 )
atmel.c:1434: Error flashing the block: err -2.
ERROR
Memory write error, use debug for more info.
commands.c:360: Error writing memory data. (err -4)
### Pro Micro as ISP
Or, if you see this sort of message for a Pro Micro based controller:
[SparkFun Pro Micro](https://www.sparkfun.com/products/12640)
avrdude: butterfly_recv(): programmer is not responding
avrdude: butterfly_recv(): programmer is not responding
avrdude: verification error, first mismatch at byte 0x002a
0x2b != 0x75
avrdude: verification error; content mismatch
avrdude: verification error; content mismatch
To use a 5V/16MHz Pro Micro as an ISP flashing tool, you will first need to load a [special firmware](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) onto it that emulates a hardware ISP flasher.
**AVRDUDE Programmer**: `avrisp`
**AVRDUDE Port**: Serial
You're likely going to need to ISP flash your board/device to get it working again.
#### Wiring
## Hardware Needed
|Pro Micro |Keyboard|
|-----------|--------|
|`VCC` |`VCC` |
|`GND` |`GND` |
|`10` (`B6`)|`RESET` |
|`15` (`B1`)|`SCLK` |
|`16` (`B2`)|`MOSI` |
|`14` (`B3`)|`MISO` |
You'll need one of the following to actually perform the ISP flashing (followed by the protocol they use):
!> Note that the `10` pin on the Pro Micro should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Pro Micro to the `RESET` on the keyboard.
* [SparkFun PocketAVR](https://www.sparkfun.com/products/9825) - (USB Tiny)
* [USBtinyISP AVR Programmer Kit](https://www.adafruit.com/product/46) - (USB Tiny)
* [USBasp](https://www.fischl.de/usbasp/) - (usbasp)
* [Teensy 2.0](https://www.pjrc.com/store/teensy.html) - (avrisp)
* [Pro Micro](https://www.sparkfun.com/products/12640) - (avrisp)
* [Bus Pirate](https://www.adafruit.com/product/237) - (buspirate)
### Teensy 2.0 as ISP
There are other devices that can be used to ISP flash, but these are the main ones. Also, all product links are to the official versions. You can source them elsewhere.
[PJRC Teensy 2.0](https://www.pjrc.com/store/teensy.html)
You'll also need something to wire your "ISP Programmer" to the device that you're programming. Some PCBs may have ISP headers that you can use directly, but this often isn't the case, so you'll likely need to solder to the controller itself or to different switches or other components.
To use a Teensy 2.0 as an ISP flashing tool, you will first need to load a [special firmware](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) onto it that emulates a hardware ISP flasher.
### The ISP Firmware
**AVRDUDE Programmer**: `avrisp`
**AVRDUDE Port**: Serial
The Teensy and Pro Micro controllers will need you to flash the ISP firmware to the controllers before you can use them as an ISP programmer. The rest of the hardware should come preprogrammed. So, for these controllers, download the correct hex file, and flash it first.
#### Wiring
* Teensy 2.0: [`util/teensy_2.0_ISP_B0.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) (`B0`)
* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) (`10/B6`)
|Teensy|Keyboard|
|------|--------|
|`VCC` |`VCC` |
|`GND` |`GND` |
|`B0` |`RESET` |
|`B1` |`SCLK` |
|`B2` |`MOSI` |
|`B3` |`MISO` |
Once you've flashed your controller, you won't need this hex file anymore.
!> Note that the `B0` pin on the Teensy should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Teensy to the `RESET` on the keyboard.
## Software Needed
### SparkFun PocketAVR / USBtinyISP / USBasp
The QMK Toolbox can be used for most (all) of this.
[SparkFun PocketAVR](https://www.sparkfun.com/products/9825)
[Adafruit USBtinyISP](https://www.adafruit.com/product/46)
[Thomas Fischl's USBasp](https://www.fischl.de/usbasp/)
However, you can grab the [Teensy Loader](https://www.pjrc.com/teensy/loader.html) to flash your Teensy 2.0 board, if you are using that. Or you can use `avrdude` (installed as part of `qmk_install.sh`), or [AVRDUDESS](https://blog.zakkemble.net/avrdudess-a-gui-for-avrdude/) (for Windows) to flash the Pro Micro, and the ISP flashing.
**AVRDUDE Programmer**: `usbtiny` / `usbasp`
**AVRDUDE Port**: `usb`
#### Wiring
## Wiring
|ISP |Keyboard|
|---------|--------|
|`VCC` |`VCC` |
|`GND` |`GND` |
|`RST` |`RESET` |
|`SCLK` |`SCLK` |
|`MOSI` |`MOSI` |
|`MISO` |`MISO` |
This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner.
### SparkFun Pocket AVR
### Bus Pirate
PocketAVR RST <-> Keyboard RESET
PocketAVR SCLK <-> Keyboard B1 (SCLK)
PocketAVR MOSI <-> Keyboard B2 (MOSI)
PocketAVR MISO <-> Keyboard B3 (MISO)
PocketAVR VCC <-> Keyboard VCC
PocketAVR GND <-> Keyboard GND
[Adafruit Bus Pirate](https://www.adafruit.com/product/237)
### USBasp
!> The 5-pin "ICSP" header is for ISP flashing the PIC microcontroller of the Bus Pirate. Connect your target board to the 10-pin header opposite the USB connector instead.
USBasp RST <-> Keyboard RESET
USBasp SCLK <-> Keyboard B1 (SCLK)
USBasp MOSI <-> Keyboard B2 (MOSI)
USBasp MISO <-> Keyboard B3 (MISO)
USBasp VCC <-> Keyboard VCC
USBasp GND <-> Keyboard GND
**AVRDUDE Programmer**: `buspirate`
**AVRDUDE Port**: Serial
### Teensy 2.0
#### Wiring
Teensy B0 <-> Keyboard RESET
Teensy B1 <-> Keyboard B1 (SCLK)
Teensy B2 <-> Keyboard B2 (MOSI)
Teensy B3 <-> Keyboard B3 (MISO)
Teensy VCC <-> Keyboard VCC
Teensy GND <-> Keyboard GND
!> Note that the B0 pin on the Teensy is wired to the RESET/RST pin on the keyboard's controller. ***DO NOT*** wire the RESET pin on the Teensy to the RESET on the keyboard.
### Pro Micro
Pro Micro 10 (B6) <-> Keyboard RESET
Pro Micro 15 (B1) <-> Keyboard B1 (SCLK)
Pro Micro 16 (B2) <-> Keyboard B2 (MOSI)
Pro Micro 14 (B3) <-> Keyboard B3 (MISO)
Pro Micro VCC <-> Keyboard VCC
Pro Micro GND <-> Keyboard GND
!> Note that the 10/B6 pin on the Pro Micro is wired to the RESET/RST pin on the keyboard's controller. ***DO NOT*** wire the RESET pin on the Pro Micro to the RESET on the keyboard.
## Flashing Your Keyboard
After you have your ISP programmer set up, and wired to your keyboard, it's time to flash your keyboard.
### The Bootloader File
The simplest and quickest way to get things back to normal is to flash only a bootloader to the keyboard. Once this is done, you can connect the keyboard normally and flash the keyboard like you normally would.
You can find the stock bootloaders in the [`util/` folder](https://github.com/qmk/qmk_firmware/tree/master/util). Be sure to flash the correct bootloader for your chip:
* **Atmel DFU**
* [ATmega16U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega16u4_1.0.1.hex)
* [ATmega32U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1.0.0.hex)
* [AT90USB64](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb64_1.0.0.hex)
* [AT90USB128](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128_1.0.1.hex)
* **Caterina**
* [Pro Micro (5V/16MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex)
* [Pro Micro (3.3V/8MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro8.hex)
* **BootloadHID (PS2AVRGB)**
* [ATmega32A](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_ps2avrgb_bootloadhid_1.0.1.hex)
If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU` and `BOOTLOADER` lines will have the value you need. It may differ between different versions of the board.
### Production Techniques
If you'd like to flash both the bootloader **and** the regular firmware at the same time, there are two options to do so. Manually, or with the `:production` target when compiling.
To do this manually:
1. Open the original firmware .hex file in a text editor
2. Remove the last line (which should be `:00000001FF` - this is an EOF message)
3. Copy the entire bootloader's contents onto a new line (with no empty lines between) and paste it at the end of the original file
4. Save it as a new file by naming it `<keyboard>_<keymap>_production.hex`
?> It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to use ISP again to write new firmware to your keyboard.
#### Create QMK DFU Bootloader and Production images
You can create the firmware, the QMK DFU Bootloader and the production firmware images for the board using the `:production` target when compiling. Once this is done, you'll see three files:
* `<keyboard>_<keymap>.hex`
* `<keyboard>_<keymap>_bootloader.hex`
* `<keyboard>_<keymap>_production.hex`
The QMK DFU bootloader has only really been tested on `atmega32u4` controllers (such as the AVR based Planck boards, and the Pro Micro), and hasn't been tested on other controllers. However, it will definitely not work on V-USB controllers, such as the `atmega32a` or `atmega328p`.
You can flash either the bootloader or the production firmware file. The production firmware file will take a lot longer to flash, since it's flashing a lot more data.
?> Note: You should stay with the same bootloader. If you're using DFU already, switching to QMK DFU is fine. But flashing QMK DFU onto a Pro Micro, for instance, has additional steps needed.
## Flashing Your Bootloader/Production File
Make sure your keyboard is unplugged from any device, and plug in your ISP Programmer.
If you want to change bootloader types, You'll need to use the command line.
### QMK Toolbox
1. `AVRISP device connected` or `USB Tiny device connected` will show up in yellow
2. Select the correct bootloader/production .hex file with the `Open` dialog (spaces can't be in the path)
3. Be sure the correct `Microcontroller` option for the keyboard you're flashing (not the ISP programmer) is selected
4. Hit `Flash`
5. Wait, as nothing will output for a while, especially with production files
If the verification and fuse checks are ok, you're done! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works.
### Command Line
Open a terminal (`cmd` on Windows, for instance) and navigate to your where your modified .hex file is. We'll pretend this file is called `main.hex`, and that your Teensy 2.0 is on the `COM3` port - if you're unsure, you can open your Device Manager, and look for `Ports > USB Serial Device`. Use that COM port here. You can confirm it's the right port with:
avrdude -c avrisp -P COM3 -p atmega32u4
and you should get something like the following output:
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.02s
avrdude: Device signature = 0x1e9587
avrdude: safemode: Fuses OK
avrdude done. Thank you.
Since our keyboard uses an `atmega32u4` (common), that is the chip we'll specify. This is the full command:
avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i
If your board uses an `atmega32a` (e.g. on a jj40), the command is this (the extra code at the end sets the fuses correctly):
avrdude -c avrisp -P COM3 -p atmega32 -U flash:w:main.hex:i -U hfuse:w:0xD0:m -U lfuse:w:0x0F:m
You should see a couple of progress bars, then you should see:
avrdude: verifying ...
avrdude: 32768 bytes of flash verified
avrdude: safemode: Fuses OK
avrdude done. Thank you.
Which means everything should be ok! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works.
If you're using a SparkFun PocketAVR Programmer, or another USB Tiny based ISP programmer, you will want to use something like this:
avrdude -c usbtiny -P usb -p atmega32u4
#### Advanced: Changing Fuses
If you're switching bootloaders, such as flashing QMK DFU on a Pro Micro, you will need to change the fuses, in additional to flashing the bootloader hex file. This is because `caterina` (the Pro Micro bootloader) and `dfu` handle the startup routines differently, and that behavior is controlled by the fuses.
!> This is one area that it is very important to be careful, as changing fuses is one of the ways that you can permanently brick your controller.
For this, we are assuming the 5V 16MHz versions of the `atmega32u4` (such as the 5V Pro Micro).
For DFU on the `atmega32u4`, these are the fuse settings that you want:
| Fuse | Setting |
|----------|------------------|
| Low | `0x5E` |
| High | `0xD9` or `0x99` |
| Extended | `0xC3` |
The High fuse can be 0xD9 or 0x99. The difference is that 0xD9 disables JTAG, which QMK Firmware disables via software as well, while 0x99 doesn't disable JTAG.
To set this add `-U lfuse:w:0x5E:m -U hfuse:w:0xD9:m -U efuse:w:0xC3:m` to your command. So the final command should look something like:
avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i -U lfuse:w:0x5E:m -U hfuse:w:0xD9:m -U efuse:w:0xC3:m
For Caterina on the `atmega32u4`, these are the fuse settings that you want:
| Fuse | Setting|
|Bus Pirate|Keyboard|
|----------|--------|
| Low | `0xFF` |
| High | `0xD8` |
| Extended | `0xCB` |
|`+5V` |`VCC` |
|`GND` |`GND` |
|`RST` |`RESET` |
|`CLK` |`SCLK` |
|`MOSI` |`MOSI` |
|`MISO` |`MISO` |
To set this add `-U lfuse:w:0xFF:m -U hfuse:w:0xD8:m -U efuse:w:0xCB:m` to your command. So the final command should look something like:
## Software
avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i -U lfuse:w:0xFF:m -U hfuse:w:0xD8:m -U efuse:w:0xCB:m
[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) supports flashing both the ISP firmware and bootloader, but note that it cannot (currently) set the AVR fuse bytes for the actual ISP flashing step, so you may want to work with `avrdude` directly instead.
Setting up the [QMK environment](newbs.md) is highly recommended, as it automatically installs `avrdude` along with a host of other tools.
If you are using a different controller or want different configuration, you can use [this AVR Fuse Calculator](https://www.engbedded.com/fusecalc/) to find a better value for you.
## Bootloader Firmware
## Help
One of these files is what you will be ISP flashing onto the board. The default fuses are also listed.
If you have any questions/problems, feel free to [open an issue](https://github.com/qmk/qmk_firmware/issues/new)!
If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU` and `BOOTLOADER` lines will have the values you need. It may differ between different versions of the board.
### Atmel DFU
These are the [factory default bootloaders](https://www.microchip.com/content/dam/mchp/documents/OTH/ProductDocuments/SoftwareLibraries/Firmware/megaUSB_DFU_Bootloaders.zip) shipped by Atmel (now Microchip). Note that the AT90USB64 and AT90USB128 bootloaders are [slightly modified](https://github.com/qmk/qmk_firmware/pull/14064), due to a bug causing them to not enumerate properly in Windows 8 and later.
|MCU |Low |High |Extended|USB ID |
|--------------------------------------------------------------------------------------------------|------|-------------------------------|--------|-----------|
|[ATmega16U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega16u4_1.0.1.hex)|`0x5E`|`0x99` / `0xD9` (JTAG disabled)|`0xF3` |`03EB:2FF3`|
|[ATmega32U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1.0.0.hex)|`0x5E`|`0x99` / `0xD9` (JTAG disabled)|`0xF3` |`03EB:2FF4`|
|[AT90USB64](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb64_1.0.0.hex) |`0x5E`|`0x9B` / `0xDB` (JTAG disabled)|`0xF3` |`03EB:2FF9`|
|[AT90USB128](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128_1.0.1.hex)|`0x5E`|`0x99` / `0xD9` (JTAG disabled)|`0xF3` |`03EB:2FFB`|
### Caterina
This is the default Arduino-style bootloader derived from the [LUFA CDC bootloader](https://github.com/abcminiuser/lufa/tree/master/Bootloaders/CDC), and is only for the ATmega32U4.
There are several variants depending on the vendor, but they all mostly work the same way. The SparkFun variants, for example, require the `RESET` pin to be [grounded twice quickly](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide#ts-reset) in order to stay in bootloader mode for more than 750 ms.
|MCU |Low |High |Extended|USB ID |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|------|------|--------|-----------|
|[SparkFun Pro Micro (3V3/8MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro8.hex) |`0xFF`|`0xD8`|`0xFE` |`1B4F:9203`|
|[SparkFun Pro Micro (5V/16MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex) |`0xFF`|`0xD8`|`0xFB` |`1B4F:9205`|
|[SparkFun LilyPadUSB (and some Pro Micro clones)](https://github.com/sparkfun/Arduino_Boards/blob/main/sparkfun/avr/bootloaders/caterina/Caterina-lilypadusb.hex)|`0xFF`|`0xD8`|`0xFE` |`1B4F:9207`|
|[Pololu A-Star 32U4](https://github.com/pololu/a-star/blob/master/bootloaders/caterina/Caterina-A-Star.hex)* |`0xFF`|`0xD0`|`0xF8` |`1FFB:0101`|
|[Adafruit Feather 32U4](https://github.com/adafruit/Caterina-Bootloader/blob/master/Built%20Firmwares/Caterina-Feather32u4.hex) |`0xFF`|`0xD8`|`0xFB` |`239A:000C`|
|[Adafruit ItsyBitsy 32U4 (3V3/8MHz)](https://github.com/adafruit/Caterina-Bootloader/blob/master/Caterina_itsybitsy3V.hex)* |`0xFF`|`0xD8`|`0xFB` |`239A:000D`|
|[Adafruit ItsyBitsy 32U4 (5V/16MHz)](https://github.com/adafruit/Caterina-Bootloader/blob/master/Caterina_itsybitsy5V.hex) |`0xFF`|`0xD8`|`0xFB` |`239A:000E`|
|[Arduino Leonardo](https://github.com/arduino/ArduinoCore-avr/blob/master/bootloaders/caterina/Caterina-Leonardo.hex)* |`0xFF`|`0xD8`|`0xFB` |`2341:0036`|
|[Arduino Micro](https://github.com/arduino/ArduinoCore-avr/blob/master/bootloaders/caterina/Caterina-Micro.hex)* |`0xFF`|`0xD8`|`0xFB` |`2341:0037`|
?> Files marked with a * have combined Arduino sketches, which runs by default and also appears as a serial port. However, this is *not* the bootloader device.
### BootloadHID (PS2AVRGB)
This bootloader is primarily for keyboards originally designed for the PS2AVRGB firmware and Bootmapper Client. It is not recommended for use in new designs.
|MCU |Low |High |USB ID |
|-----------------------------------------------------------------------------------------------------------|------|------|-----------|
|[ATmega32A](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_ps2avrgb_bootloadhid_1.0.1.hex)|`0x0F`|`0xD0`|`16C0:05DF`|
### USBaspLoader
USBaspLoader is a bootloader based on V-USB that emulates a hardware USBasp device. It runs on ATmega32A and ATmega328P MCUs.
Precompiled `.hex` files are generally not available, but you can compile it yourself by setting up the QMK environment and following Coseyfannitutti's guide for the appropriate MCU:
|MCU |Low |High |Extended|USB ID |
|-------------------------------------------------------------------------------------|------|------|--------|-----------|
|[ATmega32A](https://github.com/coseyfannitutti/discipline/tree/master/doc/bootloader)|`0x1F`|`0xC0`|*n/a* |`16C0:05DC`|
|[ATmega328P](https://github.com/coseyfannitutti/discipad/tree/master/doc/bootloader) |`0xD7`|`0xD0`|`0x04` |`16C0:05DC`|
Note that some boards may have their own specialized build of this bootloader in a separate repository. This will usually be linked to in the board's readme.
## Flashing the Bootloader
Open a new Terminal window - if you are on Windows, use MSYS2 or QMK MSYS, not the Command Prompt. Navigate to the directory your bootloader `.hex` is in. Now it's time to run the `avrdude` command.
The syntax of `avrdude` is:
```
avrdude -c <programmer> -P <port> -p <mcu> -U flash:w:<filename>:i
```
* `<programmer>` corresponds to the programmer type listed for each ISP flasher in the [Hardware](#hardware) section, for example `avrisp`.
* `<port>` is the serial port that appears when you plug the ISP flasher in, if any. For some programmers this is simply `usb` (or you can omit the `-P` argument completely) since they do not operate as a serial device.
* Windows: `COMx` - check Device Manager, under the "Ports (COM & LPT)" section
* Linux: `/dev/ttyACMx`
* macOS: `/dev/tty.usbmodemXXXXXX`
* `<mcu>` should be the lowercase name of the target AVR microcontroller, for example `atmega32u4`.
* `<filename>` is the absolute or relative path to the bootloader to be flashed, for example `Caterina-Micro.hex`.
You can also run `man avrdude` for more information.
If all goes well, you should get output similar to the following:
```
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e9587 (probably m32u4)
avrdude: NOTE: "flash" memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file "Caterina-Micro.hex"
avrdude: writing flash (32730 bytes):
Writing | ################################################## | 100% 11.58s
avrdude: 32730 bytes of flash written
avrdude: verifying flash memory against Caterina-Micro.hex:
avrdude: load data flash data from input file Caterina-Micro.hex:
avrdude: input file Caterina-Micro.hex contains 32730 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 10.33s
avrdude: verifying ...
avrdude: 32730 bytes of flash verified
avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)
avrdude done. Thank you.
```
### Setting the Fuses
This is a slightly more advanced topic, but may be necessary if you are switching from one bootloader to another (for example, Caterina to Atmel/QMK DFU on a Pro Micro). Fuses control some of the low-level functionality of the AVR microcontroller, such as clock speed, whether JTAG is enabled, and the size of the section of flash memory reserved for the bootloader, among other things. You can find a fuse calculator for many AVR parts [here](https://www.engbedded.com/conffuse/).
!> **WARNING:** Setting incorrect fuse values, in particular the clock-related bits, may render the MCU practically unrecoverable without high voltage programming (not covered here)! Make sure to double check the commands you enter before you execute them.
To set the fuses, add the following to the `avrdude` command:
```
-U lfuse:w:0xXX:m -U hfuse:w:0xXX:m -U efuse:w:0xXX:m
```
where the `lfuse`, `hfuse` and `efuse` arguments represent the low, high and extended fuse bytes as listed in the [Hardware](#hardware) section.
?> You may get a warning from `avrdude` that the extended fuse byte does not match what you provided when reading it back. If the second hex digit matches, this can usually be safely ignored, because the top four bits of this fuse do not actually exist on many AVR parts, and may read back as anything.
## Creating a "Production" Firmware
For mass production purposes, it is possible to join the bootloader and QMK firmware together into a single file, due to the way the [Intel Hex format](https://en.wikipedia.org/wiki/Intel_HEX) works:
1. Open the QMK firmware and bootloader `.hex` files in a text editor.
2. Remove the last line of the QMK firmware (which should be `:00000001FF` - this is just an "end of file" marker).
3. Paste the contents of the bootloader `.hex` file onto a new line at the end of the QMK firmware file, with no empty lines between.
4. Save it as a new file, for example `<keyboard>_<keymap>_production.hex`.
You can then ISP flash this combined firmware instead, which allows you to skip the extra step of flashing the QMK firmware over USB.

1
docs/ja/compatible_microcontrollers.md
View file

@ -32,6 +32,7 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま
* [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
* [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
* [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html)
* [STM32F405](https://www.st.com/en/microcontrollers-microprocessors/stm32f405-415.html)
* [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html)
* [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html)
* [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html)

4
docs/ja/config_options.md
View file

@ -141,7 +141,7 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
* `#define STRICT_LAYER_RELEASE`
* キーリリースがどのレイヤーから来たのかを覚えるのではなく、現在のレイヤースタックを使って強制的に評価されるようにします (高度なケースに使われます)
## 設定可能な挙動
## 設定可能な挙動 :id=behaviors-that-can-be-configured
* `#define TAPPING_TERM 200`
* タップがホールドになるまでの時間。500以上に設定された場合、タップ期間中にタップされたキーもホールドになります。(訳注: PERMISSIVE_HOLDも参照)
@ -358,7 +358,7 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
これらを使って特定の機能のビルドを有効または無効にします。有効にすればするほどファームウェアが大きくなり、MCU には大きすぎるファームウェアを構築するリスクがあります。
* `BOOTMAGIC_ENABLE`
* 仮想 DIP スイッチ設定
* ブートマジックライトを有効にします
* `MOUSEKEY_ENABLE`
* マウスキー
* `EXTRAKEY_ENABLE`

8
docs/ja/contributing.md
View file

@ -1,8 +1,8 @@
# 貢献方法
<!---
original document: 0.13.15:docs/contributing.md
git diff 0.13.15 HEAD -- docs/contributing.md | cat
original document: 0.14.22:docs/contributing.md
git diff 0.14.22 HEAD -- docs/contributing.md | cat
-->
👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます！🎉👍
@ -79,7 +79,7 @@ QMK には幾つかの異なるタイプの変更があり、それぞれ異な
```
kerpleplork の fronzlebop を調整します
kerpleplork はエラーコード 23 で連続的に失敗していました。根本的な原因は fronzlebop 設定で、これにより kerpleplork はN回の繰り返しごとにアクティブになります。
kerpleplork はエラーコード 23 で連続的に失敗していました。根本的な原因は fronzlebop 設定で、これにより kerpleplork は N 回の繰り返しごとにアクティブになります。
私が使用できるデバイスの限られた実験では、kerpleplork の混乱を避けるために 7 は十分高い値であることを示していますが、念のため ARM デバイスを持つ人たちからフィードバックを得たいです。
```
@ -122,7 +122,7 @@ enum my_keycodes {
ほとんどの初めての QMK 貢献者は、個人のキーマップから始めます。キーマップの標準はかなりカジュアルなものにしようとしています(キーマップは結局のところ作成者の性格を反映しています)が、他の人があなたのキーマップを簡単に見つけて学ぶことができるように、これらのガイドラインに従うようにお願いします。
* [テンプレート](documentation_templates.md) を使って `readme.md` を書きます。
* [テンプレート](ja/documentation_templates.md) を使って `readme.md` を書きます。
* 全てのキーマップの PR は squash されるため、コミットがどのように squash されるかを気にする場合は、自分で行う必要があります。
* キーマップの PR に機能をまとめないでください。最初に機能をサブミットし、次にキーマップのための2つ目の PR をサブミットします。
* `Makefile` をキーマップフォルダに含めないでください(もう使われていません)。

4
docs/ja/custom_quantum_functions.md
View file

@ -211,11 +211,11 @@ void keyboard_post_init_user(void) {
```c
void suspend_power_down_user(void) {
rgb_matrix_set_suspend_state(true);
// code will run multiple times while keyboard is suspended
}
void suspend_wakeup_init_user(void) {
rgb_matrix_set_suspend_state(false);
// code will run on keyboard wakeup
}
```

2
docs/ja/faq_keymap.md
View file

@ -10,7 +10,7 @@
## どのキーコードを使えますか？
あなたが利用可能なキーコードのインデックスについては、[キーコード](ja/keycodes.md)を見てください。より広範なドキュメントがある場合は、そこからリンクしてあります。
キーコードは実際には [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h) で定義されています。
キーコードは実際には [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h) で定義されています。
## デフォルトのキーコードとは何か？

4
docs/ja/faq_misc.md
View file

@ -39,10 +39,6 @@ Size after:
**NKRO** がまだ動作しない場合は、`Magic` **N** コマンド(デフォルトでは `LShift+RShift+N`)を試してみてください。**NKRO** モードと **6KRO** モード間を一時的に切り替えるためにこのコマンドを使うことができます。**NKRO** が機能しない状況、特に BIOS の場合は **6KRO** モードに切り替える必要があります。
ファームウェアを `BOOTMAGIC_ENABLE` でビルドした場合、`ブートマジック` **N** コマンドで切り替える必要があります(デフォルトでは `Space+N`)。この設定は EEPROM に格納され、電源を入れ直しても保持されます。
https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
## トラックポイントははリセット回路が必要です (PS/2 マウスサポート)
リセット回路が無いとハードウェアの不適切な初期化のために一貫性の無い結果になります。TPM754 の回路図を見てください:

43
docs/ja/feature_advanced_keycodes.md
View file

@ -1,30 +1,33 @@
# 修飾キー :id=modifier-keys
<!---
original document: 0.12.29:docs/feature_advanced_keycodes.md
git diff 0.12.29 HEAD -- docs/feature_advanced_keycodes.md | cat
original document: 0.14.6:docs/feature_advanced_keycodes.md
git diff 0.14.6 HEAD -- docs/feature_advanced_keycodes.md | cat
-->
以下のようにキーコードとモディファイアを組み合わせることができます。押すと、モディファイアのキーダウンイベントが送信され、次に `kc` のキーダウンイベントが送信されます。放すと、`kc` のキーアップイベントが送信され、次にモディファイアのキーアップイベントが送信されます。
| キー | エイリアス | 説明 |
| ---------- | ------------------------------- | ------------------------------------------------------------------- |
| `LCTL(kc)` | `C(kc)` | 左 Control を押しながら `kc` を押します。 |
| `LSFT(kc)` | `S(kc)` | 左 Shift を押しながら `kc` を押します。 |
| `LALT(kc)` | `A(kc)`, `LOPT(kc)` | 左 Alt を押しながら `kc`を押します。 |
| `LGUI(kc)` | `G(kc)`, `LCMD(kc)`, `LWIN(kc)` | 左 GUI を押しながら `kc` を押します。 |
| `RCTL(kc)` | | 右 Control を押しながら `kc` を押します。 |
| `RSFT(kc)` | | 右 Shift を押しながら `kc` を押します。 |
| `RALT(kc)` | `ROPT(kc)`, `ALGR(kc)` | 右 Alt を押しながら `kc` を押します。 |
| `RGUI(kc)` | `RCMD(kc)`, `LWIN(kc)` | 右 GUI を押しながら `kc` を押します。 |
| `SGUI(kc)` | `SCMD(kc)`, `SWIN(kc)` | 左 Shift と左 GUI を押しながら `kc` を押します。 |
| `LCA(kc)` | | 左 Control と左 Alt を押しながら `kc` を押します。 |
| `LSA(kc)` | | 左 Shift と左 Alt を押しながら `kc` を押します。 |
| `RSA(kc)` | `SAGR(kc)` | 右 Shift と右 Alt (AltGr) を押しながら `kc` を押します。 |
| `RCS(kc)` | | 右 Control と右 Shift を押しながら `kc` を押します。 |
| `LCAG(kc)` | | 左 Control、左 Alt、左 GUI を押しながら `kc` を押します。 |
| `MEH(kc)` | | 左 Control、左 Shift、左 Alt を押しながら `kc` を押します。 |
| `HYPR(kc)` | | 左 Control、左 Shift、左 Alt、左 GUI を押しながら `kc` を押します。 |
| キー | エイリアス | 説明 |
| ---------- | ---------------------------------- | ------------------------------------------------------------------- |
| `LCTL(kc)` | `C(kc)` | 左 Control を押しながら `kc` を押します。 |
| `LSFT(kc)` | `S(kc)` | 左 Shift を押しながら `kc` を押します。 |
| `LALT(kc)` | `A(kc)`, `LOPT(kc)` | 左 Alt を押しながら `kc`を押します。 |
| `LGUI(kc)` | `G(kc)`, `LCMD(kc)`, `LWIN(kc)` | 左 GUI を押しながら `kc` を押します。 |
| `RCTL(kc)` | | 右 Control を押しながら `kc` を押します。 |
| `RSFT(kc)` | | 右 Shift を押しながら `kc` を押します。 |
| `RALT(kc)` | `ROPT(kc)`, `ALGR(kc)` | 右 Alt を押しながら `kc` を押します。 |
| `RGUI(kc)` | `RCMD(kc)`, `LWIN(kc)` | 右 GUI を押しながら `kc` を押します。 |
| `LSG(kc)` | `SGUI(kc)`, `SCMD(kc)`, `SWIN(kc)` | 左 Shift と左 GUI を押しながら `kc` を押します。 |
| `LAG(kc)` | | 左 Alt と左 GUI を押しながら `kc` を押します。 |
| `RSG(kc)` | | 右 Shift と右 GUI を押しながら `kc` を押します。 |
| `RAG(kc)` | | 右 Alt と右 GUI を押しながら `kc` を押します。 |
| `LCA(kc)` | | 左 Control と左 Alt を押しながら `kc` を押します。 |
| `LSA(kc)` | | 左 Shift と左 Alt を押しながら `kc` を押します。 |
| `RSA(kc)` | `SAGR(kc)` | 右 Shift と右 Alt (AltGr) を押しながら `kc` を押します。 |
| `RCS(kc)` | | 右 Control と右 Shift を押しながら `kc` を押します。 |
| `LCAG(kc)` | | 左 Control、左 Alt、左 GUI を押しながら `kc` を押します。 |
| `MEH(kc)` | | 左 Control、左 Shift、左 Alt を押しながら `kc` を押します。 |
| `HYPR(kc)` | | 左 Control、左 Shift、左 Alt、左 GUI を押しながら `kc` を押します。 |
また、それらを繋げることができます。例えば、`LCTL(LALT(KC_DEL))` または `C(A(KC_DEL))` は1回のキー押下で Control+Alt+Delete を送信するキーを作成します。

47
docs/ja/feature_backlight.md
View file

@ -1,8 +1,8 @@
# バックライト :id=backlighting
<!---
original document: 0.10.33:docs/feature_backlight.md
git diff 0.10.33 HEAD -- docs/feature_backlight.md | cat
original document: 0.14.14:docs/feature_backlight.md
git diff 0.14.14 HEAD -- docs/feature_backlight.md | cat
-->
多くのキーボードは、キースイッチを貫通して配置されたり、キースイッチの下に配置された個々の LED によって、バックライトキーをサポートします。この機能は通常スイッチごとに単一の色しか使用できないため、[RGB アンダーグロー](ja/feature_rgblight.md)および [RGB マトリックス](ja/feature_rgb_matrix.md)機能のどちらとも異なりますが、キーボードに複数の異なる単一色の LED を取り付けることは当然可能です。
@ -67,14 +67,17 @@ BACKLIGHT_DRIVER = software
バックライトを設定するには、`config.h` の中で以下の `#define` をします:
| 定義 | デフォルト | 説明 |
| --------------------- | ---------- | ------------------------------------------------------------------------------------------- |
| `BACKLIGHT_PIN` | *定義なし* | LED を制御するピン |
| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) |
| `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) |
| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする |
| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） |
| `BACKLIGHT_ON_STATE` | `1` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` |
| 定義 | デフォルト | 説明 |
| ----------------------------- | ------------------ | --------------------------------------------------------------------------------------------- |
| `BACKLIGHT_PIN` | *定義なし* | LED を制御するピン |
| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) |
| `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) |
| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする |
| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） |
| `BACKLIGHT_ON_STATE` | `1` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` |
| `BACKLIGHT_LIMIT_VAL` | `255` | バックライトの最大デューティサイクル -- `255` で最大輝度になり、それ未満では最大値が減少する |
| `BACKLIGHT_DEFAULT_LEVEL` | `BACKLIGHT_LEVELS` | EEPROM をクリアする時に使うデフォルトのバックライトレベル |
| `BACKLIGHT_DEFAULT_BREATHING` | *定義なし* | EEPROM をクリアする時に、バックライトのブリージングを有効にするかどうか |
独自のキーボードを設計しているわけではない限り、通常は `BACKLIGHT_PIN` または `BACKLIGHT_ON_STATE` を変更する必要はありません。
@ -97,18 +100,18 @@ BACKLIGHT_DRIVER = pwm
AVR ボードでは、QMK はどのドライバを使うかを以下の表に従って自動的に決定します:
| バックライトピン | AT90USB64/128 | ATmega16/32U4 | ATmega16/32U2 | ATmega32A | ATmega328/P |
| ---------------- | ------------- | ------------- | ------------- | --------- | ----------- |
| `B1` | | | | | Timer 1 |
| `B2` | | | | | Timer 1 |
| `B5` | Timer 1 | Timer 1 | | | |
| `B6` | Timer 1 | Timer 1 | | | |
| `B7` | Timer 1 | Timer 1 | Timer 1 | | |
| `C4` | Timer 3 | | | | |
| `C5` | Timer 3 | | Timer 1 | | |
| `C6` | Timer 3 | Timer 3 | Timer 1 | | |
| `D4` | | | | Timer 1 | |
| `D5` | | | | Timer 1 | |
| バックライトピン | AT90USB64/128 | AT90USB162 | ATmega16/32U4 | ATmega16/32U2 | ATmega32A | ATmega328/P |
| ---------------- | ------------- | ---------- | ------------- | ------------- | --------- | ----------- |
| `B1` | | | | | | Timer 1 |
| `B2` | | | | | | Timer 1 |
| `B5` | Timer 1 | | Timer 1 | | | |
| `B6` | Timer 1 | | Timer 1 | | | |
| `B7` | Timer 1 | Timer 1 | Timer 1 | Timer 1 | | |
| `C4` | Timer 3 | | | | | |
| `C5` | Timer 3 | Timer 1 | | Timer 1 | | |
| `C6` | Timer 3 | Timer 1 | Timer 3 | Timer 1 | | |
| `D4` | | | | | Timer 1 | |
| `D5` | | | | | Timer 1 | |
他の全てのピンはタイマー支援ソフトウェア PWM を使います。

2
docs/ja/feature_encoders.md
View file

@ -76,7 +76,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) {
tap_code(KC_UP);
}
}
return true;
return false;
}
```

7
docs/ja/feature_haptic_feedback.md
View file

@ -9,9 +9,12 @@
現在のところ、`rules.mk` で触覚フィードバック用に以下のオプションを利用可能です:
`HAPTIC_ENABLE += DRV2605L`
```
HAPTIC_ENABLE = yes
`HAPTIC_ENABLE += SOLENOID`
HAPTIC_DRIVER += DRV2605L
HAPTIC_DRIVER += SOLENOID
```
## サポートされる既知のハードウェア

2
docs/ja/feature_layers.md
View file

@ -50,7 +50,7 @@ QMK を使い始めたばかりの場合は、全てを単純にしたいでし
レイヤーは番号順に上に積み重なっています。キーの押下の動作を決定する時に、QMK は上から順にレイヤーを走査し、`KC_TRNS` に設定されていない最初のアクティブなレイヤーに到達すると停止します。結果として、現在のレイヤーよりも数値的に低いレイヤーをアクティブにし、現在のレイヤー(あるいはアクティブでターゲットレイヤーよりも高い別のレイヤー)に `KC_TRNS` 以外のものがある場合、それが送信されるキーであり、アクティブ化したばかりのレイヤー上のキーではありません。これが、ほとんどの人の "なぜレイヤーが切り替わらないのか" 問題の原因です。
場合によっては、マクロ内あるいはタップダンスルーチンの一部としてレイヤーを切り替えほうが良いかもしれません。`layer_on` はレイヤーをアクティブにし、`layer_off` はそれを非アクティブにします。もっと多くのレイヤーに関する関数は、[action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h) で見つけることができます。
場合によっては、マクロ内あるいはタップダンスルーチンの一部としてレイヤーを切り替えほうが良いかもしれません。`layer_on` はレイヤーをアクティブにし、`layer_off` はそれを非アクティブにします。もっと多くのレイヤーに関する関数は、[action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/action_layer.h) で見つけることができます。
## 関数 :id=functions

17
docs/ja/feature_leader_key.md
View file

@ -1,8 +1,8 @@
# リーダーキー: 新しい種類のモディファイア
<!---
original document: 0.10.33:docs/feature_leader_key.md
git diff 0.10.33 HEAD -- docs/feature_leader_key.md | cat
original document: 0.13.24:docs/feature_leader_key.md
git diff 0.13.24 HEAD -- docs/feature_leader_key.md | cat
-->
もしあなたが Vim を使ったことがある場合、リーダーキーは何であるかを知っています。そうでなければ、素晴らしい概念を発見しようとしています。:) 例えば、Alt+Shift+W を押す(3つのキーを同時に押す)代わりに、キーの_シーケンス_を押すことができたらどうでしょう？つまり、特別なモディファイア (リーダーキー)を押して、続けて W と C を押すと (単純にキーを高速に繋げます)、何かが起こります。
@ -77,6 +77,19 @@ SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
}
```
## リーダーキーの無限タイムアウト
リーダーキーが、シーケンスの残りのキーのような快適な場所にない場合があります。リーダーキーが右上の外側のキーの1つである場合、リーダーキーに届くように手の位置を変えなければならないことがあります。
これにより、シーケンスの大部分をすばやく入力できたとしても、シーケンス全体を時間通りに入力するのが難しい場合があります。例えば、シーケンスが `Leader + asd` の場合、手をホーム行に置けば `asd` を素早く打つのは非常に簡単です。しかし、リーダーキーに届くようにホーム行から手を移動し、戻った後、時間内にシーケンスを開始することはできません。
この状況が手に与えるストレスを取り除くために、リーダーキーだけに無限のタイムアウトを有効にすることができます。つまり、リーダーキーを押した後、シーケンスの残りを開始するまでの時間が無限になり、シーケンスの残りを快適に入力するための最適な位置に手を置くことができます。
この無限のタイムアウトはリーダーキーにのみ影響するため、前述の `Leader + asd` の例では、`Leader` と `a` の間に無限の時間があります。ただし、シーケンスを開始すると、(グローバルまたはキーごとに)設定したタイムアウトは正常に機能します。
このようにして、非常に短い `LEADER_TIMEOUT` を設定できますが、それでも手を置く時間は十分にあります。
これを有効にするには、以下を `config.h` に配置します:
```c
#define LEADER_NO_TIMEOUT
```
## 厳密なキー処理
デフォルトでは、リーダーキー機能は、リーダーシーケンスの確認時に [`モッドタップ`](ja/mod_tap.md) および [`レイヤータップ`](ja/feature_layers.md#switching-and-toggling-layers) 機能からのキーコードをフィルターします。つまり、`LT(3, KC_A)` を使っている場合、`LT(3, KC_A)` ではなくシーケンスの `KC_A` として取り出され、新しいユーザにとってより期待される動作を提供します。

2
docs/ja/feature_led_indicators.md
View file

@ -25,7 +25,7 @@ LED の状態を `uint8_t` として提供する2つの非推奨の関数があ
* `uint8_t led_set_kb(uint8_t usb_led)` と `_user(uint8_t usb_led)`
* `uint8_t host_keyboard_leds()`
## 設定オプション
## 設定オプション :id=configuration-options
インジケータを設定するには、`config.h` で以下の `#define` をします:

2
docs/ja/feature_led_matrix.md
View file

@ -52,7 +52,7 @@ I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED
`<keyboard>.c` に全ての LED を列挙する配列を定義します:
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = {
/* これらの位置については IS31 マニュアルを参照してください
* driver
* | LED address

31
docs/ja/feature_ps2_mouse.md
View file

@ -43,14 +43,8 @@ PS2_USE_BUSYWAIT = yes
```c
#ifdef PS2_USE_BUSYWAIT
# define PS2_CLOCK_PORT PORTD
# define PS2_CLOCK_PIN PIND
# define PS2_CLOCK_DDR DDRD
# define PS2_CLOCK_BIT 1
# define PS2_DATA_PORT PORTD
# define PS2_DATA_PIN PIND
# define PS2_DATA_DDR DDRD
# define PS2_DATA_BIT 2
# define PS2_CLOCK_PIN D1
# define PS2_DATA_PIN D2
#endif
```
@ -69,14 +63,8 @@ PS2_USE_INT = yes
```c
#ifdef PS2_USE_INT
#define PS2_CLOCK_PORT PORTD
#define PS2_CLOCK_PIN PIND
#define PS2_CLOCK_DDR DDRD
#define PS2_CLOCK_BIT 2
#define PS2_DATA_PORT PORTD
#define PS2_DATA_PIN PIND
#define PS2_DATA_DDR DDRD
#define PS2_DATA_BIT 5
#define PS2_CLOCK_PIN D2
#define PS2_DATA_PIN D5
#define PS2_INT_INIT() do { \
EICRA |= ((1<<ISC21) | \
@ -107,14 +95,9 @@ PS2_USE_USART = yes
```c
#ifdef PS2_USE_USART
#define PS2_CLOCK_PORT PORTD
#define PS2_CLOCK_PIN PIND
#define PS2_CLOCK_DDR DDRD
#define PS2_CLOCK_BIT 5
#define PS2_DATA_PORT PORTD
#define PS2_DATA_PIN PIND
#define PS2_DATA_DDR DDRD
#define PS2_DATA_BIT 2
#ifdef PS2_USE_USART
#define PS2_CLOCK_PIN D5
#define PS2_DATA_PIN D2
/* 同期、奇数パリティ、1-bit ストップ、8-bit データ、立ち下がりエッジでサンプル */
/* CLOCK の DDR を入力としてスレーブに設定 */

4
docs/ja/feature_stenography.md
View file

@ -45,8 +45,8 @@ MOUSEKEY_ENABLE = no
キーマップで Plover 用の新しいレイヤーを作成します。`keymap_steno.h` をインクルードする必要があります。例については `planck/keymaps/steno/keymap.c` を見てください。レイヤーに切り替えるためのキーとレイヤーから抜けるためのキーを作成することを忘れないでください。その場でモードを切り替えたい場合は、キーコード `QK_STENO_BOLT` および `QK_STENO_GEMINI` を使うことができます。プロトコルのうちの1つのみを使う場合は、初期化関数の中でそれをセットアップすることができます:
```c
void matrix_init_user() {
steno_set_mode(STENO_MODE_GEMINI); // あるいは STENO_MODE_BOLT
void eeconfig_init_user() {
steno_set_mode(STENO_MODE_GEMINI); // あるいは STENO_MODE_BOLT
}
```

1
docs/ja/feature_velocikey.md
View file

@ -11,7 +11,6 @@ Velocikey は入力の速度を使って(レインボー渦巻効果のような
Velocikey を使うためには、2つのステップがあります。最初に、キーボードをコンパイルする時に、`rules.mk` に `VELOCIKEY_ENABLE=yes` を設定する必要があります。例えば:
```
BOOTMAGIC_ENABLE = no
MOUSEKEY_ENABLE = no
STENO_ENABLE = no
EXTRAKEY_ENABLE = yes

1
docs/ja/getting_started_github.md
View file

@ -37,7 +37,6 @@ Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca
Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
```
ローカルマシンに QMK のフォークができるので、キーマップの追加、コンパイル、キーボードへの書き込みができます。変更に満足したら、以下のようにそれらをフォークへ追加、コミットおよびプッシュすることができます:

4
docs/ja/hardware_drivers.md
View file

@ -24,10 +24,6 @@ ProMicro のピンを AVR の名前ではなく、Arduino の名前で指定で
SSD1306 ベースの OLED ディスプレイのサポート。詳しくは[OLED ドライバ](ja/feature_oled_driver.md)を参照して下さい。
## uGFX
QMK 内で uGFX を使用して、キャラクタ LCD やグラフィック LCD、LED アレイ、OLED ディスプレイ、TFT 液晶や他のディスプレイを制御できます。この部分はより詳しく文書化される必要があります。もしこれを使用したい場合にコードを読んでも分からない場合、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new)を通して助けることができるかもしれません。
## WS2812
WS2811/WS2812{a,b,c} LED のサポート。 詳しくは [RGB ライト](ja/feature_rgblight.md)を参照して下さい。

2
docs/ja/hardware_keyboard_guidelines.md
View file

@ -234,8 +234,6 @@ QMK が提供する機能の量を考えれば、新しいユーザーが混乱
QMK のコア部分は [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html) でライセンスされます。AVR マイコン用のバイナリを提供する場合は、[GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) か、[GPLv3](https://www.gnu.org/licenses/gpl.html) のどちらかから選択出来ます。ARM マイコン用のバイナリを提供する場合は、 [ChibiOS](https://www.chibios.org) の GPLv3 ライセンスに準拠するため、[GPL Version 3](https://www.gnu.org/licenses/gpl.html) を選択しなければいけません。
[uGFX](https://ugfx.io) を使用している場合は、[uGFX License](https://ugfx.io/license.html) に準拠する必要があります。uGFX を利用したデバイスを販売するには個別に商用ライセンスを取得しなければいけません。
## 技術的な詳細
キーボードを QMK で動作させるための詳細は[ハードウェア](ja/hardware.md)を参照して下さい！

22
docs/ja/isp_flashing_guide.md
View file

@ -2,8 +2,8 @@
<!---
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
original document: 0.9.46:docs/isp_flashing_guide.md
git diff 0.9.46 HEAD -- docs/isp_flashing_guide.md | cat
original document: 0.13.29:docs/isp_flashing_guide.md
git diff 0.13.29 HEAD -- docs/isp_flashing_guide.md | cat
-->
ISP 書き込み(ICSP 書き込みと呼ぶ場合もあります)とは、マイクロコントローラーを直接プログラミングするプロセスです。
@ -52,6 +52,7 @@ QMK の ISP 書き込みの主な用途は、AVRベースのコントローラ
* [SparkFun PocketAVR](https://www.sparkfun.com/products/9825) - (USB Tiny)
* [USBtinyISP AVR Programmer Kit](https://www.adafruit.com/product/46) - (USB Tiny)
* [USBasp](https://www.fischl.de/usbasp/) - (usbasp)
* [Teensy 2.0](https://www.pjrc.com/store/teensy.html) - (avrisp)
* [Pro Micro](https://www.sparkfun.com/products/12640) - (avrisp)
* [Bus Pirate](https://www.adafruit.com/product/237) - (buspirate)
@ -77,8 +78,8 @@ Teensy と Pro Micro のコントローラを ISP プログラマとして使用
QMK ツールボックスは、このほとんど（すべて）に使用することができます。
ただし、Teensy 2.0 ボードを使っている場合は、[Teensy Loader](https:/www.pjrc.comteensyloader.html) を使えば、Teensy 2.0 ボードに書き込むことができます。
あるいは、`avrdude` (`qmk_install.sh` の一部としてインストールされています) や、[AVRDUDESS](https:/blog.zakkemble.netavrdudess-a-gui-for-avrdude)(Windows 用) を使って、Pro Micro に書き込んだり、ISP を書き込んだりすることができます。
ただし、Teensy 2.0 ボードを使っている場合は、[Teensy Loader](https://www.pjrc.com/teensy/loader.html) を使えば、Teensy 2.0 ボードに書き込むことができます。
あるいは、`avrdude` (`qmk_install.sh` の一部としてインストールされています) や、[AVRDUDESS](https://blog.zakkemble.net/avrdudess-a-gui-for-avrdude/) (Windows 用) を使って、Pro Micro に書き込んだり、ISP を書き込んだりすることができます。
## 配線
@ -93,6 +94,15 @@ QMK ツールボックスは、このほとんど（すべて）に使用する
PocketAVR VCC <-> Keyboard VCC
PocketAVR GND <-> Keyboard GND
### USBasp
USBasp RST <-> Keyboard RESET
USBasp SCLK <-> Keyboard B1 (SCLK)
USBasp MOSI <-> Keyboard B2 (MOSI)
USBasp MISO <-> Keyboard B3 (MISO)
USBasp VCC <-> Keyboard VCC
USBasp GND <-> Keyboard GND
### Teensy 2.0
Teensy B0 <-> Keyboard RESET
@ -180,7 +190,7 @@ QMK DFU ブートローダは `atmega32u4` コントローラ (AVR ベースの
### QMK Toolbox
1. 'AVRISP device connected' または `USB Tiny device connected` が黄色で表示されます。
1. `AVRISP device connected` または `USB Tiny device connected` が黄色で表示されます。
2. `Open` ダイアログで正しいブートローダー/プロダクションの .hex ファイルを選択します（パスにスペースを含めることはできません）
3. 書きこもうとしているキーボード（ISP プログラマではなく）のための正しい `Microcontroller` オプションが選択されていることを確認してください。
4. `Flash` を押します
@ -277,7 +287,7 @@ High ヒューズは 0xD9 か 0x99 のどちらかになります。
avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i -U lfuse:w:0xFF:m -U hfuse:w:0xD8:m -U efuse:w:0xCB:m
別のコントローラーを使用している場合や、別の設定を希望する場合は、この[AVR ヒューズ計算機](https://www.engbedded.com/fusecalc)を使用して、より適切な値を見つけることができます。
別のコントローラーを使用している場合や、別の設定を希望する場合は、この[AVR ヒューズ計算機](https://www.engbedded.com/fusecalc/)を使用して、より適切な値を見つけることができます。
## ヘルプ

34
docs/ja/ja_doc_status.sh Normal file
View file

@ -0,0 +1,34 @@
#! /bin/sh
#
# Script to display the Japanese translation status of documents
#
if [ ! -d docs/ja ]; then
echo "'docs/ja' not found."
echo "do:"
echo " cd \$(QMK_TOP)"
echo " ./docs/ja/ja_doc_status.sh"
exit 1
fi
en_docs=`cd docs;ls -1 [a-z]*.md`
ja_docs=`cd docs/ja;ls -1 [a-z]*.md`
en_count=`echo $en_docs | wc -w`
ja_count=`echo $ja_docs | wc -w`
echo "English documents $en_count files."
echo "Japanese documents $ja_count files."
echo "Files that have not been translated yet:"
for docfile in $en_docs
do
if [ ! -f docs/ja/$docfile ]; then
wc docs/$docfile
fi
done | sort
echo "Files that have not been updated yet:"
grep --no-filename "^[ ]*git diff" docs/ja/*.md | while read cmd
do
cline=`echo $cmd | sh | wc -l`
if [ $cline -gt 0 ]; then
echo "$cline $cmd"
fi
done | sort

41
docs/ja/keycodes_us_ansi_shifted.md Normal file
View file

@ -0,0 +1,41 @@
# US ANSI シフト記号
<!---
original document: 0.13.23:docs/keycodes_us_ansi_shifted.md
git diff 0.13.23 HEAD -- docs/keycodes_us_ansi_shifted.md | cat
-->
これらのキーコードは、標準の US ANSI 配列のキーボードで「シフトされる」文字に対応します。これらのキーコードは自身のキーコードを持たず、`LSFT(kc)` の単なるショートカットであり、記号自体ではなく Shift キー抜きのキーコードと左 Shift キーを送信します。
## 注意書き
残念ながら、これらのキーコードは、モッドタップやレイヤータップの中で使えません。キーコードで指定されたモディファイアは無視されるからです。
さらに、Windows でリモートデスクトップ接続を使う場合に、問題が発生する場合があります。なぜならば、これらのコードは Shift キーを非常に速く送信するため、リモートデスクトップがコードを見落とすかもしれないからです。
この問題を解決するには、リモートデスクトップ接続を開いて「オプションの表示」をクリックし、「ローカル リソース」タブを開きます。キーボードセクションでドロップダウンを「このコンピュータ」に変更します。これで問題が解決され、文字が正しく機能するようになります。
## キーコード
|キー |エイリアス |説明 |
|------------------------|-------------------|-----------|
|`KC_TILDE` |`KC_TILD` |`~` |
|`KC_EXCLAIM` |`KC_EXLM` |`!` |
|`KC_AT` | |`@` |
|`KC_HASH` | |`#` |
|`KC_DOLLAR` |`KC_DLR` |`$` |
|`KC_PERCENT` |`KC_PERC` |`%` |
|`KC_CIRCUMFLEX` |`KC_CIRC` |`^` |
|`KC_AMPERSAND` |`KC_AMPR` |`&` |
|`KC_ASTERISK` |`KC_ASTR` |`*` |
|`KC_LEFT_PAREN` |`KC_LPRN` |`(` |
|`KC_RIGHT_PAREN` |`KC_RPRN` |`)` |
|`KC_UNDERSCORE` |`KC_UNDS` |`_` |
|`KC_PLUS` | |`+` |
|`KC_LEFT_CURLY_BRACE` |`KC_LCBR` |`{` |
|`KC_RIGHT_CURLY_BRACE` |`KC_RCBR` |`}` |
|`KC_PIPE` | |`\|` |
|`KC_COLON` |`KC_COLN` |`:` |
|`KC_DOUBLE_QUOTE` |`KC_DQUO`, `KC_DQT`|`"` |
|`KC_LEFT_ANGLE_BRACKET` |`KC_LABK`, `KC_LT` |`<` |
|`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>` |
|`KC_QUESTION` |`KC_QUES` |`?` |

17
docs/ja/mod_tap.md
View file

@ -1,8 +1,8 @@
# モッドタップ
<!---
original document: 0.10.36:docs/mod_tap.md
git diff 0.10.36 HEAD -- docs/mod_tap.md | cat
original document: 0.13.34:docs/mod_tap.md
git diff 0.13.34 HEAD -- docs/mod_tap.md | cat
-->
モッドタップキー `MT(mod, kc)` は、押したままの時にモディファイアのように機能し、タップされた時に通常のキーのように振舞います。別の言い方をすると、タップした時に Escape を送信しますが、押したままの時に Control あるいは Shift キーとして機能するキーを持つことができます。
@ -42,7 +42,10 @@ MT(MOD_LCTL | MOD_LSFT, KC_ESC)
| `RSFT_T(kc)` | | 押したままの場合は右 Shift、タップした場合は `kc` |
| `RALT_T(kc)` | `ROPT_T(kc)`, `ALGR_T(kc)` | 押したままの場合は右 Alt、タップした場合は `kc` |
| `RGUI_T(kc)` | `RCMD_T(kc)`, `RWIN_T(kc)` | 押したままの場合は右 GUI、タップした場合は `kc` |
| `SGUI_T(kc)` | `SCMD_T(kc)`, `SWIN_T(kc)` | 押したままの場合は左 Shift と左 GUI、タップした場合は `kc` |
| `LSG_T(kc)` | `SGUI_T(kc)`, `SCMD_T(kc)`, `SWIN_T(kc)` | 押したままの場合は左 Shift と左 GUI、タップした場合は `kc` |
| `LAG_T(kc)` | | 押したままの場合は左 Alt と左 GUI、タップした場合は `kc` |
| `RSG_T(kc)` | | 押したままの場合は右 Shift と右 GUI、タップした場合は `kc` |
| `RAG_T(kc)` | | 押したままの場合は右 Alt と右 GUI、タップした場合は `kc` |
| `LCA_T(kc)` | | 押したままの場合は左 Control と左 Alt、タップした場合は `kc` |
| `LSA_T(kc)` | | 押したままの場合は左 Shift と Alt、タップした場合は `kc` |
| `RSA_T(kc)` | `SAGR_T(kc)` | 押したままの場合は右 Shift と Alt (AltGr)、タップした場合は `kc` |
@ -55,11 +58,13 @@ MT(MOD_LCTL | MOD_LSFT, KC_ESC)
## 注意事項
残念ながら、キーコードで指定されたモディファイアは無視されるため、これらのキーコードはモッドタップまたはレイヤータップで使うことができません。
現在のところ、`MT()` の引数 `kc` は[基本的なキーコードセット](ja/keycodes_basic.md)に制限されています。つまり、`LCTL()`、`KC_TILD`、あるいは `0xFF` より大きなキーコードを使うことができません。これは、QMK が16ビットのキーコードを使うためです。3ビットは機能の識別のために使われ、1ビットは右または左の mod を選択するために使われ、4ビットはどの mod かを区別するために使われ、キーコードには8ビットしか残されていません。さらに、モッドタップで少なくとも1つの右手用のモディファイアが指定された場合、指定された全てのモディファイアが右手用になるため、2つをうまく組み合わせて一致させることはできません。例えば、左 Control と右 Shift は、右 Control と右 Shift になります。
さらに、Windows でリモートデスクトップ接続を使う場合に、問題が発生する場合があります。これらのコードはシフトを非常に高速に送信するため、リモートデスクトップはコードを見逃すかもしれません。
これを拡張してもせいぜい複雑になるだけでしょう。32ビットキーコードに移行すると、これの多くが解決されますが、キーマップマトリックスが使用する領域が2倍になります。また、問題が起きる可能性もあります。タップしたキーコードにモディファイアを適用する必要がある場合は、[タップダンス](ja/feature_tap_dance.md#example-5)を使うことができます。
これを修正するには、リモートデスクトップ接続を開き、「オプションの表示」を開き、「ローカル リソース」タブを開きます。キーボードセクションで、ドロップダウンを「このコンピューター」に変更します。これにより問題が修正され、キャラクタが正しく動作するようになります。
さらに、Windows でリモートデスクトップ接続を使う場合に、問題が発生する場合があります。なぜならば、これらのキーコードは人よりも速くキーイベントを送信するため、リモートデスクトップがキーコードを見落とすかもしれないからです。
この問題を解決するには、リモートデスクトップ接続を開いて「オプションの表示」をクリックし、「ローカル リソース」タブを開きます。キーボードセクションで、ドロップダウンを「このコンピューター」に変更します。これで問題が解決され、文字が正しく機能するようになります。
[`TAP_CODE_DELAY`](ja/config_options.md#behaviors-that-can-be-configured) を増やすことで緩和することもできます。
## 他のリソース

11
docs/ja/one_shot_keys.md
View file

@ -1,9 +1,9 @@
# ワンショットキー
<!---
original document: 0.12.41:docs/one_shot_keys.md
git diff 0.12.41 HEAD -- docs/one_shot_keys.md | cat
-->
original document: 0.13.34:docs/one_shot_keys.md
git diff 0.13.34 HEAD -- docs/one_shot_keys.md | cat
--->
ワンショットキーは次のキーが押されるまでアクティブのままになり、そのあと放されるキーです。これにより一度に1つ以上のキーを押すことなく、キーボードの組み合わせを入力することができます。これらのキーは通常「スティッキーキー」あるいは「デッドキー」と呼ばれます。
@ -22,10 +22,13 @@
* `OSM(mod)` - *mod*を一時的に押し続けます。[モッドタップ](ja/mod_tap.md)で示したように、`KC_*` コードでは無く、`MOD_*` キーコードを使わなければなりません。
* `OSL(layer)` - 一時的に*レイヤー*に切り替えます。
* `OS_ON` - ワンショットキーをオンにします。
* `OS_OFF` - ワンショットキーをオフにします。OSM は通常の mod キーのように機能し、OSL は `MO` キーのように機能します。
* `OS_TOGG` - ワンショットキーの状態を切り替えます。
ワンショットキーをマクロあるいはタップダンスルーチンの一部として有効にしたい場合があります。
ワンショットレイヤーについては、キーを押した時に `set_oneshot_layer(LAYER, ONESHOT_START)` を呼び出し、キーを放した時に `clear_oneshot_layer_state(ONESHOT_OTHER_KEY_PRESSED)` を呼び出す必要があります。ワンショットをキャンセルする場合は、`reset_oneshot_layer()` を呼び出してください。
ワンショットレイヤーについては、キーを押した時に `set_oneshot_layer(LAYER, ONESHOT_START)` を呼び出し、キーを放した時に `clear_oneshot_layer_state(ONESHOT_PRESSED)` を呼び出す必要があります。ワンショットをキャンセルする場合は、`reset_oneshot_layer()` を呼び出してください。
ワンショットモッドについては、設定するためには `set_oneshot_mods(MOD_BIT(KC_*))` を呼び出し、キャンセルするためには `clear_oneshot_mods()` を呼び出す必要があります。

19
docs/ja/pr_checklist.md
View file

@ -1,8 +1,8 @@
# PR チェックリスト
<!---
original document: 0.10.7:docs/pr_checklist.md
git diff 0.10.7 HEAD -- docs/pr_checklist.md | cat
original document: 0.13.34:docs/pr_checklist.md
git diff 0.13.34 HEAD -- docs/pr_checklist.md | cat
-->
これは、提出された PR を QMK の協力者がレビューする際に何をチェックするのかの非網羅的なチェックリストです。
@ -27,7 +27,7 @@
- 「旧式の」 GPIO/I2C/SPI 関数を使用しない - 正当な理由がない限り、QMK の抽象化を使用しなければなりません (怠惰は正当な理由にはなりません)
- タイミングの抽象化にも従う必要があります:
- `_delay_ms()` のかわりに `wait_ms()` を。(`#include <util/delay.h>` も消します)
- `timer_read()` と `timer_read32()` など。 -- タイミング API は [timer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/timer.h) を参照してください
- `timer_read()` と `timer_read32()` など。 -- タイミング API は [timer.h](https://github.com/qmk/qmk_firmware/blob/master/platforms/timer.h) を参照してください
- 新しい抽象化が有用だと思う場合は、次のことをお勧めします:
- 機能が完成するまで自分のキーボードでプロトタイプを作成する
- Discord の QMK コラボレータと話し合う
@ -73,11 +73,13 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
- キーボードが QMK で起動するために最低限必要なコードが存在する必要があります
- マトリックスと重要なデバイスの初期化コード
- (カスタムキーコードや特別なアニメーションなど)商用キーボードの既存の機能をミラーリングする場合は、`default` ではないキーマップを使って処理する必要があります
- Vial 関連のファイルまたは変更は QMK ファームウェアで使用されないため受け入れられません (Vial 固有のコアコードは提出またはマージされていません)
- `keyboard.c`
- 空の `xxxx_xxxx_kb()` または他の weak-define のデフォルト実装関数が削除されていること
- コメントアウトされた関数も削除されていること
- `matrix_init_board()` などが `keyboard_pre_init_kb()` に移行されました。[keyboard_pre_init*](https://docs.qmk.fm/#/ja/custom_quantum_functions?id=keyboard_pre_init_-function-documentation) を参照してください
- カスタムマトリックスを使用する場合は、`CUSTOM_MATRIX = lite` を選択し、標準のデバウンスを許可します。[マトリックスコードの部分置き換え](https://docs.qmk.fm/#/ja/custom_matrix?id=lite) を参照してください
- 可能な場合は、独自の `led_update_*()` 実装よりも LED インジケータの[設定オプション](https://docs.qmk.fm/#/ja/feature_led_indicators?id=configuration-options)を優先してください。
- `keyboard.h`
- 先頭に `#include "quantum.h"` を置きます
- `LAYOUT` マクロは、該当する場合は標準の定義を使用してください
@ -95,9 +97,12 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
...キーマップの `process_record_user()` 内で `layer_on()`、 `update_tri_layer()` を手動で処理する代わりに。
- default (および via) のキーマップは「素朴」でなければなりません。
- 他のユーザーが独自のユーザー固有のキーマップを開発するための「クリーンな状態」として使用するための最低限のもの。
- これらのキーマップで推奨される標準レイアウト（可能な場合）
- これらのキーマップでは標準のレイアウトが推奨されます（可能な場合）
- デフォルトのキーマップは VIA を有効にするべきではありません -- VIA の統合ドキュメント類には `via` という名前のキーマップが必要です。
- PR の提出者は、同じ PR に機能を紹介する個人的な（または豪華な）キーマップを持たせることができますが、「デフォルト」のキーマップに埋め込むべきではありません
- PR の提出者はまた、既存の商用キーボードへ QMK を移植する場合、その商用製品の既存の機能を反映する「製造業者に一致する」キーマップを持つことができます
- PR に VIA の json ファイルを含めないでください。これらは QMK ファームウェアで使われないため QMK リポジトリに属しません -- それらは [VIA のキーボードリポジトリ](https://github.com/the-via/keyboards)に属します。
さらに、ChibiOS に固有で:
- 既存の ChibiOS ボード定義を使用することを**強く**推奨します。
@ -132,3 +137,9 @@ There are instructions on how to keep your fork updated here:
Thanks for contributing!
```
## レビュープロセス
一般的に、PR がマージの対象となる前に、意味のある(例えば、コードを検査した)2つ(またはそれ以上)の承認を確認したいと考えています。これらのレビューはコラボレータに限られません -- 時間を割いてくれるコミュニティメンバーは誰でも歓迎(奨励)されます。唯一の違いは、チェックマークが緑にならないことですが、それは問題ありません。
また、PR レビューは自由な時間に行われるものです。それは好意で行われるものなので、私たちはレビューに費やす時間に対して、報酬はうけとっていませんし埋め合わせもありません。そのため、私たちがあなたのプルリクエストに取り掛かるのには時間がかかります。家族や生活のことで PR に手が回らなくなることもあり、そして燃え尽き症候群は深刻な懸念です。QMK ファームウェアリポジトリは、毎月平均200件の PR が開かれ、200件の PR がマージされますので、しばらくお待ちください。

7
docs/ja/syllabus.md
View file

@ -1,8 +1,8 @@
# QMK シラバス
<!---
original document: 0.9.51:docs/syllabus.md
git diff 0.9.51 HEAD -- docs/syllabus.md | cat
original document: 0.14.22:docs/syllabus.md
git diff 0.14.22 HEAD -- docs/syllabus.md | cat
-->
このページは最初に基本を紹介し、そして、QMK に習熟するために必要な全ての概念を理解するように導くことで、QMK の知識を構築するのに役立ちます。
@ -45,6 +45,7 @@
* [タップダンス](ja/feature_tap_dance.md)
* [コンボ](ja/feature_combo.md)
* [ユーザスペース](ja/feature_userspace.md)
* [キーオーバーライド](ja/feature_key_overrides.md)
# 上級トピック
@ -58,7 +59,7 @@
* **高度な機能**
* [ユニコード](ja/feature_unicode.md)
* [API](ja/api_overview.md)
* [ブートマジック](ja/feature_bootmagic.md)
* [ブートマジックライト](ja/feature_bootmagic.md)
* **ハードウェア**
* [キーボードがどのように動作するか](ja/how_keyboards_work.md)
* [キーボードマトリックスの仕組み](ja/how_a_matrix_works.md)

69
docs/ja/understanding_qmk.md
View file

@ -1,15 +1,15 @@
# QMK のコードの理解
<!---
original document: 0.13.15:docs/understanding_qmk.md
git diff 0.13.15 HEAD -- docs/understanding_qmk.md | cat
original document: 0.14.22:docs/understanding_qmk.md
git diff 0.14.22 HEAD -- docs/understanding_qmk.md | cat
-->
このドキュメントでは、QMK ファームウェアがどのように機能するかを非常に高いレベルから説明しようとしています。基本的なプログラミングの概念を理解していることを前提としていますが、(実例を示す必要がある場合を除き) C に精通していることを前提にはしていません。以下のドキュメントの基本的な知識があることを前提としています。
* [入門](ja/getting_started_introduction.md)
* [キーボードがどのように動作するか](ja/how_keyboards_work.md)
* [FAQ](ja/faq.md)
* [FAQ](ja/faq_general.md)
## スタートアップ
@ -138,41 +138,42 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
`process_record()` 関数自体は一見簡単に見えますが、その内部は QMK の様々なレベルで機能を上書きするためのゲートウェイが隠されています。キーボード/キーマップレベルの機能について調べる必要があるときは、以下に列挙した一連のイベントを手引帳として使います。`rules.mk` またはほかの場所で設定されたオプションに応じて、最終的なファームウェアに以下の関数のサブセットのみが含まれます。
* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/common/action.c#L172)
* [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L206)
* [このレコードをキーコードにマップする](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L226)
* [`void velocikey_accelerate(void)`](https://github.com/qmk/qmk_firmware/blob/c1c5922aae7b60b7c7d13d3769350eed9dda17ab/quantum/velocikey.c#L27)
* [`void preprocess_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L119)
* [`bool process_key_lock(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_key_lock.c#L62)
* [`bool process_clicky(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_clicky.c#L79)
* [`bool process_haptic(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/2cee371bf125a6ec541dd7c5a809573facc7c456/drivers/haptic/haptic.c#L216)
* [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/card.c#L20)
* [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/keymaps/default/keymap.c#L58)
* [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_midi.c#L81)
* [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19)
* [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160)
* [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_music.c#L114)
* [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L141)
* [`bool process_unicode_common(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode_common.c#L169) は、以下のいずれかを呼び出します:
* [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode.c#L20)
* [`bool process_unicodemap(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicodemap.c#L46)
* [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_ucis.c#L95)
* [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_leader.c#L51)
* [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_combo.c#L115)
* [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_printer.c#L77)
* [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_auto_shift.c#L94)
* [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_terminal.c#L264)
* [Quantum 固有のキーコードを識別して処理する](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L291)
* [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L206)
* [このレコードをキーコードにマップする](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L226)
* [`void velocikey_accelerate(void)`](https://github.com/qmk/qmk_firmware/blob/c1c5922aae7b60b7c7d13d3769350eed9dda17ab/quantum/velocikey.c#L27)
* [`void preprocess_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L119)
* [`bool process_key_lock(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_key_lock.c#L62)
* [`bool process_clicky(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_clicky.c#L79)
* [`bool process_haptic(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/2cee371bf125a6ec541dd7c5a809573facc7c456/drivers/haptic/haptic.c#L216)
* [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/card.c#L20)
* [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/keymaps/default/keymap.c#L58)
* [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_midi.c#L81)
* [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19)
* [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160)
* [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_music.c#L114)
* [`bool process_key_override(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/5a1b857dea45a17698f6baa7dd1b7a7ea907fb0a/quantum/process_keycode/process_key_override.c#L397)
* [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L141)
* [`bool process_unicode_common(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode_common.c#L169) は、以下のいずれかを呼び出します:
* [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode.c#L20)
* [`bool process_unicodemap(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicodemap.c#L46)
* [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_ucis.c#L95)
* [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_leader.c#L51)
* [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_combo.c#L115)
* [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_printer.c#L77)
* [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_auto_shift.c#L94)
* [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_terminal.c#L264)
* [Quantum 固有のキーコードを識別して処理する](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L291)
この一連のイベントの中の任意のステップで (`process_record_kb()` のような)関数は `false` を返して、以降の処理を停止することができます。
この呼び出しの後で、`post_process_record()` が呼ばれます。これはキーコードが通常処理された後に実行する必要がある追加のクリーンアップを処理するために使うことができます。
* [`void post_process_record(keyrecord_t *record)`]()
* [`void post_process_record_quantum(keyrecord_t *record)`]()
* [このレコードをキーコードにマップする]()
* [`void post_process_clicky(uint16_t keycode, keyrecord_t *record)`]()
* [`void post_process_record_kb(uint16_t keycode, keyrecord_t *record)`]()
* [`void post_process_record_user(uint16_t keycode, keyrecord_t *record)`]()
* [`void post_process_record_quantum(keyrecord_t *record)`]()
* [このレコードをキーコードにマップする]()
* [`void post_process_clicky(uint16_t keycode, keyrecord_t *record)`]()
* [`void post_process_record_kb(uint16_t keycode, keyrecord_t *record)`]()
* [`void post_process_record_user(uint16_t keycode, keyrecord_t *record)`]()
<!--
#### Mouse Handling
@ -183,10 +184,6 @@ FIXME: This needs to be written
FIXME: This needs to be written
#### Visualizer
FIXME: This needs to be written
#### Keyboard state LEDs (Caps Lock, Num Lock, Scroll Lock)
FIXME: This needs to be written

409
docs/keycodes.md
View file

@ -8,205 +8,205 @@ This is a reference only. Each group of keys links to the page documenting their
See also: [Basic Keycodes](keycodes_basic.md)
|Key |Aliases |Description |Windows |macOS |Linux<sup>1</sup>|
|-----------------------|------------------------------|-----------------------------------------------|-------------|-------------|-----------------|
|`KC_NO` |`XXXXXXX` |Ignore this key (NOOP) |*N/A* |*N/A* |*N/A* |
|`KC_TRANSPARENT` |`KC_TRNS`, `_______` |Use the next lowest non-transparent key |*N/A* |*N/A* |*N/A* |
|`KC_A` | |`a` and `A` |✔ |✔ |✔ |
|`KC_B` | |`b` and `B` |✔ |✔ |✔ |
|`KC_C` | |`c` and `C` |✔ |✔ |✔ |
|`KC_D` | |`d` and `D` |✔ |✔ |✔ |
|`KC_E` | |`e` and `E` |✔ |✔ |✔ |
|`KC_F` | |`f` and `F` |✔ |✔ |✔ |
|`KC_G` | |`g` and `G` |✔ |✔ |✔ |
|`KC_H` | |`h` and `H` |✔ |✔ |✔ |
|`KC_I` | |`i` and `I` |✔ |✔ |✔ |
|`KC_J` | |`j` and `J` |✔ |✔ |✔ |
|`KC_K` | |`k` and `K` |✔ |✔ |✔ |
|`KC_L` | |`l` and `L` |✔ |✔ |✔ |
|`KC_M` | |`m` and `M` |✔ |✔ |✔ |
|`KC_N` | |`n` and `N` |✔ |✔ |✔ |
|`KC_O` | |`o` and `O` |✔ |✔ |✔ |
|`KC_P` | |`p` and `P` |✔ |✔ |✔ |
|`KC_Q` | |`q` and `Q` |✔ |✔ |✔ |
|`KC_R` | |`r` and `R` |✔ |✔ |✔ |
|`KC_S` | |`s` and `S` |✔ |✔ |✔ |
|`KC_T` | |`t` and `T` |✔ |✔ |✔ |
|`KC_U` | |`u` and `U` |✔ |✔ |✔ |
|`KC_V` | |`v` and `V` |✔ |✔ |✔ |
|`KC_W` | |`w` and `W` |✔ |✔ |✔ |
|`KC_X` | |`x` and `X` |✔ |✔ |✔ |
|`KC_Y` | |`y` and `Y` |✔ |✔ |✔ |
|`KC_Z` | |`z` and `Z` |✔ |✔ |✔ |
|`KC_1` | |`1` and `!` |✔ |✔ |✔ |
|`KC_2` | |`2` and `@` |✔ |✔ |✔ |
|`KC_3` | |`3` and `#` |✔ |✔ |✔ |
|`KC_4` | |`4` and `$` |✔ |✔ |✔ |
|`KC_5` | |`5` and `%` |✔ |✔ |✔ |
|`KC_6` | |`6` and `^` |✔ |✔ |✔ |
|`KC_7` | |`7` and `&` |✔ |✔ |✔ |
|`KC_8` | |`8` and `*` |✔ |✔ |✔ |
|`KC_9` | |`9` and `(` |✔ |✔ |✔ |
|`KC_0` | |`0` and `)` |✔ |✔ |✔ |
|`KC_ENTER` |`KC_ENT` |Return (Enter) |✔ |✔ |✔ |
|`KC_ESCAPE` |`KC_ESC` |Escape |✔ |✔ |✔ |
|`KC_BSPACE` |`KC_BSPC` |Delete (Backspace) |✔ |✔ |✔ |
|`KC_TAB` | |Tab |✔ |✔ |✔ |
|`KC_SPACE` |`KC_SPC` |Spacebar |✔ |✔ |✔ |
|`KC_MINUS` |`KC_MINS` |`-` and `_` |✔ |✔ |✔ |
|`KC_EQUAL` |`KC_EQL` |`=` and `+` |✔ |✔ |✔ |
|`KC_LBRACKET` |`KC_LBRC` |`[` and `{` |✔ |✔ |✔ |
|`KC_RBRACKET` |`KC_RBRC` |`]` and `}` |✔ |✔ |✔ |
|`KC_BSLASH` |`KC_BSLS` |`\` and `\|` |✔ |✔ |✔ |
|`KC_NONUS_HASH` |`KC_NUHS` |Non-US `#` and `~` |✔ |✔ |✔ |
|`KC_SCOLON` |`KC_SCLN` |`;` and `:` |✔ |✔ |✔ |
|`KC_QUOTE` |`KC_QUOT` |`'` and `"` |✔ |✔ |✔ |
|`KC_GRAVE` |`KC_GRV`, `KC_ZKHK` |<code>&#96;</code> and `~`, JIS Zenkaku/Hankaku|✔ |✔ |✔ |
|`KC_COMMA` |`KC_COMM` |`,` and `<` |✔ |✔ |✔ |
|`KC_DOT` | |`.` and `>` |✔ |✔ |✔ |
|`KC_SLASH` |`KC_SLSH` |`/` and `?` |✔ |✔ |✔ |
|`KC_CAPSLOCK` |`KC_CLCK`, `KC_CAPS` |Caps Lock |✔ |✔ |✔ |
|`KC_F1` | |F1 |✔ |✔ |✔ |
|`KC_F2` | |F2 |✔ |✔ |✔ |
|`KC_F3` | |F3 |✔ |✔ |✔ |
|`KC_F4` | |F4 |✔ |✔ |✔ |
|`KC_F5` | |F5 |✔ |✔ |✔ |
|`KC_F6` | |F6 |✔ |✔ |✔ |
|`KC_F7` | |F7 |✔ |✔ |✔ |
|`KC_F8` | |F8 |✔ |✔ |✔ |
|`KC_F9` | |F9 |✔ |✔ |✔ |
|`KC_F10` | |F10 |✔ |✔ |✔ |
|`KC_F11` | |F11 |✔ |✔ |✔ |
|`KC_F12` | |F12 |✔ |✔ |✔ |
|`KC_PSCREEN` |`KC_PSCR` |Print Screen |✔ |✔<sup>2</sup>|✔ |
|`KC_SCROLLLOCK` |`KC_SLCK`, `KC_BRMD` |Scroll Lock, Brightness Down (macOS) |✔ |✔<sup>2</sup>|✔ |
|`KC_PAUSE` |`KC_PAUS`, `KC_BRK`, `KC_BRMU`|Pause, Brightness Up (macOS) |✔ |✔<sup>2</sup>|✔ |
|`KC_INSERT` |`KC_INS` |Insert |✔ | |✔ |
|`KC_HOME` | |Home |✔ |✔ |✔ |
|`KC_PGUP` | |Page Up |✔ |✔ |✔ |
|`KC_DELETE` |`KC_DEL` |Forward Delete |✔ |✔ |✔ |
|`KC_END` | |End |✔ |✔ |✔ |
|`KC_PGDOWN` |`KC_PGDN` |Page Down |✔ |✔ |✔ |
|`KC_RIGHT` |`KC_RGHT` |Right Arrow |✔ |✔ |✔ |
|`KC_LEFT` | |Left Arrow |✔ |✔ |✔ |
|`KC_DOWN` | |Down Arrow |✔ |✔ |✔ |
|`KC_UP` | |Up Arrow |✔ |✔ |✔ |
|`KC_NUMLOCK` |`KC_NLCK` |Keypad Num Lock and Clear |✔ |✔ |✔ |
|`KC_KP_SLASH` |`KC_PSLS` |Keypad `/` |✔ |✔ |✔ |
|`KC_KP_ASTERISK` |`KC_PAST` |Keypad `*` |✔ |✔ |✔ |
|`KC_KP_MINUS` |`KC_PMNS` |Keypad `-` |✔ |✔ |✔ |
|`KC_KP_PLUS` |`KC_PPLS` |Keypad `+` |✔ |✔ |✔ |
|`KC_KP_ENTER` |`KC_PENT` |Keypad Enter |✔ |✔ |✔ |
|`KC_KP_1` |`KC_P1` |Keypad `1` and End |✔ |✔ |✔ |
|`KC_KP_2` |`KC_P2` |Keypad `2` and Down Arrow |✔ |✔ |✔ |
|`KC_KP_3` |`KC_P3` |Keypad `3` and Page Down |✔ |✔ |✔ |
|`KC_KP_4` |`KC_P4` |Keypad `4` and Left Arrow |✔ |✔ |✔ |
|`KC_KP_5` |`KC_P5` |Keypad `5` |✔ |✔ |✔ |
|`KC_KP_6` |`KC_P6` |Keypad `6` and Right Arrow |✔ |✔ |✔ |
|`KC_KP_7` |`KC_P7` |Keypad `7` and Home |✔ |✔ |✔ |
|`KC_KP_8` |`KC_P8` |Keypad `8` and Up Arrow |✔ |✔ |✔ |
|`KC_KP_9` |`KC_P9` |Keypad `9` and Page Up |✔ |✔ |✔ |
|`KC_KP_0` |`KC_P0` |Keypad `0` and Insert |✔ |✔ |✔ |
|`KC_KP_DOT` |`KC_PDOT` |Keypad `.` and Delete |✔ |✔ |✔ |
|`KC_NONUS_BSLASH` |`KC_NUBS` |Non-US `\` and `\|` |✔ |✔ |✔ |
|`KC_APPLICATION` |`KC_APP` |Application (Windows Context Menu Key) |✔ | |✔ |
|`KC_POWER` | |System Power | |✔<sup>3</sup>|✔ |
|`KC_KP_EQUAL` |`KC_PEQL` |Keypad `=` |✔ |✔ |✔ |
|`KC_F13` | |F13 |✔ |✔ |✔ |
|`KC_F14` | |F14 |✔ |✔ |✔ |
|`KC_F15` | |F15 |✔ |✔ |✔ |
|`KC_F16` | |F16 |✔ |✔ |✔ |
|`KC_F17` | |F17 |✔ |✔ |✔ |
|`KC_F18` | |F18 |✔ |✔ |✔ |
|`KC_F19` | |F19 |✔ |✔ |✔ |
|`KC_F20` | |F20 |✔ | |✔ |
|`KC_F21` | |F21 |✔ | |✔ |
|`KC_F22` | |F22 |✔ | |✔ |
|`KC_F23` | |F23 |✔ | |✔ |
|`KC_F24` | |F24 |✔ | |✔ |
|`KC_EXECUTE` |`KC_EXEC` |Execute | | |✔ |
|`KC_HELP` | |Help | | |✔ |
|`KC_MENU` | |Menu | | |✔ |
|`KC_SELECT` |`KC_SLCT` |Select | | |✔ |
|`KC_STOP` | |Stop | | |✔ |
|`KC_AGAIN` |`KC_AGIN` |Again | | |✔ |
|`KC_UNDO` | |Undo | | |✔ |
|`KC_CUT` | |Cut | | |✔ |
|`KC_COPY` | |Copy | | |✔ |
|`KC_PASTE` |`KC_PSTE` |Paste | | |✔ |
|`KC_FIND` | |Find | | |✔ |
|`KC__MUTE` | |Mute | |✔ |✔ |
|`KC__VOLUP` | |Volume Up | |✔ |✔ |
|`KC__VOLDOWN` | |Volume Down | |✔ |✔ |
|`KC_LOCKING_CAPS` |`KC_LCAP` |Locking Caps Lock |✔ |✔ | |
|`KC_LOCKING_NUM` |`KC_LNUM` |Locking Num Lock |✔ |✔ | |
|`KC_LOCKING_SCROLL` |`KC_LSCR` |Locking Scroll Lock |✔ |✔ | |
|`KC_KP_COMMA` |`KC_PCMM` |Keypad `,` | | |✔ |
|`KC_KP_EQUAL_AS400` | |Keypad `=` on AS/400 keyboards | | | |
|`KC_INT1` |`KC_RO` |JIS `\` and `_` |✔ | |✔ |
|`KC_INT2` |`KC_KANA` |JIS Katakana/Hiragana |✔ | |✔ |
|`KC_INT3` |`KC_JYEN` |JIS `¥` and `\|` |✔ | |✔ |
|`KC_INT4` |`KC_HENK` |JIS Henkan |✔ | |✔ |
|`KC_INT5` |`KC_MHEN` |JIS Muhenkan |✔ | |✔ |
|`KC_INT6` | |JIS Numpad `,` | | |✔ |
|`KC_INT7` | |International 7 | | | |
|`KC_INT8` | |International 8 | | | |
|`KC_INT9` | |International 9 | | | |
|`KC_LANG1` |`KC_HAEN` |Hangul/English | | |✔ |
|`KC_LANG2` |`KC_HANJ` |Hanja | | |✔ |
|`KC_LANG3` | |JIS Katakana | | |✔ |
|`KC_LANG4` | |JIS Hiragana | | |✔ |
|`KC_LANG5` | |JIS Zenkaku/Hankaku | | |✔ |
|`KC_LANG6` | |Language 6 | | | |
|`KC_LANG7` | |Language 7 | | | |
|`KC_LANG8` | |Language 8 | | | |
|`KC_LANG9` | |Language 9 | | | |
|`KC_ALT_ERASE` |`KC_ERAS` |Alternate Erase | | | |
|`KC_SYSREQ` | |SysReq/Attention | | | |
|`KC_CANCEL` | |Cancel | | | |
|`KC_CLEAR` |`KC_CLR` |Clear | | |✔ |
|`KC_PRIOR` | |Prior | | | |
|`KC_RETURN` | |Return | | | |
|`KC_SEPARATOR` | |Separator | | | |
|`KC_OUT` | |Out | | | |
|`KC_OPER` | |Oper | | | |
|`KC_CLEAR_AGAIN` | |Clear/Again | | | |
|`KC_CRSEL` | |CrSel/Props | | | |
|`KC_EXSEL` | |ExSel | | | |
|`KC_LCTRL` |`KC_LCTL` |Left Control |✔ |✔ |✔ |
|`KC_LSHIFT` |`KC_LSFT` |Left Shift |✔ |✔ |✔ |
|`KC_LALT` |`KC_LOPT` |Left Alt (Option) |✔ |✔ |✔ |
|`KC_LGUI` |`KC_LCMD`, `KC_LWIN` |Left GUI (Windows/Command/Meta key) |✔ |✔ |✔ |
|`KC_RCTRL` |`KC_RCTL` |Right Control |✔ |✔ |✔ |
|`KC_RSHIFT` |`KC_RSFT` |Right Shift |✔ |✔ |✔ |
|`KC_RALT` |`KC_ROPT`, `KC_ALGR` |Right Alt (Option/AltGr) |✔ |✔ |✔ |
|`KC_RGUI` |`KC_RCMD`, `KC_RWIN` |Right GUI (Windows/Command/Meta key) |✔ |✔ |✔ |
|`KC_SYSTEM_POWER` |`KC_PWR` |System Power Down |✔ |✔<sup>3</sup>|✔ |
|`KC_SYSTEM_SLEEP` |`KC_SLEP` |System Sleep |✔ |✔<sup>3</sup>|✔ |
|`KC_SYSTEM_WAKE` |`KC_WAKE` |System Wake | |✔<sup>3</sup>|✔ |
|`KC_AUDIO_MUTE` |`KC_MUTE` |Mute |✔ |✔ |✔ |
|`KC_AUDIO_VOL_UP` |`KC_VOLU` |Volume Up |✔ |✔<sup>4</sup>|✔ |
|`KC_AUDIO_VOL_DOWN` |`KC_VOLD` |Volume Down |✔ |✔<sup>4</sup>|✔ |
|`KC_MEDIA_NEXT_TRACK` |`KC_MNXT` |Next Track |✔ |✔<sup>5</sup>|✔ |
|`KC_MEDIA_PREV_TRACK` |`KC_MPRV` |Previous Track |✔ |✔<sup>5</sup>|✔ |
|`KC_MEDIA_STOP` |`KC_MSTP` |Stop Track |✔ | |✔ |
|`KC_MEDIA_PLAY_PAUSE` |`KC_MPLY` |Play/Pause Track |✔ |✔ |✔ |
|`KC_MEDIA_SELECT` |`KC_MSEL` |Launch Media Player |✔ | |✔ |
|`KC_MEDIA_EJECT` |`KC_EJCT` |Eject | |✔ |✔ |
|`KC_MAIL` | |Launch Mail |✔ | |✔ |
|`KC_CALCULATOR` |`KC_CALC` |Launch Calculator |✔ | |✔ |
|`KC_MY_COMPUTER` |`KC_MYCM` |Launch My Computer |✔ | |✔ |
|`KC_WWW_SEARCH` |`KC_WSCH` |Browser Search |✔ | |✔ |
|`KC_WWW_HOME` |`KC_WHOM` |Browser Home |✔ | |✔ |
|`KC_WWW_BACK` |`KC_WBAK` |Browser Back |✔ | |✔ |
|`KC_WWW_FORWARD` |`KC_WFWD` |Browser Forward |✔ | |✔ |
|`KC_WWW_STOP` |`KC_WSTP` |Browser Stop |✔ | |✔ |
|`KC_WWW_REFRESH` |`KC_WREF` |Browser Refresh |✔ | |✔ |
|`KC_WWW_FAVORITES` |`KC_WFAV` |Browser Favorites |✔ | |✔ |
|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD` |Next Track |✔ |✔<sup>5</sup>|✔ |
|`KC_MEDIA_REWIND` |`KC_MRWD` |Previous Track |✔<sup>6</sup>|✔<sup>5</sup>|✔ |
|`KC_BRIGHTNESS_UP` |`KC_BRIU` |Brightness Up |✔ |✔ |✔ |
|`KC_BRIGHTNESS_DOWN` |`KC_BRID` |Brightness Down |✔ |✔ |✔ |
|Key |Aliases |Description |Windows |macOS |Linux<sup>1</sup>|
|------------------------|-------------------------------|---------------------------------------|-------------|-------------|-----------------|
|`KC_NO` |`XXXXXXX` |Ignore this key (NOOP) |*N/A* |*N/A* |*N/A* |
|`KC_TRANSPARENT` |`KC_TRNS`, `_______` |Use the next lowest non-transparent key|*N/A* |*N/A* |*N/A* |
|`KC_A` | |`a` and `A` |✔ |✔ |✔ |
|`KC_B` | |`b` and `B` |✔ |✔ |✔ |
|`KC_C` | |`c` and `C` |✔ |✔ |✔ |
|`KC_D` | |`d` and `D` |✔ |✔ |✔ |
|`KC_E` | |`e` and `E` |✔ |✔ |✔ |
|`KC_F` | |`f` and `F` |✔ |✔ |✔ |
|`KC_G` | |`g` and `G` |✔ |✔ |✔ |
|`KC_H` | |`h` and `H` |✔ |✔ |✔ |
|`KC_I` | |`i` and `I` |✔ |✔ |✔ |
|`KC_J` | |`j` and `J` |✔ |✔ |✔ |
|`KC_K` | |`k` and `K` |✔ |✔ |✔ |
|`KC_L` | |`l` and `L` |✔ |✔ |✔ |
|`KC_M` | |`m` and `M` |✔ |✔ |✔ |
|`KC_N` | |`n` and `N` |✔ |✔ |✔ |
|`KC_O` | |`o` and `O` |✔ |✔ |✔ |
|`KC_P` | |`p` and `P` |✔ |✔ |✔ |
|`KC_Q` | |`q` and `Q` |✔ |✔ |✔ |
|`KC_R` | |`r` and `R` |✔ |✔ |✔ |
|`KC_S` | |`s` and `S` |✔ |✔ |✔ |
|`KC_T` | |`t` and `T` |✔ |✔ |✔ |
|`KC_U` | |`u` and `U` |✔ |✔ |✔ |
|`KC_V` | |`v` and `V` |✔ |✔ |✔ |
|`KC_W` | |`w` and `W` |✔ |✔ |✔ |
|`KC_X` | |`x` and `X` |✔ |✔ |✔ |
|`KC_Y` | |`y` and `Y` |✔ |✔ |✔ |
|`KC_Z` | |`z` and `Z` |✔ |✔ |✔ |
|`KC_1` | |`1` and `!` |✔ |✔ |✔ |
|`KC_2` | |`2` and `@` |✔ |✔ |✔ |
|`KC_3` | |`3` and `#` |✔ |✔ |✔ |
|`KC_4` | |`4` and `$` |✔ |✔ |✔ |
|`KC_5` | |`5` and `%` |✔ |✔ |✔ |
|`KC_6` | |`6` and `^` |✔ |✔ |✔ |
|`KC_7` | |`7` and `&` |✔ |✔ |✔ |
|`KC_8` | |`8` and `*` |✔ |✔ |✔ |
|`KC_9` | |`9` and `(` |✔ |✔ |✔ |
|`KC_0` | |`0` and `)` |✔ |✔ |✔ |
|`KC_ENTER` |`KC_ENT` |Return (Enter) |✔ |✔ |✔ |
|`KC_ESCAPE` |`KC_ESC` |Escape |✔ |✔ |✔ |
|`KC_BACKSPACE` |`KC_BSPC` |Delete (Backspace) |✔ |✔ |✔ |
|`KC_TAB` | |Tab |✔ |✔ |✔ |
|`KC_SPACE` |`KC_SPC` |Spacebar |✔ |✔ |✔ |
|`KC_MINUS` |`KC_MINS` |`-` and `_` |✔ |✔ |✔ |
|`KC_EQUAL` |`KC_EQL` |`=` and `+` |✔ |✔ |✔ |
|`KC_LEFT_BRACKET` |`KC_LBRC` |`[` and `{` |✔ |✔ |✔ |
|`KC_RIGHT_BRACKET` |`KC_RBRC` |`]` and `}` |✔ |✔ |✔ |
|`KC_BACKSLASH` |`KC_BSLS` |`\` and `\|` |✔ |✔ |✔ |
|`KC_NONUS_HASH` |`KC_NUHS` |Non-US `#` and `~` |✔ |✔ |✔ |
|`KC_SEMICOLON` |`KC_SCLN` |`;` and `:` |✔ |✔ |✔ |
|`KC_QUOTE` |`KC_QUOT` |`'` and `"` |✔ |✔ |✔ |
|`KC_GRAVE` |`KC_GRV` |<code>&#96;</code> and `~` |✔ |✔ |✔ |
|`KC_COMMA` |`KC_COMM` |`,` and `<` |✔ |✔ |✔ |
|`KC_DOT` | |`.` and `>` |✔ |✔ |✔ |
|`KC_SLASH` |`KC_SLSH` |`/` and `?` |✔ |✔ |✔ |
|`KC_CAPS_LOCK` |`KC_CAPS` |Caps Lock |✔ |✔ |✔ |
|`KC_F1` | |F1 |✔ |✔ |✔ |
|`KC_F2` | |F2 |✔ |✔ |✔ |
|`KC_F3` | |F3 |✔ |✔ |✔ |
|`KC_F4` | |F4 |✔ |✔ |✔ |
|`KC_F5` | |F5 |✔ |✔ |✔ |
|`KC_F6` | |F6 |✔ |✔ |✔ |
|`KC_F7` | |F7 |✔ |✔ |✔ |
|`KC_F8` | |F8 |✔ |✔ |✔ |
|`KC_F9` | |F9 |✔ |✔ |✔ |
|`KC_F10` | |F10 |✔ |✔ |✔ |
|`KC_F11` | |F11 |✔ |✔ |✔ |
|`KC_F12` | |F12 |✔ |✔ |✔ |
|`KC_PRINT_SCREEN` |`KC_PSCR` |Print Screen |✔ |✔<sup>2</sup>|✔ |
|`KC_SCROLL_LOCK` |`KC_SCRL`, `KC_BRMD` |Scroll Lock, Brightness Down (macOS) |✔ |✔<sup>2</sup>|✔ |
|`KC_PAUSE` |`KC_PAUS`, `KC_BRK`, `KC_BRMU` |Pause, Brightness Up (macOS) |✔ |✔<sup>2</sup>|✔ |
|`KC_INSERT` |`KC_INS` |Insert |✔ | |✔ |
|`KC_HOME` | |Home |✔ |✔ |✔ |
|`KC_PAGE_UP` |`KC_PGUP` |Page Up |✔ |✔ |✔ |
|`KC_DELETE` |`KC_DEL` |Forward Delete |✔ |✔ |✔ |
|`KC_END` | |End |✔ |✔ |✔ |
|`KC_PAGE_DOWN` |`KC_PGDN` |Page Down |✔ |✔ |✔ |
|`KC_RIGHT` |`KC_RGHT` |Right Arrow |✔ |✔ |✔ |
|`KC_LEFT` | |Left Arrow |✔ |✔ |✔ |
|`KC_DOWN` | |Down Arrow |✔ |✔ |✔ |
|`KC_UP` | |Up Arrow |✔ |✔ |✔ |
|`KC_NUM_LOCK` |`KC_NUM` |Keypad Num Lock and Clear |✔ |✔ |✔ |
|`KC_KP_SLASH` |`KC_PSLS` |Keypad `/` |✔ |✔ |✔ |
|`KC_KP_ASTERISK` |`KC_PAST` |Keypad `*` |✔ |✔ |✔ |
|`KC_KP_MINUS` |`KC_PMNS` |Keypad `-` |✔ |✔ |✔ |
|`KC_KP_PLUS` |`KC_PPLS` |Keypad `+` |✔ |✔ |✔ |
|`KC_KP_ENTER` |`KC_PENT` |Keypad Enter |✔ |✔ |✔ |
|`KC_KP_1` |`KC_P1` |Keypad `1` and End |✔ |✔ |✔ |
|`KC_KP_2` |`KC_P2` |Keypad `2` and Down Arrow |✔ |✔ |✔ |
|`KC_KP_3` |`KC_P3` |Keypad `3` and Page Down |✔ |✔ |✔ |
|`KC_KP_4` |`KC_P4` |Keypad `4` and Left Arrow |✔ |✔ |✔ |
|`KC_KP_5` |`KC_P5` |Keypad `5` |✔ |✔ |✔ |
|`KC_KP_6` |`KC_P6` |Keypad `6` and Right Arrow |✔ |✔ |✔ |
|`KC_KP_7` |`KC_P7` |Keypad `7` and Home |✔ |✔ |✔ |
|`KC_KP_8` |`KC_P8` |Keypad `8` and Up Arrow |✔ |✔ |✔ |
|`KC_KP_9` |`KC_P9` |Keypad `9` and Page Up |✔ |✔ |✔ |
|`KC_KP_0` |`KC_P0` |Keypad `0` and Insert |✔ |✔ |✔ |
|`KC_KP_DOT` |`KC_PDOT` |Keypad `.` and Delete |✔ |✔ |✔ |
|`KC_NONUS_BACKSLASH` |`KC_NUBS` |Non-US `\` and `\|` |✔ |✔ |✔ |
|`KC_APPLICATION` |`KC_APP` |Application (Windows Context Menu Key) |✔ | |✔ |
|`KC_KB_POWER` | |System Power | |✔<sup>3</sup>|✔ |
|`KC_KP_EQUAL` |`KC_PEQL` |Keypad `=` |✔ |✔ |✔ |
|`KC_F13` | |F13 |✔ |✔ |✔ |
|`KC_F14` | |F14 |✔ |✔ |✔ |
|`KC_F15` | |F15 |✔ |✔ |✔ |
|`KC_F16` | |F16 |✔ |✔ |✔ |
|`KC_F17` | |F17 |✔ |✔ |✔ |
|`KC_F18` | |F18 |✔ |✔ |✔ |
|`KC_F19` | |F19 |✔ |✔ |✔ |
|`KC_F20` | |F20 |✔ | |✔ |
|`KC_F21` | |F21 |✔ | |✔ |
|`KC_F22` | |F22 |✔ | |✔ |
|`KC_F23` | |F23 |✔ | |✔ |
|`KC_F24` | |F24 |✔ | |✔ |
|`KC_EXECUTE` |`KC_EXEC` |Execute | | |✔ |
|`KC_HELP` | |Help | | |✔ |
|`KC_MENU` | |Menu | | |✔ |
|`KC_SELECT` |`KC_SLCT` |Select | | |✔ |
|`KC_STOP` | |Stop | | |✔ |
|`KC_AGAIN` |`KC_AGIN` |Again | | |✔ |
|`KC_UNDO` | |Undo | | |✔ |
|`KC_CUT` | |Cut | | |✔ |
|`KC_COPY` | |Copy | | |✔ |
|`KC_PASTE` |`KC_PSTE` |Paste | | |✔ |
|`KC_FIND` | |Find | | |✔ |
|`KC_KB_MUTE` | |Mute | |✔ |✔ |
|`KC_KB_VOLUME_UP` | |Volume Up | |✔ |✔ |
|`KC_KB_VOLUME_DOWN` | |Volume Down | |✔ |✔ |
|`KC_LOCKING_CAPS_LOCK` |`KC_LCAP` |Locking Caps Lock |✔ |✔ | |
|`KC_LOCKING_NUM_LOCK` |`KC_LNUM` |Locking Num Lock |✔ |✔ | |
|`KC_LOCKING_SCROLL_LOCK`|`KC_LSCR` |Locking Scroll Lock |✔ |✔ | |
|`KC_KP_COMMA` |`KC_PCMM` |Keypad `,` | | |✔ |
|`KC_KP_EQUAL_AS400` | |Keypad `=` on AS/400 keyboards | | | |
|`KC_INTERNATIONAL_1` |`KC_INT1` |International 1 |✔ | |✔ |
|`KC_INTERNATIONAL_2` |`KC_INT2` |International 2 |✔ | |✔ |
|`KC_INTERNATIONAL_3` |`KC_INT3` |International 3 |✔ | |✔ |
|`KC_INTERNATIONAL_4` |`KC_INT4` |International 4 |✔ | |✔ |
|`KC_INTERNATIONAL_5` |`KC_INT5` |International 5 |✔ | |✔ |
|`KC_INTERNATIONAL_6` |`KC_INT6` |International 6 | | |✔ |
|`KC_INTERNATIONAL_7` |`KC_INT7` |International 7 | | | |
|`KC_INTERNATIONAL_8` |`KC_INT8` |International 8 | | | |
|`KC_INTERNATIONAL_9` |`KC_INT9` |International 9 | | | |
|`KC_LANGUAGE_1` |`KC_LNG1` |Language 1 | | |✔ |
|`KC_LANGUAGE_2` |`KC_LNG2` |Language 2 | | |✔ |
|`KC_LANGUAGE_3` |`KC_LNG3` |Language 3 | | |✔ |
|`KC_LANGUAGE_4` |`KC_LNG4` |Language 4 | | |✔ |
|`KC_LANGUAGE_5` |`KC_LNG5` |Language 5 | | |✔ |
|`KC_LANGUAGE_6` |`KC_LNG6` |Language 6 | | | |
|`KC_LANGUAGE_7` |`KC_LNG7` |Language 7 | | | |
|`KC_LANGUAGE_8` |`KC_LNG8` |Language 8 | | | |
|`KC_LANGUAGE_9` |`KC_LNG9` |Language 9 | | | |
|`KC_ALTERNATE_ERASE` |`KC_ERAS` |Alternate Erase | | | |
|`KC_SYSTEM_REQUEST` |`KC_SYRQ` |SysReq/Attention | | | |
|`KC_CANCEL` |`KC_CNCL` |Cancel | | | |
|`KC_CLEAR` |`KC_CLR` |Clear | | |✔ |
|`KC_PRIOR` |`KC_PRIR` |Prior | | | |
|`KC_RETURN` |`KC_RETN` |Return | | | |
|`KC_SEPARATOR` |`KC_SEPR` |Separator | | | |
|`KC_OUT` | |Out | | | |
|`KC_OPER` | |Oper | | | |
|`KC_CLEAR_AGAIN` |`KC_CLAG` |Clear/Again | | | |
|`KC_CRSEL` |`KC_CRSL` |CrSel/Props | | | |
|`KC_EXSEL` |`KC_EXSL` |ExSel | | | |
|`KC_LEFT_CTRL` |`KC_LCTL` |Left Control |✔ |✔ |✔ |
|`KC_LEFT_SHIFT` |`KC_LSFT` |Left Shift |✔ |✔ |✔ |
|`KC_LEFT_ALT` |`KC_LALT`, `KC_LOPT` |Left Alt (Option) |✔ |✔ |✔ |
|`KC_LEFT_GUI` |`KC_LGUI`, `KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) |✔ |✔ |✔ |
|`KC_RIGHT_CTRL` |`KC_RCTL` |Right Control |✔ |✔ |✔ |
|`KC_RIGHT_SHIFT` |`KC_RSFT` |Right Shift |✔ |✔ |✔ |
|`KC_RIGHT_ALT` |`KC_RALT`, `KC_ROPT`, `KC_ALGR`|Right Alt (Option/AltGr) |✔ |✔ |✔ |
|`KC_RIGHT_GUI` |`KC_RGUI`, `KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key) |✔ |✔ |✔ |
|`KC_SYSTEM_POWER` |`KC_PWR` |System Power Down |✔ |✔<sup>3</sup>|✔ |
|`KC_SYSTEM_SLEEP` |`KC_SLEP` |System Sleep |✔ |✔<sup>3</sup>|✔ |
|`KC_SYSTEM_WAKE` |`KC_WAKE` |System Wake | |✔<sup>3</sup>|✔ |
|`KC_AUDIO_MUTE` |`KC_MUTE` |Mute |✔ |✔ |✔ |
|`KC_AUDIO_VOL_UP` |`KC_VOLU` |Volume Up |✔ |✔<sup>4</sup>|✔ |
|`KC_AUDIO_VOL_DOWN` |`KC_VOLD` |Volume Down |✔ |✔<sup>4</sup>|✔ |
|`KC_MEDIA_NEXT_TRACK` |`KC_MNXT` |Next Track |✔ |✔<sup>5</sup>|✔ |
|`KC_MEDIA_PREV_TRACK` |`KC_MPRV` |Previous Track |✔ |✔<sup>5</sup>|✔ |
|`KC_MEDIA_STOP` |`KC_MSTP` |Stop Track |✔ | |✔ |
|`KC_MEDIA_PLAY_PAUSE` |`KC_MPLY` |Play/Pause Track |✔ |✔ |✔ |
|`KC_MEDIA_SELECT` |`KC_MSEL` |Launch Media Player |✔ | |✔ |
|`KC_MEDIA_EJECT` |`KC_EJCT` |Eject | |✔ |✔ |
|`KC_MAIL` | |Launch Mail |✔ | |✔ |
|`KC_CALCULATOR` |`KC_CALC` |Launch Calculator |✔ | |✔ |
|`KC_MY_COMPUTER` |`KC_MYCM` |Launch My Computer |✔ | |✔ |
|`KC_WWW_SEARCH` |`KC_WSCH` |Browser Search |✔ | |✔ |
|`KC_WWW_HOME` |`KC_WHOM` |Browser Home |✔ | |✔ |
|`KC_WWW_BACK` |`KC_WBAK` |Browser Back |✔ | |✔ |
|`KC_WWW_FORWARD` |`KC_WFWD` |Browser Forward |✔ | |✔ |
|`KC_WWW_STOP` |`KC_WSTP` |Browser Stop |✔ | |✔ |
|`KC_WWW_REFRESH` |`KC_WREF` |Browser Refresh |✔ | |✔ |
|`KC_WWW_FAVORITES` |`KC_WFAV` |Browser Favorites |✔ | |✔ |
|`KC_MEDIA_FAST_FORWARD` |`KC_MFFD` |Next Track |✔ |✔<sup>5</sup>|✔ |
|`KC_MEDIA_REWIND` |`KC_MRWD` |Previous Track |✔<sup>6</sup>|✔<sup>5</sup>|✔ |
|`KC_BRIGHTNESS_UP` |`KC_BRIU` |Brightness Up |✔ |✔ |✔ |
|`KC_BRIGHTNESS_DOWN` |`KC_BRID` |Brightness Down |✔ |✔ |✔ |
<sup>1. The Linux kernel HID driver recognizes [nearly all keycodes](https://github.com/torvalds/linux/blob/master/drivers/hid/hid-input.c), but the default bindings depend on the DE/WM.</sup><br/>
<sup>2. Treated as F13-F15.</sup><br/>
@ -344,6 +344,7 @@ See also: [Magic Keycodes](keycodes_magic.md)
|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
|`MAGIC_TOGGLE_GUI` |`GUI_TOG`|Toggles the status of the GUI keys |
|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>&#96;</code> and Escape |
|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>&#96;</code> and Escape |
|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
@ -585,6 +586,16 @@ See also: [Mod-Tap](mod_tap.md)
|`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](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
## Tapping Term Keys :id=tapping-term-keys
See also: [Dynamic Tapping Term](tap_hold#dynamic-tapping-term)
| Key | Description |
|-------------|------------------------------------------------------------------------------------------------------------------------|
| `DT_PRNT` | "Dynamic Tapping Term Print": Types the current tapping term, in milliseconds |
| `DT_UP` | "Dynamic Tapping Term Up": Increases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) |
| `DT_DOWN` | "Dynamic Tapping Term Down": Decreases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) |
## RGB Lighting :id=rgb-lighting
See also: [RGB Lighting](feature_rgblight.md)

200
docs/keycodes_basic.md
View file

@ -74,118 +74,118 @@ The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07
## Punctuation
|Key |Aliases |Description |
|-----------------|-------------------|-----------------------------------------------|
|`KC_ENTER` |`KC_ENT` |Return (Enter) |
|`KC_ESCAPE` |`KC_ESC` |Escape |
|`KC_BSPACE` |`KC_BSPC` |Delete (Backspace) |
|`KC_TAB` | |Tab |
|`KC_SPACE` |`KC_SPC` |Spacebar |
|`KC_MINUS` |`KC_MINS` |`-` and `_` |
|`KC_EQUAL` |`KC_EQL` |`=` and `+` |
|`KC_LBRACKET` |`KC_LBRC` |`[` and `{` |
|`KC_RBRACKET` |`KC_RBRC` |`]` and `}` |
|`KC_BSLASH` |`KC_BSLS` |`\` and `\|` |
|`KC_NONUS_HASH` |`KC_NUHS` |Non-US `#` and `~` |
|`KC_SCOLON` |`KC_SCLN` |`;` and `:` |
|`KC_QUOTE` |`KC_QUOT` |`'` and `"` |
|`KC_GRAVE` |`KC_GRV`, `KC_ZKHK`|<code>&#96;</code> and `~`, JIS Zenkaku/Hankaku|
|`KC_COMMA` |`KC_COMM` |`,` and `<` |
|`KC_DOT` | |`.` and `>` |
|`KC_SLASH` |`KC_SLSH` |`/` and `?` |
|`KC_NONUS_BSLASH`|`KC_NUBS` |Non-US `\` and `\|` |
|Key |Aliases |Description |
|--------------------|---------|--------------------------|
|`KC_ENTER` |`KC_ENT` |Return (Enter) |
|`KC_ESCAPE` |`KC_ESC` |Escape |
|`KC_BACKSPACE` |`KC_BSPC`|Delete (Backspace) |
|`KC_TAB` | |Tab |
|`KC_SPACE` |`KC_SPC` |Spacebar |
|`KC_MINUS` |`KC_MINS`|`-` and `_` |
|`KC_EQUAL` |`KC_EQL` |`=` and `+` |
|`KC_LEFT_BRACKET` |`KC_LBRC`|`[` and `{` |
|`KC_RIGHT_BRACKET` |`KC_RBRC`|`]` and `}` |
|`KC_BACKSLASH` |`KC_BSLS`|`\` and `\|` |
|`KC_NONUS_HASH` |`KC_NUHS`|Non-US `#` and `~` |
|`KC_SEMICOLON` |`KC_SCLN`|`;` and `:` |
|`KC_QUOTE` |`KC_QUOT`|`'` and `"` |
|`KC_GRAVE` |`KC_GRV` |<code>&#96;</code> and `~`|
|`KC_COMMA` |`KC_COMM`|`,` and `<` |
|`KC_DOT` | |`.` and `>` |
|`KC_SLASH` |`KC_SLSH`|`/` and `?` |
|`KC_NONUS_BACKSLASH`|`KC_NUBS`|Non-US `\` and `\|` |
## Lock Keys
|Key |Aliases |Description |
|-------------------|--------------------|------------------------------------|
|`KC_CAPSLOCK` |`KC_CLCK`, `KC_CAPS`|Caps Lock |
|`KC_SCROLLLOCK` |`KC_SLCK`, `KC_BRMD`|Scroll Lock, Brightness Down (macOS)|
|`KC_NUMLOCK` |`KC_NLCK` |Keypad Num Lock and Clear |
|`KC_LOCKING_CAPS` |`KC_LCAP` |Locking Caps Lock |
|`KC_LOCKING_NUM` |`KC_LNUM` |Locking Num Lock |
|`KC_LOCKING_SCROLL`|`KC_LSCR` |Locking Scroll Lock |
|Key |Aliases |Description |
|------------------------|--------------------|------------------------------------|
|`KC_CAPS_LOCK` |`KC_CAPS` |Caps Lock |
|`KC_SCROLL_LOCK` |`KC_SCRL`, `KC_BRMD`|Scroll Lock, Brightness Down (macOS)|
|`KC_NUM_LOCK` |`KC_NUM` |Keypad Num Lock and Clear |
|`KC_LOCKING_CAPS_LOCK` |`KC_LCAP` |Locking Caps Lock |
|`KC_LOCKING_NUM_LOCK` |`KC_LNUM` |Locking Num Lock |
|`KC_LOCKING_SCROLL_LOCK`|`KC_LSCR` |Locking Scroll Lock |
## Modifiers
|Key |Aliases |Description |
|-----------|--------------------|------------------------------------|
|`KC_LCTRL` |`KC_LCTL` |Left Control |
|`KC_LSHIFT`|`KC_LSFT` |Left Shift |
|`KC_LALT` |`KC_LOPT` |Left Alt (Option) |
|`KC_LGUI` |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) |
|`KC_RCTRL` |`KC_RCTL` |Right Control |
|`KC_RSHIFT`|`KC_RSFT` |Right Shift |
|`KC_RALT` |`KC_ROPT`, `KC_ALGR`|Right Alt (Option/AltGr) |
|`KC_RGUI` |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)|
|Key |Aliases |Description |
|----------------|-------------------------------|------------------------------------|
|`KC_LEFT_CTRL` |`KC_LCTL` |Left Control |
|`KC_LEFT_SHIFT` |`KC_LSFT` |Left Shift |
|`KC_LEFT_ALT` |`KC_LALT`, `KC_LOPT` |Left Alt (Option) |
|`KC_LEFT_GUI` |`KC_LGUI`, `KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) |
|`KC_RIGHT_CTRL` |`KC_RCTL` |Right Control |
|`KC_RIGHT_SHIFT`|`KC_RSFT` |Right Shift |
|`KC_RIGHT_ALT` |`KC_RALT`, `KC_ROPT`, `KC_ALGR`|Right Alt (Option/AltGr) |
|`KC_RIGHT_GUI` |`KC_RGUI`, `KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)|
## International
|Key |Aliases |Description |
|----------|---------|---------------------|
|`KC_INT1` |`KC_RO` |JIS `\` and `_` |
|`KC_INT2` |`KC_KANA`|JIS Katakana/Hiragana|
|`KC_INT3` |`KC_JYEN`|JIS `¥` and `\|` |
|`KC_INT4` |`KC_HENK`|JIS Henkan |
|`KC_INT5` |`KC_MHEN`|JIS Muhenkan |
|`KC_INT6` | |JIS Numpad `,` |
|`KC_INT7` | |International 7 |
|`KC_INT8` | |International 8 |
|`KC_INT9` | |International 9 |
|`KC_LANG1`|`KC_HAEN`|Hangul/English |
|`KC_LANG2`|`KC_HANJ`|Hanja |
|`KC_LANG3`| |JIS Katakana |
|`KC_LANG4`| |JIS Hiragana |
|`KC_LANG5`| |JIS Zenkaku/Hankaku |
|`KC_LANG6`| |Language 6 |
|`KC_LANG7`| |Language 7 |
|`KC_LANG8`| |Language 8 |
|`KC_LANG9`| |Language 9 |
|Key |Aliases |Description |
|--------------------|---------|---------------------|
|`KC_INTERNATIONAL_1`|`KC_INT1`|JIS `\` and `_` |
|`KC_INTERNATIONAL_2`|`KC_INT2`|JIS Katakana/Hiragana|
|`KC_INTERNATIONAL_3`|`KC_INT3`|JIS `¥` and `\|` |
|`KC_INTERNATIONAL_4`|`KC_INT4`|JIS Henkan |
|`KC_INTERNATIONAL_5`|`KC_INT5`|JIS Muhenkan |
|`KC_INTERNATIONAL_6`|`KC_INT6`|JIS Numpad `,` |
|`KC_INTERNATIONAL_7`|`KC_INT7`|International 7 |
|`KC_INTERNATIONAL_8`|`KC_INT8`|International 8 |
|`KC_INTERNATIONAL_9`|`KC_INT9`|International 9 |
|`KC_LANGUAGE_1` |`KC_LNG1`|Hangul/English |
|`KC_LANGUAGE_2` |`KC_LNG2`|Hanja |
|`KC_LANGUAGE_3` |`KC_LNG3`|JIS Katakana |
|`KC_LANGUAGE_4` |`KC_LNG4`|JIS Hiragana |
|`KC_LANGUAGE_5` |`KC_LNG5`|JIS Zenkaku/Hankaku |
|`KC_LANGUAGE_6` |`KC_LNG6`|Language 6 |
|`KC_LANGUAGE_7` |`KC_LNG7`|Language 7 |
|`KC_LANGUAGE_8` |`KC_LNG8`|Language 8 |
|`KC_LANGUAGE_9` |`KC_LNG9`|Language 9 |
## Commands
|Key |Aliases |Description |
|------------------|------------------------------|--------------------------------------|
|`KC_PSCREEN` |`KC_PSCR` |Print Screen |
|`KC_PAUSE` |`KC_PAUS`, `KC_BRK`, `KC_BRMU`|Pause, Brightness Up (macOS) |
|`KC_INSERT` |`KC_INS` |Insert |
|`KC_HOME` | |Home |
|`KC_PGUP` | |Page Up |
|`KC_DELETE` |`KC_DEL` |Forward Delete |
|`KC_END` | |End |
|`KC_PGDOWN` |`KC_PGDN` |Page Down |
|`KC_RIGHT` |`KC_RGHT` |Right Arrow |
|`KC_LEFT` | |Left Arrow |
|`KC_DOWN` | |Down Arrow |
|`KC_UP` | |Up Arrow |
|`KC_APPLICATION` |`KC_APP` |Application (Windows Context Menu Key)|
|`KC_POWER` | |System Power |
|`KC_EXECUTE` |`KC_EXEC` |Execute |
|`KC_HELP` | |Help |
|`KC_MENU` | |Menu |
|`KC_SELECT` |`KC_SLCT` |Select |
|`KC_STOP` | |Stop |
|`KC_AGAIN` |`KC_AGIN` |Again |
|`KC_UNDO` | |Undo |
|`KC_CUT` | |Cut |
|`KC_COPY` | |Copy |
|`KC_PASTE` |`KC_PSTE` |Paste |
|`KC_FIND` | |Find |
|`KC__MUTE` | |Mute |
|`KC__VOLUP` | |Volume Up |
|`KC__VOLDOWN` | |Volume Down |
|`KC_ALT_ERASE` |`KC_ERAS` |Alternate Erase |
|`KC_SYSREQ` | |SysReq/Attention |
|`KC_CANCEL` | |Cancel |
|`KC_CLEAR` |`KC_CLR` |Clear |
|`KC_PRIOR` | |Prior |
|`KC_RETURN` | |Return |
|`KC_SEPARATOR` | |Separator |
|`KC_OUT` | |Out |
|`KC_OPER` | |Oper |
|`KC_CLEAR_AGAIN` | |Clear/Again |
|`KC_CRSEL` | |CrSel/Props |
|`KC_EXSEL` | |ExSel |
|Key |Aliases |Description |
|--------------------|------------------------------|--------------------------------------|
|`KC_PRINT_SCREEN` |`KC_PSCR` |Print Screen |
|`KC_PAUSE` |`KC_PAUS`, `KC_BRK`, `KC_BRMU`|Pause, Brightness Up (macOS) |
|`KC_INSERT` |`KC_INS` |Insert |
|`KC_HOME` | |Home |
|`KC_PAGE_UP` |`KC_PGUP` |Page Up |
|`KC_DELETE` |`KC_DEL` |Forward Delete |
|`KC_END` | |End |
|`KC_PAGE_DOWN` |`KC_PGDN` |Page Down |
|`KC_RIGHT` |`KC_RGHT` |Right Arrow |
|`KC_LEFT` | |Left Arrow |
|`KC_DOWN` | |Down Arrow |
|`KC_UP` | |Up Arrow |
|`KC_APPLICATION` |`KC_APP` |Application (Windows Context Menu Key)|
|`KC_KB_POWER` | |System Power |
|`KC_EXECUTE` |`KC_EXEC` |Execute |
|`KC_HELP` | |Help |
|`KC_MENU` | |Menu |
|`KC_SELECT` |`KC_SLCT` |Select |
|`KC_STOP` | |Stop |
|`KC_AGAIN` |`KC_AGIN` |Again |
|`KC_UNDO` | |Undo |
|`KC_CUT` | |Cut |
|`KC_COPY` | |Copy |
|`KC_PASTE` |`KC_PSTE` |Paste |
|`KC_FIND` | |Find |
|`KC_KB_MUTE` | |Mute |
|`KC_KB_VOLUME_UP` | |Volume Up |
|`KC_KB_VOLUME_DOWN` | |Volume Down |
|`KC_ALTERNATE_ERASE`|`KC_ERAS` |Alternate Erase |
|`KC_SYSTEM_REQUEST` |`KC_SYRQ` |SysReq/Attention |
|`KC_CANCEL` |`KC_CNCL` |Cancel |
|`KC_CLEAR` |`KC_CLR` |Clear |
|`KC_PRIOR` |`KC_PRIR` |Prior |
|`KC_RETURN` |`KC_RETN` |Return |
|`KC_SEPARATOR` |`KC_SEPR` |Separator |
|`KC_OUT` | |Out |
|`KC_OPER` | |Oper |
|`KC_CLEAR_AGAIN` |`KC_CLAG` |Clear/Again |
|`KC_CRSEL` |`KC_CRSL` |CrSel/Props |
|`KC_EXSEL` |`KC_EXSL` |ExSel |
## Media Keys

4
docs/keymap.md
View file

@ -105,7 +105,7 @@ At the top of the file you'll find this:
#include QMK_KEYBOARD_H
// Helpful defines
#define GRAVE_MODS (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
#define GRAVE_MODS (MOD_BIT(KC_LSFT)|MOD_BIT(KC_RSFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* You can use _______ in place for KC_TRNS (transparent) *
@ -164,7 +164,7 @@ Our function layer is, from a code point of view, no different from the base lay
[_FL] = LAYOUT(
KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, _______, KC_DEL, BL_STEP, \
_______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SLCK, KC_PAUS, _______, _______, _______, _______, \
_______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SCRL, KC_PAUS, _______, _______, _______, _______, \
_______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, \
_______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, KC_PGUP, \
_______, _______, _______, _______, _______,_______, _______, _______, _______, MO(_FL), KC_HOME, KC_PGDN, KC_END),

71
docs/mod_tap.md
View file

@ -61,6 +61,77 @@ You may also run into issues when using Remote Desktop Connection on Windows. Be
To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
It can also be mitigated by increasing [`TAP_CODE_DELAY`](config_options.md#behaviors-that-can-be-configured).
## Intercepting Mod-Taps
### Changing tap function
The basic keycode limitation with Mod-Tap can be worked around by intercepting it in `process_record_user`. For example, shifted keycode `KC_DQUO` cannot be used with `MT()` because it is a 16-bit keycode alias of `LSFT(KC_QUOT)`. Modifiers on `KC_DQUO` will be masked by `MT()`. But the following custom code can be used to intercept the "tap" function to manually send `KC_DQUO`:
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case LCTL_T(KC_DQUO):
if (record->tap.count && record->event.pressed) {
tap_code16(KC_DQUO); // Send KC_DQUO on tap
return false; // Return false to ignore further processing of key
}
break;
}
return true;
}
```
### Changing hold function
Likewise, similar custom code can also be used to intercept the hold function to send custom user key code. The following example uses `LT(0, kc)` (layer-tap key with no practical use because layer 0 is always active) to add cut, copy and paste function to X,C and V keys when they are held down:
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case LT(0,KC_X):
if (!record->tap.count && record->event.pressed) {
tap_code16(C(KC_X)); // Intercept hold function to send Ctrl-X
return false;
}
return true; // Return true for normal processing of tap keycode
case LT(0,KC_C):
if (!record->tap.count && record->event.pressed) {
tap_code16(C(KC_C)); // Intercept hold function to send Ctrl-C
return false;
}
return true; // Return true for normal processing of tap keycode
case LT(0,KC_V):
if (!record->tap.count && record->event.pressed) {
tap_code16(C(KC_V)); // Intercept hold function to send Ctrl-V
return false;
}
return true; // Return true for normal processing of tap keycode
}
return true;
}
```
Enabling `IGNORE_MOD_TAP_INTERRUPT` is recommended when using Mod-Tap on alphanumeric keys to avoid hold function taking precendence when the next key is pressed quickly. See [Ignore Mod Tap Interrupt](tap_hold.md#ignore-mod-tap-interrupt) for more details.
### Changing both tap and hold
This last example implements custom tap and hold function with `LT(0,KC_NO)` to create a single copy-on-tap, paste-on-hold key:
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case LT(0,KC_NO):
if (record->tap.count && record->event.pressed) {
tap_code16(C(KC_C)); // Intercept tap function to send Ctrl-C
} else if (record->event.pressed) {
tap_code16(C(KC_V)); // Intercept hold function to send Ctrl-V
}
return false;
}
return true;
}
```
## Other Resources
See the [Tap-Hold Configuration Options](tap_hold.md) for additional flags that tweak Mod-Tap behavior.

2
docs/newbs_getting_started.md
View file

@ -194,7 +194,7 @@ You can also set your default keymap name. Most people use their GitHub username
qmk config user.keymap=<github_username>
After this you can leave those arguments off and compile your keyboard like this:
The keyboard can now be compiled without arguments using the following command after creating your keymap in the next section:
qmk compile

65
docs/pr_checklist.md
View file

@ -4,31 +4,33 @@ This is a non-exhaustive checklist of what the QMK Collaborators will be checkin
If there are any inconsistencies with these recommendations, you're best off [creating an issue](https://github.com/qmk/qmk_firmware/issues/new) against this document, or getting in touch with a QMK Collaborator on [Discord](https://discord.gg/Uq7gcHh).
## General PRs
## Requirements for all PRs
- PR should be submitted using a non-`master` branch on the source repository
- this does not mean you target a different branch for your PR, rather that you're not working out of your own master branch
- if submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](https://docs.qmk.fm/#/newbs_git_using_your_master_branch) page after merging -- (end of this document will contain the contents of the message)
- newly-added directories and filenames must be lowercase
- this rule may be relaxed if upstream sources originally had uppercase characters (e.g. ChibiOS, or imported files from other repositories etc.)
- if there is enough justification (i.e. consistency with existing core files etc.) this can be relaxed
- this rule may be relaxed if upstream sources originally had uppercase characters (e.g. LUFA, ChibiOS, or imported files from other repositories etc.)
- if there is valid justification (i.e. consistency with existing core files etc.) this can be relaxed
- a board designer naming their keyboard with uppercase letters is not enough justification
- valid license headers on all `*.c` and `*.h` source files
- GPL2/GPL3 recommended for consistency
- an example GPL2+ license header may be copied and modified from the bottom of this document
- other licenses are permitted, however they must be GPL-compatible and must allow for redistribution. Using a different license will almost certainly delay a PR getting merged.
- missing license headers will prevent PR merge due to ambiguity with license compatibility
- QMK Codebase "best practices" followed
- this is not an exhaustive list, and will likely get amended as time goes by
- `#pragma once` instead of `#ifndef` include guards in header files
- no "old-school" GPIO/I2C/SPI functions used -- must use QMK abstractions unless justifiable (and laziness is not valid justification)
- no "old-school" or other low-level GPIO/I2C/SPI functions may be used -- must use QMK abstractions unless justifiable (and laziness is not valid justification)
- timing abstractions should be followed too:
- `wait_ms()` instead of `_delay_ms()` (remove `#include <util/delay.h>` too)
- `timer_read()` and `timer_read32()` etc. -- see [timer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/timer.h) for the timing APIs
- `timer_read()` and `timer_read32()` etc. -- see [timer.h](https://github.com/qmk/qmk_firmware/blob/master/platforms/timer.h) for the timing APIs
- if you think a new abstraction is useful, you're encouraged to:
- prototype it in your own keyboard until it's feature-complete
- discuss it with QMK Collaborators on Discord
- refactor it as a separate core change
- remove your specific copy in your board
- rebase and fix all merge conflicts before opening the PR (in case you need help or advice, reach out to QMK Collaborators on Discord)
- fix all merge conflicts before opening the PR (in case you need help or advice, reach out to QMK Collaborators on Discord)
## Keymap PRs
@ -48,11 +50,13 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
- valid maintainer
- displays correctly in Configurator (press Ctrl+Shift+I to preview local file, turn on fast input to verify ordering)
- `readme.md`
- standard template should be present
- flash command has `:flash` at end
- standard template should be present -- [link to template](https://github.com/qmk/qmk_firmware/blob/master/data/templates/avr/readme.md)
- flash command is present, and has `:flash` at end
- valid hardware availability link (unless handwired) -- private groupbuys are okay, but one-off prototypes will be questioned. If open-source, a link to files should be provided.
- clear instructions on how to reset the board into bootloader mode
- a picture about the keyboard and preferably about the PCB, too
- images are not to be placed in the `qmk_firmware` repository
- images should be uploaded to an external image hosting service, such as [imgur](https://imgur.com/).
- `rules.mk`
- removed `MIDI_ENABLE`, `FAUXCLICKY_ENABLE` and `HD44780_ENABLE`
- modified `# Enable Bluetooth with the Adafruit EZ-Key HID` -> `# Enable Bluetooth`
@ -69,20 +73,20 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
- initialisation code for the matrix and critical devices
- mirroring existing functionality of a commercial board (like custom keycodes and special animations etc.) should be handled through non-`default` keymaps
- Vial-related files or changes will not be accepted, as they are not used by QMK firmware (no Vial-specific core code has been submitted or merged)
- `keyboard.c`
- `<keyboard>.c`
- empty `xxxx_xxxx_kb()` or other weak-defined default implemented functions removed
- commented-out functions removed too
- `matrix_init_board()` etc. migrated to `keyboard_pre_init_kb()`, see: [keyboard_pre_init*](https://docs.qmk.fm/#/custom_quantum_functions?id=keyboard_pre_init_-function-documentation)
- prefer `CUSTOM_MATRIX = lite` if custom matrix used, allows for standard debounce, see [custom matrix 'lite'](https://docs.qmk.fm/#/custom_matrix?id=lite)
- prefer LED indicator [Configuration Options](https://docs.qmk.fm/#/feature_led_indicators?id=configuration-options) to custom `led_update_*()` implementations where possible
- `keyboard.h`
- `<keyboard>.h`
- `#include "quantum.h"` appears at the top
- `LAYOUT` macros should use standard definitions if applicable
- use the Community Layout macro names where they apply (preferred above `LAYOUT`/`LAYOUT_all`)
- keymap `config.h`
- no duplication of `rules.mk` or `config.h` from keyboard
- `keymaps/default/keymap.c`
- `QMKBEST`/`QMKURL` removed (sheesh)
- `QMKBEST`/`QMKURL` removed
- if using `MO(_LOWER)` and `MO(_RAISE)` keycodes or equivalent, and the keymap has an adjust layer when holding both keys -- if the keymap has no "direct-to-adjust" keycode (such as `MO(_ADJUST)`) then you should prefer to write...
```
layer_state_t layer_state_set_user(layer_state_t state) {
@ -97,7 +101,9 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
- submitters can have a personal (or bells-and-whistles) keymap showcasing capabilities in the same PR but it shouldn't be embedded in the 'default' keymap
- submitters can also have a "manufacturer-matching" keymap that mirrors existing functionality of the commercial product, if porting an existing board
- Do not include VIA json files in the PR. These do not belong in the QMK repository as they are not used by QMK firmware -- they belong in the [VIA Keyboard Repo](https://github.com/the-via/keyboards)
- Do not include source files from another keyboard or vendors keyboard folder. Including core files is fine.
- For instance, only `wilba_tech` boards using be including `keyboards/wilba_tech/wt_main.c` and `keyboards/wilba_tech/wt_rgb_backlight.c`. But including `drivers/sensors/pmw3360.c` is absolutely fine.
- Code that needs to be used by multiple boards is a candidate for core code changes, and should be separated out.
Also, specific to ChibiOS:
- **strong** preference to using existing ChibiOS board definitions.
@ -112,7 +118,11 @@ Also, specific to ChibiOS:
## Core PRs
- must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline
- other notes TBD
- any support for new hardware now requires a corresponding test board under `keyboards/handwired/onekey`
- for new MCUs, a new "child" keyboard should be added that targets your newly-added MCU, so that builds can be verified
- for new hardware support such as display panels, core-side matrix implementations, or other peripherals, an associated keymap should be provided
- if an existing keymap exists that can leverage this functionality this may not be required (e.g. a new RGB driver chip, supported by the `rgb` keymap) -- consult with the QMK Collaborators on Discord to determine if there is sufficient overlap already
- other requirements are at the discretion of QMK collaborators
- core is a lot more subjective given the breadth of posted changes
---
@ -134,6 +144,33 @@ Thanks for contributing!
## Review Process
In general, we want to see two (or more) approvals that are meaningful (e.g. that have inspected code) before a PR will be considered for merge. These reviews are not limited to collaborators -- any community member willing to put in the time is welcomed (and encouraged). The only difference is that your checkmark won't be green, and that's fine!
In general, we want to see two (or more) approvals that are meaningful (e.g. that have inspected code) before a PR will be considered for merge. These reviews are not limited to collaborators -- any community member willing to put in the time is welcomed (and encouraged). The only difference is that your checkmark won't be green, and that's fine!
Additionally, PR reviews are something that is done in our free time. We are not paid nor compensated for the time we spend reviewing, as it is a labor of love. As such, this means that it can take time for us to get to your Pull Request. Things like family, or life can get in the way of us getting to PRs, and burnout is a serious concern. The QMK firmware repository averages 200 PRs opened and 200 PRs merged every month, so please have patience.
## Example GPLv2 Header
```
/* Copyright 2021 Your Name (@yourgithub)
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
```
Or, optionally, using [SPDX identifier](https://spdx.org/licenses/) instead:
```
// Copyright 2021 Your Name (@yourgithub)
// SPDX-License-Identifier: GPL-2.0-or-later
```

2
docs/reference_configurator_support.md
View file

@ -168,7 +168,7 @@ k33 | {"label":"Enter", "x":3, "y":3, "h":2}
k40 | {"label":"0", "x":0, "y":4, "w":2}
k42 | {"label":".", "x":2, "y":4}
When a user selects the top-left key in the Configurator, and assigns Num Lock to it, the Configurator builds a keymap file with `KC_NLCK` as the first key, and so on as the keymap is built. The `label` keys are not used; they are only for the user's reference in identifying specific keys when debugging the `info.json` file.
When a user selects the top-left key in the Configurator, and assigns Num Lock to it, the Configurator builds a keymap file with `KC_NUM` as the first key, and so on as the keymap is built. The `label` keys are not used; they are only for the user's reference in identifying specific keys when debugging the `info.json` file.
## Issues and Hazards

94
docs/reference_info_json.md
View file

@ -9,33 +9,39 @@ You can create `info.json` files at every level under `qmk_firmware/keyboards/<n
The `info.json` file is a JSON formatted dictionary with the following keys available to be set. You do not have to set all of them, merely the keys that apply to your keyboard.
* `keyboard_name`
* A free-form text string describing the keyboard.
* Example: `Clueboard 66%`
* A free-form text string describing the keyboard.
* Example: `Clueboard 66%`
* `manufacturer`
* A free-form text string describing the keyboard's manufacturer.
* Example: `Clueboard`
* `url`
* A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard.
* A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard.
* Example: `https://clueboard.co`
* `maintainer`
* GitHub username of the maintainer, or `qmk` for community maintained boards
* GitHub username of the maintainer, or `qmk` for community maintained boards.
* Example: `skullydazed`
* `debounce`
* How many milliseconds (ms) to wait for debounce to happen. (Default: 5)
* The amount of time in milliseconds to wait for debounce to happen.
* Default: `5`
* `diode_direction`
* The direction diodes face. See [`DIRECT_PINS` in the hardware configuration](https://docs.qmk.fm/#/config_options?id=hardware-options) for more details.
* The direction diodes face. See [`DIRECT_PINS` in the hardware configuration](https://docs.qmk.fm/#/config_options?id=hardware-options) for more details.
* `layout_aliases`
* A dictionary containing layout aliases. The key is the alias and the value is a layout in `layouts` it maps to.
* A dictionary containing layout aliases. The key is the alias and the value is a layout in `layouts` it maps to.
* `layouts`
* Physical Layout representations. See the [Layout Format](#layout_format) section for more detail.
* Physical Layout representations. See the [Layout Format](#layout_format) section for more detail.
* `matrix_pins`
* Configure the pins corresponding to columns and rows, or direct pins. See [Matrix Pins](#matrix_pins) for more detail.
* Configure the pins corresponding to columns and rows, or direct pins. See the [Matrix Pins](#matrix_pins) section for more detail.
* `rgblight`
* Configure the [RGB Lighting feature](feature_rgblight.md). See the [RGB Lighting](#rgb_lighting) section for more detail.
* Configure the [RGB Lighting feature](feature_rgblight.md). See the [RGB Lighting](#rgb_lighting) section for more detail.
* `usb`
* Configure USB VID, PID, and other parameters. See [USB](#USB) for more detail.
* Configure USB VID, PID, and other parameters. See the [USB](#USB) section for more detail.
### Layout Format
Within our `info.json` file the `layouts` portion of the dictionary contains several nested dictionaries. The outer layer consists of QMK layout macros, for example `LAYOUT_ansi` or `LAYOUT_iso`.
* `layout`
* A list of Key Dictionaries describing the physical layout. See the next section for more details.
* A list of Key Dictionaries describing the physical layout. See the next section for more details.
### Key Dictionary Format
@ -44,18 +50,20 @@ Each Key Dictionary in a layout describes the physical properties of a key. If y
All key positions and rotations are specified in relation to the top-left corner of the keyboard, and the top-left corner of each key.
* `x`
* **Required**: The absolute position of the key in the horizontal axis, in Key Units.
* **Required**. The absolute position of the key in the horizontal axis, in Key Units.
* `y`
* **Required**: The absolute position of the key in the vertical axis, in Key Units.
* **Required**. The absolute position of the key in the vertical axis, in Key Units.
* `w`
* The width of the key, in Key Units. Ignored if `ks` is provided. Default: `1`
* The width of the key, in Key Units.
* Default: `1`
* `h`
* The height of the key, in Key Units. Ignored if `ks` is provided. Default: `1`
* The height of the key, in Key Units.
* Default: `1`
* `label`
* What to name this position in the matrix.
* This should usually correspond to the keycode for the first layer of the default keymap.
* What to name this position in the matrix. This should usually correspond to the keycode for the first layer of the default keymap.
* `matrix`
* A 2 item list describing the row and column location for this key.
* A two item list describing the row and column location for this key.
* Example: `[0, 4]`
### Matrix Pins
@ -69,11 +77,11 @@ Example:
```json
{
"diode_direction": "COL2ROW",
"matrix_pins": {
"cols": ["F4", "E6", "B1", "D2"],
"rows": ["B0", "D3", "D5", "D4", "D6"]
}
"diode_direction": "COL2ROW",
"matrix_pins": {
"cols": ["F4", "E6", "B1", "D2"],
"rows": ["B0", "D3", "D5", "D4", "D6"]
}
}
```
@ -144,23 +152,23 @@ Example:
}
```
#### RGB Light Animations
#### RGBLight Animations
The following animations can be enabled:
| Key | Description |
|-----|-------------|
| `all` | Enable all additional animation modes. |
| `alternating` | Enable alternating animation mode. |
| `breathing` | Enable breathing animation mode. |
| `christmas` | Enable christmas animation mode. |
| `knight` | Enable knight animation mode. |
| `rainbow_mood` | Enable rainbow mood animation mode. |
| `rainbow_swirl` | Enable rainbow swirl animation mode. |
| `rgb_test` | Enable RGB test animation mode. |
| `snake` | Enable snake animation mode. |
| `static_gradient` | Enable static gradient mode. |
| `twinkle` | Enable twinkle animation mode. |
|Key |Description |
|-----------------|--------------------------------------|
|`all` |Enable all additional animation modes.|
|`alternating` |Enable alternating animation mode. |
|`breathing` |Enable breathing animation mode. |
|`christmas` |Enable christmas animation mode. |
|`knight` |Enable knight animation mode. |
|`rainbow_mood` |Enable rainbow mood animation mode. |
|`rainbow_swirl` |Enable rainbow swirl animation mode. |
|`rgb_test` |Enable RGB test animation mode. |
|`snake` |Enable snake animation mode. |
|`static_gradient`|Enable static gradient mode. |
|`twinkle` |Enable twinkle animation mode. |
### USB
@ -170,10 +178,10 @@ Example:
```json
{
"usb": {
"vid": "0xC1ED",
"pid": "0x23B0",
"device_ver": "0x0001"
}
"usb": {
"vid": "0xC1ED",
"pid": "0x23B0",
"device_ver": "0x0001"
}
}
```

1
docs/ru-ru/getting_started_github.md
View file

@ -31,7 +31,6 @@ Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca
Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
```
Теперь у вас есть форк QMK на вашем локальном компьютере, и вы можете добавить свою раскладку, скомпилировать ее и прошить ей свою клавиатуру. Как только вы будете довольны своими изменениями, есть возможность добавить, зафиксировать их и сделать коммит в свой форк следующим образом:

180
docs/squeezing_avr.md Normal file
View file

@ -0,0 +1,180 @@
# Squeezing the most out of AVR
AVR is severely resource-constrained, and as QMK continues to grow, it is approaching a point where support for AVR may need to be moved to legacy status as newer development is unable to fit into those constraints.
However, if you need to reduce the compiled size of your firmware, there are a number of options to do so.
## `rules.mk` Settings
First and foremost is enabling link time optimization. To do so, add this to your rules.mk:
```make
LTO_ENABLE = yes
```
This will cause the final step to take longer, but should get you a smaller compiled size. This also disables Action Functions, and Action Macros, both of which are deprecated.
This will get you the most savings, in most situations.
From there, disabling extraneous systems will help -- e.g.:
```make
CONSOLE_ENABLE = no
COMMAND_ENABLE = no
MOUSEKEY_ENABLE = no
EXTRAKEY_ENABLE = no
```
This disables some of the functionality that you may not need. But note that extrakeys disables stuff like the media keys and system volume control.
If that isn't enough to get your firmware down to size, then there are some additional features that you can disable:
```make
SPACE_CADET_ENABLE = no
GRAVE_ESC_ENABLE = no
MAGIC_ENABLE = no
```
These features are enabled by default, but may not be needed. Double check to make sure, though.
Largest in size is "magic" -- the QMK magic keycodes -- which control things like NKRO toggling, GUI and ALT/CTRL swapping, etc. Disabling it will disable those functions.
## `config.h` Settings
If you've done all of that, and you don't want to disable features like RGB, Audio, OLEDs, etc, there are some additional options that you can add to your config.h that can help.
Starting with Lock Key support. If you have an Cherry MX Lock switch (lucky you!), you don't want to do this. But chances are, you don't. In that case, add this to your `config.h`:
```c
#undef LOCKING_SUPPORT_ENABLE
#undef LOCKING_RESYNC_ENABLE
```
Oneshots. If you're not using these, you can disable the feature by adding this to your `config.h`:
```c
#define NO_ACTION_ONESHOT
```
The same with tapping keys (mod tap, layer tap, etc)
```c
#define NO_ACTION_TAPPING
```
## Audio Settings
If you're using the Audio feature, by default that includes the music mode feature. This tranlates matrix positions into notes. It's neat for sure, but most likely, you're not using it. You can disable it by adding this to your `config.h`:
```c
#define NO_MUSIC_MODE
```
And by adding this to your `rules.mk`
```make
MUSIC_ENABLE = no
```
## Layers
There are also some options for layers, that can reduce the firmware size. All of these settngs are for your `config.h`.
You can limit the number of layers that the firmware uses -- if you're using less than 8 layers in total:
```c
#define LAYER_STATE_8BIT
```
or if you require up to 16 layers instead:
```c
#define LAYER_STATE_16BIT
```
Or if you're not using layers at all, you can outright remove the functionality altogether:
```c
#define NO_ACTION_LAYER
```
## OLED tweaks
One place you can save a bunch of space here is by not using `sprintf` or `snprintf`. This function call takes up ~1.5kB of firmware space, and can be rewritten. For instance, WPM uses this a lot.
You can convert this:
```c
// OLD CODE
char wpm_str[4] = {0};
sprintf(wpm_str, "WPM: %03d", get_current_wpm());
oled_write(wpm_str, ' '), false);
```
into this:
```c
// NEW CODE
oled_write_P(PSTR("WPM: "), false);
oled_write(get_u8_str(get_current_wpm(), ' '), false);
```
which outputs `WPM: 5`. Or this:
```c
// NEW CODE
oled_write_P(PSTR("WPM: "), false);
oled_write(get_u8_str(get_current_wpm(), '0'), false);
```
which outputs `WPM: 005`.
## RGB Settings
If you're using RGB on your board, both RGB Light (Underglow) and RGB Matrix (per key RGB) now require defines to enable different animations -- some keyboards enable a lot of animations by default, so you can generally gain back some space by disabling specific animations if you don't use them.. For RGB Light you can disable these in your keymap's `config.h`:
```c
#undef RGBLIGHT_ANIMATIONS
#undef RGBLIGHT_EFFECT_BREATHING
#undef RGBLIGHT_EFFECT_RAINBOW_MOOD
#undef RGBLIGHT_EFFECT_RAINBOW_SWIRL
#undef RGBLIGHT_EFFECT_SNAKE
#undef RGBLIGHT_EFFECT_KNIGHT
#undef RGBLIGHT_EFFECT_CHRISTMAS
#undef RGBLIGHT_EFFECT_STATIC_GRADIENT
#undef RGBLIGHT_EFFECT_RGB_TEST
#undef RGBLIGHT_EFFECT_ALTERNATING
#undef RGBLIGHT_EFFECT_TWINKLE
```
For RGB Matrix, these need to be explicitly enabled as well. To disable any that were enabled by the keyboard, add one or more of these to your keymap's `config.h`:
```c
#undef ENABLE_RGB_MATRIX_ALPHAS_MODS
#undef ENABLE_RGB_MATRIX_GRADIENT_UP_DOWN
#undef ENABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT
#undef ENABLE_RGB_MATRIX_BREATHING
#undef ENABLE_RGB_MATRIX_BAND_SAT
#undef ENABLE_RGB_MATRIX_BAND_VAL
#undef ENABLE_RGB_MATRIX_BAND_PINWHEEL_SAT
#undef ENABLE_RGB_MATRIX_BAND_PINWHEEL_VAL
#undef ENABLE_RGB_MATRIX_BAND_SPIRAL_SAT
#undef ENABLE_RGB_MATRIX_BAND_SPIRAL_VAL
#undef ENABLE_RGB_MATRIX_CYCLE_ALL
#undef ENABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT
#undef ENABLE_RGB_MATRIX_CYCLE_UP_DOWN
#undef ENABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON
#undef ENABLE_RGB_MATRIX_CYCLE_OUT_IN
#undef ENABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL
#undef ENABLE_RGB_MATRIX_CYCLE_PINWHEEL
#undef ENABLE_RGB_MATRIX_CYCLE_SPIRAL
#undef ENABLE_RGB_MATRIX_DUAL_BEACON
#undef ENABLE_RGB_MATRIX_RAINBOW_BEACON
#undef ENABLE_RGB_MATRIX_RAINBOW_PINWHEELS
#undef ENABLE_RGB_MATRIX_RAINDROPS
#undef ENABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS
#undef ENABLE_RGB_MATRIX_HUE_BREATHING
#undef ENABLE_RGB_MATRIX_HUE_PENDULUM
#undef ENABLE_RGB_MATRIX_HUE_WAVE
#undef ENABLE_RGB_MATRIX_PIXEL_FRACTAL
#undef ENABLE_RGB_MATRIX_PIXEL_RAIN
#undef ENABLE_RGB_MATRIX_TYPING_HEATMAP
#undef ENABLE_RGB_MATRIX_DIGITAL_RAIN
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS
#undef ENABLE_RGB_MATRIX_SPLASH
#undef ENABLE_RGB_MATRIX_MULTISPLASH
#undef ENABLE_RGB_MATRIX_SOLID_SPLASH
#undef ENABLE_RGB_MATRIX_SOLID_MULTISPLASH
```
# Final Thoughts
If you've done all of this, and your firmware is still too large, then it's time. It's time to consider making the switch to ARM. Unfortunately, right now is the worst possible time for that, due to the silicon shortage, and supply chain issues. Getting an ARM chip is difficult, at best, and significantly overpriced, at worst.
-- Drashna
That said, there are a number of Pro Micro replacements with ARM controllers:
* [Proton C](https://qmk.fm/proton-c/) (out of stock)
* [Bonsai C](https://github.com/customMK/Bonsai-C) (Open Source, DIY/PCBA)
* [Raspberry Pi 2040](https://www.sparkfun.com/products/18288) (not currently supported, no ETA)
There are other, non-Pro Micro compatible boards out there. The most popular being:
* [WeAct Blackpill F411](https://www.aliexpress.com/item/1005001456186625.html) (~$6 USD)

1
docs/syllabus.md
View file

@ -31,6 +31,7 @@ These topics start to dig into some of the features that QMK supports. You don't
* [RGB Lighting](feature_rgblight.md)
* [RGB Matrix](feature_rgb_matrix.md)
* [Tap-Hold Configuration](tap_hold.md)
* [Squeezing Space from AVR](squeezing_avr.md)
* **Learn More About Keymaps**
* [Keymaps](keymap.md)
* [Custom Functions and Keycodes](custom_quantum_functions.md)

92
docs/tap_hold.md
View file

@ -6,7 +6,9 @@ These options let you modify the behavior of the Tap-Hold keys.
## Tapping Term
The crux of all of the following features is the tapping term setting. This determines what is a tap and what is a hold. And the exact timing for this to feel natural can vary from keyboard to keyboard, from switch to switch, and from key to key.
The crux of all of the following features is the tapping term setting. This determines what is a tap and what is a hold. The exact timing for this to feel natural can vary from keyboard to keyboard, from switch to switch, and from key to key.
?> `DYNAMIC_TAPPING_TERM_ENABLE` enables three special keys that can help you quickly find a comfortable tapping term for you. See "Dynamic Tapping Term" for more details.
You can set the global time for this by adding the following setting to your `config.h`:
@ -36,6 +38,82 @@ uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
}
```
### Dynamic Tapping Term :id=dynamic-tapping-term
`DYNAMIC_TAPPING_TERM_ENABLE` is a feature you can enable in `rules.mk` that lets you use three special keys in your keymap to configure the tapping term on the fly.
| Key | Description |
|-------------|------------------------------------------------------------------------------------------------------------------------|
| `DT_PRNT` | "Dynamic Tapping Term Print": Types the current tapping term, in milliseconds |
| `DT_UP` | "Dynamic Tapping Term Up": Increases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) |
| `DT_DOWN` | "Dynamic Tapping Term Down": Decreases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) |
Set the tapping term as usual with `#define TAPPING_TERM <value>` in `config.h` and add `DYNAMIC_TAPPING_TERM_ENABLE = yes` in `rules.mk`. Then, place the above three keys somewhere in your keymap and flash the new firmware onto your board.
Now, you can try using your dual-role keys, such as layer-taps and mod-taps, and use `DT_DOWN` and `DT_UP` to adjust the tapping term immediately. If you find that you frequently trigger the modifier of your mod-tap(s) by accident for example, that's a sign that your tapping term may be too low so tap `DT_UP` a few times to increase the tapping term until that no longer happens. On the flip side, if you get superfluous characters when you actually intended to momentarily activate a layer, tap `DT_DOWN` to lower the tapping term. Do note that these keys affect the *global* tapping term, you cannot change the tapping term of a specific key on the fly.
Once you're satisfied with the current tapping term value, open `config.h` and replace whatever value you first wrote for the tapping term by the output of the `DT_PRNT` key.
It's important to update `TAPPING_TERM` with the new value because the adjustments made using `DT_UP` and `DT_DOWN` are not persistent.
The value by which the tapping term increases or decreases when you tap `DT_UP` and `DT_DOWN` can be configured in `config.h` with `#define DYNAMIC_TAPPING_TERM_INCREMENT <new value>`. Note that the tapping term is *not* modified when holding down the tap term keys so if you need to, for example, decrease the current tapping term by 50ms, you cannot just press down and hold `DT_DOWN`; you will have to tap it 10 times in a row with the default increment of 5ms.
If you need more flexibility, nothing prevents you from defining your own custom keys to dynamically change the tapping term.
```c
enum custom_dynamic_tapping_term_keys = {
DT_UP_50 = SAFE_RANGE,
DT_DOWN_50,
DT_UP_X2,
DT_DOWN_X2,
}
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case DT_UP_50:
if (record->event.pressed) {
g_tapping_term += 50;
}
break;
case DT_DOWN_50:
if (record->event.pressed) {
g_tapping_term -= 50;
}
break;
case DT_UP_X2:
if (record->event.pressed) {
g_tapping_term *= 2;
}
break;
case DT_DOWN_X2:
if (record->event.pressed) {
g_tapping_term /= 2;
}
break;
}
return true;
};
```
In order for this feature to be effective if you use per-key tapping terms, you need to make a few changes to the syntax of the `get_tapping_term` function. All you need to do is replace every occurrence of `TAPPING_TERM` in the `get_tapping_term` function by lowercase `g_tapping_term`. If you don't do that, you will still see the value typed by `DT_PRNT` go up and down as you configure the tapping term on the fly but you won't feel those changes as they don't get applied. If you can go as low as 10ms and still easily trigger the tap function of a dual-role key, that's a sign that you forgot to make the necessary changes to your `get_tapping_term` function.
For instance, here's how the example `get_tapping_term` shown earlier should look like after the transformation:
```c
uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case SFT_T(KC_SPC):
return g_tapping_term + 1250;
case LT(1, KC_GRV):
return 130;
default:
return g_tapping_term;
}
}
```
The reason being that `TAPPING_TERM` is a macro that expands to a constant integer and thus cannot be changed at runtime whereas `g_tapping_term` is a variable whose value can be changed at runtime. If you want, you can temporarily enable `DYNAMIC_TAPPING_TERM_ENABLE` to find a suitable tapping term value and then disable that feature and revert back to using the classic syntax for per-key tapping term settings.
## Tap-Or-Hold Decision Modes
The code which decides between the tap and hold actions of dual-role keys supports three different modes, in increasing order of preference for the hold action:
@ -67,7 +145,7 @@ An example of a sequence which is affected by the “permissive hold” mode:
- `KC_L` Up
- `LT(2, KC_A)` Up
Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `PERMISSIVE_HOLD` option enabled, the Layer Tap key is considered as a layer switch if another key is tapped, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2).
Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `PERMISSIVE_HOLD` option enabled, the Layer Tap key is considered as a layer switch if another key is tapped, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2). We could describe this sequence as a “nested press” (the modified key's key down and key up events are “nested” between the dual-role key's key down and key up events).
However, this slightly different sequence will not be affected by the “permissive hold” mode:
@ -76,7 +154,7 @@ However, this slightly different sequence will not be affected by the “permiss
- `LT(2, KC_A)` Up
- `KC_L` Up
In the sequence above the dual-role key is released before the other key is released, and if that happens within the tapping term, the “permissive hold” mode will still choose the tap action for the dual-role key, and the sequence will be registered as `al` by the host.
In the sequence above the dual-role key is released before the other key is released, and if that happens within the tapping term, the “permissive hold” mode will still choose the tap action for the dual-role key, and the sequence will be registered as `al` by the host. We could describe this as a “rolling press” (the two keys' key down and key up events behave as if you were rolling a ball across the two keys, first pressing each key down in sequence and then releasing them in the same order).
?> The `PERMISSIVE_HOLD` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers both the “nested press” and “rolling press” sequences like shown above as a modifier hold, not the tap action. If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `PERMISSIVE_HOLD` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host.
@ -247,7 +325,7 @@ To enable `retro tapping`, add the following to your `config.h`:
Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term.
For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead.
For instance, holding and releasing `LT(2, KC_SPC)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPC` instead.
For more granular control of this feature, you can add the following to your `config.h`:
@ -260,7 +338,7 @@ You can then add the following function to your keymap:
```c
bool get_retro_tapping(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case LT(2, KC_SPACE):
case LT(2, KC_SPC):
return true;
default:
return false;
@ -268,6 +346,10 @@ bool get_retro_tapping(uint16_t keycode, keyrecord_t *record) {
}
```
### Retro Shift
[Auto Shift,](feature_auto_shift.md) has its own version of `retro tapping` called `retro shift`. It is extremely similar to `retro tapping`, but holding the key past `AUTO_SHIFT_TIMEOUT` results in the value it sends being shifted. Other configurations also affect it differently; see [here](feature_auto_shift.md#retro-shift) for more information.
## Why do we include the key record for the per key functions?
One thing that you may notice is that we include the key record for all of the "per key" functions, and may be wondering why we do that.

38
docs/uart_driver.md
View file

@ -60,30 +60,56 @@ Initialize the UART driver. This function must be called only once, before any o
---
### `void uart_putchar(uint8_t c)`
### `void uart_write(uint8_t data)`
Transmit a single byte.
#### Arguments
- `uint8_t c`
The byte (character) to send, from 0 to 255.
- `uint8_t data`
The byte to write.
---
### `uint8_t uart_getchar(void)`
### `uint8_t uart_read(void)`
Receive a single byte.
#### Return Value
The byte read from the receive buffer.
The byte read from the receive buffer. This function will block if the buffer is empty (ie. no data to read).
---
### `void uart_transmit(const uint8_t *data, uint16_t length)`
Transmit multiple bytes.
#### Arguments
- `const uint8_t *data`
A pointer to the data to write from.
- `uint16_t length`
The number of bytes to write. Take care not to overrun the length of `data`.
---
### `void uart_receive(char *data, uint16_t length)`
Receive multiple bytes.
#### Arguments
- `uint8_t *data`
A pointer to the buffer to read into.
- `uint16_t length`
The number of bytes to read. Take care not to overrun the length of `data`.
---
### `bool uart_available(void)`
Return whether the receive buffer contains data. Call this function to determine if `uart_getchar()` will return meaningful data.
Return whether the receive buffer contains data. Call this function to determine if `uart_read()` will return data immediately.
#### Return Value

33
docs/understanding_qmk.md
View file

@ -4,7 +4,7 @@ This document attempts to explain how the QMK firmware works from a very high le
* [Introduction](getting_started_introduction.md)
* [How Keyboards Work](how_keyboards_work.md)
* [FAQ](faq.md)
* [FAQ](faq_general.md)
## Startup
@ -29,7 +29,6 @@ Within `keyboard_task()` you'll find code to handle:
* [Matrix Scanning](#matrix-scanning)
* Mouse Handling
* Serial Link(s)
* Visualizer
* Keyboard status LEDs (Caps Lock, Num Lock, Scroll Lock)
#### Matrix Scanning
@ -67,10 +66,10 @@ At the keyboard level we define a C macro (typically named `LAYOUT()`) which map
k30, k31, k32, k33, \
k40, k42 \
) { \
{ k00, k01, k02, k03, }, \
{ k10, k11, k12, k13, }, \
{ k20, k21, k22, KC_NO, }, \
{ k30, k31, k32, k33, }, \
{ k00, k01, k02, k03 }, \
{ k10, k11, k12, k13 }, \
{ k20, k21, k22, KC_NO }, \
{ k30, k31, k32, k33 }, \
{ k40, KC_NO, k42, KC_NO } \
}
```
@ -83,14 +82,15 @@ You can also use this macro to handle unusual matrix layouts, for example the [C
At the keymap level we make use of our `LAYOUT()` macro above to map keycodes to physical locations to matrix locations. It looks like this:
```
```c
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT(
KC_NLCK, KC_PSLS, KC_PAST, KC_PMNS, \
KC_P7, KC_P8, KC_P9, KC_PPLS, \
KC_P4, KC_P5, KC_P6, \
KC_P1, KC_P2, KC_P3, KC_PENT, \
KC_P0, KC_PDOT)
[0] = LAYOUT(
KC_NUM, KC_PSLS, KC_PAST, KC_PMNS,
KC_P7, KC_P8, KC_P9, KC_PPLS,
KC_P4, KC_P5, KC_P6,
KC_P1, KC_P2, KC_P3, KC_PENT,
KC_P0, KC_PDOT
)
}
```
@ -124,7 +124,7 @@ And when our current scan completes it will look like this:
}
```
Comparing against our keymap we can see that the pressed key is KC_NLCK. From here we dispatch to the `process_record` set of functions.
Comparing against our keymap we can see that the pressed key is `KC_NUM`. From here we dispatch to the `process_record` set of functions.
<!-- FIXME: Magic happens between here and process_record -->
@ -157,6 +157,7 @@ The `process_record()` function itself is deceptively simple, but hidden within
* [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_combo.c#L115)
* [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_printer.c#L77)
* [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_auto_shift.c#L94)
* `bool process_dynamic_tapping_term(uint16_t keycode, keyrecord_t *record)`
* [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_terminal.c#L264)
* [Identify and process Quantum-specific keycodes](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L291)
@ -180,10 +181,6 @@ FIXME: This needs to be written
FIXME: This needs to be written
#### Visualizer
FIXME: This needs to be written
#### Keyboard state LEDs (Caps Lock, Num Lock, Scroll Lock)
FIXME: This needs to be written

4
docs/unit_testing.md
View file

@ -20,12 +20,12 @@ One thing to remember, is that you have to append `extern "C"` around all of you
## Adding Tests for New or Existing Features
If you want to unit test some feature, then take a look at the existing serial_link tests, in the `quantum/serial_link/tests folder`, and follow the steps below to create a similar structure.
If you want to unit test a feature, take a look at some of the existing tests, for example those in the `quantum/sequencer/tests` folder. Then follow the steps below to create a similar structure.
1. If it doesn't already exist, add a test subfolder to the folder containing the feature.
2. Create a `testlist.mk` and a `rules.mk` file in that folder.
3. Include those files from the root folder `testlist.mk`and `build_test.mk` respectively.
4. Add a new name for your testgroup to the `testlist.mk` file. Each group defined there will be a separate executable. And that's how you can support mocking out different parts. Note that it's worth adding some common prefix, just like it's done for the serial_link tests. The reason for that is that the make command allows substring filtering, so this way you can easily run a subset of the tests.
4. Add a new name for your testgroup to the `testlist.mk` file. Each group defined there will be a separate executable. And that's how you can support mocking out different parts. Note that it's worth adding some common prefix, just like it's done for the existing tests. The reason for that is that the make command allows substring filtering, so this way you can easily run a subset of the tests.
5. Define the source files and required options in the `rules.mk` file.
* `_SRC` for source files
* `_DEFS` for additional defines

13
docs/ws2812_driver.md
View file

@ -49,6 +49,19 @@ WS2812_DRIVER = bitbang
!> This driver is not hardware accelerated and may not be performant on heavily loaded systems.
#### Adjusting bit timings
The WS2812 LED communication topology depends on a serialized timed window. Different versions of the addressable LEDs have differing requirements for the timing parameters, for instance, of the SK6812.
You can tune these parameters through the definition of the following macros:
| Macro |Default | AVR | ARM |
|---------------------|--------------------------------------------|--------------------|--------------------|
|`WS2812_TIMING` |`1250` | :heavy_check_mark: | :heavy_check_mark: |
|`WS2812_T0H` |`350` | :heavy_check_mark: | :heavy_check_mark: |
|`WS2812_T0L` |`WS2812_TIMING - WS2812_T0H` | | :heavy_check_mark: |
|`WS2812_T1H` |`900` | :heavy_check_mark: | :heavy_check_mark: |
|`WS2812_T1L` |`WS2812_TIMING - WS2812_T1H` | | :heavy_check_mark: |
### I2C
Targeting boards where WS2812 support is offloaded to a 2nd MCU. Currently the driver is limited to AVR given the known consumers are ps2avrGB/BMC. To configure it, add this to your rules.mk:

4
docs/zh-cn/custom_quantum_functions.md
View file

@ -275,11 +275,11 @@ void keyboard_post_init_user(void) {
```c
void suspend_power_down_user(void) {
rgb_matrix_set_suspend_state(true);
// code will run multiple times while keyboard is suspended
}
void suspend_wakeup_init_user(void) {
rgb_matrix_set_suspend_state(false);
// code will run on keyboard wakeup
}
```

5
docs/zh-cn/faq_debug.md
View file

@ -81,11 +81,6 @@ Size after:
全键无冲还不好用的话试着用`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复位电路。

2
docs/zh-cn/faq_keymap.md
View file

@ -5,7 +5,7 @@
## 我能用什么键码?
看[键码](keycodes.md)你可以找到你能用的键码索引。可以的话这些链接可以连接到更广泛的文档。
键码实际上定义在[common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
键码实际上定义在[common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h).
## 默认的键码什么样?

1
docs/zh-cn/getting_started_github.md
View file

@ -32,7 +32,6 @@ Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca
Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
```
现在你本地计算机有QMK的分叉了,你可以添加你的布局了, 为你的键盘编译并刷新固件吧。如果你觉得你的修改很不错, 你可以添加,提交,然后想你的分叉推出（pull）你的改变，像这样: