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