[REQUEST FOR TEST] TMK IBM PC Keyboard Converter

[hasu]

IBM PC Keyboard Converter

The converter translates IBM PC keyboard protocols to use classic keyboards with 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 project is intended to integrated existent TMK XT, PS/2 and Terminal converters.
- IBM XT converter: https://geekhack.org/index.php?topic=94649.0
- PS/2 converter: https://geekhack.org/index.php?topic=14618.0
- IBM Terminal converter: http://geekhack.org/index.php?topic=27272.0

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

REQUEST FOR HELP: Try and report your result.
Post your keyboard model number here, also debug outputs on hid_listen would be helpful.


Tested Keyboards
- IBM 122-key Terminal: 6110345


Keyboards which this firmware should work with(not tested)

- PC XT keyboard of IBM 5150 5160
  - 83-key: 1501100 1501105
- PC AT keyboard of IBM 5170
  - 84-key: 6450200 6450225
- PC Terminal keyboard of IBM 5271(3270 PC)
  - 122-key: 6110344 6110345 1397000
  - 102-key: 1390680 1395764 1392595
- PS/2 keyboards(AT+CodeSet2)
- Clones of above models


Hardware

Firmware supports ATMega32u4 by default, Teensy2/2++ or ProMicro can be used.
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



Prebuilt Firmware

https://github.com/tmk/tmk_keyboard/tree/master/converter/ibmpc_usb/binary



Build Firmware


    $ cd converter/ibmpc_usb
    $ make clean
    $ make



Keyboard discrimination

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
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.



Debug

Use hid_listen to see debug outputs from the converter.

https://www.pjrc.com/teensy/hid_listen.html

Code: [Select]

Waiting for new device:...
Listening:


TMK:95aba6dd/LUFA


USB configured.

Keyboard start.
rAA rBF rBF wF5 rFA wF2 rFA rBF rBF wF4 rFA ID: BFBF
kbd: Terminal
wF8 rFA 



Resources

IBM PC Keyboard Protocol Resources:

a. Microsoft USB HID to PS/2 Translation Table - Scan Code Set 1 and 2
http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/translate.pdf

b. Microsoft Keyboard Scan Code Specification - Special rules of Scan Code Set 1 and 2
http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/scancode.doc

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

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.



Update

[hasu]

anyone? please check first post.

REQUEST FOR HELP: Try and report your result.
Post your keyboard model number here, also debug outputs on hid_listen would be helpful.

[Maledicted]

I have a few ATMega32u4s sitting around waiting to be turned into Soarer's Converters, and probably the necessary resistors. I have both the standard IBM Model F XT, and AT. I also have some AT/XT switchable Uniteks and a DC-2014, although it already currently has a Soarer's converter I built inside of it. I know a guy that has an old RJ11 Wyse too (among other old weird things), if any of that may be helpful for testing.

What exactly is it that you wish to accomplish? An open-source alternative to Soarer's Converter? I would think that the AT/PS2 keyboards should all work just about the same, right? My F AT works with modern systems with a 5 pin din to PS2 adapter. There's certainly no shortage of random old PS2 boards that must be available to you.

[hasu]

I have a few ATMega32u4s sitting around waiting to be turned into Soarer's Converters, and probably the necessary resistors. I have both the standard IBM Model F XT, and AT. I also have some AT/XT switchable Uniteks and a DC-2014, although it already currently has a Soarer's converter I built inside of it. I know a guy that has an old RJ11 Wyse too (among other old weird things), if any of that may be helpful for testing.

Report on those keyobards would be definitely helpful. As for DC-2014 this firmware is compatible to Soarer's hardware you can just program it to test. This doesn't break your existent keymap settings of in eeprom, so you just need to program Soarer's firmware again to restore.

I really want to know my firmware with the IBM model F AT and XT(I don't own any unfortunately), they are very original and legitimate test samples for the keyboard  protocols.

I don't know much about RJ11 Wyse but I guess some of them uses Wyse specific protocol, not AT or XT.

What exactly is it that you wish to accomplish? An open-source alternative to Soarer's Converter? I would think that the AT/PS2 keyboards should all work just about the same, right? My F AT works with modern systems with a 5 pin din to PS2 adapter. There's certainly no shortage of random old PS2 boards that must be available to you.

Yes, I like to make this useful open-source converter and I will have to improve it.
I believe that there are still unexpected behaviours of keyboards and bugs on my code that cuases problems. It is difficult to find them without testing with real keyboards.

[hasu]

I tested with IBM 122-key Terminal 6110345 and it worked well.

The converter recognizes like below.

Waiting for new device:.......
Listening:


TMK:5a759850/LUFA


USB configured.

Keyboard start.
err: 2A
rAA rBF rBF wF5 rFA wF2 rFA rBF rBF wF4 rFA ID: BFBF
kbd: Terminal
wF8 rFA r3B rF0 r3B r3B rF0 r3B r3B rF0 r3B

[Maledicted]

My DC-2014 doesn't have any resistors soldered to the Pro Micro (I figured that would be fine with such short wires, but I think the reset pin should still be easily accessible to flash your firmware and it does appear to be wired the same. My general-use Soarer's converter at home doesn't even have the XT reset wire soldered to it ... and that's encased in hot glue now. I really should pry it back out and resolve that though. Worst case, I'll rig up a fresh controller and get back to you, maybe tonight. I'll have to lug the F AT and DC-2014 home from work.

[hasu]

It works without pull up resistors in most cases, you don't have to modify your exisitent converter, this conveter should work if Soarer's does.
XT reset is needed only for Old Type-1 IBM XT keyboard and some of XT clones.

Don't use short wire intead of pull up resistor, it may harm on the pin.

[Maledicted]

What I mean is that the wires are very short, since I put the converter inside the case of the keyboard. I like to move that one around so I removed the original cable and have a short micro usb extension cable peeking out of the case. The one I have in a hardware store junction box needs to be freed from the hot glue to add the reset wire anyway, so I may as well add resistors to it as well.

Tonight, hopefully, I will get to this. My box jades for a keyboard mod are coming in today as well, so possibly not, but it all gives me an excuse to keep the soldering iron hot.

[Maledicted]

Sorry about the delay. I don't get enough sleep on weekdays. Here's a fun one. It looks like the K151L worked in both AT and XT mode. Neither the F AT, nor F XT worked. The Leading Edge DC-2014 didn't work either. I did notice that the lock lights did seem to come on if I enabled them from another usb keyboard on the F AT, but the F AT lock light did not work. The F XT spewed out garbled keypresses the entire time that it was connected.

With the F AT, interestingly, it would say it was an XT keyboard until I hit the reset button I added to the Pro Micro. Here's the results of HID_Listen for that board, including after having hit the reset button:



For the F XT I unplugged the converter so that it would stop listening for me to copy the entire text ... it is a long one:

 IBM Model F XT output.txt

Here's the results from the DC-2014:



Here are the results of the K151L in AT mode:



And here are the results of the K151L in XT mode:



Let me know if you need anything else.

[hasu]

Thank you for the report!

As for Model F AT, can you try procedure below?
1. connect keyboard to converter
2. plug it into usb port
When you connect keyboard after usb plugin, the converter tries to recognize the keyboard as possible, but it requires several key strokes and the keys are ignored. You better connect keyboard before plugin to computer basically.

For Model F XT and DC-2014, the converter seems to miss signal, could you try attached firmware?

[Maledicted]

Thank you for the report!

As for Model F AT, can you try procedure below?
1. connect keyboard to converter
2. plug it into usb port
When you connect keyboard after usb plugin, the converter tries to recognize the keyboard as possible, but it requires several key strokes and the keys are ignored. You better connect keyboard before plugin to computer basically.

For Model F XT and DC-2014, the converter seems to miss signal, could you try attached firmware?

Well, with every keyboard I tested I made sure that their 5 pin din connectors were plugged into the Pro Micro before I connected the Pro Micro to the computer. I did the following with all of them:

1) Start HID_listen

2) Connect keyboard to Pro Micro

3) Connect Pro Micro to usb port on the computer

What I did with the F AT, since it was being detected as an XT keyboard for some reason when doing this, was short the reset contact to ground with a momentary button I added (while everything was still plugged in), since I figured I would need such functionality if we would be doing a lot of this.

This almost makes me want to pick up a female PS/2 adapter to wire into it as well to see what happens with random generic boards I have lying around, but I suppose they would probably work just about like the Unitek, right? I did also add a 1k resistor between data - ground and clock - ground as well, just in case (2 separate resistors). I added both of those resistors and the proper XT reset wire before I started testing your firmware.

Your alternative firmware seems to work with the DC-2014, but the XT behaved similarly to before. I would plug the Pro Micro into the computer with the keyboard already attached, no keypresses seemed to register, and HID_listen would freak out until I unplugged it. It looks like the output was a bit different this time though?

 IBM Model F XT output with alternative firmware.txt (1 kB - downloaded 7 times.)

[hasu]

Just note that Pull-up register is placed between 5V and signal line, not ground. 1-10K Ohm would be fine.
To confirm your converter hardware setup before testing my firmware, you can use well-tested Soarer's converter firmware.

[Maledicted]

Just note that Pull-up register is placed between 5V and signal line, not ground. 1-10K Ohm would be fine.
To confirm your converter hardware setup before testing my firmware, you can use well-tested Soarer's converter firmware.

Right. 5V, not ground. My mistake. What you describe is actually how I wired it. I had previously used all of these keyboards successfully with Soarer's firmware, but I could re-test with this specific Pro Micro, and the new modifications if you like. I imagine they'll all work.

Alright, interesting results. With Soarer's converter flashed to the Pro Micro, it works with everything (including the F AT) except for the F XT, it continues to spit random things out in HID_listen. I think it might dislike the reset wire that the DC-2014 requires. I may solder an on/of switch in if I desolder the reset wire and the F XT suddenly works again with Soarer's converter.

Even with the reset wire desoldered, it is doing the same thing. Is it possible that the F XT isn't happy with a 1k ohm resistor between clock - 5v/vcc and data - 5v/vcc? I know that this keyboard worked with this very same Pro Micro without the resistors.

I think I'll throw together another basic Soarer's converter from scratch, without the resistors. I have a few more Pro Micros lying around anyway.

It just keeps getting stranger. I desoldered the resistors and resoldered the XT reset wire and the F XT did nothing. If I disconnected the XT reset wire as well, it went back to freaking out. My computer even bluescreened. I wonder what version of Soarer's firmware I originally used with this keyboard now. I'm most recently using one that somebody modified to make the Pro Micro's PB6/ contact/pin 10 into the keyboard reset line, since Soarer's firmware apparently didn't account for this on the Pro Micro.

Now the Pro Micro itself is spurting out random characters. I tried reflowing all of the solder and flashing another version of Soarer's but that didn't change anything ... I'll build a new one.

[hasu]

Just note that Pull-up register is placed between 5V and signal line, not ground. 1-10K Ohm would be fine.
To confirm your converter hardware setup before testing my firmware, you can use well-tested Soarer's converter firmware.

Right. 5V, not ground. My mistake. What you describe is actually how I wired it. I had previously used all of these keyboards successfully with Soarer's firmware, but I could re-test with this specific Pro Micro, and the new modifications if you like. I imagine they'll all work.

Alright, interesting results. With Soarer's converter flashed to the Pro Micro, it works with everything (including the F AT) except for the F XT, it continues to spit random things out in HID_listen. I think it might dislike the reset wire that the DC-2014 requires. I may solder an on/of switch in if I desolder the reset wire and the F XT suddenly works again with Soarer's converter.

Interesting.
There are two types of IBM XT. Type-1 requires reset line to start up while Type-2 doesn't. But on Type-2 reset line is not connected to its controller so I believe reset line doesn't bother Type-2. Converter with reset line should work regardless of whether your XT keyboard is Type-1 or Type-2.
https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-XT-Keyboard-Protocol#type-1-vs-type-2

If your XT is Type-1 and you use ProMicro you will have to use this modified version of Soarers' firmware to support reset line on pin 10(PB6). I belive you already know and use this on DC-2014, though.
https://deskthority.net/viewtopic.php?p=187874#p187874

Even with the reset wire desoldered, it is doing the same thing. Is it possible that the F XT isn't happy with a 1k ohm resistor between clock - 5v/vcc and data - 5v/vcc? I know that this keyboard worked with this very same Pro Micro without the resistors.

I think I'll throw together another basic Soarer's converter from scratch, without the resistors. I have a few more Pro Micros lying around anyway.

I don't think 1K pull-up resistors are problem but it is still worth trying without them.

Thanks for your time.

[Maledicted]

I redid all of the wiring on the Pro Micro with some good high quality silicone wire, cleaned up all of the old solder first with some wick. It seems to work with other keyboards again, with Soarer's firmware. I didn't know that some F XTs required the reset wire and that some did not, I figured it was weird "XT-like" boards that used it. I do know that my F XT refused to work on initial boot of my operating system unless I unplugged the converter and plugged it back in, without the reset wire. The F XT is still doing the same thing as before even with Soarer's firmware. I may take it apart and take a look inside. I got it with a cut cable, so I snipped a MIDI cable and soldered it in.

Let me know if there's anything else you want me to try with the F AT with your firmware in the mean time.

F XT cable tests good, all wires make a good connection to the controller and none are bridged. I should have known. I made sure this thing would never break. Mine must be a type-2, there are only 4 wires running from what's left of the original cable to the controller.

Alright, I built an entirely new Soarer's converter and the F XT is now working with that. I thought there may be something wrong with the other converter, but I think there was something flaky with the usb cable, grounding maybe, since once I removed the usb extender it would work. I still can't get the F AT or F XT to work with either version of your firmware though. At least the F XT doesn't spit out random keypresses though. So, I've tried 3 different usb cables and 2 different Pro Micros, one with and without the pullup resistors and a complete rewire, with the same results (once whatever was going on with the XT was resolved).

With a little more testing, I also noticed that the K151L was only working when I connected while it was in XT mode. If i switched it to AT mode, it would continue to work, but if I connected it while it was already in AT mode, it would not.

So, with the original firmware the K151L worked in XT mode. With the alternative firmware the DC-2014 worked.

[hasu]

Let me know if there's anything else you want me to try with the F AT with your firmware in the mean time.

I found description of power-on-reset on original 84-key AT in IBM tech reference, it is  rather slower than I expected.
Could you try this new attached firmware and show me output of hid_listen when press a, s, d and f key? I need to know numbers of Ixxx and Rxxx in particular, like below.

Code: [Select]

TMK:ee0200d6/LUFA

USB configured.

Keyboard start.
I401
rAA R1163
wF5 rFA wF2 rFA rAB r83 wF4 rFA ID: AB83
kbd: AT
L1175
wED rFA w00 rFA wED rFA w02 rFA r1C rF0 r1C r1B rF0 r1B r23 rF0 r23 r2B rF0 r2B r34 rF0 r34


Alright, I built an entirely new Soarer's converter and the F XT is now working with that. I thought there may be something wrong with the other converter, but I think there was something flaky with the usb cable, grounding maybe, since once I removed the usb extender it would work. I still can't get the F AT or F XT to work with either version of your firmware though. At least the F XT doesn't spit out random keypresses though. So, I've tried 3 different usb cables and 2 different Pro Micros, one with and without the pullup resistors and a complete rewire, with the same results (once whatever was going on with the XT was resolved).

Do you test my firmware with the "new Soarer's converter", right?
Sorry but can you share output of hid_listen for F XT with this new firmware again?  Pressing a, s, d and f key would be helpful.

[Maledicted]

I tried both previous firmwares with both the newly assembled Pro Micro, and the previous one that I had re-wired. The results were the same other than the F XT no longer spewed out random keypresses (most of the time). I noticed that with your latest firmware the F XT spewed out random keypresses on the rebuilt Pro Micro and did not on the one that I just newly built specific for this testing. That makes no sense to me since I wired them exactly the same way this time, with the extra XT wire soldered, and no resistors.

The XT did now give results with the new firmware, on the newly-assembled Pro Micro, when pressing the a,s,d, and f keys, although that didn't seem to translate into actual character signals that the computer understood when I tried to type out text. HID_listen detected nothing at all when I used the latest supplied firmware to press the a,s,d, and f keys on the F AT. I have attached the results of your requested test with the F XT:

 Ibm Model F XT output second alternative firmware, asdf pressed.txt (0.65 kB - downloaded 10 times.)

[Maledicted]

I don't mean to double post, but do you have everything you need, or is there anything else I can test for you while I have all of the boards in one place? I jump around between buildings at work, and use the DC-2014 especially at work, but also the F AT. I have been keeping them at home the last few days for testing this.

[hasu]

Maledicted,
Thank you for your service so far! I really appreciate.
I don't want to prevent you from using your keyobards anymore, feel free to place them back to where they should be when you need.

I'm debuging my code on keyboard protocol recoginition and signal handling and this will take some time. If this is not in time for your test, others in the community will help me in the end.

Thanks agian!

[Maledicted]

Absolutely, anything I can do. Thank you for putting all of that effort into an open source project for the community at large.

Actually, since I posted that, I won another F AT and DC-2014 on Ebay, so I should have at least one of each available no matter what now. lol

Have others with the same boards helped elsewhere? I wouldn't be surprised if none had. I imagine a lot of people go, "Soarer's firmware works for me. I'm good." since all of these boards work fine already. I think it is pretty important to expand on the functionality of Soarer's work though myself, and being open source like that, TMK seems to have the potential to become the one catch-all solution in time.

[gravesgeek]

Hi, I am new to the community with my model m, unicomp ultracompact.
I found a 1987model m122 with stepped key and DIN 5 plug and 1981 model f xt with DIN 5 plug from a local flea market for 30 and 40 USD, respectively.

But the problem is I am not an electronics man (MD. actually). I can find someone from the medical device maintenance dept. for soldering. But I don't think they can handle the programming.

Is there any guide for building converters from the beginning?

Is there a software with a simple interface for remapping the keys or this can be don only by code writing?

Thanks to everybody.

[Maledicted]

Hi, I am new to the community with my model m, unicomp ultracompact.
I found a 1987model m122 with stepped key and DIN 5 plug and 1981 model f xt with DIN 5 plug from a local flea market for 30 and 40 USD, respectively.

But the problem is I am not an electronics man (MD. actually). I can find someone from the medical device maintenance dept. for soldering. But I don't think they can handle the programming.

Is there any guide for building converters from the beginning?

Is there a software with a simple interface for remapping the keys or this can be don only by code writing?

Thanks to everybody.

Hello gravesgeek, welcome to the keyboard obsession. You're probably best off posting a separate thread on this, but the M122 should work with most any 5-pin din to ps2 adapter with any modern computer that has a ps2 port. For the F XT, or to use either through a usb port, you'll need to build or buy a converter and flash it either with Soarer's converter firmware, or Hasu's. Pre-made converters with Soarer's firmware are readily available on Ebay.

For remapping, there are programs like SharpKeys, which seemed easy enough to me the last time I used it, but that was years ago. The zip downloads for Soarer's firmware contain documentation on how to remap keys and apply that remapping to the converter (which would, conveniently, mean that all computers you use with the converter would have that same mapping). Google searches reveal the same.

For the process of wiring and flashing, this is a simple/detailed guide:

https://deskthority.net/viewtopic.php?t=19035

[hking0036]

I can try this out - my kbd is Terminal F122 6111070. It's got french legends on the CMD keys up top but other than that I believe it is identical to 6110344.

Here is the output:

Code: [Select]

Waiting for device:.....
Listening:


TMK:5a759850/LUFA


USB configured.

Keyboard start.
rAA rBF rBF wF5 rFA wF2 rFA rBF rBF wF4 rFA ID: BFBF
kbd: Terminal
wF8 rFA

I have been using the terminal_usb converter for some time, and it has worked very well. Is there a particular intent for this FW?

P.S. Looking in unimap_trans.h, it seems that 0x58 is bound to 0x14 for Type-3 sets, but isn't marked.