* redo make args to use colons, better folder structuring system [skip ci]
* don't put spaces after statements - hard lessons in makefile development
* fix-up some other rules.mk
* give travis a chance
* reset KEYMAPS variable
* start converting keyboards to new system
* try making all with travis
* redo make args to use colons, better folder structuring system [skip ci]
* don't put spaces after statements - hard lessons in makefile development
* fix-up some other rules.mk
* give travis a chance
* reset KEYMAPS variable
* start converting keyboards to new system
* try making all with travis
* start to update readmes and keyboards
* look in keyboard directories for board.mk
* update visualizer rules
* fix up some other keyboards/keymaps
* fix arm board ld includes
* fix board rules
* fix up remaining keyboards
* reset layout variable
* reset keyboard_layouts
* fix remainging keymaps/boards
* update readmes, docs
* add note to makefile error
* update readmes
* remove planck keymap warnings
* update references and docs
* test out tarvis build stages
* don't use stages for now
* don't use stages for now
* add ymd96 base
currently not working correctly.
* Update
honestly not really sure what I've been doing but I'm just more or less brute forcing this until I can get the pcb schematic or something
* honestly just trying stuff out
* Update keymaps
Getting closer hopefully
* ymd96 works!
at least for me
* Update readme
* Update readme
* Update readme
* Adds support for multiple layouts. Adds custom keymap for "offset"
layout.
* Adds a tool to help detach the keyboard from the Linux HID driver before programming.
* Adds a tool to help detach the keyboard from the Linux HID driver before programming.
- a keyboard already in bootloader mode will now be detected
- if setting the keyboard to bootloader mode doesn't work, a hint will be printed on how to do so
- instead of failing instantly when no keyboard is found, the script will now wait up to 60 seconds (it retries every 5 seconds, up to 12 times)
At one time, "ez" and "infinity" may have been subprojects of a
unified "ergodox" project, but this is not currently the case. Running
`make ergodox-ez-default-teensy` (or similar), as the documentation
currently implies, does not work.
neue Datei: keyboards/lets_split/keymaps/DE_simple/config.h
neue Datei: keyboards/lets_split/keymaps/DE_simple/keymap.c
neue Datei: keyboards/lets_split/keymaps/DE_simple/rules.mk
* slight modifier changes; added plover and reusing jack's default planck keymap as the basis
* space is not shift when held anymore
* added fabian layout (based on jack's default)
* changed fabian layout (based on jack's default)
* changed fabian layout (based on jack's default)
* Fix mbsurfer let's split layout RGB indicators when both lower and raise are pressed
* Update mbsurfer let's split keymap with new RGB key codes for modes
* Clean up mbsurfer keymap matrix layout
Overall changes
===============
* Updated to work with QMK master.
* The `$` and `^` symbols on the number row were swapped on both the base and
the ADORE layers.
* The bracket tap-dance keys can now be used to input Japanese brackets, `「`
and `」` with a third tap.
* The second column of the top row on the right side will act as a "Social"
application selector on the `AppSel` layer.
* The third key on the same column will select a password manager.
* The `GUI` key will now launch `rofi` when triple-tapped.
Miscellaneous
=============
* The `👶` symbol can be entered with UCIS.
* The `👪` symbol can be entered with UCIS.
Tools
=====
* `tools/hid-commands` can now find the `Mstdn`, not just `Slack`, as the
"Slack"/chat app.
* `tools/hid-commands` can now find the Plex web app as a music/media player.
* `tools/hid-commands` now understands the "Social" application selector. It
raises the `Mstdn` and `Tweetdeck` windows, but keeps focus on the previous
window.
* `tools/hid-commands` now understands the "Social2" application selector, which
raises `Signal` and `Viber`, but keeps focus on the previous window.
* `tools/hid-commands` is now able to select a password manager (KeePass*).
* `tools/hid-commands` can now run `rofi` when receiving an `appsel_helper`
command (triggered by a triple-tapped `GUI` key).
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* initial clueboard_60 support
* LED lighting support
* fix the clueboard->clueboard_66 rename
* Add layout support to clueboard_60
* Fix the 60_iso layout so it's actually iso
* add a default keymap for AEK layout
* fix clueboard_17
* Fixup the ISO layouts
* Fix the `wait_ms()/wait_us()` definitions for chibios
* Fix up the wait_ms/wait_us hack. Reduce stack size.
* Add a missing #include "wait.h"
* commit files that should have already been comitted
* Support for KBP V60 Type R 60% keyboard
Support does not include in switch or underglow lighting for Polestar Edition.
* rename v60type_r to v60_type_r
* Remove old v60type_r
* Modify readme.md to adhere with QMK readme formatting.
tearing it down so that it can be rebuilt
fiddling with audio
big default config overhaul
apparently startup sounds work without the override now
readme!
readme fixes
readme tweaking
* Add yuuki keymap
Documentation is still a TODO and the keymap may not be final
* GRV on colon
* add KC_GRV to FN ESC
* hhkb ish
* hhkbish 2
* HHKBish and documentation
* Fix Markdown warnings
* typo
* phreed keymap added
This keymap moves many pinky keys to the center
* set to do what I want but LT() does not return to previous layer
* get overlays working
* get overlays working
* fix the readme
* fix the readme
* swapped the shift
* swapped the shift
* propagate mods
* clear special char on readme
* Implement sticky modifiers
* Change underglow based on sticky mod status
* Set RGB lights based on which mods are stickied
* Add controls for dimming RGB LEDs
* Only update RGB lights if modifiers have changed
* Use all LEDs to show modifier state
* Create default keymap for Viterbi
* Duplicate default layout as basis of my own
* Basic Colemak layer, just to practice flashing
* Add reset button so that we don't have to short out the reset button on the board to flash it.
* Symbols layer
* Navigation layer, and remove unused keys. Now usable, nice.
* Correct backspace for UK QWERTY mapping
* Small clarification in XD75RE readme instructions
* Use UK pipe so that I can type a pipe on a UK keyboard
* adding new layout for the planck that helps when coming from the pok3r
* Fixing the function layer
* Update readme.md
* Update keymap.c
Making some small adjustments
* Update keymap.c
switching GUI and Esc
* Update keymap.c
* changed 'infinity' to 'ergodox_infinity' and specified to be in the top-level directory as per recent changes to directory structure of QMK_firmware git repo
* accidently removed '-' in last line of readme
* add new RGB keycodes and clean up lets split keymap
* extraneous cases
* More cleanup and added macro
* one more macro
* cleaned up my planck keymap and added macros
* Transitioned planck keymap to new formatting / audio modes based on new default
* Remove extraneous newline in song list, add keycodes missed in previous commit
* error in graphical representation of keycodes
* Merge with upstream
* Finish merge
* Add new keymap
* Change use of KEYMAP macro
* Add Readme.md
* Fix link
* Clean up comments
* Raise on leading edge of keypress
* Add HOME/END keys as upper/lower on arrow-up/down
* Reduce .hex file size by turning off unneeded options
* Put digit keypad onto left hand upon RAISE; this will sometimes be preferable to double-hits of right hand
* Latest super latest version merge
* cbbrowne keymap for XD75re
* starting notes on XD75re keymap plans
* First draft of bottom row of QWERTY
* Switch my special bottom line over to QCENT
* Dunno
* Filling in wanted keys, bit by bit...
* Add copyright, extra macro
* Clean up comments, remove some experimental code I didn't like
* TODO plans for xd75re
* clean up keyboard layout
* QCENT2 is my new experiment for the main keyboard...
* Add a few more main layer keys, and modify LOWER to shift things outwards to conform with main layer
* Clean up RAISE layer to conform with main layer, remove QCENT layer as QCENT2 is the new thing
* More xd75 changes, now that I actually have it in hand
* shift keymap around, as original attempt was a bit too aggressive in keeping to the edges
* more revs to XD75
* Dropping parts of the centre keypad in favor of Keys I Really Need
* Improve documentation to conform with how builds are done now
* Improve documentation to conform with how builds are done now
* Add cbbrowne rules file as alternative to having the rules in Makefile
* Makefile not needed anymore for individual keymap
* Remove all Makefiles from the keyboards directory.
* update keymaps added in the last 8 days
* Ignore keyboard/keymap makefiles
* update hand_wire to reflect our new Makefile-less reality
* Update the make guide to reflect the new reality
* move planck keymap options to rules.mk
* update planck keymaps 4real
* trigger travis
* add back build_keyboard.mk
* restore changes to build_keyboard
* Allow the knight animation to be restricted to a portion of the LED strip
* Add keys for jumping directly to particular animation modes
* Remove orphaned break statements
* Tweak the `RGB_MODE` buttons so they cycle through the same mode.
* small indentation fix
* Add a new revision of the clueboard with 18 underlight LEDs
* Allow the knight animation to be restricted to a portion of the LED strip
* Add keys for jumping directly to particular animation modes
* Remove orphaned break statements
* Tweak the `RGB_MODE` buttons so they cycle through the same mode.
* small indentation fix
`avr-libc` is no longer, and it's called `avr-gcc` now. https://github.com/osx-cross/homebrew-avr
Also you need `gcc-arc-none-eabi` to be able to compile in my experience.
* copied mjt keymaps from archive
* All mjt boards now compile
* fixed jd45-mjt breathing
* Updates to fix SpaceFN but not tested yet.
* Still missing either spacebar or an adjacent keypress.
* Debugging rigged up for use with hid_listen.
* Reverted the default keymap to use tap_layer_key rather than custom. Moved custom approach to keymap_debug.c
* Fixed the lower-left side of the keymap, which needed more spacers due to the matrix being directly put into the array rather than using the keymap function.
* Cleaned up JD45 keymap that uses tapkey.
* Redid minivan keymap with numsym rather than raise/lower.
Untested.
* Created my MJT keymap for HHKB
Enabled dynamic macros and moved
somoe of the shortcuts around.
* Minor keymap fixes to make them compile without errors.
* Added home/end to right arrow cluster on DYN layer.
* Added more keys to fn and dyn layers.
* It wasn't using my custom layer last time somehow...? Now it will.
* Compiled and installed at end of day on 8/23
* Moved macros to FKEY layer because Adjust was too hard to get into and out of without some sort of feedback.
* Fixed volume controls... were reversed and disabled.
* Added F13-F15 back to fkeys layer in Minivan
* Created new Planck Keymap that uses the NumSym and FKeys layer approach like the Minivan.
* Removed DYN layer.
* Fixed diagram in planck numsym.
* Cleanup for pull request.
* Roadkit flip phone warning.
* Replaced PLAY_NOTES_ARRAY to PLAY_SONG
* reset the submodules
* checked out specific commits for submodules
* Removed debugging from JD45 shared config.h
* Moved custom rules.mk to apropriate keymap
Reset the shared rules.mk file.
* Trailing return issue in rules.mk
Gotta make for a smooth pull request :-)
* Mitosis music troubleshooting
Also updated the song playing function.
Does not work currently.
* Fixed mitosis audio
* Put mitosis/rules.mk back to QMK master
* copied mjt keymaps from archive
* All mjt boards now compile
* fixed jd45-mjt breathing
* Updates to fix SpaceFN but not tested yet.
* Still missing either spacebar or an adjacent keypress.
* Debugging rigged up for use with hid_listen.
* Reverted the default keymap to use tap_layer_key rather than custom. Moved custom approach to keymap_debug.c
* Fixed the lower-left side of the keymap, which needed more spacers due to the matrix being directly put into the array rather than using the keymap function.
* Cleaned up JD45 keymap that uses tapkey.
* Redid minivan keymap with numsym rather than raise/lower.
Untested.
* Created my MJT keymap for HHKB
Enabled dynamic macros and moved
somoe of the shortcuts around.
* Minor keymap fixes to make them compile without errors.
* Added home/end to right arrow cluster on DYN layer.
* Added more keys to fn and dyn layers.
* It wasn't using my custom layer last time somehow...? Now it will.
* Compiled and installed at end of day on 8/23
* Moved macros to FKEY layer because Adjust was too hard to get into and out of without some sort of feedback.
* Fixed volume controls... were reversed and disabled.
* Added F13-F15 back to fkeys layer in Minivan
* Created new Planck Keymap that uses the NumSym and FKeys layer approach like the Minivan.
* Removed DYN layer.
* Fixed diagram in planck numsym.
* Cleanup for pull request.
* Roadkit flip phone warning.
* Replaced PLAY_NOTES_ARRAY to PLAY_SONG
* reset the submodules
* checked out specific commits for submodules
* Removed debugging from JD45 shared config.h
* Moved custom rules.mk to apropriate keymap
Reset the shared rules.mk file.
* Trailing return issue in rules.mk
Gotta make for a smooth pull request :-)
* include variables and .h files as pp directives
* start layout compilation
* split ergodoxes up
* don't compile all layouts for everything
* might seg fault
* reset layouts variable
* actually reset layouts
* include rules.mk instead
* remove includes from rules.mk
* update variable setting
* load visualizer from path
* adds some more examples
* adds more layouts
* more boards added
* more boards added
* adds documentation for layouts
* use lowercase names for LAYOUT_
* add layout.json files for each layout
* add community folder, default keymaps for layouts
* touch-up default layouts
* touch-up layouts, some keyboard rules.mk
* update documentation for layouts
* fix up serial/i2c switches
Turns out that 3c and 3d are not reversed when splitting the right
shift in the way that the Mark I layout does. Reversing it here, rather
than in the generic satan.h to avoid breaking the other layouts.
Fix and issue with the original Sentraq S60-X not being compatible with 'default'. If 'default' shouldn't be changed, perhaps I can create an 'original' revision.
It looks like build_environment_setup.md got renamed to
getting_started_build_tools.md in this commit:
commit e6c638bed1fa0a48bb6f8697b2a61717c4fd0992
Author: skullY <skullydazed@gmail.com>
Date: Sat Aug 5 20:54:34 2017 -0700
Overhaul the Getting Started section and add a FAQ section
docs/{build_environment_setup.md => getting_started_build_tools.md} | 132 ++++++++++++++++++++++++++++++++++++-------------------------------------
This commit adjusts the links to match the new name.
Updated MiniDox split_util.h and eeprom files to reflect this change.
I recommend adding this to any split board that used these files, my changes will not effect them currently.
This adds the `ACTION_TAP_DANCE_DUAL_ROLE` helper, which makes it easy to have
keys that act as a key on the first tap, and as a layer toggle on the second.
Fixes#1532, reported by @Ptomerty.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
[Colemak Mod-DH](https://colemakmods.github.io/mod-dh/) layout for
users keeping an `azerty` layout configuration on their OS.
The symbols layers was done after analysing various programming
languages sources codes and should be close to optimal for typing
confort.
The let's split code used delays in its debouncing algorithm which
increases input latency. This commit copies and adapts the code from
`quantum/matrix.c` to lets_split's `matrix.c`.
@ -12,14 +12,14 @@ Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk
## How to compile {#how-to-compile}
Before you are able to compile, you'll need to [install an environment](build_environment_setup.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation:
Before you are able to compile, you'll need to [install an environment](getting_started_build_tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation:
make planck-rev4-default
make planck/rev4:default
This would build the `rev4` revision of the `planck` with the `default` keymap. Not all keyboards have revisions (also called subprojects), in which case, it can be omitted:
This would build the `rev4` revision of the `planck` with the `default` keymap. Not all keyboards have revisions (also called subprojects or folders), in which case, it can be omitted:
make preonic-default
make preonic:default
## How to customize {#how-to-customize}
QMK has lots of [features](features/README.md) to explore, and a good deal of [reference documentation](reference/README.md) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
@ -4,7 +4,7 @@ We welcome all keyboard projects into QMK, but ask that you try to stick to a co
## Naming your directory/project
All names should be lowercase alphanumeric, and separated by an underscore (`_`), but not begin with one. Dashes (`-`) aren't allow by our build system, and will confuse it with keymaps/subprojects. Your directory and your `.h` and `.c` files should have exactly the same name. Subprojects/revision should follow the same format.
All names should be lowercase alphanumeric, and separated by an underscore (`_`), but not begin with one. Your directory and your `.h` and `.c` files should have exactly the same name. All folders should follow the same format.
## `readme.md`
@ -26,7 +26,7 @@ When developing your keyboard, keep in mind that all warnings will be treated as
## Licenses
If you're adapting your keyboard's setup from another project, but not using the same code, but sure to update the copyright header at the top of the files to show your name, it this format:
If you're adapting your keyboard's setup from another project, but not using the same code, but sure to update the copyright header at the top of the files to show your name, in this format:
If you have an idea for a custom feature or extra hardware connection, we'd love to accept it into QMK!
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 [Understaning QMK](understanding_qmk.html), 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 Gitter](https://gitter.im/qmk/qmk_firmware)
* [Open an Issue](https://github.com/qmk/qmk_firmware/issues/new)
Once you have implemented your new feature you will generally submit a [pull request](https://github.com/qmk/qmk_firmware/pulls). Here are some things to keep in mind when creating one:
* **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 subprojects and different chip-bases** - there are several keyboards that have subprojects that have allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled in one that doesn't work.
* **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.
* **Don't refactor code** - 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).
@ -12,29 +12,25 @@ This is a c header file that is one of the first things included, and will persi
// config options
#ifdef SUBPROJECT_<subproject>
#include"<subproject>/config.h"
#endif
#endif
```
This file contains config options that should apply to the whole keyboard, and won't change in subprojects, or most keymaps. The suproject block here only applies to keyboards with subprojects.
This file contains config options that should apply to the whole keyboard, and won't change in revisions, or most keymaps. The revision block here only applies to keyboards with revisions.
## Subproject
## Revisions
```c
#ifndef <subproject>_CONFIG_H
#define <subproject>_CONFIG_H
#ifndef <revision>_CONFIG_H
#define <revision>_CONFIG_H
#include"../config.h"
#include"config_common.h"
// config options
#endif
```
For keyboards that have subprojects, this file contains config options that should apply to only that subproject, and won't change in most keymaps.
For keyboards that have revisions, this file contains config options that should apply to only that revisions, and won't change in most keymaps.
## Keymap
@ -42,7 +38,7 @@ For keyboards that have subprojects, this file contains config options that shou
👍🎉 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 [Gitter](https://gitter.im/qmk/qmk_firmware).
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:
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 gitter](http://gitter.im/QMK/qmk_firmware).
# 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, 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 two spaces (soft tabs)
* We use 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 use 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 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.
# 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 PR's 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 an error
* Keyboards: Make sure that `make keyboard:all` does not return any errors
* Core: Make sure that `make allkb` 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.
```
## 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 "Suggest An Edit" at the top of each page on http://docs.qmk.fm/.
## 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](https://docs.qmk.fm/documentation_templates.html#).
* 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.
## 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](https://docs.qmk.fm/documentation_templates.html#).
* 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.
## 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 [Understaning QMK](understanding_qmk.html), 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 Gitter](https://gitter.im/qmk/qmk_firmware)
* [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](http://docs.qmk.fm/unit_testing.html) 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 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.
You can add some colors. What about a warning message?
**[warning [WARNING] The color depends on the theme. Could look normal too]
What about an error message?
**[error [ERROR] This is not the error you are looking for]
```
# 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 sentances 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.
This page documents the templates you should use when submitting new Keymaps and Keyboards to QMK.
## Keymap `readme.md` 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.
Make example for this keyboard (after setting up your build environment):
make planck/rev4:default
See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
```
There needs to be two spaces at the end of the `Keyboard Maintainer` and `Hardware Supported` lines for it to render correctly with Markdown.
[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).
## 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's](https://github.com/jackhumbert) 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 [Quantum Keycodes](quantum_keycodes.html).
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 follows 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.
# 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 pluged 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` usually in `matrix_init()` in **matrix.c**.
- 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).
## Linux or UNIX like system requires Super User privilege
Just use 'sudo' to execute *hid_listen* with privilege.
```
$ sudo hid_listen
```
Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system.
File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)
First you have to compile frimware 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 firmeare 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 keeped over power cycles.
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 [16bit] 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`.
## 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.
Arduino leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
## Using PF4-7 pins of USB AVR?
You need to set JTD bit of MCUCR yourself to use PF4-7 as GPIO. Those pins are configured to serve JTAG function by default. MCUs like ATMega*U* or AT90USB* are affeteced with this.
If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.
See this code.
```
// JTAG disable for PORT F. write JTD bit twice within four cycles.
## 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.
This page covers questions about building QMK. If you have not yet you should read the [Build Guide](https://github.com/qmk/qmk_firmware/blob/master/docs/build_guide.md).
In short,
$ make [-f Makefile.<variant>] [KEYMAP=...] clean
$ make [-f Makefile.<variant>] [KEYMAP=...]
$ make [-f Makefile.<variant>] [KEYMAP=...] dfu
This page covers questions about building QMK. If you have not yet you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](make_instructions.md) guides.
## Can't program on Linux
You will need proper permission to operate a device. For Linux users see udev rules below.
Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line.
You will need proper permission to operate a device. For Linux users see udev rules below. Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line.
In short when your controller is ATMega32u4,
@ -21,16 +13,16 @@ In short when your controller is ATMega32u4,
or just
$ sudo make dfu
$ sudo make <keyboard>:<keymap>:dfu
But to run `make` with root privilege is not good idea. Use former method as possible.
But to run `make` with root privilege is not good idea. Use former method if possible.
## WINAVR is obsolete
It is no longer recommended and may cause some problem.
See [Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
## 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 least chance of collision with other product.
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.
@ -41,7 +33,6 @@ You can buy a really unique VID:PID here. I don't think you need this for person
On Linux you need proper privilege to access device file of MCU, you'll have to use `sudo` when flashing firmware. You can circumvent this with placing these files in `/etc/udev/rules.d/`.
- DFU tools do /not/ allow you to write into the bootloader (unless
you throw in extra fruitsalad 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 frimware 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 keeped over power cycles.
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 [16bit] 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`.
## 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.
Arduino leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
## Using PF4-7 pins of USB AVR?
You need to set JTD bit of MCUCR yourself to use PF4-7 as GPIO. Those pins are configured to serve JTAG function by default. MCUs like ATMega*U* or AT90USB* are affeteced with this.
If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.
See this code.
```
// JTAG disable for PORT F. write JTD bit twice within four cycles.
## 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.
[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).
### Why the name Quantum?
<!-- FIXME -->
## 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's](https://github.com/jackhumbert) 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.
Use `GRAVE_ESC` or `KC_GESC` in your keymap.`GUI`+`GRAVE_ESC` results in `` ` `` and `SHIFT`+`GRAVE_ESC` results in `~`.
Note that this will break the CTRL+SHIFT+ESC shortcut to the Windows task manager. Use `#define GRAVE_ESC_CTRL_OVERRIDE` in your `config.h` to get the shortcut back. With this option, `ESC_GRAVE` results in `ESC` if `CTRL` is held, even if `SHIFT` or `GUI` are also held.
## Arrow on Right Modifier keys with Dual-Role
This turns right modifer keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**.
Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to the C6 or B5 port (`#define C6_AUDIO` and/or `#define B5_AUDIO`), 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.
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)
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
floatmy_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.
## 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
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!
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
## MIDI functionalty
This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
Tap a key and you get its character. Tap a key, but hold it *slightly* longer
and you get its shifted state. Viola! 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. 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.
3. 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!
## 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
#ifndef CONFIG_USER_H
#define CONFIG_USER_H
#include "../../config.h"
#define AUTO_SHIFT_TIMEOUT 150
#define NO_AUTO_SHIFT_SPECIAL
#endif
### 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
occassion. 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.
{% hint style='info' %}
Auto Shift has three special keys that can help you get this value right very
quick. See "Auto Shift Setup" for more details!
{% endhint %}
### 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 temporailiy to increase, decrease and report your `AUTO_SHIFT_TIMEOUT`.
This requires [some hardware changes](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts), but can be enabled via the Makefile. The firmware will still output characters via USB, so be aware of this when charging via a computer. It would make sense to have a switch on the Bluefruit to turn it off at will.
<!-- FIXME: Document bluetooth support more completely. -->
## 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.
Your keymap can include shortcuts to common operations, for example shifted keys. This page documents the functions that are available to you.
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.
### Limits of these aliases
Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.html), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.html).
## Switching and toggling layers
These functions allow you to activate layers in various ways.
*`MO(layer)` - momentary switch to *layer*. As soon as you let go of the key, the layer is deactivated and you pop back out to the previous layer.
*`LT(layer, kc)` - momentary switch to *layer* when held, and *kc* when tapped.
*`TG(layer)` - toggles a layer on or off.
*`TO(layer)` - Goes to a layer. This code is special, because it lets you go either up or down the stack -- just goes directly to the layer you want. So while other codes only let you go _up_ the stack (from layer 0 to layer 3, for example), `TO(2)` is going to get you to layer 2, no matter where you activate it from -- even if you're currently on layer 5. This gets activated on keydown (as soon as the key is pressed).
*`TT(layer)` - Layer Tap-Toggle. If you hold the key down, the layer becomes active, and then deactivates when you let go. And if you tap it, the layer simply becomes active (toggles on). It needs 5 taps by default, but you can set it by defining `TAPPING_TOGGLE`, for example, `#define TAPPING_TOGGLE 2` for just two taps.
## 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
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 "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.)
* 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.
* Never try to stack a higher numbered layer on top of a lower numbered layer. Doing so is tricky and error prone.
### 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
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.
## Modifier keys
These functions allow you to combine a mod with a keycode. When pressed the keydown for the mod will be sent first, and then *kc* will be sent. When released the keyup for *kc* will be sent and then the mod will be sent.
*`LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
*`RSFT(kc)` - applies right Shift to *kc*
*`LCTL(kc)` - applies left Control to *kc*
*`RCTL(kc)` - applies right Control to *kc*
*`LALT(kc)` - applies left Alt to *kc*
*`RALT(kc)` - applies right Alt to *kc*
*`LGUI(kc)` - applies left GUI (command/win) to *kc*
*`RGUI(kc)` - applies right GUI (command/win) to *kc*
*`HYPR(kc)` - applies Hyper (all modifiers) to *kc*
*`MEH(kc)` - applies Meh (all modifiers except Win/Cmd) to *kc*
*`LCAG(kc)` - applies CtrlAltGui to *kc*
You can also chain these, like this:
LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
## Shifted Keycodes
The following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols.
|Name|Description|
|----|-----------|
| KC_TILD | ~ |
| KC_EXLM | ! |
| KC_QUES | ? |
| KC_AT | @ |
| KC_HASH | # |
| KC_DLR | $ |
| KC_PERC | % |
| KC_CIRC | ^ |
| KC_AMPR | & |
| KC_ASTR | * |
| KC_LPRN | ( |
| KC_RPRN | ) |
| KC_UNDS | _ |
| KC_PLUS | + |
| KC_DQUO | " |
| KC_LCBR | { |
| KC_RCBR | } |
| KC_LABK | < |
| KC_RABK | > |
| KC_PIPE | | |
| KC_COLN | : |
## Mod Tap
`MT(mod, kc)` - is *mod* (modifier key - MOD_LCTL, MOD_LSFT) when held, and *kc* when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down.
These are the values you can use for the `mod` in `MT()` and `OSM()`:
* MOD_LCTL
* MOD_LSFT
* MOD_LALT
* MOD_LGUI
* MOD_RCTL
* MOD_RSFT
* MOD_RALT
* MOD_RGUI
* MOD_HYPR
* MOD_MEH
These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped. Note however, that you cannot mix right and left side modifiers.
We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
*`CTL_T(kc)` - is LCTL when held and *kc* when tapped
*`SFT_T(kc)` - is LSFT when held and *kc* when tapped
*`ALT_T(kc)` - is LALT when held and *kc* when tapped
*`ALGR_T(kc)` - is AltGr when held and *kc* when tapped
*`GUI_T(kc)` - is LGUI when held and *kc* when tapped
*`ALL_T(kc)` - is Hyper (all mods) when held and *kc* when tapped. To read more about what you can do with a Hyper key, see [this blog post by Brett Terpstra](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)
*`LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
*`MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
## One Shot Keys
One shot keys are keys that remain active until the next key is pressed, and then are releasd. This allows you to type keyboard combinations without pressing more than one key at a time.
For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A character by first pressing and releasing shift, and then pressing and releasing A. Your computer will see the shift key being held the moment shift is pressed, and it will see the shift key being released immediately after A is released.
One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key.
You can control the behavior of one shot keys by defining these in `config.h`:
```c
#define ONESHOT_TAP_TOGGLE 5 /* Tapping this number of times holds the key until tapped this number of times again. */
#define ONESHOT_TIMEOUT 5000 /* Time (in ms) before the one shot key is released */
```
*`OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
*`OSL(layer)` - momentary switch to *layer*.
## Permissive Hold
As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
```
#define PERMISSIVE_HOLD
```
This makes it easier for fast typists to use dual-function keys. Without this, if you let go of a held key inside the tapping term, it won't register.
Example: (Tapping Term = 200ms)
- SHFT_T(KC_A) Down
- KC_X Down
- KC_X Up
- SHFT_T(KC_A) Up
With defaults, if above is typed within tapping term, this will emit `ax`. With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).
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 reposistories 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 (`[a-z0-9_]`) must be defined in it's `<keyboard>.h`, and match the number of arguments/keys (and preferrably the physical layout):
#define LAYOUT_60_ansi KEYMAP_ANSI
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.
## Tips for making layouts keyboard-agnostic
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
In your config.h, you can also use this variable to include the keyboard's `config.h`:
#include QMK_KEYBOARD_CONFIG_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.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
