From 8a9bf1f1653a5029ffd8f1e1171cd0b16bc2bc71 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 30 Jul 2016 08:37:30 +0200 Subject: Update some obsolete references Some links were still pointing to `/keyboards/ergodox_ez`, while the directory is `/keyboards/erdogox` now. Not all references have been updated, and some of the text here and there may need updating to mention the ErgoDox Infinity too, but that's out of the scope for this quick fix. Signed-off-by: Gergely Nagy --- doc/TMK_README.md | 2 +- doc/VAGRANT_GUIDE.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/TMK_README.md b/doc/TMK_README.md index 6164dacd3..f3d96717a 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 diff --git a/doc/VAGRANT_GUIDE.md b/doc/VAGRANT_GUIDE.md index 62044b7f7..c9958e16b 100644 --- a/doc/VAGRANT_GUIDE.md +++ b/doc/VAGRANT_GUIDE.md @@ -20,7 +20,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 + -- cgit v1.2.3-24-g4f1b From d9bef1658e062d76f87a752daa30047d865dca0f Mon Sep 17 00:00:00 2001 From: Jiehong Ma Date: Sun, 31 Jul 2016 16:49:31 +0200 Subject: feature: add basic doc about how a keyboard works on USB This comes from the discussion on #520 --- doc/basic_how_keyboards_work.md | 96 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 doc/basic_how_keyboards_work.md (limited to 'doc') diff --git a/doc/basic_how_keyboards_work.md b/doc/basic_how_keyboards_work.md new file mode 100644 index 000000000..73c3f5c5f --- /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. -- cgit v1.2.3-24-g4f1b From f41c2e6863f2ebf55311051cdead743683846a49 Mon Sep 17 00:00:00 2001 From: Felix Uhl Date: Mon, 8 Aug 2016 17:53:08 +0200 Subject: Update TMK_README.md updated link to non-existent build.md file --- doc/TMK_README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/TMK_README.md b/doc/TMK_README.md index f3d96717a..0c75a0e27 100644 --- a/doc/TMK_README.md +++ b/doc/TMK_README.md @@ -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 [doc/BUILD_GUIDE.md](tmk_core/doc/BUILD_GUIDE.md), or the readme in the particular keyboards/* folder. -- cgit v1.2.3-24-g4f1b From 6975135f545d08955ed26ef046a0333e291af716 Mon Sep 17 00:00:00 2001 From: Felix Uhl Date: Wed, 10 Aug 2016 11:40:51 +0200 Subject: updated reference Build setup links to main readme now. --- doc/TMK_README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/TMK_README.md b/doc/TMK_README.md index 0c75a0e27..e3438eda2 100644 --- a/doc/TMK_README.md +++ b/doc/TMK_README.md @@ -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_GUIDE.md](tmk_core/doc/BUILD_GUIDE.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. -- cgit v1.2.3-24-g4f1b From a41a53baadf14b50d63fc9424aca67e7bde193f3 Mon Sep 17 00:00:00 2001 From: Felix Uhl Date: Thu, 11 Aug 2016 09:13:38 +0200 Subject: Fix dead link in keycode.txt The link to the HID Usage tables was outdated and dead, so I replaced it. --- doc/keycode.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/keycode.txt b/doc/keycode.txt index c1134f9bf..5a42c50bf 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: - + Virtual keycodes are defined out of above range to support special actions. -- cgit v1.2.3-24-g4f1b From dd378601608849679ead6e2cccb74f7f29c131dc Mon Sep 17 00:00:00 2001 From: Joe Wasson Date: Wed, 27 Jul 2016 08:43:02 -0700 Subject: Add one-hand support. This adds an action, `ACTION_SWAP_HANDS`, that swaps the the keys on the keyboard across a keymap-defined hemisphere in order to support one-hand typing without requiring a separate one-handed layer. See updated `doc/keymap.md` for more information. --- doc/keymap.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'doc') diff --git a/doc/keymap.md b/doc/keymap.md index d1985e567..1285ad6cd 100644 --- a/doc/keymap.md +++ b/doc/keymap.md @@ -455,6 +455,24 @@ 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 is executed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd` + +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). + + + ## 3. Layer switching Example There are some ways to switch layer with 'Layer' actions. -- cgit v1.2.3-24-g4f1b From 8090f6b499fd87ddeb7a191f7bc3dace9d03be23 Mon Sep 17 00:00:00 2001 From: Joe Wasson Date: Thu, 28 Jul 2016 01:24:06 -0700 Subject: Improve one-hand support by adding more actions and tap keys. --- doc/keymap.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/keymap.md b/doc/keymap.md index 1285ad6cd..6f2a663fc 100644 --- a/doc/keymap.md +++ b/doc/keymap.md @@ -456,8 +456,9 @@ 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 is executed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd` +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: ``` @@ -471,6 +472,16 @@ const keypos_t hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = { 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 -- cgit v1.2.3-24-g4f1b From bbf06d516a2946816e2ad53798dac7ee901ad25b Mon Sep 17 00:00:00 2001 From: IBNobody Date: Thu, 15 Sep 2016 21:44:03 -0500 Subject: Added notes on vagrant file fixes, UPRINT --- doc/VAGRANT_GUIDE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/VAGRANT_GUIDE.md b/doc/VAGRANT_GUIDE.md index c9958e16b..439e78da7 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. -- cgit v1.2.3-24-g4f1b From 64218f0f7018cf0ebedb14197b07d05904b5bc09 Mon Sep 17 00:00:00 2001 From: Noah Andrews Date: Tue, 8 Nov 2016 22:05:24 -0500 Subject: Add proper shortcode for KC_DELETE to keycode.txt --- doc/keycode.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/keycode.txt b/doc/keycode.txt index 5a42c50bf..687406fda 100644 --- a/doc/keycode.txt +++ b/doc/keycode.txt @@ -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 -- cgit v1.2.3-24-g4f1b