diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/TMK_README.md | 4 | ||||
| -rw-r--r-- | doc/VAGRANT_GUIDE.md | 4 | ||||
| -rw-r--r-- | doc/basic_how_keyboards_work.md | 96 | ||||
| -rw-r--r-- | doc/keycode.txt | 6 |
4 files changed, 103 insertions, 7 deletions
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..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 + 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 44d7e27cd6..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: -<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. @@ -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 + |