This introduces a grep dependency, which I believe we didn't have
before, but it should be available and installed by default on all the
supported systems.
This is a setup that is very useful for me. It may or may not be for
you. I will use it in conjunction with the A5 overlayed sv_SE layout.
The layout is subject to change (in particular I'm thinking about adding
a macro recording feature), but it have not changed much the past year
or two so you can expect it to be stable enough to learn it.
A5: http://aoeu.info/s/dvorak/svorak
My xkb map: https://github.com/lindhe/dotfiles/blob/master/usr/share/X11/xkb/symbols/se-A5
The most major points:
======================
L0:
---
* Easily accessible F11 key for fullscreening
* Print screen
* Middle mouse button for X-paste
* Improved reachability of meta buttons (LCtrl, LALt, AltGr, LGui etc.)
* Cluster Page Up/Down + Home/End by the right thumb
* Vim-like arrow layout in right bottom row
* Set media layer toggle to right thumb (Enter)
* Set apostrophe on LCtl (putting it next to some other small
characters)
L1:
---
* Full function key layout
* Teensy button
L2:
---
* Improved media buttons layout (close by the jkl; Vim binding)
* Improved layout of emulated mouse buttons
LED behaviour to binary+CAPS
============================
The ErgoDox LEDs on this layout is using the two rightmost LEDs as the
two LSB in a two digit binary number, representing layer 0, 1, 2 and 3.
The leftmost byte/LED indicates CAPS status.
Instead of having all sendstring keycode mappings in the main quantum.c
file, give each one its own file in keymap_extras that can be #included
in a user's keymap. If one is included, it will define the appropriate
lookup tables and overwrite the weak definitions in quantum.c.
(Including more than one sendstring definition will fail at compile
time.)
Update @rai-suta's test keymap to match, as well as the documentation.
Refactor new-ish JIS_KEYCODE send_string implementation with existing
send_string
Reshuffle JIS in line with other alternative keycodes for sendstring,
and make them all accessible via compile-time options
Add a separate function to allow sending a string with a delay.
* Move Space Caded Parentheses to own layer
The space cadet parentheses where too much distracting. Therefore they are now on the function layer. I also added two more layers for also having angle brackets and curly braces on the shift keys forr better access.
Also updated the README
* Fixed SHIFT+Function key conflict
* Removed Angle Bracket and Curly Bracket layers, as they don't work corrrectly
*NOTE:* it might still be desirable to set the software layout to sv_SE in your
OS.
Swedish (sv_SE) Qwerty layout for ErgoDox, based on the Default configuration
I have tried making this as close of a match I could between the [default
ErgoDox EZ configuration](https://ergodox-ez.com/pages/our-firmware) and a
standard Swedish Qwerty layout.
Notable differences from default:
=================================
* There are three special character buttons (acute accent, circumflex/tilde and
apostrophe/asterisk) that don't have any buttons to map to naturally. I've put
these at other places:
* Acute accent (´) can be found in the lower left corner, conveniently
placed to reach for making an é.
* Apostrophe (') was put in the lower left corner, close to acute accent.
* Circumflex (^) and asterisk (*) was placed in the lower right corner.
* Tilde (~) and diaeresis (¨) I couldn't find a good place for, so I left
those out. I could only get the buttons to produce a single one of the
characters. How can I get it to work properly?
* The Alt button on right thumb was exchanged for AltGr (RAlt).
* I changed the backslash in the numpad (layer 1) for a minus. Thought it was
more sensible.
* I didn't find a good place for the "<>|" button, so that one was left out.
That is a problem that really needs to be resolved. Pipe can be found on layer
one, however.
* allow mod swapping for mod tap
* quick include
* fix the mod swapping
* make changes consistent with action code
* fix bug
* re-enable no gui, etc
* fix binary comps
* solid logic
* Added orthodox
* Modified readme
* Modified readme
* Modified readme
* Updated makefile
* Fixed keymap issues
* Modified serial communications to allow for over 8 columns
* Fixed sizeof command
* Fixed some typing issues
* Testing issue #1191 (n-column split i2c slave)
Based on initial OrthoDox (serial) config by @reddragond and others,
this attempts to add TWI (I2C) support.
Relevant: <https://github.com/qmk/qmk_firmware/issues/1191>
- per @ahtn recommendation, using memcpy for moving slave matrix
into slave sending buffer
- slave buffer has been enlarged using sizeof(matrix_row_t)
- note: i2c.h now includes matrix.h
- note: matrix.c includes <string.h>
* Added i2c keymap - right col still not working
* orthodox: re-added i2c keymap, based on serial
* orthodox / issue #1191: trying 9-bit serial
- orthodox serial protocol now sends 9 bits per row, instead of 16.
Technically it's using MATRIX_COLS, so it might work generically.
- ROW_MASK is #defined in serial.c to truncate the checksums to prevent
overflows causing false errors. This macro should be renamed if it's
kept.
* Revert "Fixed sizeof command"
This reverts commit f62a5b9939.
Changes had been made to the lets_split serial driver for testing which
mirrored the multi-byte-row changes made to support the orthodox. As the
lets_split does not require these changes, and new improvements had
been added to the orthodox port only, this commit reverts them.
Because the new code could potentially reduce latency over the serial
transport, it may be desirable to re-add in the future, by backporting
the current working orthodox code.
* orthodox: default serial keymap improvements
- formatting has been improved
- a few keys have been shifted, mainly in Raise and Lower layers,
to be more like the default Planck layout
- Now available: F12, Home, End, PgUp, PgDn, Media-Next, Media-Play
Still To Do:
- duplicate for TWI
- Alt modifier
- GUI modifier
* orthodox: failed attempt at 16b/row TWI
- duplicated updated serial keymap for "i2c"
- removed string.h/memcpy, instead
- hardcoded copying of six bytes per update
- still doesn't work; master reports interconnect errors on txled
* orthodox: adjusted default keymap
- this is applied to both 'serial' and 'i2c' keymaps
- Alt and GUI have been added, as they were missing
- comma and period persist across more layers; Home/PgUp and End/PgDn
have been moved slightly to accommodate
* orthodox: revert TWI support to minimum to debug
- disabled ssd1306 and hardware locking in build configuration
- increased TWI buffer from 0x10 to 0x20 bytes
- decreased TWI clock from 400000 to 100000
- removed hardcoded TWI multi-byte sending/receiving
An 'i2c' build of this was found to work on a rev1 Orthodox, although
slave-side col9 was understandably not working. When testing-time
permits, features will be gradually re-enabled towards getting the full
matrix supported over TWI.
* orthodox: TWI (i2c) is working, kludge for col9
The TWI interconnect ("i2c" in directories and build config) is now
working for the Orthodox, including the slave half's column #9.
This is intended as an interim solution, as it's a kludge, not a fix.
Rather than a working multi-byte implementation, the two col9 keys'
bits are packed-into and unpacked-from the two unused bits in row1.
Furthermore, the TWI clock constant has been reduced to 100000 from
400000, as testing revealed the higher value just didn't work.
Testing also found that (with this kludge) increasing the TWI buffer
was not necessary.
This commit leaves many commented-out lines in matrix.c from previous
testing, which will be removed in a future commit once the
interconnects' multi-byte problems have been debugged more thoroughly.
* orthodox: updated readme.md
The readme for the Orthodox now includes a description of the keyboard,
allusions to its author and availability, a linked photo, and links to
the evolving build guide and the current keymap on KLE.
This update has been prepared with /u/Deductivemonkee's assistance.
Added basic description of the keyboard and some build and configuration
instructions.
Also moved the RGB underlight modification instructions to the readme.
The previous default configuration and keymap was made for a Phantom
modified with RGB underlight.
This commit makes the default more in line with the "official"
configurations provided by the PCB.
The previous default have been moved to a separate keymap named
`rgbmod`. It has also been updated to better match the template keymap.
It's a little unclear what the style guidelines are for the QMK project.
But I figured that I should at least keep the indentation consistent
within the KMAC part.
Previously KEYMAP referred to the KEYMAP_ARROW layout and had 45 keys. It makes
more sense for the default keymap to be the 44 key layout, as is implied by the
name.
Additionally keymaps for all other known layouts have been added:
KEYMAP - base layout
KEYMAP_ARROW - additional key in bottom right
KEYMAP_COMMAND - additional key in bottom left
KEYMAP_ARROW_COMMAND - combination of KEYMAP_ARROW and KEYMAP_COMMAND
* Make submodules point to qmk
* Update uGFX to 2.7
* Use ugfx with custom fixes
* Fix the ChibiOs submodule commit hash
To match the hashes in the mabl/ChibiOS and therefore QMK repository.
* Add MIDI layer
* Respect brightness level on layer signalling
* Add hotkey in control layer for signalling state
* Update layout.png
* Remove image and replace it with imgur link
* SCKLCK is now SCROLLLOCK
Yes, with all three Ls
At least it doesn't have a random K anymore lol
* Removed strange mystery trailing numbers in the docs
* Fix layer LED signalling in magicmonty keymap
* Include the breathing modes in layer signalling
* Reverts mode to 1 as the other modes flicker
* Add Cursor keys on VIM positions and PAUSE to function layer
If a macro play key is inadvertently recorded in a dynamic macro
a loop is created and the macro will not terminate when played.
This should be prevented.
* Add 80ms delay for KC_CAPS when used as a tap key
Workaround for the macOS caps lock delay
* Revert "Increase TAPPING_TERM for the Clueboard"
This reverts commit a74e69e9fa.
* Add keymap for smt Clueboard (HHKB layout)
* Add readme for smt Clueboard (HHKB) keymap
* Flesh out the keymap a bit more to support Colemak & Dvorak
* Update README with layout image
Replacement controller for Filco Majestouch 2 104 key keyboard. BE
advises code will also work with the Black Petal controller - I don't
have one to test with. Tests working perfectly on my Filco.
More specifically, we save them and then place the `macro_end` pointer
before them so they are essentially ignored and the other macro may
freely overwrite them.
Right after the user initiates the macro recording, they usually need
to release some keys used to access the DYN_REC_START layers. It makes
sense to ignore them.
Note: The keys used to access the DYN_REC_STOP key are *not* ignored.
From the official docs:
```
Note: The official Debian and Ubuntu images automatically run apt-get clean, so explicit invocation is not required.
```
Also added ` && rm -rf /var/lib/apt/lists/*` as part of the install line which probably does what was intended (no need to make a new layer).
Added apt-get update to the RUN payload, as it should be part of the same layer.
Both are documented here: https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/
Dynamic macro functionality is modified to check for `DYN_REC_STOP`, so
that macro recording can be stopped with a designated key combination
(e.g. `qs` or anything) instead of mandating the use of a `_DYN` layer.
`_DYN` layer stopping can still be done by passing `DYN_REC_STOP` within
`process_record_user()`:
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
uint16_t macro_kc = (keycode == MO(_DYN) ? DYN_REC_STOP : keycode);
if (!process_record_dynamic_macro(macro_kc, record)) {
return false;
}
return true;
}
Empirically, waiting for N consecutive identical scans as a debouncing
strategy doesn't work very well for the ErgoDox EZ where scans are very
slow compared to most keyboards. Instead, debounce the signals by
eagerly reporting a change as soon as one scan observes it, but then
ignoring further changes from that key for the next N scans.
This is implemented by keeping an extra matrix of uint8 countdowns, such
that only keys whose countdown is currently zero are eligible to change.
When we do observe a change, we bump that key's countdown to DEBOUNCE.
During each scan, every nonzero countdown is decremented.
With this approach to debouncing, much higher debounce constants are
tolerable, because latency does not increase with the constant, and
debounce countdowns on one key do not interfere with events on other
keys. The only negative effect of increasing the constant is that the
minimum duration of a keypress increases. Perhaps I'm just extremely
unlucky w.r.t. key switch quality, but I saw occasional bounces even
with DEBOUNCE=10; with 15, I've seen none so far. That's around 47ms,
which seems like an absolutely insane amount of time for a key to be
bouncy, but at least it works.
Using only one layer, and activating it with two keys at the moment.
As with previous comments, this isn't final, but is a good starting point for a one-handed keyboard, half a Planck-like ortholinear keyboard, or a sample to show a layout with a function layer.
There was a typo, so the attempted configuration proably didn't do
what it should have done. I think it left the pin floating, and
could cause the LCD problems issue-1230.
It turns out that the ChibiOS K20 SPI driver doesn't handle the
chip select, so it needs to be done manually. Acquiring the bus is
not enough since the pin was in the wrong mode. This is now fixed.
Also increase the frequency of the SPI from around 200kHz to nearly
20 Mhz.
No animation, display led statuses and layer name on the same screen
Don't display layer bitmap
Fully saturated colors for caps, less saturated ones normally
Added MOD_TAP aliases for keymap.c readability.
Updated README to document said changes.
Added additional Dvorak layer to make using the CMD key easier on Macs.
fixed issue where Default.c "function key" does not work (actually it's changing my LED steps). Changed layout to be more user friendly for people that use the standard spacebar milled top plate.
* Clarify the license for files we have signoff on
* Update against the currently signed off files
* Remove unused and not clearly licensed headers
* Replace an #endif I accidentally removed while resolving merge conflicts
As per Pramod's comment on stack overflow:
In C int foo() and int foo(void) are different functions. int foo()
accepts an arbitrary number of arguments, while int foo(void) accepts 0
arguments. In C++ they mean the same thing. I suggest that you use void
consistently when you mean no arguments.
Refactored Bluetooth support to make adding new Bluetooth modules
easier in the future.
* Remove `OUT_BLE` key from QMK's keymap. `OUT_BT` is all we need now
as there's no difference anymore.
* Made BLUETOOTH_ENABLE build option legacy as not to break existing
keymaps (Falls back to existing EZ Key support if on)
* Removed `ADAFRUIT_BLE_ENABLE` build option
* Created new build option `BLUETOOTH` with module option (Currently
`AdafruitEZKey` & `AdafruitBLE`)
* Moved all LUFA bluetooth key/mouse events under `BLUETOOTH_ENABLE`
ifdef with selected modules output.
This only applies to keymaps that has combined esc/grave. Here we call it theKEY.
Think about the motion when we do shift + theKEY (typing ~), or CMD + theKEY (switching window on MAC). Based on the original code, we must do following sequence: press shift -> press theKEY -> release theKEY -> release shift. However, it is very possible and natural that we do this stroke sequence instead: press shift -> press theKEY -> release shift -> release theKEY.
If we do the 2nd stroke sequence, the code will del_key(ESC) instead of (GRV) when we release theKEY. This caused some inconvenient issues and ghost typing.
By adding a flag, this issue is eliminated and will not affect any other functions.
A simple addition to the `install_dependencies` script which remaps the debian dependencies to their freebsd package-names. After a recursive clone and using gmake, I can successfully build all firmware from the root directory (minus some warnings generated by gcc-4.9.4 which I can procure on request). however there is a problem running tests.
Removed some unneeded keys from raise and lower layers
moved the + and = signs, backspace is now more intuitive
moved all the Function keys to CUSTOM layer
added ctrl alt del to CUSTOM layer
simplified the layout picture greatly
Update existing keymaps to enable MIDI_BASIC functionality. Also added
an option MIDI_ENABLE_STRICT to be strict about keycode use (which also
reduces memory footprint at runtime)
tone array:
text data bss dec hex filename
0 25698 0 25698 6462 satan_newsboytko.hex
0x6480 bytes written into 0x7000 bytes memory (89.73%).
note on array:
text data bss dec hex filename
0 25802 0 25802 64ca satan_newsboytko.hex
0x6500 bytes written into 0x7000 bytes memory (90.18%).
if you compare split_util.h with the original project by ahtn, the
address we look for isLeftHand config went from addr 7 to addr 10
(decimal). The EEP files were not updated.
EE_HANDS should not be enabled by default since it's more confusing for
most users
Added new keymap `Admiral Strokers` to the Satan keyboard. This is an
ISO based layout with tap for brackets/ curly on shft and ctl keys.
Furthermore, there is added arrows and media/volume/special/f-keys layer
on the TAB button when you hold.
The previous two options were COL2ROW, ROW2COL; this adds CUSTOM_MATRIX
to disable the built-in matrix scanning code.
Most notably, this obviates the need to set MATRIX_ROW_PINS or
MATRIX_COL_PINS.
The oneshot cancellation code do not depend on the
action_tapping_process and since process_record get called via the
action_tapping_process logic moved the oneshot cancellation code into
the action_exec function just before the action_tapping_process call
A macro key can now be easily set to act as a modifier on hold, and
press a shifted key when tapped. Or to switch layers when held, and
again press a shifted key when tapped.
Various other helper defines have been created which send macros when
the key is pressed, released and tapped, cleaning up the
action_get_macro function inside keymap definitions.
The layer switching macros require a GCC extension - 'compound
statements enclosed within parentheses'. The use of this extension is
already present within the macro subsystem of this project, so its use
in this commit should not cause any additional issues.
MACRO_NONE had to be cast to a (macro_t*) to suppress compiler
warnings within some tapping macros.
* master:
Clarify license on abnt2 keymap (#1038)
replace jackhumbert with qmk
Add gitter image, start update to qmk org
Remove COLEMAK from preonic_keycodes enum
layer defines to enum
Update readme for smt Preonic keymap
Add smt keymap for Preonic
updated all the other keymaps to support the new changes.
fix: infinity60 keyboard was not using quantum features.
Compare Makefile with itself instead of using `--help`
After setting a ONESHOT_TIMEOUT value, the oneshot layer state would
not expire without an event being triggered (key pressed). The reason
was that in the process_record function we would return priort to
execute the process_action function if it detected a NOEVENT cycle. The
process_action contained the codes to timeout the oneshot layer state.
The codes to clear the oneshot layer state have been move just in
front of where we check for the NOEVENT cycle in the process_record
function.
QMK strives to be an inclusive and tolerant community. We welcome participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation.
> “A gentle word turns away wrath, but a harsh word stirs up anger.”
Our users, contributors, and collaborators are expected to treat each other with respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. Some examples of behavior we will not tolerate include, but is not limited to:
* The use of sexualized language or imagery
* Unwelcome advances, sexual or otherwise
* Insults or derogatory comments, or personal or political attacks
* Publishing others’ private information without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
If someone is violating this Code of Conduct you may email hello@qmk.fm to bring your concern to the Members. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
# This guide has now been included in the main readme - please reference that one instead.
## Build Environment Setup
### Windows (Vista and later)
1. If you have ever installed WinAVR, uninstall it.
2. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**.
3. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location.
4. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/qmk/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer.
5. Double-click on the 1-setup-path-win batch script to run it. You'll need to accept a User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up.
6. Right-click on the 2-setup-environment-win batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete!
7. Future build commands should be run from the standard Windows command prompt, which you can find by searching for "command prompt" from the start menu or start screen. Ignore the "MHV AVR Shell".
### Mac
If you're using [homebrew,](http://brew.sh/) you can use the following commands:
brew tap osx-cross/avr
brew install avr-libc
brew install dfu-programmer
This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line.
You can also try these instructions:
1. Install Xcode from the App Store.
2. Install the Command Line Tools from `Xcode->Preferences->Downloads`.
3. Install [DFU-Programmer][dfu-prog].
### Linux
Install AVR GCC, AVR libc, and dfu-progammer with your favorite package manager.
If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [VAGRANT_GUIDE file](VAGRANT_GUIDE.md).
## Verify Your Installation
1. If you haven't already, obtain this repository ([https://github.com/qmk/qmk_firmware](https://github.com/qmk/qmk_firmware)). You can either download it as a zip file and extract it, or clone it using the command line tool git or the Github Desktop application.
2. Open up a terminal or command prompt and navigate to the `qmk_firmware` folder using the `cd` command. The command prompt will typically open to your home directory. If, for example, you cloned the repository to your Documents folder, then you would type `cd Documents/qmk_firmware`. If you extracted the file from a zip, then it may be named `qmk_firmware-master` instead.
3. To confirm that you're in the correct location, you can display the contents of your current folder using the `dir` command on Windows, or the `ls` command on Linux or Mac. You should see several files, including `readme.md` and a `quantum` folder. From here, you need to navigate to the appropriate folder under `keyboards/`. For example, if you're building for a Planck, run `cd keyboards/planck`.
4. Once you're in the correct keyboard-specific folder, run the `make` command. This should output a lot of information about the build process. More information about the `make` command can be found below.
## Customizing, Building, and Deploying Your Firmware
### The Make command
The `make` command is how you compile the firmware into a .hex file, which can be loaded by a dfu programmer (like dfu-progammer via `make dfu`) or the [Teensy loader](https://www.pjrc.com/teensy/loader.html) (only used with Teensys). You can run `make` from the root (`/`), your keyboard folder (`/keyboards/<keyboard>/`), or your keymap folder (`/keyboards/<keyboard>/keymaps/<keymap>/`) if you have a `Makefile` there (see the example [here](/doc/keymap_makefile_example.mk)).
By default, this will generate a `<keyboard>_<keymap>.hex` file in whichever folder you run `make` from. These files are ignored by git, so don't worry about deleting them when committing/creating pull requests.
* The "root" (`/`) folder is the qmk_firmware folder, in which are `doc`, `keyboard`, `quantum`, etc.
* The "keyboard" folder is any keyboard project's folder, like `/keyboards/planck`.
* The "keymap" folder is any keymap's folder, like `/keyboards/planck/keymaps/default`.
Below is a list of the useful `make` commands in QMK:
*`make` - cleans automatically and builds your keyboard and keymap depending on which folder you're in. This defaults to the "default" layout (unless in a keymap folder), and Planck keyboard in the root folder
*`make keyboard=<keyboard>` - specifies the keyboard (only to be used in root)
*`make keymap=<keymap>` - specifies the keymap (only to be used in root and keyboard folder - not needed when in keymap folder)
*`make quick` - skips the clean step (cannot be used immediately after modifying config.h or Makefiles)
*`make dfu` - (requires dfu-programmer) builds and flashes the keymap to your keyboard once placed in reset/dfu mode (button or press `KC_RESET`). This does not work for Teensy-based keyboards like the ErgoDox EZ.
*`keyboard=` and `keymap=` are compatible with this
*`make all-keyboards` - builds all keymaps for all keyboards and outputs status of each (use in root)
*`make all-keyboards-default` - builds all default keymaps for all keyboards and outputs status of each (use in root)
*`make all-keymaps [keyboard=<keyboard>]` - builds all of the keymaps for whatever keyboard folder you're in, or specified by `<keyboard>`
*`make all-keyboards-quick`, `make all-keyboards-default-quick` and `make all-keymaps-quick [keyboard=<keyboard>]` - like the normal "make-all-*" commands, but they skip the clean steps
Other, less useful functionality:
*`make COLOR=false` - turns off color output
*`make SILENT=true` - turns off output besides errors/warnings
*`make VERBOSE=true` - outputs all of the avr-gcc stuff (not interesting)
### The Makefile
There are 3 different `make` and `Makefile` locations:
The root contains the code used to automatically figure out which keymap or keymaps to compile based on your current directory and commandline arguments. It's considered stable, and shouldn't be modified. The keyboard one will contain the MCU set-up and default settings for your keyboard, and shouldn't be modified unless you are the producer of that keyboard. The keymap Makefile can be modified by users, and is optional. It is included automatically if it exists. You can see an example [here](/doc/keymap_makefile_example.mk) - the last few lines are the most important. The settings you set here will override any defaults set in the keyboard Makefile. **It is required if you want to run `make` in the keymap folder.**
The keyboard `config.h` is included only if the keymap one doesn't exist. The format to use for your custom one [is here](/doc/keymap_config_h_example.h). If you want to override a setting from the parent `config.h` file, you need to do this:
```
#undef MY_SETTING
#define MY_SETTING 4
```c
For a value of `4` for this imaginary setting. So we `undef` it first, then `define` it.
You can then override any settings, rather than having to copy and paste the whole thing.
1. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**.
2. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location.
3. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/qmk/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer.
4. Right-click on the 1-setup-path-win batch script, select "Run as administrator", and accept the User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up.
5. Right-click on the 2-setup-environment-win batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete!
### Mac
If you're using homebrew, you can use the following commands:
brew tap osx-cross/avr
brew install avr-libc
brew install dfu-programmer
Otherwise, these instructions will work:
1. Install Xcode from the App Store.
2. Install the Command Line Tools from `Xcode->Preferences->Downloads`.
3. Install [DFU-Programmer][dfu-prog].
### Linux
1. Install AVR GCC with your favorite package manager.
2. Install [DFU-Programmer][dfu-prog].
Note that, since it will be directly accessing USB hardware, the
`dfu-programmer` program needs to be run as root.
## Verify Your Installation
1. Clone the following repository: https://github.com/qmk/qmk_firmware
2. Open a Terminal and `cd` into `qmk_firmware/keyboards/planck`
3. Run `make`. This should output a lot of information about the build process.
## Using the built-in functions
Here is a list of some of the functions available from the command line:
*`make clean`: clean the environment - may be required in-between builds
*`make`: compile the code
*`make KEYMAP=<keymap>`: compile with the extended keymap file `extended_keymaps/extended_keymap_<keymap>.c`
*`make dfu`: build and flash the layout to the PCB
*`make dfu-force`: build and force-flash the layout to the PCB (may be require for first flash)
Generally, the instructions to flash the PCB are as follows:
1. Make changes to the appropriate keymap file
2. Save the file
3.`make clean`
4. Press the reset button on the PCB/press the key with the `RESET` keycode
5.`make <arguments> dfu` - use the necessary `KEYMAP=<keymap>` and/or `COMMON=true` arguments here.
## Troubleshooting
If you see something like this
0 [main] sh 13384 sync_with_child: child 9716(0x178) died before initialization with status code 0xC0000142
440 [main] sh 13384 sync_with_child: *** child state waiting for longjmp
after running 'make' on Windows than you are encountering a very popular issue with WinAVR on Windows 8.1 and 10.
You can easily fix this problem by replacing msys-1.0.dll in WinAVR/utils/bin with [this one](http://www.madwizard.org/download/electronics/msys-1.0-vista64.zip).
Restart your system and everything should work fine!
make (e=2): The system cannot find the file specified.
make: *** [dfu] Error 2
when trying to 'make dfu' on Windows you need to copy the dfu-programmer.exe to qmk_firmware/keyboards/planck.
## Quantum MK Firmware
### Keymap
Unlike the other keymaps, prefixing the keycodes with `KC_` is required. A full list of the keycodes is available [here](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/doc/keycode.txt). For the keycodes available only in the extended keymap, see this [header file](https://github.com/qmk/qmk_firmware/blob/master/quantum/keymap_common.h).
You can use modifiers with keycodes like this:
LCTL(KC_C)
Which will generate Ctrl+c. These are daisy-chainable, meaning you can do things like:
LCTL(LALT(KC_C))
That will generate Ctrl+Alt+c. The entire list of these functions is here:
*`LCTL()`: Left control
*`LSFT()` / `S()`: Left shift
*`LALT()`: Left alt/opt
*`LGUI()`: Left win/cmd
*`RCTL()`: Right control
*`RSFT()`: Right shift
*`RALT()`: Right alt/opt
*`RGUI()`: Right win/cmd
`S(KC_1)`-like entries are useful in writing keymaps for the Planck.
### Other keycodes
A number of other keycodes have been added that you may find useful:
*`CM_<key>`: the Colemak equivalent of a key (in place of `KC_<key>`), when using Colemak in software (`CM_O` generates `KC_SCLN`)
*`RESET`: jump to bootloader for flashing (same as press the reset button)
*`BL_STEP`: step through the backlight brightnesses
*`BL_<0-15>`: set backlight brightness to 0-15
*`BL_DEC`: lower the backlight brightness
*`BL_INC`: raise the backlight brightness
*`BL_TOGG`: toggle the backlight on/off
### Function layers
The extended keymap extends the number of function layers from 32 to the near-infinite value of 256. Rather than using `FN<num>` notation (still available, but limited to `FN0`-`FN31`), you can use the `FUNC(<num>)` notation. `F(<num>)` is a shortcut for this.
The function actions are unchanged, and you can see the full list of them [here](https://github.com/jackhumbert/tmk_keyboard/blob/master/common/action_code.h). They are explained in detail [here](https://github.com/jackhumbert/tmk_keyboard/blob/master/doc/keymap.md#2-action).
### Macros
Macros have been setup in the `keymaps/keymap_default.c` file so that you can use `M(<num>)` to access a macro in the `action_get_macro` section on your keymap. The switch/case structure you see here is required, and is setup for `M(0)` - you'll need to copy and paste the code to look like this (e.g. to support `M(3)`):
switch(id) {
case 0:
return MACRODOWN(TYPE(KC_A), END);
break;
case 1:
return MACRODOWN(TYPE(KC_B), END);
break;
case 2:
return MACRODOWN(TYPE(KC_C), END);
break;
case 3:
return MACRODOWN(TYPE(KC_D), END);
break;
}
return MACRO_NONE;
`MACRODOWN()` is a shortcut for `(record->event.pressed ? MACRO(__VA_ARGS__) : MACRO_NONE)` which tells the macro to execute when the key is pressed. Without this, the macro will be executed on both the down and up stroke.
**GPLv2** or later. Some protocol files are under **Modified BSD License**.
Third party libraries like LUFA, PJRC and V-USB have their own license respectively.
Build Firmware and Program Controller
-------------------------------------
See [build environment setup](/readme.md#build-environment-setup), or the readme in the particular keyboards/* folder.
Change your keymap
------------------
See [doc/keymap.md](tmk_core/doc/keymap.md).
Magic Commands
--------------
To see help press `Magic` + `H`.
`Magic` key combination is `LShift` + `RShift` in many project, but `Power` key on ADB converter.
`Magic` keybind can be vary on each project, check `config.h` in project directory.
Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
----- Command Help -----
c: enter console mode
d: toggle debug enable
x: toggle matrix debug
k: toggle keyboard debug
m: toggle mouse debug
v: print device version & info
t: print timer count
s: print status
e: print eeprom config
n: toggle NKRO
0/F10: switch to Layer0
1/F1: switch to Layer1
2/F2: switch to Layer2
3/F3: switch to Layer3
4/F4: switch to Layer4
PScr: power down/remote wake-up
Caps: Lock Keyboard(Child Proof)
Paus: jump to bootloader
Boot Magic Configuration - Virtual DIP Switch
---------------------------------------------
Boot Magic are executed during boot up time. Press Magic key below then plug in keyboard cable.
Note that you must use keys of **Layer 0** as Magic keys. These settings are stored in EEPROM so that retain your configure over power cycles.
To avoid configuring accidentally additive salt key `KC_SPACE` also needs to be pressed along with the following configuration keys. The salt key is configurable in `config.h`. See [tmk_core/common/bootmagic.h](tmk_core/common/bootmagic.h).
#### General
- Skip reading EEPROM to start with default configuration(`ESC`)
- Clear configuration stored in EEPROM to reset configuration(`Backspace`)
#### Bootloader
- Kick up Bootloader(`B`)
#### Debug
- Debug enable(`D`)
- Debug matrix enable(`D`+`X`)
- Debug keyboard enable(`D`+`K`)
- Debug mouse enable(`D`+`M`)
#### Keymap
- Swap Control and CapsLock(`Left Control`)
- Change CapsLock to Control(`Caps Lock`)
- Swap LeftAlt and Gui(`Left Alt`)
- Swap RightAlt and Gui(`Right Alt`)
- Disable Gui(`Left Gui`)
- Swap Grave and Escape(`Grave`)
- Swap BackSlash and BackSpace(`Back Slash`)
- Enable NKRO on boot(`N`)
#### Default Layer
- Set Default Layer to 0(`0`)
- Set Default Layer to 1(`1`)
- Set Default Layer to 2(`2`)
- Set Default Layer to 3(`3`)
- Set Default Layer to 4(`4`)
- Set Default Layer to 5(`5`)
- Set Default Layer to 6(`6`)
- Set Default Layer to 7(`7`)
Mechanical Locking support
--------------------------
This feature makes it possible for you to use mechanical locking switch for `CapsLock`, `NumLock`
or `ScrollLock`. To enable this feature define these macros in `config.h` and use `KC_LCAP`, `KC_LN
UM` or `KC_LSCR` in keymap for locking key instead of normal `KC_CAPS`, `KC_NLCK` or `KC_SLCK`. Res
ync option tries to keep switch state consistent with keyboard LED state.
#define LOCKING_SUPPORT_ENABLE
#define LOCKING_RESYNC_ENABLE
Start Your Own Project
-----------------------
**TBD**
Debugging
--------
Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
You can use xprintf() to display debug info on `hid_listen`, see `tmk_core/common/xprintf.h`.
Files and Directories
-------------------
### Top
* tmk_core/ - core library
* keyboards/ - keyboard projects
* converter/ - protocol converter projects
* doc/ - documents
Coding Style
-------------
- Doesn't use Tab to indent, use 4-spaces instead.
Other Keyboard Firmware Projects
------------------
You can learn a lot about keyboard firmware from these. See [doc/other_projects.md](tmk_core/doc/other_projects.md).
## This guide may be out-dated - use doc/BUILD_GUIDE.md instead
Download and Install
--------------------
### 1. Install Tools
1.**Toolchain** On Windows install [MHV AVR Tools][mhv] for AVR GCC compiler and [Cygwin][cygwin](or [MinGW][mingw]) for shell terminal. On Mac you can use [CrossPack][crosspack]. On Linux you can install AVR GCC (and avr-libc) with your favorite package manager or run the avr_setup.sh script in the root of this repository.
2.**Programmer** On Windows install [Atmel FLIP][flip]. On Mac and Linux install [dfu-programmer][dfu-prog].
3.**Driver** On Windows you start DFU bootloader on the chip first time you will see 'Found New Hardware Wizard' to install driver. If you install device driver properly you can find chip name like 'ATmega32U4' under 'LibUSB-Win32 Devices' tree on 'Device Manager'. If not you shall need to update its driver on 'Device Manager'. You will find the driver in `FLIP` install directory like: C:\Program Files (x86)\Atmel\Flip 3.4.5\usb\. In case of `dfu-programmer` use its driver.
If you use PJRC Teensy you don't need step 2 and 3 above, just get [Teensy loader][teensy-loader].
### 2. Download source
You can find firmware source at github:
- <https://github.com/tmk/tmk_keyboard>
If you are familiar with `Git` tools you are recommended to use it but you can also download zip archive from:
Open terminal window to get access to commands. Use Cygwin(or MingGW) `shell terminal` in Windows or `Terminal.app` on Mac OSX. In Windows press `Windows` key and `R` then enter `cmd` in 'Run command' dialog showing up.
### 2. Change directory
Move to project directory in the firmware source.
cd tmk_keyboard/{'keyboard' or 'converter'}/<project>
### 3. Make
Build firmware using GNU `make` command. You'll see `<project>_<variant>.hex` file in that directory unless something unexpected occurs in build process.
make -f Makefile.<variant> clean
make -f Makefile.<variant>
Program Controller
------------------
Now you have **hex** file to program on current directory. This **hex** is only needed to program your controller, other files are used for development and you may leave and forget them.
### 1. Start bootloader
How to program controller depends on controller chip and its board design. To program AVR USB chips you'll need to start it up in bootloader mode. Most of boards with the chip have a push button to let bootloader come up. Consult with your controller board manual.
### 2. Program with DFU bootloader
Stock AVR USB chip including ATmega32U4 has DFU bootloader by factory default. `FLIP` is a DFU programmer on Windows offered by Atmel. Open source command line tool `dfu-programmer` also supports AVR chips, it runs on Linux, Mac OSX and even Windows.
To program AVR chip with DFU bootloader use `FLIP` or `dfu-programmer`.
If you have a proper program command in `Makefile` just type this.
`FLIP` has two version of tool, GUI app and command line program. If you want GUI see tutorial below.
To use command line tool run this command. Note that you need to set PATH variable properly.
$ make -f Makefile.<variant> flip
Or to program with `dfu-programmer` run:
$ make -f Makefile.<variant> dfu
#### FLIP GUI tutorial
1. On menu bar click Device -> Select, then. `ATmega32u4`.
2. On menu bar click Settings -> Communication -> USB, then click 'Open' button on 'USB Port Connection' dialog.
At this point you'll see grey-outed widgets on the app get colored and ready.
3. On menu bar click File -> Load HEX File, then select your firmware hex file on File Selector dialog.
4. On 'Operations Flow' panel click 'Run' button to load the firmware binary to the chip. Note that you should keep 'Erase', 'Blank Check', 'Program' and 'Verify' check boxes selected.
5. Re-plug USB cord or click 'Start Application' button to restart your controller.
If you have PJRC Teensy see instruction of `Teensy Loader`.
- <http://www.pjrc.com/teensy/loader.html>
Or use this command if you have command line version of Teensy Loader installed.
$ make -f Makefile.<variant> teensy
### 4. Program with Other programmer
You may want to use other programmer like `avrdude` with AVRISPmkII, Arduino or USBasp. In that case you can still use make target `program` for build with configuring `PROGRAM_CMD` in Makefile.
Optional. Set proper command for your controller, bootloader and programmer. This command can be used with `make program`. Not needed if you use `FLIP`, `dfu-programmer` or `Teensy Loader`.
QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains QMK Firmware, QMK Flasher, qmk.fm, and these docs. QMK Firmware is a keyboard firmware based on the [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.com), the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard, and the [Clueboard product line](http://clueboard.co/). It has also been ported to ARM chips using ChibiOS. You can use it to power your own hand-wired or custom keyboard PCB.
## How to get it {#how-to-get-it}
If you plan on contributing a keymap, keyboard, or features to QMK, the easiest thing to do is [fork the repo through Github](https://github.com/qmk/qmk_firmware#fork-destination-box), and clone your repo locally to make your changes, push them, then open a [Pull Request](https://github.com/qmk/qmk_firmware/pulls) from your fork.
Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), or clone it via git (`git@github.com:qmk/qmk_firmware.git`), or https (`https://github.com/qmk/qmk_firmware.git`).
## 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:
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:
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).
We welcome all keyboard projects into QMK, but ask that you try to stick to a couple guidelines that help us keep things organised and consistent.
## 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.
## `readme.md`
All projects need to have a `readme.md` file that explains what the keyboard is, who made it, where it is available, and links to move information (template coming).
## Image/Hardware files
In an effort to keep the repo size down, we're no longer accepting images of any format in the repo, with few exceptions. Hosting them elsewhere (imgur) and linking them in the readme.md is the preferred method.
Any sort of hardware file (plate, case, pcb) can't be stored in qmk_firmware, but we have the [qmk.fm repo](https://github.com/qmk/qmk.fm) where such files (as well as in-depth info) can be store, and viewed on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` directory for an example.
## Non-production/handwired projects
We're happy to accept any project that uses QMK, including prototypes and handwired ones, but we have a separate `/keyboards/handwired/` folder for them, so the main `/keyboards/` folder doesn't get overcrowded. If a prototype project becomes a production project at some point in the future, we'd be happy to move it to the main `/keyboards/` folder!
## Warnings as errors
When developing your keyboard, keep in mind that all warnings will be treated as errors - these small warnings can build-up and cause larger errors down the road (and keeping them is generally a bad practice).
## 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:
Copyright 2017 Your Name <your@email.com>
## Technical details
If you're looking for more information on making your keyboard work with QMK, [check out this guide](porting_your_keyboard_to_qmk.md)!
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).
Whenever you press a key, the firmware of your keyboard can register this event.
It can register when the key is pressed, held and released.
This usually happens with a [periodic scan of key presses with a frequency around 100 hz](https://github.com/benblazak/ergodox-firmware/blob/master/references.md#typical-keyboard-information).
This speed often is limited by the mechanical key response time, the protocol
to transfer those key presses (here USB HID), and by the software it is used in.
This usually happens with a periodic scan of key presses. This speed often is limited by the mechanical key response time, the protocol to transfer those key presses (here USB HID), and by the software it is used in.
## 2. What the Firmware Sends
The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf)
tells what a keyboard can actually send through USB to have a chance to be
properly recognised. This includes a pre-defined list of keycodes which are
simple numbers from `0x00` to `0xE7`. The firmware assigns a keycode to each
key of the keyboard.
The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
The firmware does not send actually letters or characters, but only keycodes.
Thus, by modifying the firmware, you only can modify what keycode is sent over
The firmware does not send actually letters or characters, but only scancodes.
Thus, by modifying the firmware, you only can modify what scancode is sent over
USB for a given key.
## 3. What the Operating System Does
@@ -45,49 +39,31 @@ Once the keycode reaches the operating system, a piece of software has to have
it match an actual character thanks to a keyboard layout. For example, if your
layout is set to QWERTY, a sample of the matching table is as follow:
``` text
| keycode | character |
|---------+-----------|
| 0x04 | a/A |
| 0x05 | b/B |
| 0x06 | c/C |
| ... | ... |
| 0x1C | y/Y |
| 0x1D | z/Z |
| ... | ... |
|---------+-----------|
```
|---------|-----------|
| 0x04 | a/A |
| 0x05 | b/B |
| 0x06 | c/C |
| ... | ... |
| 0x1C | y/Y |
| 0x1D | z/Z |
| ... | ... |
## Back to the firmware
As the layout is generally fixed (unless you create your own), the firmware can
actually call a keycode by its layout name directly to ease things for you.
This is exactly what is done here with `KC_A` actually representing `0x04` in
QWERTY. The full list can be found in `keycode.txt`.
As the layout is generally fixed (unless you create your own), the firmware can actually call a keycode by its layout name directly to ease things for you. This is exactly what is done here with `KC_A` actually representing `0x04` in QWERTY. The full list can be found in `keycode.txt`.
## List of Characters You Can Send
Putting aside shortcuts, having a limited set of keycodes mapped to a limited
layout means that **the list of characters you can assign to a given key only
is the ones present in the layout**.
Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key only is the ones present in the layout**.
For example, this means that if you have a QWERTY US layout, and you want to
assign 1 key to produce `€` (euro currency symbol), you are unable to do so,
because the QWERTY US layout does not have such mapping. You could fix that by
using a QWERTY UK layout, or a QWERTY US International.
For example, this means that if you have a QWERTY US layout, and you want to assign 1 key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
You may wonder why a keyboard layout containing all of Unicode is not devised
then? The limited number of keycode available through USB simply disallow such
a thing.
You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycode available through USB simply disallow such a thing.
## How to (Maybe) Enter Unicode Characters
You can have the firmware send *sequences of keys* to use the [software Unicode
Input
Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of
the target operating system, thus effectively entering characters independently
of the layout defined in the OS.
You can have the firmware send *sequences of keys* to use the [software Unicode Input Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of the target operating system, thus effectively entering characters independently of the layout defined in the OS.
A QMK collaborator is a keyboard maker/designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users/customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements:
* **Have a PCB available for sale** - unfortunately there's just too much variation and complications with handwired keyboards.
* **Maintain the your keyboard's directory** - this may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core.
* **Approve and merge your keyboard's keymap pull requests** - we like to encourage users to contribute their keymaps for others to see and work from when creating their own.
If you feel you meet these requirements, shoot us an email at hello@qmk.fm with an introduction and some links to your keyboard!
This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4.)
<!-- FIXME: We should have ARM instructions somewhere. -->
# Windows 10
## Creators Update
If you have Windows 10 with Creators Update or later, you can build and flash the firmware directly. Before the Creators Update, only building was possible. If you don't have it yet or if are unsure, follow [these instructions](https://support.microsoft.com/en-us/instantanswers/d4efb316-79f0-1aa1-9ef3-dcada78f3fa0/get-the-windows-10-creators-update).
## Windows Subsystem for Linux
In addition to the Creators Update, you need Windows 10 Subystem for Linux, so install it following [these instructions](http://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/). If you already have the Windows 10 Subsystem for Linux from the Anniversary update it's recommended that you [upgrade](https://betanews.com/2017/04/14/upgrade-windows-subsystem-for-linux/) it to 16.04LTS, because some keyboards don't compile with the toolchains included in 14.04LTS. Note that you need to know what your are doing if you chose the `sudo do-release-upgrade` method.
## Git
If you already have cloned the repository on your Windows file system you can ignore this section.
You will need to clone the repository to your Windows file system using the normal Git for Windows and **not** the WSL Git. So if you haven't installed Git before, [download](https://git-scm.com/download/win) and install it. Then [set it up](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup), it's important that you setup the e-mail and user name, especially if you are planning to contribute.
Once Git is installed, open the Git bash command and change the directory to where you want to clone QMK, note that you have to use forward slashes, and that your c drive is accessed like this `/c/path/to/where/you/want/to/go`. Then run `git clone --recurse-submodules https://github.com/qmk/qmk_firmware`, this will create a new folder `qmk_firmware` as a subfolder of the current one.
## Toolchain setup
The Toolchain setup is done through the Windows Subsystem for Linux, and the process is fully automated. If you want to do everything manually, there are no other instructions than the scripts themselves, but you can always open issues and ask for more information.
1. Open "Bash On Ubuntu On Windows" from the start menu.
2. Go to the directory where you cloned `qmk_firmware`. Note that the paths start with `/mnt/` in the WSL, so you have to write for example `cd /mnt/c/path/to/qmk_firmware`.
3. Run `util/wsl_install.sh` and follow the on-screen instructions.
4. Close the Bash command window, and re-open it.
5. You are ready to compile and flash the firmware!
## Some important things to keep in mind
* You can run `util/wsl_install.sh` again to get all the newest updates.
* Your QMK repository need to be on a Windows file system path, since WSL can't run executables outside it.
* The WSL Git is **not** compatible with the Windows Git, so use the Windows Git Bash or a windows Git GUI for all Git operations
* You can edit files either inside WSL or normally using Windows, but note that if you edit makefiles or shell scripts, make sure you are using an editor that saves the files with Unix line endings. Otherwise the compilation might not work.
# Windows (Vista and later)
1. If you have ever installed WinAVR, uninstall it.
2. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**.
3. If you are going to flash Infinity based keyboards you will need to install dfu-util, refer to the instructions by [Input Club](https://github.com/kiibohd/controller/wiki/Loading-DFU-Firmware).
4. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location.
5. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/qmk/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer.
6. Open the `\util` folder.
7. Double-click on the `1-setup-path-win` batch script to run it. You'll need to accept a User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up.
8. Right-click on the `2-setup-environment-win` batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete!
If you have trouble and want to ask for help, it is useful to generate a *Win_Check_Output.txt* file by running `Win_Check.bat` in the `\util` folder.
# Mac
If you're using [homebrew,](http://brew.sh/) you can use the following commands:
brew tap osx-cross/avr
brew install avr-libc
brew install dfu-programmer
This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of avr-libc can take over 20 minutes and exhibit high CPU usage.
You can also try these instructions:
1. Install Xcode from the App Store.
2. Install the Command Line Tools from `Xcode->Preferences->Downloads`.
If you are going to flash Infinity based keyboards you will also need dfu-util
brew install dfu-util
# Linux
To ensure you are always up to date, you can just run `sudo util/install_dependencies.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.**
You can also install things manually, but this documentation might not be always up to date with all requirements.
The current requirements are the following, but not all might be needed depending on what you do. Also note that some systems might not have all the dependencies available as packages, or they might be named differently.
```
build-essential
gcc
unzip
wget
zip
gcc-avr
binutils-avr
avr-libc
dfu-programmer
dfu-util
gcc-arm-none-eabi
binutils-arm-none-eabi
libnewlib-arm-none-eabi
git
```
Install the dependencies with your favorite package manager.
If this is a bit complex for you, Docker might be the turn-key solution you need. After installing [Docker](https://www.docker.com/products/docker), run the following command at the root of the QMK folder to build a keyboard/keymap:
```bash
# You'll run this every time you want to build a keymap
# modify the keymap and keyboard assigment to compile what you want
# On windows docker seems to have issue with VOLUME tag in Dockerfile, and $('pwd') won't print a windows compliant path, use full path instead like this
This will compile the targeted keyboard/keymap and leave it in your QMK directory for you to flash.
# Vagrant
If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](vagrant_guide.md).
# Verify Your Installation
1. If you haven't already, obtain this repository ([https://github.com/qmk/qmk_firmware](https://github.com/qmk/qmk_firmware)). You can either download it as a zip file and extract it, or clone it using the command line tool git or the Github Desktop application.
2. Open up a terminal or command prompt and navigate to the `qmk_firmware` folder using the `cd` command. The command prompt will typically open to your home directory. If, for example, you cloned the repository to your Documents folder, then you would type `cd Documents/qmk_firmware`. If you extracted the file from a zip, then it may be named `qmk_firmware-master` instead.
3. To confirm that you're in the correct location, you can display the contents of your current folder using the `dir` command on Windows, or the `ls` command on Linux or Mac. You should see several files, including `readme.md` and a `quantum` folder. From here, you need to navigate to the appropriate folder under `keyboards/`. For example, if you're building for a Planck, run `cd keyboards/planck`.
4. Once you're in the correct keyboard-specific folder, run the `make` command. This should output a lot of information about the build process. More information about the `make` command can be found below.
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.
Fred Sundvik
plgruener