gitbot/qmk_firmware
0
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2024-11-22 03:19:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Deploying to gh-pages from master @ aae3b35c0f 🚀

Browse Source
This commit is contained in:
skullydazed 2020-11-10 15:02:44 +00:00
parent 117d4a338d
commit e9694e7218
375 changed files with 44952 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
.nojekyll Normal file
View File

1
CNAME Normal file
View File

@ -0,0 +1 @@
docs.qmk.fm

53
ChangeLog/20190830.md Normal file
View File

@ -0,0 +1,53 @@
# QMK Breaking Change - 2019 Aug 30
Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
This document marks the inaugural Breaking Change merge. A list of changes follows.
## Core code formatting with clang-format
* All core files (`drivers/`, `quantum/`, `tests/`, and `tmk_core/`) have been formatted with clang-format
* A travis process to reformat PR's on merge has been instituted
* You can use the new CLI command `qmk cformat` to format before submitting your PR if you wish.
## LUFA USB descriptor cleanup
* Some code cleanups related to the USB HID descriptors on AVR keyboards, to make them easier to read and understand
* More information: see https://github.com/qmk/qmk_firmware/pull/4871
* No behaviour changes anticipated and no keymaps modified
## Migrating `ACTION_LAYER_MOMENTARY()` entries in `fn_actions` to `MO()` keycodes
* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
* The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity
* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
## Update Atreus to current code conventions
* Duplicate include guards have bypassed the expected header processing behavior
* All keymaps affected are recommended to remove duplication of `<keyboard>/config.h` to `<keyboard>/keymaps/<user>/config.h` and only provide overrides at the keymap level
## Backport changes to keymap language files from ZSA fork
* Fixes an issue in the `keymap_br_abnt2.h` file that includes the wrong source (`keymap_common.h` instead of `keymap.h`)
* Updates the `keymap_swedish.h` file to be specific to swedish, and not just "nordic" in general.
* Any keymaps using this will need to remove `NO_*` and replace it with `SE_*`.
## Update repo to use LUFA as a git submodule
* `/lib/LUFA` removed from the repo
* LUFA set as a submodule, pointing to qmk/lufa
* This should allow more flexibility with LUFA, and allow us to keep the sub-module up to date, a lot more easily. It was ~2 years out of date with no easy path to fix that. This prevents that from being an issue in the future
## Migrating `ACTION_BACKLIGHT_*()` entries in `fn_actions` to `BL_` keycodes
* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
* All keymaps using these actions have had the relevant `KC_FN*` keys replaced with the equivalent `BL_*` keys
* If you currently use `KC_FN*` you will need to replace `fn_actions` with the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
## Remove `KC_DELT` alias in favor of `KC_DEL`
* `KC_DELT` was a redundant, undocumented alias for `KC_DELETE`
* It has been removed and all its uses replaced with the more common `KC_DEL` alias
* Around 90 keymaps (mostly for ErgoDox boards) have been modified as a result

75
ChangeLog/20200229.md Normal file
View File

@ -0,0 +1,75 @@
# QMK Breaking Change - 2020 Feb 29 Changelog
Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
## Update ChibiOS/ChibiOS-Contrib/uGFX submodules
* General Notes
* A `make git-submodule` may be required after pulling the latest QMK firmware code to update affected submodules to the upgraded revisions
* Enabling link-time-optimization (`LINK_TIME_OPTIMIZATION_ENABLE = yes`) should work on a lot more boards
* Upgrade to ChibiOS ver19.1.3
* This will allow QMK to update to upstream ChibiOS a lot easier -- the old version was ~2 years out of date. Automated update scripts have been made available to simplify future upgrades.
* Includes improved MCU support and bugfixes
* ChibiOS revision is now included in Command output
* Timers should now be more accurate
* Upgrade to newer ChibiOS-Contrib
* Also includes improved MCU support and bugfixes
* ChibiOS-Contrib revision is now included in Command output
* Upgrade to newer uGFX
* Required in order to support updated ChibiOS
## Fix ChibiOS timer overflow for 16-bit SysTick devices
* On 16-bit SysTick devices, the timer subsystem in QMK was incorrectly dealing with overflow.
* When running at a 100000 SysTick frequency (possible on 16-bit devices, but uncommon), this overflow would occur after 0.65 seconds.
* Timers are now correctly handling this overflow case and timing should now be correct on ChibiOS/ARM.
## Update LUFA submodule
* Updates the LUFA submodule to include updates from upstream (abcminiuser/lufa)
* Includes some cleanup for QMK DFU generation
## Encoder flip
* Flips the encoder direction so that `clockwise == true` is for actually turning the knob clockwise
* Adds `ENCODER_DIRECTION_FLIP` define, so that reversing the expected dirction is simple for users.
* Cleans up documentation page for encoders
## Adding support for `BACKLIGHT_ON_STATE` for hardware PWM backlight
* Previously, the define only affected software PWM, and hardware PWM always assumed an N-channel MOSFET.
* The hardware PWM backlight setup has been updated to respect this option.
* The default "on" state has been changed to `1` - **this impacts all keyboards using software PWM backlight that do not define it explicitly**. If your keyboard's backlight is acting strange, it may have a P-channel MOSFET, and will need to have `#define BACKLIGHT_ON_STATE 0` added to the keyboard-level `config.h`. Please see the PR for more detailed information.
## Migrating `ACTION_LAYER_TAP_KEY()` entries in `fn_actions` to `LT()` keycodes
* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
* The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity
* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
## Moving backlight keycode handling to `process_keycode/`
* This refactors the backlight keycode logic to be clearer and more modular.
* All backlight-related keycodes are now actioned in a single file.
* The `ACTION_BACKLIGHT_*` macros have also been deleted. If you are still using these in a `fn_actions[]` block, please switch to using the backlight keycodes or functions directly.
## Refactor Planck keymaps to use Layout Macros
* Refactor Planck keymaps to use layout macros instead of raw matrix assignments
* Makes keymaps revision-agnostic
* Should reduce noise and errors in Travis CI logs
## GON NerD codebase refactor
* Splits the codebase for GON NerD 60 and NerdD TKL PCBs into two separate directories.
* If your keymap is for a NerD 60 PCB, your `make` command is now `make gon/nerd60:<keymap>`.
* If your keymap is for a NerD TKL PCB, your `make` command is now `make gon/nerdtkl:<keymap>`.

239
ChangeLog/20200530.md Normal file
View File

@ -0,0 +1,239 @@
# QMK Breaking Change - 2020 May 30 Changelog
Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
The list of changes follows.
## Core Changes
### Converting V-USB usbdrv to a submodule
[#8321](https://github.com/qmk/qmk_firmware/pull/8321) and [qmk_compiler#62](https://github.com/qmk/qmk_compiler/pull/62).
These PRs move the V-USB driver code out of the qmk_firmware repository and into a submodule pointed at https://github.com/obdev/v-usb. This will make it easier to update the codebase if needed, while applying any potential QMK-specific modifications by forking it to the QMK GitHub organization.
### Unify Tap Hold functions and documentation
[#8348](https://github.com/qmk/qmk_firmware/pull/8348)
Updates all of the per key tap-hold functions to pass the `keyrecord_t` structure, and include documentation changes.
Any remaining versions or code outside of the main repo will need to be converted:
| Old function | New Function |
|------------------------------------------------------|---------------------------------------------------------------------------|
|`uint16_t get_tapping_term(uint16_t keycode)` |`uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record)` |
|`bool get_ignore_mod_tap_interrupt(uint16_t keycode)` |`bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record)` |
### Python Required In The Build Process
[#9000](https://github.com/qmk/qmk_firmware/pull/9000)
This is the last release of QMK that will work without having Python 3.6 (or later) installed. If your environment is not fully setup you will get a warning instructing you to set it up.
After the next breaking change you will not be able to build if `bin/qmk hello` does not work.
### Upgrade from tinyprintf to mpaland/printf
[#8269](https://github.com/qmk/qmk_firmware/pull/8269)
- Provides debug functionality on ChibiOS/ARM that is more compliant than previous integrations.
- Less maintenence, fewer QMK customisations, and allows QMK to sidestep previous compile and runtime issues.
- A `make git-submodule` may be required after pulling the latest QMK Firmware code to update to the new dependency.
### Fixed RGB_DISABLE_AFTER_TIMEOUT to be seconds based & small internals cleanup
[#6480](https://github.com/qmk/qmk_firmware/pull/6480)
- Changes `RGB_DISABLE_AFTER_TIMEOUT` to be based on milliseconds instead of ticks.
- Includes a code cleanup, resulting in a savings of 100 bytes, depending on features used.
- Fixed issues with timeouts / suspending at the wrong time not turning off all LEDs in some cases.
The `RGB_DISABLE_AFTER_TIMEOUT` definition is now deprecated, and has been superseded by `RGB_DISABLE_TIMEOUT`. To use the new definition, rename `RGB_DISABLE_AFTER_TIMEOUT` to `RGB_DISABLE_TIMEOUT` in your `config.h` file, and multiply the value set by 1200.
Before: `#define RGB_DISABLE_AFTER_TIMEOUT 100`
After: `#define RGB_DISABLE_TIMEOUT 120000`
### Switch to qmk forks for everything
[#9019](https://github.com/qmk/qmk_firmware/pull/9019)
Fork all QMK submodules to protect against upstream repositories disappearing.
### code cleanup regarding deprecated macro PLAY_NOTE_ARRAY by replacing it with PLAY_SONG
[#8484](https://github.com/qmk/qmk_firmware/pull/8484)
Removes the deprecated `PLAY_NOTE_ARRAY` macro. References to it are replaced with `PLAY_SONG`, which references the same function.
### fixing wrong configuration of AUDIO feature
[#8903](https://github.com/qmk/qmk_firmware/pull/8903) and [#8974](https://github.com/qmk/qmk_firmware/pull/8974)
`audio_avr.c` does not default to any pin; there has to be a #define XX_AUDIO in config.h at some level for Audio to actually work. Otherwise, the Audio code ends up cluttering the firmware, possibly breaking builds because the maximum allowed firmware size is exceeded.
These changes fix this by disabling Audio on keyboards that have the feature misconfigured, and therefore non-functional.
Also, add a compile-time error to alert the user to a missing pin-configuration (on AVR boards) when `AUDIO_ENABLE = yes` is set.
## Keyboard Refactors
### Migrating Lily58 to use split_common
[#6260](https://github.com/qmk/qmk_firmware/pull/6260)
Modifies the default firmware for Lily58 to use the `split_common` library, instead of including and depending on its own set of libraries for the following functionality:
- SSD1306 display
- i2c for OLED
- Serial Communication
This allows current lily58 firmware to advance with updates to the `split_common` library, which is shared with many other split keyboards.
#### To migrate existing Lily58 firmware:
[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-445ac369c8717dcd6fc6fc3630836fc1):
- Remove `#define SSD1306OLED` from config.h
[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7):
- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE`
- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190)
- Alternatively, if you did not change the OLED code from that in `default`, you may find it easier to simply copy the [relevant section](https://github.com/qmk/qmk_firmware/blob/4ac310668501ae6786c711ecc8f01f62ddaa1c0b/keyboards/lily58/keymaps/default/keymap.c#L138-L172). Otherwise, the changes you need to make are as follows (sample change [here](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7R138-R173))
- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L138-L141) the block
```c
#ifdef SSD1306OLED
iota_gfx_init(!has_usb()); // turns on the display
#endif
```
- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
```c
oled_rotation_t oled_init_user(oled_rotation_t rotation) {
if (!is_keyboard_master())
return OLED_ROTATION_180; // flips the display 180 degrees if offhand
return rotation;
}
```
- Remove the functions `matrix_scan_user`, `matrix_update` and `iota_gfx_task_user`
- Find/Replace `matrix_render_user(struct CharacterMatrix *matrix)` with `iota_gfx_task_user(void)`
- Find/Replace `is_master` with `is_keyboard_master()`
- For each instance of `matrix_write_ln(matrix, display_fn())`, rewrite it as `oled_write_ln(read_layer_state(), false);`
- For each instance of `matrix_write(matrix, read_logo());`, replace with `oled_write(read_logo(), false);`
### Refactor zinc to use split_common
[#7114](https://github.com/qmk/qmk_firmware/pull/7114) and [#9171](https://github.com/qmk/qmk_firmware/pull/9171)
* Refactor to use split_common and remove split codes under the zinc/revx/
* Add - backlight RGB LED and/or underglow RGB LED option
* Add - continuous RGB animations feature (between L and R halves)
* Fix - keymap files to adapt to changes
* all authors of keymaps confirmed this PR
* Update - documents and rules.mk
### Refactor of TKC1800 to use common OLED code
[#8472](https://github.com/qmk/qmk_firmware/pull/8472)
Modifies the default firmware for TKC1800 to use the in-built I2C and OLED drivers, instead of including and depending on its own set of libraries for the following functionality:
- SSD1306 display
- i2c for OLED
This allows current TKC1800 firmware to advance with updates to those drivers, which are shared with other keyboards.
#### To migrate existing TKC1800 firmware:
[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-d10b26e676b4a55cbb00d71955116526):
- Remove `#define SSD1306OLED` from config.h
[Changes to `tkc1800.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-3b35bd30abe89c8110717c6972cd2cc5):
- Add the following to avoid debug errors on HID_listen if the screen is not present
```c
void keyboard_pre_init_kb(void) {
setPinInputHigh(D0);
setPinInputHigh(D1);
keyboard_pre_init_user();
}
```
[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-05a2a344ce27e4d045fe68520ccd4771):
- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE`
- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190)
- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L91-L158) the block
```c
#ifdef SSD1306OLED
iota_gfx_init(!has_usb()); // turns on the display
#endif
```
- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
```c
oled_rotation_t oled_init_user(oled_rotation_t rotation) {
if (!is_keyboard_master())
return OLED_ROTATION_180; // flips the display 180 degrees if offhand
return rotation;
}
```
- Remove the function `iota_gfx_task_user`
### Split HHKB to ANSI and JP layouts and Add VIA support for each
[#8582](https://github.com/qmk/qmk_firmware/pull/8582)
- Splits the HHKB codebase into two separate folders `keyboards/hhkb/ansi` and `keyboards/hhkb/jp`.
- Adds VIA Configurator support for both versions.
#### Migrating existing HHKB keymaps
- Remove any checks for the `HHKB_JP` definition
- All checks for this definition have been removed, and each version uses the source that is appropriate to that version.
- Move the directory for your keymap into the appropriate `keymaps` directory
- `keyboards/hhkb/ansi/keymaps/` for ANSI HHKBs
- `keyboards/hhkb/jp/keymaps/` for HHKB JPs
- Compile with the new keyboard names
- This PR changes the compilation instructions for the HHKB Alternate Controller. To compile firmware for this controller moving forward, use:
- `make hhkb/ansi` for ANSI-layout HHKBs
- `make hhkb/jp` for HHKB JP keyboards
## Keyboard Moves
- [#8412](https://github.com/qmk/qmk_firmware/pull/8412 "Changing board names to prevent confusion") by blindassassin111
- [#8499](https://github.com/qmk/qmk_firmware/pull/8499 "Move the Keyboardio Model01 to a keyboardio/ subdir") by algernon
- [#8830](https://github.com/qmk/qmk_firmware/pull/8830 "Move spaceman keyboards") by Spaceman (formerly known as Rionlion100)
- [#8537](https://github.com/qmk/qmk_firmware/pull/8537 "Organizing my keyboards (plaid, tartan, ergoinu)") by hsgw
Keyboards by Keyboardio, Spaceman, and hsgw move to vendor folders, while PCBs designed by blindassassin111 are renamed.
Old Name | New Name
:----------------- | :-----------------
2_milk | spaceman/2_milk
at101_blackheart | at101_bh
ergoinu | dm9records/ergoinu
model01 | keyboardio/model01
omnikey_blackheart | omnikey_bh
pancake | spaceman/pancake
plaid | dm9records/plaid
tartan | dm9records/tartan
z150_blackheart | z150_bh
If you own one of these PCBs, please use the new names to compile your firmware moving forward.
## Keycode Migration PRs
[#8954](https://github.com/qmk/qmk_firmware/pull/8954 "Migrate `ACTION_LAYER_TOGGLE` to `TG()`"), [#8957](https://github.com/qmk/qmk_firmware/pull/8957 "Migrate `ACTION_MODS_ONESHOT` to `OSM()`"), [#8958](https://github.com/qmk/qmk_firmware/pull/8958 "Migrate `ACTION_DEFAULT_LAYER_SET` to `DF()`"), [#8959](https://github.com/qmk/qmk_firmware/pull/8959 "Migrate `ACTION_LAYER_MODS` to `LM()`"), [#8968](https://github.com/qmk/qmk_firmware/pull/8968 "Migrate `ACTION_MODS_TAP_KEY` to `MT()`"), [#8977](https://github.com/qmk/qmk_firmware/pull/8977 "Migrate miscellaneous `fn_actions` entries"), and [#8979](https://github.com/qmk/qmk_firmware/pull/8979 "Migrate `ACTION_MODS_KEY` to chained mod keycodes")
Authored by fauxpark, these pull requests remove references to deprecated TMK macros that have been superseded by native QMK keycodes.
Old `fn_actions` action | New QMK keycode
:---------------------- | :--------------
`ACTION_DEFAULT_LAYER_SET(layer)` | `DF(layer)`
`ACTION_LAYER_MODS(layer, mod)` | `LM(layer, mod)`
`ACTION_LAYER_ONESHOT(mod)` | `OSL(mod)`
`ACTION_LAYER_TOGGLE(layer)` | `TG(layer)`
`ACTION_MODS_ONESHOT(mod)` | `OSM(mod)`
`ACTION_MODS_TAP_KEY(mod, kc)` | `MT(mod, kc)`
`ACTION_MODS_KEY(mod, kc)`<br>e.g. `ACTION_MODS_KEY(MOD_LCTL, KC_0)` | `MOD(kc)`<br>e.g. `LCTL(KC_0)`

148
ChangeLog/20200829.md Normal file
View File

@ -0,0 +1,148 @@
# QMK Breaking Change - 2020 Aug 29 Changelog
Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
## Changes Requiring User Action :id=changes-requiring-user-action
### Relocated Keyboards :id-relocated-keyboards
#### The Key Company project consolidation ([#9547](https://github.com/qmk/qmk_firmware/pull/9547))
#### relocating boards by flehrad to flehrad/ folder ([#9635](https://github.com/qmk/qmk_firmware/pull/9635))
Keyboards released by The Key Company and keyboards designed by flehrad have moved to vendor folders. If you own any of the keyboards listed below, please use the new names to compile your firmware moving forward.
Old Name | New Name
:--------------------- | :------------------
candybar/lefty | tkc/candybar/lefty
candybar/righty | tkc/candybar/righty
m0lly | tkc/m0lly
tkc1800 | tkc/tkc1800
bigswitch | flehrad/bigswitch
handwired/downbubble | flehrad/downbubble
handwired/numbrero | flehrad/numbrero
snagpad | flehrad/snagpad
handwired/tradestation | flehrad/tradestation
### Updated Keyboard Codebases :id=keyboard-updates
#### Keebio RGB wiring update ([#7754](https://github.com/qmk/qmk_firmware/pull/7754))
This pull request changes the configuration for Keebio split boards to use the same RGB strip wiring for each half, which provides the following improvements:
* Easier wiring due to one fewer wire needed (the wire between left DOut to extra data pin) and the fact that wiring is the same for both halves.
* RGB LEDs can be controlled by each half now instead of just master half.
* Extra data line is freed up to allow for I2C usage instead of serial.
If you have customized the value of `RGBLED_SPLIT` for your keymap, you will need to undefine it using `#undef RGBLED_SPLIT` before defining it to your customized value.
This change affects:
* BFO-9000
* Fourier
* Iris rev2
* Levinson, revs. 1 and 2
* Nyquist, revs. 1 and 2
* Quefrency rev1
* Viterbi, revs. 1 and 2
### Changes to Core Functionality :id=core-updates
* Bigger Combo index ([#9318](https://github.com/qmk/qmk_firmware/pull/9318))
Allows the Combo feature to support more than 256 combos.
Any fork that uses `process_combo_event` needs to update the function's first argument to `uint16_t`:
* Old function: `void process_combo_event(uint8_t combo_index, bool pressed)`
* New function: `void process_combo_event(uint16_t combo_index, bool pressed)`
## Core Changes :id=core-changes
### Fixes :id=core-fixes
* Mousekeys: scrolling acceleration is no longer coupled to mouse movement acceleration ([#9174](https://github.com/qmk/qmk_firmware/pull/9174))
* Keymap Extras: correctly assign Question Mark in Czech layout ([#9987](https://github.com/qmk/qmk_firmware/pull/9987))
### Additions and Enhancements :id=core-additions
* allow for WS2812 PWM to work on DMAMUX-capable devices ([#9471](https://github.com/qmk/qmk_firmware/pull/9471))
* Newer STM32 MCUs have a DMAMUX peripheral, which allows mapping of DMAs to different DMA streams, rather than hard-defining the target streams in silicon.
* Affects STM32L4+ devices, as well as the soon-to-be-supported-by-QMK STM32G4/H7 families.
* Tested on F303/Proton C (ChibiOS v19, non-DMAMUX), G474 (ChibiOS v20, with DMAMUX).
* dual-bank STM32 bootloader support ([#8778](https://github.com/qmk/qmk_firmware/pull/8778) and [#9738](https://github.com/qmk/qmk_firmware/pull/9738))
* Adds support for STM32 dual-bank flash bootloaders, by toggling a GPIO during early init in order to charge an RC circuit attached to `BOOT0`.
* The main rationale behind this is that dual-bank STM32 devices unconditionally execute user-mode code, regardless of whether or not the user-mode code jumps to the bootloader. If either flash bank is valid (and `BOOT0` is low), then the built-in bootloader will skip any sort of DFU.
* This PR allows for the initialisation sequencing to charge the RC circuit based on the example circuit posted on Discord, effectively pulling `BOOT0` high before issuing the system reset. As the RC circuit takes a while to discharge, the system reset executes the ROM bootloader which subsequently sees `BOOT0` high, and starts executing the DFU routines.
* Tested with STM32L082 (with current QMK+current ChibiOS), and STM32G474 (against ChibiOS 20.x).
* update Space Cadet and Tap Dance features to use Custom Tapping Term when appropriate ([#6259](https://github.com/qmk/qmk_firmware/pull/6259))
* For the Tap Dance feature, this completely removes the need for the `ACTION_TAP_DANCE_FN_ADVANCED_TIME` dance.
* HID Joystick Interface ([#4226](https://github.com/qmk/qmk_firmware/pull/4226) and [#9949](https://github.com/qmk/qmk_firmware/pull/9949 "Fix Joystick Compile Issues"))
* This implements a joystick feature, including a joystick_task function called from TMK, specific keycodes for joystick buttons and a USB HID interface.
* Tested on V-USB backend and Proton C; compiles but untested on LUFA.
* In order to test, you have to add `JOYSTICK_ENABLE = yes` to your `rules.mk` and
```c
#define JOYSTICK_BUTTON_COUNT 8
#define JOYSTICK_AXES_COUNT 2
```
in your config.h.
* Christmas RGB Underglow animation now fades between green and red ([#7648](https://github.com/qmk/qmk_firmware/pull/7648))
* `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` has been greatly decreased; please check your animation if you have customized this value.
* layer state now initializes on startup ([#8318](https://github.com/qmk/qmk_firmware/pull/8318))
* This should produce more consistent behavior between the two functions and layer masks.
* added support for HSV->RGB conversion without using CIE curve ([#9856](https://github.com/qmk/qmk_firmware/pull/9856))
* added NOEEPROM functions for RGB Matrix ([#9487](https://github.com/qmk/qmk_firmware/pull/9487))
* Added eeprom_helpers for toggle, mode, sethsv, speed, similar to rgblight versions.
* Added set_speed function.
* Added helper functions, similar to those in rgblight, in order to add NOEEPROM versions of toggle, step, hue, sat, val, and speed.
* Minor: spelling correction for EEPROM in a debug message.
* flashing firmware using `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink) is now supported ([#9964](https://github.com/qmk/qmk_firmware/pull/9964))
* add ability to dump all makefile variables for the specified target ([#8256](https://github.com/qmk/qmk_firmware/pull/8256))
* Adds a new subtarget to builds, `dump_vars`, which allows for printing out all the variables that make knows about, after all substitutions occur.
* Example: `make handwired/onekey/proton_c:default:dump_vars`
* add ability to change the Auto Shift timeout in real time ([#8441](https://github.com/qmk/qmk_firmware/pull/8441))
* added a timer implementation for backlight on ChibiOS ([#8291](https://github.com/qmk/qmk_firmware/pull/8291))
* added a third endpoint to V-USB keyboards ([#9020](https://github.com/qmk/qmk_firmware/pull/9020))
* added a method to read the OLED display buffer from user space ([#8777](https://github.com/qmk/qmk_firmware/pull/8777))
* K-Type refactor ([#9864](https://github.com/qmk/qmk_firmware/pull/9864))
* The K-Type has been refactored to use QMK's native matrix scanning routine, and now has partial support for the RGB Matrix feature.
* Joysticks can now be used without defining analog pins ([#10169](https://github.com/qmk/qmk_firmware/pull/10169))
### Clean-ups and Optimizations :id=core-optimizations
* iWRAP protocol removed ([#9284](https://github.com/qmk/qmk_firmware/pull/9284))
* work begun for consolidation of ChibiOS platform files ([#8327](https://github.com/qmk/qmk_firmware/pull/8327) and [#9315](https://github.com/qmk/qmk_firmware/pull/9315))
* Start of the consolidation work to move the ChibiOS board definitions as well as the default set of configuration files for existing board definitions used by keyboards.
* Uses `/platforms/chibios` as previously discussed on discord.
* Consolidates the Proton C configs into the generic F303 definitions.
* Allows for defining a default set of `chconf.h`, `halconf.h`, and `mcuconf.h` files within the platform definition, which is able to be overridden by the keyboard directly, though include path ordering.
* Adds template `chconf.h`, `halconf.h`, `mcuconf.h`, and `board.h` that can be dropped into a keyboard directory, in order to override rather than replace the entire contents of the respective files.
* Removed Proton C QMK board definitions, falling back to ChibiOS board definitions with QMK overrides.
* Various tidy-ups for USB descriptor code ([#9005](https://github.com/qmk/qmk_firmware/pull/9005))
* Renamed `keyboard_led_stats` in lufa.c and ChibiOS usb_main.c to `keyboard_led_state`, as well as `vusb_keyboard_leds`, for consistency
* Formatted CDC and MIDI descriptors better
* Removed `ENDPOINT_CONFIG` macro, it seems pointless and removes the need for endpoint address defines in the middle of the endpoint numbering enum
* Fixed (possibly?) V-USB `GET_REPORT` request handling. Not sure about this one, but the existing code appears to always return an empty report - now `send_keyboard` sets this variable to the current report, matching what the LUFA code does.
* converted `CONSUMER2BLUEFRUIT()` and `CONSUMER2RN42()` macros to static inline functions ([#9055](https://github.com/qmk/qmk_firmware/pull/9055))
* Additional cleanups for V-USB code ([#9310](https://github.com/qmk/qmk_firmware/pull/9310))
* Removing the UART stuff entirely, now that we have Console support. Also fixing up various other things; switching some `debug()` calls to `dprintf()`, moved `raw_hid_report` out of the way so that we can implement the shared endpoint stuff.
* removed inclusion of `adafruit_ble.h` from `ssd1306.c` ([#9355](https://github.com/qmk/qmk_firmware/pull/9355))
* `outputselect.c` is no longer compiled if Bluetooth is disabled ([#9356](https://github.com/qmk/qmk_firmware/pull/9356))
* `analogRead()` deprecated in favor of `analogReadPin()` ([#9023](https://github.com/qmk/qmk_firmware/pull/9023))
* forcibly disable NKRO on V-USB controllers ([#9054](https://github.com/qmk/qmk_firmware/pull/9054))
* removed warning if running backlight on STM32F072 ([#10040](https://github.com/qmk/qmk_firmware/pull/10040))
* removed unused CORTEX_VTOR_INIT rules.mk option ([#10053](https://github.com/qmk/qmk_firmware/pull/10053))
* improved handling for enabling Link Time Optimization ([#9832](https://github.com/qmk/qmk_firmware/pull/9832))
* streamline rules for supporting Kiibohd bootloader ([#10129](https://github.com/qmk/qmk_firmware/pull/10129))
* Define `STM32_DMA_REQUIRED` when using DMA-based WS2812 driver on STM32 ([#10127](https://github.com/qmk/qmk_firmware/pull/10127))
* fix DMA stream ID calculation in ws2812_pwm ([#10008](https://github.com/qmk/qmk_firmware/pull/10008))
* remove support for Adafruit EZ Key Bluetooth controller ([#10103](https://github.com/qmk/qmk_firmware/pull/10103))
## QMK Infrastructure and Internals :id=qmk-internals
* Attempt to fix CI for non-master branches. ([#9308](https://github.com/qmk/qmk_firmware/pull/9308))
* Actually fetch the branch we're attempting to compare against.
* Run `qmk cformat` on `develop` branch ([#9501](https://github.com/qmk/qmk_firmware/pull/9501))
* minor refactor of Bluetooth API ([#9905](https://github.com/qmk/qmk_firmware/pull/9905))

43
README.md Normal file
View File

@ -0,0 +1,43 @@
# Quantum Mechanical Keyboard Firmware
[![Current Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
[![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
[![Docs Status](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
[![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
[![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
## What is QMK Firmware?
QMK (*Quantum Mechanical Keyboard*) is an open source community centered around developing computer input devices. The community encompasses all sorts of input devices, such as keyboards, mice, and MIDI devices. A core group of collaborators maintains [QMK Firmware](https://github.com/qmk/qmk_firmware), [QMK Configurator](https://config.qmk.fm), [QMK Toolbox](https://github.com/qmk/qmk_toolbox), [qmk.fm](https://qmk.fm), and this documentation with the help of community members like you.
## Get Started
Totally new to QMK? There are two ways to get started:
* Basic: [QMK Configurator](https://config.qmk.fm)
* Just select your keyboard from the dropdown and program your keyboard.
* We have an [introductory video](https://www.youtube.com/watch?v=-imgglzDMdY) you can watch.
* There is also an overview [document you can read](newbs_building_firmware_configurator.md).
* Advanced: [Use The Source](newbs.md)
* More powerful, but harder to use
## Make It Yours
QMK has lots of [features](features.md) to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
## Need help?
Check out the [support page](support.md) to see how you can get help using QMK.
## Give Back
There are a lot of ways you can contribute to the QMK Community. The easiest way to get started is to use it and spread the word to your friends.
* Help people out on our forums and chat rooms:
* [/r/olkb](https://www.reddit.com/r/olkb/)
* [Discord Server](https://discord.gg/Uq7gcHh)
* Contribute to our documentation by clicking "Edit This Page" at the bottom
* [Translate our documentation into your language](translating.md)
* [Report a bug](https://github.com/qmk/qmk_firmware/issues/new/choose)
* [Open a Pull Request](contributing.md)

9
_langs.md Normal file
View File

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

180
_summary.md Normal file
View File

@ -0,0 +1,180 @@
* Tutorial
* [Introduction](newbs.md)
* [Setup](newbs_getting_started.md)
* [Building Your First Firmware](newbs_building_firmware.md)
* [Flashing Firmware](newbs_flashing.md)
* [Testing and Debugging](newbs_testing_debugging.md)
* [Getting Help/Support](support.md)
* [Other Resources](newbs_learn_more_resources.md)
* [Syllabus](syllabus.md)
* FAQs
* [General FAQ](faq_general.md)
* [Build/Compile QMK](faq_build.md)
* [Debugging/Troubleshooting QMK](faq_debug.md)
* [Keymap FAQ](faq_keymap.md)
* [Glossary](reference_glossary.md)
* Configurator
* [Overview](newbs_building_firmware_configurator.md)
* [Step by Step](configurator_step_by_step.md)
* [Troubleshooting](configurator_troubleshooting.md)
* QMK API
* [Overview](api_overview.md)
* [API Documentation](api_docs.md)
* [Keyboard Support](reference_configurator_support.md)
* [Adding Default Keymaps](configurator_default_keymaps.md)
* CLI
* [Overview](cli.md)
* [Configuration](cli_configuration.md)
* [Commands](cli_commands.md)
* Using QMK
* Guides
* [Customizing Functionality](custom_quantum_functions.md)
* [Driver Installation with Zadig](driver_installation_zadig.md)
* [Keymap Overview](keymap.md)
* Development Environments
* [Docker Guide](getting_started_docker.md)
* [Vagrant Guide](getting_started_vagrant.md)
* Flashing
* [Flashing](flashing.md)
* [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md)
* IDEs
* [Using Eclipse with QMK](other_eclipse.md)
* [Using VSCode with QMK](other_vscode.md)
* Git Best Practices
* [Introduction](newbs_git_best_practices.md)
* [Your Fork](newbs_git_using_your_master_branch.md)
* [Merge Conflicts](newbs_git_resolving_merge_conflicts.md)
* [Fixing Your Branch](newbs_git_resynchronize_a_branch.md)
* Keyboard Building
* [Hand Wiring Guide](hand_wire.md)
* [ISP Flashing Guide](isp_flashing_guide.md)
* Simple Keycodes
* [Full List](keycodes.md)
* [Basic Keycodes](keycodes_basic.md)
* [Language-Specific Keycodes](reference_keymap_extras.md)
* [Modifier Keys](feature_advanced_keycodes.md)
* [Quantum Keycodes](quantum_keycodes.md)
* Advanced Keycodes
* [Command](feature_command.md)
* [Dynamic Macros](feature_dynamic_macros.md)
* [Grave Escape](feature_grave_esc.md)
* [Leader Key](feature_leader_key.md)
* [Mod-Tap](mod_tap.md)
* [Macros](feature_macros.md)
* [Mouse Keys](feature_mouse_keys.md)
* [Space Cadet Shift](feature_space_cadet.md)
* [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
* Software Features
* [Auto Shift](feature_auto_shift.md)
* [Combos](feature_combo.md)
* [Debounce API](feature_debounce_type.md)
* [Key Lock](feature_key_lock.md)
* [Layers](feature_layers.md)
* [One Shot Keys](one_shot_keys.md)
* [Pointing Device](feature_pointing_device.md)
* [Raw HID](feature_rawhid.md)
* [Swap Hands](feature_swap_hands.md)
* [Tap Dance](feature_tap_dance.md)
* [Tap-Hold Configuration](tap_hold.md)
* [Terminal](feature_terminal.md)
* [Unicode](feature_unicode.md)
* [Userspace](feature_userspace.md)
* [WPM Calculation](feature_wpm.md)
* Hardware Features
* Displays
* [HD44780 LCD Controller](feature_hd44780.md)
* [OLED Driver](feature_oled_driver.md)
* Lighting
* [Backlight](feature_backlight.md)
* [LED Matrix](feature_led_matrix.md)
* [RGB Lighting](feature_rgblight.md)
* [RGB Matrix](feature_rgb_matrix.md)
* [Audio](feature_audio.md)
* [Bluetooth](feature_bluetooth.md)
* [Bootmagic](feature_bootmagic.md)
* [Custom Matrix](custom_matrix.md)
* [DIP Switch](feature_dip_switch.md)
* [Encoders](feature_encoders.md)
* [Haptic Feedback](feature_haptic_feedback.md)
* [Joystick](feature_joystick.md)
* [LED Indicators](feature_led_indicators.md)
* [Proton C Conversion](proton_c_conversion.md)
* [PS/2 Mouse](feature_ps2_mouse.md)
* [Split Keyboard](feature_split_keyboard.md)
* [Stenography](feature_stenography.md)
* [Thermal Printer](feature_thermal_printer.md)
* [Velocikey](feature_velocikey.md)
* Developing QMK
* [PR Checklist](pr_checklist.md)
* Breaking Changes
* [Overview](breaking_changes.md)
* [My Pull Request Was Flagged](breaking_changes_instructions.md)
* History
* [2020 Aug 29](ChangeLog/20200829.md)
* [2020 May 30](ChangeLog/20200530.md)
* [2020 Feb 29](ChangeLog/20200229.md)
* [2019 Aug 30](ChangeLog/20190830.md)
* C Development
* [ARM Debugging Guide](arm_debugging.md)
* [AVR Processors](hardware_avr.md)
* [Coding Conventions](coding_conventions_c.md)
* [Compatible Microcontrollers](compatible_microcontrollers.md)
* [Drivers](hardware_drivers.md)
* [ADC Driver](adc_driver.md)
* [I2C Driver](i2c_driver.md)
* [SPI Driver](spi_driver.md)
* [WS2812 Driver](ws2812_driver.md)
* [EEPROM Driver](eeprom_driver.md)
* ['serial' Driver](serial_driver.md)
* [GPIO Controls](internals_gpio_control.md)
* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
* Python Development
* [Coding Conventions](coding_conventions_python.md)
* [QMK CLI Development](cli_development.md)
* Configurator Development
* QMK API
* [Development Environment](api_development_environment.md)
* [Architecture Overview](api_development_overview.md)
* Hardware Platform Development
* Arm/ChibiOS
* [Selecting an MCU](platformdev_selecting_arm_mcu.md)
* [Early initialization](platformdev_chibios_earlyinit.md)
* QMK Reference
* [Contributing to QMK](contributing.md)
* [Translating the QMK Docs](translating.md)
* [Config Options](config_options.md)
* [Make Documentation](getting_started_make_guide.md)
* [Documentation Best Practices](documentation_best_practices.md)
* [Documentation Templates](documentation_templates.md)
* [Community Layouts](feature_layouts.md)
* [Unit Testing](unit_testing.md)
* [Useful Functions](ref_functions.md)
* [info.json Format](reference_info_json.md)
* For a Deeper Understanding
* [How Keyboards Work](how_keyboards_work.md)
* [How a Matrix Works](how_a_matrix_works.md)
* [Understanding QMK](understanding_qmk.md)
* QMK Internals (In Progress)
* [Defines](internals_defines.md)
* [Input Callback Reg](internals_input_callback_reg.md)
* [Midi Device](internals_midi_device.md)
* [Midi Device Setup Process](internals_midi_device_setup_process.md)
* [Midi Util](internals_midi_util.md)
* [Send Functions](internals_send_functions.md)
* [Sysex Tools](internals_sysex_tools.md)

150
adc_driver.md Normal file
View File

@ -0,0 +1,150 @@
# ADC Driver
QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](feature_encoders.md).
This driver currently supports both AVR and a limited selection of ARM devices. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V for AVR, 3.3V only for ARM), however on ARM there is more flexibility in control of operation through `#define`s if you need more precision.
## Usage
To use this driver, add the following to your `rules.mk`:
```make
SRC += analog.c
```
Then place this include at the top of your code:
```c
#include "analog.h"
```
## Channels
### AVR
|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P|
|-------|-------------|-------------|---------|----------|
|0 |`F0` |`F0` |`A0` |`C0` |
|1 |`F1` |`F1` |`A1` |`C1` |
|2 |`F2` | |`A2` |`C2` |
|3 |`F3` | |`A3` |`C3` |
|4 |`F4` |`F4` |`A4` |`C4` |
|5 |`F5` |`F5` |`A5` |`C5` |
|6 |`F6` |`F6` |`A6` |* |
|7 |`F7` |`F7` |`A7` |* |
|8 | |`D4` | | |
|9 | |`D6` | | |
|10 | |`D7` | | |
|11 | |`B4` | | |
|12 | |`B5` | | |
|13 | |`B6` | | |
<sup>\* The ATmega328/P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
### ARM
Note that some of these pins are doubled-up on ADCs with the same channel. This is because the pins can be used for either ADC.
Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-indexed, whereas the F3 has 4 ADCs and the channels are 1-indexed. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
|ADC|Channel|STM32F0xx|STM32F3xx|
|---|-------|---------|---------|
|1 |0 |`A0` | |
|1 |1 |`A1` |`A0` |
|1 |2 |`A2` |`A1` |
|1 |3 |`A3` |`A2` |
|1 |4 |`A4` |`A3` |
|1 |5 |`A5` |`F4` |
|1 |6 |`A6` |`C0` |
|1 |7 |`A7` |`C1` |
|1 |8 |`B0` |`C2` |
|1 |9 |`B1` |`C3` |
|1 |10 |`C0` |`F2` |
|1 |11 |`C1` | |
|1 |12 |`C2` | |
|1 |13 |`C3` | |
|1 |14 |`C4` | |
|1 |15 |`C5` | |
|1 |16 | | |
|2 |1 | |`A4` |
|2 |2 | |`A5` |
|2 |3 | |`A6` |
|2 |4 | |`A7` |
|2 |5 | |`C4` |
|2 |6 | |`C0` |
|2 |7 | |`C1` |
|2 |8 | |`C2` |
|2 |9 | |`C3` |
|2 |10 | |`F2` |
|2 |11 | |`C5` |
|2 |12 | |`B2` |
|2 |13 | | |
|2 |14 | | |
|2 |15 | | |
|2 |16 | | |
|3 |1 | |`B1` |
|3 |2 | |`E9` |
|3 |3 | |`E13` |
|3 |4 | | |
|3 |5 | | |
|3 |6 | |`E8` |
|3 |7 | |`D10` |
|3 |8 | |`D11` |
|3 |9 | |`D12` |
|3 |10 | |`D13` |
|3 |11 | |`D14` |
|3 |12 | |`B0` |
|3 |13 | |`E7` |
|3 |14 | |`E10` |
|3 |15 | |`E11` |
|3 |16 | |`E12` |
|4 |1 | |`E14` |
|4 |2 | |`B12` |
|4 |3 | |`B13` |
|4 |4 | |`B14` |
|4 |5 | |`B15` |
|4 |6 | |`E8` |
|4 |7 | |`D10` |
|4 |8 | |`D11` |
|4 |9 | |`D12` |
|4 |10 | |`D13` |
|4 |11 | |`D14` |
|4 |12 | |`D8` |
|4 |13 | |`D9` |
|4 |14 | | |
|4 |15 | | |
|4 |16 | | |
## Functions
### AVR
|Function |Description |
|----------------------------|-------------------------------------------------------------------------------------------------------------------|
|`analogReference(mode)` |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.|
|`analogReadPin(pin)` |Reads the value from the specified pin, eg. `F6` for ADC6 on the ATmega32U4. |
|`pinToMux(pin)` |Translates a given pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)". |
|`adc_read(mux)` |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information. |
### ARM
|Function |Description |
|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`analogReadPin(pin)` |Reads the value from the specified pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
|`analogReadPinAdc(pin, adc)`|Reads the value from the specified pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function. |
|`pinToMux(pin)` |Translates a given pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)". |
|`adc_read(mux)` |Reads the value from the ADC according to the specified pin and ADC combination. See your MCU's datasheet for more information. |
## Configuration
## ARM
The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.
|`#define` |Type |Default |Description |
|---------------------|------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`ADC_CIRCULAR_BUFFER`|`bool`|`false` |If `true`, then the implementation will use a circular buffer. |
|`ADC_NUM_CHANNELS` |`int` |`1` |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`. |
|`ADC_BUFFER_DEPTH` |`int` |`2` |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.|
|`ADC_SAMPLING_RATE` |`int` |`ADC_SMPR_SMP_1P5` |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. |
|`ADC_RESOLUTION` |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. |

3
api_development_environment.md Normal file
View File

@ -0,0 +1,3 @@
# Development Environment Setup
To setup a development stack head over to the [qmk_web_stack](https://github.com/qmk/qmk_web_stack).

44
api_development_overview.md Normal file
View File

@ -0,0 +1,44 @@
# QMK Compiler Development Guide
This page attempts to introduce developers to the QMK Compiler. It does not go into nitty gritty details- for that you should read code. What this will give you is a framework to hang your understanding on as you read the code.
# Overview
The QMK Compile API consists of a few movings parts:
![Architecture Diagram](https://raw.githubusercontent.com/qmk/qmk_api/master/docs/architecture.svg)
API Clients interact exclusively with the API service. This is where they submit jobs, check status, and download results. The API service inserts compile jobs into [Redis Queue](https://python-rq.org) and checks both RQ and S3 for the results of those jobs.
Workers fetch new compile jobs from RQ, compile them, and then upload the source and the binary to an S3 compatible storage engine.
# Workers
QMK Compiler Workers are responsible for doing the actual building. When a worker pulls a job from RQ it does several things to complete that job:
* Make a fresh qmk_firmware checkout
* Use the supplied layers and keyboard metadata to build a `keymap.c`
* Build the firmware
* Zip a copy of the source
* Upload the firmware, source zip, and a metadata file to S3.
* Report the status of the job to RQ
# API Service
The API service is a relatively simple Flask application. There are a few main views you should understand.
## @app.route('/v1/compile', methods=['POST'])
This is the main entrypoint for the API. A client's interaction starts here. The client POST's a JSON document describing their keyboard, and the API does some (very) basic validation of that JSON before submitting the compile job.
## @app.route('/v1/compile/&lt;string:job_id&gt;', methods=['GET'])
This is the most frequently called endpoint. It pulls the job details from redis, if they're still available, or the cached job details on S3 if they're not.
## @app.route('/v1/compile/&lt;string:job_id&gt;/download', methods=['GET'])
This method allows users to download the compiled firmware file.
## @app.route('/v1/compile/&lt;string:job_id&gt;/source', methods=['GET'])
This method allows users to download the source for their firmware.

68
api_docs.md Normal file
View File

@ -0,0 +1,68 @@
# QMK API
This page describes using the QMK API. If you are an application developer you can use this API to compile firmware for any [QMK](https://qmk.fm) Keyboard.
## Overview
This service is an asynchronous API for compiling custom keymaps. You POST some JSON to the API, periodically check the status, and when your firmware has finished compiling you can download the resulting firmware and (if desired) source code for that firmware.
#### Example JSON Payload:
```json
{
"keyboard": "clueboard/66/rev2",
"keymap": "my_awesome_keymap",
"layout": "LAYOUT_all",
"layers": [
["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_GRV","KC_BSPC","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_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","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],
["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_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"],
["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","RESET","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"]
]
}
```
As you can see the payload describes all aspects of a keyboard necessary to create and generate a firmware. Each layer is a single list of QMK keycodes the same length as the keyboard's `LAYOUT` macro. If a keyboard supports mulitple `LAYOUT` macros you can specify which macro to use.
## Submitting a Compile Job
To compile your keymap into a firmware simply POST your JSON to the `/v1/compile` endpoint. In the following example we've placed the JSON payload into a file named `json_data`.
```
$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" http://api.qmk.fm/v1/compile
{
"enqueued": true,
"job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
}
```
## Checking The Status
After submitting your keymap you can check the status using a simple HTTP GET call:
```
$ curl http://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
{
"created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
"enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",
"id": "f5f9b992-73b4-479b-8236-df1deb37c163",
"status": "running",
"result": null
}
```
This shows us that the job has made it through the queue and is currently running. There are 5 possible statuses:
* **failed**: Something about the compiling service has broken.
* **finished**: The compilation is complete and you should check `result` to see the results.
* **queued**: The keymap is waiting for a compilation server to become available.
* **running**: The compilation is in progress and should be complete soon.
* **unknown**: A serious error has occurred and you should [file a bug](https://github.com/qmk/qmk_compiler/issues).
## Examining Finished Results
Once your compile job has finished you'll check the `result` key. The value of this key is a hash containing several key bits of information:
* `firmware_binary_url`: A list of URLs for the the flashable firmware
* `firmware_keymap_url`: A list of URLs for the the `keymap.c`
* `firmware_source_url`: A list of URLs for the full firmware source code
* `output`: The stdout and stderr for this compile job. Errors will be found here.

15
api_overview.md Normal file
View File

@ -0,0 +1,15 @@
# QMK API
The QMK API provides an asynchronous API that Web and GUI tools can use to compile arbitrary keymaps for any keyboard supported by [QMK](http://qmk.fm/). The stock keymap template supports all QMK keycodes that do not require supporting C code. Keyboard maintainers can supply their own custom templates to enable more functionality.
## App Developers
If you are an app developer interested in using this API in your application you should head over to [Using The API](api_docs.md).
## Keyboard Maintainers
If you would like to enhance your keyboard's support in the QMK Compiler API head over to the [Keyboard Support](reference_configurator_support.md) section.
## Backend Developers
If you are interested in working on the API itself you should start by setting up a [Development Environment](api_development_environment.md), then check out [Hacking On The API](api_development_overview.md).

87
arm_debugging.md Normal file
View File

@ -0,0 +1,87 @@
# ARM Debugging using Eclipse
This page describes how to setup debugging for ARM MCUs using an SWD adapter and open-source/free tools. In this guide we will install GNU MCU Eclipse IDE for C/C++ Developers and OpenOCD together with all the necessary dependencies.
This guide is catered towards advance users and assumes you can compile an ARM compatible keyboard on your machine using the MAKE flow.
## Installing the software
The main objective here is to get the MCU Eclipse IDE correctly installed on our machine. The necessary instructions are derived from [this](https://gnu-mcu-eclipse.github.io/install/) install guide.
### The xPack Manager
This tool is a software package manager and it is used to help us get the necessary dependencies.
XPM runs using Node.js so grab that from [here](https://nodejs.org/en/). After installation, open a terminal and type `npm -v`. A reply with the version number means that the installation was successful.
XPM installation instructions can be found [here](https://www.npmjs.com/package/xpm) and are OS specific. Entering `xpm --version` to your terminal should return the software version.
### The ARM Toolchain
Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @xpack-dev-tools/arm-none-eabi-gcc`.
### Windows build tools
If you are using windows you need to install this!
`xpm install --global @gnu-mcu-eclipse/windows-build-tools`
### Programmer/Debugger Drivers
Now it's time to install your programmer's drivers. This tutorial was made using an ST-Link v2 which you can get from almost anywhere.
If you have an ST-Link the drivers can be found [here](https://www.st.com/en/development-tools/stsw-link009.html) otherwise consult the manufacturer of your tool.
### OpenOCD
This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @xpack-dev-tools/openocd`.
### Java
Java is needed by Eclipse so please download it from [here](https://www.oracle.com/technetwork/java/javase/downloads/index.html).
### GNU MCU Eclipse IDE
Now its finally time to install the IDE. Use the Release page [here](https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/) to get the latest version.
## Configuring Eclipse
Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing Code as Makefile Project. Select Next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish.
Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchains Paths. Press xPack and OK. Repeat for OpenOCD Path and if you are on Windows for Build Tools Path. Select Apply and Close.
Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Perspective -> Open Perspective -> Other... -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore.
When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectronics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Perspective -> Open Perspective -> Other... -> C/C++.
We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under Devices select the appropriate variant of your MCU. For my example it is STM32F303CC
While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the Build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close.
## Building
If you have setup everything correctly pressing the hammer button should build the firmware for you and a .bin file should appear.
## Debugging
### Connecting the Debugger
ARM MCUs use the Single Wire Debug (SWD) protocol which comprises of the clock (SWCLK) signal and the data (SWDIO) signal. Connecting this two wires and ground should be enough to allow full manipulation of the MCU. Here we assume that the keyboard will be powered though USB. The RESET signal is not necessary as we can manually assert it using the reset button. For a more advance setup, the SWO signal can be used which pipes printf and scanf asynchronously to the host but for our setup we will ignore it.
NOTE: Make sure the SWCLK and SWDIO pins are not used in the matrix of your keyboard. If they are you can temporarily switch them for some other pins.
### Configuring the Debugger
Right click on your QMK folder, select Debug As -> Debug Configurations... . Here double click on GDB OpenOCD Debugging. Select the Debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and Googling to find out. The default script for the STM32F3 is called `stm32f3discovery.cfg`. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`.
NOTE: In my case this configuration script requires editing to disable the reset assertion. The locations of the scripts can be found in the actual executable field usually under the path `openocd/version/.content/scripts/board`. Here I edited `reset_config srst_only` to `reset_config none`.
Select Apply and Close.
### Running the Debugger.
Reset your keyboard.
Press the bug icon and if all goes well you should soon find yourself in the Debug perspective. Here the program counter will pause at the beginning of the main function and wait for you to press Play. Most of the features of all debuggers work on Arm MCUs but for exact details Google is your friend!
Happy debugging!

110
breaking_changes.md Normal file
View File

@ -0,0 +1,110 @@
# Breaking Changes
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.
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?
* [2020 Aug 29](ChangeLog/20200829.md)
* [2020 May 30](ChangeLog/20200530.md)
* [2020 Feb 29](ChangeLog/20200229.md)
* [2019 Aug 30](ChangeLog/20190830.md)
## When is the next Breaking Change?
The next Breaking Change is scheduled for November 28, 2020.
### Important Dates
* [x] 2020 Aug 29 - `develop` is created. It will be rebased weekly.
* [ ] 2020 Oct 31 - `develop` closed to new PR's.
* [ ] 2020 Oct 31 - Call for testers.
* [ ] 2020 Nov 26 - `master` is locked, no PR's merged.
* [ ] 2020 Nov 28 - Merge `develop` to `master`.
* [ ] 2020 Nov 28 - `master` is unlocked. PR's can be merged again.
## What changes will be included?
To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `develop` is closed, and a PR with that label applied is not guaranteed to be merged.
If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `develop` closes. After `develop` closes no new breaking changes will be accepted.
Criteria for acceptance:
* PR is complete and ready to merge
* PR has a ChangeLog
# Checklists
This section documents various processes we use when running the Breaking Changes process.
## Rebase `develop` from `master`
This is run every Friday while `develop` is open.
Process:
```
cd qmk_firmware
git checkout master
git pull --ff-only
git checkout develop
git rebase master
git push --force
```
## Creating the `develop` branch
This happens immediately after the previous `develop` branch is merged.
* `qmk_firmware` git commands
* [ ] `git checkout master`
* [ ] `git pull --ff-only`
* [ ] `git checkout -b develop`
* [ ] Edit `readme.md`
* [ ] Add a big notice at the top that this is a testing branch.
* [ ] Include a link to this document
* [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
* [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
* [ ] `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
* [ ] `git push origin develop`
* [ ] `git push --tags`
## 4 Weeks Before Merge
* `develop` is now closed to new PR's, only fixes for current PR's may be merged
* 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>
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
## 2 Days Before Merge
* Announce that master is closed for 2 days
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
## Day Of Merge
* `qmk_firmware` git commands
* [ ] `git checkout develop`
* [ ] `git pull --ff-only`
* [ ] `git rebase origin/master`
* [ ] Edit `readme.md`
* [ ] Remove the notes about `develop`
* [ ] Roll up the ChangeLog into one file.
* [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
* [ ] `git push origin develop`
* GitHub Actions
* [ ] Create a PR for `develop`
* [ ] Make sure travis comes back clean
* [ ] Merge `develop` PR

42
breaking_changes_instructions.md Normal file
View File

@ -0,0 +1,42 @@
# Breaking Changes: My Pull Request Was Flagged
A QMK member may have replied to your pull request stating that your submission is a breaking change. In their judgment, the changes you have proposed have greater implications for either QMK, or its users.
Some things that may cause a pull request to be flagged are:
- **Edits to User Keymaps**
A user may submit their keymap to QMK, then some time later open a pull request with further updates, only to find it can't be merged because it was edited in the `qmk/qmk_firmware` repository. As not all users are proficient at using Git or GitHub, the user may find themself unable to fix the issue on their own.
- **Changes to Expected Behavior**
Changes to QMK behavior may cause users to believe their hardware or QMK is broken if they flash new firmware that incorporates changes to existing QMK features, and find themselves without a means to restore the desired behavior.
- **Changes Requiring User Action**
Changes may also require action to be taken by users, such as updating a toolchain or taking some action in Git.
- **Changes Necessitating Increased Scrutiny**
On occasion, a submission may have implications for QMK as a project. This could be copyright/licensing issues, coding conventions, large feature overhauls, "high-risk" changes that need wider testing by our community, or something else entirely.
- **Changes Requiring Communication to End Users**
This includes warnings about future deprecations, outdated practices, and anything else that needs to be communicated but doesn't fit into one of the above categories.
## What Do I Do?
If it is determined that your submission is a breaking change, there are a few things you can do to smooth the process:
### Consider Splitting Up Your PR
If you are contributing core code, and the only reason it needs to go through breaking changes is that you are updating keymaps to match your change, consider whether you can submit your feature in a way that the old keymaps continue to work. Then submit a separate PR that goes through the breaking changes process to remove the old code.
### Contribute a ChangeLog Entry
We require submissions that go through the Breaking Change process to include a changelog entry. The entry should be a short summary of the changes your pull request makes &ndash; [each section here started as a changelog](ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc - @noroadsleft").
Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch &ndash; usually named `develop` &ndash; will be merged into the `master` branch, and `####` is the number of your pull request.
If your submission requires action on the part of users, your changelog should instruct users what action(s) must be taken, or link to a location that does so.
### Document Your Changes
Understanding the purpose for your submission, and possible implications or actions it will require can make the review process more straightforward. A changelog may suffice for this purpose, but more extensive changes may require a level of detail that is ill-suited for a changelog.
Commenting on your pull request and being responsive to questions, comments, and change requests is much appreciated.
### Ask for Help
Having your submission flagged may have caught you off guard. If you find yourself intimidated or overwhelmed, let us know. Comment on your pull request, or [reach out to the QMK team on Discord](https://discord.gg/Uq7gcHh).

38
cli.md Normal file
View File

@ -0,0 +1,38 @@
# QMK CLI :id=qmk-cli
## Overview :id=overview
The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more.
### Requirements :id=requirements
QMK requires Python 3.6 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). These are installed automatically when you install the QMK CLI.
### Install Using Homebrew (macOS, some Linux) :id=install-using-homebrew
If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
```
brew install qmk/qmk/qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
```
### Install Using pip :id=install-using-easy_install-or-pip
If your system is not listed above you can install QMK manually. First ensure that you have Python 3.6 (or later) installed and have installed pip. Then install QMK with this command:
```
python3 -m pip install qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
```
### Packaging For Other Operating Systems :id=packaging-for-other-operating-systems
We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines:
* Follow best practices for your OS when they conflict with these guidelines
* Document why in a comment when you do deviate
* Install using a virtualenv
* Instruct the user to set the environment variable `QMK_HOME` to have the firmware source checked out somewhere other than `~/qmk_firmware`.

339
cli_commands.md Normal file
View File

@ -0,0 +1,339 @@
# QMK CLI Commands
# User Commands
## `qmk compile`
This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm>, compile keymaps in the repo, or compile the keyboard in the current working directory.
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Usage for Configurator Exports**:
```
qmk compile <configuratorExport.json>
```
**Usage for Keymaps**:
```
qmk compile -kb <keyboard_name> -km <keymap_name>
```
**Usage in Keyboard Directory**:
Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap <keymap_name>`
```
qmk compile
```
**Usage for building all keyboards that support a specific keymap**:
```
qmk compile -kb all -km <keymap_name>
```
**Example**:
```
$ qmk config compile.keymap=default
$ cd ~/qmk_firmware/keyboards/planck/rev6
$ qmk compile
Ψ Compiling keymap with make planck/rev6:default
...
```
or with optional keymap argument
```
$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4
$ qmk compile -km 66_iso
Ψ Compiling keymap with make clueboard/66/rev4:66_iso
...
```
or in keymap directory
```
$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
$ qmk compile
Ψ Compiling keymap with make make gh60/satan:colemak
...
```
**Usage in Layout Directory**:
Must be under `qmk_firmware/layouts/`, and in a keymap folder.
```
qmk compile -kb <keyboard_name>
```
**Example**:
```
$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
$ qmk compile -kb dz60
Ψ Compiling keymap with make dz60:mechmerlin-ansi
...
```
## `qmk flash`
This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders.
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Usage for Configurator Exports**:
```
qmk flash <configuratorExport.json> -bl <bootloader>
```
**Usage for Keymaps**:
```
qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
```
**Listing the Bootloaders**
```
qmk flash -b
```
## `qmk config`
This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md).
**Usage**:
```
qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
```
## `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.
**Usage**:
```
qmk doctor [-y] [-n]
```
**Examples**:
Check your environment for problems and prompt to fix them:
qmk doctor
Check your environment and automatically fix any problems found:
qmk doctor -y
Check your environment and report problems only:
qmk doctor -n
## `qmk info`
Displays information about keyboards and keymaps in QMK. You can use this to get information about a keyboard, show the layouts, display the underlying key matrix, or to pretty-print JSON keymaps.
**Usage**:
```
qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
```
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Examples**:
Show basic information for a keyboard:
qmk info -kb planck/rev5
Show the matrix for a keyboard:
qmk info -kb ergodox_ez -m
Show a JSON keymap for a keyboard:
qmk info -kb clueboard/california -km default
## `qmk json2c`
Creates a keymap.c from a QMK Configurator export.
**Usage**:
```
qmk json2c [-o OUTPUT] filename
```
## `qmk c2json`
Creates a keymap.json from a keymap.c.
**Note:** Parsing C source files is not easy, therefore this subcommand may not work your keymap. In some cases not using the C pre-processor helps.
**Usage**:
```
qmk c2json [--no-cpp] [-o OUTPUT] filename
```
## `qmk lint`
Checks over a keyboard and/or keymap and highlights common errors, problems, and anti-patterns.
**Usage**:
```
qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict]
```
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Examples**:
Do a basic lint check:
qmk lint -kb rominronin/katana60/rev2
## `qmk list-keyboards`
This command lists all the keyboards currently defined in `qmk_firmware`
**Usage**:
```
qmk list-keyboards
```
## `qmk list-keymaps`
This command lists all the keymaps for a specified keyboard (and revision).
This command is directory aware. It will automatically fill in KEYBOARD if you are in a keyboard directory.
**Usage**:
```
qmk list-keymaps -kb planck/ez
```
## `qmk new-keymap`
This command creates a new keymap based on a keyboard's existing default keymap.
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Usage**:
```
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
```
## `qmk clean`
This command cleans up the `.build` folder. If `--all` is passed, any .hex or .bin files present in the `qmk_firmware` directory will also be deleted.
**Usage**:
```
qmk clean [-a]
```
---
# Developer Commands
## `qmk cformat`
This command formats C code using clang-format.
Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>`
Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files.
**Usage for specified files**:
```
qmk cformat [file1] [file2] [...] [fileN]
```
**Usage for all core files**:
```
qmk cformat -a
```
**Usage for only changed files against origin/master**:
```
qmk cformat
```
**Usage for only changed files against branch_name**:
```
qmk cformat -b branch_name
```
## `qmk docs`
This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
**Usage**:
```
qmk docs [-p PORT]
```
## `qmk generate-docs`
This command allows you to generate QMK documentation locally. It can be uses for general browsing or improving the docs. External tools such as [serve](https://www.npmjs.com/package/serve) can be used to browse the generated files.
**Usage**:
```
qmk generate-docs
```
## `qmk kle2json`
This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
**Usage**:
```
qmk kle2json [-f] <filename>
```
**Examples**:
```
$ qmk kle2json kle.txt
☒ File info.json already exists, use -f or --force to overwrite.
```
```
$ qmk kle2json -f kle.txt -f
Ψ Wrote out to info.json
```
## `qmk pyformat`
This command formats python code in `qmk_firmware`.
**Usage**:
```
qmk pyformat
```
## `qmk pytest`
This command runs the python test suite. If you make changes to python code you should ensure this runs successfully.
**Usage**:
```
qmk pytest
```

121
cli_configuration.md Normal file
View File

@ -0,0 +1,121 @@
# QMK CLI Configuration
This document explains how `qmk config` works.
# Introduction
Configuration for the QMK CLI is a key/value system. Each key consists of a subcommand and an argument name separated by a period. This allows for a straightforward and direct translation between config keys and the arguments they set.
## Simple Example
As an example let's look at the command `qmk compile --keyboard clueboard/66/rev4 --keymap default`.
There are two command line arguments that could be read from configuration instead:
* `compile.keyboard`
* `compile.keymap`
Let's set these now:
```
$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
compile.keyboard: None -> clueboard/66/rev4
compile.keymap: None -> default
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
```
Now I can run `qmk compile` without specifying my keyboard and keymap each time.
## Setting User Defaults
Sometimes you want to share a setting between multiple commands. For example, multiple commands take the argument `--keyboard`. Rather than setting this value for every command you can set a user value which will be used by any command that takes that argument.
Example:
```
$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
user.keyboard: None -> clueboard/66/rev4
user.keymap: None -> default
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
```
# CLI Documentation (`qmk config`)
The `qmk config` command is used to interact with the underlying configuration. When run with no argument it shows the current configuration. When arguments are supplied they are assumed to be configuration tokens, which are strings containing no spaces with the following form:
<subcommand|general|default>[.<key>][=<value>]
## Setting Configuration Values
You can set configuration values by putting an equal sign (=) into your config key. The key must always be the full `<section>.<key>` form.
Example:
```
$ qmk config default.keymap=default
default.keymap: None -> default
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
```
## Reading Configuration Values
You can read configuration values for the entire configuration, a single key, or for an entire section. You can also specify multiple keys to display more than one value.
### Entire Configuration Example
qmk config
### Whole Section Example
qmk config compile
### Single Key Example
qmk config compile.keyboard
### Multiple Keys Example
qmk config user compile.keyboard compile.keymap
## Deleting Configuration Values
You can delete a configuration value by setting it to the special string `None`.
Example:
```
$ qmk config default.keymap=None
default.keymap: default -> None
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
```
## Multiple Operations
You can combine multiple read and write operations into a single command. They will be executed and displayed in order:
```
$ qmk config compile default.keymap=default compile.keymap=None
compile.keymap=skully
compile.keyboard=clueboard/66_hotswap/gen1
default.keymap: None -> default
compile.keymap: skully -> None
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
```
# User Configuration Options
| Key | Default Value | Description |
|-----|---------------|-------------|
| user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
| user.keymap | None | The keymap name (Example: `default`) |
| user.name | None | The user's GitHub username. |
# All Configuration Options
| Key | Default Value | Description |
|-----|---------------|-------------|
| compile.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
| compile.keymap | None | The keymap name (Example: `default`) |
| hello.name | None | The name to greet when run. |
| new_keyboard.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
| new_keyboard.keymap | None | The keymap name (Example: `default`) |

219
cli_development.md Normal file
View File

@ -0,0 +1,219 @@
# QMK CLI Development
This document has useful information for developers wishing to write new `qmk` subcommands.
# Overview
The QMK CLI operates using the subcommand pattern made famous by git. The main `qmk` script is simply there to setup the environment and pick the correct entrypoint to run. Each subcommand is a self-contained module with an entrypoint (decorated by `@cli.subcommand()`) that performs some action and returns a shell returncode, or None.
## Developer mode:
If you intend to maintain keyboards and/or contribute to QMK, you can enable the CLI's "Developer" mode:
`qmk config user.developer=True`
This will allow you to see all available subcommands.
**Note:** You will have to install additional requirements:
```bash
python3 -m pip install -r requirements-dev.txt
```
# Subcommands
[MILC](https://github.com/clueboard/milc) is the CLI framework `qmk` uses to handle argument parsing, configuration, logging, and many other features. It lets you focus on writing your tool without wasting your time writing glue code.
Subcommands in the local CLI are always found in `qmk_firmware/lib/python/qmk/cli`.
Let's start by looking at an example subcommand. This is `lib/python/qmk/cli/hello.py`:
```python
"""QMK Python Hello World
This is an example QMK CLI script.
"""
from milc import cli
@cli.argument('-n', '--name', default='World', help='Name to greet.')
@cli.subcommand('QMK Hello World.')
def hello(cli):
"""Log a friendly greeting.
"""
cli.log.info('Hello, %s!', cli.config.hello.name)
```
First we import the `cli` object from `milc`. This is how we interact with the user and control the script's behavior. We use `@cli.argument()` to define a command line flag, `--name`. This also creates a configuration variable named `hello.name` (and the corresponding `user.name`) which the user can set so they don't have to specify the argument. The `cli.subcommand()` decorator designates this function as a subcommand. The name of the subcommand will be taken from the name of the function.
Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.6/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator.
# User Interaction
MILC and the QMK CLI have several nice tools for interacting with the user. Using these standard tools will allow you to colorize your text for easier interactions, and allow the user to control when and how that information is displayed and stored.
## Printing Text
There are two main methods for outputting text in a subcommand- `cli.log` and `cli.echo()`. They operate in similar ways but you should prefer to use `cli.log.info()` for most general purpose printing.
You can use special tokens to colorize your text, to make it easier to understand the output of your program. See [Colorizing Text](#colorizing-text) below.
Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.6/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example.
You should never use the format operator (`%`) directly, always pass values as arguments.
### Logging (`cli.log`)
The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.6/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong.
The default log level is `INFO`. If the user runs `qmk -v <subcommand>` the default log level will be set to `DEBUG`.
| Function | Emoji |
|----------|-------|
| cli.log.critical | `{bg_red}{fg_white}¬_¬{style_reset_all}` |
| cli.log.error | `{fg_red}☒{style_reset_all}` |
| cli.log.warning | `{fg_yellow}⚠{style_reset_all}` |
| cli.log.info | `{fg_blue}Ψ{style_reset_all}` |
| cli.log.debug | `{fg_cyan}☐{style_reset_all}` |
| cli.log.notset | `{style_reset_all}¯\\_(o_o)_/¯` |
### Printing (`cli.echo`)
Sometimes you simply need to print text outside of the log system. This is appropriate if you are outputting fixed data or writing out something that should never be logged. Most of the time you should prefer `cli.log.info()` over `cli.echo`.
### Colorizing Text
You can colorize the output of your text by including color tokens within text. Use color to highlight, not to convey information. Remember that the user can disable color, and your subcommand should still be usable if they do.
You should generally avoid setting the background color, unless it's integral to what you are doing. Remember that users have a lot of preferences when it comes to their terminal color, so you should pick colors that work well against both black and white backgrounds.
Colors prefixed with 'fg' will affect the foreground (text) color. Colors prefixed with 'bg' will affect the background color.
| Color | Background | Extended Background | Foreground | Extended Foreground|
|-------|------------|---------------------|------------|--------------------|
| Black | {bg_black} | {bg_lightblack_ex} | {fg_black} | {fg_lightblack_ex} |
| Blue | {bg_blue} | {bg_lightblue_ex} | {fg_blue} | {fg_lightblue_ex} |
| Cyan | {bg_cyan} | {bg_lightcyan_ex} | {fg_cyan} | {fg_lightcyan_ex} |
| Green | {bg_green} | {bg_lightgreen_ex} | {fg_green} | {fg_lightgreen_ex} |
| Magenta | {bg_magenta} | {bg_lightmagenta_ex} | {fg_magenta} | {fg_lightmagenta_ex} |
| Red | {bg_red} | {bg_lightred_ex} | {fg_red} | {fg_lightred_ex} |
| White | {bg_white} | {bg_lightwhite_ex} | {fg_white} | {fg_lightwhite_ex} |
| Yellow | {bg_yellow} | {bg_lightyellow_ex} | {fg_yellow} | {fg_lightyellow_ex} |
There are also control sequences that can be used to change the behavior of
ANSI output:
| Control Sequences | Description |
|-------------------|-------------|
| {style_bright} | Make the text brighter |
| {style_dim} | Make the text dimmer |
| {style_normal} | Make the text normal (neither `{style_bright}` nor `{style_dim}`) |
| {style_reset_all} | Reset all text attributes to default. (This is automatically added to the end of every string.) |
| {bg_reset} | Reset the background color to the user's default |
| {fg_reset} | Reset the foreground color to the user's default |
# Arguments and Configuration
QMK handles the details of argument parsing and configuration for you. When you add a new argument it is automatically incorporated into the config tree based on your subcommand's name and the long name of the argument. You can access this configuration in `cli.config`, using either attribute-style access (`cli.config.<subcommand>.<argument>`) or dictionary-style access (`cli.config['<subcommand>']['<argument>']`).
Under the hood QMK uses [ConfigParser](https://docs.python.org/3/library/configparser.html) to store configurations. This gives us an easy and straightforward way to represent the configuration in a human-editable way. We have wrapped access to this configuration to provide some nicities that ConfigParser does not normally have.
## Reading Configuration Values
You can interact with `cli.config` in all the ways you'd normally expect. For example the `qmk compile` command gets the keyboard name from `cli.config.compile.keyboard`. It does not need to know whether that value came from the command line, an environment variable, or the configuration file.
Iteration is also supported:
```
for section in cli.config:
for key in cli.config[section]:
cli.log.info('%s.%s: %s', section, key, cli.config[section][key])
```
## Setting Configuration Values
You can set configuration values in the usual ways.
Dictionary style:
```
cli.config['<section>']['<key>'] = <value>
```
Attribute style:
```
cli.config.<section>.<key> = <value>
```
## Deleting Configuration Values
You can delete configuration values in the usual ways.
Dictionary style:
```
del(cli.config['<section>']['<key>'])
```
Attribute style:
```
del(cli.config.<section>.<key>)
```
## Writing The Configuration File
The configuration is not written out when it is changed. Most commands do not need to do this. We prefer to have the user change their configuration deliberitely using `qmk config`.
You can use `cli.save_config()` to write out the configuration.
## Excluding Arguments From Configuration
Some arguments should not be propagated to the configuration file. These can be excluded by adding `arg_only=True` when creating the argument.
Example:
```
@cli.argument('-o', '--output', arg_only=True, help='File to write to')
@cli.argument('filename', arg_only=True, help='Configurator JSON file')
@cli.subcommand('Create a keymap.c from a QMK Configurator export.')
def json_keymap(cli):
pass
```
You will only be able to access these arguments using `cli.args`. For example:
```
cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.output)
```
# Testing, and Linting, and Formatting (oh my!)
We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `pyformat` subcommands to run these tests:
### Testing and Linting
qmk pytest
### Formatting
qmk pyformat
## Formatting Details
We use [yapf](https://github.com/google/yapf) to automatically format code. Our configuration is in the `[yapf]` section of `setup.cfg`.
?> Tip- Many editors can use yapf as a plugin to automatically format code as you type.
## Testing Details
Our tests can be found in `lib/python/qmk/tests/`. You will find both unit and integration tests in this directory. We hope you will write both unit and integration tests for your code, but if you do not please favor integration tests.
If your PR does not include a comprehensive set of tests please add comments like this to your code so that other people know where they can help:
# TODO(unassigned/<your_github_username>): Write <unit|integration> tests
We use [nose2](https://nose2.readthedocs.io/en/latest/getting_started.html) to run our tests. You can refer to the nose2 documentation for more details on what you can do in your test functions.
## Linting Details
We use flake8 to lint our code. Your code should pass flake8 before you open a PR. This will be checked when you run `qmk pytest` and by CI when you submit a PR.

58
coding_conventions_c.md Normal file
View File

@ -0,0 +1,58 @@
# Coding Conventions (C)
Most of our style is pretty easy to pick up on, but right now it's not entirely consistent. You should match the style of the code surrounding your change, but if that code is inconsistent or unclear use the following guidelines:
* We indent using four (4) spaces (soft tabs)
* We use a modified One True Brace Style
* Opening Brace: At the end of the same line as the statement that opens the block
* Closing Brace: Lined up with the first character of the statement that opens the block
* Else If: Place the closing brace at the beginning of the line and the next opening brace at the end of the same line.
* Optional Braces: Always include optional braces.
* Good: if (condition) { return false; }
* Bad: if (condition) return false;
* We encourage use of C style comments: `/* */`
* Think of them as a story describing the feature
* Use them liberally to explain why particular decisions were made.
* Do not write obvious comments
* If you're not sure if a comment is obvious, go ahead and include it.
* In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
* We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)
* We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)`
* If you are not sure which to prefer use the `#if defined(DEFINED)` form.
* Do not change existing code from one style to the other, except when moving to a multiple condition `#if`.
* When deciding how (or if) to indent preprocessor directives, keep these points in mind:
* Readability is more important than consistency.
* Follow the file's existing style. If the file is mixed, follow the style that makes sense for the section you are modifying.
* When indenting, keep the hash at the start of the line and add whitespace between `#` and `if`, starting with 4 spaces after the `#`.
* You can follow the indention level of the surrounding C code, or preprocessor directives can have their own indentation levels. Choose the style that best communicates the intent of your code.
Here is an example for easy reference:
```c
/* Enums for foo */
enum foo_state {
FOO_BAR,
FOO_BAZ,
};
/* Returns a value */
int foo(void) {
if (some_condition) {
return FOO_BAR;
} else {
return -1;
}
}
```
# Auto-formatting with clang-format
[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) is part of LLVM and can automatically format your code for you, because ain't nobody got time to do it manually. We supply a configuration file for it that applies most of the coding conventions listed above. It will only change whitespace and newlines, so you will still have to remember to include optional braces yourself.
Use the [full LLVM installer](http://llvm.org/builds/) to get clang-format on Windows, or use `sudo apt install clang-format` on Ubuntu.
If you run it from the command-line, pass `-style=file` as an option and it will automatically find the .clang-format configuration file in the QMK root directory.
If you use VSCode, the standard C/C++ plugin supports clang-format, alternatively there is a [separate extension](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat) for it.
Some things (like LAYOUT macros) are destroyed by clang-format, so either don't run it on those files, or wrap the sensitive code in `// clang-format off` and `// clang-format on`.

326
coding_conventions_python.md Normal file
View File

@ -0,0 +1,326 @@
# Coding Conventions (Python)
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 indent using four (4) spaces (soft tabs)
* We encourage liberal use of comments
* Think of them as a story describing the feature
* Use them liberally to explain why particular decisions were made.
* Do not write obvious comments
* If you're not sure if a comment is obvious, go ahead and include it.
* We require useful docstrings for all functions.
* In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
* Some of our practices conflict with the wider python community to make our codebase more approachable to non-pythonistas.
# YAPF
You can use [yapf](https://github.com/google/yapf) to style your code. We provide a config in [setup.cfg](setup.cfg).
# Imports
We don't have a hard and fast rule for when to use `import ...` vs `from ... import ...`. Understandability and maintainability is our ultimate goal.
Generally we prefer to import specific function and class names from a module to keep code shorter and easier to understand. Sometimes this results in a name that is ambiguous, and in such cases we prefer to import the module instead. You should avoid using the "as" keyword when importing, unless you are importing a compatability module.
Imports should be one line per module. We group import statements together using the standard python rules- system, 3rd party, local.
Do not use `from foo import *`. Supply a list of objects you want to import instead, or import the whole module.
## Import Examples
Good:
```
from qmk import effects
effects.echo()
```
Bad:
```
from qmk.effects import echo
echo() # It's unclear where echo comes from
```
Good:
```
from qmk.keymap import compile_firmware
compile_firmware()
```
OK, but the above is better:
```
import qmk.keymap
qmk.keymap.compile_firmware()
```
# Statements
One statement per line.
Even when allowed (EG `if foo: bar`) we do not combine 2 statements onto a single line.
# Naming
`module_name`, `package_name`, `ClassName`, `method_name`, `ExceptionName`, `function_name`, `GLOBAL_CONSTANT_NAME`, `global_var_name`, `instance_var_name`, `function_parameter_name`, `local_var_name`.
Function names, variable names, and filenames should be descriptive; eschew abbreviation. In particular, do not use abbreviations that are ambiguous or unfamiliar to readers outside your project, and do not abbreviate by deleting letters within a word.
Always use a .py filename extension. Never use dashes.
## Names to Avoid
* single character names except for counters or iterators. You may use `e` as an exception identifier in try/except statements.
* dashes (`-`) in any package/module name
* `__double_leading_and_trailing_underscore__` names (reserved by Python)
# Docstrings
To maintain consistency with our docstrings we've set out the following guidelines.
* Use markdown formatting
* Always use triple-dquote docstrings with at least one linebreak: `"""\n"""`
* First line is a short (< 70 char) description of what the function does
* If you need more in your docstring leave a blank line between the description and the rest.
* Start indented lines at the same indent level as the opening triple-dquote
* Document all function arguments using the format described below
* If present, Args:, Returns:, and Raises: should be the last three things in the docstring, separated by a blank line each.
## Simple docstring example
```
def my_awesome_function():
"""Return the number of seconds since 1970 Jan 1 00:00 UTC.
"""
return int(time.time())
```
## Complex docstring example
```
def my_awesome_function():
"""Return the number of seconds since 1970 Jan 1 00:00 UTC.
This function always returns an integer number of seconds.
"""
return int(time.time())
```
## Function arguments docstring example
```
def my_awesome_function(start=None, offset=0):
"""Return the number of seconds since 1970 Jan 1 00:00 UTC.
This function always returns an integer number of seconds.
Args:
start
The time to start at instead of 1970 Jan 1 00:00 UTC
offset
Return an answer that has this number of seconds subtracted first
Returns:
An integer describing a number of seconds.
Raises:
ValueError
When `start` or `offset` are not positive numbers
"""
if start < 0 or offset < 0:
raise ValueError('start and offset must be positive numbers.')
if not start:
start = time.time()
return int(start - offset)
```
# Exceptions
Exceptions are used to handle exceptional situations. They should not be used for flow control. This is a break from the python norm of "ask for forgiveness." If you are catching an exception it should be to handle a situation that is unusual.
If you use a catch-all exception for any reason you must log the exception and stacktrace using cli.log.
Make your try/except blocks as short as possible. If you need a lot of try statements you may need to restructure your code.
# Tuples
When defining one-item tuples always include a trailing comma so that it is obvious you are using a tuple. Do not rely on implicit one-item tuple unpacking. Better still use a list which is unambiguous.
This is particularly important when using the printf-style format strings that are commonly used.
# Lists and Dictionaries
We have configured YAPF to differentiate between sequence styles with a trailing comma. When a trailing comma is omitted YAPF will format the sequence as a single line. When a trailing comma is included YAPF will format the sequence with one item per line.
You should generally prefer to keep short definition on a single line. Break out to multiple lines sooner rather than later to aid readability and maintainability.
# Parentheses
Avoid excessive parentheses, but do use parentheses to make code easier to understand. Do not use them in return statements unless you are explicitly returning a tuple, or it is part of a math expression.
# Format Strings
We generally prefer printf-style format strings. Example:
```
name = 'World'
print('Hello, %s!' % (name,))
```
This style is used by the logging module, which we make use of extensively, and we have adopted it in other places for consistency. It is also more familiar to C programmers, who are a big part of our casual audience.
Our included CLI module has support for using these without using the percent (%) operator. Look at `cli.echo()` and the various `cli.log` functions (EG, `cli.log.info()`) for more details.
# Comprehensions & Generator Expressions
We encourage the liberal use of comprehensions and generators, but do not let them get too complex. If you need complexity fall back to a for loop that is easier to understand.
# Lambdas
OK to use but probably should be avoided. With comprehensions and generators the need for lambdas is not as strong as it once was.
# Conditional Expressions
OK in variable assignment, but otherwise should be avoided.
Conditional expressions are if statements that are in line with code. For example:
```
x = 1 if cond else 2
```
It's generally not a good idea to use these as function arguments, sequence items, etc. It's too easy to overlook.
# Default Argument Values
Encouraged, but values must be immutable objects.
When specifying default values in argument lists always be careful to specify objects that can't be modified in place. If you use a mutable object the changes you make will persist between calls, which is usually not what you want. Even if that is what you intend to do it is confusing for others and will hinder understanding.
Bad:
```
def my_func(foo={}):
pass
```
Good:
```
def my_func(foo=None):
if not foo:
foo = {}
```
# Properties
Always use properties instead of getter and setter functions.
```
class Foo(object):
def __init__(self):
self._bar = None
@property
def bar(self):
return self._bar
@bar.setter
def bar(self, bar):
self._bar = bar
```
# True/False Evaluations
You should generally prefer the implicit True/False evaluation in if statements, rather than checking equivalency.
Bad:
```
if foo == True:
pass
if bar == False:
pass
```
Good:
```
if foo:
pass
if not bar:
pass
```
# Decorators
Use when appropriate. Try to avoid too much magic unless it helps with understanding.
# Threading and Multiprocessing
Should be avoided. If you need this you will have to make a strong case before we merge your code.
# Power Features
Python is an extremely flexible language and gives you many fancy features such as custom metaclasses, access to bytecode, on-the-fly compilation, dynamic inheritance, object reparenting, import hacks, reflection, modification of system internals, etc.
Don't use these.
Performance is not a critical concern for us, and code understandability is. We want our codebase to be approachable by someone who only has a day or two to play with it. These features generally come with a cost to easy understanding, and we would prefer to have code that can be readily understood over faster or more compact code.
Note that some standard library modules use these techniques and it is ok to make use of those modules. But please keep readability and understandability in mind when using them.
# Type Annotated Code
For now we are not using any type annotation system, and would prefer that code remain unannotated. We may revisit this in the future.
# Function length
Prefer small and focused functions.
We recognize that long functions are sometimes appropriate, so no hard limit is placed on function length. If a function exceeds about 40 lines, think about whether it can be broken up without harming the structure of the program.
Even if your long function works perfectly now, someone modifying it in a few months may add new behavior. This could result in bugs that are hard to find. Keeping your functions short and simple makes it easier for other people to read and modify your code.
You could find long and complicated functions when working with some code. Do not be intimidated by modifying existing code: if working with such a function proves to be difficult, you find that errors are hard to debug, or you want to use a piece of it in several different contexts, consider breaking up the function into smaller and more manageable pieces.
# FIXMEs
It is OK to leave FIXMEs in code. Why? Encouraging people to at least document parts of code that need to be thought out more (or that are confusing) is better than leaving this code undocumented.
All FIXMEs should be formatted like:
```
FIXME(username): Revisit this code when the frob feature is done.
```
...where username is your GitHub username.
# Testing
We use a combination of Integration and Unit testing to ensure that the our code is as bug-free as possible. All the tests can be found in `lib/python/qmk/tests/`. You can run all the tests with `qmk pytest`.
At the time of this writing our tests are not very comprehensive. Looking at the current tests and writing new test cases for untested situations is a great way to both familiarize yourself with the codebase and contribute to QMK.
## Integration Tests
Integration tests can be found in `lib/python/qmk/tests/test_cli_commands.py`. This is where CLI commands are actually run and their overall behavior is verified. We use [`subprocess`](https://docs.python.org/3.6/library/subprocess.html#module-subprocess) to launch each CLI command and a combination of checking output and returncode to determine if the right thing happened.
## Unit Tests
The other `test_*.py` files in `lib/python/qmk/tests/` contain unit tests. You can write tests for individual functions inside `lib/python/qmk/` here. Generally these files are named after the module, with dots replaced by underscores.
At the time of this writing we do not do any mocking for our tests. If you would like to help us change this please [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there.

37
compatible_microcontrollers.md Normal file
View File

@ -0,0 +1,37 @@
# Compatible Microcontrollers
QMK runs on any USB-capable AVR or ARM microcontroller with enough flash space - generally 32kB or more, though it will *just* squeeze into 16kB with most features disabled.
## Atmel AVR
The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB stack:
* [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2)
* [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4)
* [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286)
Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/products/vusb/index.html) instead:
* [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A)
* [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P)
* [ATmega328](https://www.microchip.com/wwwproducts/en/ATmega328)
## ARM
You can also use any ARM chip with USB that [ChibiOS](http://www.chibios.org) supports. Most have plenty of flash. Known to work are:
### STMicroelectronics (STM32)
* [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html)
* [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
* [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
### 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)
## 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).

414
config_options.md Normal file
View File

@ -0,0 +1,414 @@
# Configuring QMK
QMK is nearly infinitely configurable. Wherever possible we err on the side of allowing users to customize their keyboard, even at the expense of code size. That level of flexibility makes for a daunting configuration experience, however.
There are two main types of configuration files in QMK- `config.h` and `rules.mk`. These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are:
* QMK Default
* Keyboard
* Folders (Up to 5 levels deep)
* Keymap
## QMK Default
Every available setting in QMK has a default. If that setting is not set at the Keyboard, Folder, or Keymap level this is the setting that will be used.
## Keyboard
This level contains config options that should apply to the whole keyboard. Some settings won't change in revisions, or most keymaps. Other settings are merely defaults for this keyboard and can be overridden by folders and/or keymaps.
## Folders
Some keyboards have folders and sub-folders to allow for different hardware configurations. Most keyboards only go 1 folder deep, but QMK supports structures up to 5 folders deep. Each folder can have its own `config.h` and `rules.mk` files that are incorporated into the final configuration.
## Keymap
This level contains all of the options for that particular keymap. If you wish to override a previous declaration, you can use `#undef <variable>` to undefine it, where you can then redefine it without an error.
# The `config.h` File
This is a C header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere. The `config.h` file shouldn't be including other `config.h` files, or anything besides this:
#include "config_common.h"
## Hardware Options
* `#define VENDOR_ID 0x1234`
* defines your VID, and for most DIY projects, can be whatever you want
* `#define PRODUCT_ID 0x5678`
* defines your PID, and for most DIY projects, can be whatever you want
* `#define DEVICE_VER 0`
* defines the device version (often used for revisions)
* `#define MANUFACTURER Me`
* generally who/whatever brand produced the board
* `#define PRODUCT Board`
* the name of the keyboard
* `#define MATRIX_ROWS 5`
* the number of rows in your keyboard's matrix
* `#define MATRIX_COLS 15`
* the number of columns in your keyboard's matrix
* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
* pins of the rows, from top to bottom
* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
* pins of the columns, from left to right
* `#define MATRIX_IO_DELAY 30`
* the delay in microseconds when between changing matrix pin state and reading values
* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
* pins unused by the keyboard for reference
* `#define MATRIX_HAS_GHOST`
* define is matrix has ghost (unlikely)
* `#define DIODE_DIRECTION COL2ROW`
* COL2ROW or ROW2COL - how your matrix is configured. COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows.
* `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
* pins mapped to rows and columns, from left to right. Defines a matrix where each switch is connected to a separate pin and ground.
* `#define AUDIO_VOICES`
* turns on the alternate audio voices (to cycle through)
* `#define C4_AUDIO`
* enables audio on pin C4
* `#define C5_AUDIO`
* enables audio on pin C5
* `#define C6_AUDIO`
* enables audio on pin C6
* `#define B5_AUDIO`
* enables audio on pin B5 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
* `#define B6_AUDIO`
* enables audio on pin B6 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
* `#define B7_AUDIO`
* enables audio on pin B7 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
* `#define BACKLIGHT_PIN B7`
* pin of the backlight
* `#define BACKLIGHT_LEVELS 3`
* number of levels your backlight will have (maximum 31 excluding off)
* `#define BACKLIGHT_BREATHING`
* enables backlight breathing
* `#define BREATHING_PERIOD 6`
* the length of one backlight "breath" in seconds
* `#define DEBOUNCE 5`
* the delay when reading the value of the pin (5 is default)
* `#define LOCKING_SUPPORT_ENABLE`
* mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
* `#define LOCKING_RESYNC_ENABLE`
* tries to keep switch state consistent with keyboard LED state
* `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)`
* key combination that allows the use of magic commands (useful for debugging)
* `#define USB_MAX_POWER_CONSUMPTION 500`
* sets the maximum power (in mA) over USB for the device (default: 500)
* `#define USB_POLLING_INTERVAL_MS 10`
* sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces
* `#define F_SCL 100000L`
* sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`.
## Features That Can Be Disabled
If you define these options you will disable the associated feature, which can save on code size.
* `#define NO_DEBUG`
* disable debugging
* `#define NO_PRINT`
* disable printing/debugging using hid_listen
* `#define NO_ACTION_LAYER`
* disable layers
* `#define NO_ACTION_TAPPING`
* disable tap dance and other tapping features
* `#define NO_ACTION_ONESHOT`
* disable one-shot modifiers
* `#define NO_ACTION_MACRO`
* disable old-style macro handling using `MACRO()`, `action_get_macro()` _(deprecated)_
* `#define NO_ACTION_FUNCTION`
* disable old-style function handling using `fn_actions`, `action_function()` _(deprecated)_
## Features That Can Be Enabled
If you define these options you will enable the associated feature, which may increase your code size.
* `#define FORCE_NKRO`
* NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
* `#define STRICT_LAYER_RELEASE`
* force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases)
## Behaviors That Can Be Configured
* `#define TAPPING_TERM 200`
* how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too
* `#define TAPPING_TERM_PER_KEY`
* enables handling for per key `TAPPING_TERM` settings
* `#define RETRO_TAPPING`
* tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
* See [Retro Tapping](tap_hold.md#retro-tapping) for details
* `#define TAPPING_TOGGLE 2`
* how many taps before triggering the toggle
* `#define PERMISSIVE_HOLD`
* makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
* See [Permissive Hold](tap_hold.md#permissive-hold) for details
* `#define PERMISSIVE_HOLD_PER_KEY`
* enabled handling for per key `PERMISSIVE_HOLD` settings
* `#define IGNORE_MOD_TAP_INTERRUPT`
* makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
* See [Ignore Mod Tap Interrupt](tap_hold.md#ignore-mod-tap-interrupt) for details
* `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
* enables handling for per key `IGNORE_MOD_TAP_INTERRUPT` settings
* `#define TAPPING_FORCE_HOLD`
* makes it possible to use a dual role key as modifier shortly after having been tapped
* See [Tapping Force Hold](tap_hold.md#tapping-force-hold)
* Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
* `#define TAPPING_FORCE_HOLD_PER_KEY`
* enables handling for per key `TAPPING_FORCE_HOLD` settings
* `#define LEADER_TIMEOUT 300`
* how long before the leader key times out
* If you're having issues finishing the sequence before it times out, you may need to increase the timeout setting. Or you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped.
* `#define LEADER_PER_KEY_TIMING`
* sets the timer for leader key chords to run on each key press rather than overall
* `#define LEADER_KEY_STRICT_KEY_PROCESSING`
* Disables keycode filtering for Mod-Tap and Layer-Tap keycodes. Eg, if you enable this, you would need to specify `MT(MOD_CTL, KC_A)` if you want to use `KC_A`.
* `#define ONESHOT_TIMEOUT 300`
* how long before oneshot times out
* `#define ONESHOT_TAP_TOGGLE 2`
* how many taps before oneshot toggle is triggered
* `#define QMK_KEYS_PER_SCAN 4`
* Allows sending more than one key per scan. By default, only one key event gets
sent via `process_record()` per scan. This has little impact on most typing, but
if you're doing a lot of chords, or your scan rate is slow to begin with, you can
have some delay in processing key events. Each press and release is a separate
event. For a keyboard with 1ms or so scan times, even a very fast typist isn't
going to produce the 500 keystrokes a second needed to actually get more than a
few ms of delay from this. But if you're doing chording on something with 3-4ms
scan times? You probably want this.
* `#define COMBO_COUNT 2`
* Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
* `#define COMBO_TERM 200`
* how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
* `#define TAP_CODE_DELAY 100`
* Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds.
* `#define TAP_HOLD_CAPS_DELAY 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.
## RGB Light Configuration
* `#define RGB_DI_PIN D7`
* pin the DI on the WS2812 is hooked-up to
* `#define RGBLIGHT_ANIMATIONS`
* run RGB animations
* `#define RGBLIGHT_LAYERS`
* Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
* `#define RGBLIGHT_MAX_LAYERS`
* Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed.
* Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards.
* `#define RGBLIGHT_LAYER_BLINK`
* Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF`
* If defined, then [lighting layers](feature_rgblight?id=overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off.
* `#define RGBLED_NUM 12`
* number of LEDs
* `#define RGBLIGHT_SPLIT`
* Needed if both halves of the board have RGB LEDs wired directly to the RGB output pin on the controllers instead of passing the output of the left half to the input of the right half
* `#define RGBLED_SPLIT { 6, 6 }`
* number of LEDs connected that are directly wired to `RGB_DI_PIN` on each half of a split keyboard
* First value indicates number of LEDs for left half, second value is for the right half
* When RGBLED_SPLIT is defined, RGBLIGHT_SPLIT is implicitly defined.
* `#define RGBLIGHT_HUE_STEP 12`
* units to step when in/decreasing hue
* `#define RGBLIGHT_SAT_STEP 25`
* units to step when in/decreasing saturation
* `#define RGBLIGHT_VAL_STEP 12`
* units to step when in/decreasing value (brightness)
* `#define RGBW`
* Enables RGBW LED support
## Mouse Key Options
* `#define MOUSEKEY_INTERVAL 20`
* `#define MOUSEKEY_DELAY 0`
* `#define MOUSEKEY_TIME_TO_MAX 60`
* `#define MOUSEKEY_MAX_SPEED 7`
* `#define MOUSEKEY_WHEEL_DELAY 0`
## Split Keyboard Options
Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
* `SPLIT_TRANSPORT = custom`
* Allows replacing the standard split communication routines with a custom one. ARM based split keyboards must use this at present.
### Setting Handedness
One thing to remember, the side that the USB port is plugged into is always the master half. The side not plugged into USB is the slave.
There are a few different ways to set handedness for split keyboards (listed in order of precedence):
1. Set `SPLIT_HAND_PIN`: Reads a pin to determine handedness. If pin is high, it's the left side, if low, the half is determined to be the right side
2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half
* For boards with DFU bootloader you can use `:dfu-split-left`/`:dfu-split-right` to flash these EEPROM files
* For boards with Caterina bootloader (like stock Pro Micros), use `:avrdude-split-left`/`:avrdude-split-right`
* For boards with ARM DFU bootloader (like Proton C), use `:dfu-util-split-left`/`:dfu-util-split-right`
3. Set `MASTER_RIGHT`: Half that is plugged into the USB port is determined to be the master and right half (inverse of the default)
4. Default: The side that is plugged into the USB port is the master half and is assumed to be the left half. The slave side is the right half
#### Defines for handedness
* `#define SPLIT_HAND_PIN B7`
* For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
* `#define SPLIT_HAND_MATRIX_GRID <out_pin>,<in_pin>`
* The handedness is determined by using the intersection of the keyswitches in the key matrix, which does not exist. Normally, when this intersection is shorted (level low), it is considered left. If you define `#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT`, it is determined to be right when the level is low.
* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` and `SPLIT_HAND_MATRIX_GRID` are not defined)
* Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves.
* `#define MASTER_RIGHT`
* Master half is defined to be the right half.
### Other Options
* `#define USE_I2C`
* For using I2C instead of Serial (defaults to serial)
* `#define SOFT_SERIAL_PIN D0`
* When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
* `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
* If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns.
* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
* If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`.
* `#define RGBLED_SPLIT { 6, 6 }`
* See [RGB Light Configuration](#rgb-light-configuration)
* `#define SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1)
* Sets the protocol speed when using serial communication
* Speeds:
* 0: about 189kbps (Experimental only)
* 1: about 137kbps (default)
* 2: about 75kbps
* 3: about 39kbps
* 4: about 26kbps
* 5: about 20kbps
* `#define SPLIT_USB_DETECT`
* Detect (with timeout) USB connection when delegating master/slave
* Default behavior for ARM
* Required for AVR Teensy
* `#define SPLIT_USB_TIMEOUT 2000`
* Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`
* `#define SPLIT_USB_TIMEOUT_POLL 10`
* Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
# The `rules.mk` File
This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
## Build Options
* `DEFAULT_FOLDER`
* Used to specify a default folder when a keyboard has more than one sub-folder.
* `FIRMWARE_FORMAT`
* Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
* `SRC`
* Used to add files to the compilation/linking list.
* `LIB_SRC`
* Used to add files as a library to the compilation/linking list.
The files specified by `LIB_SRC` is linked after the files specified by `SRC`.
For example, if you specify:
```
SRC += a.c
LIB_SRC += lib_b.c
SRC += c.c
LIB_SRC += lib_d.c
```
The link order is as follows.
```
... a.o c.o ... lib_b.a lib_d.a ...
```
* `LAYOUTS`
* A list of [layouts](feature_layouts.md) this keyboard supports.
* `LTO_ENABLE`
* Enables Link Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).
However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`. (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).)
## AVR MCU Options
* `MCU = atmega32u4`
* `F_CPU = 16000000`
* `ARCH = AVR8`
* `F_USB = $(F_CPU)`
* `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
* `BOOTLOADER = atmel-dfu` with the following options:
* `atmel-dfu`
* `lufa-dfu`
* `qmk-dfu`
* `halfkay`
* `caterina`
* `bootloadHID`
* `USBasp`
## Feature Options :id=feature-options
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.
* `BOOTMAGIC_ENABLE`
* Virtual DIP switch configuration
* `MOUSEKEY_ENABLE`
* Mouse keys
* `EXTRAKEY_ENABLE`
* Audio control and System control
* `CONSOLE_ENABLE`
* Console for debug
* `COMMAND_ENABLE`
* Commands for debug and configuration
* `COMBO_ENABLE`
* 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
* `AUDIO_ENABLE`
* Enable the audio subsystem.
* `RGBLIGHT_ENABLE`
* Enable keyboard underlight functionality
* `LEADER_ENABLE`
* Enable leader key chording
* `MIDI_ENABLE`
* MIDI controls
* `UNICODE_ENABLE`
* Unicode
* `BLUETOOTH`
* Current options are AdafruitBLE, RN42
* `SPLIT_KEYBOARD`
* Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
* `CUSTOM_MATRIX`
* Allows replacing the standard matrix scanning routine with a custom one.
* `DEBOUNCE_TYPE`
* Allows replacing the standard key debouncing routine with an alternative or custom one.
* `WAIT_FOR_USB`
* 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.
## USB Endpoint Limitations
In order to provide services over USB, QMK has to use USB endpoints.
These are a finite resource: each microcontroller has only a certain number.
This limits what features can be enabled together.
If the available endpoints are exceeded, a build error is thrown.
The following features can require separate endpoints:
* `MOUSEKEY_ENABLE`
* `EXTRAKEY_ENABLE`
* `CONSOLE_ENABLE`
* `NKRO_ENABLE`
* `MIDI_ENABLE`
* `RAW_ENABLE`
* `VIRTSER_ENABLE`
In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint.
By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint.
The base keyboard functionality can also be combined into the endpoint,
by setting `KEYBOARD_SHARED_EP = yes`.
This frees up one more endpoint,
but it can prevent the keyboard working in some BIOSes,
as they do not implement Boot Keyboard protocol switching.
Combining the mouse also breaks Boot Mouse compatibility.
The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.

193
configurator_default_keymaps.md Normal file
View File

@ -0,0 +1,193 @@
# Adding Default Keymaps to QMK Configurator :id=adding-default-keymaps
This page covers how to add a default keymap for a keyboard to QMK Configurator.
## Technical Information :id=technical-information
QMK Configurator uses JSON as its native file format for keymaps. As much as possible, these should be kept such that they behave the same as running `make <keyboard>:default` from `qmk_firmware`.
Keymaps in this directory require four key-value pairs:
* `keyboard` (string)
* This is the name of the keyboard, the same as would be used when running a compile job through `make` (e.g. `make 1upkeyboards/1up60rgb:default`).
* `keymap` (string)
* Should be set to `default`.
* `layout` (string)
* This is the layout macro used by the default keymap.
* `layers` (array)
* The keymap itself. This key should contain one array per layer, which themselves should contain the keycodes that make up that layer.
Additionally, most keymaps contain a `commit` key. This key is not consumed by the API that back-stops QMK Configurator, but is used by Configurator's maintainers to tell which version of a keymap was used to create the JSON keymap in this repository. The value is the SHA of the last commit to modify a board's default `keymap.c` in the `qmk_firmware` repository. The SHA is found by checking out [the `master` branch of the `qmk/qmk_firmware` repository](https://github.com/qmk/qmk_firmware/tree/master/) and running `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c` (use `keymap.json` if the keyboard in question has this file instead), which should return something similar to:
```shell
f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625)
```
In this example, `f14629ed1cd7c7ec9089604d64f29a99981558e8` is the value that should be used for `commit`.
## Example :id=example
If one wished to add a default keymap for the H87a by Hineybush, one would run the `git log` command above against the H87a's default keymap in `qmk_firmware`:
```shell
user ~/qmk_firmware (master)
$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c
ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237)
```
Now that we have the commit hash, we need the keymap (edited for readability):
```c
...
#include QMK_KEYBOARD_H
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_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,
KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_TRNS, KC_UP,
KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_RGUI, KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT),
[1] = LAYOUT_all(
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RGB_TOG, RGB_MOD, RGB_HUD, RGB_HUI, RGB_SAD, RGB_SAI, RGB_VAD, RGB_VAI, BL_TOGG, BL_DEC, BL_INC,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_VOLU,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RESET, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_MPLY, KC_MNXT, KC_VOLD,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS),
};
```
The default keymap uses the `LAYOUT_all` macro, so that will be the value of the `layout` key. Compiled to a QMK Configurator JSON keymap, our resulting file should be:
```json
{
"keyboard": "hineybush/h87a",
"keymap": "default",
"commit": "ef8878fba5d3786e3f9c66436da63a560cd36ac9",
"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_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",
"KC_LSFT", "KC_NUBS", "KC_Z", "KC_X", "KC_C", "KC_V", "KC_B", "KC_N", "KC_M", "KC_COMM", "KC_DOT", "KC_SLSH", "KC_RSFT", "KC_TRNS", "KC_UP",
"KC_LCTL", "KC_LGUI", "KC_LALT", "KC_SPC", "KC_RALT", "MO(1)", "KC_RGUI", "KC_RCTL", "KC_LEFT", "KC_DOWN", "KC_RGHT"
],
[
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RGB_TOG", "RGB_MOD", "RGB_HUD", "RGB_HUI", "RGB_SAD", "RGB_SAI", "RGB_VAD", "RGB_VAI", "BL_TOGG", "BL_DEC", "BL_INC",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_VOLU",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RESET", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_MPLY", "KC_MNXT", "KC_VOLD",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS"
]
]
}
```
The white space in the `layers` arrays have no effect on the functionality of the keymap, but are used to make these files easier for humans to read.
## Caveats :id=caveats
### Layers can only be referenced by number :id=layer-references
A common QMK convention is to name layers using a series of `#define`s, or an `enum` statement:
```c
enum layer_names {
_BASE,
_MEDIA,
_FN
};
```
This works in C, but for Configurator, you *must* use the layer's numeric index – `MO(_FN)` would need to be `MO(2)` in the above example.
### No support for custom code of any kind :id=custom-code
Features that require adding functions to the keymap.c file, such as Tap Dance or Unicode, can not be compiled in Configurator **at all**. Even setting `TAP_DANCE_ENABLE = yes` in the `qmk_firmware` repository at the keyboard level will prevent Configurator from compiling **any** firmware for that keyboard. This is limited both by the API and the current spec of our JSON keymap format.
### Limited Support for Custom keycodes :id=custom-keycodes
There is a way to support custom keycodes: if the logic for a custom keycode is implemented at the keyboard level instead of the keymap level in qmk_firmware, that keycode *can* be used in Configurator and it *will* compile and work. Instead of using the following in your `keymap.c`:
```c
enum custom_keycodes {
MACRO_1 = SAFE_RANGE,
MACRO_2,
MACRO_3
};
...
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
case MACRO_1:
if (record->event.pressed) {
SEND_STRING("This is macro #1.");
}
return false;
case MACRO_2:
if (record->event.pressed) {
SEND_STRING("This is macro #2.");
}
return false;
case MACRO_3:
if (record->event.pressed) {
SEND_STRING("This is macro #3.");
}
return false;
}
return true;
};
```
... add the keycode `enum` block to your keyboard's header file (`<keyboard>.h`) as follows (note that the `enum` is named `keyboard_keycodes` here):
```c
enum keyboard_keycodes {
MACRO_1 = SAFE_RANGE,
MACRO_2,
MACRO_3,
NEW_SAFE_RANGE // Important!
};
```
... then the logic to your `<keyboard>.c` through `process_record_kb()`:
```c
bool process_record_kb(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
case MACRO_1:
if (record->event.pressed) {
SEND_STRING("This is macro #1.");
}
return false;
case MACRO_2:
if (record->event.pressed) {
SEND_STRING("This is macro #2.");
}
return false;
case MACRO_3:
if (record->event.pressed) {
SEND_STRING("This is macro #3.");
}
return false;
}
return process_record_user(keycode, record);
};
```
Note the call to `process_record_user()` at the end. Additionally, users of the keyboard will need to use `NEW_SAFE_RANGE` instead of `SAFE_RANGE` if they wish to add their own custom keycodes at keymap level, beyond what is provided by the keyboard.
## Additional Reading :id=additional-reading
For QMK Configurator to support your keyboard, your keyboard must be present in the `master` branch of the `qmk_firmware` repository. For instructions on this, please see [Supporting Your Keyboard in QMK Configurator](reference_configurator_support.md).

58
configurator_step_by_step.md Normal file
View File

@ -0,0 +1,58 @@
# QMK Configurator: Step by Step
This page describes the steps for building your firmware in QMK Configurator.
## Step 1: Select Your Keyboard
Click the drop down box and select the keyboard you want to create a keymap for.
?> If your keyboard has several versions, make sure you select the correct one.
I'll say that again because it's important:
!> **MAKE SURE YOU SELECT THE RIGHT VERSION!**
If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own GitHub accounts. Double check for that as well. <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
## Step 2: Select Your Keyboard Layout
Choose the layout that best represents the keymap you want to create. Some keyboards do not have enough layouts or correct layouts defined yet. They will be supported in the future.
!> Sometimes there isn't a layout that supports your exact build. In that case select `LAYOUT_all`.
## Step 3: Name Your Keymap
Call this keymap what you want.
?> If you are running into issues when compiling, it may be worth changing this name, as it may already exist in the QMK Firmware repo.
## Step 4: Define Your Keymap
Keycode Entry is accomplished in one of 3 ways:
1. Drag and drop
2. Clicking on an empty spot on the layout, then clicking the keycode you desire
3. Clicking on an empty spot on the layout, then pressing the physical key on your keyboard
?> Hover your mouse over a key and a short blurb will tell you what that keycode does. For a more verbose description please see:
* [Basic Keycode Reference](keycodes_basic.md)
* [Advanced Keycode Reference](feature_advanced_keycodes.md)
!> If your selected layout doesn't match your physical build leave the unused keys blank. If you're not sure which key is in use, for example you have a one backspace key but `LAYOUT_all` has 2 keys, put the same keycode in both locations.
## Step 5: Save Your Keymap for Future Changes
When you're satisfied with your keymap or just want to work on it later, press the `Export Keymap` button. It will save your keymap to your computer. You can then load this .json file in the future by pressing the `Import Keymap` button.
!> **CAUTION:** This is not the same type of .json file used for kbfirmware.com or any other tool. If you try to use this for those tools, or the .json from those tools with QMK Configurator, you will encounter problems.
## Step 6: Compile Your Firmware File
Press the green `Compile` button.
When the compilation is done, you will be able to press the green `Download Firmware` button.
## Next steps: Flashing Your Keyboard
Please refer to [Flashing Firmware](newbs_flashing.md).

26
configurator_troubleshooting.md Normal file
View File

@ -0,0 +1,26 @@
# Configurator Troubleshooting
## My .json file is not working
If the .json file was generated with QMK Configurator, congratulations you have stumbled upon a bug. File an issue at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues).
If not... how did you miss the big bold message at the top saying not to use other .json files?
## There are extra spaces in my layout? What do I do?
If you're referring to having three spots for space bar, the best course of action is to just fill them all with Space. The same can be done for Backspace and Shift keys.
## What is the keycode for...
Please see:
* [Basic Keycode Reference](keycodes_basic.md)
* [Advanced Keycode Reference](feature_advanced_keycodes.md)
## It won't compile
Please double check the other layers of your keymap to make sure there are no random keys present.
## Problems and Bugs
We are always accepting customer requests and bug reports. Please file them at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues).

168
contributing.md Normal file
View File

@ -0,0 +1,168 @@
# How to Contribute
👍🎉 First off, thanks for taking the time to read this and contribute! 🎉👍
Third-party contributions help us grow and improve QMK. We want to make the pull request and contribution process useful and easy for both contributors and maintainers. To this end we've put together some guidelines for contributors to help your pull request be accepted without major changes.
* [Project Overview](#project-overview)
* [Coding Conventions](#coding-conventions)
* [General Guidelines](#general-guidelines)
* [What does the Code of Conduct mean for me?](#what-does-the-code-of-conduct-mean-for-me)
## I Don't Want to Read This Whole Thing! I Just Have a Question!
If you'd like to ask questions about QMK you can do so on the [OLKB Subreddit](https://reddit.com/r/olkb) or on [Discord](https://discord.gg/Uq7gcHh).
Please keep these things in mind:
* It may take several hours for someone to respond to your question. Please be patient!
* Everyone involved with QMK is donating their time and energy. We don't get paid to work on or answer questions about QMK.
* Try to ask your question so it's as easy to answer as possible. If you're not sure how to do that these are some good guides:
* https://opensource.com/life/16/10/how-ask-technical-questions
* http://www.catb.org/esr/faqs/smart-questions.html
# Project Overview
QMK is largely written in C, with specific features and parts written in C++. It targets embedded processors found in keyboards, particularly AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) and ARM ([ChibiOS](http://www.chibios.com)). If you are already well versed in Arduino programming you'll find a lot of the concepts and limitations familiar. Prior experience with Arduino is not required to successfully contribute to QMK.
<!-- FIXME: We should include a list of resources for learning C here. -->
# Where Can I Go for Help?
If you need help you can [open an issue](https://github.com/qmk/qmk_firmware/issues) or [chat on Discord](https://discord.gg/Uq7gcHh).
# How Do I Make a Contribution?
Never made an open source contribution before? Wondering how contributions work in QMK? Here's a quick rundown!
0. Sign up for a [GitHub](https://github.com) account.
1. Put together a keymap to contribute, [find an issue](https://github.com/qmk/qmk_firmware/issues) you are interested in addressing, or [a feature](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature) you would like to add.
2. Fork the repository associated with the issue to your GitHub account. This means that you will have a copy of the repository under `your-GitHub-username/qmk_firmware`.
3. Clone the repository to your local machine using `git clone https://github.com/github-username/repository-name.git`.
4. If you're working on a new feature consider opening an issue to talk with us about the work you're about to undertake.
5. Create a new branch for your fix using `git checkout -b branch-name-here`.
6. Make the appropriate changes for the issue you are trying to address or the feature that you want to add.
7. Use `git add insert-paths-of-changed-files-here` to add the file contents of the changed files to the "snapshot" git uses to manage the state of the project, also known as the index.
8. Use `git commit -m "Insert a short message of the changes made here"` to store the contents of the index with a descriptive message.
9. Push the changes to your repository on GitHub using `git push origin branch-name-here`.
10. Submit a pull request to [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master).
11. Title the pull request with a short description of the changes made and the issue or bug number associated with your change. For example, you can title an issue like so "Added more log outputting to resolve #4352".
12. In the description of the pull request explain the changes that you made, any issues you think exist with the pull request you made, and any questions you have for the maintainer. It's OK if your pull request is not perfect (no pull request is), the reviewer will be able to help you fix any problems and improve it!
13. Wait for the pull request to be reviewed by a maintainer.
14. Make changes to the pull request if the reviewing maintainer recommends them.
15. Celebrate your success after your pull request is merged!
# Coding Conventions
Most of our style is pretty easy to pick up on. If you are familiar with either C or Python you should not have too much trouble with our local styles.
* [Coding Conventions - C](coding_conventions_c.md)
* [Coding Conventions - Python](coding_conventions_python.md)
# General Guidelines
We have a few different types of changes in QMK, each requiring a different level of rigor. We'd like you to keep the following guidelines in mind no matter what type of change you're making.
* Separate PRs into logical units. For example, do not submit one PR covering two separate features, instead submit a separate PR for each feature.
* Check for unnecessary whitespace with `git diff --check` before committing.
* Make sure your code change actually compiles.
* Keymaps: Make sure that `make keyboard:your_new_keymap` does not return any errors.
* Keyboards: Make sure that `make keyboard:all` does not return any errors.
* Core: Make sure that `make all` does not return any errors.
* Make sure commit messages are understandable on their own. You should put a short description (no more than 70 characters) on the first line, the second line should be empty, and on the 3rd and later lines you should describe your commit in detail, if required. Example:
```
Adjust the fronzlebop for the kerpleplork
The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations.
Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure.
```
!> **IMPORTANT:** If you would like to contribute a bugfix or improvement to user code, such as non-default keymaps, userspace and layouts, be sure to tag the original submitter of the code in your PR. Many users, regardless of skill level with Git and GitHub, may be confused or frustrated at their code being modified without their knowledge.
## Documentation
Documentation is one of the easiest ways to get started contributing to QMK. Finding places where the documentation is wrong or incomplete and fixing those is easy! We also very badly need someone to edit our documentation, so if you have editing skills but aren't sure where or how to jump in please [reach out for help](#where-can-i-go-for-help)!
You'll find all our documentation in the `qmk_firmware/docs` directory, or if you'd rather use a web based workflow you can click the "Edit this page" link at the bottom of each page on https://docs.qmk.fm/.
When providing code examples in your documentation, try to observe naming conventions used elsewhere in the docs. For example, standardizing enums as `my_layers` or `my_keycodes` for consistency:
```c
enum my_layers {
_FIRST_LAYER,
_SECOND_LAYER
};
enum my_keycodes {
FIRST_LAYER = SAFE_RANGE,
SECOND_LAYER
};
```
### Previewing the Documentation :id=previewing-the-documentation
Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder:
./bin/qmk docs
or if you only have Python 3 installed:
python3 -m http.server 8936
and navigating to `http://localhost:8936/`.
## Keymaps
Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap.
* Write a `readme.md` using [the template](documentation_templates.md).
* All Keymap PR's are squashed, so if you care about how your commits are squashed you should do it yourself
* Do not lump features in with keymap PR's. Submit the feature first and then a second PR for the keymap.
* Do not include `Makefile`s in your keymap folder (they're no longer used)
* Update copyrights in file headers (look for `%YOUR_NAME%`)
## Keyboards
Keyboards are the raison d'être for QMK. Some keyboards are community maintained, while others are maintained by the people responsible for making a particular keyboard. The `readme.md` should tell you who maintains a particular keyboard. If you have questions relating to a particular keyboard you can [Open An Issue](https://github.com/qmk/qmk_firmware/issues) and tag the maintainer in your question.
We also ask that you follow these guidelines:
* Write a `readme.md` using [the template](documentation_templates.md).
* Keep the number of commits reasonable or we will squash your PR
* Do not lump core features in with new keyboards. Submit the feature first and then submit a separate PR for the keyboard.
* Name `.c`/`.h` file after the immediate parent folder, eg `/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
* Do not include `Makefile`s in your keyboard folder (they're no longer used)
* Update copyrights in file headers (look for `%YOUR_NAME%`)
## Quantum/TMK Core
Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading [Understanding QMK](understanding_qmk.md), which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this:
* [Chat on Discord](https://discord.gg/Uq7gcHh)
* [Open an Issue](https://github.com/qmk/qmk_firmware/issues/new)
Feature and Bug Fix PR's affect all keyboards. We are also in the process of restructuring QMK. For this reason it is especially important for significant changes to be discussed before implementation has happened. If you open a PR without talking to us first please be prepared to do some significant rework if your choices do not mesh well with our planned direction.
Here are some things to keep in mind when working on your feature or bug fix.
* **Disabled by default** - memory is a pretty limited on most chips QMK supports, and it's important that current keymaps aren't broken, so please allow your feature to be turned **on**, rather than being turned off. If you think it should be on by default, or reduces the size of the code, please talk with us about it.
* **Compile locally before submitting** - hopefully this one is obvious, but things need to compile! Our Travis system will catch any issues, but it's generally faster for you to compile a few keyboards locally instead of waiting for the results to come back.
* **Consider revisions and different chip-bases** - there are several keyboards that have revisions that allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled on platforms it doesn't work on.
* **Explain your feature** - Document it in `docs/`, either as a new file or as part of an existing file. If you don't document it other people won't be able to benefit from your hard work.
We also ask that you follow these guidelines:
* Keep the number of commits reasonable or we will squash your PR
* Do not lump keyboards or keymaps in with core changes. Submit your core changes first.
* Write [Unit Tests](unit_testing.md) for your feature
* Follow the style of the file you are editing. If the style is unclear or there are mixed styles you should conform to the [coding conventions](#coding-conventions) above.
## Refactoring
To maintain a clear vision of how things are laid out in QMK we try to plan out refactors in-depth and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues), we'd love to talk about how QMK can be improved.
# What Does the Code of Conduct Mean for Me?
Our [Code of Conduct](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) means that you are responsible for treating everyone on the project with respect and courtesy regardless of their identity. If you are the victim of any inappropriate behavior or comments as described in our Code of Conduct, we are here for you and will do the best to ensure that the abuser is reprimanded appropriately, per our code.

108
custom_matrix.md Normal file
View File

@ -0,0 +1,108 @@
# Custom Matrix
QMK provides a mechanism to supplement or replace the default matrix scanning routine with your own code.
The reasons to use this feature include:
* Extra hardware between the keyboard's switches and MCU pins
* I/O multiplexer
* Line decoder
* Irregular switch matrix
* Simultaneous use of `COL2ROW` and `ROW2COL`
## Prerequisites
Implementing custom matrix usually involves compilation of an additional source file. It is recommended that for consistency, this file is called `matrix.c`.
Add a new file to your keyboard directory:
```text
keyboards/<keyboard>/matrix.c
```
And to configure compilation for the new file, add this to your `rules.mk`:
```make
SRC += matrix.c
```
## 'lite'
Provides a default implementation for various scanning functions, reducing the boilerplate code when implementing custom matrix.
To configure it, add this to your `rules.mk`:
```make
CUSTOM_MATRIX = lite
```
And implement the following functions in a `matrix.c` file in your keyboard folder:
```c
void matrix_init_custom(void) {
// TODO: initialize hardware here
}
bool matrix_scan_custom(matrix_row_t current_matrix[]) {
bool matrix_has_changed = false;
// TODO: add matrix scanning routine here
return matrix_has_changed;
}
```
## Full Replacement
When more control over the scanning routine is required, you can choose to implement the full scanning routine.
To configure it, add this to your rules.mk:
```make
CUSTOM_MATRIX = yes
```
And implement the following functions in a `matrix.c` file in your keyboard folder:
```c
matrix_row_t matrix_get_row(uint8_t row) {
// TODO: return the requested row data
}
void matrix_print(void) {
// TODO: use print() to dump the current matrix state to console
}
void matrix_init(void) {
// TODO: initialize hardware and global matrix state here
// Unless hardware debouncing - Init the configured debounce routine
debounce_init(MATRIX_ROWS);
// This *must* be called for correct keyboard behavior
matrix_init_quantum();
}
uint8_t matrix_scan(void) {
bool matrix_has_changed = false;
// TODO: add matrix scanning routine here
// Unless hardware debouncing - use the configured debounce routine
debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
// This *must* be called for correct keyboard behavior
matrix_scan_quantum();
return matrix_has_changed;
}
```
And also provide defaults for the following callbacks:
```c
__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); }
__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); }
__attribute__((weak)) void matrix_init_user(void) {}
__attribute__((weak)) void matrix_scan_user(void) {}
```

391
custom_quantum_functions.md Normal file
View File

@ -0,0 +1,391 @@
# How to Customize Your Keyboard's Behavior
For a lot of people a custom keyboard is about more than sending button presses to your computer. You want to be able to do things that are more complex than simple button presses and macros. QMK has hooks that allow you to inject code, override functionality, and otherwise customize how your keyboard behaves in different situations.
This page does not assume any special knowledge about QMK, but reading [Understanding QMK](understanding_qmk.md) will help you understand what is going on at a more fundamental level.
## A Word on Core vs Keyboards vs Keymap :id=a-word-on-core-vs-keyboards-vs-keymap
We have structured QMK as a hierarchy:
* Core (`_quantum`)
* Keyboard/Revision (`_kb`)
* Keymap (`_user`)
Each of the functions described below can be defined with a `_kb()` suffix or a `_user()` suffix. We intend for you to use the `_kb()` suffix at the Keyboard/Revision level, while the `_user()` suffix should be used at the Keymap level.
When defining functions at the Keyboard/Revision level it is important that your `_kb()` implementation call `_user()` before executing anything else- otherwise the keymap level function will never be called.
# Custom Keycodes
By far the most common task is to change the behavior of an existing keycode or to create a new keycode. From a code standpoint the mechanism for each is very similar.
## Defining a New Keycode
The first step to creating your own custom keycode(s) is to enumerate them. This means both naming them and assigning a unique number to that keycode. Rather than limit custom keycodes to a fixed range of numbers QMK provides the `SAFE_RANGE` macro. You can use `SAFE_RANGE` when enumerating your custom keycodes to guarantee that you get a unique number.
Here is an example of enumerating 2 keycodes. After adding this block to your `keymap.c` you will be able to use `FOO` and `BAR` inside your keymap.
```c
enum my_keycodes {
FOO = SAFE_RANGE,
BAR
};
```
## Programming the Behavior of Any Keycode :id=programming-the-behavior-of-any-keycode
When you want to override the behavior of an existing key, or define the behavior for a new key, you should use the `process_record_kb()` and `process_record_user()` functions. These are called by QMK during key processing before the actual key event is handled. If these functions return `true` QMK will process the keycodes as usual. That can be handy for extending the functionality of a key rather than replacing it. If these functions return `false` QMK will skip the normal key handling, and it will be up to you to send any key up or down events that are required.
These function are called every time a key is pressed or released.
### Example `process_record_user()` Implementation
This example does two things. It defines the behavior for a custom keycode called `FOO`, and it supplements our Enter key by playing a tone whenever it is pressed.
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case FOO:
if (record->event.pressed) {
// Do something when pressed
} else {
// Do something else when release
}
return false; // Skip all further processing of this key
case KC_ENTER:
// Play a tone when enter is pressed
if (record->event.pressed) {
PLAY_SONG(tone_qwerty);
}
return true; // Let QMK send the enter press/release events
default:
return true; // Process all other keycodes normally
}
}
```
### `process_record_*` Function Documentation
* Keyboard/Revision: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
* Keymap: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
The `keycode` argument is whatever is defined in your keymap, eg `MO(1)`, `KC_L`, etc. You should use a `switch...case` block to handle these events.
The `record` argument contains information about the actual press:
```c
keyrecord_t record {
keyevent_t event {
keypos_t key {
uint8_t col
uint8_t row
}
bool pressed
uint16_t time
}
}
```
# Keyboard Initialization Code
There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use.
These are the three main initialization functions, listed in the order that they're called.
* `keyboard_pre_init_*` - Happens before most anything is started. Good for hardware setup that you want running very early.
* `matrix_init_*` - Happens midway through the firmware's startup process. Hardware is initialized, but features may not be yet.
* `keyboard_post_init_*` - Happens at the end of the firmware's startup process. This is where you'd want to put "customization" code, for the most part.
!> For most people, the `keyboard_post_init_user` function is what you want to call. For instance, this is where you want to set up things for RGB Underglow.
## Keyboard Pre Initialization code
This runs very early during startup, even before the USB has been started.
Shortly after this, the matrix is initialized.
For most users, this shouldn't be used, as it's primarily for hardware oriented initialization.
However, if you have hardware stuff that you need initialized, this is the best place for it (such as initializing LED pins).
### Example `keyboard_pre_init_user()` Implementation
This example, at the keyboard level, sets up B0, B1, B2, B3, and B4 as LED pins.
```c
void keyboard_pre_init_user(void) {
// Call the keyboard pre init code.
// Set our LED pins as output
setPinOutput(B0);
setPinOutput(B1);
setPinOutput(B2);
setPinOutput(B3);
setPinOutput(B4);
}
```
### `keyboard_pre_init_*` Function Documentation
* Keyboard/Revision: `void keyboard_pre_init_kb(void)`
* Keymap: `void keyboard_pre_init_user(void)`
## Matrix Initialization Code
This is called when the matrix is initialized, and after some of the hardware has been set up, but before many of the features have been initialized.
This is useful for setting up stuff that you may need elsewhere, but isn't hardware related nor is dependant on where it's started.
### `matrix_init_*` Function Documentation
* Keyboard/Revision: `void matrix_init_kb(void)`
* Keymap: `void matrix_init_user(void)`
## Keyboard Post Initialization code
This is ran as the very last task in the keyboard initialization process. This is useful if you want to make changes to certain features, as they should be initialized by this point.
### Example `keyboard_post_init_user()` Implementation
This example, running after everything else has initialized, sets up the rgb underglow configuration.
```c
void keyboard_post_init_user(void) {
// Call the post init code.
rgblight_enable_noeeprom(); // enables Rgb, without saving settings
rgblight_sethsv_noeeprom(180, 255, 255); // sets the color to teal/cyan without saving
rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // sets mode to Fast breathing without saving
}
```
### `keyboard_post_init_*` Function Documentation
* Keyboard/Revision: `void keyboard_post_init_kb(void)`
* Keymap: `void keyboard_post_init_user(void)`
# Matrix Scanning Code
Whenever possible you should customize your keyboard by using `process_record_*()` and hooking into events that way, to ensure that your code does not have a negative performance impact on your keyboard. However, in rare cases it is necessary to hook into the matrix scanning. Be extremely careful with the performance of code in these functions, as it will be called at least 10 times per second.
### Example `matrix_scan_*` Implementation
This example has been deliberately omitted. You should understand enough about QMK internals to write this without an example before hooking into such a performance sensitive area. If you need help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) or [chat with us on Discord](https://discord.gg/Uq7gcHh).
### `matrix_scan_*` Function Documentation
* Keyboard/Revision: `void matrix_scan_kb(void)`
* Keymap: `void matrix_scan_user(void)`
This function gets called at every matrix scan, which is basically as often as the MCU can handle. Be careful what you put here, as it will get run a lot.
You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LEDs or a display) or other functionality that you want to trigger regularly even when the user isn't typing.
# Keyboard Idling/Wake Code
If the board supports it, it can be "idled", by stopping a number of functions. A good example of this is RGB lights or backlights. This can save on power consumption, or may be better behavior for your keyboard.
This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system board is idled and when it wakes up, respectively.
### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
```c
void suspend_power_down_user(void) {
rgb_matrix_set_suspend_state(true);
}
void suspend_wakeup_init_user(void) {
rgb_matrix_set_suspend_state(false);
}
```
### Keyboard suspend/wake Function Documentation
* Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
* Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
# Layer Change Code :id=layer-change-code
This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling.
### Example `layer_state_set_*` Implementation
This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example.
```c
layer_state_t layer_state_set_user(layer_state_t state) {
switch (get_highest_layer(state)) {
case _RAISE:
rgblight_setrgb (0x00, 0x00, 0xFF);
break;
case _LOWER:
rgblight_setrgb (0xFF, 0x00, 0x00);
break;
case _PLOVER:
rgblight_setrgb (0x00, 0xFF, 0x00);
break;
case _ADJUST:
rgblight_setrgb (0x7A, 0x00, 0xFF);
break;
default: // for any other layers, or the default layer
rgblight_setrgb (0x00, 0xFF, 0xFF);
break;
}
return state;
}
```
Use the `IS_LAYER_ON_STATE(state, layer)` and `IS_LAYER_OFF_STATE(state, layer)` macros to check the status of a particular layer.
Outside of `layer_state_set_*` functions, you can use the `IS_LAYER_ON(layer)` and `IS_LAYER_OFF(layer)` macros to check global layer state.
### `layer_state_set_*` Function Documentation
* Keyboard/Revision: `layer_state_t layer_state_set_kb(layer_state_t state)`
* Keymap: `layer_state_t layer_state_set_user(layer_state_t state)`
The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status)
# Persistent Configuration (EEPROM)
This allows you to configure persistent settings for your keyboard. These settings are stored in the EEPROM of your controller, and are retained even after power loss. The settings can be read with `eeconfig_read_kb` and `eeconfig_read_user`, and can be written to using `eeconfig_update_kb` and `eeconfig_update_user`. This is useful for features that you want to be able to toggle (like toggling rgb layer indication). Additionally, you can use `eeconfig_init_kb` and `eeconfig_init_user` to set the default values for the EEPROM.
The complicated part here, is that there are a bunch of ways that you can store and access data via EEPROM, and there is no "correct" way to do this. However, you only have a DWORD (4 bytes) for each function.
Keep in mind that EEPROM has a limited number of writes. While this is very high, it's not the only thing writing to the EEPROM, and if you write too often, you can potentially drastically shorten the life of your MCU.
* If you don't understand the example, then you may want to avoid using this feature, as it is rather complicated.
### Example Implementation
This is an example of how to add settings, and read and write it. We're using the user keymap for the example here. This is a complex function, and has a lot going on. In fact, it uses a lot of the above functions to work!
In your keymap.c file, add this to the top:
```c
typedef union {
uint32_t raw;
struct {
bool rgb_layer_change :1;
};
} user_config_t;
user_config_t user_config;
```
This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits. You can mix and match, but changing the order can cause issues, as it will change the values that are read and written.
We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `keyboard_post_init_user` and `process_record_user` to configure everything.
Now, using the `keyboard_post_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like:
```c
void keyboard_post_init_user(void) {
// Call the keymap level matrix init.
// Read the user config from EEPROM
user_config.raw = eeconfig_read_user();
// Set default layer, if enabled
if (user_config.rgb_layer_change) {
rgblight_enable_noeeprom();
rgblight_sethsv_noeeprom_cyan();
rgblight_mode_noeeprom(1);
}
}
```
The above function will use the EEPROM config immediately after reading it, to set the default layer's RGB color. The "raw" value of it is converted in a usable structure based on the "union" that you created above.
```c
layer_state_t layer_state_set_user(layer_state_t state) {
switch (get_highest_layer(state)) {
case _RAISE:
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
break;
case _LOWER:
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); }
break;
case _PLOVER:
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); }
break;
case _ADJUST:
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
break;
default: // for any other layers, or the default layer
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
break;
}
return state;
}
```
This will cause the RGB underglow to be changed ONLY if the value was enabled. Now to configure this value, create a new keycode for `process_record_user` called `RGB_LYR`. Additionally, we want to make sure that if you use the normal RGB codes, that it turns off Using the example above, make it look this:
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case FOO:
if (record->event.pressed) {
// Do something when pressed
} else {
// Do something else when release
}
return false; // Skip all further processing of this key
case KC_ENTER:
// Play a tone when enter is pressed
if (record->event.pressed) {
PLAY_SONG(tone_qwerty);
}
return true; // Let QMK send the enter press/release events
case RGB_LYR: // This allows me to use underglow as layer indication, or as normal
if (record->event.pressed) {
user_config.rgb_layer_change ^= 1; // Toggles the status
eeconfig_update_user(user_config.raw); // Writes the new status to EEPROM
if (user_config.rgb_layer_change) { // if layer state indication is enabled,
layer_state_set(layer_state); // then immediately update the layer color
}
}
return false;
case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference)
if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled
if (user_config.rgb_layer_change) { // only if this is enabled
user_config.rgb_layer_change = false; // disable it, and
eeconfig_update_user(user_config.raw); // write the setings to EEPROM
}
}
return true; break;
default:
return true; // Process all other keycodes normally
}
}
```
And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued.
```c
void eeconfig_init_user(void) { // EEPROM is getting reset!
user_config.raw = 0;
user_config.rgb_layer_change = true; // We want this enabled by default
eeconfig_update_user(user_config.raw); // Write default value to EEPROM now
// use the non noeeprom versions, to write these values to EEPROM too
rgblight_enable(); // Enable RGB by default
rgblight_sethsv_cyan(); // Set it to CYAN by default
rgblight_mode(1); // set to solid by default
}
```
And you're done. The RGB layer indication will only work if you want it to. And it will be saved, even after unplugging the board. And if you use any of the RGB codes, it will disable the layer indication, so that it stays on the mode and color that you set it to.
### 'EECONFIG' Function Documentation
* Keyboard/Revision: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` and `void eeconfig_update_kb(uint32_t val)`
* 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.

33
de/README.md Normal file
View File

@ -0,0 +1,33 @@
# Quantum Mechanical Keyboard Firmware
[![Aktuelle Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
[![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
[![Docs Status](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
[![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
[![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
## Was ist QMK Firmware?
QMK (*Quantum Mechanical Keyboard*) ist eine Open-Source-Community, welche die QMK-Firmware, die QMK-Toolbox, [qmk.fm](https://qmk.fm) und diese Dokumententation betreut. QMK-Firmware ist eine Weiterentwicklung der [tmk\_keyboard](http://github.com/tmk/tmk_keyboard)-Tastatur-Firmware mit vielen nützlichen Zusatzfunktionen für Atmel AVR-Prozessoren. Ursprünglich wurde sie für Produkte von [OLKB](http://olkb.com), das [ErgoDox EZ](http://www.ergodox-ez.com) und das [Clueboard](http://clueboard.co/) entwickelt. Im Laufe der Zeit wurde sie mit Hilfe von [ChibiOS](http://chibios.org) auch für die ARM-Architektur angepasst. Außerdem ist es inzwischen möglich, auch handverdrahtete Tastaturen und selbst geätzte PCBs mit QMK zu verwenden.
## Bezugsquelle für QMK
Wenn Du vorhast, deine Tastatur, Tastaturbelegung oder Features zu QMK beizusteuern, geht das am einfachsten, indem Du das [Repository auf GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box) forkst, die Änderungen in deinem lokalen Repo vornimmst und anschließend einen [Pull Request](https://github.com/qmk/qmk_firmware/pulls) einreichst.
Ansonsten kannst Du es als [zip](https://github.com/qmk/qmk_firmware/zipball/master) oder [tar](https://github.com/qmk/qmk_firmware/tarball/master) herunterladen, oder es direkt via git klonen (`git clone git@github.com:qmk/qmk_firmware.git` bzw. `git clone https://github.com/qmk/qmk_firmware.git`).
## Anleitung fürs Kompilieren
Bevor Du in der Lage bist, die Firmware zu kompilieren, musst Du eine [Entwicklungsumgebung](de/getting_started_build_tools.md) für AVR und/oder ARM aufsetzen. Danach kannst Du mit dem `make` Befehl eine Keymap für deine Tastatur erzeugen. Die Notation dafür ist:
make planck/rev4:default
Dies generiert die Revision `rev4` für eine Tastatur vom Type `planck` mit der `default` Tastaturbelegung. Nicht alle Tastaturen haben Revisionen (auch bekannt als Subprojekt oder Unterordner) weswegen dies auch ausgelassen werden kann:
make preonic:default
## Möglichkeiten der Anpassung
QMK hat viele [Features](de/features.md), die es zu entdecken gibt. In der [Dokumentation](https://docs.qmk.fmk) kannst Du Dir einen Überblick verschaffen. Die meisten Features basieren darauf, die [Tastaturbelegung](de/keymap.md) anzupassen und das Verhalten der [Keycodes](de/keycodes.md) zu verändern.

122
de/_summary.md Normal file
View File

@ -0,0 +1,122 @@
* [Anleitung für Anfänger](de/newbs.md)
* [Erste Schritte](de/newbs_getting_started.md)
* [Die erste Firmware](de/newbs_building_firmware.md)
* [Firmware flashen](de/newbs_flashing.md)
* [Testen und Debuggen](de/newbs_testing_debugging.md)
* [Git Tips und Tricks](de/newbs_best_practices.md)
* [Hilfreiche Ressourcen](de/newbs_learn_more_resources.md)
* [QMK Basics](de/README.md)
* [QMK Einführung](de/getting_started_introduction.md)
* [QMK CLI](de/cli.md)
* [QMK CLI Konfiguration](de/cli_configuration.md)
* [Zu QMK beitragen](de/contributing.md)
* [Anleitung für GitHub](de/getting_started_github.md)
* [Nach Hilfe fragen](de/getting_started_getting_help.md)
* [Breaking Changes](de/breaking_changes.md)
* [2019 Aug 30](de/ChangeLog/20190830.md)
* [FAQ](de/faq.md)
* [Häufige Fragen](de/faq_general.md)
* [Build/Kompilieren](de/faq_build.md)
* [Debugging/Troubleshooting](de/faq_debug.md)
* [Keymap](de/faq_keymap.md)
* [Treiber Installation mit Zadig](de/driver_installation_zadig.md)
* Detailierte Guides
* [Build Tools installieren](de/getting_started_build_tools.md)
* [Vagrant Guide](de/getting_started_vagrant.md)
* [Build/Compile Anleitung](de/getting_started_make_guide.md)
* [Firmware flashen](de/flashing.md)
* [Funktionalität anpassen](de/custom_quantum_functions.md)
* [Keymap Überblick](de/keymap.md)
* [Hardware](de/hardware.md)
* [AVR Prozessoren](de/hardware_avr.md)
* [Treiber](de/hardware_drivers.md)
* Referenz
* [Tastatur Richtlinien](de/hardware_keyboard_guidelines.md)
* [Konfigurations Optionen](de/config_options.md)
* [Keycodes](de/keycodes.md)
* [Coding Konventionen - C](de/coding_conventions_c.md)
* [Coding Konventionen - Python](de/coding_conventions_python.md)
* [Dokumentations Best Practices](de/documentation_best_practices.md)
* [Dokumentations Templates](de/documentation_templates.md)
* [Glossar](de/reference_glossary.md)
* [Unit Testing](de/unit_testing.md)
* [Nützliche Funktionen](de/ref_functions.md)
* [Configurator Support](de/reference_configurator_support.md)
* [info.json Format](de/reference_info_json.md)
* [Python CLI Development](de/cli_development.md)
* [Features](de/features.md)
* [Basic Keycodes](de/keycodes_basic.md)
* [US ANSI Shifted Keys](de/keycodes_us_ansi_shifted.md)
* [Quantum Keycodes](de/quantum_keycodes.md)
* [Advanced Keycodes](de/feature_advanced_keycodes.md)
* [Audio](de/feature_audio.md)
* [Auto Shift](de/feature_auto_shift.md)
* [Backlight](de/feature_backlight.md)
* [Bluetooth](de/feature_bluetooth.md)
* [Bootmagic](de/feature_bootmagic.md)
* [Combos](de/feature_combo.md)
* [Command](de/feature_command.md)
* [Debounce API](de/feature_debounce_type.md)
* [DIP Switch](de/feature_dip_switch.md)
* [Dynamic Macros](de/feature_dynamic_macros.md)
* [Encoders](de/feature_encoders.md)
* [Grave Escape](de/feature_grave_esc.md)
* [Haptic Feedback](de/feature_haptic_feedback.md)
* [HD44780 LCD Controller](de/feature_hd44780.md)
* [Key Lock](de/feature_key_lock.md)
* [Layouts](de/feature_layouts.md)
* [Leader Key](de/feature_leader_key.md)
* [LED Matrix](de/feature_led_matrix.md)
* [Macros](de/feature_macros.md)
* [Mouse Keys](de/feature_mouse_keys.md)
* [OLED Driver](de/feature_oled_driver.md)
* [One Shot Keys](de/one_shot_keys.md)
* [Pointing Device](de/feature_pointing_device.md)
* [PS/2 Mouse](de/feature_ps2_mouse.md)
* [RGB Lighting](de/feature_rgblight.md)
* [RGB Matrix](de/feature_rgb_matrix.md)
* [Space Cadet](de/feature_space_cadet.md)
* [Split Keyboard](de/feature_split_keyboard.md)
* [Stenography](de/feature_stenography.md)
* [Swap Hands](de/feature_swap_hands.md)
* [Tap Dance](de/feature_tap_dance.md)
* [Terminal](de/feature_terminal.md)
* [Thermal Printer](de/feature_thermal_printer.md)
* [Unicode](de/feature_unicode.md)
* [Userspace](de/feature_userspace.md)
* [Velocikey](de/feature_velocikey.md)
* Für Maker und Modder
* [Hand Wiring Guide](de/hand_wire.md)
* [ISP Flashing Guide](de/isp_flashing_guide.md)
* [ARM Debugging Guide](de/arm_debugging.md)
* [I2C Driver](de/i2c_driver.md)
* [SPI Driver](de/spi_driver.md)
* [GPIO Controls](de/internals_gpio_control.md)
* [Proton C Conversion](de/proton_c_conversion.md)
* Für ein tieferes Verständnis
* [Wie Tastaturen funktionieren](de/how_keyboards_work.md)
* [QMK verstehen](de/understanding_qmk.md)
* Andere Themen
* [Eclipse mit QMK](de/other_eclipse.md)
* [VSCode mit QMK](de/other_vscode.md)
* [Support](de/getting_started_getting_help.md)
* [Übersetzungen](de/translating.md)
* QMK Internals (In Progress)
* [Defines](de/internals_defines.md)
* [Input Callback Reg](de/internals_input_callback_reg.md)
* [Midi Device](de/internals_midi_device.md)
* [Midi Device Setup Process](de/internals_midi_device_setup_process.md)
* [Midi Util](de/internals_midi_util.md)
* [Send Functions](de/internals_send_functions.md)
* [Sysex Tools](de/internals_sysex_tools.md)

169
de/cli.md Normal file
View File

@ -0,0 +1,169 @@
# QMK CLI (Kommandozeile)
Diese Seite beschreibt die Einrichtung und den Umgang mit dem QMK CLI (Kommandozeile).
# Übersicht
Die QMK CLI vereinfacht das Zusammenbauen und Arbeiten mit QMK Tastaturen. Hier findest Du wichtige Befehle, um beispielsweise das Herunterladen und Kompilieren der QMK Firmware oder das Erstellen von Tastaturbelegungen (und vieles mehr) zu erleichtern.
* [Globale CLI](#globale-cli)
* [Lokale CLI](#lokale-cli)
* [CLI-Befehle](#cli-befehle)
# System-Anforderungen
Die CLI benötigt Python 3.5 oder höher. Außerdem ist es nötig, die Packages laut [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) zu installieren.
# Globale CLI
QMK bietet ein installierbares CLI, das Du zum Einrichten Deiner QMK Build-Umgebung verwenden kannst. Dieses ermöglicht Dir das Arbeiten mit QMK, und erleichtert das Arbeiten mit mehreren Kopien der `qmk_firmware`. Wir empfehlen, dieses CLI zu installieren und regelmäßig upzudaten.
## Installation mit Homebrew (macOS, manche Linux)
Solltest Du [Homebrew](https://brew.sh) installiert haben, kannst Du QMK per tap installieren:
```
brew tap qmk/qmk
brew install qmk
export QMK_HOME='~/qmk_firmware' # Optional: setzt den Installationsort für `qmk_firmware`
qmk setup # Dies klont `qmk/qmk_firmware` und richtet optional auch Deine Build-Umgebung ein
```
## Installation mit easy_install oder pip
Falls Du kein Homebrew hast, kannst Du QMK auch manuell installieren. Zuerst musst Du sicherstellen, dass Python 3.5 (oder höher) und pip installiert ist. Dann installiere QMK mit diesem Befehl:
```
pip3 install qmk
export QMK_HOME='~/qmk_firmware' # Optional: setzt den Installationsort für `qmk_firmware`
qmk setup # Dies klont `qmk/qmk_firmware` und richtet optional auch Deine Build-Umgebung ein
```
## Installation mit git Repo
`git clone https://github.com/qmk/qmk_cli.git && cd qmk_cli && python3 setup.py install`
## Packaging für andere Betriebssysteme
Wir suchen nach Freiwilligen, die ein `qmk`-Package für weitere Betriebssysteme erstellen und pflegen. Falls Du ein Package für Dein OS erstellen möchtest, bitte befolge diese Richtlinien:
* Verwende "Best Practices" für Dein OS, sollten sie mit diesen Richtlinien in Konflikt stehen.
* Dokumentiere den Grund in einem Kommentar, wenn Du abweichen musstest.
* Installiere mit einem [virtualenv](https://virtualenv.pypa.io/en/latest/).
* Weise den User an, die Umgebungs-Variable `QMK_HOME` zu setzen, um die Firmware-Quelle anders einzustellen als `~/qmk_firmware`.
# Lokale CLI
Wenn Du die globale CLI nicht verwenden möchtest, beinhaltet `qmk_firmware` auch eine lokale CLI. Du kannst sie hier finden: `qmk_firmware/bin/qmk`. Du kannst den `qmk`-Befehl aus irgendeinem Datei-Verzeichnis ausführen und es wird immer auf dieser Kopie von `qmk_firmware` arbeiten.
**Beispiel**:
```
$ ~/qmk_firmware/bin/qmk hello
Ψ Hello, World!
```
## Einschränkungen der lokalen CLI
Hier ein Vergleich mit der globalen CLI:
* Die lokale CLI unterstützt kein `qmk setup` oder `qmk clone`.
* Die lokale CLI arbeitet immer innerhalb der selben `qmk_firmware`-Verzeichnisstruktur, auch wenn Du mehrere Repositories geklont hast.
* Die lokale CLI läuft nicht in einer virtualenv. Daher ist es möglich, dass Abhängigkeiten (dependencies) miteinander in Konflikt kommen/stehen.
# CLI-Befehle
## `qmk compile`
Dieser Befehl erlaubt es dir, die Firmware - aus egal welchem Datei-Verzeichnis - zu compilen. Du kannst JSON-Exporte von <https://config.qmk.fm> oder Keymaps in der Repo kompilen.
**Anwendung für Konfigurations-Exports**:
```
qmk compile <configuratorExport.json>
```
**Anwendung für Keymaps**:
```
qmk compile -kb <keyboard_name> -km <keymap_name>
```
## `qmk cformat`
Dieser Befehl formatiert C-Code im clang-Format. Benutze ihn ohne Argumente, um den core-Code zu formatieren, oder benutze Namen von Dateien in der CLI, um den Befehl auf bestimmte Dateien anzuwenden.
**Anwendung**:
```
qmk cformat [file1] [file2] [...] [fileN]
```
## `qmk config`
Dieser Befehl konfiguriert das Verhalten von QMK. Für die volle `qmk config`-Dokumentation gehe zu [CLI-Konfiguration](cli_configuration.md).
**Anwendung**:
```
qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
```
## `qmk docs`
Dieser Befehl startet einen lokalen HTTP-Server, den Du zum Browsen oder Verbessern der Dokumentation verwenden kannst. Der Default-Port ist 8936.
**Anwendung**:
```
qmk docs [-p PORT]
```
## `qmk doctor`
Dieser Befehl untersucht Deine Umgebung und warnt Dich vor potentiellen Build- oder Flash-Problemen.
**Anwendung**:
```
qmk doctor
```
## `qmk list-keyboards`
Dieser Befehl listet alle zurzeit in `qmk_firmware` definierten Tastaturen/Keyboards auf.
**Anwendung**:
```
qmk list-keyboards
```
## `qmk new-keymap`
Dieser Befehl erstellt eine neue Keymap basierend auf einer existierenden Standard-Keymap eines bestimmten Keyboards.
**Anwendung**:
```
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
```
## `qmk pyformat`
Dieser Befehl formatiert Python-Code in `qmk_firmware`.
**Anwendung**:
```
qmk pyformat
```
## `qmk pytest`
Dieser Befehl führt die Python Test Suite aus. Wenn Du Python-Code veränderst, solltest Du sicherstellen, dass der Test erfolgreich ausgeführt wurde.
**Anwendung**:
```
qmk pytest
```

47
de/driver_installation_zadig.md Normal file
View File

@ -0,0 +1,47 @@
# Bootloader Treiber Installation mit Zadig
QMK erscheint für den Host als normales HID Eingabegerät und benötigt deshalb keine zusätzlichen Treiber. Der Bootloader, den Du für das Flashen der Firmware benötigst, jedoch meistens schon.
Hierzu gibt es zwei Ausnahmen: den Caterina Bootloader, meistens auf Pro Micros, sowie den HalfKay Bootloader auf PJRC Teensys. Diese erscheinen als serieller Port und als generisches HID Gerät und benötigen keine Treiber.
Wir empfehlen deshalb [Zadig](https://zadig.akeo.ie/). Wenn Du die Entwicklungsumgebung mit MSYS2 oder WSL installiert hast, wird dich dass `qmk_install.sh` Skript gefragt haben, ob es die Treiber für dich installieren sollte.
## Installation
Versetze deine Tastatur in den Bootloader-Modus, entweder durch Betätigung des physischen `RESET` Schalters - meist auf der Unterseite der Platine - oder durch das Auslösen des Key-Codes `RESET` bzw. `KC_RESET` (sollte in der zur Tastatur gehörigen `keycode.c` zu entnehmen sein). Sollte deine Tastatur weder noch besitzen, versuche es damit die `Escape`-Taste oder `Leertaste + B` zu halten während Du die Tastatur mit dem PC verbindest (Siehe auch [Bootmagic](de/feature_bootmagic.md) für weitere Details). Ein paar Tastaturen benutzen das [Command](de/feature_command.md)-Feature an Stelle von Bootmagic; in diesem Fall kannst du mit den Tastenkombinationen `linkes Shift + rechtes Shift + B` oder `linkes Shift + rechtes Shift + Escape` zu jeder Zeit in den Bootloader wechseln solange die Tastatur verbunden ist.
Eingie Tastaturen haben u.U. spezielle Anweisungen um in den Bootloader-Modus zu gelangen. Zum Beispiel kann die [Bootmagic-Lite](de/feature_bootmagic.md#bootmagic-lite)-Taste (default: Escape) auf eine andere Taste gemappt sein; oder die magische Kombination (default: linkes Shift+rechtes Shift) verwendet anstatt Shift die STRG-Tasten. Die zur Tastatur gehörige README sollte dir Aufschluss darüber geben wie der Bootloader-Modus ausgelöst werden kann wenn Du unsicher bist.
Um ein Gerät mit USBaspLoader in den Bootloader-Modus zu versetzen, halte `BOOT` gedrückt während Du den `RESET`-Knopf drückst.
Alternativ, halte `BOOT` gedrückt während Du das USB-Kabel einsteckst.
Zadig sollte das Bootloader-Gerät automatisch erkennen. Manchmal musst Du zusätzlich noch **Options → List All Devices** auswählen.
- Tastaturen mit Atmel AVR MCUs sollten als `ATm32U4DFU` (oder ähnlich) angezeigt werden, mit der Vendor ID `03EB`.
- USBasp werden als `USBasp` angezeigt, mit VID/PID `16C0:05DC`.
- Tastaturen AVR controller und dem QMK-DFU Bootloader haben den namen `<Tastatur Name> Bootloader` und die VID `03EB`.
- Die meisten ARM Tastaturen werden als `STM32 BOOTLOADER` angezeigt, mit VID/PID `0483:DF11`.
!> Sollte Zadig ein oder mehrere Geräte mit `HidUsb`-Treiber anzeigen, dann ist deine Tastatur wahrscheinlich nicht im Bootloader-Modus. Der Pfeil wird orange eingefärbt sein und Du wirst nach einer Bestätigung gefragt um Veränderungen am System vorzunehmen. In diesem Fall **fahre nicht fort**!
Wenn der Pfeil grün angezeigt wird, wähle den Treiber aus und klicke auf **Treiber installieren**. Der `libusb-win32`-Treiber sollte gewöhnlich für AVR verwendet werden und `WinUSB` für ARM. Sollte es danach noch nicht möglich sein die Tastatur zu flashen, versuche es mit einem anderen Treiber. Für USBaspLoader Geräte, die über die Befehlszeile mit MSYS2 geflasht werden, wird der `libusbk`-Treiber empfohlen. Ansonsten sollte `libusb-win32` funktionieren wenn die QMK Toolbox verwendet wird.
![Zadig mit Bootloader-Treiber korrekt installiert](https://i.imgur.com/b8VgXzx.png)
Entferne nun deine Tastatur und verbinde sie erneut um sicherzugehen dass der neue Treiber erfolgreich installiert wurde. Wenn Du QMK Toolbox benutzt, starte die Anwendung zur Sicherheit einmal neu, da Veränderungen am Treiber manchmal nicht richtig erkannt werden. Wenn dies immer noch nicht erfolgreich war hilft es an dieser Stelle manchmal ein Neustart des Computers.
## Wiederherstellung einer Installation für ein falsches Gerät
Wenn Du feststellst dass Du anschließend auf deiner Tastatur nicht mehr tippen kannst, ist etwas bei der Installation schief gelaufen. Ein häufiger Fehler ist es dass die Tastatur nicht im Bootloader-Modus war und stattdessen der Treiber für das HID-Gerät ersetzt wurde. Dies kannst Du einfach mit Zadig überprüfen, eine funktionierende Tastatur verwendet als Treiber `HidUsb` auf allen Interfaces .
![Eine funktionierende Tastatur aus Zadigs Sicht](https://i.imgur.com/Hx0E5kC.png)
Öffne den Geräte-Manager und suche nach einem Gerät das wie deine Tastatur aussieht.
![Die Tastatur mit dem falschen Treiber installiert, im Geräte-Manager](https://i.imgur.com/L3wvX8f.png)
Rechtsklick und **Gerät deinstallieren** anklicken. Bitte gehe sicher dass in diesem Schritt auch **Treibersoftware für dieses Gerät löschen** markiert ist.
![Der "Gerät deinstallieren"-Dialog, mit "Treibersoftware für dieses Gerät entfernen" markiert](https://i.imgur.com/aEs2RuA.png)
Klick **Aktion → Suche nach veränderter Hardware**. Nun solltest Du wieder in der Lage sein normal zu tippen. Vergewissere dich mit Hilfe von Zadig dass die Tastatur nun `HidUsb` als Treiber verwendet. Wenn dies der Fall ist sollte wieder alles funktionieren.

22
de/newbs.md Normal file
View File

@ -0,0 +1,22 @@
# Anleitung für absolute Beginner
QMK ist eine mächtige Open Source Firmware für mechanische Tastaturen. Mit QMK kannst Du deine Tastatur sowohl sehr einfach als auch sehr umfangreich anpassen. Menschen unterschiedlichen Wissensstandes - vom kompletten Anfänger bis zum erfahrenen Programmierer - haben ihre Tastaturen mit QMK erfolgreich auf ihre persönlichen Bedürfnisse angepasst. Diese Anleitung soll Dir unabhängig von deinen Vorkenntnissen dabei helfen dies ebenfalls zu bewältigen.
Bist Du unsicher ob deine Tastatur QMK unterstützt? Wenn es eine mechanische Tastatur ist, die Du selbst gebaut hast, stehen deine Chancen gut. Wir unterstützen eine [Vielzahl](https://qmk.fm/keyboards/) selbst gebauter Tastaturen, sodass selbst wenn deine jetzige Tastatur nicht unterstützt wird Du keine Probleme haben solltest eine für deine Anforderungen zu finden.
## Übersicht
Diese Anleitung ist in 7 Abschnitte unterteilt:
* [Die ersten Schritte](newbs_getting_started.md)
* [Die erste Firmware auf der Kommandozeile erzeugen](newbs_building_firmware.md)
* [Die erste Firmware mit der Online GUI erzeugen](newbs_building_firmware_configurator.md)
* [Firmware flashen](newbs_flashing.md)
* [Testen und Debuggen](newbs_testing_debugging.md)
* [Git Leitfaden](newbs_best_practices.md)
* [Weitere hilfreiche Ressourcen für Anfänger](newbs_learn_more_resources.md)
Diese Anleitung richtet sich an Personen, die vorher noch nie Software kompiliert haben. Die Entscheidungen und Empfehlungen basieren auf dieser Grundannahme. Es gibt unterschiedliche Herangehensweisen für viele der Prozeduren und wir unterstützen die meisten Alternativen. Wenn Du mal nicht weiter weißt oder Dir nicht sicher bist, wie Du an ein Problem herangehen sollst, kannst Du uns gerne [um Hilfe bitten](getting_started_getting_help.md).
## Weitere Ressourcen
* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – Ein äußerst hilfreicher Blog eines Community-Mitglieds, der einige Grundlagen der QMK-Firmware aus der Sicht des Benutzers erklärt (auf Englisch).

78
de/newbs_building_firmware.md Normal file
View File

@ -0,0 +1,78 @@
# Eine eigene Firmware erstellen
Nachdem Du nun eine funktionierende Entwicklungsumgebung aufgesetzt hast, bist Du nun bereit, deine eigene Firmware zu erstellen. Dieses Sektion des Guides wird zwischen drei Programmen hin- und herwechseln: deinem Dateimanager, deinem Texteditor und der Befehlszeile. Lasse diese drei Fenster geöffnet, bis Du fertig und zufrieden mit deiner Tastatur-Firmware bist.
Solltest Du die Befehlszeile zwischenzeitlich geschlossen haben, vergiss nicht wieder in das richtige Verzeichnis zu navigieren, benutze dazu den Befehl `cd qmk_firmware`.
## Navigiere in deinen Keymap Ordner
Beginne damit, in das `keymaps` Verzeichnis für deine Tastatur zu navigieren.
Wenn Du macOS oder Windows benutzt, kannst Du einfach in das keymaps Verzeichnis wechseln.
?> macOS:<br>
open keyboards/<keyboard_folder>/keymaps
?> Windows:<br>
start .\\keyboards\\<keyboard_folder>\\keymaps
## Eine Kopie der `default` Tastaturbelegung erstellen
Wenn Du den `keymaps` Ordner geöffnet hast, solltest Du zuerst eine Kopie des `default` Verzeichnisses erstellen. Wir empfehlen dafür deinen GitHub Benutzernamen zu verweden, aber Du kannst auch jeden anderen Namen verwenden solange er nur aus Kleinbuchstaben, Zahlen und Unterstrichen besteht.
Um den Prozess zu automatisieren kannst Du dazu auch das Skript `new_keymap.sh` verwenden.
Navigiere dazu in das `qmk_firmware/util` Verzeichnis und gib folgenden Befehl ein:
```
./new_keymap.sh <keyboard path> <username>
```
Um zum Beispiel den Benutzernamen John für die Tastaturbelegung eines 1up60hse zu verwenden, würdest Du Folgendes eingeben:
```
./new_keymap.sh 1upkeyboards/1up60hse john
```
## Öffne `keymap.c` in deinem bevorzugtem Text Editor
Öffne deine `keymap.c`. In dieser Datei findest Du die Strukturen, die das Verhalten deiner Tastatur bestimmen. Oben in der `keymap.c` befinden sich Definitionen (defines) und Aufzählungen (enums), die die Tastaturbelegung leserlicher machen sollen. Weiter unten wirst Du eine Zeile finden, die wie folgt aussieht:
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
Diese Zeile markiert den Anfang der Liste der Ebenen (Layers). Darunter befinden sich Zeilen die entweder `LAYOUT` oder `KEYMAP` enthalten, das deutet auf den Start einer Ebene hin. Danach folgt eine Liste von Tasten, die dieser Ebene zugewiesen sind.
!> Beim Bearbeiten einer Tastaturbelegung solltest Du darauf achten, keine Kommata hinzuzufügen oder zu entfernen. Ansonsten kann dies dazu führen, dass deine Firmware nicht mehr kompiliert und es ist nicht immer einfach festzustellen, wo genau ein Komma zuviel oder zu wenig ist. Die letzte Zeile hat am Ende kein Komma, die Zeilen davor jedoch schon.
## Personalisiere die Tastaturbelegung nach deinen Wünschen
Wie Du diesen Schritt abschließt ist vollkommen Dir überlassen. Ändere die eine Sache die Dich stört oder verändere alles von Grund auf. Du kannst Ebenen entfernen die Du nicht brauchst oder Neue hinzufügen, bis zu 32 Stück. Die folgende Dokumentation verrät Dir was Du hier alles definieren kannst:
* [Keycodes](de/keycodes.md)
* [Features](de/features.md)
* [FAQ](de/faq.md)
?> Während Du langsam ein Gefühl dafür kriegst wie Keymaps funktionieren, solltest Du darauf achten nicht zuviel auf einmal zu verändern. Größere Änderungen machen es schwieriger, Probleme zu debuggen.
## Deine Firmware erzeugen
Wenn Du damit fertig bist, deine Tastaturbelegung anzupassen, musst Du noch die Firmware erzeugen. Öffne dazu wieder die Befehlszeile und führe folgenden Befehl aus:
make <my_keyboard>:<my_keymap>
Wenn deine Tastaturbelegung z.B. "xyverz" heißt und Du die Belegung für ein rev5 planck erzeugen möchtest, lautet der Befehl:
make planck/rev5:xyverz
Während des Kompiliervorgangs wird viel Text auf dem Bildschirm ausgegeben. Es sollte am Ende mit etwas enden das ungefähr so aussieht:
```
Linking: .build/planck_rev5_xyverz.elf [OK]
Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
Checking file size of planck_rev5_xyverz.hex [OK]
* File size is fine - 18392/28672
```
## Deine Firmware flashen
Bitte fahre mit [Firmware flashen](de/newbs_flashing.md) fort, um zu erfahren, wie Du deine neue Firmware auf deine Tastatur flashen kannst.

369
de/newbs_flashing.md Normal file
View File

@ -0,0 +1,369 @@
# Deine Tastatur flashen
Nachdem deine Firmware nun fertig ist musst Du Sie noch auf deine Tastatur flashen.
## Flash-Vorgang mit QMK Toolbox
Der einfachste Weg deine Tastatur zu flashen ist mit Hilfe der [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases)
Leider ist die QMK Toolbox derzeit nur für Windows und macOS verfügbar. Wenn Du Linux benutzt (oder es vorziehst die Firmware mit der Kommandozeile zu flashen) solltest Du die Methode benutzen die [hier](de/newbs_flashing.md#tastatur-mit-der-befehlszeile-flashen) beschrieben wird.
### Lade die Datei in QMK Toolbox
Beginne damit die Datei in der QMK Toolbox Anwendung zu laden. Versichere dich dass Du die Firmware-Datei im Finder oder Explorer findest. Deine Tastatur-Firmware sollte entweder vom Typ `.hex` oder `.bin` sein sein. QMK sollte die für deine Tastatur entsprechende Datei automatisch in das Root-Verzeichnis (normalerweise `qmk_firmware`) kopieren.
?> Wenn Du Windows oder macOS benutzt kannst Du mit folgenden Befehlen ganz einfach das aktuelle Firmware-Verzeichnis im Explorer oder Finder öffnen.
#### Windows:
``` start . ```
#### macOS:
``` open . ```
Die Firmware-Dateien folgen dabei immer folgendem Schema:
<meine_Tastatur>_<meine_Tastaturbelegung>.{bin,hex}
Zum Beispiel würde ein `planck/rev5` mit der `default` Tastaturbelegung folgenden Dateinamen haben:
planck_rev5_default.hex
Wenn Du die Firmware-Datei gefunden hast kannst Du sie in das "Local file" ("Lokale Datei") Feld in der QMK Toolbox ziehen, alternativ kannst Du auf "Öffnen" klicken und in das Verzeichnis navigieren indem sich die Firmware-Datei befindet.
### Die Tastatur in den DFU (Bootloader) Modus versetzen
Um deine angepasste Firmware auf deine Tastatur zu flashen musst Du diese erst in einen speziellen "flashing"-Modus versetzen. Während die Tastatur in diesem Modus ist kannst Du nicht auf ihr tippen oder sie wie gewohnt als Tastatur benutzen. Es ist wichtig dass der flashing-Prozesses nicht unterbrochen oder die Tastatur ausstöpselst wird, da der Vorgang ansonst wiederholt werden muss.
Verschiedene Tastaturen verwenden unterschiedliche Methoden um in den Bootloader-Modus zu gelangen. Wenn dein PCB im Moment QMK oder TMK verwendet und Du keine spezifischen Anweisungen erhalten hast probiere die folgenden Methoden in dieser Reihenfolge:
* Halte beide Shift-Tasten und drücke `Pause`
* Halte beide Shift-Tasten und drücke `B`
* Entferne deine Tastatur vom Computer, drücke gleichzeitig `Leertaste` und `B`, verbinde die Tastatur wieder mit dem Computer und warte eine Sekunde bevor Du die Tasten wieder loslässt.
* Drücke den physischen `RESET`-Knopf auf der Unterseite des PCBs
* Suche auf dem PCB den Pin mit dem Label `RESET`, verbinde diesen mit deinem GND-Pin
* Suche auf dem PCB den Pin mit dem Label `BOOT0`, verbinde diesen mit GND und schließe die Tastatur wieder an den PC an TODO: DIS IS DANGEROUS!!
Wenn Du damit erfolgreich warst solltest Du in der QMK Toolbox eine Nachricht sehen die ungefähr so aussieht:
```
*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
*** DFU device connected
```
### Tastatur flashen
Klicke auf den `Flash`-Knopf in der QMK Toolbox. Die Ausgabe wird ungefähr so aussehen:
```
*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
*** DFU device connected
*** Attempting to flash, please don't remove device
>>> dfu-programmer atmega32u4 erase --force
Erasing flash... Success
Checking memory from 0x0 to 0x6FFF... Empty.
>>> dfu-programmer atmega32u4 flash qmk_firmware/clueboard_66_hotswap_skully.hex
Checking memory from 0x0 to 0x55FF... Empty.
0% 100% Programming 0x5600 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
0% 100% Reading 0x7000 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
Validating... Success
0x5600 bytes written into 0x7000 bytes memory (76.79%).
>>> dfu-programmer atmega32u4 reset
*** DFU device disconnected
*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
```
## Tastatur mit der Befehlszeile flashen
Zunächst solltest Du versuchen herauszufinden welchen Bootlader deine Tastatur benutzt. Diese vier Bootloader sind am Weitesten verbreitet:
| MCU | Bootloader |
| --- | --- |
| Pro-Micro und Klone | CATERINA |
| Teensy | Halfkay |
| OLKB Boards | QMK-DFU |
| sonstige atmega32u4 | DFU |
Auf der Seite [Flash Anleitung und Bootloader Informationen](de/flashing.md) kannst Du mehr über das Thema erfahren.
Wenn Du weißt welchen Bootloader deine Tastaur verwendet, kannst Du diese Information bei der Kompilation hinzufügen um den Flash-Vorgang mit dem `make`-Befehl zu automatisieren.
```rules.mk
...
BOOTLOADER = caterina
...
```
### DFU
Wenn Du den DFU-Bootloader verwendest und Du bereit bist deine Firmware zu kompilieren und zu flashen, öffne ein Befehlszeile und führe folgenden Befehl aus:
make <meine_Tastatur>:<meine_Tastaturbelegung>:dfu
Wenn deine Tastaturbelegung z.B den Namen "xzverz" trägt und Du ein rev5 planck flashen möchtest sähe der Befehl wie folgt aus:
make planck/rev5:xyverz:dfu
Nachdem der Vorgang abgeschlossen ist sollte die Ausgabe ungefähr so aussehen:
```
Linking: .build/planck_rev5_xyverz.elf [OK]
Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
Checking file size of planck_rev5_xyverz.hex
* File size is fine - 18574/28672
```
Wenn dieser Punkt erreicht ist wird das Build-Skript alle 5 Sekunden nach einem DFU Bootloader suchen. Dieser Vorgang wird wiederholt bis er erfolgreich ist oder abgebrochen wird.
dfu-programmer: no device present.
Error: Bootloader not found. Trying again in 5s.
Wenn diese Nachricht erscheint konnte das Build-Skript den Controller nicht eigenständig in den DFU Modus versetzen (z.B. weil der Modus in rules.mk falsch gesetzt wurde oder ein Problem mit der Hardware besteht), wenn dies eintritt musst Du die oben beschrieben Schritte benutzen um den Controller in den DFU Modus zu versetzen. Danach sollte die Ausgabe ungefähr so aussehen:
```
*** Attempting to flash, please don't remove device
>>> dfu-programmer atmega32u4 erase --force
Erasing flash... Success
Checking memory from 0x0 to 0x6FFF... Empty.
>>> dfu-programmer atmega32u4 flash qmk_firmware/clueboard_66_hotswap_skully.hex
Checking memory from 0x0 to 0x55FF... Empty.
0% 100% Programming 0x5600 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
0% 100% Reading 0x7000 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
Validating... Success
0x5600 bytes written into 0x7000 bytes memory (76.79%).
>>> dfu-programmer atmega32u4 reset
```
?> Wenn Du mit diesem Schritt Probleme hast (z.B. `dfu-programmer: no device present`) hilft dir hoffentlich der Abschnitt [Häufig gestellte Fragen (Build/Kompilieren)](de/faq_build.md).
#### DFU Befehle
Es gibt verschiedene DFU Befehle um die Firmware auf ein DFU Gerät zu flashen:
* `:dfu` - Dies ist die default Option. Es wird gecheckt ob ein DFU Gerät verfügbar ist, ist dies der Fall wird die Firmware geflasht. Dieser Check wird alle 5 Sekunden ausgeführt bis ein DFU Gerät erkannt wird.
* `:dfu-ee` - Der Flash-Vorgang benutzt eine `.eep` Datei anstatt einer `.hex` Datei. Dies ist eher unüblich.
* `:dfu-split-left` - Dies flasht die Firmware wie gewohnt (`:dfu`). Allerdings nur die "linke Seite" der EEPROM für geteilte Tastaturen. _Dies ist ideal für auf Elite C basierenden geteilten Tastaturen._
* `:dfu-split-right` - Dies flasht die Firmware wie gewohnt (`:dfu`). Allerdings nur die "rechte Seite" der EEPROM für geteilte Tastaturen. _Dies ist ideal für auf Elite C basierenden geteilten Tastaturen._
### Caterina
Für Arduinos und andere ProMicro Klone (z.B. SparkFun ProMicro), wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus:
make <meine_Tastatur>:<meine_Tastaturbelegung>:avrdude
Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein "rev2 Lets Split" erzeugen möchtest, lautet der Befehl dafür:
make lets_split/rev2:xyverz:avrdude
Nachdem die Kompilation abgeschlossen ist sollte die Ausgabe ungefähr so aussehen:
```
Linking: .build/lets_split_rev2_xyverz.elf [OK]
Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK]
Checking file size of lets_split_rev2_xyverz.hex [OK]
* File size is fine - 27938/28672
Detecting USB port, reset your controller now..............
```
Nun wird die Tastatur automatisch zurückgesetzt und das Skript wird die Firmware flashen sobald es den Bootloader erkennt. Die Ausgabe sollte ungefähr so aussehen:
```
Detected controller on USB port at /dev/ttyS15
Connecting to programmer: .
Found programmer: Id = "CATERIN"; type = S
Software Version = 1.0; No Hardware Version given.
Programmer supports auto addr increment.
Programmer supports buffered memory access with buffersize=128 bytes.
Programmer supports the following devices:
Device code: 0x44
avrdude.exe: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude.exe: erasing chip
avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
avrdude.exe: writing flash (27938 bytes):
Writing | ################################################## | 100% 2.40s
avrdude.exe: 27938 bytes of flash written
avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
avrdude.exe: reading on-chip flash data:
Reading | ################################################## | 100% 0.43s
avrdude.exe: verifying ...
avrdude.exe: 27938 bytes of flash verified
avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
avrdude.exe done. Thank you.
```
Sollten dabei Probleme auftreten (z.B. "Zugriff verweigert" / "Permission denied") muss der Make-Befehl mit privilegierten Berechtigungen ausgeführt werden:
sudo make <meine_Tastatur>:<meine_Tastaturbelegung>:avrdude
Zusätzlich ist es möglich mehrere Tastaturen in einem Vorgang zu flashen:
make <keyboard>:<keymap>:avrdude-loop
Du kannst den Loop mit STRG + C unterbrechen sobald der Vorgang abgeschlossen ist. Die korrekte Tastenkombination kann abweichen und hängt vom Betriebssystem ab.
### HalfKay
Für Tastaturen mit PJRC Controllern (Teensy's), wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus:
make <meine_Tastatur>:<meine_Tastaturbelegung>:teensy
Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein Ergodox oder Ergodox EZ erzeugen möchtest, lautet der Befehl dafür:
make ergodox_ez:xyverz:teensy
Nachdem die Kompilation abgeschlossen ist sollte die Ausgabe ungefähr so aussehen:
```
Linking: .build/ergodox_ez_xyverz.elf [OK]
Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK]
Checking file size of ergodox_ez_xyverz.hex [OK]
* File size is fine - 25584/32256
Teensy Loader, Command Line, Version 2.1
Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
Waiting for Teensy device...
(hint: press the reset button)
```
An diesem Punkt solltest Du die Tastatur zurücksetzen um den Flash-Vorgang auszulösen. Wenn dies abgeschlossen ist sollte die Ausgabe ungefähr so aussehen:
```
Found HalfKay Bootloader
Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
Programming.............................................................
...................................................
Booting
```
### BootloadHID
Für auf Bootmapper Client(BMC)/bootloaderHID/ATmega32A basierende Tastaturen, wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus:
make <meine_Tastatur>:<meine_Tastaturbelegung>:bootloaderHID
Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein jj40 erzeugen möchtest, lautet der Befehl dafür:
make jj40:xyverz:bootloaderHID
Nachdem die Kompilation abgeschlossen ist sollte die Ausgabe ungefähr so aussehen:
```
Linking: .build/jj40_default.elf [OK]
Creating load file for flashing: .build/jj40_default.hex [OK]
Copying jj40_default.hex to qmk_firmware folder [OK]
Checking file size of jj40_default.hex [OK]
* The firmware size is fine - 21920/28672 (6752 bytes free)
```
Wenn dieser Punkt erreicht ist wird das Build-Skript alle 5 Sekunden nach einem DFU Bootloader suchen. Dieser Vorgang wird wiederholt bis er erfolgreich ist oder abgebrochen wird.
```
Error opening HIDBoot device: The specified device was not found
Trying again in 5s.
```
An diesem Punkt solltest Du die Tastatur zurücksetzen um den Flash-Vorgang auszulösen. Wenn dies abgeschlossen ist sollte die Ausgabe ungefähr so aussehen:
```
Page size = 128 (0x80)
Device size = 32768 (0x8000); 30720 bytes remaining
Uploading 22016 (0x5600) bytes starting at 0 (0x0)
0x05580 ... 0x05600
```
### STM32 (ARM)
Für die meisten ARM Tastaturen (inkl. Proton C, Planck Rev 6 und Preonic Rev 3), wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus:
make <meine_Tastatur>:<meine_Tastaturbelegung>:dfu-util
Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein Planck Revision 6 erzeugen möchtest, benutze dafür den folgenden Befehl und reboote die Tastatur in den Bootloader (kurz bevor der Kompiliervorgang abgeschlossen ist):
make planck/rev6:xyverz:dfu-util
Nachdem der Kompiliervorgang abgeschlossen ist sollte die Ausgabe ungefähr so aussehen:
Für auf Bootmapper Client(BMC)/bootloaderHID/ATmega32A basierende Tastaturen, wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus:
make <meine_Tastatur>:<meine_Tastaturbelegung>:bootloaderHID
Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein jj40 erzeugen möchtest, lautet der Befehl dafür:
```
Linking: .build/planck_rev6_xyverz.elf [OK]
Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK]
Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK]
Size after:
text data bss dec hex filename
0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex
Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK]
dfu-util 0.9
Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
Invalid DFU suffix signature
A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 011a
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuERROR, status = 10
dfuERROR, clearing status
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 011a
Device returned transfer size 2048
DfuSe interface name: "Internal Flash "
Downloading to address = 0x08000000, size = 41824
Download [=========================] 100% 41824 bytes
Download done.
File downloaded successfully
Transitioning to dfuMANIFEST state
```
#### STM32 Befehle
Für Tastaturen mit STM32 Controller sind die DFU Befehle wie folgt:
* `:dfu-util` - The default command for flashing to STM32 devices.
* `:dfu-util` - Der Standard-Befehl für STM32 Geräte.
* `:dfu-util-wait` - Funktioniert wie der Standard-Befehl, aber mit einem 10 Sekunden Timeout bevor erneut versucht wird die Firmware zu flashen. Mit dem Parameter `TIME_DELAY=20` auf der Befehlszeile kann der Timeout beeinflusst werden.
* z.B.: `make <meine_Tastatur>:<meine_Tastaturbelegung>:dfu-util TIME_DELAY=5`
* `:dfu-util-split-left` - Gleiche Funktionsweise wie `dfu-util`, jedoch wird zusätzlich das EEPROM Setting "linke Seite" für geteilte Tastaturen gesetzt.
* `:dfu-util-split-right` - Gleiche Funktionsweise wie `dfu-util`, jedoch wird zusätzlich das EEPROM Setting "rechte Seite" für geteilte Tastaturen gesetzt.
## Probier's aus!
Herzlichen Glückwunsch! Deine individuell angepasst Firmware wurde auf deine Tastatur übertragen!
Probiere deine neue Tastatur aus und gehe sicher dass alles wie gewünscht funktioniert. Wir haben einen weiteren Artikel zum Thema [Testen und Debuggen](de/newbs_testing_debugging.md) verfasst der sich mit Problembeseitigung beschäftigt um den Beginnger-Guide abzuschließen.

101
de/newbs_getting_started.md Normal file
View File

@ -0,0 +1,101 @@
# Einleitung
Genau wie in einem Computer befindet sich auch in einer Tastatur ein Prozessor.
Dieser Prozessor führt Software aus, die registriert wenn Tasten gedrückt bzw. wieder losgelassen werden und leitet die entsprechenden Signale an den Computer weiter.
QMK übernimmt die Rolle dieser Software und teilt dem Host-Computer den aktuellen Zustand der Tastatur mit. Wenn Du eine Tastaturbelegung definierst, ist dies äquivalent zu einem ausführbarem Programm, das auf deiner Tastatur läuft.
QMK möchte seine BenutzerInnen in die Lage versetzen, simple Aufgaben möglichst einfach zu gestalten und gleichzeitig komplexe Dinge zu ermöglichen, die mit normalen Tastaturen ohne zusätzliche Software undenkbar wären. Du musst nicht programmieren können, um abgefahrene Tastaturbelegungen zu gestalten - es reicht wenn Du eine Idee hast und ein paar einfache syntaktische Regeln verstehen kannst.
# Los geht's!
Bevor Du damit loslegen kannst, deine Tastaturbelegung zu erstellen, musst Du ein wenig Software installieren und Dir eine Entwicklungsumgebung aufsetzen. Die gute Nachricht ist, dass das nur einmal erledigt werden muss, egal für wie viele verschiedene Tastaturen Du hinterher Firmware entwickeln willst.
Wenn Du es vorziehst mit einer grafischen Oberfläche zu entwickeln kannst Du auch dazu gerne direkt mit dem online [QMK Konfigurator](https://config.qmk.fm) loslegen. Siehe auch: [Firmware mit der Online GUI erzeugen](de/newbs_building_firmware_configurator.md)
## Software herunterladen
### Text Editor
Du wirst ein Programm benötigen, mit dem Du **plain text** (= reiner Text) Dateien bearbeiten und speichern kannst. Wenn Du Windows benutzt, reicht dafür schon das normale `Notepad` und für Linux z.B. `gedit` oder `leafpad`. Beide sind sehr rudimentäre Editoren deren Funktionsumfang aber vollkommen ausreicht. Für macOS' standard `TextEdit` muss man ein bisschen vorsichtig sein und darauf achten, beim Speichern explizit unter _Format_ die Option _Reiner Text_ auszuwählen.
Ansonsten ist es empfehlenswert, einen Editor herunterzuladen der für die Programmierung und das Bearbeiten von Code ausgelegt ist wie z.b [Notepad++](http://notepad-plus-plus.org/), [Sublime Text](https://www.sublimetext.com/) oder [VS Code](https://code.visualstudio.com/).
?> Immer noch unsicher, welcher Text Editor der Richtige für Dich ist? Laurence Bradford hat eine hervorragende [Einleitung](https://learntocodewith.me/programming/basics/text-editors/) zu dem Thema geschrieben (auf Englisch).
### QMK Toolbox
QMK Toolbox ist ein optionales grafisches Programm für Windows und macOS, das es erleichtern soll, deine Tastatur zu programmieren und zu debuggen. Du wirst es höchstwahrscheinlich früher oder später als unverzichtbar ansehen, wenn es darum geht eine Tastatur einfach zu flashen oder zu debuggen, da es ermöglicht, sich debug-Nachrichten direkt anzeigen zu lassen.
[Hier kannst Du die aktuelle Version herunterladen.](https://github.com/qmk/qmk_toolbox/releases/latest)
* Für Windows: `qmk_toolbox.exe` (portable) oder `qmk_toolbox_install.exe` (installer)
* Für macOS: `QMK.Toolbox.app.zip` (portable) oder `QMK.Toolbox.pkg` (installer)
## Die Entwicklungsumgebung aufsetzen
Wir haben versucht, die Installation der Entwicklungsumgebung für QMK so einfach wie möglich zu gestalten. Alles, was Du tun musst, ist eine Linux oder Unix Umgebung aufzusetzen, danach macht QMK den Rest.
?> Wenn Du das erste Mal mit der Linux/Unix Befehlszeile arbeitest, schadet es nicht, sich mit ein paar Grundlagen und Befehlen vertraut zu machen. Diese Ressourcen sollten ausreichen, um sich das Nötigste anzueignen um mit QMK arbeiten zu können:<br>
[Erforderliche Linux Grundlagen](https://www.guru99.com/must-know-linux-commands.html)<br>
[Noch ein paar Linux Befehle](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
### Windows
Du wirst MSYS2 (o.Ä.) und Git benötigen.
* Befolge die Installationsanleitung auf der [MSYS2 Homepage](http://www.msys2.org)
* Schließe alle offenen MSYS2 Fenster und öffne ein neues MSYS2 MinGW 64-bit Terminal
* Installiere Git mit dem Kommando: `pacman -S git`
### macOS
Du wirst Homebrew benötigen. Folge dafür den Anweisungen auf der [Homebrew homepage](https://brew.sh).
Nachdem Homebrew erfolgreich installiert ist, kannst Du mit _QMK aufsetzen_ fortfahren.
### Linux
Du benötigst Git, aber es ist ziemlich wahrscheinlich, dass es bereits installiert ist. Sollte dies nicht der Fall sein, kannst Du es mit dem folgenden Aufruf installieren:
* Debian / Ubuntu / Devuan: `apt-get install git`
* Fedora / Red Hat / CentOS: `yum install git`
* Arch Linux: `pacman -S git`
?> Docker ist ebenfalls eine Option für alle Plattformen. [Hier](de/getting_started_build_tools.md#docker) kannst Du dazu weitere Informationen finden.
## QMK aufsetzen
Wenn Du damit fertig bist, deine Linux/Unix Umgebung zu installieren, kannst Du damit fortfahren QMK herunterzuladen. Dafür werden wir mit Git das QMK Repository "klonen". Öffne ein Terminal oder ein MSYS2 MinGW Fenster, dies wirst Du für den Rest der Anleitung benötigen. In diesem Fenster rufst Du nun die beiden folgenden Kommandos auf:
```shell
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
```
?> Wenn Du bereits weißt, [wie man GitHub benutzt](de/getting_started_github.md), empfehlen wir, dass Du Dir ein eigenen Fork erstellst. Wenn Du nicht weißt, was das bedeuten soll, kannst Du diesen Ratschlag getrost ignorieren.
QMK liefert ein Script mit, das helfen soll, Dir alles Weitere abzunehmen. Du kannst es mit dem folgenden Befehl aufrufen:
util/qmk_install.sh
## Die Build-Umgebung testen
Nun sollte hoffentlich alles Nötige für eine funktionierende QMK Build-Umgebung installiert sein und Du solltest in der Lage sein, die QMK-Firmware zu kompilieren. Um dies mit einer `default` Tastaturbelegung zu testen, kannst Du den folgenden Befehl ausprobieren:
make <keyboard>:default
Der Befehl um z.B. die Firmware für ein _Clueboard 66%_ zu erzeugen lautet:
make clueboard/66/rev3:default
Wenn es fertig ist, sollte der Output ungefähr so ähnlich wie das Folgende aussehen:
```
Linking: .build/clueboard_66_rev3_default.elf [OK]
Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK]
Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK]
Checking file size of clueboard_66_rev3_default.hex [OK]
* The firmware size is fine - 26356/28672 (2316 bytes free)
```
# Eine eigene Tastaturbelegung erstellen
Du bist nun fertig mit dem Setup der Entwicklungsumgebung und solltest somit in der Lage sein, deine eigenen Tastaturbelegungen zu erstellen. Um fortzufahren, folge bitte der nächsten Anleitung unter [Die erste Firmware](de/newbs_building_firmware.md).

14
de/newbs_learn_more_resources.md Normal file
View File

@ -0,0 +1,14 @@
# Lernmaterial
Diese weiterführenden Ressourcen sind darauf ausgerichtet, Neulingen der QMK Commmunity mehr Informationen und ein besseres Verständnis zu einzelnen Themen zu bieten.
Git Ressourcen:
* [Gutes allgemeines Tutorial](https://www.codecademy.com/learn/learn-git) (auf Englisch)
* [Git spielerisch anhand von Beispielen lernen](https://learngitbranching.js.org/) (auf Englisch)
* [Mehr über den allgemeinen Umgang mit GitHub](getting_started_github.md)
* [Mehr über Git im Bezug zu QMK](contributing.md)
Mehr über die Arbeit mit der Befehlszeile:
* [Gutes allgemeines Tutorial über die Arbeit mit der Befehlszeile](https://www.codecademy.com/learn/learn-the-command-line) (auf Englisch)

100
de/newbs_testing_debugging.md Normal file
View File

@ -0,0 +1,100 @@
# Testen und Debuggen
Nachdem Du deine Tastatur mit deiner angepassten Firmware geflasht hast, ist es nun an der Zeit sie auszuprobieren. Mit ein bisschen Glück sollte alles ohne Probleme funktionieren, wenn dies nicht der Fall ist, soll dieses Dokument dir dabei helfen, herauszufinden wo das Problem liegt.
## Testen
Die Tastatur zu testen ist relativ selbsterklärend. Drücke jede der Tasten um dich zu versichern, dass der gesendete Keyode der ist, den du erwarten würdest. Dafür gibt es sogar ein paar Programme die helfen sollen, dass keine Taste ausgelassen wurde.
Anmerkung: Diese Programme werden weder von QMK bereitgestellt oder gutgeheißen.
* [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (Nur für Windows)
* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Nur für Mac)
* [Keyboard Tester](http://www.keyboardtester.com) (Web basiert)
* [Keyboard Checker](http://keyboardchecker.com) (Web basiert)
## Debuggen
Deine Tastatur wird Debug Informationen liefern wenn Du `CONSOLE_ENABLE = yes` in deiner `rules.mk` gesetzt hast. Die default-Ausgabe ist sehr beschränkt und kann wenn nötig durch die Aktivierung des Debug-Modes erhöht werden. Benutze dafür entweder den `DEBUG` Keycode in deiner Tastaturbelegung, das [Command](de/feature_command.md)-Feature oder füge den folgenden Code zu deiner Tastaturbelegung hinzu.
```c
void keyboard_post_init_user(void) {
// Customise these values to desired behaviour
debug_enable=true;
debug_matrix=true;
//debug_keyboard=true;
//debug_mouse=true;
}
```
### Debuggen mit der QMK Toolbox
Für kompatible Plattformen kann die [QMK Toolbox](https://github.com/qmk/qmk_toolbox) benutzt werden um Debug-Nachrichten deiner Tastatur anzuzeigen.
### Debuggen mit hid_listen
Bevorzugst Du es lieber auf der Befehlszeile zu debuggen? Dafür eignet sich das Programm [hid_listen](https://www.pjrc.com/teensy/hid_listen.html) von PJRC. Binaries sind für Windows, Linux und MacOS verfügbar.
<!-- FIXME: Describe the debugging messages here. -->
## Eigene Debug-Nachrichten senden
Manchmal ist es hilfreich Debug-Nachrichten innerhalb deines eigenen [Custom Codes](de/custom_quantum_functions.md) zu drucken. Das ist ziemlich einfach. Beginne damit `print.h` am Anfang deiner Datei zu inkludieren:
#include <print.h>
Danach stehen dir verschiedene Druck-Funktionen zur Verfügung:
* `print("string")`: Druckt einen simplen String
* `uprintf("%s string", var)`: Druckt einen formatierten String
* `dprint("string")` Druckt einen simplen String, aber nur wenn der Debug-Mode aktiviert ist
* `dprintf("%s string", var)`: Druckt einen formatierten String, aber nur wenn der Debug-Mode aktiviert ist
## Debug Beispiele
Anbei findest Du eine Sammlung von hilfreichen Beispielen. Für weitere Informationen Informationen sei an dieser Stelle auf [Debugging/Troubleshooting QMK](de/faq_debug.md) verwiesen.
### Which matrix position is this keypress?
### Welche Matrix Position hat dieser Tastenanschlag
Beim Portieren, oder bei der Fehlerdiagnose von PCB Problemen, ist es nützlich sich anzeigen zu lassen ob ein Tastenanschlag richtig erkannt wurde. Um die Protokollierung für diesen Fall zu aktivieren, füge bitte folgenden Code zu deiner Tastaturbelegung `keymap.c` hinzu.
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
// Wenn 'console' aktiviert ist wird die Matrix-Position und der Status jedes Tastenanschlags ausgegeben
#ifdef CONSOLE_ENABLE
uprintf("KL: kc: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed);
#endif
return true;
}
```
Beispiel Ausgabe:
```text
Waiting for device:.......
Listening:
KL: kc: 169, col: 0, row: 0, pressed: 1
KL: kc: 169, col: 0, row: 0, pressed: 0
KL: kc: 174, col: 1, row: 0, pressed: 1
KL: kc: 174, col: 1, row: 0, pressed: 0
KL: kc: 172, col: 2, row: 0, pressed: 1
KL: kc: 172, col: 2, row: 0, pressed: 0
```
### Wieviel Zeit wurde benötigt um einen Tastenanschlag zu detektieren?
Wenn Performance-Probleme auftreten ist es hilfreich die Frequenz, mit der die Matrix gescannt wird, zu wissen. Um dies in diesem Fall zu aktiveren füge, den folgenden Code zu deiner Tastaturbelegung in `config.h` hinzu.
```c
#define DEBUG_MATRIX_SCAN_RATE
```
Beispiel Ausgabe
```text
> matrix scan frequency: 315
> matrix scan frequency: 313
> matrix scan frequency: 316
> matrix scan frequency: 316
> matrix scan frequency: 316
> matrix scan frequency: 316
```

64
documentation_best_practices.md Normal file
View File

@ -0,0 +1,64 @@
# Documentation Best Practices
This page exists to document best practices when writing documentation for QMK. Following these guidelines will help to keep a consistent tone and style, which will in turn help other people more easily understand QMK.
# Page Opening
Your documentation page should generally start with an H1 heading, followed by a 1 paragraph description of what the user will find on this page. Keep in mind that this heading and paragraph will sit next to the Table of Contents, so keep the heading short and avoid long strings with no whitespace.
Example:
```
# My Page Title
This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone.
```
# Headings
Your page should generally have multiple "H1" headings. Only H1 and H2 headings will included in the Table of Contents, so plan them out appropriately. Excess width should be avoided in H1 and H2 headings to prevent the Table of Contents from getting too wide.
# Styled Hint Blocks
You can have styled hint blocks drawn around text to draw attention to it.
### Important
```
!> This is important
```
Renders as:
!> This is important
### General Tips
```
?> This is a helpful tip.
```
Renders as:
?> This is a helpful tip.
# Documenting Features
If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentences describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:
```markdown
# My Cool Feature
This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.
## My Cool Feature Keycodes
|Long Name|Short Name|Description|
|---------|----------|-----------|
|KC_COFFEE||Make Coffee|
|KC_CREAM||Order Cream|
|KC_SUGAR||Order Sugar|
```
Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.

40
documentation_templates.md Normal file
View File

@ -0,0 +1,40 @@
# Documentation Templates
This page documents the templates you should use when submitting new Keymaps and Keyboards to QMK.
## Keymap `readme.md` Template :id=keyboard-readmemd-template
Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](http://imgur.com) or another hosting service, please do not include images in your Pull Request.
Below the image you should write a short description to help people understand your keymap.
```
![Clueboard Layout Image](http://i.imgur.com/7Capi8W.png)
# Default Clueboard Layout
This is the default layout that comes flashed on every Clueboard. For the most
part it's a straightforward and easy to follow layout. The only unusual key is
the key in the upper left, which sends Escape normally, but Grave when any of
the Ctrl, Alt, or GUI modifiers are held down.
```
## Keyboard `readme.md` Template
```
# Planck
![Planck](http://i.imgur.com/q2M3uEU.jpg)
A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](http://qmk.fm/planck/)
* Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)
* Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0
* Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.massdrop.com/buy/planck-mechanical-keyboard?mode=guest_open)
Make example for this keyboard (after setting up your build environment):
make planck/rev4:default
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
```

48
driver_installation_zadig.md Normal file
View File

@ -0,0 +1,48 @@
# Bootloader Driver Installation with Zadig
QMK presents itself to the host as a regular HID keyboard device, and as such requires no special drivers. However, in order to flash your keyboard on Windows, the bootloader device that appears when you reset the board often *does*.
There are two notable exceptions: the Caterina bootloader, usually seen on Pro Micros, and the HalfKay bootloader shipped with PJRC Teensys, appear as a serial port and a generic HID device respectively, and so do not require a driver.
We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2, the `qmk_install.sh` script will have already installed the drivers for you.
## Installation
Put your keyboard into bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic](feature_bootmagic.md) docs for more details). Some boards use [Command](feature_command.md) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in.
Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure.
To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button.
Alternatively, hold `BOOT` while inserting the USB cable.
Zadig will automatically detect the bootloader device. You may sometimes need to check **Options → List All Devices**.
- For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`, and have a Vendor ID of `03EB`.
- USBasp bootloaders will appear as `USBasp`, with a VID/PID of `16C0:05DC`.
- AVR keyboards flashed with the QMK-DFU bootloader will be named `<keyboard name> Bootloader` and will also have the VID `03EB`.
- For most ARM keyboards, it will be called `STM32 BOOTLOADER`, and have a VID/PID of `0483:DF11`.
!> If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is probably not in bootloader mode. The arrow will be colored orange and you will be asked to confirm modifying a system driver. **Do not** proceed if this is the case!
If the arrow appears green, select the driver, and click **Install Driver**. The `libusb-win32` driver will usually work for AVR, and `WinUSB` for ARM, but if you still cannot flash the board, try installing a different driver from the list. USBAspLoader devices must use the `libusbK` driver.
![Zadig with a bootloader driver correctly installed](https://i.imgur.com/b8VgXzx.png)
Finally, unplug and replug the keyboard to make sure the new driver has been loaded. If you are using the QMK Toolbox to flash, exit and restart it too, as it can sometimes fail to recognize the driver change.
## Recovering from Installation to Wrong Device
If you find that you can no longer type with the keyboard, you may have accidentally replaced the driver for the keyboard itself instead of for the bootloader. This can happen when the keyboard is not in the bootloader mode. You can easily confirm this in Zadig - a healthy keyboard has the `HidUsb` driver installed on all of its interfaces:
![A healthy keyboard as seen by Zadig](https://i.imgur.com/Hx0E5kC.png)
Open the Device Manager and look for a device that looks like your keyboard.
![The board with the wrong driver installed, in Device Manager](https://i.imgur.com/L3wvX8f.png)
Right-click it and hit **Uninstall device**. Make sure to tick **Delete the driver software for this device** first.
![The Device Uninstall dialog, with the "delete driver" checkbox ticked](https://i.imgur.com/aEs2RuA.png)
Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again!
?> A full reboot of your computer may sometimes be necessary at this point, to get Windows to pick up the new driver.

71
eeprom_driver.md Normal file
View File

@ -0,0 +1,71 @@
# EEPROM Driver Configuration :id=eeprom-driver-configuration
The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
Driver | Description
-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`EEPROM_DRIVER = vendor` (default) | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. STM32L0xx and STM32L1xx will use the onboard dedicated true EEPROM. Other chips will generally act as "transient" below.
`EEPROM_DRIVER = i2c` | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below.
`EEPROM_DRIVER = spi` | Supports writing to SPI-based 25xx EEPROM chips. See the driver section below.
`EEPROM_DRIVER = transient` | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.
## Vendor Driver Configuration :id=vendor-eeprom-driver-configuration
#### STM32 L0/L1 Configuration :id=stm32l0l1-eeprom-driver-configuration
!> Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used.
`config.h` override | Description | Default Value
------------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------
`#define STM32_ONBOARD_EEPROM_SIZE` | The size of the EEPROM to use, in bytes. Erase times can be high, so it's configurable here, if not using the default value. | Minimum required to cover base _eeconfig_ data, or `1024` if VIA is enabled.
## I2C Driver Configuration :id=i2c-eeprom-driver-configuration
Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h:
`config.h` override | Description | Default Value
------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------
`#define EXTERNAL_EEPROM_I2C_BASE_ADDRESS` | Base I2C address for the EEPROM -- shifted left by 1 as per i2c_master requirements | 0b10100000
`#define EXTERNAL_EEPROM_I2C_ADDRESS(addr)` | Calculated I2C address for the EEPROM | `(EXTERNAL_EEPROM_I2C_BASE_ADDRESS)`
`#define EXTERNAL_EEPROM_BYTE_COUNT` | Total size of the EEPROM in bytes | 8192
`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32
`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2
`#define EXTERNAL_EEPROM_WRITE_TIME` | Write cycle time of the EEPROM, as specified in the datasheet | 5
Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`.
Alternatively, there are pre-defined hardware configurations for available chips/modules:
Module | Equivalent `#define` | Source
-----------------|---------------------------------|------------------------------------------
CAT24C512 EEPROM | `#define EEPROM_I2C_CAT24C512` | <https://www.sparkfun.com/products/14764>
RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C` | <https://www.sparkfun.com/products/14764>
24LC128 EEPROM | `#define EEPROM_I2C_24LC128` | <https://www.microchip.com/wwwproducts/en/24LC128>
24LC256 EEPROM | `#define EEPROM_I2C_24LC256` | <https://www.sparkfun.com/products/525>
MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895>
?> If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`.
## SPI Driver Configuration :id=spi-eeprom-driver-configuration
Currently QMK supports 25xx-series chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h:
`config.h` override | Description | Default Value
-----------------------------------------------|--------------------------------------------------------------------------------------|--------------
`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | SPI Slave select pin in order to inform that the EEPROM is currently being addressed | _none_
`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR` | Clock divisor used to divide the peripheral clock to derive the SPI frequency | `64`
`#define EXTERNAL_EEPROM_BYTE_COUNT` | Total size of the EEPROM in bytes | 8192
`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32
`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2
!> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.
## Transient Driver configuration :id=transient-eeprom-driver-configuration
The only configurable item for the transient EEPROM driver is its size:
`config.h` override | Description | Default Value
------------------------------- | ----------------------------------------- | -------------
`#define TRANSIENT_EEPROM_SIZE` | Total size of the EEPROM storage in bytes | 64
Default values and extended descriptions can be found in `drivers/eeprom/eeprom_transient.h`.

32
es/README.md Normal file
View File

@ -0,0 +1,32 @@
# Firmware Quantum Mechanical Keyboard
[![Versión actual](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
[![Estado de Build](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
[![Estado de la documentación](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
[![Contribuyentes en GitHub](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
[![Forks en GitHub](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
## ¿Qué es el firmware QMK?
QMK (*Quantum Mechanical Keyboard*) es una comunidad open source que mantiene el firmware QMK, QMK Toolbox, qmk.fm, y estos documentos. El firmware QMK es un firmware para teclados basado en [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) con algunas características útiles para controladores Atmel AVR, y más específicamente, la [línea de productos OLKB](http://olkb.com), el teclado [ErgoDox EZ](http://www.ergodox-ez.com), y la [línea de productos Clueboard](http://clueboard.co/). También ha sido portado a chips ARM chips usando ChibiOS. Lo puedes utilizar para manejar tu propio teclado ya sea cableado a mano o basado en una PCB personalizada.
## Cómo conseguirlo
Si estás pensando en contribuir con un keymap, teclado, or característica a QMK, la manera más sencilla es hacer un [fork del repositorio en GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box), y clonar tu repositorio localmente para hacer los cambios, subirlos, y abir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) desde tu fork.
De cualquier manera, también puedes descargarlo directamente en formatos ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), o clonarlo via git (`git@github.com:qmk/qmk_firmware.git`), o https (`https://github.com/qmk/qmk_firmware.git`).
## Cómo compilar
Antes de poder compilar, necesitarás [instalar un entorno](es/getting_started_build_tools.md) para el desarrollo de AVR y/o ARM. Una vez hayas completado este paso, usarás el comando `make` para compilar un teclado y keymap con la siguiente notación:
make planck/rev4:default
Este ejemplo compilaría la revisión `rev4` del teclado `planck` con el keymap `default`. No todos los teclados tienen revisiones (también llamados subproyectos o carpetas), en ese caso, se puede omitir:
make preonic:default
## Cómo personalizar
QMK tiene montones de [características](es/features.md) para explorar, y una buena cantidad de [documentación de referencia](http://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](es/keymap.md), y cambiando los [keycodes](es/keycodes.md).

122
es/_summary.md Normal file
View File

@ -0,0 +1,122 @@
* [Guía completa para novatos](es/newbs.md)
* [Empezando](es/newbs_getting_started.md)
* [Construyendo tu primer firmare](es/newbs_building_firmware.md)
* [Flasheando el firmware](es/newbs_flashing.md)
* [Testeando y depurando ](es/newbs_testing_debugging.md)
* [Mejores práticas](es/newbs_best_practices.md)
* [Recursos de aprendizaje](es/newbs_learn_more_resources.md)
* [QMK Basics](es/README.md)
* [Introducción a QMK](es/getting_started_introduction.md)
* [QMK CLI](es/cli.md)
* [Configuración de QMK CLI](es/cli_configuration.md)
* [Contribuyendo a QMK](es/contributing.md)
* [Cómo usar GitHub](es/getting_started_github.md)
* [Obtener ayuda](es/getting_started_getting_help.md)
* [Cambios incompatibles](es/breaking_changes.md)
* [30 Ago 2019](es/ChangeLog/20190830.md)
* [Preguntas frecuentes](es/faq.md)
* [General](es/faq_general.md)
* [Construir/Compilar QMK](es/faq_build.md)
* [Depurando/Encontrando problemas en QMK](es/faq_debug.md)
* [Keymap](es/faq_keymap.md)
* [Instalación de drivers con Zadig](es/driver_installation_zadig.md)
* Guías detalladas
* [Instalar herramientas construcción](es/getting_started_build_tools.md)
* [Guía Vagrant](es/getting_started_vagrant.md)
* [Instrucciones de Construcción/Compilado](es/getting_started_make_guide.md)
* [Flasheando Firmware](es/flashing.md)
* [Personalizando funcionalidad](es/custom_quantum_functions.md)
* [Visión general del Keymap](es/keymap.md)
* [Hardware](es/hardware.md)
* [Procesadores AVR](es/hardware_avr.md)
* [Drivers](es/hardware_drivers.md)
* Referencia
* [Pautas de teclados](es/hardware_keyboard_guidelines.md)
* [Opciones de configuración](es/config_options.md)
* [Keycodes](es/keycodes.md)
* [Convenciones de código - C](es/coding_conventions_c.md)
* [Convenciones de código - Python](es/coding_conventions_python.md)
* [Mejores prácticas de documentación](es/documentation_best_practices.md)
* [Plantillas de documentación](es/documentation_templates.md)
* [Glosario](es/reference_glossary.md)
* [Tests unitarios](es/unit_testing.md)
* [Funciones útiles](es/ref_functions.md)
* [Sporte configurador](es/reference_configurator_support.md)
* [Formato info.json](es/reference_info_json.md)
* [Desarrollo Python CLI](es/cli_development.md)
* [Características](es/features.md)
* [Keycodes Básicos](es/keycodes_basic.md)
* [Teclas US ANSI Shifted](es/keycodes_us_ansi_shifted.md)
* [Keycodes Quantum](es/quantum_keycodes.md)
* [Keycodes Avanzados](es/feature_advanced_keycodes.md)
* [Audio](es/feature_audio.md)
* [Auto Shift](es/feature_auto_shift.md)
* [Retroiluminación](es/feature_backlight.md)
* [Bluetooth](es/feature_bluetooth.md)
* [Bootmagic](es/feature_bootmagic.md)
* [Combos](es/feature_combo.md)
* [Comando](es/feature_command.md)
* [API Debounce](es/feature_debounce_type.md)
* [Switch DIP](es/feature_dip_switch.md)
* [Macros Dinámicas](es/feature_dynamic_macros.md)
* [Encoders](es/feature_encoders.md)
* [Grave Escape](es/feature_grave_esc.md)
* [Feedback Háptico](es/feature_haptic_feedback.md)
* [Controlador LCD HD44780](es/feature_hd44780.md)
* [Key Lock](es/feature_key_lock.md)
* [Layouts](es/feature_layouts.md)
* [Tecla Leader](es/feature_leader_key.md)
* [Matriz LED](es/feature_led_matrix.md)
* [Macros](es/feature_macros.md)
* [Teclas del ratón](es/feature_mouse_keys.md)
* [Driver OLED](es/feature_oled_driver.md)
* [Teclas One Shot](es/one_shot_keys.md)
* [Dispositivo de apuntado](es/feature_pointing_device.md)
* [Ratón PS/2](es/feature_ps2_mouse.md)
* [Iluminación RGB](es/feature_rgblight.md)
* [Matriz RGB](es/feature_rgb_matrix.md)
* [Cadete espacial](es/feature_space_cadet.md)
* [Teclado dividido](es/feature_split_keyboard.md)
* [Stenografía](es/feature_stenography.md)
* [Swap Hands](es/feature_swap_hands.md)
* [Tap Dance](es/feature_tap_dance.md)
* [Terminal](es/feature_terminal.md)
* [Impresora Térmica](es/feature_thermal_printer.md)
* [Unicode](es/feature_unicode.md)
* [Userspace](es/feature_userspace.md)
* [Velocikey](es/feature_velocikey.md)
* Para Makers y Modders
* [Guía de cableado a mano](es/hand_wire.md)
* [Guía de flasheado de ISP](es/isp_flashing_guide.md)
* [Guía de depuración de ARM](es/arm_debugging.md)
* [Driver I2C](es/i2c_driver.md)
* [Driver SPI](es/spi_driver.md)
* [Controles GPIO](es/internals_gpio_control.md)
* [Conversión Proton C](es/proton_c_conversion.md)
* Para entender en profundidad
* [Cómo funcionan los teclados](es/how_keyboards_work.md)
* [Entendiendo QMK](es/understanding_qmk.md)
* Otros temas
* [Usando Eclipse con QMK](es/other_eclipse.md)
* [Usando VSCode con QMK](es/other_vscode.md)
* [Soporte](es/getting_started_getting_help.md)
* [Cómo añadir traducciones](es/translating.md)
* QMK Internals (En progreso)
* [Defines](es/internals_defines.md)
* [Input Callback Reg](es/internals_input_callback_reg.md)
* [Dispositivo Midi](es/internals_midi_device.md)
* [Proceso de configuración de un dispositivo Midi](es/internals_midi_device_setup_process.md)
* [Utilidad Midi](es/internals_midi_util.md)
* [Funciones Send](es/internals_send_functions.md)
* [Herramientas Sysex](es/internals_sysex_tools.md)

8
es/hardware.md Normal file
View File

@ -0,0 +1,8 @@
# Hardware
QMK es compatible con una variedad de hardware. Si tu procesador puede ser dirigido por [LUFA](http://www.fourwalledcubicle.com/LUFA.php) o [ChibiOS](http://www.chibios.com), probablemente puedes hacer que QMK se ejecute en él. Esta sección explora cómo hacer que QMK se ejecute y se comunique con hardware de todo tipo.
* [Pautas de teclados](hardware_keyboard_guidelines.md)
* [Procesadores AVR](hardware_avr.md)
* Procesadores ARM (TBD)
* [Drivers](hardware_drivers.md)

180
es/hardware_avr.md Normal file
View File

@ -0,0 +1,180 @@
# Teclados con Procesadores AVR
Esta página describe el soporte para procesadores AVR en QMK. Los procesadores AVR incluyen el atmega32u4, atmega32u2, at90usb1286, y otros procesadores de la Corporación Atmel. Los procesadores AVR son MCUs de 8-bit que son diseñados para ser fáciles de trabajar. Los procesadores AVR más comunes en los teclados tienen USB y un montón de GPIO para permitir grandes matrices de teclado. Son los MCUs más populares para el uso en los teclados hoy en día.
Si aún no lo has hecho, debes leer las [Pautas de teclados](hardware_keyboard_guidelines.md) para tener una idea de cómo los teclados encajan en QMK.
## Añadir tu Teclado AVR a QMK
QMK tiene varias características para simplificar el trabajo con teclados AVR. Para la mayoría de los teclados no tienes que escribir ni una sola línea de código. Para empezar, ejecuta el archivo `util/new_keyboard.sh`:
```
$ ./util/new_keyboard.sh
Generating a new QMK keyboard directory
Keyboard Name: mycoolkb
Keyboard Type [avr]:
Your Name [John Smith]:
Copying base template files... done
Copying avr template files... done
Renaming keyboard files... done
Replacing %KEYBOARD% with mycoolkb... done
Replacing %YOUR_NAME% with John Smith... done
Created a new keyboard called mycoolkb.
To start working on things, cd into keyboards/mycoolkb,
or open the directory in your favourite text editor.
```
Esto creará todos los archivos necesarios para tu nuevo teclado, y rellenará la configuración con valores predeterminados. Ahora sólo tienes que personalizarlo para tu teclado.
## `readme.md`
Aquí es donde describirás tu teclado. Por favor sigue la [Plantilla del readme de teclados](documentation_templates.md#keyboard-readmemd-template) al escribir tu `readme.md`. Te animamos a colocar una imagen en la parte superior de tu `readme.md`. Por favor, utiliza un servicio externo como [Imgur](http://imgur.com) para alojar las imágenes.
## `<keyboard>.c`
Aquí es donde pondrás toda la lógica personalizada para tu teclado. Muchos teclados no necesitan nada aquí. Puedes aprender más sobre cómo escribir lógica personalizada en [Funciones Quantum Personalizadas](custom_quantum_functions.md).
## `<keyboard>.h`
Este es el archivo en el que defines tu(s) [Macro(s) de Layout](feature_layouts.md). Por lo menos deberías tener un `#define LAYOUT` para tu teclado que se ve algo así:
```c
#define LAYOUT( \
k00, k01, k02, \
k10, k11 \
) { \
{ k00, k01, k02 }, \
{ k10, KC_NO, k11 }, \
}
```
La primera mitad de la macro pre-procesador `LAYOUT` define la disposición física de las llaves. La segunda mitad de la macro define la matriz a la que están conectados los interruptores. Esto te permite tener una disposición física de las llaves que difiere de la matriz de cableado.
Cada una de las variables `k__` tiene que ser única, y normalmente sigue el formato `k<row><col>`.
La matriz física (la segunda mitad) debe tener un número de filas igualando `MATRIX_ROWS`, y cada fila debe tener exactamente `MATRIX_COLS` elementos. Si no tienes tantas teclas físicas puedes usar `KC_NO` para rellenar los espacios en blanco.
## `config.h`
El archivo `config.h` es donde configuras el hardware y el conjunto de características para tu teclado. Hay un montón de opciones que se pueden colocar en ese archivo, demasiadas para listar allí. Para obtener una visión de conjunto completa de las opciones disponibles consulta la página de [Opciones de Configuración](config_options.md).
### Configuración de hardware
En la parte superior de `config.h` encontrarás ajustes relacionados con USB. Estos controlan la apariencia de tu teclado en el Sistema Operativo. Si no tienes una buena razón para cambiar debes dejar el `VENDOR_ID` como `0xFEED`. Para el `PRODUCT_ID` debes seleccionar un número que todavía no esté en uso.
Cambia las líneas de `MANUFACTURER` y `PRODUCT` para reflejar con precisión tu teclado.
```c
#define VENDOR_ID 0xFEED
#define PRODUCT_ID 0x6060
#define DEVICE_VER 0x0001
#define MANUFACTURER Tú
#define PRODUCT mi_teclado_fantastico
```
?> Windows y macOS mostrarán el `MANUFACTURER` y `PRODUCT` en la lista de dispositivos USB. `lsusb` en Linux toma estos de la lista mantenida por el [Repositorio de ID USB](http://www.linux-usb.org/usb-ids.html) por defecto. `lsusb -v` mostrará los valores reportados por el dispositivo, y también están presentes en los registros del núcleo después de conectarlo.
### Configuración de la matriz del teclado
La siguiente sección del archivo `config.h` trata de la matriz de tu teclado. Lo primero que debes establecer es el tamaño de la matriz. Esto es generalmente, pero no siempre, el mismo número de filas y columnas como la disposición física de las teclas.
```c
#define MATRIX_ROWS 2
#define MATRIX_COLS 3
```
Una vez que hayas definido el tamaño de tu matriz, necesitas definir qué pines en tu MCU están conectados a filas y columnas. Para hacerlo simplemente especifica los nombres de esos pines:
```c
#define MATRIX_ROW_PINS { D0, D5 }
#define MATRIX_COL_PINS { F1, F0, B0 }
#define UNUSED_PINS
```
El número de entradas debe ser el mismo que el número que asignaste a `MATRIX_ROWS`, y del mismo modo para `MATRIX_COL_PINS` y `MATRIX_COLS`. No tienes que especificar `UNUSED_PINS`, pero puedes si deseas documentar qué pines están abiertos.
Finalmente, puedes especificar la dirección en la que apuntan tus diodos. Esto puede ser `COL2ROW` o `ROW2COL`.
```c
#define DIODE_DIRECTION COL2ROW
```
#### Matriz de patas directas
Para configurar un teclado en el que cada interruptor está conectado a un pin y tierra separados en lugar de compartir los pines de fila y columna, usa `DIRECT_PINS`. La asignación define los pines de cada interruptor en filas y columnas, de izquierda a derecha. Debe ajustarse a los tamaños dentro de `MATRIX_ROWS` y `MATRIX_COLS`. Usa `NO_PIN` para rellenar espacios en blanco. Sobreescribe el comportamiento de `DIODE_DIRECTION`, `MATRIX_ROW_PINS` y `MATRIX_COL_PINS`.
```c
// #define MATRIX_ROW_PINS { D0, D5 }
// #define MATRIX_COL_PINS { F1, F0, B0 }
#define DIRECT_PINS { \
{ F1, E6, B0, B2, B3 }, \
{ F5, F0, B1, B7, D2 }, \
{ F6, F7, C7, D5, D3 }, \
{ B5, C6, B6, NO_PIN, NO_PIN } \
}
#define UNUSED_PINS
/* COL2ROW, ROW2COL */
//#define DIODE_DIRECTION
```
### Configuración de retroiluminación
QMK soporta retroiluminación en la mayoría de los pines GPIO. Algunos de ellos pueden ser manejados por el MCU en hardware. Para más detalles, consulta la [Documentación de Retroiluminación](feature_backlight.md).
```c
#define BACKLIGHT_PIN B7
#define BACKLIGHT_LEVELS 3
#define BACKLIGHT_BREATHING
#define BREATHING_PERIOD 6
```
### Otras opciones de configuración
Hay un montón de características que se pueden configurar o ajustar en `config.h`. Debes consultar la página de [Opciones de Configuración](config_options.md) para más detalles.
## `rules.mk`
Usa el archivo `rules.mk` para decirle a QMK qué archivos construir y qué características habilitar. Si estás construyendo sobre un atmega32u4 deberías poder dejar mayormente los valores predeterminados. Si estás usando otro MCU es posible que tengas que ajustar algunos parámetros.
### Opciones MCU
Estas opciones le indican al sistema de compilación para qué CPU construir. Ten mucho cuidado si cambias cualquiera de estos ajustes. Puedes inutilizar tu teclado.
```make
MCU = atmega32u4
F_CPU = 16000000
ARCH = AVR8
F_USB = $(F_CPU)
OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
```
### Gestores de arranque
El gestor de arranque es una sección especial de tu MCU que te permite actualizar el código almacenado en el MCU. Piensa en ello como una partición de rescate para tu teclado.
#### Ejemplo de gestor de arranque
```make
BOOTLOADER = halfkay
```
#### Ejemplo de cargador DFU Atmel
```make
BOOTLOADER = atmel-dfu
```
#### Ejemplo de gestor de arranque Pro Micro
```make
BOOTLOADER = caterina
```
### Opciones de construcción
Hay un serie de características que se pueden activar o desactivar en `rules.mk`. Consulta la página de [Opciones de Configuración](config_options.md#feature-options) para obtener una lista detallada y una descripción.

36
es/hardware_drivers.md Normal file
View File

@ -0,0 +1,36 @@
# Controladores de hardware QMK
QMK se utiliza en un montón de hardware diferente. Mientras que el soporte para los MCUs y las configuraciones de matriz más comunes está integrado, hay una serie de controladores que se pueden añadir para soportar hardware adicional al teclado. Los ejemplos incluyen ratones y otros dispositivos de apuntamiento, extensores de i/o para teclados divididos, modúlos Bluetooth, y pantallas LCD, OLED y TFT.
<!-- FIXME: Esto debe hablar de cómo se integran los controladores en QMK y cómo puedes añadir su propio controlador.
# Descripción del sistema de controladores
-->
# Controladores disponibles
## ProMicro (Solo AVR)
Soporte para direccionar pines en el ProMicro por su nombre Arduino en lugar de su nombre AVR. 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.
## Controlador OLED SSD1306
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).
## IS31FL3731
Soporte para hasta 2 controladores. Cada controlador implementa 2 matrices charlieplex para direccionar LEDs individualmente usando I2C. Esto permite hasta 144 LEDs del mismo color o 32 LEDs RGB. Para obtener más información sobre cómo configurar el controlador, consulta la página de [Matriz RGB](feature_rgb_matrix.md).
## IS31FL3733
Soporte para hasta un solo controlador con espacio para expansión. Cada controlador puede controlar 192 LEDs individuales o 64 LEDs RGB. Para obtener más información sobre cómo configurar el controlador, consulta la página de [Matriz RGB](feature_rgb_matrix.md).

149
es/hardware_keyboard_guidelines.md Normal file
View File

@ -0,0 +1,149 @@
# Pautas del teclado QMK
Desde sus inicios, QMK ha crecido a pasos agigantados gracias a personas como tú que contribuyes a la creación y mantenimiento de nuestros teclados comunitarios. A medida que hemos crecido hemos descubierto algunos patrones que funcionan bien, y pedimos que te ajustes a ellos para que sea más fácil para que otras personas se beneficien de tu duro trabajo.
## Nombrar tu Teclado/Proyecto
Todos los nombres de teclado están en minúsculas, consistiendo sólo de letras, números y guiones bajos (`_`). Los nombres no pueden comenzar con un guión bajo. La barra de desplazamiento (`/`) se utiliza como un carácter de separación de subcarpetas.
Los nombres `test`, `keyboard`, y `all` están reservados para las órdenes de make y no pueden ser usados como un nombre de teclado o subcarpeta.
Ejemplos Válidos:
* `412_64`
* `chimera_ortho`
* `clueboard/66/rev3`
* `planck`
* `v60_type_r`
## Subcarpetas
QMK utiliza subcarpetas tanto para organización como para compartir código entre las revisiones del mismo teclado. Puedes anidar carpetas hasta 4 niveles de profundidad:
qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4
Si una subcarpeta tiene un archivo `rules.mk` será considerado un teclado compilable. Estará disponible en el configurador de QMK y se probará con `make all`. Si estás utilizando una carpeta para organizar varios teclados del mismo fabricante no debes tener un archivo `rules.mk`.
Ejemplo:
Clueboard utiliza subcarpetas para ambos propósitos: organización y revisiones de teclado.
* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master)
* [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards)
* [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) &larr; This is the organization folder, there's no `rules.mk` file
* [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) &larr; This is a compilable keyboard, it has a `rules.mk` file
* [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) &larr; This is also compilable- it uses `DEFAULT_FOLDER` to specify `rev3` as the default revision
* [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) &larr; compilable: `make clueboard/66/rev1`
* [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) &larr; compilable: `make clueboard/66/rev2`
* [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) &larr; compilable: `make clueboard/66/rev3` or `make clueboard/66`
## Estructura de carpetas de teclado
Su teclado debe estar ubicado en `qmk_firm cuidada/keyboards/` y el nombre de la carpeta debe ser el nombre de su teclado como se describe en la sección anterior. Dentro de esta carpeta debe haber varios archivos:
* `readme.md`
* `info.json`
* `config.h`
* `rules.mk`
* `<keyboard_name>.c`
* `<keyboard_name>.h`
### `readme.md`
Todos los proyectos necesitan tener un archivo `readme.md` que explica lo que es el teclado, quién lo hizo y dónde está disponible. Si es aplicable, también debe contener enlaces a más información, como el sitio web del fabricante. Por favor, sigue la [plantilla publicada](documentation_templates.md#keyboard-readmemd-template).
### `info.json`
Este archivo es utilizado por la [API de QMK](https://github.com/qmk/qmk_api). Contiene la información que [configurador de QMK](https://config.qmk.fm/) necesita mostrar en una representación de su teclado. También puede establecer metadatos aquí. Para más información, consulta la [página de referencia](reference_info_json.md).
### `config.h`
Todos los proyectos necesitan tener un archivo `config.h` que establece cosas como el tamaño de la matriz, nombre del producto, USB VID/PID, descripción y otros ajustes. En general, usa este archivo para establecer la información esencial y los valores predeterminados para tu teclado que siempre funcionarán.
### `rules.mk`
La presencia de este archivo indica que la carpeta es un destino de teclado y se puede utilizar en las órdenes `make`. Aquí es donde estableces el entorno de compilación para tu teclado y configuras el conjunto predeterminado de características.
### `<keyboard_name.c>`
Aquí es donde escribirás código personalizado para tu teclado. Típicamente escribirás código para inicializar e interactuar con el hardware de tu teclado. Si tu teclado se compone de sólo una matriz de teclas sin LEDs, altavoces u otro hardware auxiliar este archivo puede estar en blanco.
Las funciones siguientes se definen típicamente en este archivo:
* `void matrix_init_kb(void)`
* `void matrix_scan_kb(void)`
* `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
* `void led_set_kb(uint8_t usb_led)`
### `<keyboard_name.h>`
Este archivo se utiliza para definir la matriz para tu teclado. Debes definir al menos un macro de C que traduce una serie en una matriz que representa la matriz de interruptor físico para tu teclado. Si es posible construir tu teclado con múltiples diseños debes definir macros adicionales.
Si solo tienes un diseño debes llamar a esta macro `LAYOUT`.
Al definir diseños múltiples debes tener un diseño base, llamado `LAYOUT_all`, que soporte todas las posibles posiciones de switch en tu matriz, incluso si ese diseño es imposible de construir físicamente. Esta es la macro que deberías usar en tu keymap `predeterminado`. Debes tener keymaps adicionales llamados `default_ término layout>` que usen tus otras macros de diseño. Esto hará que sea más fácil para las personas utilizar los diseños que defines.
Los nombres de las macros de diseño son completamente minúsculas, excepto por la palabra `LAYOUT` en el frente.
Por ejemplo, si tienes un PCB de 60% que soporta ANSI e ISO podría definir los siguientes diseños y keymaps:
| Nombre de diseño | Nombre de keymap | Descripción |
|-------------|-------------|-------------|
| LAYOUT_all | default | Un diseño que soporta tanto ISO como ANSI |
| LAYOUT_ansi | default_ansi | Un diseño ANSI |
| LAYOUT_iso | default_iso | Un diseño ISO |
## Archivos de Imagen/Hardware
En un esfuerzo por mantener el tamaño de repo abajo ya no estamos aceptando archivos binarios de cualquier formato, con pocas excepciones. Alojarlos en otro lugar (por ejemplo <https://imgur.com>) y enlazarlos en el `readme.md` es preferible.
Para archivos de hardware (tales como placas, casos, pcb) puedes contribuir a [qmk.fm repo](https://github.com/qmk/qmk.fm) y estarán disponibles en [qmk.fm](http://qmk.fm). Archivos descargables se almacenan en `/<teclado>/` (nombre sigue el mismo formato que el anterior), se sirven en `http://qmk.fm/<teclado>/`, y se generan páginas de `/_pages/<teclado>/` que se sirven en la misma ubicación (Los archivos .md se generan en archivos .html mediante Jekyll). Echa un vistazo a la carpeta `lets_split` para ver un ejemplo.
## Predeterminados de teclado
Dada la cantidad de funcionalidad que expone QMK, es muy fácil confundir a los nuevos usuarios. Al armar el firmware predeterminado para tu teclado, te recomendamos limitar tus funciones y opciones habilitadas al conjunto mínimo necesario para soportar tu hardware. A continuación se formulan recomendaciones sobre características específicas.
### Bootmagic y Command
[Bootmagic](feature_bootmagic.md) and [Command](feature_command.md) son dos características relacionadas que permiten a un usuario controlar su teclado de manera no obvia. Te recomendamos que piense largo y tendido acerca de si vas a habilitar cualquiera de las características, y cómo vas a exponer esta funcionalidad. Tengas en cuenta que los usuarios que quieren esta funcionalidad puede habilitarla en sus keymaps personales sin afectar a todos los usuarios novatos que pueden estar usando tu teclado como su primera tarjeta programable.
De lejos el problema más común con el que se encuentran los nuevos usuarios es la activación accidental de Bootmagic mientras están conectando su teclado. Están sosteniendo el teclado por la parte inferior, presionando sin saberlo en alt y barra espaciadora, y luego se dan cuenta de que estas teclas han sido intercambiadas en ellos. Recomendamos dejar esta característica deshabilitada de forma predeterminada, pero si la activas consideres establecer la opción `BOOTMAGIC_KEY_SALT` a una tecla que es difícil de presionar al conectar el teclado.
Si tu teclado no tiene 2 teclas de cambio debes proporcionar un predeterminado de trabajo para `IS_COMMAND`, incluso cuando haya definido `COMMAND_ENABLE = no`. Esto dará a sus usuarios un valor predeterminado para ajustarse a si lo hacen enable Command.
## Programación de teclado personalizado
Como se documenta en [Funcionalidad de Adaptación](custom_quantum_functions.md) puedes definir funciones personalizadas para tu teclado. Por favor, tengas en cuenta que sus usuarios pueden querer personalizar ese comportamiento así, y hacer que sea posible para que puedan hacer eso. Si está proporcionando una función personalizada, por ejemplo `process_record_kb()`, asegúrese de que su función también llame a la versión` `_user()` de la llamada. También debes tener en cuenta el valor de retorno de la versión `_user()`, y ejecutar sólo tu código personalizado si el usuario devuelve `true`.
## Proyectos Sin Producción/Conectados A Mano
Estamos encantados de aceptar cualquier proyecto que utilice QMK, incluidos los prototipos y los cableados de mano, pero tenemos una carpeta `/keyboards/handwired/` separada para ellos, por lo que la carpeta `/keyboards/` principal no se llena. Si un proyecto prototipo se convierte en un proyecto de producción en algún momento en el futuro, ¡estaremos encantados de moverlo a la carpeta `/keyboards/` principal!
## Advertencias como errores
Al desarrollar su teclado, tengas en cuenta que todas las advertencias serán tratadas como errores - estas pequeñas advertencias pueden acumularse y causar errores más grandes en el camino (y pierdan es generalmente una mala práctica).
## Derechos de autor
Si estás adaptando la configuración de tu teclado de otro proyecto, pero no utilizando el mismo código, asegúrese de actualizar la cabecera de derechos de autor en la parte superior de los archivos para mostrar tu nombre, en este formato:
Copyright 2017 Tu nombre <tu@email.com>
Si estás modificando el código de otra persona y sólo ha hecho cambios triviales debes dejar su nombre en la declaración de derechos de autor. Si has hecho un trabajo significativo en el archivo debe agregar tu nombre a la de ellos, así:
Copyright 2017 Su nombre <original_author@ejemplo.com> Tu nombre <tu@ejemplo.com>
El año debe ser el primer año en que se crea el archivo. Si el trabajo se hizo a ese archivo en años posteriores puedes reflejar que mediante la adición del segundo año a la primera, como así:
Copyright 2015-2017 Tu nombre <tu@ejemplo.com>
## Licencia
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](http://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)!

23
es/newbs.md Normal file
View File

@ -0,0 +1,23 @@
# La guía completa de QMK para novatos
QMK es un poderoso firmware Open Source para tu teclado mecánico. Puedes utilizar QMK para personalizar tu teclado en maneras a la vez simples y potentes. Gente de todos los niveles de habilidad, desde completos novatos hasta expertos programadores, han utilizado con éxito QMK para personalizar sus teclados. Esta guía te ayudará a hacer lo mismo, sin importar tu nivel de habilidad.
¿No estás seguro de si tu teclado puede ejecutar QMK? Si es un teclado mecánico construido por ti mismo probablemente puedas. Damos soporte a [gran número de placas de hobbistas](http://qmk.fm/keyboards/), e incluso si tu teclado actual no pudiera ejecutar QMK no deberías tener problemas encontrando uno que cumpliera tus necesidades.
## Visión general
Hay 7 secciones principales en esta guía:
* [Empezando](newbs_getting_started.md)
* [Construyendo tu primer firmware](newbs_building_firmware.md)
* [Construyendo tu primer firmware usando la GUI](newbs_building_firmware_configurator.md)
* [Flasheando el firmware](newbs_flashing.md)
* [Testeando y depurando](newbs_testing_debugging.md)
* [Mejores práticas](newbs_best_practices.md)
* [Recursos de aprendizaje](newbs_learn_more_resources.md)
Esta guía está enfocada en ayudar a alguien que nunca ha compilado software con anterioridad. Toma decisiones y hace recomendaciones teniendo en cuenta este punto de vista. Hay métodos alternativos para muchos de estos procedimientos, y soportamos la mayoría de esas alternativas. Si tienes alguna duda sobre cómo llevar a cabo una tarea nos puedes [preguntar para que te guiemos](getting_started_getting_help.md).
## Recursos adicionales
* [Blog de Básicos de Thomas Baart's QMK](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – Un blog creado por un usuario que cubre lo básico sobre cómo usar el firmware QMK Firmware, visto desde la perspectiva de un usuario nuevo.

159
es/newbs_best_practices.md Normal file
View File

@ -0,0 +1,159 @@
# Mejores prácticas
## O, "Cómo aprendí a dejar de preocuparme y amarle a Git."
Este documento procura instruir a los novatos en las mejores prácticas para tener una experiencia más fácil en contribuir a QMK. Te guiaremos por el proceso de contribuir a QMK, explicando algunas maneras de hacerlo más fácilmente, y luego romperemos algunas cosas para enseñarte cómo arreglarlas.
En este documento suponemos un par de cosas:
1. Tienes una cuenta de GitHub, y has hecho un [fork del repo qmk_firmware](getting_started_github.md) en tu cuenta.
2. Has [configurado tu entorno de desarrollo](newbs_getting_started.md?id=environment-setup).
## La rama master de tu fork: Actualizar a menudo, nunca commit
Se recomienda que para desarrollo con QMK, lo que sea que estés haciendo, mantener tu rama `master` actualizada, pero **nunca** commit en ella. Mejor, haz todos tus cambios en una rama de desarrollo y manda pull requests de tus ramas mientras programas.
Para evitar los conflictos de merge &mdash; cuando dos o más usuarios han editado la misma parte de un archivo al mismo tiempo &mdash; mantén tu rama `master` actualizada, y empieza desarrollo nuevo creando una nueva rama.
### Actualizando tu rama master
Para mantener tu rama `master` actualizada, se recomienda agregar el repository ("repo") de Firmware QMK como un repo remoto en git. Para hacer esto, abre tu interfaz de línea de mandatos y ingresa:
```
git remote add upstream https://github.com/qmk/qmk_firmware.git
```
Para verificar que el repo ha sido agregado, ejecuta `git remote -v`, y lo siguiente debe aparecer:
```
$ git remote -v
origin https://github.com/<your_username>/qmk_firmware.git (fetch)
origin https://github.com/<your_username>/qmk_firmware.git (push)
upstream https://github.com/qmk/qmk_firmware.git (fetch)
upstream https://github.com/qmk/qmk_firmware.git (push)
```
Ya que has hecho esto, puedes buscar actualizaciones del repo ejecutando `git fetch upstream`. Esto busca las ramas y etiquetas &mdash; juntos conocidos como "refs" &mdash; del repo QMK, que ahora tiene el apodo `upstream`. Ahora podemos comparar los archivos en nuestro fork `origin` con los de QMK.
Para actualizar la rama master de tu fork, ejecuta lo siguiente, pulsando Intro después de cada línea:
```
git checkout master
git fetch upstream
git pull upstream master
git push origin master
```
Esto te coloca en tu rama master, busca los refs del repo de QMK, descarga la rama `master` actual a tu computadora, y después lo sube a tu fork.
### Hacer cambios
Para hacer cambios, crea una nueva rama ejecutando:
```
git checkout -b dev_branch
git push --set-upstream origin dev_branch
```
Esto crea una nueva rama llamada `dev_branch`, te coloca en ella, y después guarda la nueva rama a tu fork. El parámetro `--set-upstream` le dice a git que use tu fork y la rama `dev_branch` cada vez que uses `git push` o `git pull` en esta rama. Solo necesitas usarlo la primera que que subes cambios; ya después, puedes usar `git push` o `git pull`, sin usar los demás parámetros.
!> Con `git push`, puedes usar `-u` en vez de `--set-upstream` &mdash; `-u` es un alias de `--set-upstream`.
Puedes nombrar tu rama casi cualquier cosa, pero se recomienda ponerle algo con relación a los cambios que vas a hacer.
Por defecto `git checkout -b` se basará tu nueva rama en la rama en la cual estás actualmente. Puedes basar tu rama en otra rama existente agregando el nombre de la rama al comando:
```
git checkout -b dev_branch master
```
Ahora que tienes una rama development, abre tu editor de texto y haz los cambios que quieres. Se recomienda hacer varios commits pequeños a tu rama; de este modo cualquier cambio que causa problemas puede ser rastreado y deshecho si fuera necesario. Para hacer tus cambios, edita y guarda los archivos que necesitas actualizar, agrégalos al *staging area* de Git, y luego haz un commit a tu rama:
```
git add path/to/updated_file
git commit -m "My commit message."
```
`git add` agrega los archivos que han sido cambiados al *staging area* de Git, lo cual es la "zona de preparación"de Git. Este contiene los cambios que vas a *commit* usando `git commit`, que guarda los cambios en el repo. Usa un mensaje de commit descriptivo para que puedas saber que ha cambiado fácilmente.
!> Si has cambiado muchos archivos, pero todos los archivos son parte del mismo cambio, puedes usar `git add .` para agregar todos los archivos cambiados que están en tu directiro actual, en vez de agregar cada archivo manualmente.
### Publicar tus cambios
El útimo paso es subir tus cambios a tu fork. Para hacerlo, ejecuta `git push`. Ahora Git publicará el estado actual de `dev_branch` a tu fork.
## Resolver los conflictos del merge
A veces cuando el trabajo en una rama tarda mucho tiempo en completarse, los cambios que han sido hechos por otros chocan con los cambios que has hecho en tu rama cuando abres un pull request. Esto se llama un *merge conflict*, y es algo que ocurre cuando varias personas editan las mismas partes de los mismos archivos.
### Rebase tus cambios
Un *rebase* es la manera de Git de tomar los cambios que se aplicaron en un punto, deshacerlos, y aplicar estos mismos cambios en otro punto. En el caso de un conflicto de merge, puedes hacer un rebase de tu rama para recoger los cambios que has hecho.
Para empezar, ejecuta lo siguiente:
```
git fetch upstream
git rev-list --left-right --count HEAD...upstream/master
```
El comando `git rev-list` ejecutado aquí muestra el número de commits que difieren entre la rama actual y la rama master de QMK. Ejecutamos `git fetch` primero para asegurarnos de que tenemos los refs que representan es estado actual del repo upstream. El output del comando `git rev-list` muestra dos números:
```
$ git rev-list --left-right --count HEAD...upstream/master
7 35
```
El primer número representa el número de commits en la rama actual desde que fue creada, y el segundo número es el número de commits hecho a `upstream/master` desde que la rama actual fue creada, o sea los cambios que no están registrados en la rama actual.
Ahora que sabemos el estado actual de la rama actual y el del repo upstream, podemos empezar una operación rebase:
```
git rebase upstream/master
```
Esto le dice a Git que deshaga los commits en la rama actual, y después los re-aplica en la rama master de QMK.
```
$ git rebase upstream/master
First, rewinding head to replay your work on top of it...
Applying: Commit #1
Using index info to reconstruct a base tree...
M conflicting_file_1.txt
Falling back to patching base and 3-way merge...
Auto-merging conflicting_file_1.txt
CONFLICT (content): Merge conflict in conflicting_file_1.txt
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch' to see the failed patch
Patch failed at 0001 Commit #1
Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".
```
Esto nos dice que tenemos un conflicto de merge, y nos dice el nombre del archivo con el conflict. Abre el archivo en tu editor de texto, y en alguna parte del archivo verás algo así:
```
<<<<<<< HEAD
<p>For help with any issues, email us at support@webhost.us.</p>
=======
<p>Need help? Email support@webhost.us.</p>
>>>>>>> Commit #1
```
La línea `<<<<<<< HEAD` marca el principio de un conflicto de merge, y la línea `>>>>>>> Commit #1` marca el final, con las secciones de conflicto separadas por `=======`. La parte del lado `HEAD` is de la versión de QMK master del archivo, y la parte marcada con el mensaje de commit es de la rama actual.
Ya que Git rastrea *cambios de archivos* en vez del contenido de los archivos directamente, si Git no puede encontrar el texto que estaba en el archivo antes del último commit, no sabrá cómo editar el archivo. El editar el archivo de nuevo resolverá este conflicto. Haz tus cambios, y guarda el archivo.
```
<p>Need help? Email support@webhost.us.</p>
```
Ahora ejecuta:
```
git add conflicting_file_1.txt
git rebase --continue
```
Git registra los cambios al archivo con conflictos, y sigue aplicando los commits de nuestra rama hasta llegar al final.

81
es/newbs_building_firmware.md Normal file
View File

@ -0,0 +1,81 @@
# Construyendo tu primer firmware
Ahora que has configurado tu entorno de construcción estas listo para empezar a construir firmwares personalizados. Para esta sección de la guía alternaremos entre 3 programas - tu gestor de ficheros, tu editor de texto , y tu ventana de terminal. Manten los 3 abiertos hasta que hayas acabado y estés contento con el firmware de tu teclado.
Si has cerrado y reabierto la ventana de tu terminal después de seguir el primero paso de esta guía, no olvides hacer `cd qmk_firmware` para que tu terminal esté en el directorio correcto.
## Navega a tu carpeta de keymaps
Comienza navegando a la carpeta `keymaps` correspondiente a tu teclado.
?> Si estás en macOS o Windows hay comandos que puedes utilizar fácilmente para abrir la carpeta keymaps.
?> macOS:
abre keyboards/<keyboard_folder>/keymaps
?> Windows:
inicia .\\keyboards\\<keyboard_folder>\\keymaps
## Crea una copia del keymap `default`
Una vez que tengas la carpeta `keymaps` abierta querrás crear una copia de la carpeta `default`. Recomendamos encarecidamente que nombres la carpeta igual que tu nombre de usuario de GitHub, pero puedes utilizar el nombre que quieras siempre que contenga sólo letras en minúscula, números y el caracter de guión bajo.
Para automatizar el proceso, también tienes la opción de ejecutar el script `new_keymap.sh`.
Navega a la carpeta `qmk_firmware/util` e introduce lo siguiente:
```
./new_keymap.sh <keyboard path> <username>
```
Por ejemplo, para un usuario llamado John, intentando hacer un keymap nuevo para el 1up60hse, tendría que teclear
```
./new_keymap.sh 1upkeyboards/1up60hse john
```
## Abre `keymap.c` con tu editor de texto favorito
Abre tu `keymap.c`. Dentro de este fichero encontrarás la estructura que controla cómo se comporta tu teclado. En lo alto de `keymap.c` puede haber distintos defines y enums que hacen el keymap más fácil de leer. Continuando por abajo encontrarás una línea con este aspecto:
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
Esta línea indica el comienzo del listado de Capas. Debajo encontrarás líneas que contienen o bien `LAYOUT` o `KEYMAP`, y estas líneas indican el comienzo de una capa. Debajo de esa línea está la lista de teclas que pertenecen a esa capa concreta.
!> Cuando estés editando tu fichero de keymap ten cuidado con no añadir ni eliminar ninguna coma. Si lo haces el firmware dejará de compilar y puede no ser fácil averiguar dónde está la coma faltante o sobrante.
## Personaliza el Layout a tu gusto
Cómo completar esta paso depende enteramente de ti. Haz ese pequeño cambio que querías o rehaz completamente todo. Puedes eliminar capas si no las necesitas todas, o añadir nuevas hasta un total de 32. Comprueba la siguiente documentación para descubrir qué es lo que puedes definir aquí:
* [Keycodes](keycodes.md)
* [Características](features.md)
* [Preguntas frecuentes](faq.md)
?> Mientras estás descubriendo cómo funcionan los keymaps, haz pequeños cambios. Cambios mayores pueden hacer difícil la depuración de problemas que puedan aparecer.
## Construye tu firmware
Cuando los cambios a tu keymap están completos necesitarás construir el firmware. Para hacerlo vuelve a la ventana de tu terminal y ejecuta el siguiente comando:
make <my_keyboard>:<my_keymap>
Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un planck rev5, utilizarás el siguiente comando:
make planck/rev5:xyverz
Mientras compila, recibirás un montón de información de salida en la pantalla informándote de qué ficheros están siendo compilados. Debería acabar con una información similar a esta:
```
Linking: .build/planck_rev5_xyverz.elf [OK]
Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
Checking file size of planck_rev5_xyverz.hex [OK]
* File size is fine - 18392/28672
```
## Flashea tu firmware
Continua con [Flasheando el firmware](newbs_flashing.md) para aprender cómo escribir tu firmware nuevo en tu teclado.

105
es/newbs_building_firmware_configurator.md Normal file
View File

@ -0,0 +1,105 @@
# Configurador QMK
El [Configurador QMK](https://config.qmk.fm) es un entorno gráfico online que genera ficheros hexadecimales de Firmware QMK.
?> **Por favor sigue estos pasos en orden.**
Ve el [Video tutorial](https://www.youtube.com/watch?v=-imgglzDMdY)
El Configurador QMK functiona mejor con Chrome/Firefox.
!> **Ficheros de otras herramientas como KLE, o kbfirmware no serán compatibles con el Configurador QMK. No las cargues, no las importes. El configurador Configurador QMK es una herramienta DIFERENTE. **
## Seleccionando tu teclado
Haz click en el desplegable y selecciona el teclado para el que quieres crear el keymap.
?> Si tu teclado tiene varias versiones, asegúrate de que seleccionas la correcta.**
Lo diré otra vez porque es importante
!> **ASEGÚRATE DE QUE SELECCIONAS LA VERSIÓN CORRECTA!**
Si se ha anunciado que tu teclado funciona con QMK pero no está en la lista, es probable que un desarrollador no se haya encargado de él aún o que todavía no hemos tenido la oportunidad de incluirlo. Abre un issue en [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) solicitando soportar ese teclado un particular, si no hay un [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) activo para ello. Hay también teclados que funcionan con QMK que están en las cuentas de GitHub de sus manufacturantes. Acuérdate de comprobar esto también.
## Eligiendo el layout de tu teclado
Elige el layout que mejor represente el keymap que quieres crear. Algunos teclados no tienen suficientes layouts o layouts correctos definidos aún. Serán soportados en el futuro.
## Nombre del keymap
Llama a este keymap como quieras.
?> Si estás teniendo problemas para compilar, puede merecer la pena probar un cambio de nombre, ya que puede que ya exista en el repositorio de QMK Firmware.
## Creando Tu keymap
La adición de keycodes se puede hacer de 3 maneras.
1. Arrastrando y soltando
2. Clickando en un hueco vacío en el layout y haciendo click en el keycode que deseas
3. Clickando en un hueco vacío en el layout, presionando la tecla física en tu teclado.
Mueve el puntero de tu ratón sobre una tecla y un pequeño extracto te dirá que es lo que hace la tecla. Para una descripción más detallada por favor, mira
[Referencia básica de keycodes](https://docs.qmk.fm/#/keycodes_basic)
[Referencia avanzada de keycodes](https://docs.qmk.fm/#/feature_advanced_keycodes)
En el caso de que no puedas encontrar un layout que suporte tu keymap, por ejemplo, tres huecos para la barra espaciadora, dos huecos para el retroceso o dos huecos para shift etc etc, rellènalos TODOS.
### Ejemplo:
3 huecos para barra espaciadora: Rellena TODOS con barra espaciadora
2 huecos para retroceso: Rellena AMBOS con retroceso
2 huecos para el shift derecho: Rellena AMBOS con shift derecho
1 hueco para el shift izquierdo y 1 hueco para soporte iso: Rellena ambos con el shift izquierdo
5 huecos , pero sólo 4 teclas: Intuye y comprueba o pregunta a alguien que lo haya hecho anteriormente.
## Guardando tu keymap para ediciones futuras
Cuando estés satisfecho con un teclado o quieres trabajar en el después, pulsa el botón `Exportar Keymap`. Guardára tu keymap con el nombre que elijas seguido de .json.
Entonces podrás cargar este fichero .json en el futuro pulsando el botón `Importar Keymap`.
!> **PRECAUCIÓN:** No es el mismo tipo de fichero .json usado en kbfirmware.com ni ninguna otra herramienta. Si intentas utilizar un fichero .json de alguna de estas herramientas con el Configurador QMK, existe la posibilidad de que tu teclado **explote**.
## Generando tu fichero de firmware
Pulsa el botón verde `Compilar`.
Cuando la compilación haya acabado, podrás presionar el botón verde `Descargar Firmware`.
## Flasheando tu teclado
Por favor, dirígete a la sección de [Flashear firmware](newbs_flashing.md)
## Problemas comunes
#### Mi fichero .json no funciona
Si el fichero .json fue generado con el Configurador QMK, enhorabuena, has dado con un bug. Abre una issue en [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)
Si no....cómo no viste el mensaje en negrita que puse arriba diciendo que no hay que utilizar otros ficheros .json?
#### Hay espacios extra en mi layout ¿Qué hago?
Si te refieres a tener tres espacios para la barra espaciadora, la mejor decisión es rellenar los tres con la barra espaciadora. También se puede hacer lo mismo con las teclas retroceso y las de shift
#### Para qué sirve el keycode.......
Por favor, mira
[Referencia básica de keycodes](https://docs.qmk.fm/#/keycodes_basic)
[Referencia avanzada de keycodes](https://docs.qmk.fm/#/feature_advanced_keycodes)
#### No compila
Por favor, revisa las otras capas de tu keymap para asegurarte de que no hay teclas aleatorias presentes.
## Problemas y bugs
Siempre aceptamos peticiones de clientes y reportes de bug. Por favor, indícalos en [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)

351
es/newbs_flashing.md Normal file
View File

@ -0,0 +1,351 @@
# Flasheando tu teclado
Ahora que has construido tu fichero de firmware personalizado querrás flashear tu teclado.
## Flasheando tu teclado con QMK Toolbox
La manera más simple de flashear tu teclado sería con [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases).
De todos modos, QMK Toolbox actualmente sólo está disponible para Windows y macOS. Si estás usando Linux (o sólo quisieras flashear el firmware desde la línea de comandos), tendrás que utilizar el [método indicado abajo](newbs_flashing.md#flash-your-keyboard-from-the-command-line).
### Cargar el fichero en QMK Toolbox
Empieza abriendo la aplicación QMK Toolbox. Tendrás que buscar el fichero de firmware usando Finder o Explorer. El firmware de teclado puede estar en uno de estos dos formatos- `.hex` o `.bin`. QMK intenta copiar el apropiado para tu teclado en el fichero raíz `qmk_firmware`.
?> Si tu estás on Windows o macOS hay comandos que puedes usar para abrir fácilmente la carpeta del firmware actual en Explorer o Finder.
?> Windows:
start .
?> macOS:
open .
El fichero de firmware sempre sigue el siguiente formato de nombre:
<nombre_teclado>_<nombre_keymap>.{bin,hex}
Por ejemplo, un `plank/rev5` con un keymap `default` tendrá este nombre de fichero:
planck_rev5_default.hex
Una vez que hayas localizado el fichero de tu firmware arrástralo a la caja "Fichero local" en QMK Toolbox, o haz click en "Abrir" y navega allí donde tengas almacenado tu fichero de firmware.
### Pon tu teclado en modo DFU (Bootloader)
Para poder flashear tu firmware personalizado tienes que poner tu teclado en un modo especial que permite flasheado. Cuando está en este modo no podrás teclear o utilizarlo para ninguna otra cosa. Es muy importante que no desconectes tu teclado, de lo contrario interrumpirás el proceso de flasheo mientras el firmware se está escribiendo.
Diferentes teclados tienen diferentes maneras de entrar en este modo especial. Si tu PCB actualmente ejecuta QMK o TMK y no has recibido instrucciones específicas, intenta los siguientes pasos en orden:
* Manten pulsadas ambas teclas shift y pulsa `Pause`
* Manten pulsadas ambas teclas shift y pulsa `B`
* Desconecta tu teclado, mantén pulsada la barra espaciadora y `B` al mismo tiempo, conecta tu teclado y espera un segundo antes de dejar de pulsar las teclas
* Pulsa el botón físico `RESET` situado en el fondo de la PCB
* Localiza los pines en la PCB etiquetados on `BOOT0` o `RESET`, puentea estos dos juntos cuando enchufes la PCB
Si has tenido éxito verás un mensaje similar a este en QMK Toolbox:
```
*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
*** DFU device connected
```
### Flashea tu teclado
Haz click en el botón `Flash` de QMK Toolbox. Verás una información de salida similar a esta:
```
*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
*** DFU device connected
*** Attempting to flash, please don't remove device
>>> dfu-programmer atmega32u4 erase --force
Erasing flash... Success
Checking memory from 0x0 to 0x6FFF... Empty.
>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
Checking memory from 0x0 to 0x55FF... Empty.
0% 100% Programming 0x5600 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
0% 100% Reading 0x7000 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
Validating... Success
0x5600 bytes written into 0x7000 bytes memory (76.79%).
>>> dfu-programmer atmega32u4 reset
*** DFU device disconnected
*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
```
## Flashea tu teclado desde la línea de comandos
Lo primero que tienes que saber es qué bootloader utiliza tu teclado. Hay cuatro bootloaders pincipales que se usan habitualmente . Pro-Micro y sus clones usan CATERINA, Teensy's usa Halfkay, las placas OLKB usan QMK-DFU, y otros chips atmega32u4 usan DFU.
Puedes encontrar más información sobre bootloaders en la página [Instrucciones de flasheado e información de Bootloader](flashing.md).
Si sabes qué bootloader estás usando, en el momento de compilar el firmware, podrás añadir algún texto extra al comando `make` para automatizar el proceso de flasheado.
### DFU
Para eo bootloader DFU, cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el siguiente comando de construcción:
make <my_keyboard>:<my_keymap>:dfu
Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un planck rev5, utilizarás este comando:
make planck/rev5:xyverz:dfu
Una vez que finalice de compilar, deberá aparecer lo siguiente:
```
Linking: .build/planck_rev5_xyverz.elf [OK]
Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
Checking file size of planck_rev5_xyverz.hex
* File size is fine - 18574/28672
```
Después de llegar a este punto, el script de construcción buscará el bootloader DFU cada 5 segundos. Repetirá lo siguiente hasta que se encuentre el dispositivo o lo canceles:
dfu-programmer: no device present.
Error: Bootloader not found. Trying again in 5s.
Una vez haya hecho esto, tendrás que reiniciar el controlador. Debería mostrar una información de salida similar a esta:
```
*** Attempting to flash, please don't remove device
>>> dfu-programmer atmega32u4 erase --force
Erasing flash... Success
Checking memory from 0x0 to 0x6FFF... Empty.
>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
Checking memory from 0x0 to 0x55FF... Empty.
0% 100% Programming 0x5600 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
0% 100% Reading 0x7000 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
Validating... Success
0x5600 bytes written into 0x7000 bytes memory (76.79%).
>>> dfu-programmer atmega32u4 reset
```
?> Si tienes problemas con esto- del estilo de `dfu-programmer: no device present` - por favor consulta las [Preguntas frecuentes de construcción](faq_build.md).
#### Comandos DFU
Hay un número de comandos DFU que puedes usar para flashear firmware a un dispositivo DFU:
* `:dfu` - Esta es la opción normal y espera hasta que un dispositivo DFU esté disponible, entonces flashea el firmware. Esperará reintentando cada 5 segundos, para ver si un dispositivo DFU ha aparecido.
* `:dfu-ee` - Esta flashea un fichero `eep` en vez del hex normal. Esto no es lo común.
* `:dfu-split-left` - Esta flashea el firmware normal, igual que la opción por defecto (`:dfu`). Sin embargo, también flashea el fichero EEPROM "Lado Izquierdo" para teclados divididos. _Esto es ideal para los ficheros divididos basados en Elite C._
* `:dfu-split-right` - Esto flashea el firmware normal, igual que la opción por defecto (`:dfu`). Sin embargo, también flashea el fichero EEPROM "Lado Derecho" para teclados divididos. _Esto es ideal para los ficheros divididos basados en Elite C._
### Caterina
Para placas Arduino y sus clones (como la SparkFun ProMicro), cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el siguiente comando de construcción:
make <my_keyboard>:<my_keymap>:avrdude
Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un Lets Split rev2, usarás este comando:
make lets_split/rev2:xyverz:avrdude
Una vez que finalice de compilar, deberá aparecer lo siguiente:
```
Linking: .build/lets_split_rev2_xyverz.elf [OK]
Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK]
Checking file size of lets_split_rev2_xyverz.hex [OK]
* File size is fine - 27938/28672
Detecting USB port, reset your controller now..............
```
En este punto, reinicia la placa y entonces el script detectará el bootloader y procederá a flashear la placa. La información de salida deber ser algo similar a esto:
```
Detected controller on USB port at /dev/ttyS15
Connecting to programmer: .
Found programmer: Id = "CATERIN"; type = S
Software Version = 1.0; No Hardware Version given.
Programmer supports auto addr increment.
Programmer supports buffered memory access with buffersize=128 bytes.
Programmer supports the following devices:
Device code: 0x44
avrdude.exe: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude.exe: erasing chip
avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
avrdude.exe: writing flash (27938 bytes):
Writing | ################################################## | 100% 2.40s
avrdude.exe: 27938 bytes of flash written
avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
avrdude.exe: reading on-chip flash data:
Reading | ################################################## | 100% 0.43s
avrdude.exe: verifying ...
avrdude.exe: 27938 bytes of flash verified
avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
avrdude.exe done. Thank you.
```
Si tienes problemas con esto, puede ser necesario que hagas esto:
sudo make <my_keyboard>:<my_keymap>:avrdude
Adicionalmente, si quisieras flashear múltiples placas, usa el siguiente comando:
make <keyboard>:<keymap>:avrdude-loop
Cuando hayas acabado de flashear placas, necesitarás pulsar Ctrl + C o cualquier combinación que esté definida en tu sistema operativo para finalizar el bucle.
### HalfKay
Para dispositivos PJRC (Teensy's), cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el siguiente comando de construcción:
make <my_keyboard>:<my_keymap>:teensy
Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un Ergodox o un Ergodox EZ, usarás este comando:
make ergodox_ez:xyverz:teensy
Una vez que el firmware acabe de compilar, deberá mostrar una información de salida como esta:
```
Linking: .build/ergodox_ez_xyverz.elf [OK]
Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK]
Checking file size of ergodox_ez_xyverz.hex [OK]
* File size is fine - 25584/32256
Teensy Loader, Command Line, Version 2.1
Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
Waiting for Teensy device...
(hint: press the reset button)
```
En este punto, reinicia tu placa. Una vez que lo hayas hecho, deberás ver una información de salida como esta:
```
Found HalfKay Bootloader
Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
Programming............................................................................................................................................................................
...................................................
Booting
```
### BootloadHID
Para placas basadas en Bootmapper Client(BMC)/bootloadHID/ATmega32A, cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el comando de construcción:
make <my_keyboard>:<my_keymap>:bootloaderHID
Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un jj40, usarás esté comando:
make jj40:xyverz:bootloaderHID
Una vez que el firmware acaba de compilar, mostrará una información de salida como esta:
```
Linking: .build/jj40_default.elf [OK]
Creating load file for flashing: .build/jj40_default.hex [OK]
Copying jj40_default.hex to qmk_firmware folder [OK]
Checking file size of jj40_default.hex [OK]
* The firmware size is fine - 21920/28672 (6752 bytes free)
```
Después de llegar a este punto, el script de construcción buscará el bootloader DFU cada 5 segundos. Repetirá lo siguiente hasta que se encuentre el dispositivo o hasta que lo canceles.
```
Error opening HIDBoot device: The specified device was not found
Trying again in 5s.
```
Una vez que lo haga, querrás reinicar el controlador. Debería entonces mostrar una información de salida similar a esta:
```
Page size = 128 (0x80)
Device size = 32768 (0x8000); 30720 bytes remaining
Uploading 22016 (0x5600) bytes starting at 0 (0x0)
0x05580 ... 0x05600
```
### STM32 (ARM)
Para la mayoría de placas ARM (incluyendo la Proton C, Planck Rev 6, y Preonic Rev 3), cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el siguiente comando de construcción:
make <my_keyboard>:<my_keymap>:dfu-util
Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un teclado Planck Revision 6, utilizarás este comando y a continuación reiniciarás el teclado con el bootloader (antes de que acabe de compilar):
make planck/rev6:xyverz:dfu-util
Una vez que el firmware acaba de compilar, mostrará una información de salida similar a esta:
```
Linking: .build/planck_rev6_xyverz.elf [OK]
Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK]
Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK]
Size after:
text data bss dec hex filename
0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex
Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK]
dfu-util 0.9
Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
Invalid DFU suffix signature
A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 011a
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuERROR, status = 10
dfuERROR, clearing status
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 011a
Device returned transfer size 2048
DfuSe interface name: "Internal Flash "
Downloading to address = 0x08000000, size = 41824
Download [=========================] 100% 41824 bytes
Download done.
File downloaded successfully
Transitioning to dfuMANIFEST state
```
#### STM32 Commands
Hay un número de comandos DFU que puedes usar para flashear firmware a un dispositivo DFU:
* `:dfu-util` - El comando por defecto para flashing en dispositivos STM32.
* `:dfu-util-wait` - Esto funciona como el comando por defecto, pero te da (configurable) 10 segundos de tiempo antes de que intente flashear el firmware. Puedes usar `TIME_DELAY=20` desde la líena de comandos para cambiar este tiempo de retardo.
* Eg: `make <keyboard>:<keymap>:dfu-util TIME_DELAY=5`
* `:dfu-util-split-left` - Flashea el firmware normal, igual que la opción por defecto (`:dfu-util`). Sin embargo, también flashea el fichero EEPROM "Lado Izquierdo" para teclados divididos.
* `:dfu-util-split-right` - Flashea el firmware normal, igual que la opción por defecto (`:dfu-util`). Sin embargo, también flashea el fichero EEPROM "Lado Derecho" para teclados divididos.
## ¡Pruébalo!
¡Felicidades! ¡Tu firmware personalizado ha sido programado en tu teclado!
Pruébalo y asegúrate de que todo funciona de la manera que tu quieres. Hemos escrito [Testeando y depurando](newbs_testing_debugging.md) para redondear esta guía de novatos, así que pásate por allí para aprender cómo resolver problemas con tu funcionalidad personalizada.

103
es/newbs_getting_started.md Normal file
View File

@ -0,0 +1,103 @@
# Introducción
El teclado de tu computador tiene un procesador dentro de él, no muy distinto del que está dentro de tu ordenador. Este procesador ejecuta software que es responsable de detectar la pulsación de las teclas y enviar informes sobre el estado del teclado cuando las teclas son pulsadas y liberadas. QMK ocupa el rol de ese software. Cuando construyes un keymap personalizado , estas creando el equivalente de un programa ejecutable en tu teclado.
QMK intenta poner un montón de poder en tus manos haciendo que las cosas fáciles sean fáciles, y las cosas difíciles posibles. No tienes que saber cómo programar para crear keymaps potentes — sólo tienes que seguir un conjunto simple de reglas sintácticas.
# Comenzando
Antes de que puedas construir keymaps, necesitarás instalar algun software y configurar tu entorno de construcción. Esto sólo hay que hacerlo una vez sin importar en cuántos teclados planeas configurar el software.
Si prefieres hacerlo mediante un interfaz gráfico , por favor, considera utilizar el [Configurador QMK](https://config.qmk.fm). En ese caso dirígete a [Construyendo tu primer firmware usando la GUI](newbs_building_firmware_configurator.md).
## Descarga el software
### Editor de texto
Necesitarás un programa con el que puedas editar y guardar archivos de **texto plano**, en windows puedes utilizar Notepad y en tu Linux puedes utilizar gedit. Estos dos programas son editores simples y funcionales. En macOS ten cuidado con la aplicación de edición de texto por defecto TextEdit: no guardará texto plano a menos de que se le seleccione explícitamente _Make Plain Text_ desde el menú _Format_.
También puedes descargar e instalar un editor de texto dedicado como [Sublime Text](https://www.sublimetext.com/) o [VS Code](https://code.visualstudio.com/). Esta es probablemente la mejor manera independientemente de la plataforma, ya que estos programas fueron creados específicamente para editar código.
?> ¿No estás seguro de qué editor de texto utilizar? Laurence Bradford escribió una [estupenda introducción](https://learntocodewith.me/programming/basics/text-editors/) al tema.
### QMK Toolbox
QMK Toolbox is an optional graphical program for Windows and macOS that allows you to both program and debug your custom keyboard. You will likely find it invaluable for easily flashing your keyboard and viewing debug messages that it prints.
[Download the latest release here.](https://github.com/qmk/qmk_toolbox/releases/latest)
* For Windows: `qmk_toolbox.exe` (portable) or `qmk_toolbox_install.exe` (installer)
* For macOS: `QMK.Toolbox.app.zip` (portable) or `QMK.Toolbox.pkg` (installer)
## Configura tu entorno
Hemos intentado hacer QMK lo más fácil de configurar posible. Sólo tienes que preparar tu entorno Linux o Unix, y luego dejar que QMK
instale el resto.
?> Si no has trabajado con la línea de comandos de Linux/Unix con anterioridad, hay algunos conceptos y comandos básicos que deberías aprender. Estos recursos te enseñarán lo suficiente para poder trabajar con QMK:<br>
[Comandos de Linux que debería saber](https://www.guru99.com/must-know-linux-commands.html)<br>
[Algunos comandos básicos de Unix](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
### Windows
Necesitarás instalar MSYS2 y Git.
* Sigue las instrucciones de instalación en la [página de MSYS2](http://www.msys2.org).
* Cierra las terminales abiertas de MSYS2 y abre una nueva termial de MSYS2 MinGW 64-bit.
* Instala Git ejecutando este comando: `pacman -S git`.
### macOS
Necesitarás instalar Homebrew. Sigue las instrucciones que encontrarás en la [página de Homebrew](https://brew.sh).
Despueś de que se haya inastalado Homebrew, continúa con _Set Up QMK_. En ese paso ejecutará un script que instalará el resto de paquetes.
### Linux
Necesitarás instalar Git. Es bastante probable que ya lo tengas, pero si no, uno de los siguientes comandos debería instalarlo:
* Debian / Ubuntu / Devuan: `apt-get install git`
* Fedora / Red Hat / CentOS: `yum install git`
* Arch: `pacman -S git`
?> Docker es también una opción en todas las plataformas. [Haz click aquí si quieres detalles.](getting_started_build_tools.md#docker)
## Configura QMK
Una vez que hayas configurado tu entorno Linux/Unix, estarás listo para descargar QMK. Haremos esto utilizando Git para "clonar" el respositorio de QMK. Abre una ventana de Terminal o MSYS2 MinGW y mantenla abierta mientras sigues esta guía. Dentro de esa ventana ejecuta estos dos comandos:
```shell
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
```
?> Si ya sabes [cómo usar GitHub](getting_started_github.md), te recomendamos en vez de eso, crees y clones tu propio fork. Si no sabes lo que significa, puedes ignorar este mensaje sin problemas.
QMK viene con un script para ayudarte a configurar el resto de cosas que necesitarás. Deberías ejecutarlo introduciendo este comando:
util/qmk_install.sh
## Prueba tu entorno de construcción
Ahora que tu entorno de construcción de QMK está configurado, puedes construcir un firmware para tu teclado. Comienza intentado construir el keymap por defecto del teclado. Deberías ser capaz de hacerlo con un comando con este formato:
make <keyboard>:default
Por ejemplo, para construir el firmware para un Clueboard 66% deberías usar:
make clueboard/66/rev3:default
Cuando esté hecho, deberías tener un montón de información de salida similar a esta:
```
Linking: .build/clueboard_66_rev3_default.elf [OK]
Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK]
Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK]
Checking file size of clueboard_66_rev3_default.hex [OK]
* The firmware size is fine - 26356/28672 (2316 bytes free)
```
# Creando tu keymap
Ya estás listo para crear tu propio keymap personal! Para hacerlo continua con [Construyendo tu primer firmware](newbs_building_firmware.md).

15
es/newbs_learn_more_resources.md Normal file
View File

@ -0,0 +1,15 @@
# Recursos de aprendizaje
Estos recursos procuran dar miembros nuevos en la communidad QMK un mayor entendimiento de la información proporcionada en la documentación para novatos.
Recursos de Git:
* [Excelente tutorial general](https://www.codecademy.com/learn/learn-git)
* [Juego de Git para aprender usando ejemplos](https://learngitbranching.js.org/)
* [Recursos de Git para aprender más sobre GitHub](getting_started_github.md)
* [Recursos de Git dirigidos específicamente a QMK](contributing.md)
Recursos para línea de mandatos:
* [Excelente tutorial general sobre la línea de mandatos](https://www.codecademy.com/learn/learn-the-command-line)

99
es/newbs_testing_debugging.md Normal file
View File

@ -0,0 +1,99 @@
# Testeando y depurando
Una vez que hayas flasheado tu teclado con un firmware personalizado estarás listo para probarlo. Con un poco de suerte todo funcionará a la primera, pero si no es así, este documento te ayudará a averiguar qué está mal.
## Probando
Probar tu teclado es generalmente bastante sencillo. Persiona cada una de las teclas y asegúrate de que envía la tecla correcta. Existen incluso programas que te ayudarán a asegurarte de que no te dejas ninguna tecla sin comprobar.
Nota: Estos programas no los provée ni están relacionados con QMK.
* [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (Sólo Windows)
* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Sólo Mac)
* [Keyboard Tester](http://www.keyboardtester.com) (Aplicación web)
* [Keyboard Checker](http://keyboardchecker.com) (Aplicación web)
## Depurando
Tu teclado mostrará información de depuración si tienes `CONSOLE_ENABLE = yes` en tu `rules.mk`. Por defecto la información de salida es muy limitada, pero puedes encender el modo de depuración para incrementar la información de salida. Utiliza el keycode `DEBUG` de tu keymap, usa la característica [Comando](feature_command.md) para activar el modo depuración, o añade el siguiente código a tu keymap.
```c
void keyboard_post_init_user(void) {
// Customise these values to desired behaviour
debug_enable=true;
debug_matrix=true;
//debug_keyboard=true;
//debug_mouse=true;
}
```
### Depurando con QMK Toolbox
Para plataformas compatibles, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) se puede usar para mostrar mensajes de depuración de tu teclado.
### Depurando con hid_listen
¿Prefieres una solución basada en una terminal? [hid_listen](https://www.pjrc.com/teensy/hid_listen.html), provista por PJRC, se puede usar también para mostrar mensajes de depuración. Hay binarios preconstruídos para Windows,Linux,y MacOS.
<!-- FIXME: Describe the debugging messages here. -->
## Enviando tus propios mensajes de depuración
A veces, es útil imprimir mensajes de depuración desde tu [código personalizado](custom_quantum_functions.md). Hacerlo es bastante simple. Comienza incluyendo `print.h` al principio de tu fichero:
#include <print.h>
Después de eso puedes utilzar algunas funciones print diferentes:
* `print("string")`: Imprime un string simple
* `uprintf("%s string", var)`: Imprime un string formateado
* `dprint("string")` Imprime un string simple, pero sólo cuando el modo de depuración está activo
* `dprintf("%s string", var)`: Imprime un string formateado, pero sólo cuando el modo de depuración está activo
## Ejemplos de depuración
Debajo hay una colección de ejemplos de depuración del mundo real. Para información adicional, Dirígete a [Depurando/Encontrando problemas en QMK](faq_debug.md).
### ¿Que posición en la matriz tiene esta pulsación de tecla?
Cuando estés portando, o intentando diagnosticar problemas en la pcb, puede ser útil saber si la pulsación de una tecla es escaneada correctamente. Para hablitar la información de registro en este escenario, añade el siguiente código al `keymap.c` de tus keymaps
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
// If console is enabled, it will print the matrix position and status of each key pressed
#ifdef CONSOLE_ENABLE
uprintf("KL: kc: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed);
#endif
return true;
}
```
Ejemplo de salida
```text
Waiting for device:.......
Listening:
KL: kc: 169, col: 0, row: 0, pressed: 1
KL: kc: 169, col: 0, row: 0, pressed: 0
KL: kc: 174, col: 1, row: 0, pressed: 1
KL: kc: 174, col: 1, row: 0, pressed: 0
KL: kc: 172, col: 2, row: 0, pressed: 1
KL: kc: 172, col: 2, row: 0, pressed: 0
```
### ¿Cuanto tiempo tardó en escanear la pulsación de una tecla?
Cuando estés probando problemas en el rendimiento, puede ser útil saber la frecuenta a la cual la matríz de pulsadores se está escaneando. Para hablitar la información de registro en este escenario, añade el siguiente código al `config.h` de tus keymaps
```c
#define DEBUG_MATRIX_SCAN_RATE
```
Ejemplo de salida
```text
> matrix scan frequency: 315
> matrix scan frequency: 313
> matrix scan frequency: 316
> matrix scan frequency: 316
> matrix scan frequency: 316
> matrix scan frequency: 316
```

69
faq_build.md Normal file
View File

@ -0,0 +1,69 @@
# Frequently Asked Build Questions
This page covers questions about building QMK. If you haven't yet done so, you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides.
## Can't Program on Linux
You will need proper permissions to operate a device. For Linux users, see the instructions regarding `udev` rules, below. If you have issues with `udev`, a work-around is to use the `sudo` command. If you are not familiar with this command, check its manual with `man sudo` or [see this webpage](https://linux.die.net/man/8/sudo).
An example of using `sudo`, when your controller is ATMega32u4:
$ sudo dfu-programmer atmega32u4 erase --force
$ sudo dfu-programmer atmega32u4 flash your.hex
$ sudo dfu-programmer atmega32u4 reset
or just:
$ sudo make <keyboard>:<keymap>:flash
Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible.
### Linux `udev` Rules
On Linux, you'll need proper privileges to communicate with the bootloader device. You can either use `sudo` when flashing firmware (not recommended), or place [this file](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules) into `/etc/udev/rules.d/`.
Once added, run the following:
```
sudo udevadm control --reload-rules
sudo udevadm trigger
```
**Note:** With older versions of ModemManager (< 1.12), filtering only works when not in strict mode. The following commands can update that setting:
```
printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf
sudo systemctl daemon-reload
sudo systemctl restart ModemManager
```
### Serial device is not detected in bootloader mode on Linux
Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as
Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options.
## Unknown Device for DFU Bootloader
Issues encountered when flashing keyboards on Windows are most often due to having the wrong drivers installed for the bootloader, or none at all.
Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_firmware` directory in MSYS2 or WSL) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package manually.
If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig.md) for more detailed information.
## USB VID and PID
You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product.
Most boards in QMK use `0xFEED` as the vendor ID. You should look through other keyboards to make sure you pick a unique Product ID.
Also see this.
https://github.com/tmk/tmk_keyboard/issues/150
You can buy a really unique VID:PID here. I don't think you need this for personal use.
- http://www.obdev.at/products/vusb/license.html
- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
### I just flashed my keyboard and it does nothing/keypresses don't register - it's also ARM (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019)
Due to how EEPROM works on ARM based chips, saved settings may no longer be valid. This affects the default layers, and *may*, under certain circumstances we are still figuring out, make the keyboard unusable. Resetting the EEPROM will correct this.
[Planck rev6 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) can be used to force an eeprom reset. After flashing this image, flash your normal firmware again which should restore your keyboard to _normal_ working order.
[Preonic rev3 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin)
If bootmagic is enabled in any form, you should be able to do this too (see [Bootmagic docs](feature_bootmagic.md) and keyboard info for specifics on how to do this).

148
faq_debug.md Normal file
View File

@ -0,0 +1,148 @@
# Debugging FAQ
This page details various common questions people have about troubleshooting their keyboards.
# Debug Console
## `hid_listen` Can't Recognize Device
When debug console of your device is not ready you will see like this:
```
Waiting for device:.........
```
once the device is plugged in then *hid_listen* finds it you will get this message:
```
Waiting for new device:.........................
Listening:
```
If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes` in [Makefile]
You may need privilege to access the device on OS like Linux.
- try `sudo hid_listen`
## Can't Get Message on Console
Check:
- *hid_listen* finds your device. See above.
- Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
- set `debug_enable=true`. See [Testing and Debugging](newbs_testing_debugging.md#debugging)
- try using 'print' function instead of debug print. See **common/print.h**.
- disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
***
# Miscellaneous
## Safety Considerations
You probably don't want to "brick" your keyboard, making it impossible
to rewrite firmware onto it. Here are some of the parameters to show
what things are (and likely aren't) too risky.
- If your keyboard map does not include RESET, then, to get into DFU
mode, you will need to press the reset button on the PCB, which
requires unscrewing the bottom.
- Messing with tmk_core / common files might make the keyboard
inoperable
- Too large a .hex file is trouble; `make dfu` will erase the block,
test the size (oops, wrong order!), which errors out, failing to
flash the keyboard, leaving it in DFU mode.
- To this end, note that the maximum .hex file size on Planck is
7000h (28672 decimal)
```
Linking: .build/planck_rev4_cbbrowne.elf [OK]
Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
Size after:
text data bss dec hex filename
0 22396 0 22396 577c planck_rev4_cbbrowne.hex
```
- The above file is of size 22396/577ch, which is less than
28672/7000h
- As long as you have a suitable alternative .hex file around, you
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
- DFU tools do /not/ allow you to write into the bootloader (unless
you throw in extra fruit salad of options), so there is little risk
there.
- EEPROM has around a 100000 write cycle. You shouldn't rewrite the
firmware repeatedly and continually; that'll burn the EEPROM
eventually.
## NKRO Doesn't work
First you have to compile firmware with this build option `NKRO_ENABLE` in **Makefile**.
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 you need to switch to **6KRO** mode, in particular when you are in BIOS.
If your firmware 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 initialize of the hardware. See circuit schematic of TPM754.
- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
## Can't Read Column of Matrix Beyond 16
Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
In C `1` means one of [int] type which is [16 bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say `1<<16`. You have to use [unsigned long] type with `1UL`.
http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
## Special Extra Key Doesn't Work (System, Audio Control Keys)
You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
```
EXTRAKEY_ENABLE = yes # Audio control and System control
```
## Wakeup from Sleep Doesn't Work
In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.
Pressing any key during sleep should wake host.
## Using Arduino?
**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
## Enabling JTAG
By default, the JTAG debugging interface is disabled as soon as the keyboard starts up. JTAG-capable MCUs come from the factory with the `JTAGEN` fuse set, and it takes over certain pins of the MCU that the board may be using for the switch matrix, LEDs, etc.
If you would like to keep JTAG enabled, just add the following to your `config.h`:
```c
#define NO_JTAG_DISABLE
```
## USB 3 Compatibility
I heard some people have a problem with USB 3 port, try USB 2 port.
## Mac Compatibility
### OS X 10.11 and Hub
https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
## Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles
Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).
As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
https://github.com/tmk/tmk_keyboard/issues/266
https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778

53
faq_general.md Normal file
View File

@ -0,0 +1,53 @@
# Frequently Asked Questions
## What is QMK?
[QMK](https://github.com/qmk), short for Quantum Mechanical Keyboard, is a group of people building tools for custom keyboards. We started with the [QMK firmware](https://github.com/qmk/qmk_firmware), a heavily modified fork of [TMK](https://github.com/tmk/tmk_keyboard).
## I don't know where to start!
If this is the case, then you should start with our [Newbs Guide](newbs.md). There is a lot of great info there, and that should cover everything you need to get started.
If that's an issue, hop onto the [QMK Configurator](https://config.qmk.fm), as that will handle a majority of what you need there.
## How can I flash the firmware I built?
First, head to the [Compiling/Flashing FAQ Page](faq_build.md). There is a good deal of info there, and you'll find a bunch of solutions to common issues there.
## What if I have an issue that isn't covered here?
Okay, that's fine. Then please check the [open issues in our GitHub](https://github.com/qmk/qmk_firmware/issues) to see if somebody is experiencing the same thing (make sure it's not just similar, but actually the same).
If you can't find anything, then please open a [new issue](https://github.com/qmk/qmk_firmware/issues/new)!
## What if I found a bug?
Then please open an [issue](https://github.com/qmk/qmk_firmware/issues/new), and if you know how to fix it, open up a Pull Request on GitHub with the fix.
## But `git` and `GitHub` are intimidating!
Don't worry, we have some pretty nice [Guidelines](newbs_git_best_practices.md) on how to start using `git` and GitHub to make things easier to develop.
Additionally, you can find additional `git` and GitHub related links [here](newbs_learn_more_resources.md).
## I have a Keyboard that I want to add support for
Awesome! Open up a Pull Request for it. We'll review the code, and merge it!
### What if I want to do brand it with `QMK`?
That's amazing! We would love to assist you with that!
In fact, we have a [whole page](https://qmk.fm/powered/) dedicated to adding QMK Branding to your page and keyboard. This covers pretty much everything you need (knowledge and images) to officially support QMK.
If you have any questions about this, open an issue or head to [Discord](https://discord.gg/Uq7gcHh).
## What Differences Are There Between QMK and TMK?
TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert](https://github.com/jackhumbert)'s fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.
From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md).
From a project and community management standpoint TMK maintains all the officially supported keyboards by himself, with a bit of community support. Separate community maintained forks exist or can be created for other keyboards. Only a few keymaps are provided by default, so users typically don't share keymaps with each other. QMK encourages sharing of both keyboards and keymaps through a centrally managed repository, accepting all pull requests that follow the quality standards. These are mostly community maintained, but the QMK team also helps when necessary.
Both approaches have their merits and their drawbacks, and code flows freely between TMK and QMK when it makes sense.

156
faq_keymap.md Normal file
View File

@ -0,0 +1,156 @@
# Keymap FAQ
This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
## What Keycodes Can I Use?
See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available.
Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
## What Are the Default Keycodes?
There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
## How Can I Make Custom Names For Complex Keycodes?
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 ALT_TAB LALT(KC_TAB)
```
This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable.
## Some Of My Keys Are Swapped Or Not Working
QMK has two features, Bootmagic and Command, which allow you to change the behavior of your keyboard on the fly. This includes, but is not limited to, swapping Ctrl/Caps, disabling Gui, swapping Alt/Gui, swapping Backspace/Backslash, disabling all keys, and other behavioral modifications.
As a quick fix try holding down `Space`+`Backspace` while you plug in your keyboard. This will reset the stored settings on your keyboard, returning those keys to normal operation. If that doesn't work look here:
* [Bootmagic](feature_bootmagic.md)
* [Command](feature_command.md)
## The Menu Key Isn't Working
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'.
See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
* http://en.wikipedia.org/wiki/Magic_SysRq_key
* http://en.wikipedia.org/wiki/System_request
## 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.
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.
## One Shot Modifier
Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'. One Shot Shift mitigates this for me.
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.
* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
* https://github.com/tmk/tmk_keyboard/issues/248
## Mechanical Lock Switch Support
This feature is for *mechanical lock switch* like [this Alps one](http://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
```
#define LOCKING_SUPPORT_ENABLE
#define LOCKING_RESYNC_ENABLE
```
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`.***
## Input Special Characters Other Than ASCII like Cédille 'Ç'
See the [Unicode](feature_unicode.md) feature.
## `Fn` Key on macOS
Unlike most Fn keys, the one on Apple keyboards actually has its own keycode... sort of. It takes the place of the sixth keycode in a basic 6KRO HID report -- so an Apple keyboard is in fact only 5KRO.
It is technically possible to get QMK to send this key. However, doing so requires modification of the report format to add the state of the Fn key.
Even worse, it is not recognized unless the keyboard's VID and PID match that of a real Apple keyboard. The legal issues that official QMK support for this feature may create mean it is unlikely to happen.
See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
## Keys Supported in Mac OSX?
You can know which keycodes are supported in OSX from this source code.
`usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
## JIS Keys in Mac OSX
Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` are not recognized on OSX. You can use **Seil** to enable those keys, try following options.
* Enable NFER Key on PC keyboard
* Enable XFER Key on PC keyboard
* Enable KATAKANA Key on PC keyboard
https://pqrs.org/osx/karabiner/seil.html
## RN-42 Bluetooth Doesn't Work with Karabiner
Karabiner - Keymapping tool on Mac OSX - ignores inputs from RN-42 module by default. You have to enable this option to make Karabiner working with your keyboard.
https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
See these for the detail of this problem.
https://github.com/tmk/tmk_keyboard/issues/213
https://github.com/tekezo/Karabiner/issues/403
## Esc and <code>&#96;</code> on a Single Key
See the [Grave Escape](feature_grave_esc.md) feature.
## Eject on Mac OSX
`KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
Not sure what keycode Eject is on genuine Apple keyboard actually. HHKB uses `F20` for Eject key(`Fn+f`) on Mac mode but this is not same as Apple Eject keycode probably.
## What's `weak_mods` and `real_mods` in `action_util.c`
___TO BE IMPROVED___
real_mods is intended to retains state of real/physical modifier key state, while
weak_mods retains state of virtual or temporary modifiers which should not affect state real modifier key.
Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
with weak_mods,
* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
real_mods still keeps modifier state.
without weak mods,
* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
here real_mods lost state for 'physical left shift'.
weak_mods is ORed with real_mods when keyboard report is sent.
https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57

44
feature_advanced_keycodes.md Normal file
View File

@ -0,0 +1,44 @@
# Modifier Keys :id=modifier-keys
These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
|Key |Aliases |Description |
|----------|-------------------------------|------------------------------------------------------|
|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` |
|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` |
|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` |
|`RCTL(kc)`| |Hold Right Control and press `kc` |
|`RSFT(kc)`| |Hold Right Shift and press `kc` |
|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` |
|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)` |Hold Right GUI and press `kc` |
|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)` |Hold Left Shift and GUI and press `kc` |
|`LCA(kc)` | |Hold Left Control and Alt and press `kc` |
|`LSA(kc)` | |Hold Left Shift and Left Alt and press `kc` |
|`RSA(kc)` |`SAGR(kc)` |Hold Right Shift and Right Alt (AltGr) and press `kc` |
|`RCS(kc)` | |Hold Right Control and Right Shift and press `kc` |
|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` |
|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` |
|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc` |
You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
# Legacy Content :id=legacy-content
This page used to encompass a large set of features. We have moved many sections that used to be part of this page to their own pages. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for.
## Layers :id=switching-and-toggling-layers
* [Layers](feature_layers.md)
## Mod-Tap :id=mod-tap
* [Mod-Tap](mod_tap.md)
## One Shot Keys :id=one-shot-keys
* [One Shot Keys](one_shot_keys.md)
## Tap-Hold Configuration Options :id=tap-hold-configuration-options
* [Tap-Hold Configuration Options](tap_hold.md)

323
feature_audio.md Normal file
View File

@ -0,0 +1,323 @@
# Audio
Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to certain PWM-capable pins, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
Up to two simultaneous audio voices are supported, one driven by timer 1 and another driven by timer 3. The following pins can be defined as audio outputs in config.h:
Timer 1:
`#define B5_AUDIO`
`#define B6_AUDIO`
`#define B7_AUDIO`
Timer 3:
`#define C4_AUDIO`
`#define C5_AUDIO`
`#define C6_AUDIO`
If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration:
```
STARTUP_SONG // plays when the keyboard starts up (audio.c)
GOODBYE_SONG // plays when you press the RESET key (quantum.c)
AG_NORM_SONG // plays when you press AG_NORM (quantum.c)
AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)
CG_NORM_SONG // plays when you press CG_NORM (quantum.c)
CG_SWAP_SONG // plays when you press CG_SWAP (quantum.c)
MUSIC_ON_SONG // plays when music mode is activated (process_music.c)
MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)
CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c)
GUITAR_SONG // plays when the guitar music mode is selected (process_music.c)
VIOLIN_SONG // plays when the violin music mode is selected (process_music.c)
MAJOR_SONG // plays when the major music mode is selected (process_music.c)
```
You can override the default songs by doing something like this in your `config.h`:
```c
#ifdef AUDIO_ENABLE
#define STARTUP_SONG SONG(STARTUP_SOUND)
#endif
```
A full list of sounds can be found in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) - feel free to add your own to this list! All available notes can be seen in [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h).
To play a custom sound at a particular time, you can define a song like this (near the top of the file):
```c
float my_song[][2] = SONG(QWERTY_SOUND);
```
And then play your song like this:
```c
PLAY_SONG(my_song);
```
Alternatively, you can play it in a loop like this:
```c
PLAY_LOOP(my_song);
```
It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard.
The available keycodes for audio are:
* `AU_ON` - Turn Audio Feature on
* `AU_OFF` - Turn Audio Feature off
* `AU_TOG` - Toggle Audio Feature state
!> These keycodes turn all of the audio functionality on and off. Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely.
## ARM Audio Volume
For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `DAC_SAMPLE_MAX` in your `config.h`:
```c
#define DAC_SAMPLE_MAX 65535U
```
## Music Mode
The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode.
Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.
Keycodes available:
* `MU_ON` - Turn music mode on
* `MU_OFF` - Turn music mode off
* `MU_TOG` - Toggle music mode
* `MU_MOD` - Cycle through the music modes:
* `CHROMATIC_MODE` - Chromatic scale, row changes the octave
* `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st)
* `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st)
* `MAJOR_MODE` - Major scale
In music mode, the following keycodes work differently, and don't pass through:
* `LCTL` - start a recording
* `LALT` - stop recording/stop playing
* `LGUI` - play recording
* `KC_UP` - speed-up playback
* `KC_DOWN` - slow-down playback
The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
#define PITCH_STANDARD_A 432.0f
You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller. To disable it, add this to your `config.h`:
#define NO_MUSIC_MODE
### Music Mask
By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this:
#define MUSIC_MASK keycode != KC_NO
Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
For a more advanced way to control which keycodes should still be processed, you can use `music_mask_kb(keycode)` in `<keyboard>.c` and `music_mask_user(keycode)` in your `keymap.c`:
bool music_mask_user(uint16_t keycode) {
switch (keycode) {
case RAISE:
case LOWER:
return false;
default:
return true;
}
}
Things that return false are not part of the mask, and are always processed.
### Music Map
By default, the Music Mode uses the columns and row to determine the scale for the keys. For a board that uses a rectangular matrix that matches the keyboard layout, this is just fine. However, for boards that use a more complicated matrix (such as the Planck Rev6, or many split keyboards) this would result in a very skewed experience.
However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural.
To enable this feature, add `#define MUSIC_MAP` to your `config.h` file, and then you will want to add a `uint8_t music_map` to your keyboard's `c` file, or your `keymap.c`.
```c
const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12(
36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47,
24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35,
12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
);
```
You will want to use whichever `LAYOUT` macro that your keyboard uses here. This maps it to the correct key location. Start in the bottom left of the keyboard layout, and move to the right, and then upwards. Fill in all the entries until you have a complete matrix.
You can look at the [Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) as an example of how to implement this.
## Audio Click
This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly.
* `CK_TOGG` - Toggles the status (will play sound if enabled)
* `CK_ON` - Turns on Audio Click (plays sound)
* `CK_OFF` - Turns off Audio Click (doesn't play sound)
* `CK_RST` - Resets the frequency to the default state (plays sound at default frequency)
* `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency)
* `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency)
The feature is disabled by default, to save space. To enable it, add this to your `config.h`:
#define AUDIO_CLICKY
You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values:
| Option | Default Value | Description |
|--------|---------------|-------------|
| `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. |
| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. This is a multiplicative factor. The default steps the frequency up/down by a musical minor third. |
| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. |
| `AUDIO_CLICKY_DELAY_DURATION` | 1 | An integer note duration where 1 is 1/16th of the tempo, or a sixty-fourth note (see `quantum/audio/musical_notes.h` for implementation details). The main clicky effect will be delayed by this duration. Adjusting this to values around 6-12 will help compensate for loud switches. |
## MIDI Functionality
This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile.
## Audio Keycodes
|Key |Aliases |Description |
|----------------|---------|----------------------------------|
|`AU_ON` | |Audio mode on |
|`AU_OFF` | |Audio mode off |
|`AU_TOG` | |Toggles Audio mode |
|`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode |
|`CLICKY_UP` |`CK_UP` |Increases frequency of the clicks |
|`CLICKY_DOWN` |`CK_DOWN`|Decreases frequency of the clicks |
|`CLICKY_RESET` |`CK_RST` |Resets frequency to default |
|`MU_ON` | |Turns on Music Mode |
|`MU_OFF` | |Turns off Music Mode |
|`MU_TOG` | |Toggles Music Mode |
|`MU_MOD` | |Cycles through the music modes |
<!-- FIXME: this formatting needs work
## Audio
```c
#ifdef AUDIO_ENABLE
AU_ON,
AU_OFF,
AU_TOG,
#ifdef FAUXCLICKY_ENABLE
FC_ON,
FC_OFF,
FC_TOG,
#endif
// Music mode on/off/toggle
MU_ON,
MU_OFF,
MU_TOG,
// Music voice iterate
MUV_IN,
MUV_DE,
#endif
```
### Midi
#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
MI_ON, // send midi notes when music mode is enabled
MI_OFF, // don't send midi notes when music mode is enabled
#endif
MIDI_TONE_MIN,
MIDI_TONE_MAX
MI_C = MIDI_TONE_MIN,
MI_Cs,
MI_Db = MI_Cs,
MI_D,
MI_Ds,
MI_Eb = MI_Ds,
MI_E,
MI_F,
MI_Fs,
MI_Gb = MI_Fs,
MI_G,
MI_Gs,
MI_Ab = MI_Gs,
MI_A,
MI_As,
MI_Bb = MI_As,
MI_B,
MIDI_TONE_KEYCODE_OCTAVES > 1
where x = 1-5:
MI_C_x,
MI_Cs_x,
MI_Db_x = MI_Cs_x,
MI_D_x,
MI_Ds_x,
MI_Eb_x = MI_Ds_x,
MI_E_x,
MI_F_x,
MI_Fs_x,
MI_Gb_x = MI_Fs_x,
MI_G_x,
MI_Gs_x,
MI_Ab_x = MI_Gs_x,
MI_A_x,
MI_As_x,
MI_Bb_x = MI_As_x,
MI_B_x,
MI_OCT_Nx 1-2
MI_OCT_x 0-7
MIDI_OCTAVE_MIN = MI_OCT_N2,
MIDI_OCTAVE_MAX = MI_OCT_7,
MI_OCTD, // octave down
MI_OCTU, // octave up
MI_TRNS_Nx 1-6
MI_TRNS_x 0-6
MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
MIDI_TRANSPOSE_MAX = MI_TRNS_6,
MI_TRNSD, // transpose down
MI_TRNSU, // transpose up
MI_VEL_x 1-10
MIDI_VELOCITY_MIN = MI_VEL_1,
MIDI_VELOCITY_MAX = MI_VEL_9,
MI_VELD, // velocity down
MI_VELU, // velocity up
MI_CHx 1-16
MIDI_CHANNEL_MIN = MI_CH1
MIDI_CHANNEL_MAX = MI_CH16,
MI_CHD, // previous channel
MI_CHU, // next channel
MI_ALLOFF, // all notes off
MI_SUS, // sustain
MI_PORT, // portamento
MI_SOST, // sostenuto
MI_SOFT, // soft pedal
MI_LEG, // legato
MI_MOD, // modulation
MI_MODSD, // decrease modulation speed
MI_MODSU, // increase modulation speed
#endif // MIDI_ADVANCED
-->

167
feature_auto_shift.md Normal file
View File

@ -0,0 +1,167 @@
# Auto Shift: Why Do We Need a Shift Key?
Tap a key and you get its character. Tap a key, but hold it *slightly* longer
and you get its shifted state. Voilà! No shift key needed!
## Why Auto Shift?
Many people suffer from various forms of RSI. A common cause is stretching your
fingers repetitively long distances. For us on the keyboard, the pinky does that
all too often when reaching for the shift key. Auto Shift looks to alleviate that
problem.
## How Does It Work?
When you tap a key, it stays depressed for a short period of time before it is
then released. This depressed time is a different length for everyone. Auto Shift
defines a constant `AUTO_SHIFT_TIMEOUT` which is typically set to twice your
normal pressed state time. When you press a key, a timer starts and then stops
when you release the key. If the time depressed is greater than or equal to the
`AUTO_SHIFT_TIMEOUT`, then a shifted version of the key is emitted. If the time
is less than the `AUTO_SHIFT_TIMEOUT` time, then the normal state is emitted.
## Are There Limitations to Auto Shift?
Yes, unfortunately.
1. Key repeat will cease to work. For example, before if you wanted 20 'a'
characters, you could press and hold the 'a' key for a second or two. This no
longer works with Auto Shift because it is timing your depressed time instead
of emitting a depressed key state to your operating system.
2. 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.
## How Do I Enable Auto Shift?
Add to your `rules.mk` in the keymap folder:
AUTO_SHIFT_ENABLE = yes
If no `rules.mk` exists, you can create one.
Then compile and install your new firmware with Auto Key enabled! That's it!
## Modifiers
By default, Auto Shift is disabled for any key press that is accompanied by one or more
modifiers. Thus, Ctrl+A that you hold for a really long time is not the same
as Ctrl+Shift+A.
You can re-enable Auto Shift for modifiers by adding a define to your `config.h`
```c
#define AUTO_SHIFT_MODIFIERS
```
In which case, Ctrl+A held past the `AUTO_SHIFT_TIMEOUT` will be sent as Ctrl+Shift+A
## Configuring Auto Shift
If desired, there is some configuration that can be done to change the
behavior of Auto Shift. This is done by setting various variables the
`config.h` file located in your keymap folder. If no `config.h` file exists, you can create one.
A sample is
```c
#pragma once
#define AUTO_SHIFT_TIMEOUT 150
#define NO_AUTO_SHIFT_SPECIAL
```
### AUTO_SHIFT_TIMEOUT (Value in ms)
This controls how long you have to hold a key before you get the shifted state.
Obviously, this is different for everyone. For the common person, a setting of
135 to 150 works great. However, one should start with a value of at least 175, which
is the default value. Then work down from there. The idea is to have the shortest time required to get the shifted state without having false positives.
Play with this value until things are perfect. Many find that all will work well
at a given value, but one or two keys will still emit the shifted state on
occasion. This is simply due to habit and holding some keys a little longer
than others. Once you find this value, work on tapping your problem keys a little
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!
### NO_AUTO_SHIFT_SPECIAL (simple define)
Do not Auto Shift special keys, which include -\_, =+, [{, ]}, ;:, '", ,<, .>,
and /?
### NO_AUTO_SHIFT_NUMERIC (simple define)
Do not Auto Shift numeric keys, zero through nine.
### NO_AUTO_SHIFT_ALPHA (simple define)
Do not Auto Shift alpha characters, which include A through Z.
## Using Auto Shift Setup
This will enable you to define three keys temporarily to increase, decrease and report your `AUTO_SHIFT_TIMEOUT`.
### Setup
Map three keys temporarily in your keymap:
| Key Name | Description |
|----------|-----------------------------------------------------|
| KC_ASDN | Lower the Auto Shift timeout variable (down) |
| KC_ASUP | Raise the Auto Shift timeout variable (up) |
| KC_ASRP | Report your current Auto Shift timeout value |
| KC_ASON | Turns on the Auto Shift Function |
| KC_ASOFF | Turns off the Auto Shift Function |
| KC_ASTG | Toggles the state of the Auto Shift feature |
Compile and upload your new firmware.
### Use
It is important to note that during these tests, you should be typing
completely normal and with no intention of shifted keys.
1. Type multiple sentences of alphabetical letters.
2. Observe any upper case letters.
3. If there are none, press the key you have mapped to `KC_ASDN` to decrease
time Auto Shift timeout value and go back to step 1.
4. If there are some upper case letters, decide if you need to work on tapping
those keys with less down time, or if you need to increase the timeout.
5. If you decide to increase the timeout, press the key you have mapped to
`KC_ASUP` and go back to step 1.
6. Once you are happy with your results, press the key you have mapped to
`KC_ASRP`. The keyboard will type by itself the value of your
`AUTO_SHIFT_TIMEOUT`.
7. Update `AUTO_SHIFT_TIMEOUT` in your `config.h` with the value reported.
8. Add `AUTO_SHIFT_NO_SETUP` to your `config.h`.
9. Remove the key bindings `KC_ASDN`, `KC_ASUP` and `KC_ASRP`.
10. Compile and upload your new firmware.
#### An Example Run
hello world. my name is john doe. i am a computer programmer playing with
keyboards right now.
[PRESS KC_ASDN quite a few times]
heLLo woRLd. mY nAMe is JOHn dOE. i AM A compUTeR proGRaMMER PlAYiNG witH
KEYboArDS RiGHT NOw.
[PRESS KC_ASUP a few times]
hello world. my name is john Doe. i am a computer programmer playing with
keyboarDs right now.
[PRESS KC_ASRP]
115
The keyboard typed `115` which represents your current `AUTO_SHIFT_TIMEOUT`
value. You are now set! Practice on the *D* key a little bit that showed up
in the testing and you'll be golden.

217
feature_backlight.md Normal file
View File

@ -0,0 +1,217 @@
# Backlighting :id=backlighting
Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously install multiple different single coloured LEDs on a keyboard.
QMK is able to control the brightness of these LEDs by switching them on and off rapidly in a certain ratio, a technique known as *Pulse Width Modulation*, or PWM. By altering the duty cycle of the PWM signal, it creates the illusion of dimming.
The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs.
Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following:
```makefile
BACKLIGHT_ENABLE = yes
```
## Keycodes :id=keycodes
Once enabled, the following keycodes below can be used to change the backlight level.
|Key |Description |
|---------|-----------------------------------|
|`BL_TOGG`|Turn the backlight on or off |
|`BL_STEP`|Cycle through backlight levels |
|`BL_ON` |Set the backlight to max brightness|
|`BL_OFF` |Turn the backlight off |
|`BL_INC` |Increase the backlight level |
|`BL_DEC` |Decrease the backlight level |
|`BL_BRTG`|Toggle backlight breathing |
## Functions :id=functions
These functions can be used to change the backlighting in custom code:
|Function |Description |
|------------------------|--------------------------------------------|
|`backlight_toggle()` |Turn the backlight on or off |
|`backlight_enable()` |Turn the backlight on |
|`backlight_disable()` |Turn the backlight off |
|`backlight_step()` |Cycle through backlight levels |
|`backlight_increase()` |Increase the backlight level |
|`backlight_decrease()` |Decrease the backlight level |
|`backlight_level(x)` |Sets the backlight level to specified level |
|`get_backlight_level()` |Return the current backlight level |
|`is_backlight_enabled()`|Return whether the backlight is currently on|
If backlight breathing is enabled (see below), the following functions are also available:
|Function |Description |
|---------------------|--------------------------------------|
|`breathing_toggle()` |Turn the backlight breathing on or off|
|`breathing_enable()` |Turns on backlight breathing |
|`breathing_disable()`|Turns off backlight breathing |
## Configuration :id=configuration
To select which driver to use, configure your `rules.mk` with the following:
```makefile
BACKLIGHT_DRIVER = software
```
Valid driver values are `pwm`, `software`, `custom` or `no`. See below for help on individual drivers.
To configure the backlighting, `#define` these in your `config.h`:
|Define |Default |Description |
|---------------------|-------------|-------------------------------------------------------------------------------------|
|`BACKLIGHT_PIN` |*Not defined*|The pin that controls the LED(s) |
|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) |
|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) |
|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported |
|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds |
|`BACKLIGHT_ON_STATE` |`1` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low|
Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`.
### Backlight On State :id=backlight-on-state
Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
### AVR Driver :id=avr-driver
The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
```makefile
BACKLIGHT_DRIVER = pwm
```
#### Caveats :id=avr-caveats
On AVR boards, QMK automatically decides which driver to use according to the following table:
|Backlight Pin|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 | |
All other pins will use timer-assisted software PWM:
|Audio Pin|Audio Timer|Software PWM Timer|
|---------|-----------|------------------|
|`C4` |Timer 3 |Timer 1 |
|`C5` |Timer 3 |Timer 1 |
|`C6` |Timer 3 |Timer 1 |
|`B5` |Timer 1 |Timer 3 |
|`B6` |Timer 1 |Timer 3 |
|`B7` |Timer 1 |Timer 3 |
When both timers are in use for Audio, the backlight PWM cannot use a hardware timer, and will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision.
#### Hardware PWM Implementation :id=hardware-pwm-implementation
When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the backlight pin will go low, and is pulled high again when the counter resets.
In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus the brightness, where `0x0000` is completely off and `0xFFFF` is completely on.
The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second.
In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM.
#### Timer Assisted PWM Implementation :id=timer-assisted-implementation
When `BACKLIGHT_PIN` is not set to a hardware backlight pin, QMK will use a hardware timer configured to trigger software interrupts. This time will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
When resetting to 0, the CPU will fire an OVF (overflow) interrupt that will turn the LEDs on, starting the duty cycle.
The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the CPU will fire a Compare Output match interrupt, which will turn the LEDs off.
In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus the brightness, where `0x0000` is completely off and `0xFFFF` is completely on.
The breathing effect is the same as in the hardware PWM implementation.
### ARM Driver :id=arm-configuration
While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
```makefile
BACKLIGHT_DRIVER = pwm
```
#### ChibiOS Configuration :id=arm-configuration
The following `#define`s apply only to ARM-based keyboards:
|Define |Default|Description |
|-----------------------|-------|-----------------------------------|
|`BACKLIGHT_PWM_DRIVER` |`PWMD4`|The PWM driver to use |
|`BACKLIGHT_PWM_CHANNEL`|`3` |The PWM channel to use |
|`BACKLIGHT_PAL_MODE` |`2` |The pin alternative function to use|
See the ST datasheet for your particular MCU to determine these values. Unless you are designing your own keyboard, you generally should not need to change them.
#### Caveats :id=arm-caveats
Currently only hardware PWM is supported, not timer assisted, and does not provide automatic configuration.
### Software PWM Driver :id=software-pwm-driver
In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your `rules.mk`:
```makefile
BACKLIGHT_DRIVER = software
```
#### Multiple Backlight Pins :id=multiple-backlight-pins
Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
In software PWM, it is possible to define multiple backlight pins, which will be turned on and off at the same time during the PWM duty cycle.
This feature allows to set, for instance, the Caps Lock LED's (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped Control in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on, as it is usually wired to a separate pin from the backlight.
To activate multiple backlight pins, add something like this to your `config.h`, instead of `BACKLIGHT_PIN`:
```c
#define BACKLIGHT_PINS { F5, B2 }
```
### Custom Driver :id=custom-driver
If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using this simple API provided by QMK. To enable, add this to your `rules.mk`:
```makefile
BACKLIGHT_DRIVER = custom
```
Then implement any of these hooks:
```c
void backlight_init_ports(void) {
// Optional - runs on startup
// Usually you want to configure pins here
}
void backlight_set(uint8_t level) {
// Optional - runs on level change
// Usually you want to respond to the new value
}
void backlight_task(void) {
// Optional - runs periodically
// Note that this is called in the main keyboard loop,
// so long running actions here can cause performance issues
}
```
## Example Schematic
In this typical example, the backlight LEDs are all connected in parallel towards an N-channel MOSFET. Its gate pin is wired to one of the microcontroller's GPIO pins through a 470Ω resistor to avoid ringing.
A pulldown resistor is also placed between the gate pin and ground to keep it at a defined state when it is not otherwise being driven by the MCU.
The values of these resistors are not critical - see [this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) for more information.
![Backlight example circuit](https://i.imgur.com/BmAvoUC.png)

45
feature_bluetooth.md Normal file
View File

@ -0,0 +1,45 @@
# Bluetooth
## Bluetooth Known Supported Hardware
Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input.
|Board |Bluetooth Protocol |Connection Type |rules.mk |Bluetooth Chip|
|----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------|
|Roving Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic | UART |`BLUETOOTH = RN42` | RN-42 |
|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy | SPI |`BLUETOOTH = AdafruitBLE` | nRF51822 |
Not Supported Yet but possible:
* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514)
* HC-05 boards flashed with RN-42 firmware. They apparently both use the CSR BC417 Chip. Flashing it with RN-42 firmware gives it HID capability.
* Sparkfun Bluetooth Mate
* HM-13 based boards
### 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
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.
<!-- FIXME: Document bluetooth support more completely. -->
## Bluetooth Rules.mk Options
The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary.md#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`.
Use only one of these to enable Bluetooth:
* BLUETOOTH_ENABLE = yes (Legacy Option)
* BLUETOOTH = RN42
* BLUETOOTH = AdafruitBLE
## Bluetooth Keycodes
This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both.
|Name |Description |
|----------|----------------------------------------------|
|`OUT_AUTO`|Automatically switch between USB and Bluetooth|
|`OUT_USB` |USB only |
|`OUT_BT` |Bluetooth only |

177
feature_bootmagic.md Normal file
View File

@ -0,0 +1,177 @@
# Bootmagic
There are three separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality, it is accessed in different ways depending on how your keyboard is configured.
**Bootmagic** is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command, hold down the Bootmagic key and one or more command keys.
**Bootmagic Keycodes** are prefixed with `MAGIC_`, and allow you to access the Bootmagic functionality *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode.
**Command**, formerly known as **Magic**, is another feature that allows you to control different aspects of your keyboard. While it shares some functionality with Bootmagic, it also allows you to do things that Bootmagic does not, such as printing version information to the console. For more information, see [Command](feature_command.md).
On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
```make
BOOTMAGIC_ENABLE = full
```
?> You may see `yes` being used in place of `full`, and this is okay. However, `yes` is deprecated, and ideally `full` (or `lite`) should be used instead.
Additionally, you can use [Bootmagic Lite](#bootmagic-lite) (a scaled down, very basic version of Bootmagic) by adding the following to your `rules.mk` file:
```make
BOOTMAGIC_ENABLE = lite
```
## Hotkeys
Hold down the Bootmagic key (Space by default) and the desired hotkey while plugging in your keyboard. For example, holding Space+`B` should cause it to enter the bootloader.
|Hotkey |Description |
|------------------|---------------------------------------------|
|Escape |Ignore Bootmagic configuration in EEPROM |
|`B` |Enter the bootloader |
|`D` |Toggle debugging over serial |
|`X` |Toggle key matrix debugging |
|`K` |Toggle keyboard debugging |
|`M` |Toggle mouse debugging |
|`L` |Set "Left Hand" for EE_HANDS handedness |
|`R` |Set "Right Hand" for EE_HANDS handedness |
|Backspace |Clear the EEPROM |
|Caps Lock |Toggle treating Caps Lock as Left Control |
|Left Control |Toggle swapping Caps Lock and Left Control |
|Left Alt |Toggle swapping Left Alt and Left GUI |
|Right Alt |Toggle swapping Right Alt and Right GUI |
|Left GUI |Toggle the GUI keys (useful when gaming) |
|<code>&#96;</code>|Toggle swapping <code>&#96;</code> and Escape|
|`\` |Toggle swapping `\` and Backspace |
|`N` |Toggle N-Key Rollover (NKRO) |
|`0` |Make layer 0 the default layer |
|`1` |Make layer 1 the default layer |
|`2` |Make layer 2 the default layer |
|`3` |Make layer 3 the default layer |
|`4` |Make layer 4 the default layer |
|`5` |Make layer 5 the default layer |
|`6` |Make layer 6 the default layer |
|`7` |Make layer 7 the default layer |
## Keycodes :id=keycodes
|Key |Aliases |Description |
|----------------------------------|---------|--------------------------------------------------------------------------|
|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
|`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_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 |
|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
## Configuration
If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level.
|Define |Default |Description |
|----------------------------------------|-------------|---------------------------------------------------|
|`BOOTMAGIC_KEY_SALT` |`KC_SPACE` |The Bootmagic key |
|`BOOTMAGIC_KEY_SKIP` |`KC_ESC` |Ignore Bootmagic configuration in EEPROM |
|`BOOTMAGIC_KEY_EEPROM_CLEAR` |`KC_BSPACE` |Clear the EEPROM configuration |
|`BOOTMAGIC_KEY_BOOTLOADER` |`KC_B` |Enter the bootloader |
|`BOOTMAGIC_KEY_DEBUG_ENABLE` |`KC_D` |Toggle debugging over serial |
|`BOOTMAGIC_KEY_DEBUG_MATRIX` |`KC_X` |Toggle matrix debugging |
|`BOOTMAGIC_KEY_DEBUG_KEYBOARD` |`KC_K` |Toggle keyboard debugging |
|`BOOTMAGIC_KEY_DEBUG_MOUSE` |`KC_M` |Toggle mouse debugging |
|`BOOTMAGIC_KEY_EE_HANDS_LEFT` |`KC_L` |Set "Left Hand" for EE_HANDS handedness |
|`BOOTMAGIC_KEY_EE_HANDS_RIGHT` |`KC_R` |Set "Right Hand" for EE_HANDS handedness |
|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK` |`KC_LCTRL` |Swap Left Control and Caps Lock |
|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL` |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control |
|`BOOTMAGIC_KEY_SWAP_LALT_LGUI` |`KC_LALT` |Toggle swapping Left Alt and Left GUI (for macOS) |
|`BOOTMAGIC_KEY_SWAP_RALT_RGUI` |`KC_RALT` |Toggle swapping Right Alt and Right GUI (for macOS)|
|`BOOTMAGIC_KEY_NO_GUI` |`KC_LGUI` |Toggle the GUI keys (useful when gaming) |
|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC` |`KC_GRAVE` |Toggle swapping <code>&#96;</code> and Escape |
|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH` |Toggle swapping `\` and Backspace |
|`BOOTMAGIC_HOST_NKRO` |`KC_N` |Toggle N-Key Rollover (NKRO) |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_0` |`KC_0` |Make layer 0 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_1` |`KC_1` |Make layer 1 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_2` |`KC_2` |Make layer 2 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_3` |`KC_3` |Make layer 3 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_4` |`KC_4` |Make layer 4 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_5` |`KC_5` |Make layer 5 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_6` |`KC_6` |Make layer 6 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_7` |`KC_7` |Make layer 7 the default layer |
# Bootmagic Lite :id=bootmagic-lite
In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
```make
BOOTMAGIC_ENABLE = lite
```
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
#define BOOTMAGIC_LITE_ROW 0
#define BOOTMAGIC_LITE_COLUMN 1
```
By default, these are set to 0 and 0, which is usually the "ESC" key on a majority of keyboards.
And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key.
!> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
## Split Keyboards
When handedness is predetermined via an option like `SPLIT_HAND_PIN`, you might need to configure a different key between halves. This To do so, add these entries to your `config.h` file:
```c
#define BOOTMAGIC_LITE_ROW_RIGHT 4
#define BOOTMAGIC_LITE_COLUMN_RIGHT 1
```
By default, these values are not set.
## Advanced Bootmagic Lite
The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need. A great example of this is the Zeal60 boards that have some additional handling needed.
To replace the function, all you need to do is add something like this to your code:
```c
void bootmagic_lite(void) {
matrix_scan();
wait_ms(DEBOUNCE * 2);
matrix_scan();
if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) {
// Jump to bootloader.
bootloader_jump();
}
}
```
You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.

103
feature_combo.md Normal file
View File

@ -0,0 +1,103 @@
# Combos
The Combo feature is a chording type solution for adding custom actions. It lets you hit multiple keys at once and produce a different effect. For instance, hitting `A` and `S` within the tapping term would hit `ESC` instead, or have it perform even more complex tasks.
To enable this feature, you need to add `COMBO_ENABLE = yes` to your `rules.mk`.
Additionally, in your `config.h`, you'll need to specify the number of combos that you'll be using, by adding `#define COMBO_COUNT 1` (replacing 1 with the number that you're using).
<!-- At this time, this is necessary -->
Also, by default, the tapping term for the Combos is set to the same value as `TAPPING_TERM` (200 by default on most boards). But you can specify a different value by defining it in your `config.h`. For instance: `#define COMBO_TERM 300` would set the time out period for combos to 300ms.
Then, your `keymap.c` file, you'll need to define a sequence of keys, terminated with `COMBO_END`, and a structure to list the combination of keys, and it's resulting action.
```c
const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {COMBO(test_combo, KC_ESC)};
```
This will send "Escape" if you hit the A and B keys.
!> This method only supports [basic keycodes](keycodes_basic.md). See the examples for more control.
## Examples
If you want to add a list, then you'd use something like this:
```c
enum combos {
AB_ESC,
JK_TAB
};
const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {
[AB_ESC] = COMBO(ab_combo, KC_ESC),
[JK_TAB] = COMBO(jk_combo, KC_TAB)
};
```
For a more complicated implementation, you can use the `process_combo_event` function to add custom handling.
```c
enum combo_events {
ZC_COPY,
XV_PASTE
};
const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END};
const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {
[ZC_COPY] = COMBO_ACTION(copy_combo),
[XV_PASTE] = COMBO_ACTION(paste_combo),
};
void process_combo_event(uint16_t combo_index, bool pressed) {
switch(combo_index) {
case ZC_COPY:
if (pressed) {
tap_code16(LCTL(KC_C));
}
break;
case XV_PASTE:
if (pressed) {
tap_code16(LCTL(KC_V));
}
break;
}
}
```
This will send Ctrl+C if you hit Z and C, and Ctrl+V if you hit X and V. But you could change this to do stuff like change layers, play sounds, or change settings.
## Additional Configuration
If you're using long combos, or even longer combos, you may run into issues with this, as the structure may not be large enough to accommodate what you're doing.
In this case, you can add either `#define EXTRA_LONG_COMBOS` or `#define EXTRA_EXTRA_LONG_COMBOS` in your `config.h` file.
You may also be able to enable action keys by defining `COMBO_ALLOW_ACTION_KEYS`.
## Keycodes
You can enable, disable and toggle the Combo feature on the fly. This is useful if you need to disable them temporarily, such as for a game.
|Keycode |Description |
|----------|---------------------------------|
|`CMB_ON` |Turns on Combo feature |
|`CMB_OFF` |Turns off Combo feature |
|`CMB_TOG` |Toggles Combo feature on and off |
## User callbacks
In addition to the keycodes, there are a few functions that you can use to set the status, or check it:
|Function |Description |
|-----------|--------------------------------------------------------------------|
| `combo_enable()` | Enables the combo feature |
| `combo_disable()` | Disables the combo feature, and clears the combo buffer |
| `combo_toggle()` | Toggles the state of the combo feature |
| `is_combo_enabled()` | Returns the status of the combo feature state (true or false) |

51
feature_command.md Normal file
View File

@ -0,0 +1,51 @@
# Command
Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md#keycodes). Wherever possible we encourage you to use that feature instead of Command.
On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`:
```make
COMMAND_ENABLE = yes
```
## Usage
To use Command, hold down the key combination defined by the `IS_COMMAND()` macro. By default this is Left Shift+Right Shift. Then, press the key corresponding to the command you want. For example, to output the current QMK version to the QMK Toolbox console, press Left Shift+Right Shift+`V`.
## Configuration
If you would like to change the key assignments for Command, `#define` these in your `config.h` at either the keyboard or keymap level. All keycode assignments here must omit the `KC_` prefix.
|Define |Default |Description |
|------------------------------------|--------------------------------|------------------------------------------------|
|`IS_COMMAND()` |`(get_mods() == MOD_MASK_SHIFT)`|The key combination to activate Command |
|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true` |Set default layer with the Function row |
|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true` |Set default layer with the number keys |
|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false` |Set default layer with `MAGIC_KEY_LAYER0..9` |
|`MAGIC_KEY_DEBUG` |`D` |Toggle debugging over serial |
|`MAGIC_KEY_DEBUG_MATRIX` |`X` |Toggle key matrix debugging |
|`MAGIC_KEY_DEBUG_KBD` |`K` |Toggle keyboard debugging |
|`MAGIC_KEY_DEBUG_MOUSE` |`M` |Toggle mouse debugging |
|`MAGIC_KEY_CONSOLE` |`C` |Enable the Command console |
|`MAGIC_KEY_VERSION` |`V` |Print the running QMK version to the console |
|`MAGIC_KEY_STATUS` |`S` |Print the current keyboard status to the console|
|`MAGIC_KEY_HELP` |`H` |Print Command help to the console |
|`MAGIC_KEY_HELP_ALT` |`SLASH` |Print Command help to the console (alternate) |
|`MAGIC_KEY_LAYER0` |`0` |Make layer 0 the default layer |
|`MAGIC_KEY_LAYER0_ALT` |`GRAVE` |Make layer 0 the default layer (alternate) |
|`MAGIC_KEY_LAYER1` |`1` |Make layer 1 the default layer |
|`MAGIC_KEY_LAYER2` |`2` |Make layer 2 the default layer |
|`MAGIC_KEY_LAYER3` |`3` |Make layer 3 the default layer |
|`MAGIC_KEY_LAYER4` |`4` |Make layer 4 the default layer |
|`MAGIC_KEY_LAYER5` |`5` |Make layer 5 the default layer |
|`MAGIC_KEY_LAYER6` |`6` |Make layer 6 the default layer |
|`MAGIC_KEY_LAYER7` |`7` |Make layer 7 the default layer |
|`MAGIC_KEY_LAYER8` |`8` |Make layer 8 the default layer |
|`MAGIC_KEY_LAYER9` |`9` |Make layer 9 the default layer |
|`MAGIC_KEY_BOOTLOADER` |`B` |Jump to bootloader |
|`MAGIC_KEY_BOOTLOADER_ALT` |`ESC` |Jump to bootloader (alternate) |
|`MAGIC_KEY_LOCK` |`CAPS` |Lock the keyboard so nothing can be typed |
|`MAGIC_KEY_EEPROM` |`E` |Print stored EEPROM config to the console |
|`MAGIC_KEY_EEPROM_CLEAR` |`BSPACE` |Clear the EEPROM |
|`MAGIC_KEY_NKRO` |`N` |Toggle N-Key Rollover (NKRO) |
|`MAGIC_KEY_SLEEP_LED` |`Z` |Toggle LED when computer is sleeping |

151
feature_debounce_type.md Normal file
View File

@ -0,0 +1,151 @@
# Contact bounce / contact chatter
Mechanical switches often don't have a clean single transition between pressed and unpressed states.
In an ideal world, when you press a switch, you would expect the digital pin to see something like this:
(X axis showing time
```
voltage +----------------------
^ |
| |
| ------------------+
----> time
```
However in the real world you will actually see contact bounce, which will look like multiple 1->0 and 0->1 transitions,
until the value finally settles.
```
+-+ +--+ +-------------
| | | | |
| | | | |
+-----------------+ +-+ +-+
```
The time it takes for the switch to settle might vary with switch type, age, and even pressing technique.
If the device chooses not to mitigate contact bounce, then often actions that happen when the switch is pressed are repeated
multiple times.
There are many ways to handle contact bounce ("Debouncing"). Some include employing additional hardware, for example an RC filter,
while there are various ways to do debouncing in software too, often called debounce algorithms. This page discusses software
debouncing methods available in QMK.
While technically not considered contact bounce/contact chatter, some switch technologies are susceptible to noise, meaning,
while the key is not changing state, sometimes short random 0->1 or 1->0 transitions might be read by the digital circuit, for example:
```
+-+
| |
| |
+-----------------+ +--------------------
```
Many debounce methods (but not all) will also make the device resistant to noise. If you are working with a technology that is
susceptible to noise, you must choose a debounce method that will also mitigate noise for you.
## Types of debounce algorithms
1) Unit of time: Timestamp (milliseconds) vs Cycles (scans)
* Debounce algorithms often have a 'debounce time' parameter, that specifies the maximum settling time of the switch contacts.
This time might be measured in various units:
* Cycles-based debouncing waits n cycles (scans), decreasing count by one each matrix_scan
* Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does substraction to figure out time elapsed.
* Timestamp-based debouncing is usually superior, especially in the case of noise-resistant devices because settling times of physical
switches is specified in units of time, and should not depend on the matrix scan-rate of the keyboard.
* Cycles-based debouncing is sometimes considered inferior, because the settling time that it is able to compensate for depends on the
performance of the matrix scanning code. If you use cycles-based debouncing, and you significantly improve the performance of your scanning
code, you might end up with less effective debouncing. A situation in which cycles-based debouncing might be preferable is when
noise is present, and the scanning algorithm is slow, or variable speed. Even if your debounce algorithm is fundamentally noise-resistant,
if the scanning is slow, and you are using a timestamp-based algorithm, you might end up making a debouncing decision based on only two
sampled values, which will limit the noise-resistance of the algorithm.
* Currently all built-in debounce algorithms support timestamp-based debouncing only. In the future we might
implement cycles-based debouncing, and it will be selectable via a ```config.h``` macro.
2) Symmetric vs Asymmetric
* Symmetric - apply the same debouncing algorithm, to both key-up and key-down events.
* Recommended naming convention: ```sym_*```
* Asymmetric - apply different debouncing algorithms to key-down and key-up events. E.g. Eager key-down, Defer key-up.
* Recommended naming convention: ```asym_*``` followed by details of the type of algorithm in use, in order, for key-down and then key-up
3) Eager vs Defer
* Eager - any key change is reported immediately. All further inputs for DEBOUNCE ms are ignored.
* Eager algorithms are not noise-resistant.
* Recommended naming conventions:
* ```sym_eager_*```
* ```asym_eager_*_*```: key-down is using eager algorithm
* ```asym_*_eager_*```: key-up is using eager algorithm
* Defer - wait for no changes for DEBOUNCE ms before reporting change.
* Defer algorithms are noise-resistant
* Recommended naming conventions:
* ```sym_defer_*```
* ```asym_defer_*_*```: key-down is using defer algorithm
* ```asym_*_defer_*```: key-up is using defer algorithm
4) Global vs Per-Key vs Per-Row
* Global - one timer for all keys. Any key change state affects global timer
* Recommended naming convention: ```*_g```
* Per-key - one timer per key
* Recommended naming convention: ```*_pk```
* Per-row - one timer per row
* Recommended naming convention: ```*_pr```
* Per-key and per-row algorithms consume more resources (in terms of performance,
and ram usage), but fast typists might prefer them over global.
## Debounce algorithms supported by QMK
QMK supports multiple debounce algorithms through its debounce API.
The logic for which debounce method called is below. It checks various defines that you have set in ```rules.mk```
```
DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
DEBOUNCE_TYPE?= sym_defer_g
ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
endif
```
### Debounce selection
| DEBOUNCE_TYPE | Description | What else is needed |
| ------------- | --------------------------------------------------- | ----------------------------- |
| Not defined | Use the default algorithm, currently sym_defer_g | Nothing |
| custom | Use your own debounce code | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions |
| Anything Else | Use another algorithm from quantum/debounce/* | Nothing |
**Regarding split keyboards**:
The debounce code is compatible with split keyboards.
### Selecting an included debouncing method
Keyboards may select one of the already implemented debounce methods, by adding to ```rules.mk``` the following line:
```
DEBOUNCE_TYPE = <name of algorithm>
```
Where name of algorithm is one of:
* ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed.
* This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant.
* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row.
For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
* ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
* ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed.
### A couple algorithms that could be implemented in the future:
* ```sym_defer_pr```
* ```sym_eager_g```
* ```asym_eager_defer_pk```
### Use your own debouncing code
You have the option to implement you own debouncing algorithm. To do this:
* Set ```DEBOUNCE_TYPE = custom``` in ```rules.mk```.
* Add ```SRC += debounce.c``` in ```rules.mk```
* Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples.
* Debouncing occurs after every raw matrix scan.
* Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly.
* If the algorithm might be applicable to other keyboards, please consider adding it to ```quantum/debounce```
### Old names
The following old names for existing algorithms will continue to be supported, however it is recommended to use the new names instead.
* sym_g - old name for sym_defer_g
* eager_pk - old name for sym_eager_pk
* sym_pk - old name for sym_defer_pk
* eager_pr - old name for sym_eager_pr

104
feature_dip_switch.md Normal file
View File

@ -0,0 +1,104 @@
# DIP Switches
DIP switches are supported by adding this to your `rules.mk`:
DIP_SWITCH_ENABLE = yes
and this to your `config.h`:
```c
// Connects each switch in the dip switch to the GPIO pin of the MCU
#define DIP_SWITCH_PINS { B14, A15, A10, B9 }
```
or
```c
// Connect each switch in the DIP switch to an unused intersections in the key matrix.
#define DIP_SWITCH_MATRIX_GRID { {0,6}, {1,6}, {2,6} } // List of row and col pairs
```
## Callbacks
The callback functions can be inserted into your `<keyboard>.c`:
```c
void dip_switch_update_kb(uint8_t index, bool active) {
dip_switch_update_user(index, active);
}
```
or `keymap.c`:
```c
void dip_switch_update_user(uint8_t index, bool active) {
switch (index) {
case 0:
if(active) { audio_on(); } else { audio_off(); }
break;
case 1:
if(active) { clicky_on(); } else { clicky_off(); }
break;
case 2:
if(active) { music_on(); } else { music_off(); }
break;
case 3:
if (active) {
#ifdef AUDIO_ENABLE
PLAY_SONG(plover_song);
#endif
layer_on(_PLOVER);
} else {
#ifdef AUDIO_ENABLE
PLAY_SONG(plover_gb_song);
#endif
layer_off(_PLOVER);
}
break;
}
}
```
Additionally, we support bit mask functions which allow for more complex handling.
```c
void dip_switch_update_mask_kb(uint32_t state) {
dip_switch_update_mask_user(state);
}
```
or `keymap.c`:
```c
void dip_switch_update_mask_user(uint32_t state) {
if (state & (1UL<<0) && state & (1UL<<1)) {
layer_on(_ADJUST); // C on esc
} else {
layer_off(_ADJUST);
}
if (state & (1UL<<0)) {
layer_on(_TEST_A); // A on ESC
} else {
layer_off(_TEST_A);
}
if (state & (1UL<<1)) {
layer_on(_TEST_B); // B on esc
} else {
layer_off(_TEST_B);
}
}
```
## Hardware
### Connects each switch in the dip switch to the GPIO pin of the MCU
One side of the DIP switch should be wired directly to the pin on the MCU, and the other side to ground. It should not matter which side is connected to which, as it should be functionally the same.
### Connect each switch in the DIP switch to an unused intersections in the key matrix.
As with the keyswitch, a diode and DIP switch connect the ROW line to the COL line.

66
feature_dynamic_macros.md Normal file
View File

@ -0,0 +1,66 @@
# Dynamic Macros: Record and Replay Macros in Runtime
QMK supports temporary macros created on the fly. We call these Dynamic Macros. They are defined by the user from the keyboard and are lost when the keyboard is unplugged or otherwise rebooted.
You can store one or two macros and they may have a combined total of 128 keypresses. You can increase this size at the cost of RAM.
To enable them, first include `DYNAMIC_MACRO_ENABLE = yes` in your `rules.mk`. Then, add the following keys to your keymap:
|Key |Alias |Description |
|------------------|----------|---------------------------------------------------|
|`DYN_REC_START1` |`DM_REC1` |Start recording Macro 1 |
|`DYN_REC_START2` |`DM_REC2` |Start recording Macro 2 |
|`DYN_MACRO_PLAY1` |`DM_PLY1` |Replay Macro 1 |
|`DYN_MACRO_PLAY2` |`DM_PLY2` |Replay Macro 2 |
|`DYN_REC_STOP` |`DM_RSTP` |Finish the macro that is currently being recorded. |
That should be everything necessary.
To start recording the macro, press either `DYN_REC_START1` or `DYN_REC_START2`.
To finish the recording, press the `DYN_REC_STOP` layer button. You can also press `DYN_REC_START1` or `DYN_REC_START2` again to stop the recording.
To replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`.
It is possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again. You can disable this completely by defining `DYNAMIC_MACRO_NO_NESTING` in your `config.h` file.
?> For the details about the internals of the dynamic macros, please read the comments in the `process_dynamic_macro.h` and `process_dynamic_macro.c` files.
## Customization
There are a number of options added that should allow some additional degree of customization
|Define |Default |Description |
|----------------------------|----------------|-----------------------------------------------------------------------------------------------------------------|
|`DYNAMIC_MACRO_SIZE` |128 |Sets the amount of memory that Dynamic Macros can use. This is a limited resource, dependent on the controller. |
|`DYNAMIC_MACRO_USER_CALL` |*Not defined* |Defining this falls back to using the user `keymap.c` file to trigger the macro behavior. |
|`DYNAMIC_MACRO_NO_NESTING` |*Not Defined* |Defining this disables the ability to call a macro from another macro (nested macros). |
If the LEDs start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by adding the `DYNAMIC_MACRO_SIZE` define in your `config.h` (default value: 128; please read the comments for it in the header).
### DYNAMIC_MACRO_USER_CALL
For users of the earlier versions of dynamic macros: It is still possible to finish the macro recording using just the layer modifier used to access the dynamic macro keys, without a dedicated `DYN_REC_STOP` key. If you want this behavior back, add `#define DYNAMIC_MACRO_USER_CALL` to your `config.h` and insert the following snippet at the beginning of your `process_record_user()` function:
```c
uint16_t macro_kc = (keycode == MO(_DYN) ? DYN_REC_STOP : keycode);
if (!process_record_dynamic_macro(macro_kc, record)) {
return false;
}
```
### User Hooks
There are a number of hooks that you can use to add custom functionality and feedback options to Dynamic Macro feature. This allows for some additional degree of customization.
Note, that direction indicates which macro it is, with `1` being Macro 1, `-1` being Macro 2, and 0 being no macro.
* `dynamic_macro_record_start_user(void)` - Triggered when you start recording a macro.
* `dynamic_macro_play_user(int8_t direction)` - Triggered when you play back a macro.
* `dynamic_macro_record_key_user(int8_t direction, keyrecord_t *record)` - Triggered on each keypress while recording a macro.
* `dynamic_macro_record_end_user(int8_t direction)` - Triggered when the macro recording is stopped.
Additionally, you can call `dynamic_macro_led_blink()` to flash the backlights if that feature is enabled.

76
feature_encoders.md Normal file
View File

@ -0,0 +1,76 @@
# Encoders
Basic encoders are supported by adding this to your `rules.mk`:
```make
ENCODER_ENABLE = yes
```
and this to your `config.h`:
```c
#define ENCODERS_PAD_A { B12 }
#define ENCODERS_PAD_B { B13 }
```
Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.:
```c
#define ENCODERS_PAD_A { encoder1a, encoder2a }
#define ENCODERS_PAD_B { encoder1b, encoder2b }
```
If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions. They can also be flipped with a define:
```c
#define ENCODER_DIRECTION_FLIP
```
Additionally, the resolution, which defines how many pulses the encoder registers between each detent, can be defined with:
```c
#define ENCODER_RESOLUTION 4
```
## Split Keyboards
If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout for the right half like this:
```c
#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a }
#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b }
```
## Callbacks
The callback functions can be inserted into your `<keyboard>.c`:
```c
void encoder_update_kb(uint8_t index, bool clockwise) {
encoder_update_user(index, clockwise);
}
```
or `keymap.c`:
```c
void encoder_update_user(uint8_t index, bool clockwise) {
if (index == 0) { /* First encoder */
if (clockwise) {
tap_code(KC_PGDN);
} else {
tap_code(KC_PGUP);
}
} else if (index == 1) { /* Second encoder */
if (clockwise) {
tap_code(KC_DOWN);
} else {
tap_code(KC_UP);
}
}
}
```
## Hardware
The A an B lines of the encoders should be wired directly to the MCU, and the C/common lines should be wired to ground.

32
feature_grave_esc.md Normal file
View File

@ -0,0 +1,32 @@
# Grave Escape
If you're using a 60% keyboard, or any other layout with no F-row, you will have noticed that there is no dedicated Escape key. Grave Escape is a feature that allows you to share the grave key (<code>&#96;</code> and `~`) with Escape.
## 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.
## What Your OS Sees
If Mary presses GESC on her keyboard, the OS will see an KC_ESC character. Now if Mary holds Shift down and presses GESC it will output `~`, or a shifted backtick. Now if she holds GUI/CMD/WIN, it will output a simple <code>&#96;</code> character.
## Keycodes
|Key |Aliases |Description |
|---------|-----------|------------------------------------------------------------------|
|`KC_GESC`|`GRAVE_ESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
### Caveats
On macOS, Command+<code>&#96;</code> is by default mapped to "Move focus to next window" so it will not output a backtick. Additionally, Terminal always recognises this shortcut to cycle between windows, even if the shortcut is changed in the Keyboard preferences.
## Configuration
There are several possible key combinations this will break, among them Control+Shift+Escape on Windows and Command+Option+Escape on macOS. To work around this, you can `#define` these options in your `config.h`:
|Define |Description |
|--------------------------|-----------------------------------------|
|`GRAVE_ESC_ALT_OVERRIDE` |Always send Escape if Alt is pressed |
|`GRAVE_ESC_CTRL_OVERRIDE` |Always send Escape if Control is pressed |
|`GRAVE_ESC_GUI_OVERRIDE` |Always send Escape if GUI is pressed |
|`GRAVE_ESC_SHIFT_OVERRIDE`|Always send Escape if Shift is pressed |

158
feature_haptic_feedback.md Normal file
View File

@ -0,0 +1,158 @@
# Haptic Feedback
## Haptic feedback rules.mk options
The following options are currently available for haptic feedback in `rules.mk`:
`HAPTIC_ENABLE += DRV2605L`
`HAPTIC_ENABLE += SOLENOID`
## Known Supported Hardware
| Name | Description |
|--------------------|-------------------------------------------------|
| [LV061228B-L65-A](https://www.digikey.com/product-detail/en/jinlong-machinery-electronics-inc/LV061228B-L65-A/1670-1050-ND/7732325) | z-axis 2v LRA |
| [Mini Motor Disc](https://www.adafruit.com/product/1201) | small 2-5v ERM |
## Haptic Keycodes
Not all keycodes below will work depending on which haptic mechanism you have chosen.
| Name | Description |
|-----------|-------------------------------------------------------|
|`HPT_ON` | Turn haptic feedback on |
|`HPT_OFF` | Turn haptic feedback off |
|`HPT_TOG` | Toggle haptic feedback on/off |
|`HPT_RST` | Reset haptic feedback config to default |
|`HPT_FBK` | Toggle feedback to occur on keypress, release or both |
|`HPT_BUZ` | Toggle solenoid buzz on/off |
|`HPT_MODI` | Go to next DRV2605L waveform |
|`HPT_MODD` | Go to previous DRV2605L waveform |
|`HPT_CONT` | Toggle continuous haptic mode on/off |
|`HPT_CONI` | Increase DRV2605L continous haptic strength |
|`HPT_COND` | Decrease DRV2605L continous haptic strength |
|`HPT_DWLI` | Increase Solenoid dwell time |
|`HPT_DWLD` | Decrease Solenoid dwell time |
### Solenoids
First you will need a build a circuit to drive the solenoid through a mosfet as most MCU will not be able to provide the current needed to drive the coil in the solenoid.
[Wiring diagram provided by Adafruit](https://playground.arduino.cc/uploads/Learning/solenoid_driver.pdf)
| Settings | Default | Description |
|--------------------------|---------------|-------------------------------------------------------|
|`SOLENOID_PIN` | *Not defined* |Configures the pin that the Solenoid is connected to. |
|`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. |
?> Dwell time is how long the "plunger" stays activated. The dwell time changes how the solenoid sounds.
Beware that some pins may be powered during bootloader (ie. A13 on the STM32F303 chip) and will result in the solenoid kept in the on state through the whole flashing process. This may overheat and damage the solenoid. If you find that the pin the solenoid is connected to is triggering the solenoid during bootloader/DFU, select another pin.
### DRV2605L
DRV2605L is controlled over i2c protocol, and has to be connected to the SDA and SCL pins, these varies depending on the MCU in use.
#### Feedback motor setup
This driver supports 2 different feedback motors. Set the following in your `config.h` based on which motor you have selected.
##### ERM
Eccentric Rotating Mass vibration motors (ERM) is motor with a off-set weight attached so when drive signal is attached, the off-set weight spins and causes a sinusoidal wave that translate into vibrations.
```
#define FB_ERM_LRA 0
#define FB_BRAKEFACTOR 3 /* For 1x:0, 2x:1, 3x:2, 4x:3, 6x:4, 8x:5, 16x:6, Disable Braking:7 */
#define FB_LOOPGAIN 1 /* For Low:0, Medium:1, High:2, Very High:3 */
/* Please refer to your datasheet for the optimal setting for your specific motor. */
#define RATED_VOLTAGE 3
#define V_PEAK 5
```
##### LRA
Linear resonant actuators (LRA, also know as a linear vibrator) works different from a ERM. A LRA has a weight and magnet suspended by springs and a voice coil. When the drive signal is applied, the weight would be vibrate on a single axis (side to side or up and down). Since the weight is attached to a spring, there is a resonance effect at a specific frequency. This frequency is where the LRA will operate the most efficiently. Refer to the motor's datasheet for the recommanded range for this frequency.
```
#define FB_ERM_LRA 1
#define FB_BRAKEFACTOR 3 /* For 1x:0, 2x:1, 3x:2, 4x:3, 6x:4, 8x:5, 16x:6, Disable Braking:7 */
#define FB_LOOPGAIN 1 /* For Low:0, Medium:1, High:2, Very High:3 */
/* Please refer to your datasheet for the optimal setting for your specific motor. */
#define RATED_VOLTAGE 2
#define V_PEAK 2.8
#define V_RMS 2.0
#define V_PEAK 2.1
#define F_LRA 205 /* resonance freq */
```
#### DRV2605L waveform library
DRV2605L comes with preloaded library of various waveform sequences that can be called and played. If writing a macro, these waveforms can be played using `DRV_pulse(*sequence name or number*)`
List of waveform sequences from the datasheet:
|seq# | Sequence name |seq# | Sequence name |seq# |Sequence name |
|-----|---------------------|-----|-----------------------------------|-----|--------------------------------------|
| 1 | strong_click | 43 | lg_dblclick_med_60 | 85 | transition_rampup_med_smooth2 |
| 2 | strong_click_60 | 44 | lg_dblsharp_tick | 86 | transition_rampup_short_smooth1 |
| 3 | strong_click_30 | 45 | lg_dblsharp_tick_80 | 87 | transition_rampup_short_smooth2 |
| 4 | sharp_click | 46 | lg_dblsharp_tick_60 | 88 | transition_rampup_long_sharp1 |
| 5 | sharp_click_60 | 47 | buzz | 89 | transition_rampup_long_sharp2 |
| 6 | sharp_click_30 | 48 | buzz_80 | 90 | transition_rampup_med_sharp1 |
| 7 | soft_bump | 49 | buzz_60 | 91 | transition_rampup_med_sharp2 |
| 8 | soft_bump_60 | 50 | buzz_40 | 92 | transition_rampup_short_sharp1 |
| 9 | soft_bump_30 | 51 | buzz_20 | 93 | transition_rampup_short_sharp2 |
| 10 | dbl_click | 52 | pulsing_strong | 94 | transition_rampdown_long_smooth1_50 |
| 11 | dbl_click_60 | 53 | pulsing_strong_80 | 95 | transition_rampdown_long_smooth2_50 |
| 12 | trp_click | 54 | pulsing_medium | 96 | transition_rampdown_med_smooth1_50 |
| 13 | soft_fuzz | 55 | pulsing_medium_80 | 97 | transition_rampdown_med_smooth2_50 |
| 14 | strong_buzz | 56 | pulsing_sharp | 98 | transition_rampdown_short_smooth1_50 |
| 15 | alert_750ms | 57 | pulsing_sharp_80 | 99 | transition_rampdown_short_smooth2_50 |
| 16 | alert_1000ms | 58 | transition_click | 100 | transition_rampdown_long_sharp1_50 |
| 17 | strong_click1 | 59 | transition_click_80 | 101 | transition_rampdown_long_sharp2_50 |
| 18 | strong_click2_80 | 60 | transition_click_60 | 102 | transition_rampdown_med_sharp1_50 |
| 19 | strong_click3_60 | 61 | transition_click_40 | 103 | transition_rampdown_med_sharp2_50 |
| 20 | strong_click4_30 | 62 | transition_click_20 | 104 | transition_rampdown_short_sharp1_50 |
| 21 | medium_click1 | 63 | transition_click_10 | 105 | transition_rampdown_short_sharp2_50 |
| 22 | medium_click2_80 | 64 | transition_hum | 106 | transition_rampup_long_smooth1_50 |
| 23 | medium_click3_60 | 65 | transition_hum_80 | 107 | transition_rampup_long_smooth2_50 |
| 24 | sharp_tick1 | 66 | transition_hum_60 | 108 | transition_rampup_med_smooth1_50 |
| 25 | sharp_tick2_80 | 67 | transition_hum_40 | 109 | transition_rampup_med_smooth2_50 |
| 26 | sharp_tick3_60 | 68 | transition_hum_20 | 110 | transition_rampup_short_smooth1_50 |
| 27 | sh_dblclick_str | 69 | transition_hum_10 | 111 | transition_rampup_short_smooth2_50 |
| 28 | sh_dblclick_str_80 | 70 | transition_rampdown_long_smooth1 | 112 | transition_rampup_long_sharp1_50 |
| 29 | sh_dblclick_str_60 | 71 | transition_rampdown_long_smooth2 | 113 | transition_rampup_long_sharp2_50 |
| 30 | sh_dblclick_str_30 | 72 | transition_rampdown_med_smooth1 | 114 | transition_rampup_med_sharp1_50 |
| 31 | sh_dblclick_med | 73 | transition_rampdown_med_smooth2 | 115 | transition_rampup_med_sharp2_50 |
| 32 | sh_dblclick_med_80 | 74 | transition_rampdown_short_smooth1 | 116 | transition_rampup_short_sharp1_50 |
| 33 | sh_dblclick_med_60 | 75 | transition_rampdown_short_smooth2 | 117 | transition_rampup_short_sharp2_50 |
| 34 | sh_dblsharp_tick | 76 | transition_rampdown_long_sharp1 | 118 | long_buzz_for_programmatic_stopping |
| 35 | sh_dblsharp_tick_80 | 77 | transition_rampdown_long_sharp2 | 119 | smooth_hum1_50 |
| 36 | sh_dblsharp_tick_60 | 78 | transition_rampdown_med_sharp1 | 120 | smooth_hum2_40 |
| 37 | lg_dblclick_str | 79 | transition_rampdown_med_sharp2 | 121 | smooth_hum3_30 |
| 38 | lg_dblclick_str_80 | 80 | transition_rampdown_short_sharp1 | 122 | smooth_hum4_20 |
| 39 | lg_dblclick_str_60 | 81 | transition_rampdown_short_sharp2 | 123 | smooth_hum5_10 |
| 40 | lg_dblclick_str_30 | 82 | transition_rampup_long_smooth1 | | |
| 41 | lg_dblclick_med | 83 | transition_rampup_long_smooth2 | | |
| 42 | lg_dblclick_med_80 | 84 | transition_rampup_med_smooth1 | | |
### Optional DRV2605L defines
```
#define DRV_GREETING *sequence name or number*
```
If haptic feedback is enabled, the keyboard will vibrate to a specific sqeuence during startup. That can be selected using the following define:
```
#define DRV_MODE_DEFAULT *sequence name or number*
```
This will set what sequence HPT_RST will set as the active mode. If not defined, mode will be set to 1 when HPT_RST is pressed.
### DRV2605L Continuous Haptic Mode
This mode sets continuous haptic feedback with the option to increase or decrease strength.

57
feature_hd44780.md Normal file
View File

@ -0,0 +1,57 @@
# HD44780 LCD Displays
This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes.
## Configuration
You will need to configure the pins used by your display, and its number of lines and columns in your keyboard's `config.h`.
Uncomment the section labled HD44780 and change the parameters as needed.
````
/*
* HD44780 LCD Display Configuration
*/
#define LCD_LINES 2 //< number of visible lines of the display
#define LCD_DISP_LENGTH 16 //< visibles characters per line of the display
#define LCD_IO_MODE 1 //< 0: memory mapped mode, 1: IO port mode
#if LCD_IO_MODE
#define LCD_PORT PORTB //< port for the LCD lines
#define LCD_DATA0_PORT LCD_PORT //< port for 4bit data bit 0
#define LCD_DATA1_PORT LCD_PORT //< port for 4bit data bit 1
#define LCD_DATA2_PORT LCD_PORT //< port for 4bit data bit 2
#define LCD_DATA3_PORT LCD_PORT //< port for 4bit data bit 3
#define LCD_DATA0_PIN 4 //< pin for 4bit data bit 0
#define LCD_DATA1_PIN 5 //< pin for 4bit data bit 1
#define LCD_DATA2_PIN 6 //< pin for 4bit data bit 2
#define LCD_DATA3_PIN 7 //< pin for 4bit data bit 3
#define LCD_RS_PORT LCD_PORT //< port for RS line
#define LCD_RS_PIN 3 //< pin for RS line
#define LCD_RW_PORT LCD_PORT //< port for RW line
#define LCD_RW_PIN 2 //< pin for RW line
#define LCD_E_PORT LCD_PORT //< port for Enable line
#define LCD_E_PIN 1 //< pin for Enable line
#endif
````
Should you need to configure other properties you can copy them from `quantum/hd44780.h` and set them in your `config.h`
## Usage
To initialize your display, call `lcd_init()` with one of these parameters:
````
LCD_DISP_OFF : display off
LCD_DISP_ON : display on, cursor off
LCD_DISP_ON_CURSOR : display on, cursor on
LCD_DISP_ON_CURSOR_BLINK : display on, cursor on flashing
````
This is best done in your keyboards `matrix_init_kb` or your keymaps `matrix_init_user`.
It is advised to clear the display before use.
To do so call `lcd_clrscr()`.
To now print something to your Display you first call `lcd_gotoxy(column, line)`. To go to the start of the first line you would call `lcd_gotoxy(0, 0)` and then print a string with `lcd_puts("example string")`.
There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)

147
feature_joystick.md Normal file
View File

@ -0,0 +1,147 @@
## Joystick
The keyboard can be made to be recognized as a joystick HID device by the operating system.
This is enabled by adding `JOYSTICK_ENABLE` to `rules.mk`. You can set this value to `analog`, `digital`, or `no`.
!> Joystick support is not currently available on V-USB devices.
The joystick feature provides two services:
* reading analog input devices (eg. potentiometers)
* sending gamepad HID reports
Both services can be used without the other, depending on whether you just want to read a device but not send gamepad reports (for volume control for instance)
or send gamepad reports based on values computed by the keyboard.
### Analog Input
To use analog input you must first enable it in `rules.mk`:
```makefile
JOYSTICK_ENABLE = analog
```
An analog device such as a potentiometer found on a gamepad's analog axes is based on a [voltage divider](https://en.wikipedia.org/wiki/Voltage_divider).
It is composed of three connectors linked to the ground, the power input and power output (usually the middle one). The power output holds the voltage that varies based on the position of the cursor,
which value will be read using your MCU's [ADC](https://en.wikipedia.org/wiki/Analog-to-digital_converter).
Depending on which pins are already used by your keyboard's matrix, the rest of the circuit can get a little bit more complicated,
feeding the power input and ground connection through pins and using diodes to avoid bad interactions with the matrix scanning procedures.
### Configuring the Joystick
By default, two axes and eight buttons are defined. This can be changed in your `config.h`:
```c
// Max 32
#define JOYSTICK_BUTTON_COUNT 16
// Max 6: X, Y, Z, Rx, Ry, Rz
#define JOYSTICK_AXES_COUNT 3
```
When defining axes for your joystick, you have to provide a definition array. You can do this from your keymap.c file.
A joystick will either be read from an input pin that allows the use of the ADC, or can be virtual, so that its value is provided by your code.
You have to define an array of type ''joystick_config_t'' and of proper size.
There are three ways for your circuit to work with the ADC, that relies on the use of 1, 2 or 3 pins of the MCU:
* 1 pin: your analog device is directly connected to your device GND and VCC. The only pin used is the ADC pin of your choice.
* 2 pins: your analog device is powered through a pin that allows toggling it on or off. The other pin is used to read the input value through the ADC.
* 3 pins: both the power input and ground are connected to pins that must be set to a proper state before reading and restored afterwards.
The configuration of each axis is performed using one of four macros:
* `JOYSTICK_AXIS_VIRTUAL`: no ADC reading must be performed, that value will be provided by keyboard/keymap-level code
* `JOYSTICK_AXIS_IN(INPUT_PIN, LOW, REST, HIGH)`: a voltage will be read on the provided pin, which must be an ADC-capable pin.
* `JOYSTICK_AXIS_IN_OUT(INPUT_PIN, OUTPUT_PIN, LOW, REST, HIGH)`: the provided `OUTPUT_PIN` will be set high before `INPUT_PIN` is read.
* `JOYSTICK_AXIS_IN_OUT_GROUND(INPUT_PIN, OUTPUT_PIN, GROUND_PIN, LOW, REST, HIGH)`: the `OUTPUT_PIN` will be set high and `GROUND_PIN` will be set low before reading from `INPUT_PIN`.
In any case where an ADC reading takes place (when `INPUT_PIN` is provided), additional `LOW`, `REST` and `HIGH` parameters are used.
These implement the calibration of the analog device by defining the range of read values that will be mapped to the lowest, resting position and highest possible value for the axis (-127 to 127).
In practice, you have to provide the lowest/highest raw ADC reading, and the raw reading at resting position, when no deflection is applied. You can provide inverted `LOW` and `HIGH` to invert the axis.
For instance, an axes configuration can be defined in the following way:
```c
//joystick config
joystick_config_t joystick_axes[JOYSTICK_AXES_COUNT] = {
[0] = JOYSTICK_AXIS_IN_OUT_GROUND(A4, B0, A7, 900, 575, 285),
[1] = JOYSTICK_AXIS_VIRTUAL
};
```
When the ADC reads 900 or higher, the returned axis value will be -127, whereas it will be 127 when the ADC reads 285 or lower. Zero is returned when 575 is read.
In this example, the first axis will be read from the `A4` pin while `B0` is set high and `A7` is set low, using `analogReadPin()`, whereas the second axis will not be read.
In order to give a value to the second axis, you can do so in any customizable entry point: as an action, in `process_record_user()` or in `matrix_scan_user()`, or even in `joystick_task()` which is called even when no key has been pressed.
You assign a value by writing to `joystick_status.axes[axis_index]` a signed 8-bit value (ranging from -127 to 127). Then it is necessary to assign the flag `JS_UPDATED` to `joystick_status.status` in order for an updated HID report to be sent.
The following example writes two axes based on keypad presses, with `KC_P5` as a precision modifier:
```c
#ifdef ANALOG_JOYSTICK_ENABLE
static uint8_t precision_val = 70;
static uint8_t axesFlags = 0;
enum axes {
Precision = 1,
Axis1High = 2,
Axis1Low = 4,
Axis2High = 8,
Axis2Low = 16
};
#endif
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
#ifdef ANALOG_JOYSTICK_ENABLE
// virtual joystick
# if JOYSTICK_AXES_COUNT > 1
case KC_P8:
if (record->event.pressed) {
axesFlags |= Axis2Low;
} else {
axesFlags &= ~Axis2Low;
}
joystick_status.status |= JS_UPDATED;
break;
case KC_P2:
if (record->event.pressed) {
axesFlags |= Axis2High;
} else {
axesFlags &= ~Axis2High;
}
joystick_status.status |= JS_UPDATED;
break;
# endif
case KC_P4:
if (record->event.pressed) {
axesFlags |= Axis1Low;
} else {
axesFlags &= ~Axis1Low;
}
joystick_status.status |= JS_UPDATED;
break;
case KC_P6:
if (record->event.pressed) {
axesFlags |= Axis1High;
} else {
axesFlags &= ~Axis1High;
}
joystick_status.status |= JS_UPDATED;
break;
case KC_P5:
if (record->event.pressed) {
axesFlags |= Precision;
} else {
axesFlags &= ~Precision;
}
joystick_status.status |= JS_UPDATED;
break;
#endif
}
return true;
}
```
### Triggering Joystick Buttons
Joystick buttons are normal Quantum keycodes, defined as `JS_BUTTON0` to `JS_BUTTON31`, depending on the number of buttons you have configured.
To trigger a joystick button, just add the corresponding keycode to your keymap.

22
feature_key_lock.md Normal file
View File

@ -0,0 +1,22 @@
# Key Lock
Sometimes you may find yourself needing to hold down a specific key for a long period of time. Key Lock holds down the next key you press for you. Press it again, and it will be released.
Let's say you need to type in ALL CAPS for a few sentences. Hit `KC_LOCK`, and then Shift. Now, Shift will be considered held until you tap it again. You can think of Key Lock as Caps Lock, but supercharged.
## Usage
First, enable Key Lock by setting `KEY_LOCK_ENABLE = yes` in your `rules.mk`. Then pick a key in your keymap and assign it the keycode `KC_LOCK`.
## Keycodes
|Keycode |Description |
|---------|--------------------------------------------------------------|
|`KC_LOCK`|Hold down the next key pressed, until the key is pressed again|
## Caveats
Key Lock is only able to hold standard action keys and [One Shot modifier](one_shot_keys.md) keys (for example, if you have your Shift defined as `OSM(KC_LSFT)`).
This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as `KC_LPRN`. If it's in the [Basic Keycodes](keycodes_basic.md) list, it can be held.
Switching layers will not cancel the Key Lock.

93
feature_layers.md Normal file
View File

@ -0,0 +1,93 @@
# Layers :id=layers
One of the most powerful and well used features of QMK Firmware is the ability to use layers. For most people, this amounts to a function key that allows for different keys, much like what you would see on a laptop or tablet keyboard.
For a detailed explanation of how the layer stack works, checkout [Keymap Overview](keymap.md#keymap-and-layers).
## Switching and Toggling Layers :id=switching-and-toggling-layers
These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated.
* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`.
* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](one_shot_keys.md) for details and additional functionality.
* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
### Caveats :id=caveats
Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Specifically, dual function keys like `LT` and `MT` use a 16 bit keycode. 4 bits are used for the function identifier, the next 12 are divided into the parameters. Layer Tap uses 4 bits for the layer (and is why it's limited to layers 0-15, actually), while Mod Tap does the same, 4 bits for the identifier, 4 bits for which mods are used, and all of them use 8 bits for the keycode. Because of this, the keycode used is limited to `0xFF` (0-255), which are the basic keycodes only.
Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.
Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two.
## Working with Layers :id=working-with-layers
Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
### Beginners :id=beginners
If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number).
* Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
* In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
### Intermediate Users :id=intermediate-users
Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
### Advanced Users :id=advanced-users
Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
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).
## Functions :id=functions
There are a number of functions (and variables) related to how you can use or manipulate the layers.
|Function |Description |
|----------------------------------------------|---------------------------------------------------------------------------------------------------------|
| `layer_state_set(layer_mask)` | Directly sets the layer state (recommended, do not use unless you know what you are doing). |
| `layer_clear()` | Clears all layers (turns them all off). |
| `layer_move(layer)` | Turns specified layer on, and all other layers off. |
| `layer_on(layer)` | Turns specified layer on, leaves all other layers in existing state. |
| `layer_off(layer)` | Turns specified layer off, leaves all other layers in existing state. |
| `layer_invert(layer)` | Interverts/toggles the state of the specified layer |
| `layer_or(layer_mask)` | Turns on layers based on matching bits between specifed layer and existing layer state. |
| `layer_and(layer_mask)` | Turns on layers based on matching enabled bits between specifed layer and existing layer state. |
| `layer_xor(layer_mask)` | Turns on layers based on non-matching bits between specifed layer and existing layer state. |
| `layer_debug(layer_mask)` | Prints out the current bit mask and highest active layer to debugger console. |
| `default_layer_set(layer_mask)` | Directly sets the default layer state (recommended, do not use unless you know what you are doing). |
| `default_layer_or(layer_mask)` | Turns on layers based on matching bits between specifed layer and existing default layer state. |
| `default_layer_and(layer_mask)` | Turns on layers based on matching enabled bits between specifed layer and existing default layer state. |
| `default_layer_xor(layer_mask)` | Turns on layers based on non-matching bits between specifed layer and existing default layer state. |
| `default_layer_debug(layer_mask)` | Prints out the current bit mask and highest active default layer to debugger console. |
| [`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) | Sets the default layer and writes it to persistent memory (EEPROM). |
| [`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z) | Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off). |
| [`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z) | Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions. |
In addition to the functions that you can call, there are a number of callback functions that get called every time the layer changes. This passes the layer state to the function, where it can be read or modified.
|Callback |Description |
|-----------------------------------------------------|----------------------------------------------------------------------------------------|
| `layer_state_set_kb(layer_state_t state)` | Callback for layer functions, for keyboard. |
| `layer_state_set_user(layer_state_t state)` | Callback for layer functions, for users. |
| `default_layer_state_set_kb(layer_state_t state)` | Callback for default layer functions, for keyboard. Called on keyboard initialization. |
| `default_layer_state_set_user(layer_state_t state)` | Callback for default layer functions, for users. Called on keyboard initialization. |
?> For additional details on how you can use these callbacks, check out the [Layer Change Code](custom_quantum_functions.md#layer-change-code) document.
It is also possible to check the state of a particular layer using the following functions and macros.
|Function |Description |Aliases
|---------------------------------|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| `layer_state_is(layer)` | Checks if the specified `layer` is enabled globally. | `IS_LAYER_ON(layer)`, `IS_LAYER_OFF(layer)` |
| `layer_state_cmp(state, layer)` | Checks `state` to see if the specified `layer` is enabled. Intended for use in layer callbacks. | `IS_LAYER_ON_STATE(state, layer)`, `IS_LAYER_OFF_STATE(state, layer)` |

109
feature_layouts.md Normal file
View File

@ -0,0 +1,109 @@
# Layouts: Using a Keymap with Multiple Keyboards
The `layouts/` folder contains different physical key layouts that can apply to different keyboards.
```
layouts/
+ default/
| + 60_ansi/
| | + readme.md
| | + layout.json
| | + a_good_keymap/
| | | + keymap.c
| | | + readme.md
| | | + config.h
| | | + rules.mk
| | + <keymap folder>/
| | + ...
| + <layout folder>/
+ community/
| + <layout folder>/
| + ...
```
The `layouts/default/` and `layouts/community/` are two examples of layout "repositories" - currently `default` will contain all of the information concerning the layout, and one default keymap named `default_<layout>`, for users to use as a reference. `community` contains all of the community keymaps, with the eventual goal of being split-off into a separate repo for users to clone into `layouts/`. QMK searches through all folders in `layouts/`, so it's possible to have multiple repositories here.
Each layout folder is named (`[a-z0-9_]`) after the physical aspects of the layout, in the most generic way possible, and contains a `readme.md` with the layout to be defined by the keyboard:
```md
# 60_ansi
LAYOUT_60_ansi
```
New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.
## Supporting a Layout
For a keyboard to support a layout, the variable must be defined in it's `<keyboard>.h`, and match the number of arguments/keys (and preferably the physical layout):
#define LAYOUT_60_ansi KEYMAP_ANSI
The name of the layout must match this regex: `[a-z0-9_]+`
The folder name must be added to the keyboard's `rules.mk`:
LAYOUTS = 60_ansi
`LAYOUTS` can be set in any keyboard folder level's `rules.mk`:
LAYOUTS = 60_iso
but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
## Building a Keymap
You should be able to build the keyboard keymap with a command in this format:
make <keyboard>:<layout>
### Conflicting layouts
When a keyboard supports multiple layout options,
LAYOUTS = ortho_4x4 ortho_4x12
And a layout exists for both options,
```
layouts/
+ community/
| + ortho_4x4/
| | + <layout>/
| | | + ...
| + ortho_4x12/
| | + <layout>/
| | | + ...
| + ...
```
The FORCE_LAYOUT argument can be used to specify which layout to build
make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
## Tips for Making Layouts Keyboard-Agnostic
### Includes
Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<folder>.h` should not be included here) file that is being compiled:
#include QMK_KEYBOARD_H
If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement:
* `KEYBOARD_<folder1>_<folder2>`
For example:
```c
#ifdef KEYBOARD_planck
#ifdef KEYBOARD_planck_rev4
planck_rev4_function();
#endif
#endif
```
Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.
### Keymaps
In order to support both split and non-split keyboards with the same layout, you need to use the keyboard agnostic `LAYOUT_<layout name>` macro in your keymap. For instance, in order for a Let's Split and Planck to share the same layout file, you need to use `LAYOUT_ortho_4x12` instead of `LAYOUT_planck_grid` or just `{}` for a C array.

146
feature_leader_key.md Normal file
View File

@ -0,0 +1,146 @@
# The Leader Key: A New Kind of Modifier
If you've ever used Vim, you know what a Leader key is. If not, you're about to discover a wonderful concept. :) Instead of hitting Alt+Shift+W for example (holding down three keys at the same time), what if you could hit a _sequence_ of keys instead? So you'd hit our special modifier (the Leader key), followed by W and then C (just a rapid succession of keys), and something would happen.
That's what `KC_LEAD` does. Here's an example:
1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else.
2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key. Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence. The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low.
* By default, this timeout is how long after pressing `KC_LEAD` to complete your entire sequence. This may be very low for some people. So you may want to increase this timeout. Optionally, you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped. This allows you to maintain a low value here, but still be able to use the longer sequences. To enable this option, add `#define LEADER_PER_KEY_TIMING` to your `config.h`.
3. Within your `matrix_scan_user` function, add something like this:
```c
LEADER_EXTERNS();
void matrix_scan_user(void) {
LEADER_DICTIONARY() {
leading = false;
leader_end();
SEQ_ONE_KEY(KC_F) {
// Anything you can do in a macro.
SEND_STRING("QMK is awesome.");
}
SEQ_TWO_KEYS(KC_D, KC_D) {
SEND_STRING(SS_LCTL("a") SS_LCTL("c"));
}
SEQ_THREE_KEYS(KC_D, KC_D, KC_S) {
SEND_STRING("https://start.duckduckgo.com\n");
}
SEQ_TWO_KEYS(KC_A, KC_S) {
register_code(KC_LGUI);
register_code(KC_S);
unregister_code(KC_S);
unregister_code(KC_LGUI);
}
}
}
```
As you can see, you have a few function. You can use `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS`, `SEQ_THREE_KEYS` up to `SEQ_FIVE_KEYS` for longer sequences.
Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously.
## Adding Leader Key Support in the `rules.mk`
To add support for Leader Key you simply need to add a single line to your keymap's `rules.mk`:
```make
LEADER_ENABLE = yes
```
## Per Key Timing on Leader keys
Rather than relying on an incredibly high timeout for long leader key strings or those of us without 200wpm typing skills, we can enable per key timing to ensure that each key pressed provides us with more time to finish our stroke. This is incredibly helpful with leader key emulation of tap dance (read: multiple taps of the same key like C, C, C).
In order to enable this, place this in your `config.h`:
```c
#define LEADER_PER_KEY_TIMING
```
After this, it's recommended that you lower your `LEADER_TIMEOUT` to something less that 300ms.
```c
#define LEADER_TIMEOUT 250
```
Now, something like this won't seem impossible to do without a 1000MS leader key timeout:
```c
SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
SEND_STRING("Per key timing is great!!!");
}
```
## Strict Key Processing
By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](mod_tap.md) and [`Layer Tap`](feature_layers.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file. This will then disable the filtering, and you'll need to specify the whole keycode.
## Customization
The Leader Key feature has some additional customization to how the Leader Key feature works. It has two functions that can be called at certain parts of the process. Namely `leader_start()` and `leader_end()`.
The `leader_start()` function is called when you tap the `KC_LEAD` key, and the `leader_end()` function is called when either the leader sequence is completed, or the leader timeout is hit.
You can add these functions to your code (`keymap.c` usually) to add feedback to the Leader sequences (such as beeping or playing music).
```c
void leader_start(void) {
// sequence started
}
void leader_end(void) {
// sequence ended (no success/failuer detection)
}
```
### Example
This example will play the Mario "One Up" sound when you hit `KC_LEAD` to start the Leader Sequence, and will play "All Star" if it completes successfully or "Rick Roll" you if it fails.
```c
bool did_leader_succeed;
#ifdef AUDIO_ENABLE
float leader_start[][2] = SONG(ONE_UP_SOUND );
float leader_succeed[][2] = SONG(ALL_STAR);
float leader_fail[][2] = SONG(RICK_ROLL);
#endif
LEADER_EXTERNS();
void matrix_scan_user(void) {
LEADER_DICTIONARY() {
did_leader_succeed = leading = false;
SEQ_ONE_KEY(KC_E) {
// Anything you can do in a macro.
SEND_STRING(SS_LCTL(SS_LSFT("t")));
did_leader_succeed = true;
} else
SEQ_TWO_KEYS(KC_E, KC_D) {
SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c"));
did_leader_succeed = true;
}
leader_end();
}
}
void leader_start(void) {
#ifdef AUDIO_ENABLE
PLAY_SONG(leader_start);
#endif
}
void leader_end(void) {
if (did_leader_succeed) {
#ifdef AUDIO_ENABLE
PLAY_SONG(leader_succeed);
#endif
} else {
#ifdef AUDIO_ENABLE
PLAY_SONG(leader_fail);
#endif
}
}
```

116
feature_led_indicators.md Normal file
View File

@ -0,0 +1,116 @@
# LED Indicators
QMK provides methods to read 5 of the LEDs defined in the HID spec:
* Num Lock
* Caps Lock
* Scroll Lock
* Compose
* Kana
There are three ways to get the lock LED state:
* by specifying configuration options within `config.h`
* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or
* by calling `led_t host_keyboard_led_state()`
!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
Two more deprecated functions exist that provide the LED state as a `uint8_t`:
* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
* `uint8_t host_keyboard_leds()`
## Configuration Options
To configure the indicators, `#define` these in your `config.h`:
|Define |Default |Description |
|---------------------|-------------|-------------------------------------------|
|`LED_NUM_LOCK_PIN` |*Not defined*|The pin that controls the `Num Lock` LED |
|`LED_CAPS_LOCK_PIN` |*Not defined*|The pin that controls the `Caps Lock` LED |
|`LED_SCROLL_LOCK_PIN`|*Not defined*|The pin that controls the `Scroll Lock` LED|
|`LED_COMPOSE_PIN` |*Not defined*|The pin that controls the `Compose` LED |
|`LED_KANA_PIN` |*Not defined*|The pin that controls the `Kana` LED |
|`LED_PIN_ON_STATE` |`1` |The state of the indicator pins when the LED is "on" - `1` for high, `0` for low|
Unless you are designing your own keyboard, you generally should not need to change the above config options.
## `led_update_*()`
When the configuration options do not provide enough flexibility, the API hooks provided allow custom control of the LED behavior. These functions will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and
return `false` when you would prefer not to run the code in `led_update_kb()`.
Some examples include:
- overriding the LEDs to use them for something else like layer indication
- return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior.
- play a sound when an LED turns on or off.
- return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior.
?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead.
### Example `led_update_kb()` Implementation
```c
bool led_update_kb(led_t led_state) {
bool res = led_update_user(led_state);
if(res) {
// writePin sets the pin high for 1 and low for 0.
// In this example the pins are inverted, setting
// it low/0 turns it on, and high/1 turns the LED off.
// This behavior depends on whether the LED is between the pin
// and VCC or the pin and GND.
writePin(B0, !led_state.num_lock);
writePin(B1, !led_state.caps_lock);
writePin(B2, !led_state.scroll_lock);
writePin(B3, !led_state.compose);
writePin(B4, !led_state.kana);
}
return res;
}
```
### Example `led_update_user()` Implementation
This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state.
```c
#ifdef AUDIO_ENABLE
float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
#endif
bool led_update_user(led_t led_state) {
#ifdef AUDIO_ENABLE
static uint8_t caps_state = 0;
if (caps_state != led_state.caps_lock) {
led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
caps_state = led_state.caps_lock;
}
#endif
return true;
}
```
### `led_update_*` Function Documentation
* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
* Keymap: `bool led_update_user(led_t led_state)`
## `host_keyboard_led_state()`
Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
## Setting Physical LED State
Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
### Ergodox Boards
The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index.
In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`.
Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default).

90
feature_led_matrix.md Normal file
View File

@ -0,0 +1,90 @@
# LED Matrix Lighting
This feature allows you to use LED matrices driven by external drivers. It hooks into the backlight system so you can use the same keycodes as backlighting to control it.
If you want to use RGB LED's you should use the [RGB Matrix Subsystem](feature_rgb_matrix.md) instead.
## Driver configuration
### IS31FL3731
There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
LED_MATRIX_ENABLE = IS31FL3731
You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`:
| Variable | Description | Default |
|----------|-------------|---------|
| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages | 100 |
| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
| `LED_DRIVER_COUNT` | (Required) How many LED driver IC's are present | |
| `LED_DRIVER_LED_COUNT` | (Required) How many LED lights are present across all drivers | |
| `LED_DRIVER_ADDR_1` | (Required) Address for the first LED driver | |
| `LED_DRIVER_ADDR_2` | (Optional) Address for the second LED driver | |
| `LED_DRIVER_ADDR_3` | (Optional) Address for the third LED driver | |
| `LED_DRIVER_ADDR_4` | (Optional) Address for the fourth LED driver | |
Here is an example using 2 drivers.
// This is a 7-bit address, that gets left-shifted and bit 0
// set to 0 for write, 1 for read (as per I2C protocol)
// The address will vary depending on your wiring:
// 0b1110100 AD <-> GND
// 0b1110111 AD <-> VCC
// 0b1110101 AD <-> SCL
// 0b1110110 AD <-> SDA
#define LED_DRIVER_ADDR_1 0b1110100
#define LED_DRIVER_ADDR_2 0b1110110
#define LED_DRIVER_COUNT 2
#define LED_DRIVER_1_LED_COUNT 25
#define LED_DRIVER_2_LED_COUNT 24
#define LED_DRIVER_LED_COUNT LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | LED address
* | | */
{0, C3_3},
....
}
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ).
## Keycodes
All LED matrix keycodes are currently shared with the [backlight system](feature_backlight.md).
## LED Matrix Effects
Currently no LED matrix effects have been created.
## Custom layer effects
Custom layer effects can be done by defining this in your `<keyboard>.c`:
void led_matrix_indicators_kb(void) {
led_matrix_set_index_value(index, value);
}
A similar function works in the keymap as `led_matrix_indicators_user`.
## Suspended state
To use the suspend feature, add this to your `<keyboard>.c`:
void suspend_power_down_kb(void)
{
led_matrix_set_suspend_state(true);
}
void suspend_wakeup_init_kb(void)
{
led_matrix_set_suspend_state(false);
}

397
feature_macros.md Normal file
View File

@ -0,0 +1,397 @@
# Macros
Macros allow you to send multiple keystrokes when pressing just one key. QMK has a number of ways to define and use macros. These can do anything you want: type common phrases for you, copypasta, repetitive game movements, or even help you code.
!> **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.
## The New Way: `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`).
Here is an example `keymap.c` for a two-key keyboard:
```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{QMKBEST, KC_ESC},
// ...
},
};
```
What happens here is this:
We first define a new custom keycode in the range not occupied by any other keycodes.
Then we use the `process_record_user` function, which is called whenever a key is pressed or released, to check if our custom keycode has been activated.
If yes, we send the string `"QMK is the best thing ever!"` to the computer via the `SEND_STRING` macro (this is a C preprocessor macro, not to be confused with QMK macros).
We return `true` to indicate to the caller that the key press we just processed should continue to be processed as normal (as we didn't replace or alter the functionality).
Finally, we define the keymap so that the first button activates our macro and the second button is just an escape button.
You might want to add more than one macro.
You can do that by adding another keycode and adding another case to the switch statement, like so:
```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
QMKURL,
MY_OTHER_MACRO,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
case QMKURL:
if (record->event.pressed) {
// when keycode QMKURL is pressed
SEND_STRING("https://qmk.fm/\n");
} else {
// when keycode QMKURL is released
}
break;
case MY_OTHER_MACRO:
if (record->event.pressed) {
SEND_STRING(SS_LCTL("ac")); // selects all and copies
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO},
// ...
},
};
```
### 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.
In this example, we modify most normal keypresses so that `F22` is pressed before the keystroke is normally sent, and release it __only after__ it's been released.
```c
static uint8_t f22_tracker;
bool 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
if (record->event.pressed) {
register_code(KC_F22); //this means to send F22 down
f22_tracker++;
register_code(keycode);
return false;
}
break;
}
return true;
}
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
if (!record->event.pressed) {
f22_tracker--;
if (!f22_tracker) {
unregister_code(KC_F22); //this means to send F22 up
}
}
break;
}
}
```
### 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:
* `SS_TAP()` presses and releases a key.
* `SS_DOWN()` presses (but does not release) a key.
* `SS_UP()` releases a key.
For example:
SEND_STRING(SS_TAP(X_HOME));
Would tap `KC_HOME` - note how the prefix is now `X_`, and not `KC_`. You can also combine this with other strings, like this:
SEND_STRING("VE"SS_TAP(X_HOME)"LO");
Which would send "VE" followed by a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline).
Delays can be also added to the string:
* `SS_DELAY(msecs)` will delay for the specified number of milliseconds.
For example:
SEND_STRING("VE" SS_DELAY(1000) SS_TAP(X_HOME) "LO");
Which would send "VE" followed by a 1-second delay, then a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline, but delayed in the middle).
There's also a couple of mod shortcuts you can use:
* `SS_LCTL(string)`
* `SS_LSFT(string)`
* `SS_LALT(string)` or `SS_LOPT(string)`
* `SS_LGUI(string)`, `SS_LCMD(string)` or `SS_LWIN(string)`
* `SS_RCTL(string)`
* `SS_RSFT(string)`
* `SS_RALT(string)`, `SS_ROPT(string)` or `SS_ALGR(string)`
* `SS_RGUI(string)`, `SS_RCMD(string)` or `SS_RWIN(string)`
These press the respective modifier, send the supplied string and then release the modifier.
They can be used like this:
SEND_STRING(SS_LCTL("a"));
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
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:
#include <sendstring_colemak.h>
### 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:
```c
char my_str[4] = "ok.";
send_string(my_str);
```
The shortcuts defined above won't work with `send_string()`, but you can separate things out to different lines if needed:
```c
char my_str[4] = "ok.";
SEND_STRING("I said: ");
send_string(my_str);
SEND_STRING(".."SS_TAP(X_END));
```
## 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) for additional functionality. For example `reset_keyboard()` allows you to reset the keyboard as part of a macro.
### `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
```c
if (record->event.pressed) {
// on keydown
} else {
// on keyup
}
```
### `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>);`
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>);`
This will send `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).
If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
### `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();`
This will clear all mods and keys currently pressed.
### `clear_mods();`
This will clear all mods currently pressed.
### `clear_keyboard_but_mods();`
This will clear all keys besides the mods currently pressed.
## Advanced Example:
### 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.
```c
bool is_alt_tab_active = false; # ADD this near the begining of keymap.c
uint16_t alt_tab_timer = 0; # we will be using them soon.
enum custom_keycodes { # Make sure have the awesome keycode ready
ALT_TAB = SAFE_RANGE,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) { # This will do most of the grunt work with the keycodes.
case ALT_TAB:
if (record->event.pressed) {
if (!is_alt_tab_active) {
is_alt_tab_active = true;
register_code(KC_LALT);
}
alt_tab_timer = timer_read();
register_code(KC_TAB);
} else {
unregister_code(KC_TAB);
}
break;
}
return true;
}
void matrix_scan_user(void) { # The very important timer.
if (is_alt_tab_active) {
if (timer_elapsed(alt_tab_timer) > 1000) {
unregister_code(KC_LALT);
is_alt_tab_active = false;
}
}
}
```
---
## **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro`
!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead.
By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
```c
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
};
```
This defines two macros which will be run when the key they are assigned to is pressed. If instead you'd like them to run when the key is released you can change the if statement:
if (!record->event.pressed) {
### Macro Commands
A macro can include the following commands:
* I() change interval of stroke in milliseconds.
* D() press key.
* U() release key.
* T() type key(press and release).
* W() wait (milliseconds).
* END end mark.
### Mapping a Macro to a Key
Use the `M()` function within your keymap to call a macro. For example, here is the keymap for a 2-key keyboard:
```c
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT(
M(0), M(1)
),
};
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
};
```
When you press the key on the left it will type "Hi!" and when you press the key on the right it will type "Bye!".
### Naming Your Macros
If you have a bunch of macros you want to refer to from your keymap while keeping the keymap easily readable you can name them using `#define` at the top of your file.
```c
#define M_HI M(0)
#define M_BYE M(1)
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT(
M_HI, M_BYE
),
};
```
## Advanced Example:
### Single-Key Copy/Paste
This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.
```c
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
switch(id) {
case 0: {
if (record->event.pressed) {
return MACRO( D(LCTL), T(C), U(LCTL), END );
} else {
return MACRO( D(LCTL), T(V), U(LCTL), END );
}
break;
}
}
return MACRO_NONE;
};
```

142
feature_mouse_keys.md Normal file
View File

@ -0,0 +1,142 @@
# Mouse keys
Mouse keys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer at different speeds, press 5 buttons and scroll in 8 directions.
## Adding mouse keys to your keyboard
To use mouse keys, you must at least enable mouse keys support and map mouse actions to keys on your keyboard.
### Enabling mouse keys
To enable mouse keys, add the following line to your keymap’s `rules.mk`:
```c
MOUSEKEY_ENABLE = yes
```
### Mapping mouse actions
In your keymap you can use the following keycodes to map key presses to mouse actions:
|Key |Aliases |Description |
|----------------|---------|-----------------|
|`KC_MS_UP` |`KC_MS_U`|Move cursor up |
|`KC_MS_DOWN` |`KC_MS_D`|Move cursor down |
|`KC_MS_LEFT` |`KC_MS_L`|Move cursor left |
|`KC_MS_RIGHT` |`KC_MS_R`|Move cursor right|
|`KC_MS_BTN1` |`KC_BTN1`|Press button 1 |
|`KC_MS_BTN2` |`KC_BTN2`|Press button 2 |
|`KC_MS_BTN3` |`KC_BTN3`|Press button 3 |
|`KC_MS_BTN4` |`KC_BTN4`|Press button 4 |
|`KC_MS_BTN5` |`KC_BTN5`|Press button 5 |
|`KC_MS_WH_UP` |`KC_WH_U`|Move wheel up |
|`KC_MS_WH_DOWN` |`KC_WH_D`|Move wheel down |
|`KC_MS_WH_LEFT` |`KC_WH_L`|Move wheel left |
|`KC_MS_WH_RIGHT`|`KC_WH_R`|Move wheel right |
|`KC_MS_ACCEL0` |`KC_ACL0`|Set speed to 0 |
|`KC_MS_ACCEL1` |`KC_ACL1`|Set speed to 1 |
|`KC_MS_ACCEL2` |`KC_ACL2`|Set speed to 2 |
## Configuring mouse keys
Mouse keys supports three different modes to move the cursor:
* **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed.
* **Constant:** Holding movement keys moves the cursor at constant speeds.
* **Combined:** Holding movement keys accelerates the cursor until it reaches its maximum speed, but holding acceleration and movement keys simultaneously moves the cursor at constant speeds.
The same principle applies to scrolling.
Configuration options that are times, intervals or delays are given in milliseconds. Scroll speed is given as multiples of the default scroll step. For example, a scroll speed of 8 means that each scroll action covers 8 times the length of the default scroll step as defined by your operating system or application.
### Accelerated mode
This is the default mode. You can adjust the cursor and scrolling acceleration using the following settings in your keymap’s `config.h` file:
|Define |Default|Description |
|----------------------------|-------|---------------------------------------------------------|
|`MOUSEKEY_DELAY` |300 |Delay between pressing a movement key and cursor movement|
|`MOUSEKEY_INTERVAL` |50 |Time between cursor movements |
|`MOUSEKEY_MAX_SPEED` |10 |Maximum cursor speed at which acceleration stops |
|`MOUSEKEY_TIME_TO_MAX` |20 |Time until maximum cursor speed is reached |
|`MOUSEKEY_WHEEL_DELAY` |300 |Delay between pressing a wheel key and wheel movement |
|`MOUSEKEY_WHEEL_INTERVAL` |100 |Time between wheel movements |
|`MOUSEKEY_WHEEL_MAX_SPEED` |8 |Maximum number of scroll steps per scroll action |
|`MOUSEKEY_WHEEL_TIME_TO_MAX`|40 |Time until maximum scroll speed is reached |
Tips:
* Setting `MOUSEKEY_DELAY` too low makes the cursor unresponsive. Setting it too high makes small movements difficult.
* For smoother cursor movements, lower the value of `MOUSEKEY_INTERVAL`. If the refresh rate of your display is 60Hz, you could set it to `16` (1/60). As this raises the cursor speed significantly, you may want to lower `MOUSEKEY_MAX_SPEED`.
* Setting `MOUSEKEY_TIME_TO_MAX` or `MOUSEKEY_WHEEL_TIME_TO_MAX` to `0` will disable acceleration for the cursor or scrolling respectively. This way you can make one of them constant while keeping the other accelerated, which is not possible in constant speed mode.
* Setting `MOUSEKEY_WHEEL_INTERVAL` too low will make scrolling too fast. Setting it too high will make scrolling too slow when the wheel key is held down.
Cursor acceleration uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys).
### Constant mode
In this mode you can define multiple different speeds for both the cursor and the mouse wheel. There is no acceleration. `KC_ACL0`, `KC_ACL1` and `KC_ACL2` change the cursor and scroll speed to their respective setting.
You can choose whether speed selection is momentary or tap-to-select:
* **Momentary:** The chosen speed is only active while you hold the respective key. When the key is raised, mouse keys returns to the unmodified speed.
* **Tap-to-select:** The chosen speed is activated when you press the respective key and remains active even after the key has been raised. The default speed is that of `KC_ACL1`. There is no unmodified speed.
The default speeds from slowest to fastest are as follows:
* **Momentary:** `KC_ACL0` < `KC_ACL1` < *unmodified* < `KC_ACL2`
* **Tap-to-select:** `KC_ACL0` < `KC_ACL1` < `KC_ACL2`
To use constant speed mode, you must at least define `MK_3_SPEED` in your keymap’s `config.h` file:
```c
#define MK_3_SPEED
```
To enable momentary mode, also define `MK_MOMENTARY_ACCEL`:
```c
#define MK_MOMENTARY_ACCEL
```
Use the following settings if you want to adjust cursor movement or scrolling:
|Define |Default |Description |
|---------------------|-------------|-------------------------------------------|
|`MK_3_SPEED` |*Not defined*|Enable constant cursor speeds |
|`MK_MOMENTARY_ACCEL` |*Not defined*|Enable momentary speed selection |
|`MK_C_OFFSET_UNMOD` |16 |Cursor offset per movement (unmodified) |
|`MK_C_INTERVAL_UNMOD`|16 |Time between cursor movements (unmodified) |
|`MK_C_OFFSET_0` |1 |Cursor offset per movement (`KC_ACL0`) |
|`MK_C_INTERVAL_0` |32 |Time between cursor movements (`KC_ACL0`) |
|`MK_C_OFFSET_1` |4 |Cursor offset per movement (`KC_ACL1`) |
|`MK_C_INTERVAL_1` |16 |Time between cursor movements (`KC_ACL1`) |
|`MK_C_OFFSET_2` |32 |Cursor offset per movement (`KC_ACL2`) |
|`MK_C_INTERVAL_2` |16 |Time between cursor movements (`KC_ACL2`) |
|`MK_W_OFFSET_UNMOD` |1 |Scroll steps per scroll action (unmodified)|
|`MK_W_INTERVAL_UNMOD`|40 |Time between scroll steps (unmodified) |
|`MK_W_OFFSET_0` |1 |Scroll steps per scroll action (`KC_ACL0`) |
|`MK_W_INTERVAL_0` |360 |Time between scroll steps (`KC_ACL0`) |
|`MK_W_OFFSET_1` |1 |Scroll steps per scroll action (`KC_ACL1`) |
|`MK_W_INTERVAL_1` |120 |Time between scroll steps (`KC_ACL1`) |
|`MK_W_OFFSET_2` |1 |Scroll steps per scroll action (`KC_ACL2`) |
|`MK_W_INTERVAL_2` |20 |Time between scroll steps (`KC_ACL2`) |
### Combined mode
This mode functions like **Accelerated** mode, however, you can hold `KC_ACL0`, `KC_ACL1` and `KC_ACL2`
to momentarily (while held) set the cursor and scroll speeds to constant speeds. When no acceleration
keys are held, this mode is identical to **Accelerated** mode, and can be modified using all of the
relevant settings.
* **KC_ACL0:** This acceleration sets your cursor to the slowest possible speed. This is useful for very
small and detailed movements of the cursor.
* **KC_ACL1:** This acceleration sets your cursor to half the maximum (user defined) speed.
* **KC_ACL2:** This acceleration sets your cursor to the maximum (computer defined) speed. This is
useful for moving the cursor large distances without much accuracy.
To use constant speed mode, you must at least define `MK_COMBINED` in your keymap’s `config.h` file:
```c
#define MK_COMBINED
```

377
feature_oled_driver.md Normal file
View File

@ -0,0 +1,377 @@
# OLED Driver
## Supported Hardware
OLED modules using SSD1306 or SH1106 driver ICs, communicating over I2C.
Tested combinations:
|IC |Size |Platform|Notes |
|---------|------|--------|------------------------|
|SSD1306 |128x32|AVR |Primary support |
|SSD1306 |128x64|AVR |Verified working |
|SSD1306 |128x32|Arm | |
|SH1106 |128x64|AVR |No rotation or scrolling|
Hardware configurations using Arm-based microcontrollers or different sizes of OLED modules may be compatible, but are untested.
!> Warning: This OLED driver currently uses the new i2c_master driver from Split Common code. If your split keyboard uses I2C to communicate between sides, this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest Split Common code to fix this. In addition, the display timeout system to reduce OLED burn-in also uses Split Common to detect keypresses, so you will need to implement custom timeout logic for non-Split Common keyboards.
## Usage
To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to add the following to your `rules.mk`:
```make
OLED_DRIVER_ENABLE = yes
```
Then in your `keymap.c` file, implement the OLED task call. This example assumes your keymap has three layers named `_QWERTY`, `_FN` and `_ADJ`:
```c
#ifdef OLED_DRIVER_ENABLE
void oled_task_user(void) {
// Host Keyboard Layer Status
oled_write_P(PSTR("Layer: "), false);
switch (get_highest_layer(layer_state)) {
case _QWERTY:
oled_write_P(PSTR("Default\n"), false);
break;
case _FN:
oled_write_P(PSTR("FN\n"), false);
break;
case _ADJ:
oled_write_P(PSTR("ADJ\n"), false);
break;
default:
// Or use the write_ln shortcut over adding '\n' to the end of your string
oled_write_ln_P(PSTR("Undefined"), false);
}
// Host Keyboard LED Status
led_t led_state = host_keyboard_led_state();
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);
}
#endif
```
## Logo Example
In the default font, certain ranges of characters are reserved for a QMK logo. To render this logo to the OLED screen, use the following code example:
```c
static void render_logo(void) {
static const char PROGMEM qmk_logo[] = {
0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x8B, 0x8C, 0x8D, 0x8E, 0x8F, 0x90, 0x91, 0x92, 0x93, 0x94,
0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xAB, 0xAC, 0xAD, 0xAE, 0xAF, 0xB0, 0xB1, 0xB2, 0xB3, 0xB4,
0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF, 0xD0, 0xD1, 0xD2, 0xD3, 0xD4, 0x00
};
oled_write_P(qmk_logo, false);
}
```
## Buffer Read Example
For some purposes, you may need to read the current state of the OLED display
buffer. The `oled_read_raw` function can be used to safely read bytes from the
buffer.
In this example, calling `fade_display` in the `oled_task_user` function will
slowly fade away whatever is on the screen by turning random pixels black over
time.
```c
//Setup some mask which can be or'd with bytes to turn off pixels
const uint8_t single_bit_masks[8] = {127, 191, 223, 239, 247, 251, 253, 254};
static void fade_display(void) {
//Define the reader structure
oled_buffer_reader_t reader;
uint8_t buff_char;
if (random() % 30 == 0) {
srand(timer_read());
// Fetch a pointer for the buffer byte at index 0. The return structure
// will have the pointer and the number of bytes remaining from this
// index position if we want to perform a sequential read by
// incrementing the buffer pointer
reader = oled_read_raw(0);
//Loop over the remaining buffer and erase pixels as we go
for (uint16_t i = 0; i < reader.remaining_element_count; i++) {
//Get the actual byte in the buffer by dereferencing the pointer
buff_char = *reader.current_element;
if (buff_char != 0) {
oled_write_raw_byte(buff_char & single_bit_masks[rand() % 8], i);
}
//increment the pointer to fetch a new byte during the next loop
reader.current_element++;
}
}
}
```
## Other Examples
In split keyboards, it is very common to have two OLED displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
```c
#ifdef OLED_DRIVER_ENABLE
oled_rotation_t oled_init_user(oled_rotation_t rotation) {
if (!is_keyboard_master()) {
return OLED_ROTATION_180; // flips the display 180 degrees if offhand
}
return rotation;
}
void 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
}
}
#endif
```
## Basic Configuration
|Define |Default |Description |
|---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------|
|`OLED_DISPLAY_ADDRESS` |`0x3C` |The i2c address of the OLED Display |
|`OLED_FONT_H` |`"glcdfont.c"` |The font code file to use for custom fonts |
|`OLED_FONT_START` |`0` |The starting character index for custom fonts |
|`OLED_FONT_END` |`223` |The ending character index for custom fonts |
|`OLED_FONT_WIDTH` |`6` |The font width |
|`OLED_FONT_HEIGHT` |`8` |The font height (untested) |
|`OLED_TIMEOUT` |`60000` |Turns off the OLED screen after 60000ms of keyboard inactivity. Helps reduce OLED Burn-in. Set to 0 to disable. |
|`OLED_SCROLL_TIMEOUT` |`0` |Scrolls the OLED screen after 0ms of OLED inactivity. Helps reduce OLED Burn-in. Set to 0 to disable. |
|`OLED_SCROLL_TIMEOUT_RIGHT`|*Not defined* |Scroll timeout direction is right when defined, left when undefined. |
|`OLED_IC` |`OLED_IC_SSD1306`|Set to `OLED_IC_SH1106` if you're using the SH1106 OLED controller. |
|`OLED_COLUMN_OFFSET` |`0` |(SH1106 only.) Shift output to the right this many pixels.<br />Useful for 128x64 displays centered on a 132x64 SH1106 IC.|
|`OLED_BRIGHTNESS` |`255` |The default brightness level of the OLED, from 0 to 255. |
## 128x64 & Custom sized OLED Displays
The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind. We have added a define, `OLED_DISPLAY_128X64`, to switch all the values to be used in a 128x64 display, as well as added a custom define, `OLED_DISPLAY_CUSTOM`, that allows you to provide the necessary values to the driver.
|Define |Default |Description |
|---------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------|
|`OLED_DISPLAY_128X64`|*Not defined* |Changes the display defines for use with 128x64 displays. |
|`OLED_DISPLAY_CUSTOM`|*Not defined* |Changes the display defines for use with custom displays.<br>Requires user to implement the below defines. |
|`OLED_DISPLAY_WIDTH` |`128` |The width of the OLED display. |
|`OLED_DISPLAY_HEIGHT`|`32` |The height of the OLED display. |
|`OLED_MATRIX_SIZE` |`512` |The local buffer size to allocate.<br>`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`. |
|`OLED_BLOCK_TYPE` |`uint16_t` |The unsigned integer type to use for dirty rendering. |
|`OLED_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.<br>`(sizeof(OLED_BLOCK_TYPE) * 8)`. |
|`OLED_BLOCK_SIZE` |`32` |The size of each block for dirty rendering<br>`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`. |
|`OLED_COM_PINS` |`COM_PINS_SEQ` |How the SSD1306 chip maps it's memory to display.<br>Options are `COM_PINS_SEQ`, `COM_PINS_ALT`, `COM_PINS_SEQ_LR`, & `COM_PINS_ALT_LR`.|
|`OLED_SOURCE_MAP` |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering. |
|`OLED_TARGET_MAP` |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering. |
### 90 Degree Rotation - Technical Mumbo Jumbo
!> Rotation is unsupported on the SH1106.
```c
// OLED Rotation enum values are flags
typedef enum {
OLED_ROTATION_0 = 0,
OLED_ROTATION_90 = 1,
OLED_ROTATION_180 = 2,
OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
} oled_rotation_t;
```
OLED displays driven by SSD1306 drivers only natively support in hardware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an ATmega32U4 board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms.
90 degree rotation is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the display height, width, and block size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g:
| | | | | | |
|---|---|---|---|---|---|
| 0 | 1 | | | | |
| 2 | 3 | | | | |
| 4 | 5 | | | | |
| 6 | 7 | | | | |
However the local buffer is stored as if it was Height x Width display instead of Width x Height, e.g:
| | | | | | |
|---|---|---|---|---|---|
| 3 | 7 | | | | |
| 2 | 6 | | | | |
| 1 | 5 | | | | |
| 0 | 4 | | | | |
So those precalculated arrays just index the memory offsets in the order in which each one iterates its data.
## OLED API
```c
// OLED rotation enum values are flags
typedef enum {
OLED_ROTATION_0 = 0,
OLED_ROTATION_90 = 1,
OLED_ROTATION_180 = 2,
OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
} oled_rotation_t;
// Initialize the OLED display, rotating the rendered output based on the define passed in.
// Returns true if the OLED was initialized successfully
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_user(oled_rotation_t rotation);
// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
void oled_clear(void);
// Renders the dirty chunks of the buffer to OLED display
void oled_render(void);
// Moves cursor to character position indicated by column and line, wraps if out of bounds
// Max column denoted by 'oled_max_chars()' and max lines by 'oled_max_lines()' functions
void oled_set_cursor(uint8_t col, uint8_t line);
// Advances the cursor to the next page, writing ' ' if true
// Wraps to the begining when out of bounds
void oled_advance_page(bool clearPageRemainder);
// Moves the cursor forward 1 character length
// Advance page if there is not enough room for the next character
// Wraps to the begining when out of bounds
void oled_advance_char(void);
// Writes a single character to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Main handler that writes character data to the display buffer
void oled_write_char(const char data, bool invert);
// Writes a string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
void oled_write(const char *data, bool invert);
// Writes a string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
void oled_write_ln(const char *data, bool invert);
// Pans the buffer to the right (or left by passing true) by moving contents of the buffer
// Useful for moving the screen in preparation for new drawing
// oled_scroll_left or oled_scroll_right should be preferred for all cases of moving a static
// image such as a logo or to avoid burn-in as it's much, much less cpu intensive
void oled_pan(bool left);
// Writes a PROGMEM string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Remapped to call 'void oled_write(const char *data, bool invert);' on ARM
void oled_write_P(const char *data, bool invert);
// Writes a PROGMEM string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
// Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM
void oled_write_ln_P(const char *data, bool invert);
// Returns a pointer to the requested start index in the buffer plus remaining
// buffer length as struct
oled_buffer_reader_t oled_read_raw(uint16_t start_index);
// Writes a string to the buffer at current cursor position
void oled_write_raw(const char *data, uint16_t size);
// Writes a single byte into the buffer at the specified index
void oled_write_raw_byte(const char data, uint16_t index);
// Writes a PROGMEM string to the buffer at current cursor position
void oled_write_raw_P(const char *data, uint16_t size);
// Sets a specific pixel on or off
// Coordinates start at top-left and go right and down for positive x and y
void oled_write_pixel(uint8_t x, uint8_t y, bool on);
// Can be used to manually turn on the screen if it is off
// Returns true if the screen was on or turns on
bool oled_on(void);
// Can be used to manually turn off the screen if it is on
// Returns true if the screen was off or turns off
bool oled_off(void);
// Returns true if the oled is currently on, false if it is
// not
bool is_oled_on(void);
// Sets the brightness level of the display
uint8_t oled_set_brightness(uint8_t level);
// Gets the current brightness level of the display
uint8_t oled_get_brightness(void);
// Basically it's oled_render, but with timeout management and oled_task_user calling!
void oled_task(void);
// Called at the start of oled_task, weak function overridable by the user
void 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
// height of the screen. For 128x32 screens, rows 4-7 are not used.
void oled_scroll_set_area(uint8_t start_line, uint8_t end_line);
// Sets scroll speed, 0-7, fastest to slowest. Default is three.
// Does not take effect until scrolling is either started or restarted
// the ssd1306 supports 8 speeds with the delay
// listed below betwen each frame of the scrolling effect
// 0=2, 1=3, 2=4, 3=5, 4=25, 5=64, 6=128, 7=256
void oled_scroll_set_speed(uint8_t speed);
// Begin scrolling the entire display right
// Returns true if the screen was scrolling or starts scrolling
// NOTE: display contents cannot be changed while scrolling
bool oled_scroll_right(void);
// Begin scrolling the entire display left
// Returns true if the screen was scrolling or starts scrolling
// NOTE: display contents cannot be changed while scrolling
bool oled_scroll_left(void);
// Turns off display scrolling
// Returns true if the screen was not scrolling or stops scrolling
bool oled_scroll_off(void);
// Returns the maximum number of characters that will fit on a line
uint8_t oled_max_chars(void);
// Returns the maximum number of lines that will fit on the OLED
uint8_t oled_max_lines(void);
```
!> Scrolling and rotation are unsupported on the SH1106.
## SSD1306.h Driver Conversion Guide
|Old API |Recommended New API |
|-------------------------|---------------------------------|
|`struct CharacterMatrix` |*removed - delete all references*|
|`iota_gfx_init` |`oled_init` |
|`iota_gfx_on` |`oled_on` |
|`iota_gfx_off` |`oled_off` |
|`iota_gfx_flush` |`oled_render` |
|`iota_gfx_write_char` |`oled_write_char` |
|`iota_gfx_write` |`oled_write` |
|`iota_gfx_write_P` |`oled_write_P` |
|`iota_gfx_clear_screen` |`oled_clear` |
|`matrix_clear` |*removed - delete all references*|
|`matrix_write_char_inner`|`oled_write_char` |
|`matrix_write_char` |`oled_write_char` |
|`matrix_write` |`oled_write` |
|`matrix_write_ln` |`oled_write_ln` |
|`matrix_write_P` |`oled_write_P` |
|`matrix_write_ln_P` |`oled_write_ln_P` |
|`matrix_render` |`oled_render` |
|`iota_gfx_task` |`oled_task` |
|`iota_gfx_task_user` |`oled_task_user` |

49
feature_pointing_device.md Normal file
View File

@ -0,0 +1,49 @@
# 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.
To enable Pointing Device, uncomment the following line in your rules.mk:
```makefile
POINTING_DEVICE_ENABLE = yes
```
To manipulate the mouse report, you can use the following functions:
* `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
Keep in mind that a 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.
* `mouseReport.v` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing vertical scrolling (+ upward, - downward).
* `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 the last 5 bits are used. These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1.
Once you have made the necessary changes to the mouse report, you need to send it:
* `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.
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
case MS_SPECIAL:
report_mouse_t currentReport = pointing_device_get_report();
if (record->event.pressed) {
currentReport.v = 127;
currentReport.h = 127;
currentReport.buttons |= MOUSE_BTN1; // this is defined in report.h
} else {
currentReport.v = -127;
currentReport.h = -127;
currentReport.buttons &= ~MOUSE_BTN1;
}
pointing_device_set_report(currentReport);
pointing_device_send();
break;
```
Recall that the mouse report is set to zero (except the buttons) whenever it is sent, so the scrolling would only occur once in each case.

306
feature_ps2_mouse.md Normal file
View File

@ -0,0 +1,306 @@
# PS/2 Mouse Support :id=ps2-mouse-support
Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device.
To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest from a Thinkpad keyboard), identify the function of each pin of the module, and make the necessary circuitry between controller and Trackpoint module. For more information, please refer to [Trackpoint Hardware](https://deskthority.net/wiki/TrackPoint_Hardware) page on Deskthority Wiki.
There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
## The Circuitry between Trackpoint and Controller :id=the-circuitry-between-trackpoint-and-controller
To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+.
```
DATA ----------+--------- PIN
|
4.7K
|
MODULE 5+ --------+--+--------- PWR CONTROLLER
|
4.7K
|
CLK ------+------------ PIN
```
## Busywait Version :id=busywait-version
Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible.
In rules.mk:
```makefile
PS2_MOUSE_ENABLE = yes
PS2_USE_BUSYWAIT = yes
```
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
#endif
```
## Interrupt Version :id=interrupt-version
The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data.
In rules.mk:
```makefile
PS2_MOUSE_ENABLE = yes
PS2_USE_INT = yes
```
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_INT_INIT() do { \
EICRA |= ((1<<ISC21) | \
(0<<ISC20)); \
} while (0)
#define PS2_INT_ON() do { \
EIMSK |= (1<<INT2); \
} while (0)
#define PS2_INT_OFF() do { \
EIMSK &= ~(1<<INT2); \
} while (0)
#define PS2_INT_VECT INT2_vect
#endif
```
## USART Version :id=usart-version
To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version.
In rules.mk:
```makefile
PS2_MOUSE_ENABLE = yes
PS2_USE_USART = yes
```
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
/* synchronous, odd parity, 1-bit stop, 8-bit data, sample at falling edge */
/* set DDR of CLOCK as input to be slave */
#define PS2_USART_INIT() do { \
PS2_CLOCK_DDR &= ~(1<<PS2_CLOCK_BIT); \
PS2_DATA_DDR &= ~(1<<PS2_DATA_BIT); \
UCSR1C = ((1 << UMSEL10) | \
(3 << UPM10) | \
(0 << USBS1) | \
(3 << UCSZ10) | \
(0 << UCPOL1)); \
UCSR1A = 0; \
UBRR1H = 0; \
UBRR1L = 0; \
} while (0)
#define PS2_USART_RX_INT_ON() do { \
UCSR1B = ((1 << RXCIE1) | \
(1 << RXEN1)); \
} while (0)
#define PS2_USART_RX_POLL_ON() do { \
UCSR1B = (1 << RXEN1); \
} while (0)
#define PS2_USART_OFF() do { \
UCSR1C = 0; \
UCSR1B &= ~((1 << RXEN1) | \
(1 << TXEN1)); \
} while (0)
#define PS2_USART_RX_READY (UCSR1A & (1<<RXC1))
#define PS2_USART_RX_DATA UDR1
#define PS2_USART_ERROR (UCSR1A & ((1<<FE1) | (1<<DOR1) | (1<<UPE1)))
#define PS2_USART_RX_VECT USART1_RX_vect
#endif
```
## Additional Settings :id=additional-settings
### PS/2 Mouse Features :id=ps2-mouse-features
These enable settings supported by the PS/2 mouse protocol.
```c
/* Use remote mode instead of the default stream mode (see link) */
#define PS2_MOUSE_USE_REMOTE_MODE
/* Enable the scrollwheel or scroll gesture on your mouse or touchpad */
#define PS2_MOUSE_ENABLE_SCROLLING
/* Some mice will need a scroll mask to be configured. The default is 0xFF. */
#define PS2_MOUSE_SCROLL_MASK 0x0F
/* Applies a transformation to the movement before sending to the host (see link) */
#define PS2_MOUSE_USE_2_1_SCALING
/* The time to wait after initializing the ps2 host */
#define PS2_MOUSE_INIT_DELAY 1000 /* Default */
```
You can also call the following functions from ps2_mouse.h
```c
void ps2_mouse_disable_data_reporting(void);
void ps2_mouse_enable_data_reporting(void);
void ps2_mouse_set_remote_mode(void);
void ps2_mouse_set_stream_mode(void);
void ps2_mouse_set_scaling_2_1(void);
void ps2_mouse_set_scaling_1_1(void);
void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
```
### Fine Control :id=fine-control
Use the following defines to change the sensitivity and speed of the mouse.
Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads).
```c
#define PS2_MOUSE_X_MULTIPLIER 3
#define PS2_MOUSE_Y_MULTIPLIER 3
#define PS2_MOUSE_V_MULTIPLIER 1
```
### Scroll Button :id=scroll-button
If you're using a trackpoint, you will likely want to be able to use it for scrolling.
It's possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving.
To enable the feature, you must set a scroll button mask as follows:
```c
#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
```
To disable the scroll button feature:
```c
#define PS2_MOUSE_SCROLL_BTN_MASK 0
```
The available buttons are:
```c
#define PS2_MOUSE_BTN_LEFT 0
#define PS2_MOUSE_BTN_RIGHT 1
#define PS2_MOUSE_BTN_MIDDLE 2
```
You can also combine buttons in the mask by `|`ing them together.
Once you've configured your scroll button mask, you must configure the scroll button send interval.
This is the interval before which if the scroll buttons were released they would be sent to the host.
After this interval, they will cause the mouse to scroll and will not be sent.
```c
#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
```
To disable sending the scroll buttons:
```c
#define PS2_MOUSE_SCROLL_BTN_SEND 0
```
Fine control over the scrolling is supported with the following defines:
```c
#define PS2_MOUSE_SCROLL_DIVISOR_H 2
#define PS2_MOUSE_SCROLL_DIVISOR_V 2
```
### Invert Mouse and Scroll Axes :id=invert-mouse-and-scroll-axes
To invert the X and Y axes you can put:
```c
#define PS2_MOUSE_INVERT_X
#define PS2_MOUSE_INVERT_Y
```
into config.h.
To reverse the scroll axes you can put:
```c
#define PS2_MOUSE_INVERT_H
#define PS2_MOUSE_INVERT_V
```
into config.h.
### Rotate Mouse Axes :id=rotate-mouse-axes
Transform the output of the device with a clockwise rotation of 90, 180, or 270
degrees.
When compensating for device orientation, rotate the output the same amount in
the opposite direction. E.g. if the normal device orientation is considered to
be North-facing, compensate as follows:
```c
#define PS2_MOUSE_ROTATE 270 /* Compensate for East-facing device orientation. */
```
```c
#define PS2_MOUSE_ROTATE 180 /* Compensate for South-facing device orientation. */
```
```c
#define PS2_MOUSE_ROTATE 90 /* Compensate for West-facing device orientation. */
```
### Debug Settings :id=debug-settings
To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
```c
/* To debug the mouse reports */
#define PS2_MOUSE_DEBUG_HID
#define PS2_MOUSE_DEBUG_RAW
```
### Movement Hook :id=movement-hook
Process mouse movement in the keymap before it is sent to the host. Example
uses include filtering noise, adding acceleration, and automatically activating
a layer. To use, define the following function in your keymap:
```c
void ps2_mouse_moved_user(report_mouse_t *mouse_report);
```

69
feature_rawhid.md Normal file
View File

@ -0,0 +1,69 @@
# Raw HID
Raw HID allows for bidirectional communication between QMK and the host computer over an HID interface. This has many potential use cases, such as switching keymaps on the fly or changing RGB LED colors and modes.
There are two main components to getting raw HID working with your keyboard.
## Keyboard firmware
The implementation is fairly straightforward for the firmware.
In your `rules.mk` add:
```make
RAW_ENABLE = yes
```
In your `keymap.c` include `"raw_hid.h"` and implement the following:
```C
void raw_hid_receive(uint8_t *data, uint8_t length) {
// Your code goes here. data is the packet received from host.
}
```
The `"raw_hid.h"` header also declares `void raw_hid_send(uint8_t *data, uint8_t length);` which allows sending packets from keyboard to host. As an example, it can also be used for debugging when building your host application by returning all data back to the host.
```C
void raw_hid_receive(uint8_t *data, uint8_t length) {
raw_hid_send(data, length);
}
```
`raw_hid_receive` can receive variable size packets from host with maximum length `RAW_EPSIZE`. `raw_hid_send` on the other hand can send packets to host of exactly `RAW_EPSIZE` length, therefore it should be used with data of length `RAW_EPSIZE`.
Make sure to flash raw enabled firmware before proceeding with working on the host side.
## Host (Windows/macOS/Linux)
This is the more complicated part as it will require some digging.
To connect your host computer to your keyboard with raw HID you need four pieces of information about your keyboard:
1. Vendor ID
2. Product ID
3. Usage Page
4. Usage
The first two can easily be found in your keyboard's `config.h` in the keyboard's main directory under `VENDOR_ID` and `PRODUCT_ID`.
The final two can be overridden in your keyboard's `config.h` in the keyboard's main directory by redefining the values: `#define RAW_USAGE_PAGE 0xFF60` and `#define RAW_USAGE_ID 0x61`.
By default, **Usage Page** is `0xFF60` and **Usage** is `0x61`.
### Building your host
You can build your host using any language that has an available HID implementation library if you don't wish to make your own. The ones we know of for popular languages are:
* Node: [node-hid](https://github.com/node-hid/node-hid).
* C: [hidapi](https://github.com/libusb/hidapi).
* Java: [purejavahidapi](https://github.com/nyholku/purejavahidapi) and [hid4java](https://github.com/gary-rowe/hid4java).
* Python: [pyhidapi](https://pypi.org/project/hid/).
This is not an exhaustive cross-platform list but should get you started. There are no special requirements for using raw HID so any HID library should work.
Now that you have all four pieces of information required to open HID interface to your keyboard. All you need to do is use your library's available functions to open the device with its ID parameters.
Note that Vendor ID and Product ID are not actually required to open the device. They are used only to filter to a specific device out of the many HID devices you have plugged in. Many libraries will give you the option to open the device using Product Name or Manufacturer Name instead, `node-hid` being a prime example. This will create issues for devices with builtin USB Hub or any extra HID interfaces where you will have multiple interfaces with the same name or from the same manufacturer. The Vendor ID together with Product ID create a unique designation to a single interface and will not exhibit this problem. Therefore, even if your library doesn't require you to, it is best to use them to avoid issues.
Unlike Vendor ID and Product ID though, Usage Page and Usage are necessary for successful communication.
It should go without saying that regardless of the library you're using, you should always make sure to close the interface when finished. Depending on the operating system and your particular environment there may be issues connecting to it again afterwards with another client or another instance of the same client if it's not explicitly closed.

510
feature_rgb_matrix.md Normal file
View File

@ -0,0 +1,510 @@
# RGB Matrix Lighting :id=rgb-matrix-lighting
This feature allows you to use RGB LED matrices driven by external drivers. It hooks into the RGBLIGHT system so you can use the same keycodes as RGBLIGHT to control it.
If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead.
## Driver configuration :id=driver-configuration
---
### IS31FL3731 :id=is31fl3731
There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
```makefile
RGB_MATRIX_ENABLE = IS31FL3731
```
Configure the hardware via your `config.h`:
```c
// This is a 7-bit address, that gets left-shifted and bit 0
// set to 0 for write, 1 for read (as per I2C protocol)
// The address will vary depending on your wiring:
// 0b1110100 AD <-> GND
// 0b1110111 AD <-> VCC
// 0b1110101 AD <-> SCL
// 0b1110110 AD <-> SDA
#define DRIVER_ADDR_1 0b1110100
#define DRIVER_ADDR_2 0b1110110
#define DRIVER_COUNT 2
#define DRIVER_1_LED_TOTAL 25
#define DRIVER_2_LED_TOTAL 24
#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)
```
!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`.
Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | R location
* | | G location
* | | | B location
* | | | | */
{0, C1_3, C2_3, C3_3},
....
}
```
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
---
### IS31FL3733/IS31FL3737 :id=is31fl3733is31fl3737
!> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`.
There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
```makefile
RGB_MATRIX_ENABLE = IS31FL3733
```
Configure the hardware via your `config.h`:
```c
// This is a 7-bit address, that gets left-shifted and bit 0
// set to 0 for write, 1 for read (as per I2C protocol)
// The address will vary depending on your wiring:
// 00 <-> GND
// 01 <-> SCL
// 10 <-> SDA
// 11 <-> VCC
// ADDR1 represents A1:A0 of the 7-bit address.
// ADDR2 represents A3:A2 of the 7-bit address.
// The result is: 0b101(ADDR2)(ADDR1)
#define DRIVER_ADDR_1 0b1010000
#define DRIVER_ADDR_2 0b1010000 // this is here for compliancy reasons.
#define DRIVER_COUNT 2
#define DRIVER_1_LED_TOTAL 64
#define DRIVER_LED_TOTAL DRIVER_1_LED_TOTAL
```
Currently only a single drivers is supported, but it would be trivial to support all 4 combinations. For now define `DRIVER_ADDR_2` as `DRIVER_ADDR_1`
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | R location
* | | G location
* | | | B location
* | | | | */
{0, B_1, A_1, C_1},
....
}
```
Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now).
---
### WS2812 :id=ws2812
There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`:
```makefile
RGB_MATRIX_ENABLE = WS2812
```
Configure the hardware via your `config.h`:
```c
// The pin connected to the data pin of the LEDs
#define RGB_DI_PIN D7
// The number of LEDs connected
#define DRIVER_LED_TOTAL 70
```
---
From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example:
```c
led_config_t g_led_config = { {
// Key Matrix to LED Index
{ 5, NO_LED, NO_LED, 0 },
{ NO_LED, NO_LED, NO_LED, NO_LED },
{ 4, NO_LED, NO_LED, 1 },
{ 3, NO_LED, NO_LED, 2 }
}, {
// LED Index to Physical Position
{ 188, 16 }, { 187, 48 }, { 149, 64 }, { 112, 64 }, { 37, 48 }, { 38, 16 }
}, {
// LED Index to Flag
1, 4, 4, 4, 4, 1
} };
```
The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical `{ x, y }` position on the keyboard. The default expected range of values for `{ x, y }` is the inclusive range `{ 0..224, 0..64 }`. This default expected range is due to effects that calculate the center of the keyboard for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents `{ x, y }` coordinate `{ 0, 0 }` and the bottom right of your keyboard represents `{ 224, 64 }`. Using this as a basis, you can use the following formula to calculate the physical position:
```c
x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION
y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION
```
Where NUMBER_OF_COLS, NUMBER_OF_ROWS, COL_POSITION, & ROW_POSITION are all based on the physical layout of your keyboard, not the electrical layout.
As mentioned earlier, the center of the keyboard by default is expected to be `{ 112, 32 }`, but this can be changed if you want to more accurately calculate the LED's physical `{ x, y }` positions. Keyboard designers can implement `#define RGB_MATRIX_CENTER { 112, 32 }` in their config.h file with the new center point of the keyboard, or where they want it to be allowing more possibilities for the `{ x, y }` values. Do note that the maximum value for x or y is 255, and the recommended maximum is 224 as this gives animations runoff room before they reset.
`// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type.
## Flags :id=flags
|Define |Value |Description |
|----------------------------|------|-------------------------------------------------|
|`HAS_FLAGS(bits, flags)` |*n/a* |Evaluates to `true` if `bits` has all `flags` set|
|`HAS_ANY_FLAGS(bits, flags)`|*n/a* |Evaluates to `true` if `bits` has any `flags` set|
|`LED_FLAG_NONE` |`0x00`|If this LED has no flags |
|`LED_FLAG_ALL` |`0xFF`|If this LED has all flags |
|`LED_FLAG_MODIFIER` |`0x01`|If the LED is on a modifier key |
|`LED_FLAG_UNDERGLOW` |`0x02`|If the LED is for underglow |
|`LED_FLAG_KEYLIGHT` |`0x04`|If the LED is for key backlight |
|`LED_FLAG_INDICATOR` |`0x08`|If the LED is for keyboard state indication |
## Keycodes :id=keycodes
All RGB keycodes are currently shared with the RGBLIGHT system:
|Key |Aliases |Description |
|-------------------|----------|--------------------------------------------------------------------------------------|
|`RGB_TOG` | |Toggle RGB lighting on or off |
|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held |
|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held |
|`RGB_HUI` | |Increase hue, decrease hue when Shift is held |
|`RGB_HUD` | |Decrease hue, increase hue when Shift is held |
|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held |
|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held |
|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held |
|`RGB_VAD` | |Decrease value (brightness), increase value when Shift is held |
|`RGB_SPI` | |Increase effect speed (does not support eeprom yet), decrease speed when Shift is held|
|`RGB_SPD` | |Decrease effect speed (does not support eeprom yet), increase speed when Shift is held|
|`RGB_MODE_PLAIN` |`RGB_M_P `|Static (no animation) mode |
|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode |
|`RGB_MODE_RAINBOW` |`RGB_M_R` |Full gradient scrolling left to right (uses the `RGB_MATRIX_CYCLE_LEFT_RIGHT` mode) |
|`RGB_MODE_SWIRL` |`RGB_M_SW`|Full gradient spinning pinwheel around center of keyboard (uses `RGB_MATRIX_CYCLE_PINWHEEL` mode) |
* `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.
!> 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.
## RGB Matrix Effects :id=rgb-matrix-effects
All effects have been configured to support current configuration values (Hue, Saturation, Value, & Speed) unless otherwise noted below. These are the effects that are currently available:
```c
enum rgb_matrix_effects {
RGB_MATRIX_NONE = 0,
RGB_MATRIX_SOLID_COLOR = 1, // Static single hue, no speed support
RGB_MATRIX_ALPHAS_MODS, // Static dual hue, speed is hue for secondary hue
RGB_MATRIX_GRADIENT_UP_DOWN, // Static gradient top to bottom, speed controls how much gradient changes
RGB_MATRIX_GRADIENT_LEFT_RIGHT, // Static gradient left to right, speed controls how much gradient changes
RGB_MATRIX_BREATHING, // Single hue brightness cycling animation
RGB_MATRIX_BAND_SAT, // Single hue band fading saturation scrolling left to right
RGB_MATRIX_BAND_VAL, // Single hue band fading brightness scrolling left to right
RGB_MATRIX_BAND_PINWHEEL_SAT, // Single hue 3 blade spinning pinwheel fades saturation
RGB_MATRIX_BAND_PINWHEEL_VAL, // Single hue 3 blade spinning pinwheel fades brightness
RGB_MATRIX_BAND_SPIRAL_SAT, // Single hue spinning spiral fades saturation
RGB_MATRIX_BAND_SPIRAL_VAL, // Single hue spinning spiral fades brightness
RGB_MATRIX_CYCLE_ALL, // Full keyboard solid hue cycling through full gradient
RGB_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right
RGB_MATRIX_CYCLE_UP_DOWN, // Full gradient scrolling top to bottom
RGB_MATRIX_CYCLE_OUT_IN, // Full gradient scrolling out to in
RGB_MATRIX_CYCLE_OUT_IN_DUAL, // Full dual gradients scrolling out to in
RGB_MATRIX_RAINBOW_MOVING_CHEVRON, // Full gradent Chevron shapped scrolling left to right
RGB_MATRIX_CYCLE_PINWHEEL, // Full gradient spinning pinwheel around center of keyboard
RGB_MATRIX_CYCLE_SPIRAL, // Full gradient spinning spiral around center of keyboard
RGB_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard
RGB_MATRIX_RAINBOW_BEACON, // Full tighter gradient spinning around center of keyboard
RGB_MATRIX_RAINBOW_PINWHEELS, // Full dual gradients spinning two halfs of keyboard
RGB_MATRIX_RAINDROPS, // Randomly changes a single key's hue
RGB_MATRIX_JELLYBEAN_RAINDROPS, // Randomly changes a single key's hue and saturation
#if define(RGB_MATRIX_FRAMEBUFFER_EFFECTS)
RGB_MATRIX_TYPING_HEATMAP, // How hot is your WPM!
RGB_MATRIX_DIGITAL_RAIN, // That famous computer simulation
#endif
#if defined(RGB_MATRIX_KEYPRESSES) || defined(RGB_MATRIX_KEYRELEASES)
RGB_MATRIX_SOLID_REACTIVE_SIMPLE, // Pulses keys hit to hue & value then fades value out
RGB_MATRIX_SOLID_REACTIVE, // Static single hue, pulses keys hit to shifted hue then fades to current hue
RGB_MATRIX_SOLID_REACTIVE_WIDE // Hue & value pulse near a single key hit then fades value out
RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE // Hue & value pulse near multiple key hits then fades value out
RGB_MATRIX_SOLID_REACTIVE_CROSS // Hue & value pulse the same column and row of a single key hit then fades value out
RGB_MATRIX_SOLID_REACTIVE_MULTICROSS // Hue & value pulse the same column and row of multiple key hits then fades value out
RGB_MATRIX_SOLID_REACTIVE_NEXUS // Hue & value pulse away on the same column and row of a single key hit then fades value out
RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS // Hue & value pulse away on the same column and row of multiple key hits then fades value out
RGB_MATRIX_SPLASH, // Full gradient & value pulse away from a single key hit then fades value out
RGB_MATRIX_MULTISPLASH, // Full gradient & value pulse away from multiple key hits then fades value out
RGB_MATRIX_SOLID_SPLASH, // Hue & value pulse away from a single key hit then fades value out
RGB_MATRIX_SOLID_MULTISPLASH, // Hue & value pulse away from multiple key hits then fades value out
#endif
RGB_MATRIX_EFFECT_MAX
};
```
You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`:
|Define |Description |
|-------------------------------------------------------|-----------------------------------------------|
|`#define DISABLE_RGB_MATRIX_ALPHAS_MODS` |Disables `RGB_MATRIX_ALPHAS_MODS` |
|`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Disables `RGB_MATRIX_GRADIENT_UP_DOWN` |
|`#define DISABLE_RGB_MATRIX_BREATHING` |Disables `RGB_MATRIX_BREATHING` |
|`#define DISABLE_RGB_MATRIX_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_CYCLE_OUT_IN` |Disables `RGB_MATRIX_CYCLE_OUT_IN` |
|`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Disables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` |
|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |
|`#define DISABLE_RGB_MATRIX_DUAL_BEACON` |Disables `RGB_MATRIX_DUAL_BEACON` |
|`#define DISABLE_RGB_MATRIX_CYCLE_PINWHEEL` |Disables `RGB_MATRIX_CYCLE_PINWHEEL` |
|`#define DISABLE_RGB_MATRIX_CYCLE_SPIRAL` |Disables `RGB_MATRIX_CYCLE_SPIRAL` |
|`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON` |Disables `RGB_MATRIX_RAINBOW_BEACON` |
|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Disables `RGB_MATRIX_RAINBOW_PINWHEELS` |
|`#define DISABLE_RGB_MATRIX_RAINDROPS` |Disables `RGB_MATRIX_RAINDROPS` |
|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS` |
|`#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` |Disables `RGB_MATRIX_SOLID_REACTIVE` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_WIDE` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_CROSS` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`|
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_NEXUS` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
|`#define DISABLE_RGB_MATRIX_SPLASH` |Disables `RGB_MATRIX_SPLASH` |
|`#define DISABLE_RGB_MATRIX_MULTISPLASH` |Disables `RGB_MATRIX_MULTISPLASH` |
|`#define DISABLE_RGB_MATRIX_SOLID_SPLASH` |Disables `RGB_MATRIX_SOLID_SPLASH` |
|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` |
## Custom RGB Matrix Effects :id=custom-rgb-matrix-effects
By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files.
To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks something like this:
`rgb_matrix_user.inc` should go in the root of the keymap directory.
`rgb_matrix_kb.inc` should go in the root of the keyboard directory.
```c
// !!! DO NOT ADD #pragma once !!! //
// Step 1.
// Declare custom effects using the RGB_MATRIX_EFFECT macro
// (note the lack of semicolon after the macro!)
RGB_MATRIX_EFFECT(my_cool_effect)
RGB_MATRIX_EFFECT(my_cool_effect2)
// Step 2.
// Define effects inside the `RGB_MATRIX_CUSTOM_EFFECT_IMPLS` ifdef block
#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
// e.g: A simple effect, self-contained within a single method
static bool my_cool_effect(effect_params_t* params) {
RGB_MATRIX_USE_LIMITS(led_min, led_max);
for (uint8_t i = led_min; i < led_max; i++) {
rgb_matrix_set_color(i, 0xff, 0xff, 0x00);
}
return led_max < DRIVER_LED_TOTAL;
}
// e.g: A more complex effect, relying on external methods and state, with
// dedicated init and run methods
static uint8_t some_global_state;
static void my_cool_effect2_complex_init(effect_params_t* params) {
some_global_state = 1;
}
static bool my_cool_effect2_complex_run(effect_params_t* params) {
RGB_MATRIX_USE_LIMITS(led_min, led_max);
for (uint8_t i = led_min; i < led_max; i++) {
rgb_matrix_set_color(i, 0xff, some_global_state++, 0xff);
}
return led_max < DRIVER_LED_TOTAL;
}
static bool my_cool_effect2(effect_params_t* params) {
if (params->init) my_cool_effect2_complex_init(params);
return my_cool_effect2_complex_run(params);
}
#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
```
For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/`
## Colors :id=colors
These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
|RGB |HSV |
|-------------------|-------------------|
|`RGB_WHITE` |`HSV_WHITE` |
|`RGB_RED` |`HSV_RED` |
|`RGB_CORAL` |`HSV_CORAL` |
|`RGB_ORANGE` |`HSV_ORANGE` |
|`RGB_GOLDENROD` |`HSV_GOLDENROD` |
|`RGB_GOLD` |`HSV_GOLD` |
|`RGB_YELLOW` |`HSV_YELLOW` |
|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` |
|`RGB_GREEN` |`HSV_GREEN` |
|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` |
|`RGB_TURQUOISE` |`HSV_TURQUOISE` |
|`RGB_TEAL` |`HSV_TEAL` |
|`RGB_CYAN` |`HSV_CYAN` |
|`RGB_AZURE` |`HSV_AZURE` |
|`RGB_BLUE` |`HSV_BLUE` |
|`RGB_PURPLE` |`HSV_PURPLE` |
|`RGB_MAGENTA` |`HSV_MAGENTA` |
|`RGB_PINK` |`HSV_PINK` |
These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
## Additional `config.h` Options :id=additional-configh-options
```c
#define RGB_MATRIX_KEYPRESSES // reacts to keypresses
#define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses)
#define RGB_DISABLE_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off
#define RGB_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects
#define RGB_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended
#define RGB_MATRIX_LED_PROCESS_LIMIT (DRIVER_LED_TOTAL + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness)
#define RGB_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness)
#define RGB_MATRIX_MAXIMUM_BRIGHTNESS 200 // limits maximum brightness of LEDs to 200 out of 255. If not defined maximum brightness is set to 255
#define RGB_MATRIX_STARTUP_MODE RGB_MATRIX_CYCLE_LEFT_RIGHT // Sets the default mode, if none has been set
#define RGB_MATRIX_STARTUP_HUE 0 // Sets the default hue value, if none has been set
#define RGB_MATRIX_STARTUP_SAT 255 // Sets the default saturation value, if none has been set
#define RGB_MATRIX_STARTUP_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set
#define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set
#define RGB_MATRIX_DISABLE_KEYCODES // disables control of rgb matrix by keycodes (must use code functions to control the feature)
```
## EEPROM storage :id=eeprom-storage
The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with:
```c
#define EECONFIG_RGB_MATRIX (uint32_t *)28
```
Where `28` is an unused index from `eeconfig.h`.
## Functions :id=functions
### Direct Operation :id=direct-operation
|Function |Description |
|--------------------------------------------|-------------|
|`rgb_matrix_set_color_all(r, g, b)` |Set all of the LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) |
|`rgb_matrix_set_color(index, r, g, b)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255, and `index` is between 0 and `DRIVER_LED_TOTAL` (not written to EEPROM) |
### Disable/Enable Effects :id=disable-enable-effects
|Function |Description |
|--------------------------------------------|-------------|
|`rgb_matrix_toggle()` |Toggle effect range LEDs between on and off |
|`rgb_matrix_toggle_noeeprom()` |Toggle effect range LEDs between on and off (not written to EEPROM) |
|`rgb_matrix_enable()` |Turn effect range LEDs on, based on their previous state |
|`rgb_matrix_enable_noeeprom()` |Turn effect range LEDs on, based on their previous state (not written to EEPROM) |
|`rgb_matrix_disable()` |Turn effect range LEDs off, based on their previous state |
|`rgb_matrix_disable_noeeprom()` |Turn effect range LEDs off, based on their previous state (not written to EEPROM) |
### Change Effect Mode :id=change-effect-mode
|Function |Description |
|--------------------------------------------|-------------|
|`rgb_matrix_mode(mode)` |Set the mode, if RGB animations are enabled |
|`rgb_matrix_mode_noeeprom(mode)` |Set the mode, if RGB animations are enabled (not written to EEPROM) |
|`rgb_matrix_step()` |Change the mode to the next RGB animation in the list of enabled RGB animations |
|`rgb_matrix_step_noeeprom()` |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) |
|`rgb_matrix_step_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations |
|`rgb_matrix_step_reverse_noeeprom()` |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) |
|`rgb_matrix_increase_speed()` |Increase the speed of the animations |
|`rgb_matrix_increase_speed_noeeprom()` |Increase the speed of the animations (not written to EEPROM) |
|`rgb_matrix_decrease_speed()` |Decrease the speed of the animations |
|`rgb_matrix_decrease_speed_noeeprom()` |Decrease the speed of the animations (not written to EEPROM) |
|`rgb_matrix_set_speed(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 |
|`rgb_matrix_set_speed_noeeprom(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 (not written to EEPROM) |
### Change Color :id=change-color
|Function |Description |
|--------------------------------------------|-------------|
|`rgb_matrix_increase_hue()` |Increase the hue for effect range LEDs. This wraps around at maximum hue |
|`rgb_matrix_increase_hue_noeeprom()` |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) |
|`rgb_matrix_decrease_hue()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue |
|`rgb_matrix_decrease_hue_noeeprom()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) |
|`rgb_matrix_increase_sat()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation |
|`rgb_matrix_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation (not written to EEPROM) |
|`rgb_matrix_decrease_sat()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation |
|`rgb_matrix_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation (not written to EEPROM) |
|`rgb_matrix_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value |
|`rgb_matrix_increase_val_noeeprom()` |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) |
|`rgb_matrix_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value |
|`rgb_matrix_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) |
|`rgb_matrix_sethsv(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
|`rgb_matrix_sethsv_noeeprom(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
### Query Current Status :id=query-current-status
|Function |Description |
|---------------------------------|---------------------------|
|`rgb_matrix_is_enabled()` |Gets current on/off status |
|`rgb_matrix_get_mode()` |Gets current mode |
|`rgb_matrix_get_hue()` |Gets current hue |
|`rgb_matrix_get_sat()` |Gets current sat |
|`rgb_matrix_get_val()` |Gets current val |
|`rgb_matrix_get_hsv()` |Gets hue, sat, and val and returns a [`HSV` structure](https://github.com/qmk/qmk_firmware/blob/7ba6456c0b2e041bb9f97dbed265c5b8b4b12192/quantum/color.h#L56-L61)|
|`rgb_matrix_get_speed()` |Gets current speed |
|`rgb_matrix_get_suspend_state()` |Gets current suspend state |
## Callbacks :id=callbacks
### 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:
```c
void rgb_matrix_indicators_kb(void) {
rgb_matrix_set_color(index, red, green, blue);
}
```
### Suspended state :id=suspended-state
To use the suspend feature, make sure that `#define RGB_DISABLE_WHEN_USB_SUSPENDED true` is added to the `config.h` file.
Additionally add this to your `<keyboard>.c`:
```c
void suspend_power_down_kb(void) {
rgb_matrix_set_suspend_state(true);
suspend_power_down_user();
}
void suspend_wakeup_init_kb(void) {
rgb_matrix_set_suspend_state(false);
suspend_wakeup_init_user();
}
```
or add this to your `keymap.c`:
```c
void suspend_power_down_user(void) {
rgb_matrix_set_suspend_state(true);
}
void suspend_wakeup_init_user(void) {
rgb_matrix_set_suspend_state(false);
}
```

520
feature_rgblight.md Normal file
View File

@ -0,0 +1,520 @@
# RGB Lighting
QMK has the ability to control RGB LEDs attached to your keyboard. This is commonly called *underglow*, due to the LEDs often being mounted on the bottom of the keyboard, producing a nice diffused effect when combined with a translucent case.
![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/3774a7fcdab5544fc787f4c200be05fcd417e31f/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg)
Some keyboards come with RGB LEDs preinstalled. Others must have them installed after the fact. See the [Hardware Modification](#hardware-modification) section for information on adding RGB lighting to your keyboard.
Currently QMK supports the following addressable LEDs (however, the white LED in RGBW variants is not supported):
* WS2811, WS2812, WS2812B, WS2812C, etc.
* SK6812, SK6812MINI, SK6805
These LEDs are called "addressable" because instead of using a wire per color, each LED contains a small microchip that understands a special protocol sent over a single wire. The chip passes on the remaining data to the next LED, allowing them to be chained together. In this way, you can easily control the color of the individual LEDs.
## Usage
On keyboards with onboard RGB LEDs, it is usually enabled by default. If it is not working for you, check that your `rules.mk` includes the following:
```make
RGBLIGHT_ENABLE = yes
```
At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these.
|Define |Description |
|---------------|---------------------------------------------------------------------------------------------------------|
|`RGB_DI_PIN` |The pin connected to the data pin of the LEDs |
|`RGBLED_NUM` |The number of LEDs connected |
|`RGBLED_SPLIT` |(Optional) For split keyboards, the number of LEDs connected on each half directly wired to `RGB_DI_PIN` |
Then you should be able to use the keycodes below to change the RGB lighting to your liking.
### Color Selection
QMK uses [Hue, Saturation, and Value](https://en.wikipedia.org/wiki/HSL_and_HSV) to select colors rather than RGB. The color wheel below demonstrates how this works.
<img src="gitbook/images/color-wheel.svg" alt="HSV Color Wheel" width="250"/>
Changing the **Hue** cycles around the circle.<br>
Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.<br>
Changing the **Value** sets the overall brightness.<br>
![QMK Color Wheel with HSV Values](https://i.imgur.com/vkYVo66.jpg)
## Keycodes
|Key |Aliases |Description |
|-------------------|----------|--------------------------------------------------------------------|
|`RGB_TOG` | |Toggle RGB lighting on or off |
|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held |
|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held|
|`RGB_HUI` | |Increase hue, decrease hue when Shift is held |
|`RGB_HUD` | |Decrease hue, increase hue when Shift is held |
|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held |
|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held |
|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held |
|`RGB_VAD` | |Decrease value (brightness), increase value when Shift is held |
|`RGB_MODE_PLAIN` |`RGB_M_P `|Static (no animation) mode |
|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode |
|`RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation mode |
|`RGB_MODE_SWIRL` |`RGB_M_SW`|Swirl animation mode |
|`RGB_MODE_SNAKE` |`RGB_M_SN`|Snake animation mode |
|`RGB_MODE_KNIGHT` |`RGB_M_K` |"Knight Rider" animation mode |
|`RGB_MODE_XMAS` |`RGB_M_X` |Christmas animation mode |
|`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode |
|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode |
!> By default, if you have both the RGB Light and the [RGB Matrix](feature_rgb_matrix.md) 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.
## Configuration
Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
|Define |Default |Description |
|---------------------|-------------|-----------------------------------------------------------------------------|
|`RGBLIGHT_HUE_STEP` |`10` |The number of steps to cycle through the hue by |
|`RGBLIGHT_SAT_STEP` |`17` |The number of steps to increment the saturation by |
|`RGBLIGHT_VAL_STEP` |`17` |The number of steps to increment the brightness by |
|`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level |
|`RGBLIGHT_SLEEP` |*Not defined*|If defined, the RGB lighting will be switched off when the host goes to sleep|
|`RGBLIGHT_SPLIT` |*Not defined*|If defined, synchronization functionality for split keyboards is added|
|`RGBLIGHT_DISABLE_KEYCODES`|*not defined*|If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature|
## Effects and Animations
Not only can this lighting be whatever color you want,
if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a number of animation modes at your disposal:
|Mode number symbol |Additional number |Description |
|-----------------------------|-------------------|---------------------------------------|
|`RGBLIGHT_MODE_STATIC_LIGHT` | *None* |Solid color (this mode is always enabled) |
|`RGBLIGHT_MODE_BREATHING` | 0,1,2,3 |Solid color breathing |
|`RGBLIGHT_MODE_RAINBOW_MOOD` | 0,1,2 |Cycling rainbow |
|`RGBLIGHT_MODE_RAINBOW_SWIRL`| 0,1,2,3,4,5 |Swirling rainbow |
|`RGBLIGHT_MODE_SNAKE` | 0,1,2,3,4,5 |Snake |
|`RGBLIGHT_MODE_KNIGHT` | 0,1,2 |Knight |
|`RGBLIGHT_MODE_CHRISTMAS` | *None* |Christmas |
|`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9 |Static gradient |
|`RGBLIGHT_MODE_RGB_TEST` | *None* |RGB Test |
|`RGBLIGHT_MODE_ALTERNATING` | *None* |Alternating |
|`RGBLIGHT_MODE_TWINKLE` | 0,1,2,3,4,5 |Twinkle |
Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration.
Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight.h` there is a contrast table between the old mode number and the current symbol.
### Effect and Animation Toggles
Use these defines to add or remove animations from the firmware. When you are running low on flash space, it can be helpful to disable animations you are not using.
|Define |Default |Description |
|------------------------------------|-------------|-------------------------------------------------------------------------|
|`RGBLIGHT_ANIMATIONS` |*Not defined*|Enable all additional animation modes. |
|`RGBLIGHT_EFFECT_ALTERNATING` |*Not defined*|Enable alternating animation mode. |
|`RGBLIGHT_EFFECT_BREATHING` |*Not defined*|Enable breathing animation mode. |
|`RGBLIGHT_EFFECT_CHRISTMAS` |*Not defined*|Enable christmas animation mode. |
|`RGBLIGHT_EFFECT_KNIGHT` |*Not defined*|Enable knight animation mode. |
|`RGBLIGHT_EFFECT_RAINBOW_MOOD` |*Not defined*|Enable rainbow mood animation mode. |
|`RGBLIGHT_EFFECT_RAINBOW_SWIRL` |*Not defined*|Enable rainbow swirl animation mode. |
|`RGBLIGHT_EFFECT_RGB_TEST` |*Not defined*|Enable RGB test animation mode. |
|`RGBLIGHT_EFFECT_SNAKE` |*Not defined*|Enable snake animation mode. |
|`RGBLIGHT_EFFECT_STATIC_GRADIENT` |*Not defined*|Enable static gradient mode. |
|`RGBLIGHT_EFFECT_TWINKLE` |*Not defined*|Enable twinkle animation mode. |
### Effect and Animation Settings
The following options are used to tweak the various animations:
|Define |Default |Description |
|------------------------------------|-------------|-----------------------------------------------------------------------------------------------|
|`RGBLIGHT_EFFECT_BREATHE_CENTER` |*Not defined*|If defined, used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 |
|`RGBLIGHT_EFFECT_BREATHE_MAX` |`255` |The maximum brightness for the breathing mode. Valid values are 1 to 255 |
|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`40` |How long (in milliseconds) to wait between animation steps for the "Christmas" animation |
|`RGBLIGHT_EFFECT_CHRISTMAS_STEP` |`2` |The number of LEDs to group the red/green colors by for the "Christmas" animation |
|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM` |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel |
|`RGBLIGHT_EFFECT_KNIGHT_LENGTH` |`3` |The number of LEDs to light up for the "Knight" animation |
|`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by |
|`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls |
|`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation |
|`RGBLIGHT_EFFECT_TWINKLE_LIFE` |`75` |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps) |
|`RGBLIGHT_EFFECT_TWINKLE_PROBABILITY`|`1/127` |Adjusts how likely each LED is to twinkle (on each animation step) |
### Example Usage to Reduce Memory Footprint
1. Remove `RGBLIGHT_ANIMATIONS` from `config.h`.
1. Selectively add the animations you want to enable. The following would enable two animations and save about 4KiB:
```diff
#undef RGBLED_NUM
-#define RGBLIGHT_ANIMATIONS
+#define RGBLIGHT_EFFECT_STATIC_GRADIENT
+#define RGBLIGHT_EFFECT_RAINBOW_SWIRL
#define RGBLED_NUM 12
#define RGBLIGHT_HUE_STEP 8
#define RGBLIGHT_SAT_STEP 8
```
### Animation Speed
You can also modify the speeds that the different modes animate at:
Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
```c
// How long (in milliseconds) to wait between animation steps for each of the "Solid color breathing" animations
const uint8_t RGBLED_BREATHING_INTERVALS[] PROGMEM = {30, 20, 10, 5};
// How long (in milliseconds) to wait between animation steps for each of the "Cycling rainbow" animations
const uint8_t RGBLED_RAINBOW_MOOD_INTERVALS[] PROGMEM = {120, 60, 30};
// How long (in milliseconds) to wait between animation steps for each of the "Swirling rainbow" animations
const uint8_t RGBLED_RAINBOW_SWIRL_INTERVALS[] PROGMEM = {100, 50, 20};
// How long (in milliseconds) to wait between animation steps for each of the "Snake" animations
const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
// How long (in milliseconds) to wait between animation steps for each of the "Knight" animations
const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
// How long (in milliseconds) to wait between animation steps for each of the "Twinkle" animations
const uint8_t RGBLED_TWINKLE_INTERVALS[] PROGMEM = {50, 25, 10};
// These control which hues are selected for each of the "Static gradient" modes
const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
```
## Lighting Layers
By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make
it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do.
### Defining Lighting Layers :id=defining-lighting-layers
By default, 8 layers are possible. This can be expanded to as many as 32 by overriding the definition of `RGBLIGHT_MAX_LAYERS` in `config.h` (e.g. `#define RGBLIGHT_MAX_LAYERS 32`). Please note, if you use a split keyboard, you will need to flash both sides of the split after changing this. Also, increasing the maximum will increase the firmware size, and will slow sync on split keyboards.
To define a layer, we modify `keymap.c` to list out LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently:
```c
// Light LEDs 6 to 9 and 12 to 15 red when caps lock is active. Hard to ignore!
const rgblight_segment_t PROGMEM my_capslock_layer[] = RGBLIGHT_LAYER_SEGMENTS(
{6, 4, HSV_RED}, // Light 4 LEDs, starting with LED 6
{12, 4, HSV_RED} // Light 4 LEDs, starting with LED 12
);
// Light LEDs 9 & 10 in cyan when keyboard layer 1 is active
const rgblight_segment_t PROGMEM my_layer1_layer[] = RGBLIGHT_LAYER_SEGMENTS(
{9, 2, HSV_CYAN}
);
// Light LEDs 11 & 12 in purple when keyboard layer 2 is active
const rgblight_segment_t PROGMEM my_layer2_layer[] = RGBLIGHT_LAYER_SEGMENTS(
{11, 2, HSV_PURPLE}
);
// etc..
```
We combine these layers into an array using the `RGBLIGHT_LAYERS_LIST` macro, and assign it to the `rgblight_layers` variable during keyboard setup. Note that you can only define up to 8 lighting layers. Any extra layers will be ignored. Since the different lighting layers overlap, the order matters in the array, with later layers taking precedence:
```c
// Now define the array of layers. Later layers take precedence
const rgblight_segment_t* const PROGMEM my_rgb_layers[] = RGBLIGHT_LAYERS_LIST(
my_capslock_layer,
my_layer1_layer, // Overrides caps lock layer
my_layer2_layer // Overrides other layers
);
void keyboard_post_init_user(void) {
// Enable the LED layers
rgblight_layers = my_rgb_layers;
}
```
Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers.
### Enabling and disabling lighting layers :id=enabling-lighting-layers
Everything above just configured the definition of each lighting layer.
We can now enable and disable the lighting layers whenever the state of the keyboard changes:
```c
layer_state_t layer_state_set_user(layer_state_t state) {
// Both layers will light up if both kb layers are active
rgblight_set_layer_state(1, layer_state_cmp(state, 1));
rgblight_set_layer_state(2, layer_state_cmp(state, 2));
return state;
}
bool led_update_user(led_t led_state) {
rgblight_set_layer_state(0, led_state.caps_lock);
return true;
}
```
### Lighting layer blink :id=lighting-layer-blink
By including `#define RGBLIGHT_LAYER_BLINK` in your `config.h` file you can turn a lighting
layer on for a specified duration. Once the specified number of milliseconds has elapsed
the layer will be turned off. This is useful, e.g., if you want to acknowledge some
action (e.g. toggling some setting):
```c
const rgblight_segment_t PROGMEM _yes_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_GREEN} );
const rgblight_segment_t PROGMEM _no_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_RED} );
const rgblight_segment_t* const PROGMEM _rgb_layers[] =
RGBLIGHT_LAYERS_LIST( _yes_layer, _no_layer );
void keyboard_post_init_user(void) {
rgblight_layers = _rgb_layers;
}
// Note we user post_process_record_user because we want the state
// after the flag has been flipped...
void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case DEBUG:
rgblight_blink_layer(debug_enable ? 0 : 1, 500);
break;
case NK_TOGG:
case NK_ON:
case NK_OFF:
rgblight_blink_layer(keymap_config.nkro ? 0 : 1, 500);
break;
}
}
```
### Overriding RGB Lighting on/off status
Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`.
## Functions
If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include:
### Utility Functions
|Function |Description |
|--------------------------------------------|-------------------------------------------------------------------|
|`sethsv(hue, sat, val, ledbuf)` |Set ledbuf to the given HSV value |
|`sethsv_raw(hue, sat, val, ledbuf)` |Set ledbuf to the given HSV value without RGBLIGHT_LIMIT_VAL check |
|`setrgb(r, g, b, ledbuf)` |Set ledbuf to the given RGB value where `r`/`g`/`b` |
### Low level Functions
|Function |Description |
|--------------------------------------------|-------------------------------------------|
|`rgblight_set()` |Flash out led buffers to LEDs |
|`rgblight_set_clipping_range(pos, num)` |Set clipping Range. see [Clipping Range](#clipping-range) |
Example:
```c
sethsv(HSV_WHITE, (LED_TYPE *)&led[0]); // led 0
sethsv(HSV_RED, (LED_TYPE *)&led[1]); // led 1
sethsv(HSV_GREEN, (LED_TYPE *)&led[2]); // led 2
rgblight_set(); // Utility functions do not call rgblight_set() automatically, so they need to be called explicitly.
```
### Effects and Animations Functions
#### effect range setting
|Function |Description |
|--------------------------------------------|------------------|
|`rgblight_set_effect_range(pos, num)` |Set Effects Range |
#### direct operation
|Function |Description |
|--------------------------------------------|-------------|
|`rgblight_setrgb_at(r, g, b, index)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `index` is between 0 and `RGBLED_NUM` (not written to EEPROM) |
|`rgblight_sethsv_at(h, s, v, index)` |Set a single LED to the given HSV value, where `h`/`s`/`v` are between 0 and 255, and `index` is between 0 and `RGBLED_NUM` (not written to EEPROM) |
|`rgblight_setrgb_range(r, g, b, start, end)`|Set a continuous range of LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `start`(included) and `stop`(excluded) are between 0 and `RGBLED_NUM` (not written to EEPROM)|
|`rgblight_sethsv_range(h, s, v, start, end)`|Set a continuous range of LEDs to the given HSV value, where `h`/`s`/`v` are between 0 and 255, and `start`(included) and `stop`(excluded) are between 0 and `RGBLED_NUM` (not written to EEPROM)|
|`rgblight_setrgb(r, g, b)` |Set effect range LEDs to the given RGB value where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) |
|`rgblight_setrgb_master(r, g, b)` |Set the LEDs on the master side to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) |
|`rgblight_setrgb_slave(r, g, b)` |Set the LEDs on the slave side to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) |
|`rgblight_sethsv_master(h, s, v)` |Set the LEDs on the master side to the given HSV value, where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
|`rgblight_sethsv_slave(h, s, v)` |Set the LEDs on the slave side to the given HSV value, where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
Example:
```c
rgblight_sethsv(HSV_WHITE, 0); // led 0
rgblight_sethsv(HSV_RED, 1); // led 1
rgblight_sethsv(HSV_GREEN, 2); // led 2
// The above functions automatically calls rgblight_set(), so there is no need to call it explicitly.
// Note that it is inefficient to call repeatedly.
```
#### effect mode change
|Function |Description |
|--------------------------------------------|-------------|
|`rgblight_mode(x)` |Set the mode, if RGB animations are enabled |
|`rgblight_mode_noeeprom(x)` |Set the mode, if RGB animations are enabled (not written to EEPROM) |
|`rgblight_step()` |Change the mode to the next RGB animation in the list of enabled RGB animations |
|`rgblight_step_noeeprom()` |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) |
|`rgblight_step_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations |
|`rgblight_step_reverse_noeeprom()` |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) |
#### effects mode disable/enable
|Function |Description |
|--------------------------------------------|-------------|
|`rgblight_toggle()` |Toggle effect range LEDs between on and off |
|`rgblight_toggle_noeeprom()` |Toggle effect range LEDs between on and off (not written to EEPROM) |
|`rgblight_enable()` |Turn effect range LEDs on, based on their previous state |
|`rgblight_enable_noeeprom()` |Turn effect range LEDs on, based on their previous state (not written to EEPROM) |
|`rgblight_disable()` |Turn effect range LEDs off |
|`rgblight_disable_noeeprom()` |Turn effect range LEDs off (not written to EEPROM) |
#### hue, sat, val change
|Function |Description |
|--------------------------------------------|-------------|
|`rgblight_increase_hue()` |Increase the hue for effect range LEDs. This wraps around at maximum hue |
|`rgblight_increase_hue_noeeprom()` |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) |
|`rgblight_decrease_hue()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue |
|`rgblight_decrease_hue_noeeprom()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) |
|`rgblight_increase_sat()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation |
|`rgblight_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation (not written to EEPROM) |
|`rgblight_decrease_sat()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation |
|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation (not written to EEPROM) |
|`rgblight_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value |
|`rgblight_increase_val_noeeprom()` |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) |
|`rgblight_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value |
|`rgblight_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) |
|`rgblight_sethsv(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
|`rgblight_sethsv_noeeprom(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
#### Speed functions
|Function |Description |
|--------------------------------------------|-------------|
|`rgblight_increase_speed()` |Increases the animation speed |
|`rgblight_increase_speed_noeeprom()` |Increases the animation speed (not written to EEPROM) |
|`rgblight_decrease_speed()` |Decreases the animation speed |
|`rgblight_decrease_speed_noeeprom()` |Decreases the animation speed (not written to EEPROM) |
|`rgblight_set_speed()` |Sets the speed. Value is between 0 and 255 |
|`rgblight_set_speed_noeeprom()` |Sets the speed. Value is between 0 and 255 (not written to EEPROM) |
#### layer functions
|Function |Description |
|--------------------------------------------|-------------|
|`rgblight_get_layer_state(i)` |Returns `true` if lighting layer `i` is enabled |
|`rgblight_set_layer_state(i, is_on)` |Enable or disable lighting layer `i` based on value of `bool is_on` |
#### query
|Function |Description |
|-----------------------|---------------------------|
|`rgblight_is_enabled()`|Gets current on/off status |
|`rgblight_get_mode()` |Gets current mode |
|`rgblight_get_hue()` |Gets current hue |
|`rgblight_get_sat()` |Gets current sat |
|`rgblight_get_val()` |Gets current val |
|`rgblight_get_speed()` |Gets current speed |
## Colors
These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
|RGB |HSV |
|-------------------|-------------------|
|`RGB_WHITE` |`HSV_WHITE` |
|`RGB_RED` |`HSV_RED` |
|`RGB_CORAL` |`HSV_CORAL` |
|`RGB_ORANGE` |`HSV_ORANGE` |
|`RGB_GOLDENROD` |`HSV_GOLDENROD` |
|`RGB_GOLD` |`HSV_GOLD` |
|`RGB_YELLOW` |`HSV_YELLOW` |
|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` |
|`RGB_GREEN` |`HSV_GREEN` |
|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` |
|`RGB_TURQUOISE` |`HSV_TURQUOISE` |
|`RGB_TEAL` |`HSV_TEAL` |
|`RGB_CYAN` |`HSV_CYAN` |
|`RGB_AZURE` |`HSV_AZURE` |
|`RGB_BLUE` |`HSV_BLUE` |
|`RGB_PURPLE` |`HSV_PURPLE` |
|`RGB_MAGENTA` |`HSV_MAGENTA` |
|`RGB_PINK` |`HSV_PINK` |
```c
rgblight_setrgb(RGB_ORANGE);
rgblight_sethsv_noeeprom(HSV_GREEN);
rgblight_setrgb_at(RGB_GOLD, 3);
rgblight_sethsv_range(HSV_WHITE, 0, 6);
```
These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
## Changing the order of the LEDs
If you want to make the logical order of LEDs different from the electrical connection order, you can do this by defining the `RGBLIGHT_LED_MAP` macro in your `config.h`.
Normally, the contents of the LED buffer are output to the LEDs in the same order.
<img src="https://user-images.githubusercontent.com/2170248/55743718-01866c80-5a6e-11e9-8134-25419928327a.JPG" alt="simple dicrect" width="50%"/>
By defining `RGBLIGHT_LED_MAP` as in the example below, you can specify the LED with addressing in reverse order of the electrical connection order.
```c
// config.h
#define RGBLED_NUM 4
#define RGBLIGHT_LED_MAP { 3, 2, 1, 0 }
```
<img src="https://user-images.githubusercontent.com/2170248/55743725-08ad7a80-5a6e-11e9-83ed-126a2b0209fc.JPG" alt="simple mapped" width="50%"/>
For keyboards that use the RGB LEDs as a backlight for each key, you can also define it as in the example below.
```c
// config.h
#define RGBLED_NUM 30
/* RGB LED Conversion macro from physical array to electric array */
#define LED_LAYOUT( \
L00, L01, L02, L03, L04, L05, \
L10, L11, L12, L13, L14, L15, \
L20, L21, L22, L23, L24, L25, \
L30, L31, L32, L33, L34, L35, \
L40, L41, L42, L43, L44, L45 ) \
{ \
L05, L04, L03, L02, L01, L00, \
L10, L11, L12, L13, L14, L15, \
L25, L24, L23, L22, L21, L20, \
L30, L31, L32, L33, L34, L35, \
L46, L45, L44, L43, L42, L41 \
}
/* RGB LED logical order map */
/* Top->Bottom, Right->Left */
#define RGBLIGHT_LED_MAP LED_LAYOUT( \
25, 20, 15, 10, 5, 0, \
26, 21, 16, 11, 6, 1, \
27, 22, 17, 12, 7, 2, \
28, 23, 18, 13, 8, 3, \
29, 24, 19, 14, 9, 4 )
```
## Clipping Range
Using the `rgblight_set_clipping_range()` function, you can prepare more buffers than the actual number of LEDs, and output some of the buffers to the LEDs. This is useful if you want the split keyboard to treat left and right LEDs as logically contiguous.
You can set the Clipping Range by executing the following code.
```c
// some source
rgblight_set_clipping_range(3, 4);
```
<img src="https://user-images.githubusercontent.com/2170248/55743785-2bd82a00-5a6e-11e9-9d4b-1b4ffaf4932b.JPG" alt="clip direct" width="70%"/>
In addition to setting the Clipping Range, you can use `RGBLIGHT_LED_MAP` together.
```c
// config.h
#define RGBLED_NUM 8
#define RGBLIGHT_LED_MAP { 7, 6, 5, 4, 3, 2, 1, 0 }
// some soruce
rgblight_set_clipping_range(3, 4);
```
<img src="https://user-images.githubusercontent.com/2170248/55743747-119e4c00-5a6e-11e9-91e5-013203ffae8a.JPG" alt="clip mapped" width="70%"/>
## Hardware Modification
If your keyboard lacks onboard underglow LEDs, you may often be able to solder on an RGB LED strip yourself. You will need to find an unused pin to wire to the data pin of your LED strip. Some keyboards may break out unused pins from the MCU to make soldering easier. The other two pins, VCC and GND, must also be connected to the appropriate power pins.

60
feature_space_cadet.md Normal file
View File

@ -0,0 +1,60 @@
# Space Cadet: The Future, Built In
Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds, and now even cooler supporting Control and Alt as well!
## Usage
Firstly, in your keymap, do one of the following:
- Replace the Left Shift key with `KC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `KC_RSPC` (Right Shift, Parenthesis Close).
- Replace the Left Control key with `KC_LCPO` (Left Control, Parenthesis Open), and Right Control with `KC_RCPC` (Right Control, Parenthesis Close).
- Replace the Left Alt key with `KC_LAPO` (Left Alt, Parenthesis Open), and Right Alt with `KC_RAPC` (Right Alt, Parenthesis Close).
- Replace any Shift key in your keymap with `KC_SFTENT` (Right Shift, Enter).
## Keycodes
|Keycode |Description |
|-----------|-------------------------------------------|
|`KC_LSPO` |Left Shift when held, `(` when tapped |
|`KC_RSPC` |Right Shift when held, `)` when tapped |
|`KC_LCPO` |Left Control when held, `(` when tapped |
|`KC_RCPC` |Right Control when held, `)` when tapped |
|`KC_LAPO` |Left Alt when held, `(` when tapped |
|`KC_RAPC` |Right Alt when held, `)` when tapped |
|`KC_SFTENT`|Right Shift when held, Enter when tapped |
## Caveats
Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. See the [Command feature](feature_command.md) for info on how to change it, or make sure that Command is disabled in your `rules.mk` with:
```make
COMMAND_ENABLE = no
```
## Configuration
By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifer` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `KC_LSPO` key with `KC_TRNS` as the `Tap Modifer`.
|Define |Default |Description |
|----------------|-------------------------------|---------------------------------------------------------------------------------|
|`LSPO_KEYS` |`KC_LSFT, LSPO_MOD, LSPO_KEY` |Send `KC_LSFT` when held, the mod and key defined by `LSPO_MOD` and `LSPO_KEY`. |
|`RSPC_KEYS` |`KC_RSFT, RSPC_MOD, RSPC_KEY` |Send `KC_RSFT` when held, the mod and key defined by `RSPC_MOD` and `RSPC_KEY`. |
|`LCPO_KEYS` |`KC_LCTL, KC_LSFT, KC_9` |Send `KC_LCTL` when held, the mod `KC_LSFT` with the key `KC_9` when tapped. |
|`RCPC_KEYS` |`KC_RCTL, KC_RSFT, KC_0` |Send `KC_RCTL` when held, the mod `KC_RSFT` with the key `KC_0` when tapped. |
|`LAPO_KEYS` |`KC_LALT, KC_LSFT, KC_9` |Send `KC_LALT` when held, the mod `KC_LSFT` with the key `KC_9` when tapped. |
|`RAPC_KEYS` |`KC_RALT, KC_RSFT, KC_0` |Send `KC_RALT` when held, the mod `KC_RSFT` with the key `KC_0` when tapped. |
|`SFTENT_KEYS` |`KC_RSFT, KC_TRNS, SFTENT_KEY` |Send `KC_RSFT` when held, no mod with the key `SFTENT_KEY` when tapped. |
|`SPACE_CADET_MODIFIER_CARRYOVER` |*Not defined* |Store current modifiers before the hold mod is pressed and use them with the tap mod and keycode. Useful for when you frequently release a modifier before triggering Space Cadet. |
## Obsolete Configuration
These defines are used in the above defines internally to support backwards compatibility, so you may continue to use them, however the above defines open up a larger range of flexibility than before. As an example, say you want to not send any modifier when you tap just `KC_LSPO`, with the old defines you had an all or nothing choice of using the `DISABLE_SPACE_CADET_MODIFIER` define. Now you can define that key as: `#define LSPO_KEYS KC_LSFT, KC_TRNS, KC_9`. This tells the system to set Left Shift if held or used with other keys, then on tap send no modifier (transparent) with the `KC_9`.
|Define |Default |Description |
|------------------------------|-------------|------------------------------------------------------------------|
|`LSPO_KEY` |`KC_9` |The keycode to send when Left Shift is tapped |
|`RSPC_KEY` |`KC_0` |The keycode to send when Right Shift is tapped |
|`LSPO_MOD` |`KC_LSFT` |The modifier to apply to `LSPO_KEY` |
|`RSPC_MOD` |`KC_RSFT` |The modifier to apply to `RSPC_KEY` |
|`SFTENT_KEY` |`KC_ENT` |The keycode to send when the Shift key is tapped |
|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet from applying a modifier |

246
feature_split_keyboard.md Normal file
View File

@ -0,0 +1,246 @@
# Split Keyboard
Many keyboards in the QMK Firmware repo are "split" keyboards. They use two controllers—one plugging into USB, and the second connected by a serial or an I<sup>2</sup>C connection over a TRRS or similar cable.
Split keyboards can have a lot of benefits, but there is some additional work needed to get them enabled.
QMK Firmware has a generic implementation that is usable by any board, as well as numerous board specific implementations.
For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards.
!> ARM is not yet fully supported for Split Keyboards and has many limitations. Progress is being made, but we have not yet reached 100% feature parity.
## Compatibility Overview
| Transport | AVR | ARM |
|------------------------------|--------------------|--------------------|
| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
| I2C | :heavy_check_mark: | |
Notes:
1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver.md).
## Hardware Configuration
This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves.
### Required Hardware
Apart from diodes and key switches for the keyboard matrix in each half, you will need 2x TRRS sockets and 1x TRRS cable.
Alternatively, you can use any sort of cable and socket that has at least 3 wires.
If you want to use I<sup>2</sup>C to communicate between halves, you will need a cable with at least 4 wires and 2x 4.7kΩ pull-up resistors.
#### Considerations
The most commonly used connection is a TRRS cable and jacks. These provide 4 wires, making them very useful for split keyboards, and are easy to find.
However, since one of the wires carries VCC, this means that the boards are not hot pluggable. You should always disconnect the board from USB before unplugging and plugging in TRRS cables, or you can short the controller, or worse.
Another option is to use phone cables (as in, old school RJ-11/RJ-14 cables). Make sure that you use one that actually supports 4 wires/lanes.
However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers.
!> Using USB cables for communication between the controllers works just fine, but the connector could be mistaken for a normal USB connection and potentially short out the keyboard, depending on how it's wired. For this reason, they are not recommended for connecting split keyboards.
### Serial Wiring
The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0/D1/D2/D3 (aka PD0/PD1/PD2/PD3) between the two Pro Micros.
?> Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below.
<img alt="sk-pd0-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296488-28e9ad80-ef70-11ea-98be-c40cb48a0319.JPG" width="48%"/>
<img alt="sk-pd2-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296490-2d15cb00-ef70-11ea-801f-5ace313013e6.JPG" width="48%"/>
### I<sup>2</sup>C Wiring
The 4 wires of the TRRS cable need to connect GND, VCC, and SCL and SDA (aka PD0/pin 3 and PD1/pin 2, respectively) between the two Pro Micros.
The pull-up resistors may be placed on either half. If you wish to use the halves independently, it is also possible to use 4 resistors and have the pull-ups in both halves.
<img alt="sk-i2c-connection-mono" src="https://user-images.githubusercontent.com/2170248/92297182-92b98580-ef77-11ea-9d7d-d6033914af43.JPG" width="50%"/>
## Firmware Configuration
To enable the split keyboard feature, add the following to your `rules.mk`:
```make
SPLIT_KEYBOARD = yes
```
If you're using a custom transport (communication method), then you will also need to add:
```make
SPLIT_TRANSPORT = custom
```
### Setting Handedness
By default, the firmware does not know which side is which; it needs some help to determine that. There are several ways to do this, listed in order of precedence.
#### Handedness by Pin
You can configure the firmware to read a pin on the controller to determine handedness. To do this, add the following to your `config.h` file:
```c
#define SPLIT_HAND_PIN B7
```
This will read the specified pin. If it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side.
#### Handedness by Matrix Pin
You can configure the firmware to read key matrix pins on the controller to determine handedness. To do this, add the following to your `config.h` file:
```c
#define SPLIT_HAND_MATRIX_GRID D0, F1
```
The first pin is the output pin and the second is the input pin.
Some keyboards have unused intersections in the key matrix. This setting uses one of these unused intersections to determine the handness.
Normally, when a diode is connected to an intersection, it is judged to be left. If you add the following definition, it will be judged to be right.
```c
#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT
```
#### Handedness by EEPROM
This method sets the keyboard's handedness by setting a flag in the persistent storage (`EEPROM`). This is checked when the controller first starts up, and determines what half the keyboard is, and how to orient the keyboard layout.
To enable this method, add the following to your `config.h` file:
```c
#define EE_HANDS
```
However, you'll have to flash the EEPROM files for the correct hand to each controller. You can do this manually, or there are targets for avrdude and dfu to do this, while flashing the firmware:
* `:avrdude-split-left`
* `:avrdude-split-right`
* `:dfu-split-left`
* `:dfu-split-right`
* `:dfu-util-split-left`
* `:dfu-util-split-right`
This setting is not changed when re-initializing the EEPROM using the `EEP_RST` key, or using the `eeconfig_init()` function. However, if you reset the EEPROM outside of the firmware's built in options (such as flashing a file that overwrites the `EEPROM`, like how the [QMK Toolbox]()'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files.
You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common).
#### Handedness by `#define`
You can set the handedness at compile time. This is done by adding the following to your `config.h` file:
```c
#define MASTER_RIGHT
```
or
```c
#define MASTER_LEFT
```
If neither are defined, the handedness defaults to `MASTER_LEFT`.
### Communication Options
Because not every split keyboard is identical, there are a number of additional options that can be configured in your `config.h` file.
```c
#define USE_I2C
```
This enables I<sup>2</sup>C support for split keyboards. This isn't strictly for communication, but can be used for OLED or other I<sup>2</sup>C-based devices.
```c
#define SOFT_SERIAL_PIN D0
```
This sets the pin to be used for serial communication. If you're not using serial, you shouldn't need to define this.
However, if you are using serial and I<sup>2</sup>C on the board, you will need to set this, and to something other than D0 and D1 (as these are used for I<sup>2</sup>C communication).
```c
#define SELECT_SOFT_SERIAL_SPEED {#}`
```
If you're having issues with serial communication, you can change this value, as it controls the communication speed for serial. The default is 1, and the possible values are:
* **`0`**: about 189kbps (Experimental only)
* **`1`**: about 137kbps (default)
* **`2`**: about 75kbps
* **`3`**: about 39kbps
* **`4`**: about 26kbps
* **`5`**: about 20kbps
### Hardware Configuration Options
There are some settings that you may need to configure, based on how the hardware is set up.
```c
#define MATRIX_ROW_PINS_RIGHT { <row pins> }
#define MATRIX_COL_PINS_RIGHT { <col pins> }
```
This allows you to specify a different set of pins for the matrix on the right side. This is useful if you have a board with differently-shaped halves that requires a different configuration (such as Keebio's Quefrency).
```c
#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }
```
This allows you to specify a different set of direct pins for the right side.
```c
#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a }
#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b }
```
This allows you to specify a different set of encoder pins for the right side.
```c
#define RGBLIGHT_SPLIT
```
This option enables synchronization of the RGB Light modes between the controllers of the split keyboard. This is for keyboards that have RGB LEDs that are directly wired to the controller (that is, they are not using the "extra data" option on the TRRS cable).
```c
#define RGBLED_SPLIT { 6, 6 }
```
This sets how many LEDs are directly connected to each controller. The first number is the left side, and the second number is the right side.
?> This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable it, if it's not.
```c
#define SPLIT_USB_DETECT
```
This option changes the startup behavior to detect an active USB connection when delegating master/slave. If this operation times out, then the half is assume to be a slave. This is the default behavior for ARM, and required for AVR Teensy boards (due to hardware limitations).
?> This setting will stop the ability to demo using battery packs.
```c
#define SPLIT_USB_TIMEOUT 2000
```
This sets the maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`.
```c
#define SPLIT_USB_TIMEOUT_POLL 10
```
This sets the poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
## Additional Resources
Nicinabox has a [very nice and detailed guide](https://github.com/nicinabox/lets-split-guide) for the Let's Split keyboard, that covers most everything you need to know, including troubleshooting information.
However, the RGB Light section is out of date, as it was written long before the RGB Split code was added to QMK Firmware. Instead, wire each strip up directly to the controller.
<!-- I may port this information later, but for now ... it's very nice, and covers everything -->

132
feature_stenography.md Normal file
View File

@ -0,0 +1,132 @@
# Stenography in QMK :id=stenography-in-qmk
[Stenography](https://en.wikipedia.org/wiki/Stenotype) is a method of writing most often used by court reports, closed-captioning, and real-time transcription for the deaf. In stenography words are chorded syllable by syllable with a mixture of spelling, phonetic, and shortcut (briefs) strokes. Professional stenographers can reach 200-300 WPM without any of the strain usually found in standard typing and with far fewer errors (>99.9% accuracy).
The [Open Steno Project](http://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports
## Plover with QWERTY Keyboard :id=plover-with-qwerty-keyboard
Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar.
To use Plover with QMK just enable NKRO and optionally adjust your layout if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys.
## Plover with Steno Protocol :id=plover-with-steno-protocol
Plover also understands the language of several steno machines. QMK can speak a couple of these languages, TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`.
When QMK speaks to Plover over a steno protocol Plover will not use the keyboard as input. This means that you can switch back and forth between a standard keyboard and your steno keyboard, or even switch layers from Plover to standard and back without needing to activate/deactivate Plover.
In this mode Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard. By default QMK will speak the TX Bolt protocol but can be switched to GeminiPR; the last protocol used is stored in non-volatile memory so QMK will use the same protocol on restart.
> Note: Due to hardware limitations you may not be able to run both a virtual serial port and mouse emulation at the same time.
### TX Bolt :id=tx-bolt
TX Bolt communicates the status of 24 keys over a very simple protocol in variable-sized (1-5 byte) packets.
### GeminiPR :id=geminipr
GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including supporting non-English theories.
## Configuring QMK for Steno :id=configuring-qmk-for-steno
Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them.
```makefile
STENO_ENABLE = yes
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
}
```
Once you have your keyboard flashed launch Plover. Click the 'Configure...' button. In the 'Machine' tab select the Stenotype Machine that corresponds to your desired protocol. Click the 'Configure...' button on this tab and enter the serial port or click 'Scan'. Baud rate is fine at 9600 (although you should be able to set as high as 115200 with no issues). Use the default settings for everything else (Data Bits: 8, Stop Bits: 1, Parity: N, no flow control).
On the display tab click 'Open stroke display'. With Plover disabled you should be able to hit keys on your keyboard and see them show up in the stroke display window. Use this to make sure you have set up your keymap correctly. You are now ready to steno!
## Learning Stenography :id=learning-stenography
* [Learn Plover!](https://sites.google.com/site/learnplover/)
* [QWERTY Steno](http://qwertysteno.com/Home/)
* [Steno Jig](https://joshuagrams.github.io/steno-jig/)
* More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki
## Interfacing with the code :id=interfacing-with-the-code
The steno code has three interceptable hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things.
```c
bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]);
```
This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen.
```c
bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; }
```
This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values.
```c
bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed);
```
This function is called after a key has been processed, but before any decision about whether or not to send a chord. If `IS_PRESSED(record->event)` is false, and `pressed` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This is where to put hooks for things like, say, live displays of steno chords or keys.
## Keycode Reference :id=keycode-reference
As defined in `keymap_steno.h`.
> Note: TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both.
|GeminiPR|TX Bolt|Steno Key|
|--------|-------|-----------|
|`STN_N1`|`STN_NUM`|Number bar #1|
|`STN_N2`|`STN_NUM`|Number bar #2|
|`STN_N3`|`STN_NUM`|Number bar #3|
|`STN_N4`|`STN_NUM`|Number bar #4|
|`STN_N5`|`STN_NUM`|Number bar #5|
|`STN_N6`|`STN_NUM`|Number bar #6|
|`STN_N7`|`STN_NUM`|Number bar #7|
|`STN_N8`|`STN_NUM`|Number bar #8|
|`STN_N9`|`STN_NUM`|Number bar #9|
|`STN_NA`|`STN_NUM`|Number bar #A|
|`STN_NB`|`STN_NUM`|Number bar #B|
|`STN_NC`|`STN_NUM`|Number bar #C|
|`STN_S1`|`STN_SL`| `S-` upper|
|`STN_S2`|`STN_SL`| `S-` lower|
|`STN_TL`|`STN_TL`| `T-`|
|`STN_KL`|`STN_KL`| `K-`|
|`STN_PL`|`STN_PL`| `P-`|
|`STN_WL`|`STN_WL`| `W-`|
|`STN_HL`|`STN_HL`| `H-`|
|`STN_RL`|`STN_RL`| `R-`|
|`STN_A`|`STN_A`| `A` vowel|
|`STN_O`|`STN_O`| `O` vowel|
|`STN_ST1`|`STN_STR`| `*` upper-left |
|`STN_ST2`|`STN_STR`| `*` lower-left|
|`STN_ST3`|`STN_STR`| `*` upper-right|
|`STN_ST4`|`STN_STR`| `*` lower-right|
|`STN_E`|`STN_E`| `E` vowel|
|`STN_U`|`STN_U`| `U` vowel|
|`STN_FR`|`STN_FR`| `-F`|
|`STN_PR`|`STN_PR`| `-P`|
|`STN_RR`|`STN_RR`| `-R`|
|`STN_BR`|`STN_BR`| `-B`|
|`STN_LR`|`STN_LR`| `-L`|
|`STN_GR`|`STN_GR`| `-G`|
|`STN_TR`|`STN_TR`| `-T`|
|`STN_SR`|`STN_SR`| `-S`|
|`STN_DR`|`STN_DR`| `-D`|
|`STN_ZR`|`STN_ZR`| `-Z`|
|`STN_FN`|| (GeminiPR only)|
|`STN_RES1`||(GeminiPR only)|
|`STN_RES2`||(GeminiPR only)|
|`STN_PWR`||(GeminiPR only)|

31
feature_swap_hands.md Normal file
View File

@ -0,0 +1,31 @@
# Swap-Hands Action
The swap-hands action allows support for one-handed typing without requiring a separate layer. Set `SWAP_HANDS_ENABLE` in the Makefile and define a `hand_swap_config` entry in your keymap. Now whenever the `ACTION_SWAP_HANDS` command key is pressed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd`
## Configuration
The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck:
```C
const keypos_t hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = {
{{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}},
{{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}},
{{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}},
{{11, 3}, {10, 3}, {9, 3}, {8, 3}, {7, 3}, {6, 3}, {5, 3}, {4, 3}, {3, 3}, {2, 3}, {1, 3}, {0, 3}},
};
```
Note that the array indices are reversed same as the matrix and the values are of type `keypos_t` which is `{col, row}` and all values are zero-based. In the example above, `hand_swap_config[2][4]` (third row, fifth column) would return `{7, 2}` (third row, eighth column). Yes, this is confusing.
## Swap Keycodes
|Key |Description |
|-----------|-------------------------------------------------------------------------|
|`SH_T(key)`|Sends `key` with a tap; momentary swap when held. |
|`SH_ON` |Turns on swapping and leaves it on. |
|`SH_OFF` |Turn off swapping and leaves it off. Good for returning to a known state.|
|`SH_MON` |Swaps hands when pressed, returns to normal when released (momentary). |
|`SH_MOFF` |Momentarily turns off swap. |
|`SH_TG` |Toggles swap on and off with every key press. |
|`SH_TT` |Toggles with a tap; momentary when held. |
|`SH_OS` |One shot swap hands: toggles while pressed or until next key press. |

512
feature_tap_dance.md Normal file
View File

@ -0,0 +1,512 @@
# Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things
## Introduction :id=introduction
Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature:
With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter.
## How to Use Tap Dance :id=how-to-use
First, you will need `TAP_DANCE_ENABLE = yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size.
Optionally, you might want to set a custom `TAPPING_TERM` time by adding something like this in you `config.h`:
```c
#define TAPPING_TERM 175
```
The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead.
Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that takes a number which will later be used as an index into the `tap_dance_actions` array.
After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options:
* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. When the key is held, the appropriate keycode is registered: `kc1` when pressed and held, `kc2` when tapped once, then pressed and held.
* `ACTION_TAP_DANCE_LAYER_MOVE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` layer keycode).
* This is the same as `ACTION_TAP_DANCE_DUAL_ROLE`, but renamed to something that is clearer about its functionality. Both names will work.
* `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: Sends the `kc` keycode when tapped once, or toggles the state of `layer`. (this functions like the `TG` layer keycode).
* `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.
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.
!> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported.
Similar to the first option, the second option is good for simple layer-switching cases.
For more complicated cases, use the third or fourth options (examples of each are listed below).
Finally, the fifth option is particularly useful if your non-Tap-Dance keys start behaving weirdly after adding the code for your Tap Dance keys. The likely problem is that you changed the `TAPPING_TERM` time to make your Tap Dance keys easier for you to use, and that this has changed the way your other keys handle interrupts.
## Implementation Details :id=implementation
Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works!
The main entry point is `process_tap_dance()`, called from `process_record_quantum()`, which is run for every keypress, and our handler gets to run early. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. If it was the same, we increment the counter and reset the timer.
This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness.
Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-dance keys.
For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros.
## Examples :id=examples
### Simple Example :id=simple-example
Here's a simple example for a single definition:
1. In your `rules.mk`, add `TAP_DANCE_ENABLE = yes`
2. In your `config.h` (which you can copy from `qmk_firmware/keyboards/planck/config.h` to your keymap directory), add `#define TAPPING_TERM 200`
3. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
```c
// Tap Dance declarations
enum {
TD_ESC_CAPS,
};
// Tap Dance definitions
qk_tap_dance_action_t tap_dance_actions[] = {
// Tap once for Escape, twice for Caps Lock
[TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS),
};
// Add tap dance item in place of a key code
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
// ...
TD(TD_ESC_CAPS)
// ...
};
```
### Complex Examples :id=complex-examples
This section details several complex tap dance examples.
All the enums used in the examples are declared like this:
```c
// Enums defined for all examples:
enum {
CT_SE,
CT_CLN,
CT_EGG,
CT_FLSH,
X_TAP_DANCE
};
```
#### Example 1: Send `:` on Single Tap, `;` on Double Tap :id=example-1
```c
void dance_cln_finished(qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
register_code16(KC_COLN);
} else {
register_code(KC_SCLN);
}
}
void dance_cln_reset(qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
unregister_code16(KC_COLN);
} else {
unregister_code(KC_SCLN);
}
}
// All tap dance functions would go here. Only showing this one.
qk_tap_dance_action_t tap_dance_actions[] = {
[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
};
```
#### Example 2: Send "Safety Dance!" After 100 Taps :id=example-2
```c
void dance_egg(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 100) {
SEND_STRING("Safety dance!");
reset_tap_dance(state);
}
}
qk_tap_dance_action_t tap_dance_actions[] = {
[CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
};
```
#### Example 3: Turn LED Lights On Then Off, One at a Time :id=example-3
```c
// On each tap, light up one LED, from right to left
// On the fourth tap, turn them off from right to left
void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
switch (state->count) {
case 1:
ergodox_right_led_3_on();
break;
case 2:
ergodox_right_led_2_on();
break;
case 3:
ergodox_right_led_1_on();
break;
case 4:
ergodox_right_led_3_off();
wait_ms(50);
ergodox_right_led_2_off();
wait_ms(50);
ergodox_right_led_1_off();
}
}
// On the fourth tap, set the keyboard on flash state
void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 4) {
reset_keyboard();
}
}
// If the flash state didn't happen, then turn off LEDs, left to right
void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
ergodox_right_led_1_off();
wait_ms(50);
ergodox_right_led_2_off();
wait_ms(50);
ergodox_right_led_3_off();
}
// All tap dances now put together. Example 3 is "CT_FLASH"
qk_tap_dance_action_t tap_dance_actions[] = {
[CT_SE] = ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT),
[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
[CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED(dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
};
```
#### Example 4: 'Quad Function Tap-Dance' :id=example-4
By [DanielGGordon](https://github.com/danielggordon)
Allow one key to have 4 (or more) functions, depending on number of presses, and if the key is held or tapped.
Below is a specific example:
* Tap = Send `x`
* Hold = Send `Control`
* Double Tap = Send `Escape`
* Double Tap and Hold = Send `Alt`
You will need a few things that can be used for 'Quad Function Tap-Dance'.
You'll need to add these to the top of your `keymap.c` file, before your keymap.
```c
typedef struct {
bool is_press_action;
uint8_t state;
} tap;
enum {
SINGLE_TAP = 1,
SINGLE_HOLD,
DOUBLE_TAP,
DOUBLE_HOLD,
DOUBLE_SINGLE_TAP, // Send two single taps
TRIPLE_TAP,
TRIPLE_HOLD
};
// Tap dance enums
enum {
X_CTL,
SOME_OTHER_DANCE
};
uint8_t cur_dance(qk_tap_dance_state_t *state);
// For the x tap dance. Put it here so it can be used in any keymap
void x_finished(qk_tap_dance_state_t *state, void *user_data);
void x_reset(qk_tap_dance_state_t *state, void *user_data);
```
Now, at the bottom of your `keymap.c` file, you'll need to add the following:
```c
/* Return an integer that corresponds to what kind of tap dance should be executed.
*
* How to figure out tap dance state: interrupted and pressed.
*
* Interrupted: If the state of a dance dance is "interrupted", that means that another key has been hit
* under the tapping term. This is typically indicitive that you are trying to "tap" the key.
*
* Pressed: Whether or not the key is still being pressed. If this value is true, that means the tapping term
* has ended, but the key is still being pressed down. This generally means the key is being "held".
*
* One thing that is currenlty not possible with qmk software in regards to tap dance is to mimic the "permissive hold"
* feature. In general, advanced tap dances do not work well if they are used with commonly typed letters.
* For example "A". Tap dances are best used on non-letter keys that are not hit while typing letters.
*
* Good places to put an advanced tap dance:
* z,q,x,j,k,v,b, any function key, home/end, comma, semi-colon
*
* Criteria for "good placement" of a tap dance key:
* Not a key that is hit frequently in a sentence
* Not a key that is used frequently to double tap, for example 'tab' is often double tapped in a terminal, or
* in a web form. So 'tab' would be a poor choice for a tap dance.
* Letters used in common words as a double. For example 'p' in 'pepper'. If a tap dance function existed on the
* letter 'p', the word 'pepper' would be quite frustating to type.
*
* For the third point, there does exist the 'DOUBLE_SINGLE_TAP', however this is not fully tested
*
*/
uint8_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) {
if (state->interrupted || !state->pressed) return SINGLE_TAP;
// Key has not been interrupted, but the key is still held. Means you want to send a 'HOLD'.
else return SINGLE_HOLD;
} else if (state->count == 2) {
// DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap
// action when hitting 'pp'. Suggested use case for this return value is when you want to send two
// keystrokes of the key, and not the 'double tap' action/macro.
if (state->interrupted) return DOUBLE_SINGLE_TAP;
else if (state->pressed) return DOUBLE_HOLD;
else return DOUBLE_TAP;
}
// Assumes no one is trying to type the same letter three times (at least not quickly).
// If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add
// an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP'
if (state->count == 3) {
if (state->interrupted || !state->pressed) return TRIPLE_TAP;
else return TRIPLE_HOLD;
} else return 8; // Magic number. At some point this method will expand to work for more presses
}
// Create an instance of 'tap' for the 'x' tap dance.
static tap xtap_state = {
.is_press_action = true,
.state = 0
};
void x_finished(qk_tap_dance_state_t *state, void *user_data) {
xtap_state.state = cur_dance(state);
switch (xtap_state.state) {
case SINGLE_TAP: register_code(KC_X); break;
case SINGLE_HOLD: register_code(KC_LCTRL); break;
case DOUBLE_TAP: register_code(KC_ESC); break;
case DOUBLE_HOLD: register_code(KC_LALT); break;
// Last case is for fast typing. Assuming your key is `f`:
// For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`.
// In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms.
case DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X);
}
}
void x_reset(qk_tap_dance_state_t *state, void *user_data) {
switch (xtap_state.state) {
case SINGLE_TAP: unregister_code(KC_X); break;
case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
case DOUBLE_TAP: unregister_code(KC_ESC); break;
case DOUBLE_HOLD: unregister_code(KC_LALT);
case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
}
xtap_state.state = 0;
}
qk_tap_dance_action_t tap_dance_actions[] = {
[X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset)
};
```
And then simply use `TD(X_CTL)` anywhere in your keymap.
If you want to implement this in your userspace, then you may want to check out how [DanielGGordon](https://github.com/qmk/qmk_firmware/tree/master/users/gordon) has implemented this in their userspace.
> In this configuration "hold" takes place **after** tap dance timeout (see `ACTION_TAP_DANCE_FN_ADVANCED_TIME`). To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`).
#### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5
Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`.
Below your layers and custom keycodes, add the following:
```c
// Tap Dance keycodes
enum td_keycodes {
ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance.
};
// Define a type containing as many tapdance states as you need
typedef enum {
SINGLE_TAP,
SINGLE_HOLD,
DOUBLE_SINGLE_TAP
} td_state_t;
// Create a global instance of the tapdance state type
static td_state_t td_state;
// Declare your tapdance functions:
// Function to determine the current tapdance state
uint8_t cur_dance(qk_tap_dance_state_t *state);
// `finished` and `reset` functions for each tapdance keycode
void altlp_finished(qk_tap_dance_state_t *state, void *user_data);
void altlp_reset(qk_tap_dance_state_t *state, void *user_data);
```
Below your `LAYOUT`, define each of the tapdance functions:
```c
// Determine the tapdance state to return
uint8_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) {
if (state->interrupted || !state->pressed) return SINGLE_TAP;
else return SINGLE_HOLD;
}
if (state->count == 2) return DOUBLE_SINGLE_TAP;
else return 3; // Any number higher than the maximum state value you return above
}
// Handle the possible states for each tapdance keycode you define:
void altlp_finished(qk_tap_dance_state_t *state, void *user_data) {
td_state = cur_dance(state);
switch (td_state) {
case SINGLE_TAP:
register_code16(KC_LPRN);
break;
case SINGLE_HOLD:
register_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_on(_MY_LAYER)` here
break;
case DOUBLE_SINGLE_TAP: // Allow nesting of 2 parens `((` within tapping term
tap_code16(KC_LPRN);
register_code16(KC_LPRN);
}
}
void altlp_reset(qk_tap_dance_state_t *state, void *user_data) {
switch (td_state) {
case SINGLE_TAP:
unregister_code16(KC_LPRN);
break;
case SINGLE_HOLD:
unregister_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_off(_MY_LAYER)` here
break;
case DOUBLE_SINGLE_TAP:
unregister_code16(KC_LPRN);
}
}
// Define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions
qk_tap_dance_action_t tap_dance_actions[] = {
[ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset)
};
```
Wrap each tapdance keycode in `TD()` when including it in your keymap, e.g. `TD(ALT_LP)`.
#### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys :id=example-6
Tap Dance can be used to mimic MO(layer) and TG(layer) functionality. For this example, we will set up a key to function as `KC_QUOT` on single-tap, as `MO(_MY_LAYER)` on single-hold, and `TG(_MY_LAYER)` on double-tap.
The first step is to include the following code towards the beginning of your `keymap.c`:
```c
typedef struct {
bool is_press_action;
uint8_t state;
} tap;
// Define a type for as many tap dance states as you need
enum {
SINGLE_TAP = 1,
SINGLE_HOLD,
DOUBLE_TAP
};
enum {
QUOT_LAYR, // Our custom tap dance key; add any other tap dance keys to this enum
};
// Declare the functions to be used with your tap dance key(s)
// Function associated with all tap dances
uint8_t cur_dance(qk_tap_dance_state_t *state);
// Functions associated with individual tap dances
void ql_finished(qk_tap_dance_state_t *state, void *user_data);
void ql_reset(qk_tap_dance_state_t *state, void *user_data);
```
Towards the bottom of your `keymap.c`, include the following code:
```c
// Determine the current tap dance state
uint8_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) {
if (!state->pressed) return SINGLE_TAP;
else return SINGLE_HOLD;
} else if (state->count == 2) return DOUBLE_TAP;
else return 8;
}
// Initialize tap structure associated with example tap dance key
static tap ql_tap_state = {
.is_press_action = true,
.state = 0
};
// Functions that control what our tap dance key does
void ql_finished(qk_tap_dance_state_t *state, void *user_data) {
ql_tap_state.state = cur_dance(state);
switch (ql_tap_state.state) {
case SINGLE_TAP:
tap_code(KC_QUOT);
break;
case SINGLE_HOLD:
layer_on(_MY_LAYER);
break;
case DOUBLE_TAP:
// Check to see if the layer is already set
if (layer_state_is(_MY_LAYER)) {
// If already set, then switch it off
layer_off(_MY_LAYER);
} else {
// If not already set, then switch the layer on
layer_on(_MY_LAYER);
}
break;
}
}
void ql_reset(qk_tap_dance_state_t *state, void *user_data) {
// If the key was held down and now is released then switch off the layer
if (ql_tap_state.state == SINGLE_HOLD) {
layer_off(_MY_LAYER);
}
ql_tap_state.state = 0;
}
// Associate our tap dance key with its functionality
qk_tap_dance_action_t tap_dance_actions[] = {
[QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
};
```
The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is(layer)` function which returns `true` if the given `layer` is active.
The use of `cur_dance()` and `ql_tap_state` mirrors the above examples.
The `case:SINGLE_TAP` in `ql_finished` is similar to the above examples. The `SINGLE_HOLD` case works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `DOUBLE_TAP` case works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`.
`tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (\~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here.
Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`.

107
feature_terminal.md Normal file
View File

@ -0,0 +1,107 @@
# Terminal
> This feature is currently *huge*, and should probably only be put on boards with a lot of memory, or for fun.
The terminal feature is a command-line-like interface designed to communicate through a text editor with keystrokes. It's beneficial to turn off auto-indent features in your editor.
To enable, stick this in your `rules.mk` or `Makefile`:
TERMINAL_ENABLE = yes
And use the `TERM_ON` and `TERM_OFF` keycodes to turn it on or off.
When enabled, a `> ` prompt will appear, where you'll be able to type, backspace (a bell will ding if you reach the beginning and audio is enabled), and hit enter to send the command. Arrow keys are currently disabled so it doesn't get confused. Moving your cursor around with the mouse is discouraged.
`#define TERMINAL_HELP` enables some other output helpers that aren't really needed with this page.
Pressing "up" and "down" will allow you to cycle through the past 5 commands entered.
## Future Ideas
* Keyboard/user-extensible commands
* Smaller footprint
* Arrow key support
* Command history - Done
* SD card support
* LCD support for buffer display
* Keycode -> name string LUT
* Layer status
* *Analog/digital port read/write*
* RGB mode stuff
* Macro definitions
* EEPROM read/write
* Audio control
## Current Commands
### `about`
Prints out the current version of QMK with a build date:
```
> about
QMK Firmware
v0.5.115-7-g80ed73-dirty
Built: 2017-08-29-20:24:44
```
### `print-buffer`
Outputs the last 5 commands entered
```
> print-buffer
0. print-buffer
1. help
2. about
3. keymap 0
4. help
5. flush-buffer
```
### `flush-buffer`
Clears command buffer
```
> flush-buffer
Buffer cleared!
```
### `help`
Prints out the available commands:
```
> help
commands available:
about help keycode keymap exit print-buffer flush-buffer
```
### `keycode <layer> <row> <col>`
Prints out the keycode value of a certain layer, row, and column:
```
> keycode 0 1 0
0x29 (41)
```
### `keymap <layer>`
Prints out the entire keymap for a certain layer
```
> keymap 0
0x002b, 0x0014, 0x001a, 0x0008, 0x0015, 0x0017, 0x001c, 0x0018, 0x000c, 0x0012, 0x0013, 0x002a,
0x0029, 0x0004, 0x0016, 0x0007, 0x0009, 0x000a, 0x000b, 0x000d, 0x000e, 0x000f, 0x0033, 0x0034,
0x00e1, 0x001d, 0x001b, 0x0006, 0x0019, 0x0005, 0x0011, 0x0010, 0x0036, 0x0037, 0x0038, 0x0028,
0x5cd6, 0x00e0, 0x00e2, 0x00e3, 0x5cd4, 0x002c, 0x002c, 0x5cd5, 0x0050, 0x0051, 0x0052, 0x004f,
>
```
### `exit`
Exits the terminal - same as `TERM_OFF`.

10
feature_thermal_printer.md Normal file
View File

@ -0,0 +1,10 @@
# Thermal Printer
<!-- FIXME: Describe thermal printers support here. -->
## Thermal Printer Keycodes
|Key |Description |
|-----------|----------------------------------------|
|`PRINT_ON` |Start printing everything the user types|
|`PRINT_OFF`|Stop printing everything the user types |

Some files were not shown because too many files have changed in this diff Show More