diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/BUILD_GUIDE.md | 4 | ||||
| -rwxr-xr-x | doc/CYGWIN_GUIDE.md | 2 | ||||
| -rw-r--r-- | doc/HAND_WIRE.md | 6 | ||||
| -rw-r--r-- | doc/PCB_GUIDE.md | 6 | ||||
| -rw-r--r-- | doc/TMK_README.md | 4 | ||||
| -rw-r--r-- | doc/VAGRANT_GUIDE.md | 7 | ||||
| -rw-r--r-- | doc/basic_how_keyboards_work.md | 96 | ||||
| -rw-r--r-- | doc/keycode.txt | 4 | ||||
| -rw-r--r-- | doc/keymap.md | 29 |
9 files changed, 142 insertions, 16 deletions
diff --git a/doc/BUILD_GUIDE.md b/doc/BUILD_GUIDE.md index 70a4e10fa5..1750191836 100644 --- a/doc/BUILD_GUIDE.md +++ b/doc/BUILD_GUIDE.md @@ -6,7 +6,7 @@ 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/jackhumbert/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer. +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". @@ -38,7 +38,7 @@ Debian/Ubuntu example: If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [VAGRANT_GUIDE file](VAGRANT_GUIDE.md). ## Verify Your Installation -1. If you haven't already, obtain this repository ([https://github.com/jackhumbert/qmk_firmware](https://github.com/jackhumbert/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. +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/doc/CYGWIN_GUIDE.md b/doc/CYGWIN_GUIDE.md index 05e7a55f76..05d71961a4 100755 --- a/doc/CYGWIN_GUIDE.md +++ b/doc/CYGWIN_GUIDE.md @@ -234,7 +234,7 @@ If you did everything else right. This part should be a snap! Grab the latest so ###Build Planck and Load the Firmware ``` $ cd ~/src -$ git clone https://github.com/jackhumbert/qmk_firmware.git +$ git clone https://github.com/qmk/qmk_firmware.git $ cd qmk_firmware/keyboards/planck $ make ``` diff --git a/doc/HAND_WIRE.md b/doc/HAND_WIRE.md index 18cb7011ff..17ef3116f9 100644 --- a/doc/HAND_WIRE.md +++ b/doc/HAND_WIRE.md @@ -183,7 +183,7 @@ As you move along, be sure that the Teensy is staying in place - recutting and s From here, you should have a working keyboard with the correct firmware. Before we attach the Teensy permanently to the keyboard, let's quickly get some firmware loaded onto the Teensy so we can test each keyswitch. -To start out, download [the firmware](https://github.com/jackhumbert/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/). +To start out, download [the firmware](https://github.com/qmk/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/). The first thing we're going to do is create a new project using the script in the root directory of the firmware. In your terminal, run this command with `<project_name>` replaced by the name of your project - it'll need to be different from any other project in the `keyboards/` folder: @@ -276,7 +276,7 @@ This can be accomplished by using the following `keymaps` definition: ), }; -Note that the layout of the keycodes is similar to the physical layout of our keyboard - this make it much easier to see what's going on. A lot of the keycodes should be fairly obvious, but for a full list of them, check out [tmk_code/doc/keycode.txt](https://github.com/jackhumbert/qmk_firmware/blob/master/tmk_core/doc/keycode.txt) - there are also a lot of aliases to condense your keymap file. +Note that the layout of the keycodes is similar to the physical layout of our keyboard - this make it much easier to see what's going on. A lot of the keycodes should be fairly obvious, but for a full list of them, check out [tmk_code/doc/keycode.txt](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/doc/keycode.txt) - there are also a lot of aliases to condense your keymap file. It's also important to use the `KEYMAP` function we defined earlier - this is what allows the firmware to associate our intended readable keymap with the actual wiring. @@ -306,7 +306,7 @@ If you've done all of these things, keep in mind that sometimes you might have h Now that you have a working board, it's time to get things in their permanent positions. I've often used liberal amounts of hot glue to secure and insulate things, so if that's your style, start spreading that stuff like butter. Otherwise, double-sided tape is always an elegant solution, and electrical tape is a distant second. Due to the nature of these builds, a lot of this part is up to you and how you planned (or didn't plan) things out. -There are a lot of possibilities inside the firmware - check out the [readme](https://github.com/jackhumbert/qmk_firmware/blob/master/readme.md) for a full feature list, and dive into the different project (Planck, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb) +There are a lot of possibilities inside the firmware - check out the [readme](https://github.com/qmk/qmk_firmware/blob/master/readme.md) for a full feature list, and dive into the different project (Planck, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb) ## Trouble-shooting compiling diff --git a/doc/PCB_GUIDE.md b/doc/PCB_GUIDE.md index 3fad41dfb4..16de711142 100644 --- a/doc/PCB_GUIDE.md +++ b/doc/PCB_GUIDE.md @@ -5,7 +5,7 @@ ### 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/jackhumbert/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer. +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! @@ -32,7 +32,7 @@ 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/jackhumbert/qmk_firmware +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. @@ -80,7 +80,7 @@ when trying to 'make dfu' on Windows you need to copy the dfu-programmer.exe to ### Keymap -Unlike the other keymaps, prefixing the keycodes with `KC_` is required. A full list of the keycodes is available [here](https://github.com/jackhumbert/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/jackhumbert/qmk_firmware/blob/master/quantum/keymap_common.h). +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: diff --git a/doc/TMK_README.md b/doc/TMK_README.md index 6164dacd3c..e3438eda2b 100644 --- a/doc/TMK_README.md +++ b/doc/TMK_README.md @@ -34,7 +34,7 @@ You can find some keyboard specific projects under `converter` and `keyboard` di * [atomic](keyboards/atomic/) - [Atomic] Ortholinear 60% keyboard ### Ergodox EZ -* [ergodox_ez](keyboards/ergodox_ez) - [Ergodox_EZ] Assembled split keyboard +* [ergodox_ez](keyboards/ergodox/ez) - [Ergodox_EZ] Assembled split keyboard ## Other projects @@ -113,7 +113,7 @@ Third party libraries like LUFA, PJRC and V-USB have their own license respectiv Build Firmware and Program Controller ------------------------------------- -See [doc/build.md](tmk_core/doc/build.md), or the readme in the particular keyboards/* folder. +See [build environment setup](/readme.md#build-environment-setup), or the readme in the particular keyboards/* folder. diff --git a/doc/VAGRANT_GUIDE.md b/doc/VAGRANT_GUIDE.md index 62044b7f72..439e78da7d 100644 --- a/doc/VAGRANT_GUIDE.md +++ b/doc/VAGRANT_GUIDE.md @@ -6,7 +6,8 @@ This project includes a Vagrantfile that will allow you to build a new firmware 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. +*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. @@ -20,7 +21,7 @@ See [/doc/keymap.md](/doc/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_ez/readme.md) gives a great example. +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. -
\ No newline at end of file + diff --git a/doc/basic_how_keyboards_work.md b/doc/basic_how_keyboards_work.md new file mode 100644 index 0000000000..73c3f5c5fc --- /dev/null +++ b/doc/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/doc/keycode.txt b/doc/keycode.txt index c1134f9bf2..687406fdab 100644 --- a/doc/keycode.txt +++ b/doc/keycode.txt @@ -2,7 +2,7 @@ Keycode Symbol Table ==================== Keycodes are defined in `common/keycode.h`. Range of 00-A4 and E0-E7 are identical with HID Usage: -<http://www.usb.org/developers/devclass_docs/Hut1_11.pdf> +<http://www.usb.org/developers/hidpage/Hut1_12v2.pdf> Virtual keycodes are defined out of above range to support special actions. @@ -84,7 +84,7 @@ KC_PAUSE KC_PAUS 48 Keyboard Pause1 KC_INSERT KC_INS 49 Keyboard Insert1 KC_HOME 4A Keyboard Home1 KC_PGUP 4B Keyboard PageUp1 -KC_DELETE KC_DELETE 4C Keyboard Delete Forward +KC_DELETE KC_DEL 4C Keyboard Delete Forward KC_END 4D Keyboard End1 KC_PGDOWN KC_PGDN 4E Keyboard PageDown1 KC_RIGHT KC_RGHT 4F Keyboard RightArrow1 diff --git a/doc/keymap.md b/doc/keymap.md index d1985e567c..6f2a663fc8 100644 --- a/doc/keymap.md +++ b/doc/keymap.md @@ -455,6 +455,35 @@ Turn the backlight on and off without changing level. +### 2.6 Swap-Hands Action +The swap-hands action allows support for one-handed keyboards without requiring a separate layer. Set `ONEHAND_ENABLE` in the Makefile and define a `hand_swap_config` entry in your keymap. Now whenever the `ACTION_SWAP_HANDS` command key is pressed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd` + +### 2.6.1 Configuration +The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck: + +``` +const keypos_t hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = { + {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}}, + {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}}, + {{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}}, + {{11, 3}, {10, 3}, {9, 3}, {8, 3}, {7, 3}, {6, 3}, {5, 3}, {4, 3}, {3, 3}, {2, 3}, {1, 3}, {0, 3}}, +}; +``` + +Note that the array indices are reversed same as the matrix and the values are of type `keypos_t` which is `{col, row}` and all values are zero-based. In the example above, `hand_swap_config[2][4]` (third row, fifth column) would return {7, 2} (third row, eighth column). + +### 2.6.2 Advanced Swap Commands +- **`ACTION_SWAP_HANDS()`** Swaps hands when pressed, returns to normal when released (momentary). +- **`ACTION_SWAP_HANDS_TOGGLE()`** Toggles swap on and off with every keypress. +- **`ACTION_SWAP_HANDS_TAP_TOGGLE()`** Toggles with a tap; momentary when held. +- **`ACTION_SWAP_HANDS_TAP_KEY(key)`** Sends `key` with a tap; momentary swap when held. +- **`ACTION_SWAP_HANDS_ON_OFF()`** Alias for `ACTION_SWAP_HANDS()` +- **`ACTION_SWAP_HANDS_OFF_ON()`** Momentarily turns off swap. +- **`ACTION_SWAP_HANDS_ON()`** Turns on swapping and leaves it on. +- **`ACTION_SWAP_HANDS_OFF()`** Turn off swapping and leaves it off. Good for returning to a known state. + + + ## 3. Layer switching Example There are some ways to switch layer with 'Layer' actions. |