doc/basic_how_keyboards_work.md

   1 # How keys are registered, and interpreted by computers
   2
   3 In this file, you can will learn the concepts of how keyboards work over USB,
   4 and you'll be able to better understand what you can expect from changing your
   5 firmware directly.
   6
   7 ## Schematic view
   8
   9 Whenever you type on 1 particular key, here is the chain of actions taking
  10 place:
  11
  12 ``` text
  13 +------+         +-----+       +----------+      +----------+     +----+
  14 | User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS |
  15 +------+         +-----+       +----------+      +----------+     |----+
  16 ```
  17
  18 This scheme is a very simple view of what's going on, and more details follow
  19 in the next sections.
  20
  21 ## 1. You Press a Key
  22
  23 Whenever you press a key, the firmware of your keyboard can register this event.
  24 It can register when the key is pressed, held and released.
  25
  26 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).
  27 This speed often is limited by the mechanical key response time, the protocol
  28 to transfer those key presses (here USB HID), and by the software it is used in.
  29
  30 ## 2. What the Firmware Sends
  31
  32 The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf)
  33 tells what a keyboard can actually send through USB to have a chance to be
  34 properly recognised. This includes a pre-defined list of keycodes which are
  35 simple numbers from `0x00` to `0xE7`. The firmware assigns a keycode to each
  36 key of the keyboard.
  37
  38 The firmware does not send actually letters or characters, but only keycodes.
  39 Thus, by modifying the firmware, you only can modify what keycode is sent over
  40 USB for a given key.
  41
  42 ## 3. What the Operating System Does
  43
  44 Once the keycode reaches the operating system, a piece of software has to have
  45 it match an actual character thanks to a keyboard layout. For example, if your
  46 layout is set to QWERTY, a sample of the matching table is as follow:
  47
  48 ``` text
  49 | keycode | character |
  50 |---------+-----------|
  51 |    0x04 | a/A       |
  52 |    0x05 | b/B       |
  53 |    0x06 | c/C       |
  54 |     ... | ...       |
  55 |    0x1C | y/Y       |
  56 |    0x1D | z/Z       |
  57 |     ... | ...       |
  58 |---------+-----------|
  59 ```
  60
  61 ## Back to the firmware
  62
  63 As the layout is generally fixed (unless you create your own), the firmware can
  64 actually call a keycode by its layout name directly to ease things for you.
  65
  66 This is exactly what is done here with `KC_A` actually representing `0x04` in
  67 QWERTY. The full list can be found in `keycode.txt`.
  68
  69 ## List of Characters You Can Send
  70
  71 Putting aside shortcuts, having a limited set of keycodes mapped to a limited
  72 layout means that **the list of characters you can assign to a given key only
  73 is the ones present in the layout**.
  74
  75 For example, this means that if you have a QWERTY US layout, and you want to
  76 assign 1 key to produce `€` (euro currency symbol), you are unable to do so,
  77 because the QWERTY US layout does not have such mapping. You could fix that by
  78 using a QWERTY UK layout, or a QWERTY US International.
  79
  80 You may wonder why a keyboard layout containing all of Unicode is not devised
  81 then? The limited number of keycode available through USB simply disallow such
  82 a thing.
  83
  84 ## How to (Maybe) Enter Unicode Characters
  85
  86 You can have the firmware send *sequences of keys* to use the [software Unicode
  87 Input
  88 Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of
  89 the target operating system, thus effectively entering characters independently
  90 of the layout defined in the OS.
  91
  92 Yet, it does come with multiple disadvantages:
  93
  94  - Tied to a specific OS a a time (need recompilation when changing OS);
  95  - Within a given OS, does not work in all software;
  96  - Limited to a subset of Unicode on some systems.