From df25033fc6d97b0e29c8a7030196b97a8663d498 Mon Sep 17 00:00:00 2001 From: Pavlos Vinieratos Date: Mon, 4 Jul 2016 17:55:32 +0200 Subject: fix typos --- doc/keycode.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/keycode.txt b/doc/keycode.txt index 44d7e27cd6..c1134f9bf2 100644 --- a/doc/keycode.txt +++ b/doc/keycode.txt @@ -62,7 +62,7 @@ KC_NONUS_HASH KC_NUHS 32 Keyboard Non-US # and ~ KC_SCOLON KC_SCLN 33 Keyboard ; and : KC_QUOTE KC_QUOT 34 Keyboard ‘ and “ KC_GRAVE KC_GRV 35 Keyboard Grave Accent and Tilde -KC_COMMA KC_COMM 36 Keyboard, and < +KC_COMMA KC_COMM 36 Keyboard , and < KC_DOT 37 Keyboard . and > KC_SLASH KC_SLSH 38 Keyboard / and ? KC_CAPSLOCK KC_CAPS 39 Keyboard Caps Lock @@ -92,7 +92,7 @@ KC_LEFT 50 Keyboard LeftArrow1 KC_DOWN 51 Keyboard DownArrow1 KC_UP 52 Keyboard UpArrow1 KC_NUMLOCK KC_NLCK 53 Keypad Num Lock and Clear11 -KC_KP_SLASH KC_PSLS 54 Keypad /1 +KC_KP_SLASH KC_PSLS 54 Keypad / KC_KP_ASTERISK KC_PAST 55 Keypad * KC_KP_MINUS KC_PMNS 56 Keypad - KC_KP_PLUS KC_PPLS 57 Keypad + -- cgit v1.2.3 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 6164dacd3c..f3d96717a8 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 62044b7f72..c9958e16b5 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 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 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. -- cgit v1.2.3 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 f3d96717a8..0c75a0e279 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 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 0c75a0e279..e3438eda2b 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 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 c1134f9bf2..5a42c50bfb 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