converter/ibmpc_usb/README.md

   1 IBM PC Keyboard Converter
   2 =========================
   3 The converter translates IBM PC keyboard protocols to use classic keyboards with modern computer with USB ports.
   4 It supports both IBM XT and AT protocols, and all of scan code set 1, 2 and 3 with one firmware.
   5
   6 This is not finish project and still work in progress as of 2019-12-02. Test in the field and feedback from users are needed to improve
   7
   8 This project is intended to integrated existent TMK XT, PS/2 and Terminal converters.
   9
  10 - IBM XT converter: https://geekhack.org/index.php?topic=94649.0
  11 - PS/2 converter: https://geekhack.org/index.php?topic=14618.0
  12 - IBM Terminal converter: http://geekhack.org/index.php?topic=27272.0
  13
  14
  15
  16 Keyboard supported
  17 ------------------
  18 - PC XT keyboard of IBM 5150 5160
  19   - 83-key: 1501100 1501105
  20 - PC AT keyboard of IBM 5170
  21   - 84-key: 6450200 6450225
  22 - PC Terminal keyboard of IBM 5271(3270 PC)
  23   - 122-key: 6110344 6110345 1397000
  24   - 102-key: 1390680 1395764 1392595
  25 - PS/2 keyboards(AT+CodeSet2)
  26 - Clones of above models
  27
  28
  29
  30 Hardware
  31 --------
  32 Firmware supports ATMega32u4 and ATMega32u2 by default, Teensy2 or ProMicro can be used.
  33 Wire controller pins below to keyboard signals, besides VCC and GND. This is compatible for Soarer's converter.
  34
  35 - Data    PD0
  36 - Clock   PD1
  37 - Reset   PB6 or PB7 (For some of XT keyboards. Not needed for AT, PS/2 and Terminal)
  38
  39 Pull up resistors of 1-4.7K Ohm on both Data and Clock line are recommended, without them it won't work in some cases.
  40
  41 ### Reset
  42 Old Type-1 IBM XT keyboard and some of XT clones need this to reset its controller on startup. Many of IBM XT keyboards available are Type-2 and don't need the reset pin.
  43
  44 See this for Type-1 vs Type-2:
  45 https://vintagecomputer.ca/ibm-pc-model-f-keyboard-type-1-vs-type-2/
  46
  47 As for clones Zenith Z-150 XT and  Leading Edge DC-2014 are known to need this.
  48
  49 ### Connector pinouts
  50 #### XT
  51 - http://www.kbdbabel.org/conn/kbd_connector_ibmpc.png
  52 - https://allpinouts.org/pinouts/connectors/input_device/keyboard-xt-5-pin/
  53
  54 #### AT
  55 - http://www.kbdbabel.org/conn/kbd_connector_ps2.png
  56 - https://old.pinouts.ru/InputCables/KeyboardPC5_pinout.shtml
  57
  58 #### PS/2
  59 - https://pinouts.ru/InputCables/KeyboardPC6_pinout.shtml
  60
  61 #### Terminal
  62 - http://www.kbdbabel.org/conn/kbd_connector_ibmterm.png
  63 - http://www.kbdbabel.org/conn/kbd_connector_ibm3179_318x_319x.png
  64
  65
  66
  67 Source Code
  68 -----------
  69 https://github.com/tmk/tmk_keyboard/tree/master/converter/ibmpc_usb
  70
  71
  72
  73 Build Firmware
  74 --------------
  75
  76     $ cd converter/ibmpc_usb
  77     $ make clean
  78     $ make
  79
  80
  81
  82 Keyboard discrimination
  83 -----------------------
  84 This section explains how the converter determines proper protocol and scan code set for keyboard. The converter need to do that before starting to receive and translate scan codes from keyboard.
  85
  86 ### Keyboard ID
  87 After startup the converter sends 0xF2 command to get keyboard ID and sees how the keyboard responds to the command.
  88
  89 Response from keyboard:
  90
  91 - XT keyboard doesn't support any command and returns no response.
  92 - AT keyboard should respond with 0xFA to the command but returns no keyboard ID.
  93 - PS/2 keyboard should respond with 0xFA to the command, followd by keyboard ID, such as 0xAB86.
  94 - Terminal keyboard should respond with 0xFA to the command, followed by keyboard ID, such as 0xBFBF.
  95
  96 Now we can dscriminate the keyboard and determine suitable protocol and scan code set as described below.
  97
  98 ### Protocol
  99 - Signals from XT keyboard are recognized by XT protocol.
 100 - Signals from AT, PS/2 and Terminal keyboard are recognized by AT protocol.
 101
 102 ### Scan code Set
 103 - Scan codes from XT keyboard are handled as CodeSet1.
 104 - Scan codes from AT and PS/2 keyboard are handled as CodeSet2.
 105 - Scan codes from Terminal keyhboard are handled as CodeSet3.
 106
 107
 108
 109 Debug
 110 -----
 111 Use hid_listen to see debug outputs from the converter.
 112
 113 https://www.pjrc.com/teensy/hid_listen.html
 114
 115
 116
 117 Resources
 118 ---------
 119 IBM PC Keyboard Protocol Resources:
 120
 121 [a] [Microsoft USB HID to PS/2 Translation Table - Scan Code Set 1 and 2](
 122 http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/translate.pdf)
 123
 124 [b] [Microsoft Keyboard Scan Code Specification - Special rules of Scan Code Set 1 and 2](
 125 http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/scancode.doc)
 126
 127 [1] [PS/2 Reference Manuals - Collection of IBM Personal System/2 documents](
 128 http://www.mcamafia.de/pdf/pdfref.htm)
 129
 130 [2] [Keyboard and Auxiliary Device Controller - Signal Timing and Format](
 131 http://www.mcamafia.de/pdf/ibm_hitrc07.pdf)
 132
 133 [3] [Keyboards(101- and 102-key) - Keyboard Layout, Scan Code Set, POR, and Commands](
 134 http://www.mcamafia.de/pdf/ibm_hitrc11.pdf)
 135
 136 [4] [IBM PC XT Keyboard Protocol](
 137 https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-XT-Keyboard-Protocol)
 138
 139 [5] [IBM Keyboard Scan Code by John Elliott - 83-key, 84-key, 102-key and 122-key](
 140 https://www.seasip.info/VintagePC/index.html)
 141
 142 [6] [IBM 1391406 Keyboard - Scan Code Set 2 of 102-key PS/2 keyboard](
 143 https://www.seasip.info/VintagePC/ibm_1391406.html)
 144
 145 [7] [The IBM 6110344 Keyboard - Scan Code Set 3 of 122-key terminal keyboard](
 146 https://www.seasip.info/VintagePC/ibm_6110344.html)
 147
 148 [y] [TrackPoint Engineering Specifications for version 3E](
 149 https://web.archive.org/web/20100526161812/http://wwwcssrv.almaden.ibm.com/trackpoint/download.html)
 150
 151 [z] [Soarer's XT/AT/PS2/Terminal to USB converter](
 152 https://geekhack.org/index.php?topic=17458.0)
 153
 154
 155
 156 TODO
 157 ----
 158 ### Reset method for rescue
 159 For converter without accesible reset button when magickey combo doesn't work.
 160
 161 Check pin status at powerup:
 162
 163 - if Data and/or Clock are pull down to GND
 164
 165 ### Force protocol and scan code set
 166 Keyboard discrimination may fail and you have to configure them by hand.
 167
 168 ### Add AT90usb1286 support for Teensy2++