max/tmk_keyboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

ibmpc_usb: Update README

Browse source
This commit is contained in:
tmk 2021-07-07 21:44:27 +09:00
parent e2c58b5044
commit 8391b2c018
1 changed files with 106 additions and 134 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

240
converter/ibmpc_usb/README.md
View file

@ -1,22 +1,23 @@
IBM PC Keyboard Converter IBM PC Keyboard Converter
========================= =========================
The converter translates IBM PC keyboard protocols to use classic keyboards with modern computer with USB ports. The converter translates IBM PC keyboard protocols into USB HID to use classic keyboards on modern computer with USB ports.
It supports both IBM XT and AT protocols, and all of scan code set 1, 2 and 3 with one firmware. This can supports IBM XT and AT protocols and recognize scan code set 1, 2 and 3 with just one firmware.
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.
You can discuss about this project here.
https://geekhack.org/index.php?topic=103648.0
This project is intended to integrated existent TMK XT, PS/2 and Terminal converters. This project is intended to integrated existent TMK XT, PS/2 and Terminal keyboard converters.
- IBM XT converter: https://geekhack.org/index.php?topic=94649.0 - IBM XT converter: https://geekhack.org/index.php?topic=94649.0
- PS/2 converter: https://geekhack.org/index.php?topic=14618.0 - PS/2 converter: https://geekhack.org/index.php?topic=14618.0
- IBM Terminal converter: http://geekhack.org/index.php?topic=27272.0 - IBM Terminal converter: http://geekhack.org/index.php?topic=27272.0
Test in the field and feedback from users are needed to improve firmware code.
Discuss in this thread or on github. https://geekhack.org/index.php?topic=103648.0
You can buy prebuilt TMK converter to support this project here. https://geekhack.org/index.php?topic=72052.0
Keyboard supported Keyboard supported
------------------ ------------------
@ -27,87 +28,46 @@ Keyboard supported
- PC Terminal keyboard of IBM 5271(3270 PC) - PC Terminal keyboard of IBM 5271(3270 PC)
- 122-key: 6110344 6110345 1397000 - 122-key: 6110344 6110345 1397000
- 102-key: 1390680 1395764 1392595 - 102-key: 1390680 1395764 1392595
- PS/2 keyboards(AT+CodeSet2) - IBM 5576-001
- Clones of above models - PS/2 keyboards
- Other IBM PC compatible keyboards
Optionally PS/2 mouses can be supported.
- PS/2 mouse
- Default
- Microsoft IntelliMouse
- Microsoft ExplorerMouse
- Logitech PS/2++
Hardware Firmware
-------- --------
Firmware supports ATMega32u4 and ATMega32u2 by default, Teensy2 or ProMicro can be used. ### Build Firmware
Wire controller pins below to keyboard signals, besides VCC and GND. This is compatible for Soarer's converter.
- Data PD0
- Clock PD1
- Reset PB6 or PB7 (For some of XT keyboards. Not needed for AT, PS/2 and Terminal)
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.
### Reset
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.
See this for Type-1 vs Type-2:
https://vintagecomputer.ca/ibm-pc-model-f-keyboard-type-1-vs-type-2/
As for clones Zenith Z-150 XT and Leading Edge DC-2014 are known to need this.
### Connector pinouts
#### XT
- http://www.kbdbabel.org/conn/kbd_connector_ibmpc.png
- https://allpinouts.org/pinouts/connectors/input_device/keyboard-xt-5-pin/
#### AT
- http://www.kbdbabel.org/conn/kbd_connector_ps2.png
- https://old.pinouts.ru/InputCables/KeyboardPC5_pinout.shtml
#### PS/2
- https://pinouts.ru/InputCables/KeyboardPC6_pinout.shtml
#### Terminal
- http://www.kbdbabel.org/conn/kbd_connector_ibmterm.png
- http://www.kbdbabel.org/conn/kbd_connector_ibm3179_318x_319x.png
Source Code
-----------
https://github.com/tmk/tmk_keyboard/tree/master/converter/ibmpc_usb
Build Firmware
--------------
$ cd converter/ibmpc_usb $ cd converter/ibmpc_usb
$ make clean $ make -f Makefile.<variant> clean
$ make $ make -f Makefile.<variant>
### Build Options
In Makefiile:
# IBMPC Options
IBMPC_SECONDARY ?= no
IBMPC_MOUSE_ENABLE ?= no
These options bloat firmware size and you may need to disable other options.
- `IBMPC_SECONDARY` - enables secondary interface for converter with PS/2 Mini-DIN-6 connector
- `IBMPC_MOUSE_ENABLE` - enables PS/2 mouse support
Keyboard discrimination ### Keymap Editor
----------------------- You can edit keymap on web browser and download prebuilt firmware here.
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.
### Keyboard ID http://www.tmk-kbd.com/tmk_keyboard/editor/#ibmpc_usb
After startup the converter sends 0xF2 command to get keyboard ID and sees how the keyboard responds to the command.
Response from keyboard:
- XT keyboard doesn't support any command and returns no response.
- AT keyboard should respond with 0xFA to the command but returns no keyboard ID.
- PS/2 keyboard should respond with 0xFA to the command, followd by keyboard ID, such as 0xAB86.
- Terminal keyboard should respond with 0xFA to the command, followed by keyboard ID, such as 0xBFBF.
Now we can dscriminate the keyboard and determine suitable protocol and scan code set as described below.
### Protocol
- Signals from XT keyboard are recognized by XT protocol.
- Signals from AT, PS/2 and Terminal keyboard are recognized by AT protocol.
### Scan code Set
- Scan codes from XT keyboard are handled as CodeSet1.
- Scan codes from AT and PS/2 keyboard are handled as CodeSet2.
- Scan codes from Terminal keyhboard are handled as CodeSet3.
@ -115,62 +75,74 @@ Debug
----- -----
Use hid_listen to see debug outputs from the converter. Use hid_listen to see debug outputs from the converter.
https://www.pjrc.com/teensy/hid_listen.html https://github.com/tmk/tmk_keyboard/wiki#debug
Converter Hardware
------------------
This firmware supports ATMega32u4, ATMega32u2 and AT90USB1286 by default, Teensy2/2++ or ProMicro can be used.
Wire microcontroller pins below to keyboard signals, besides VCC and GND. This pin configuration is compatible for Soarer's converter.
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.
- Data PD0
- Clock PD1
- Reset PB6 or PB7 (For some of XT keyboards. Not needed for AT, PS/2 and Terminal)
For optional secondary interface use these pins.
- Data PD2
- Clock PD3
### Reset
Old Type-1 IBM XT keyboard and some of XT clones need Reset pin to starup its controller.
Connect Reset pin to pin3 of DIN-5(180-degree) connector. This should not harm keyboards which don't require reset,
it is safe and recommended to have Reset pin on AT/XT converter.
Zenith Z-150 XT and Leading Edge DC-2014 are also known to need this.
See this for IBM XT Type-1 vs Type-2: https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-XT-Keyboard-Protocol#type-1-vs-type-2
### Connector pinouts
- DIN: https://en.wikipedia.org/wiki/DIN_connector#Circular_connectors
- Mini-DIN: https://en.wikipedia.org/wiki/Mini-DIN_connector
#### XT - DIN-5(180-degree)
- http://www.kbdbabel.org/conn/kbd_connector_ibmpc.png
- https://allpinouts.org/pinouts/connectors/input_device/keyboard-xt-5-pin/
#### AT - DIN-5(180-degree)
- http://www.kbdbabel.org/conn/kbd_connector_ps2.png
- https://old.pinouts.ru/InputCables/KeyboardPC5_pinout.shtml
#### Terminal - DIN-5(240-degree) or DIN-6
- http://www.kbdbabel.org/conn/kbd_connector_ibmterm.png
- http://www.kbdbabel.org/conn/kbd_connector_ibm3179_318x_319x.png
#### PS/2 - Mini-DIN-6
- https://pinouts.ru/InputCables/KeyboardPC6_pinout.shtml
For secondary interface use pin2 and pin6 for data and clock respectively.
You can use PS/2 Y-splitter cable to access secondary interface.
Scan Code Mapping
-----------------
This is how the converter map keyboard scan code to USB key.
https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-Keyboard-Converter#default-mapping
Resources Resources
--------- ---------
IBM PC Keyboard Protocol Resources: - Source Code: https://github.com/tmk/tmk_keyboard/tree/master/converter/ibmpc_usb
- Discussion: https://geekhack.org/index.php?topic=103648.0
[a] [Microsoft USB HID to PS/2 Translation Table - Scan Code Set 1 and 2]( - Conveter impl: https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-Keyboard-Converter
http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/translate.pdf) - XT Protocol: https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-XT-Keyboard-Protocol
- AT Protocol: https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-AT-Keyboard-Protocol
[b] [Microsoft Keyboard Scan Code Specification - Special rules of Scan Code Set 1 and 2]( - Scan Code: https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-AT-Keyboard-Protocol#scan-codes
http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/scancode.doc) - PS/2 Mouse: https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-Mouse
[1] [PS/2 Reference Manuals - Collection of IBM Personal System/2 documents](
http://www.mcamafia.de/pdf/pdfref.htm)
[2] [Keyboard and Auxiliary Device Controller - Signal Timing and Format](
http://www.mcamafia.de/pdf/ibm_hitrc07.pdf)
[3] [Keyboards(101- and 102-key) - Keyboard Layout, Scan Code Set, POR, and Commands](
http://www.mcamafia.de/pdf/ibm_hitrc11.pdf)
[4] [IBM PC XT Keyboard Protocol](
https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-XT-Keyboard-Protocol)
[5] [IBM Keyboard Scan Code by John Elliott - 83-key, 84-key, 102-key and 122-key](
https://www.seasip.info/VintagePC/index.html)
[6] [IBM 1391406 Keyboard - Scan Code Set 2 of 102-key PS/2 keyboard](
https://www.seasip.info/VintagePC/ibm_1391406.html)
[7] [The IBM 6110344 Keyboard - Scan Code Set 3 of 122-key terminal keyboard](
https://www.seasip.info/VintagePC/ibm_6110344.html)
[8] [IBM PC AT Technical Reference 1986](
(http://bitsavers.org/pdf/ibm/pc/at/6183355_PC_AT_Technical_Reference_Mar86.pdf)
[y] [TrackPoint Engineering Specifications for version 3E](
https://web.archive.org/web/20100526161812/http://wwwcssrv.almaden.ibm.com/trackpoint/download.html)
[z] [Soarer's XT/AT/PS2/Terminal to USB converter](
https://geekhack.org/index.php?topic=17458.0)
TODO
----
### Reset method for rescue
For converter without accesible reset button when magickey combo doesn't work.
Check pin status at powerup:
- if Data and/or Clock are pull down to GND
### Force protocol and scan code set
Keyboard discrimination may fail and you have to configure them by hand.
### Add AT90usb1286 support for Teensy2++