diff options
Diffstat (limited to 'docs')
73 files changed, 2836 insertions, 4956 deletions
diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..515ddb7783 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,25 @@ +# Quantum Mechanical Keyboard Firmware + +## What is QMK Firmware? {#what-is-qmk-firmware} + +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](getting_started_build_tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation: + + make planck-rev4-default + +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.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md). diff --git a/docs/_summary.md b/docs/_summary.md index c5e29cb520..e32548f5b1 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -1,32 +1,67 @@ +* [Getting started](README.md) + * [QMK Introduction](getting_started_introduction.md) + * [Install Build Tools](getting_started_build_tools.md) + * Alternative: [Vagrant Guide](getting_started_vagrant_guide.md) + * [Build/Compile instructions](getting_started_make_guide.md) + * [How to Use Github](getting_started_github.md) -### Getting started -* [Introduction](home.md) -* [QMK Overview](qmk_overview.md) -* [Build Environment Setup](build_environment_setup.md) -* [Make instructions](make_instructions.md) +* [FAQ](faq.md) + * [General FAQ](faq_general.md) + * [Build/Compile QMK](faq_build.md) + * [Debugging/Troubleshooting QMK](faq_debug.md) + * [Keymap](faq_keymap.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 -* [Adding a keyboard to QMK](adding_a_keyboard_to_qmk.md) -* [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md) -* [Modding your keyboard](modding_your_keyboard.md) -* [Adding features to QMK](adding_features_to_qmk.md) -* [ISP flashing guide](isp_flashing_guide.md) - -### Other topics -* [General FAQ](faq.md) -* [Differences from TMK](differences_from_tmk.md) -* [Using Eclipse with QMK](eclipse.md) +* [Features](features.md) + * [Common Shortcuts](feature_common_shortcuts.md) + * [Backlight](feature_backlight.md) + * [Bootmagic](feature_bootmagic.md) + * [Dynamic Macros](dynamic_macros.md) + * [Key Lock](key_lock.md) + * [Leader Key](feature_leader_key.md) + * [Macros](macros.md) + * [Mouse keys](mouse_keys.md) + * [PS2 Mouse](feature_ps2_mouse.md) + * [Space Cadet](space_cadet_shift.md) + * [Tap Dance](tap_dance.md) + * [Audio](feature_audio.md) + * [Thermal Printer](feature_thermal_printer.md) + * [Stenography](stenography.md) + * [Unicode](unicode.md) + +* Reference + * [Glossary](glossary.md) + * [Keymap overview](keymap.md) + * [Keycodes](keycodes.md) + * [Basic](keycodes_basic.md) + * [Quantum](quantum_keycodes.md) + * [Backlight](feature_backlight.md#backlight-keycodes) + * [Bluetooth](feature_bluetooth.md#bluetooth-keycodes) + * [Bootmagic](feature_bootmagic.md#bootmagic-keycodes) + * [Layer Switching](feature_common_shortcuts.md#switching-and-toggling-layers) + * [Mod+Key](feature_common_shortcuts.md#modifier-keys) + * [Mod Tap](feature_common_shortcuts.md#mod-tap) + * [One Shot Keys](feature_common_shortcuts.md#one-shot-keys) + * [Shifted Keys](feature_common_shortcuts.md#shifted-keycodes) + * [Stenography](stenography.md#keycode-reference) + * [RGB Light](feature_rgblight.md#rgblight-keycodes) + * [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes) + * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) + * [The `config.h` File](config_options.md) + * [Customizing Functionality](custom_quantum_functions.md) + * [Documentation Best Practices](documentation_best_practices.md) + * [Unit Testing](unit_testing.md) + +* For Makers and Modders + * [Adding a keyboard to QMK](adding_a_keyboard_to_qmk.md) + * [Adding features to QMK](adding_features_to_qmk.md) + * [Hand Wiring Guide](hand_wiring.md) + * [ISP flashing guide](isp_flashing_guide.md) + * [Modding your keyboard](modding_your_keyboard.md) + * [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md) + +* For a Deeper Understanding + * [How Keyboards Work](how_keyboards_work.md) + * [Understanding QMK](understanding_qmk.md) + +* Other Topics + * [Using Eclipse with QMK](eclipse.md) diff --git a/docs/adding_features_to_qmk.md b/docs/adding_features_to_qmk.md index f6f7cba208..e031ddbb7b 100644 --- a/docs/adding_features_to_qmk.md +++ b/docs/adding_features_to_qmk.md @@ -1,7 +1,16 @@ -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: +# How To Add Features To QMK -* **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! +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** - 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 +* **Consider subprojects and different chip-bases** - there are several keyboards that have subprojects that allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled on platforms it doesn't work on. +* **Explain your feature** - Document it in `docs/`, either as a new file or as part of an existing file. If you don't document it other people won't be able to benefit from your hard work. +* **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), we'd love to talk about how QMK can be improved. diff --git a/docs/build_guide.md b/docs/build_guide.md deleted file mode 100644 index 8573b0fd15..0000000000 --- a/docs/build_guide.md +++ /dev/null @@ -1,103 +0,0 @@ -# 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` - 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: - -* root (`/`) -* keyboard (`/keyboards/<keyboard>/`) -* keymap (`/keyboards/<keyboard>/keymaps/<keymap>/`) - -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 `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](/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 -``` - -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. diff --git a/docs/build_old.md b/docs/build_old.md deleted file mode 100644 index 9ae3a64ae4..0000000000 --- a/docs/build_old.md +++ /dev/null @@ -1,187 +0,0 @@ -Build Firmware and Program Controller -===================================== - -## This guide may be out-dated - use [build_guide.md](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: |