diff options
Diffstat (limited to 'docs')
61 files changed, 7527 insertions, 0 deletions
diff --git a/docs/_summary.md b/docs/_summary.md new file mode 100644 index 0000000000..420003996f --- /dev/null +++ b/docs/_summary.md @@ -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) diff --git a/docs/adding_features_to_qmk.md b/docs/adding_features_to_qmk.md new file mode 100644 index 0000000000..f6f7cba208 --- /dev/null +++ b/docs/adding_features_to_qmk.md @@ -0,0 +1,7 @@ +If you have an idea for a custom feature or extra hardware connection, we'd love to accept it into QMK! These are generally done via [pull request](https://github.com/qmk/qmk_firmware/pulls) after forking, and here are some things to keep in mind when creating one: + +* **Disable 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, [open an issue](https://github.com/qmk/qmk_firmware/issues) for everyone to discuss 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** - submitting a markdown write-up of what your feature does with your PR may be needed, and it will allow a collaborator to easily copy it into the wiki for documentation (after proofing and editing). +* **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).
\ No newline at end of file diff --git a/docs/basic_how_keyboards_work.md b/docs/basic_how_keyboards_work.md new file mode 100644 index 0000000000..73c3f5c5fc --- /dev/null +++ b/docs/basic_how_keyboards_work.md @@ -0,0 +1,96 @@ +# How keys are registered, and interpreted by computers + +In this file, you can will learn the concepts of how keyboards work over USB, +and you'll be able to better understand what you can expect from changing your +firmware directly. + +## Schematic view + +Whenever you type on 1 particular key, here is the chain of actions taking +place: + +``` text ++------+ +-----+ +----------+ +----------+ +----+ +| User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS | ++------+ +-----+ +----------+ +----------+ |----+ +``` + +This scheme is a very simple view of what's going on, and more details follow +in the next sections. + +## 1. You Press a Key + +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. + +## 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 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 +USB for a given key. + +## 3. What the Operating System Does + +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 | +| ... | ... | +|---------+-----------| +``` + +## 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`. + +## 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**. + +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. + +## 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. + +Yet, it does come with multiple disadvantages: + + - Tied to a specific OS a a time (need recompilation when changing OS); + - Within a given OS, does not work in all software; + - Limited to a subset of Unicode on some systems. diff --git a/docs/becoming_a_qmk_collaborator.md b/docs/becoming_a_qmk_collaborator.md new file mode 100644 index 0000000000..1427675fdd --- /dev/null +++ b/docs/becoming_a_qmk_collaborator.md @@ -0,0 +1,7 @@ +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!
\ No newline at end of file diff --git a/docs/build_environment_setup.md b/docs/build_environment_setup.md new file mode 100644 index 0000000000..442038a58d --- /dev/null +++ b/docs/build_environment_setup.md @@ -0,0 +1,119 @@ +### 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`. +3. Install [DFU-Programmer](https://dfu-programmer.github.io/). + +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. + +Debian/Ubuntu example: + + sudo apt-get update + sudo apt-get install 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 + +### Docker + +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 +# defaults are ergodox/default + +docker run -e keymap=gwen -e subproject=ez -e keyboard=ergodox --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware + +# 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 +docker run -e keymap=default -e subproject=ez -e keyboard=ergobox --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware + +``` + +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. diff --git a/docs/build_guide.md b/docs/build_guide.md new file mode 100644 index 0000000000..8573b0fd15 --- /dev/null +++ b/docs/build_guide.md @@ -0,0 +1,103 @@ +# 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. + +Debian/Ubuntu example: + + sudo apt-get update + sudo apt-get install gcc-avr avr-libc dfu-programmer + +### 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. + +## 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` - bui |