_/qmk_firmware
1
0
Fork 0
Code Releases Activity

convert docs to lowercase and underscores

Browse source
This commit is contained in:
Jack Humbert 2017-06-10 14:58:55 -04:00
parent ca01d94005
commit 995c3141a6
19 changed files with 1311 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
docs/_summary.md Normal file
View file

@ -0,0 +1,28 @@
### Getting started
* [Introduction](home.md)
* [QMK Overview](qmk_overview.md)
* [Build Environment Setup](build_environment_setup.md)
### Making a keymap
* [Keymap overview](keymap.md)
* [Custom Quantum Functions](custom_quantum_functions.md)
* [Keycodes](keycodes.md)
* [Layer switching](key_functions.md)
* [Leader Key](leader_key.md)
* [Macros](macros.md)
* [Dynamic Macros](dynamic_macros.md)
* [Space Cadet](space_cadet_shift.md)
* [Tap Dance](tap_dance.md)
* [Mouse keys](mouse_keys.md)
* [FAQ: Creating a Keymap](faq_keymap.md)
* [FAQ: Compiling QMK](faq_build.md)
### For hardware makers and modders
* [Modding your keyboard](modding_your_keyboard.md)
* [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md)
* [Adding features to QMK](adding_features_to_qmk.md)
### Other topics
* [General FAQ](faq.md)
* [Differences from TMK](differences_from_tmk.md)

151
docs/pcb_guide.md Normal file
View file

@ -0,0 +1,151 @@
# Planck Firmware Guide
## Setting up the environment
### Windows
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
/usr/bin/sh: fork: Resource temporarily unavailable
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!
If you see this
dfu-programmer atmega32u4 erase
process_begin: CreateProcess(NULL, dfu-programmer atmega32u4 erase, ...) failed.
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/qmk/qmk_firmware/blob/master/tmk_core/common/action_code.h). They are explained in detail [here](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.
[cygwin]: https://www.cygwin.com/
[mingw]: http://www.mingw.org/
[mhv]: https://infernoembedded.com/products/avr-tools
[winavr]: http://winavr.sourceforge.net/
[crosspack]: http://www.obdev.at/products/crosspack/index.html
[dfu-prog]: http://dfu-programmer.sourceforge.net/

59
docs/porting_your_keyboard_to_qmk.md Normal file
View file

@ -0,0 +1,59 @@
If your keyboard is running an Atmega chip (atmega32u4 and others), it's pretty easy to get things setup for compiling your own firmware to flash onto your board. There is a `/util/new_project.sh <keyboard>` script to help get you started - you can simply pass your keyboard's name into the script, and all of the necessary files will be created. The components of each are described below.
## `/keyboards/<keyboard>/config.h`
The `USB Device descriptor parameter` block contains parameters are used to uniquely identify your keyboard, but they don't really matter to the machine.
Your `MATRIX_ROWS` and `MATRIX_COLS` are the numbers of rows and cols in your keyboard matrix - this may be different than the number of actual rows and columns on your keyboard. There are some tricks you can pull to increase the number of keys in a given matrix, but most keyboards are pretty straight-forward.
The `MATRIX_ROW_PINS` and `MATRIX_COL_PINS` are the pins your MCU uses on each row/column. Your schematic (if you have one) will have this information on it, and the values will vary depending on your setup. This is one of the most important things to double-check in getting your keyboard setup correctly.
For the `DIODE_DIRECTION`, most hand-wiring guides will instruct you to wire the diodes in the `COL2ROW` position, but it's possible that they are in the other - people coming from EasyAVR often use `ROW2COL`. Nothing will function if this is incorrect.
`BACKLIGHT_PIN` is the pin that your PWM-controlled backlight (if one exists) is hooked-up to. Currently only B5, B6, and B7 are supported.
`BACKLIGHT_BREATHING` is a fancier backlight feature that adds breathing/pulsing/fading effects to the backlight. It uses the same timer as the normal backlight. These breathing effects must be called by code in your keymap.
`BACKLIGHT_LEVELS` is how many levels exist for your backlight - max is 15, and they are computed automatically from this number.
## `/keyboards/<keyboard>/Makefile`
The values at the top likely won't need to be changed, since most boards use the `atmega32u4` chip. The `BOOTLOADER_SIZE` will need to be adjusted based on your MCU type. It's defaulted to the Teensy, since that's the most common controller. Below is quoted from the `Makefile`.
```
# Boot Section Size in *bytes*
# Teensy halfKay 512
# Teensy++ halfKay 1024
# Atmel DFU loader 4096
# LUFA bootloader 4096
# USBaspLoader 2048
OPT_DEFS += -DBOOTLOADER_SIZE=512
```
At the bottom of the file, you'll find lots of features to turn on and off - all of these options should be set with `?=` to allow for the keymap overrides. `?=` only assigns if the variable was previously undefined. For the full documenation of these features, see the [Makefile options](#makefile-options).
## `/keyboards/<keyboard>/readme.md`
This is where you'll describe your keyboard - please write as much as you can about it! Talking about default functionality/features is useful here. Feel free to link to external pages/sites if necessary. Images can be included here as well. This file will be rendered into a webpage at qmk.fm/keyboards/<keyboard>/.
## `/keyboards/<keyboard>/<keyboard>.c`
This is where all of the custom logic for your keyboard goes - you may not need to put anything in this file, since a lot of things are configured automatically. All of the `*_kb()` functions are defined here. If you modify them, remember to keep the calls to `*_user()`, or things in the keymaps might not work. You can read more about the functions [here](#custom-quantum-functions-for-keyboards-and-keymaps)
## `/keyboards/<keyboard>/<keyboard>.h`
Here is where you can (optionally) define your `KEYMAP` function to remap your matrix into a more readable format. With ortholinear boards, this isn't always necessary, but it can help to accomodate the dead spots on your matrix, where there are keys that take up more than one space (2u, staggering, 6.25u, etc). The example shows the difference between the physical keys, and the matrix design:
```
#define KEYMAP( \
k00, k01, k02, \
k10, k11 \
) \
{ \
{ k00, k01, k02 }, \
{ k10, KC_NO, k11 }, \
}
```
Each of the `kxx` variables needs to be unique, and usually follows the format `k<row><col>`. You can place `KC_NO` where your dead keys are in your matrix.

70
docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md Normal file
View file

@ -0,0 +1,70 @@
Setting up your ARM based PCB is a little more involved than an Atmel MCU, but is easy enough. Start by using `util/new_project.sh <keyboard>` to create a new project:
```
$ util/new_project.sh simontester
######################################################
# /keyboards/simontester project created. To start
# working on things, cd into keyboards/simontester
######################################################
```
# END OF NEW ARM DOC, OLD ATMEL DOC FOLLOWS
## `/keyboards/<keyboard>/config.h`
The `USB Device descriptor parameter` block contains parameters are used to uniquely identify your keyboard, but they don't really matter to the machine.
Your `MATRIX_ROWS` and `MATRIX_COLS` are the numbers of rows and cols in your keyboard matrix - this may be different than the number of actual rows and columns on your keyboard. There are some tricks you can pull to increase the number of keys in a given matrix, but most keyboards are pretty straight-forward.
The `MATRIX_ROW_PINS` and `MATRIX_COL_PINS` are the pins your MCU uses on each row/column. Your schematic (if you have one) will have this information on it, and the values will vary depending on your setup. This is one of the most important things to double-check in getting your keyboard setup correctly.
For the `DIODE_DIRECTION`, most hand-wiring guides will instruct you to wire the diodes in the `COL2ROW` position, but it's possible that they are in the other - people coming from EasyAVR often use `ROW2COL`. Nothing will function if this is incorrect.
`BACKLIGHT_PIN` is the pin that your PWM-controlled backlight (if one exists) is hooked-up to. Currently only B5, B6, and B7 are supported.
`BACKLIGHT_BREATHING` is a fancier backlight feature that adds breathing/pulsing/fading effects to the backlight. It uses the same timer as the normal backlight. These breathing effects must be called by code in your keymap.
`BACKLIGHT_LEVELS` is how many levels exist for your backlight - max is 15, and they are computed automatically from this number.
## `/keyboards/<keyboard>/Makefile`
The values at the top likely won't need to be changed, since most boards use the `atmega32u4` chip. The `BOOTLOADER_SIZE` will need to be adjusted based on your MCU type. It's defaulted to the Teensy, since that's the most common controller. Below is quoted from the `Makefile`.
```
# Boot Section Size in *bytes*
# Teensy halfKay 512
# Teensy++ halfKay 1024
# Atmel DFU loader 4096
# LUFA bootloader 4096
# USBaspLoader 2048
OPT_DEFS += -DBOOTLOADER_SIZE=512
```
At the bottom of the file, you'll find lots of features to turn on and off - all of these options should be set with `?=` to allow for the keymap overrides. `?=` only assigns if the variable was previously undefined. For the full documenation of these features, see the [Makefile options](#makefile-options).
## `/keyboards/<keyboard>/readme.md`
This is where you'll describe your keyboard - please write as much as you can about it! Talking about default functionality/features is useful here. Feel free to link to external pages/sites if necessary. Images can be included here as well. This file will be rendered into a webpage at qmk.fm/keyboards/<keyboard>/.
## `/keyboards/<keyboard>/<keyboard>.c`
This is where all of the custom logic for your keyboard goes - you may not need to put anything in this file, since a lot of things are configured automatically. All of the `*_kb()` functions are defined here. If you modify them, remember to keep the calls to `*_user()`, or things in the keymaps might not work. You can read more about the functions [here](#custom-quantum-functions-for-keyboards-and-keymaps)
## `/keyboards/<keyboard>/<keyboard>.h`
Here is where you can (optionally) define your `KEYMAP` function to remap your matrix into a more readable format. With ortholinear boards, this isn't always necessary, but it can help to accomodate the dead spots on your matrix, where there are keys that take up more than one space (2u, staggering, 6.25u, etc). The example shows the difference between the physical keys, and the matrix design:
```
#define KEYMAP( \
k00, k01, k02, \
k10, k11 \
) \
{ \
{ k00, k01, k02 }, \
{ k10, KC_NO, k11 }, \
}
```
Each of the `kxx` variables needs to be unique, and usually follows the format `k<row><col>`. You can place `KC_NO` where your dead keys are in your matrix.

62
docs/power.txt Normal file
View file

@ -0,0 +1,62 @@
Time to Sleep
=============
USB suspend no activity on USB line for 3ms
No Interaction no user interaction
matrix has no change
matrix has no switch on
AVR Power Management
====================
V-USB suspend
USB suspend
http://vusb.wikidot.com/examples
MCUSR MCU Status Register
WDRF Watchdog Reset Flag
BORF
EXTRF
PORF Power-on Reset Flag
SMCR Sleep Mode Control Register
SE Sleep Enable
SM2:0
#define set_sleep_mode(mode) \
#define SLEEP_MODE_IDLE (0)
#define SLEEP_MODE_ADC _BV(SM0)
#define SLEEP_MODE_PWR_DOWN _BV(SM1)
#define SLEEP_MODE_PWR_SAVE (_BV(SM0) | _BV(SM1))
#define SLEEP_MODE_STANDBY (_BV(SM1) | _BV(SM2))
#define SLEEP_MODE_EXT_STANDBY (_BV(SM0) | _BV(SM1) | _BV(SM2))
ACSR Analog Comparator Control and Status Register
To disable Analog Comparator
ACSR = 0x80;
or
ACSR &= ~_BV(ACIE);
ACSR |= _BV(ACD);
ACD: Analog Comparator Disable
When this bit is written logic one, the power to the Analog Comparator is
switched off. This bit can be set at any time to turn off the Analog
Comparator. This will reduce power consumption in Active and Idle mode.
When changing the ACD bit, the Analog Comparator Interrupt must be disabled
by clearing the ACIE bit in ACSR. Otherwise an interrupt can occur when
the bit is changed.
DIDR1 Digital Input Disable Register 1
AIN1D
AIN0D
When this bit is written logic one, the digital input buffer on the AIN1/0 pin is disabled. The corresponding PIN Register bit will always read as zero when this bit is set. When an analog signal is applied to the AIN1/0 pin and the digital input from this pin is not needed, this bit should be written logic one to reduce power consumption in the digital input buffer.
PRR Power Reduction Register
PRTWI
PRTIM2
PRTIM0
PRTIM1
PRSPI
PRUSART0
PRADC

14
docs/previously_asked_questions.asciidoc Normal file
View file

@ -0,0 +1,14 @@
= Previously Asked Questions
:toc:
:toc-placement: preamble
toc::[]
= Question thread
http://deskthority.net/workshop-f7/how-to-build-your-very-own-keyboard-firmware-t7177-270.html
= Questions
== Columns beyond 16(uint16_t) cannot be read
* https://github.com/tmk/tmk_keyboard/wiki/FAQ#cant-read-comlumn-of-matrix-beyond-16
* http://deskthority.net/workshop-f7/how-to-build-your-very-own-keyboard-firmware-t7177-270.html#p247051
* http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279

75
docs/qmk_overview.md Normal file
View file

@ -0,0 +1,75 @@
# QMK Overview
This page attempts to explain the basic information you need to know to work with the QMK project. It assumes that you are familiar with navigating a UNIX shell, but does not assume you are familiar with C or with compiling using make.
# Basic QMK structure
QMK is a fork of @tmk's [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
## Keyboard project structure
Within the `handwired` and `keyboard` folders is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within you'll find the following structure:
* `keymaps/`: Different keymaps that can be built
* `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `Makefile`.
* `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`.
### Keymap structure
In every keymap folder, the following files may be found. Only `keymap.c` is required, if the rest of the files are not found the default options will be chosen.
* `config.h`: the options to configure your keymap
* `keymap.c`: all of your keymap code, required
* `Makefile`: the features of QMK that are enabled, required to run `make` in your keymap folder
* `readme.md`: a description of your keymap, how others might use it, and explanations of features
* Other files: Some people choose to include an image depicting the layout, and other files that help people to use or understand a particular keymap.
# 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). It it recommended that you always run make from within the `root` folder.
**NOTE:** To abort a make command press `Ctrl-c`
For more details on the QMK build process see [Make Instructions](make_instructions.md).
### Simple instructions for building and uploading a keyboard
**Most keyboards have more specific instructions in the keyboard specific readme.md file, so please check that first**
1. Enter the `root` folder
2. Run `make <keyboard>-<subproject>-<keymap>-<programmer>`
In the above commands, replace:
* `<keyboard>` with the name of your keyboard
* `<keymap>` with the name of your keymap
* `<subproject>` with the name of the subproject (revision or sub-model of your keyboard). For example, for Ergodox it can be `ez` or `infinity`, and for Planck `rev3` or `rev4`.
* If the keyboard doesn't have a subproject, or if you are happy with the default (defined in `rules.mk` file of the `keyboard` folder), you can leave it out. But remember to also remove the dash (`-`) from the command.
* `<programmer>` The programmer to use. Most keyboards use `dfu`, but some use `teensy`. Infinity keyboards use `dfu-util`. Check the readme file in the keyboard folder to find out which programmer to use.
* If you don't add `-<programmer` to the command line, the firmware will be still be compiled into a hex file, but the upload will be skipped.
**NOTE:** Some operating systems will refuse to program unless you run the make command as root for example `sudo make clueboard-default-dfu`
## Make Examples
* Build all Clueboard keymaps: `make clueboard`
* Build the default Planck keymap: `make planck-rev4-default`
* Build and flash your ergodox-ez: `make ergodox-ez-default-teensy`
# The `config.h` file
There are 2 `config.h` locations:
* keyboard (`/keyboards/<keyboard>/`)
* keymap (`/keyboards/<keyboard>/keymaps/<keymap>/`)
The keyboard `config.h` is included only if the keymap one doesn't exist. The format to use for your custom one [is here](https://github.com/qmk/qmk_firmware/blob/master/doc/keymap_config_h_example.h). If you want to override a setting from the parent `config.h` file, you need to do this:
```c
#undef MY_SETTING
#define MY_SETTING 4
```
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
docs/report_descriptor.md Normal file
View file

@ -0,0 +1 @@
# Get Report Descriptor with lsusb

24
docs/space_cadet_shift.md Normal file
View file

@ -0,0 +1,24 @@
## Space Cadet Shift: The future, built in
Steve Losh [described](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) the Space Cadet Shift quite well. Essentially, you hit the left Shift on its own, and you get an opening parenthesis; hit the right Shift on its own, and you get the closing one. When hit with other keys, the Shift key keeps working as it always does. Yes, it's as cool as it sounds.
To use it, use `KC_LSPO` (Left Shift, Parens Open) for your left Shift on your keymap, and `KC_RSPC` (Right Shift, Parens Close) for your right Shift.
It's defaulted to work on US keyboards, but if your layout uses different keys for parenthesis, you can define those in your `config.h` like this:
#define LSPO_KEY KC_9
#define RSPC_KEY KC_0
You can also choose between different rollover behaviors of the shift keys by defining:
#define DISABLE_SPACE_CADET_ROLLOVER
in your `config.h`. Disabling rollover allows you to use the opposite shift key to cancel the space cadet state in the event of an erroneous press instead of emitting a pair of parentheses when the keys are released.
The only other thing you're going to want to do is create a `Makefile` in your keymap directory and set the following:
```
COMMAND_ENABLE = no # Commands for debug and configuration
```
This is just to keep the keyboard from going into command mode when you hold both Shift keys at the same time.

144
docs/tap_dance.md Normal file
View file

@ -0,0 +1,144 @@
# Tap Dance: A single key can do 3, 5, or 100 different things
Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature:
With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter.
To make it clear how this is different from `ACTION_FUNCTION_TAP`, lets explore a certain setup! We want one key to send `Space` on single tap, but `Enter` on double-tap.
With `ACTION_FUNCTION_TAP`, it is quite a rain-dance to set this up, and has the problem that when the sequence is interrupted, the interrupting key will be send first. Thus, `SPC a` will result in `a SPC` being sent, if they are typed within `TAPPING_TERM`. With the tap dance feature, that'll come out as `SPC a`, correctly.
The implementation hooks into two parts of the system, to achieve this: into `process_record_quantum()`, and the matrix scan. We need the latter to be able to time out a tap sequence even when a key is not being pressed, so `SPC` alone will time out and register after `TAPPING_TERM` time.
But lets start with how to use it, first!
First, you will need `TAP_DANCE_ENABLE=yes` in your `Makefile`, because the feature is disabled by default. This adds a little less than 1k to the firmware size. Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that - similar to `F()`, takes a number, which will later be used as an index into the `tap_dance_actions` array.
This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are three possible options:
* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. When the key is held, the appropriate keycode is registered: `kc1` when pressed and held, `kc2` when tapped once, then pressed and held.
* `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function on when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise.
And that's the bulk of it!
And now, on to the explanation of how it works!
The main entry point is `process_tap_dance()`, called from `process_record_quantum()`, which is run for every keypress, and our handler gets to run early. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. If it was the same, we increment the counter and the timer.
This means that you have `TAPPING_TERM` time to tap the key again, you do not have to input all the taps within that timeframe. This allows for longer tap counts, with minimal impact on responsiveness.
Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-dance keys.
For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros.
### Examples
Here's a simple example for a single definition:
1. In your `makefile`, add `TAP_DANCE_ENABLE = yes`
2. In your `config.h` (which you can copy from `qmk_firmware/keyboards/planck/config.h` to your keymap directory), add `#define TAPPING_TERM 200`
3. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
```c
//Tap Dance Declarations
enum {
TD_ESC_CAPS = 0
};
//Tap Dance Definitions
qk_tap_dance_action_t tap_dance_actions[] = {
//Tap once for Esc, twice for Caps Lock
[TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS)
// Other declarations would go here, separated by commas, if you have them
};
//In Layer declaration, add tap dance item in place of a key code
TD(TD_ESC_CAPS)
```
Here's a more complex example involving custom actions:
```c
enum {
CT_SE = 0,
CT_CLN,
CT_EGG,
CT_FLSH,
};
/* Have the above three on the keymap, TD(CT_SE), etc... */
void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
register_code (KC_RSFT);
register_code (KC_SCLN);
} else {
register_code (KC_SCLN);
}
}
void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
unregister_code (KC_RSFT);
unregister_code (KC_SCLN);
} else {
unregister_code (KC_SCLN);
}
}
void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 100) {
SEND_STRING ("Safety dance!");
reset_tap_dance (state);
}
}
// on each tap, light up one led, from right to left
// on the forth tap, turn them off from right to left
void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
switch (state->count) {
case 1:
ergodox_right_led_3_on();
break;
case 2:
ergodox_right_led_2_on();
break;
case 3:
ergodox_right_led_1_on();
break;
case 4:
ergodox_right_led_3_off();
_delay_ms(50);
ergodox_right_led_2_off();
_delay_ms(50);
ergodox_right_led_1_off();
}
}
// on the fourth tap, set the keyboard on flash state
void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 4) {
reset_keyboard();
reset_tap_dance(state);
}
}
// if the flash state didnt happen, then turn off leds, left to right
void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
ergodox_right_led_1_off();
_delay_ms(50);
ergodox_right_led_2_off();
_delay_ms(50);
ergodox_right_led_3_off();
}
qk_tap_dance_action_t tap_dance_actions[] = {
[CT_SE] = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
};
```

17
docs/test_for_asciidoc.asciidoc Normal file
View file

@ -0,0 +1,17 @@
.Makefile
[source,Makefile]
----
# Build Options
# comment out to disable the options.
#
BOOTMAGIC_ENABLE = yes # Virtual DIP switch configuration(+1000)
MOUSEKEY_ENABLE = yes # Mouse keys(+4700)
EXTRAKEY_ENABLE = yes # Audio control and System control(+450)
CONSOLE_ENABLE = yes # Console for debug(+400)
COMMAND_ENABLE = yes # Commands for debug and configuration
#SLEEP_LED_ENABLE = yes # Breathing sleep LED during USB suspend
NKRO_ENABLE = yes # USB Nkey Rollover - not yet supported in LUFA
----

34
docs/tmk_based_projects.md Normal file
View file

@ -0,0 +1,34 @@
## TMK based projects
Add your project here!
See https://github.com/tmk/tmk_keyboard/issues/173
### keyboards
**S60-X**: [DIY 60% keyboard](https://www.massdrop.com/buy/sentraq-60-diy-keyboard-kit?mode=guest_open) designed by [VinnyCordeiro](https://github.com/VinnyCordeiro) for Sentraq:
- https://github.com/VinnyCordeiro/tmk_keyboard
**Octagon V1**: Korean custom keyboard designed by Duck.
- https://github.com/xauser/tmk_keyboard/tree/xauser
**Compact L3**: Custom keyboard designed by LifeZone and LeeKu.
- https://github.com/xauser/tmk_keyboard/tree/xauser
**KMAC, 1,2 and Happy**: Custom keyboard designed by kbdmania.
- https://github.com/ageaenes/tmk_keyboard
**P60**: [DIY wired 60% keyboard](https://imgur.com/a/zwsDN) by [p3lim](https://github.com/p3lim).
- https://github.com/p3lim/keyboard_firmware
**Nerd, Kitten Paw, Lightsaber, Phantom, Lightpad, Ergodox** on [xauser](https://github.com/xauser)'s repository
- https://github.com/xauser/tmk_keyboard/tree/xauser
**ErgoDox** on [cub-unanic](https://github.com/cub-uanic)'s repository
- https://github.com/cub-uanic/tmk_keyboard/tree/master/keyboard/ergodox
**Atreus** by [technomancy](https://atreus.technomancy.us)
- https://github.com/technomancy/tmk_keyboard/tree/atreus/keyboard/atreus
**[mcdox](https://github.com/DavidMcEwan/mcdox)**
- https://github.com/DavidMcEwan/tmk_keyboard/tree/master/keyboard/mcdox
### converters

69
docs/tmk_own_projects.md Normal file
View file

@ -0,0 +1,69 @@
## TMK own projects by hasu
Located in [tmk_keyboard](https://github.com/tmk/tmk_keyboard/tree/master/) repository.
### converter
* [ps2_usb] - [PS/2 keyboard to USB][GH_ps2]
* [adb_usb] - [ADB keyboard to USB][GH_adb]
* [m0110_usb] - [Macintosh 128K/512K/Plus keyboard to USB][GH_m0110]
* [terminal_usb] - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal]
* [news_usb] - [Sony NEWS keyboard to USB][GH_news]
* [x68k_usb] - [Sharp X68000 keyboard to USB][GH_x68k]
* [sun_usb] - [Sun] to USB(type4, 5 and 3?)
* [pc98_usb] - [PC98] to USB
* [usb_usb] - USB to USB(experimental)
* [ascii_usb] - ASCII(Serial console terminal) to USB
* [ibm4704_usb] - [IBM 4704 keyboard Converter][GH_ibm4704]
### keyboard
* [hhkb] - [Happy Hacking Keyboard pro][GH_hhkb]
* [gh60] - [GH60][GH60_diy] DIY 60% keyboard [prototype][GH60_proto]
* [hbkb] - [Happy Buckling spring keyboard][GH_hbkb](IBM Model M 60% mod)
* [hid_liber] - [HID liberation][HID_liber] controller (by alaricljs)
* [phantom] - [Phantom] keyboard (by Tranquilite)
* [IIgs_Standard] - Apple [IIGS] keyboard mod(by JeffreySung)
* [macway] - [Compact keyboard mod][GH_macway] [retired]
* [KMAC] - Korean custom keyboard
* [Lightsaber] - Korean custom keyboard
[ps2_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/ps2_usb/
[adb_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/adb_usb/
[m0110_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/m0110_usb
[terminal_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/terminal_usb/
[news_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/news_usb/
[x68k_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/x68k_usb/
[sun_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/sun_usb/
[pc98_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/pc98_usb/
[usb_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/usb_usb/
[ascii_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/ascii_usb/
[ibm4704_usb]: https://github.com/tmk/tmk_keyboard/tree/master/converter/ibm4704_usb
[hhkb]: https://github.com/tmk/tmk_keyboard/tree/master/keyboard/hhkb/
[gh60]: https://github.com/tmk/tmk_keyboard/tree/master/keyboard/gh60/
[hbkb]: https://github.com/tmk/tmk_keyboard/tree/master/keyboard/hbkb/
[hid_liber]: https://github.com/tmk/tmk_keyboard/tree/master/keyboard/hid_liber/
[phantom]: https://github.com/tmk/tmk_keyboard/tree/master/keyboard/phantom/
[IIgs_Standard]: https://github.com/tmk/tmk_keyboard/tree/master/keyboard/IIgs/
[macway]: https://github.com/tmk/tmk_keyboard/tree/master/keyboard/macway/
[KMAC]: https://github.com/tmk/tmk_keyboard/tree/master/keyboard/kmac/
[Lightsaber]: https://github.com/tmk/tmk_keyboard/tree/master/keyboard/lightsaber/
[GH_macway]: http://geekhack.org/showwiki.php?title=Island:11930
[GH_hhkb]: http://geekhack.org/showwiki.php?title=Island:12047
[GH_ps2]: http://geekhack.org/showwiki.php?title=Island:14618
[GH_adb]: http://geekhack.org/showwiki.php?title=Island:14290
[GH_hhkb_bt]: http://geekhack.org/showwiki.php?title=Island:20851
[GH_m0110]: http://geekhack.org/showwiki.php?title=Island:24965
[GH_news]: http://geekhack.org/showwiki.php?title=Island:25759
[GH_terminal]: http://geekhack.org/showwiki.php?title=Island:27272
[GH_x68k]: http://geekhack.org/showwiki.php?title=Island:29060
[GH_hbkb]: http://geekhack.org/showwiki.php?title=Island:29483
[GH_ibm4704]: http://geekhack.org/index.php?topic=54706.0
[HID_liber]: http://deskthority.net/wiki/HID_Liberation_Device_-_DIY_Instructions
[Phantom]: http://geekhack.org/index.php?topic=26742
[GH60_diy]: http://geekhack.org/index.php?topic=34959
[GH60_proto]: http://geekhack.org/index.php?topic=37570.0
[PC98]: http://en.wikipedia.org/wiki/NEC_PC-9801
[Sun]: http://en.wikipedia.org/wiki/Sun-3
[IIGS]: http://en.wikipedia.org/wiki/Apple_IIGS
See other [[TMK Based Projects]]

243
docs/tmk_readme.md Normal file
View file

@ -0,0 +1,243 @@
# TMK Documenation
Features
--------
These features can be used in your keyboard.
* Multi-layer Keymap - Multiple keyboard layouts with layer switching
* Mouse key - Mouse control with keyboard
* System Control Key - Power Down, Sleep, Wake Up and USB Remote Wake up
* Media Control Key - Volume Down/Up, Mute, Next/Prev track, Play, Stop and etc
* USB NKRO - 120 keys(+ 8 modifiers) simultaneously
* PS/2 mouse support - PS/2 mouse(TrackPoint) as composite device
* Keyboard protocols - PS/2, ADB, M0110, Sun and other old keyboard protocols
* User Function - Customizable function of key with writing code
* Macro - Very primitive at this time
* Keyboard Tricks - Oneshot modifier and modifier with tapping feature
* Debug Console - Messages for debug and interaction with firmware
* Virtual DIP Switch - Configurations stored EEPROM(Boot Magic)
* Locking CapsLock - Mechanical switch support for CapsLock
* Breathing Sleep LED - Sleep indicator with charm during USB suspend
* Backlight - Control backlight levels
Projects
--------
You can find some keyboard specific projects under `converter` and `keyboard` directory.
## Main projects
### OLKB products
* [planck](keyboards/planck/) - [Planck] Ortholinear 40% keyboard
* [preonic](keyboards/preonic/) - [Preonic] Ortholinear 50% keyboard
* [atomic](keyboards/atomic/) - [Atomic] Ortholinear 60% keyboard
### Ergodox EZ
* [ergodox_ez](keyboards/ergodox/ez) - [Ergodox_EZ] Assembled split keyboard
## Other projects
### converter
* [ps2_usb](converter/ps2_usb/) - [PS/2 keyboard to USB][GH_ps2]
* [adb_usb](converter/adb_usb/) - [ADB keyboard to USB][GH_adb]
* [m0110_usb](converter/m0110_usb) - [Macintosh 128K/512K/Plus keyboard to USB][GH_m0110]
* [terminal_usb](converter/terminal_usb/) - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal]
* [news_usb](converter/news_usb/) - [Sony NEWS keyboard to USB][GH_news]
* [x68k_usb](converter/x68k_usb/) - [Sharp X68000 keyboard to USB][GH_x68k]
* [sun_usb](converter/sun_usb/) - [Sun] to USB(type4, 5 and 3?)
* [pc98_usb](converter/pc98_usb/) - [PC98] to USB
* [usb_usb](converter/usb_usb/) - USB to USB(experimental)
* [ascii_usb](converter/ascii_usb/) - ASCII(Serial console terminal) to USB
* [ibm4704_usb](converter/ibm4704_usb) - [IBM 4704 keyboard Converter][GH_ibm4704]
### keyboard
* [hhkb](keyboards/hhkb/) - [Happy Hacking Keyboard pro][GH_hhkb] hasu's main board
* [gh60](keyboards/gh60/) - [GH60] DIY 60% keyboard [prototype][GH60_proto] hasu's second board
* [hbkb](keyboards/hbkb/) - [Happy Buckling spring keyboard][GH_hbkb](IBM Model M 60% mod)
* [hid_liber](keyboards/hid_liber/) - [HID liberation][HID_liber] controller (by alaricljs)
* [phantom](keyboards/phantom/) - [Phantom] keyboard (by Tranquilite)
* [IIgs_Standard](keyboards/IIgs/) - Apple [IIGS] keyboard mod(by JeffreySung)
* [macway](keyboards/macway/) - [Compact keyboard mod][GH_macway] [retired]
* [KMAC](keyboards/kmac/) - Korean custom keyboard
* [Lightsaber](keyboards/lightsaber/) - Korean custom keyboard
* [Infinity](keyboards/infinity/) - Massdrop [Infinity keyboard][Infinity]
* [NerD](keyboards/nerd/) - Korean custom keyboard
* [KittenPaw](keyboards/kitten_paw) - Custom Majestouch controller
* [Lightpad](keyboards/lightpad) - Korean custom keypad
* [ghost_squid](keyboards/ghost_squid/) - [The Ghost Squid][ghost_squid] controller for [Cooler Master QuickFire XT][cmxt]
### Extenal projects using tmk_keyboard
* [ErgoDox_cub-uanic][cub-uanic] - Split Ergonomic Keyboard [ErgoDox][ergodox_org]
* [mcdox][mcdox_tmk] - [mcdox][mcdox]
[GH_macway]: http://geekhack.org/showwiki.php?title=Island:11930
[GH_hhkb]: http://geekhack.org/showwiki.php?title=Island:12047
[GH_ps2]: http://geekhack.org/showwiki.php?title=Island:14618
[GH_adb]: http://geekhack.org/showwiki.php?title=Island:14290
[GH_hhkb_bt]: http://geekhack.org/showwiki.php?title=Island:20851
[GH_m0110]: http://geekhack.org/showwiki.php?title=Island:24965
[GH_news]: http://geekhack.org/showwiki.php?title=Island:25759
[GH_terminal]: http://geekhack.org/showwiki.php?title=Island:27272
[GH_x68k]: http://geekhack.org/showwiki.php?title=Island:29060
[GH_hbkb]: http://geekhack.org/showwiki.php?title=Island:29483
[GH_ibm4704]: http://geekhack.org/index.php?topic=54706.0
[HID_liber]: http://deskthority.net/wiki/HID_Liberation_Device_-_DIY_Instructions
[Phantom]: http://geekhack.org/index.php?topic=26742
[GH60]: http://geekhack.org/index.php?topic=34959
[GH60_proto]: http://geekhack.org/index.php?topic=37570.0
[PC98]: http://en.wikipedia.org/wiki/NEC_PC-9801
[Sun]: http://en.wikipedia.org/wiki/Sun-3
[IIGS]: http://en.wikipedia.org/wiki/Apple_IIGS
[Infinity]: https://www.massdrop.com/buy/infinity-keyboard-kit
[ghost_squid]: http://deskthority.net/wiki/Costar_replacement_controllers#The_Ghost_Squid
[cmxt]: http://gaming.coolermaster.com/en/products/keyboard/quickfirext/
[ergodox_org]: http://ergodox.org/
[cub-uanic]: https://github.com/cub-uanic/tmk_keyboard/tree/master/keyboard/ergodox
[mcdox]: https://github.com/DavidMcEwan/mcdox
[mcdox_tmk]: https://github.com/DavidMcEwan/tmk_keyboard/tree/master/keyboard/mcdox
[Planck]: http://olkb.co/planck
[Preonic]: http://olkb.co/preonic
[Atomic]: http://olkb.co/atomic
[Ergodox_EZ]: https://www.indiegogo.com/projects/ergodox-ez-an-incredible-mechanical-keyboard
License
-------
**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](build_environment_setup.md), or the readme in the particular keyboards/* folder.
Change your keymap
------------------
See [keymap.md](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 [docs/other_projects.md](other_projects.md).

54
docs/unicode_and_additional_language_support.md Normal file
View file

@ -0,0 +1,54 @@
## Unicode support
There are three Unicode keymap definition method available in QMK:
### UNICODE_ENABLE
Supports Unicode input up to 0xFFFF. The keycode function is `UC(n)` in
keymap file, where *n* is a 4 digit hexadecimal.
### UNICODEMAP_ENABLE
Supports Unicode up to 0xFFFFFFFF. You need to maintain a separate mapping
table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file.
The keycode function is `X(n)` where *n* is the array index of the mapping
table.
### UCIS_ENABLE
TBD
Unicode input in QMK works by inputing a sequence of characters to the OS,
sort of like macro. Unfortunately, each OS has different ideas on how Unicode is inputted.
This is the current list of Unicode input method in QMK:
* UC_OSX: MacOS Unicode Hex Input support. Works only up to 0xFFFF. Disabled by default. To enable: go to System Preferences -> Keyboard -> Input Sources, and enable Unicode Hex.
* UC_LNX: Unicode input method under Linux. Works up to 0xFFFFF. Should work almost anywhere on ibus enabled distros. Without ibus, this works under GTK apps, but rarely anywhere else.
* UC_WIN: (not recommended) Windows built-in Unicode input. To enable: create registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad`, set its value to 1, and reboot. This method is not recommended because of reliability and compatibility issue, use WinCompose method below instead.
* UC_WINC: Windows Unicode input using WinCompose. Requires [WinCompose](https://github.com/samhocevar/wincompose). Works reliably under many (all?) variations of Windows.
## Additional language support
In `quantum/keymap_extras/`, you'll see various language files - these work the same way as the alternative layout ones do. Most are defined by their two letter country/language code followed by an underscore and a 4-letter abbreviation of its name. `FR_UGRV` which will result in a `ù` when using a software-implemented AZERTY layout. It's currently difficult to send such characters in just the firmware.
## International Characters on Windows
[AutoHotkey](https://autohotkey.com) allows Windows users to create custom hotkeys among others.
The method does not require Unicode support in the keyboard itself but depends instead of AutoHotkey running in the background.
First you need to select a modifier combination that is not in use by any of your programs.
CtrlAltWin is not used very widely and should therefore be perfect for this.
There is a macro defined for a mod-tab combo `LCAG_T`.
Add this mod-tab combo to a key on your keyboard, e.g.: `LCAG_T(KC_TAB)`.
This makes the key behave like a tab key if pressed and released immediately but changes it to the modifier if used with another key.
In the default script of AutoHotkey you can define custom hotkeys.
<^<!<#a::Send, ä
<^<!<#<+a::Send, Ä
The hotkeys above are for the combination CtrlAltGui and CtrlAltGuiShift plus the letter a.
AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.

68
docs/unit_testing.md Normal file
View file

@ -0,0 +1,68 @@
# Unit Testing
If you are new to unit testing, then you can find many good resources on internet. However most of it is scattered around in small pieces here and there, and there's also many different opinions, so I won't give any recommendations.
Instead I recommend these two books, explaining two different styles of Unit Testing in detail.
* "Test Driven Development: By Example: Kent Beck"
* "Growing Object-Oriented Software, Guided By Tests: Steve Freeman, Nat Pryce"
If you prefer videos there are Uncle Bob's [Clean Coders Videos](https://cleancoders.com/), which unfortunately cost quite a bit, especially if you want to watch many of them. But James Shore has a free [Let's Play](http://www.jamesshore.com/Blog/Lets-Play) video series.
## Google Test and Google Mock
It's possible to Unit Test your code using [Google Test](https://github.com/google/googletest). The Google Test framework also includes another component for writing testing mocks and stubs, called "Google Mock". For information how to write the actual tests, please refer to the documentation on that site.
## Use of C++
Note that Google Test and therefore any test has to be written in C++, even if the rest of the QMK codebases is written in C. This should hopefully not be a problem even if you don't know any C++, since there's quite clear documentation and examples of the required C++ features, and you can write the rest of the test code almost as you would write normal C. Note that some compiler errors which you might get can look quite scary, but just read carefully what it says, and you should be ok.
One thing to remember, is that you have to append `extern "C"` around all of your C file includes.
## Adding tests for new or existing features
If you want to unit test some feature, then take a look at the existing serial_link tests, in the `quantum/serial_link/tests folder`, and follow the steps below to create a similar structure.
1. If it doesn't already exist, add a test subfolder to the folder containing the feature.
2. Create a `testlist.mk` and a `rules.mk` file in that folder.
3. Include those files from the root folder `testlist.mk`and `build_test.mk` respectively.
4. Add a new name for your testgroup to the `testlist.mk` file. Each group defined there will be a separate executable. And that's how you can support mocking out different parts. Note that it's worth adding some common prefix, just like it's done for the serial_link tests. The reason for that is that the make command allows substring filtering, so this way you can easily run a subset of the tests.
5. Define the source files and required options in the `rules.mk` file.
* `_SRC` for source files
* `_DEFS` for additional defines
* `_INC` for additional include folders
6. Write the tests in a new cpp file inside the test folder you created. That file has to be one of the files included from the `rules.mk` file.
Note how there's several different tests, each mocking out a separate part. Also note that each of them only compiles the very minimum that's needed for the tests. It's recommend that you try to do the same. For a relevant video check out [Matt Hargett "Advanced Unit Testing in C & C++](https://www.youtube.com/watch?v=Wmy6g-aVgZI)
## Running the tests
To run all the tests in the codebase, type `make test`. You can also run test matching a substring by typing `make test-matchingsubstring` Note that the tests are always compiled with the native compiler of your platform, so they are also run like any other program on your computer.
## Debugging the tests
If there are problems with the tests, you can find the executable in the `./build/test` folder. You should be able to run those with GDB or a similar debugger.
## Full Integration tests
It's not yet possible to do a full integration test, where you would compile the whole firmware and define a keymap that you are going to test. However there are plans for doing that, because writing tests that way would probably be easier, at least for people that are not used to unit testing.
In that model you would emulate the input, and expect a certain output from the emulated keyboard.
# Tracing variables
Sometimes you might wonder why a variable gets changed and where, and this can be quite tricky to track down without having a debugger. It's of course possible to manually add print statements to track it, but you can also enable the variable trace feature. This works for both for variables that are changed by the code, and when the variable is changed by some memory corruption.
To take the feature into use add `VARIABLE_TRACE=x` to the end of you make command. `x` represents the number of variables you want to trace, which is usually 1.
Then at a suitable place in the code, call `ADD_TRACED_VARIABLE`, to begin the tracing. For example to trace all the layer changes, you can do this
```c
void matrix_init_user(void) {
ADD_TRACED_VARIABLE("layer", &layer_state, sizeof(layer_state));
}
```
This will add a traced variable named "layer" (the name is just for your information), which tracks the memory location of `layer_state`. It tracks 4 bytes (the size of `layer_state`), so any modification to the variable will be reported. By default you can not specify a size bigger than 4, but you can change it by adding `MAX_VARIABLE_TRACE_SIZE=x` to the end of the make command line.
In order to actually detect changes to the variables you should call `VERIFY_TRACED_VARIABLES` around the code that you think that modifies the variable. If a variable is modified it will tell you between which two `VERIFY_TRACED_VARIABLES` calls the modification happened. You can then add more calls to track it down further. I don't recommend spamming the codebase with calls. It's better to start with a few, and then keep adding them in a binary search fashion. You can also delete the ones you don't need, as each call need to store the file name and line number in the ROM, so you can run out of memory if you add too many calls.
Also remember to delete all the tracing code once you have found the bug, as you wouldn't want to create a pull request with tracing code.

11
docs/usb_hid.md Normal file
View file

@ -0,0 +1,11 @@
# Getting Report Descriptor
```
$ cd /sys/bus/usb/drivers/usbhid
$ ls
1-1.3.4:1.0 1-1.3.4:1.2 bind new_id uevent
1-1.3.4:1.1 1-1.3.4:1.3 module remove_id unbind
$ echo -n 1-1.4\:1.0 | sudo tee unbind
$ sudo lsusb -vvv -d 046d:c01d
$ echo -n 1-1.4\:1.0 | sudo tee bind
```

160
docs/usb_nkro.txt Normal file
View file

@ -0,0 +1,160 @@
USB NKRO MEMO
=============
2010/12/09
References
----------
USB - boot mode, NKRO, compatibility, etc...
http://geekhack.org/showthread.php?t=13162
NKey Rollover - Overview, Testing Methodology, and Results
http://geekhack.org/showwiki.php?title=NKey+Rollover+-+Overview+Testing+Methodology+and+Results
dfj's NKRO(2010/06)
http://geekhack.org/showpost.php?p=191195&postcount=251
http://geekhack.org/showthread.php?p=204389#post204389
Terminology
---------
NKRO
ghost
matrix
mechanical with diodes
membrane
OS Support Status
-----------------
USB NKRO is possible *without* a custom driver.
At least following OS's supports.
Windows7 64bit
WindowsXP
Windows2000 SP4
Ubuntu10.4(Linux 2.6)
MacOSX(To be tested)
Custom Driver for USB NKRO
--------------------------
NOT NEEDED
at least when using following report formats on Windows, Linux or MacOSX.
USB NKRO methods
----------------
1. Virtual keyboards
Keyboard can increase its KRO by using virtual keyboards with Standard or Extended report.
If the keyboard has 2 virtual keyboard with Standard report(6KRO), it gets 12KRO.
Using this method means the keyboard is a composite device.
2. Extended report
It needs large report size for this method to achieve NKRO.
If a keyboard has 101keys, it needs 103byte report. It seems to be inefficient.
3. Bitmap report
If the keyboard has less than 128keys, 16byte report will be enough for NKRO.
The 16byte report seems to be reasonable cost to get NKRO.
Report Format
-------------
Other report formats than followings are possible, though these format are typical one.
1. Standard 8bytes
modifiers(bitmap) 1byte
reserved 1byte(not used)
keys(array) 1byte*6
Standard report can send 6keys plus 8modifiers simultaneously.
Standard report is used by most keyboards in the marketplace.
Standard report is identical to boot protocol report.
Standard report is hard to suffer from compatibility problems.
2. Extended standard 16,32,64bytes
modifiers(bitmap) 1byte
reserved 1byte(not used)
keys(array) 1byte*(14,32,62)
Extended report can send N-keys by using N+2bytes.
Extended report is expected to be compatible with boot protocol.
3. Bitmap 16,32,64bytes
keys(bitmap) (16,32)bytes
Bitmap report can send at most 128keys by 16bytes and 256keys by 32bytes.
Bitmap report can achieve USB NKRO efficiently in terms of report size.
Bitmap report needs a deliberation for boot protocol implementation.
Bitmap report descriptor sample:
0x05, 0x01, // Usage Page (Generic Desktop),
0x09, 0x06, // Usage (Keyboard),
0xA1, 0x01, // Collection (Application),
// bitmap of modifiers
0x75, 0x01, // Report Size (1),
0x95, 0x08, // Report Count (8),
0x05, 0x07, // Usage Page (Key Codes),
0x19, 0xE0, // Usage Minimum (224),
0x29, 0xE7, // Usage Maximum (231),
0x15, 0x00, // Logical Minimum (0),
0x25, 0x01, // Logical Maximum (1),
0x81, 0x02, // Input (Data, Variable, Absolute), ;Modifier byte
// LED output report
0x95, 0x05, // Report Count (5),
0x75, 0x01, // Report Size (1),
0x05, 0x08, // Usage Page (LEDs),
0x19, 0x01, // Usage Minimum (1),
0x29, 0x05, // Usage Maximum (5),
0x91, 0x02, // Output (Data, Variable, Absolute),
0x95, 0x01, // Report Count (1),
0x75, 0x03, // Report Size (3),
0x91, 0x03, // Output (Constant),
// bitmap of keys
0x95, (REPORT_BYTES-1)*8, // Report Count (),
0x75, 0x01, // Report Size (1),
0x15, 0x00, // Logical Minimum (0),
0x25, 0x01, // Logical Maximum(1),
0x05, 0x07, // Usage Page (Key Codes),
0x19, 0x00, // Usage Minimum (0),
0x29, (REPORT_BYTES-1)*8-1, // Usage Maximum (),
0x81, 0x02, // Input (Data, Variable, Absolute),
0xc0 // End Collection
where REPORT_BYTES is a report size in bytes.
Considerations
--------------
Compatibility
boot protocol
minor/old system
Some BIOS doesn't send SET_PROTOCOL request, a keyboard can't switch to boot protocol mode.
This may cause a problem on a keyboard which uses other report than Standard.
Reactivity
USB polling time
OS/Driver processing time
Windows Problem
---------------
1. Windows accepts only 6keys in case of Standard report.
It should be able to send 6keys plus 8modifiers.
2. Windows accepts only 10keys in case of 16bytes Extended report.
It should be able to send 14keys plus 8modifiers.
3. Windows accepts only 18keys in case of 32bytes Extended report.
It should be able to send 30keys plus 8modifiers.
If keys are pressed in excess of the number, wrong keys are registered on Windows.
This problem will be reportedly fixed soon.(2010/12/05)
http://forums.anandtech.com/showpost.php?p=30873364&postcount=17
Tools for testing NKRO
----------------------
Browser App:
http://www.microsoft.com/appliedsciences/content/projects/KeyboardGhostingDemo.aspx
http://random.xem.us/rollover.html
Windows:
AquaKeyTest.exe http://geekhack.org/showthread.php?t=6643
Linux:
xkeycaps
xev
showkeys
EOF

27
docs/vagrant_guide.md Normal file
View file

@ -0,0 +1,27 @@
# Quick Start Directions
This project includes a Vagrantfile that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else using the Vagrantfile to build. This makes it much easier for people to help you troubleshoot any issues you encounter.
## Requirements
Using the `/Vagrantfile` in this repository requires you have [Vagrant](http://www.vagrantup.com/) as well as [VirtualBox](https://www.virtualbox.org/) (or [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](http://www.vagrantup.com/vmware) but the (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion).
*COMPATIBILITY NOTICE* Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:** `vagrant plugin install vagrant-vbguest`
Other than having Vagrant and Virtualbox installed and possibly a restart of your computer afterwards, you can simple run a 'vagrant up' anywhere inside the folder where you checked out this project and it will start a Linux virtual machine that contains all the tools required to build this project. There is a post Vagrant startup hint that will get you off on the right foot, otherwise you can also reference the build documentation below.
Build Firmware and Program Controller
-------------------------------------
See [build_guide.md](build_guide.md), or the readme in the particular keyboards/* folder.
Change your keymap
------------------
See [keymap.md](keymap.md).
## Flashing the firmware
The "easy" way to flash the firmware is using a tool from your host OS like the Teensy programming app. [ErgoDox EZ](/keyboards/ergodox/readme.md) gives a great example.
If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version.