t9/qmk-firmware
Watch
1
0
Fork
You've already forked qmk-firmware
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Deploying to gh-pages from master @ aae3b35c0f 🚀

Browse source
This commit is contained in:
skullydazed 2020-11-10 15:02:44 +00:00
commit e9694e7218
375 changed files with 44952 additions and 0 deletions
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`) |

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