XT/AT/PS2/Terminal to USB Converter with NKRO

[Soarer]

Since v1.0, this mod can also be found on Deskthority.

Introduction

This is my Teensy-based project which adapts XT, AT and some 122 key terminal keyboards to USB, also known simply as "Soarer's Converter".

There are versions for Teensy 2.0 and Teensy++ 2.0. I recommend the Teensy 2.0 for this (it's cheaper), but sometimes PJRC don't have any in stock!


Features

Keyboard protocols supported:

• XT (scan code set 1)
• AT (scan code set 2)
• PS/2 (MF2) (extended scan code set 2)
• Terminal e.g. 3179/318x/319x (scan code set 3)

Configurable Features: (v0.997+)

• Remapping
• Layers
• Macros
• On-the-fly Config Selection

Other Features:

• Full NKRO, if the keyboard supports it (even on Macs!)
• Boot mode support (even with faulty BIOS!)
• Auto-detection of the keyboard type
• XT and AT boards are remapped correctly for PrtSc etc. (see Legacy Note below)
• 1000Hz polling using Full Speed USB
• Suspend and resume support
• Media and Power key support
• Jump to bootloader function (update firmware without pressing the reset button) (v1.0+)

Legacy Note - in v0.996 and earlier, hard-coded settings were used to support correct remapping of PrtSc etc. for XT and AT keyboards. These settings are now implemented by the legacy.sc config file, which must be compiled (by scas) and loaded (by scwr, after flashing) if you want the v0.997 (or later) converter to act like v0.996.


Documentation

The latest 'full' zip contains complete documentation covering all aspects of the converter including the tools, config commands, key codes etc.

This post contains the basics, but hasn't been updated much since about v0.996. I'll keep it accurate, but not complete.


Construction

Wiring Info

Code: [Select]

Conn.       Teensy
GND -------- GND
Vcc/+5V ---- Vcc
Data ------- PD0
Clock ------ PD1

Teensy pins

See PJRC for Teensy pinouts.


Connectors

I wired mine to a PS/2 socket, and then use adapters to connect the others.

kbdbabel has masses of connector info. So much that it can be hard to find the one you want! I've included here the most common connectors used with this converter:

Terminal keyboards usually have a 5 pin, 270 degree, DIN connector...


...or sometimes this 8P5C connector...


XT and AT keyboards use the same 5 pin, 180 degree, DIN connector and pinout (top), while PS/2 keyboards use a 6 pin mini-DIN connector (bottom)...


RT keyboards use a 6 pin rectangular connector...


Important note - these diagrams are drawn looking into the front of socket. When you are soldering the pins on the back of the socket, you need to make sure they are correct. Especially for the AT and PS/2 sockets, where mirroring the connections will result in power and ground being swapped - and that is VERY BAD!


Pull-up resistors

In nearly all cases, these resistors are not needed.

But, if the keyboard has a long cable, I recommend adding two pull-up resistors of 1Kohm - one between Clock and +5V, the other between Data and +5V. These can really help to clean up a dirty signal (see here).


LEDs

Optionally, lock LEDs can be wired up. Useful if your keyboard doesn't have them!
The outputs are active high (each pin puts out +5V when it wants to light the LED).
A resistor is needed inline with each LED. (The value needed depends on the type of LED, 1Kohm is a good starting point for modern high-brightness types).
The pins used differ between Teensy and Teensy++:

Teensy 2.0 (ATMEGA32U4):

Code: [Select]

CapsLock LED ------ PF5
NumLock LED ------- PF6
ScrollLock LED ---- PF7
Teensy++ 2.0 (AT90USB1286):

Code: [Select]

CapsLock LED ------ PD3
NumLock LED ------- PD4
ScrollLock LED ---- PD5

Installation

There's great instructions on the PJRC site that cover loading a hex file into the Teensy, for any common OS.


Troubleshooting

Diagnostic output

The converter outputs some cryptic diagnostic information when in use, and it's especially useful to see what is happening when it starts up.

The hid_listen program can display this output, which mostly just consists of bytes read from and written to the keyboard when things are working correctly.


Keyboard IDs

This section is mostly only relevant to terminal keyboards. The converter uses the ID to decide between using scan code set 3 for terminal keyboards, or extended scan code set 2 for 'regular' keyboards.

By using hid_listen, you can see what ID your keyboard has by looking at the two bytes read back after the get ID command (wF2 rFA).

As of v0.996, the ID and scan code set selected is also printed in a more readable way:

Keyboard ID: BFBF
Code Set: 3

Terminal keyboards often have DIP switches on the back panel, or alternatively a pin header on the PCB that you can fit jumpers to, which configure the keyboard's ID code. The ID is a 16-bit number, but commonly fewer than 16 switches/jumpers are fitted meaning it's not possible to select all of the bits. The default value with no jumpers fitted, or with all the DIP switches in the 'open' position, is BFBF.

If your terminal keyboard is not operating correctly, it might be because the wrong ID is set on the switches/jumpers. The first byte should not be AB.


Known Issues

Weirdo Monterey International Corp. FKF456K-104 AT keyboard with 3-way A,X,S switch on the back
-- should be fixed as of v1.10, but hasn't been verified

Dell M6300 (BIOS rev A14) and Dell Inspiron 630m have incompatible/defective BIOS
-- possibly fixed by USB compliance improvements in v1.03, or by preventing debug output in boot mode in v1.11


History

v1.12 - added workaround for Linux bug which causes Delete key not to repeat - details.
v1.11 - added RT keyboard support, added boot mode indication, prevented debug output in boot mode - details.
v1.10 - improved documentation, added 'almost' PC/XT support, added aux key inputs - details.
v1.03 - fixed bug which caused the converter to lose config or reboot after using the scrd tool, and fixed minor USB errors revealed by using the Command Verifier compliance testing tool.
v1.02 - fixed bug which could cause the converter to lock up if a key was pressed at certain times during system boot - details.
v1.01 - fix bug in jump to bootloader affecting Teensy++ - details.
v1.0 - adds jump to bootloader, scboot tool, scinfo tool, documentation, settings protocol improvements, linux and macosx tools, and reduced hex size - details.
v0.997 - adds user-definable remaps, macros, layers, selects, media keys, and config tools - details.
v0.996 - fix for 'slow' responding keyboards, improved robustness when keys are being pressed before init has completed, alternative layouts for terminal keyboards - details.
v0.995 - quick fix for 122-key mapping (top right numpad key is 'pause'), and simplified the code testing which keyboard type is attached.
v0.994 - adds suspend support, with remote wake-up - details.
(v0.993 wasn't stable enough to subject you to!)
v0.992 - fixes minor incompatibility with Linux (backslash key not repeating etc.) - details.
v0.99 - first public release


Downloads

[Mr. Perfect]

Impressive work there. It's tempting to make one of these even for boards that work on USB, just to get the NKRO.

Optionally, lock LEDs can be wired up.
The outputs are active high (each pin puts out +5V when it wants to light the LED).
A resistor is needed inline with each LED. (The value needed depends on the type of LED, 1Kohm is a good starting point for modern high-brightness types).

Is this for extra LEDs on the converter? I'm assuming the LEDs on the boards themselves are controlled by the boards, or doesn't the lock message get passed to the board?

[Soarer]

Some boards don't have LEDs (e.g. XTs and Terminals), and in the case of the XT the protocol doesn't support them. The converter does pass LED state to the keyboard when it can though!

And yes, for a board like a Filco (which has a dual USB/PS2 interface), you could use it in PS2 mode and route it through this converter to get full NKRO (and any other fancy features that have yet to be enabled).

[HaveANiceDay]

This looks really interesting. Especially the Filco NKRO USB Mod possibilities.
I don't need NKRO, but somehow I crave it

[hasu]

Nice work!

I tried your converter with PS/2 keyboard on Mac and confirmed NKRO works fine. Great!
My converter's NKRO feature fails on Mac. It seems I have to check your report descriptor later.

Full NKRO, if the keyboard supports it (even on Macs!).

[Soarer]

Thanks, hasu!

I might need to add in your fix for the SET_IDLE problem on OS-X. I have made changes to that part of the code, but I have no OS-X machine to test it on. If I am lucky it will work!

[Soarer]

If you guys ever fix the OSX bug tell Nopoo and the Ducky G2 engineers (probably the same PLUM Corp. firmware designer).

 
Which one? My firmware was already working better than theirs many weeks ago.

[ch_123]

Thanks, hasu!

I might need to add in your fix for the SET_IDLE problem on OS-X. I have made changes to that part of the code, but I have no OS-X machine to test it on. If I am lucky it will work!

 
I'd be willing to check this out whenever I get my Teensy and sufficient free time.

[Soarer]

I'd be willing to check this out whenever I get my Teensy and sufficient free time.

 
That would be great, thanks!

I think the most likely problem (if any) is an occasional dropped keystroke - but it might well only happen when a keypress is made WHILE it's processing the idle AND also receiving updated LED state!! Also, if it's not using the XT protocol, it will simply ask the keyboard to resend the missed byte - the only sign that something has gone wrong will be that the LED on the Teensy lights up for a couple of seconds :-)

Or... it could fail in some way I haven't though of at all yet!

[Hak Foo]

Just built, waiting for my terminal F to come tomorrow.
adding the LEDs lets you test for a correct download and basic behaviour tho
Hint:  the Radio Shack 276-0150 breadboard is real nice for this as it has pins in twos and threes pre-shorted so you don't have to wire everything with solder bridges.  It's $2 and readily available, and it's also small unlike a lot of the boards I saw.

[Soarer]

Ah, Hak Foo... just spotted your question on IRC about the devices that the converter uses...

It's a composite device with [strike]four parts to it:
1. Boot keyboard
2. NKRO keyboard
3. Media and power keys
4. Debug channel[/strike]

edit: I really shouldn't answer these things from memory! Four was the plan at one point, but it ended up fitting into three:
1. Boot keyboard
2. Debug channel
3. NKRO keyboard, Media keys, and power keys



Spying on the debug channel with HID Listen is another way to check that the code has been loaded properly. It dumps the raw codes read from, and written to, the keyboard. Even if no keyboard is connected (or an XT), it will show 'wEE' when the converter is first plugged in. That's it writing an echo command to see if the keyboard responds.

[xwhatsit]

What are you using for a VID/PID?

[Soarer]

What are you using for a VID/PID?

I'll check later, but I haven't changed it from the defaults in the PJRC sample code.

edit: VID = 16C0, PID = 047D.

[xwhatsit]

Ah right. I'm going to use the standard V-USB HID keyboard VID/PID for my wee project. Seems you can't buy a small block any more -- the resellers have been shut down by the USB-IF -- I bought one a while ago for a project, and don't really want to re-use it.

[intealls]

Nice work!

Just wondering what kind of remapping/macro features your firmware supports? Also, when will you release the source?

[Soarer]

Ah right. I'm going to use the standard V-USB HID keyboard VID/PID for my wee project. Seems you can't buy a small block any more -- the resellers have been shut down by the USB-IF -- I bought one a while ago for a project, and don't really want to re-use it.

 
For personal projects, I guess it doesn't really matter what we use! (I admit I haven't bothered to look into it).

These are the values and comment from the PJRC keyboard sample code:

Code: [Select]

// Mac OS-X and Linux automatically load the correct drivers.  On
// Windows, even though the driver is supplied by Microsoft, an
// INF file is needed to load the driver.  These numbers need to
// match the INF file.
#define VENDOR_ID 0x16C0
#define PRODUCT_ID 0x047D


[Soarer]

Nice work!

Just wondering what kind of remapping/macro features your firmware supports? Also, when will you release the source?

Remappings are done from HID code to HID code, using a table in RAM, after the native scan codes have been translated to HID codes (using tables in the ROM). The idea is that remappings are applied to the table piecemeal - maybe some that only apply to certain boards, some that are global - in a more dynamic way than editing scan code tables directly. For example:

Code: [Select]

const uint8_t PROGMEM colemak_remaps[] = {
HID_KEY_D, HID_KEY_S,
HID_KEY_E, HID_KEY_F,
HID_KEY_F, HID_KEY_T,
HID_KEY_G, HID_KEY_D,
HID_KEY_I, HID_KEY_U,
HID_KEY_J, HID_KEY_N,
HID_KEY_K, HID_KEY_E,
HID_KEY_L, HID_KEY_I,
HID_KEY_N, HID_KEY_K,
HID_KEY_O, HID_KEY_Y,
HID_KEY_P, HID_KEY_SEMICOLON,
HID_KEY_R, HID_KEY_P,
HID_KEY_S, HID_KEY_R,
HID_KEY_T, HID_KEY_G,
HID_KEY_U, HID_KEY_L,
HID_KEY_Y, HID_KEY_J,
HID_KEY_SEMICOLON, HID_KEY_O,
0, 0
};

That's far smaller than a complete scan table, and could be applied to any keyboard regardless of the scan code set it uses natively.

Macros very quickly get fiendishly complicated to implement! So, for version 1, the converter will only support macros that emit a sequence when a key (or combi) is pressed, and do nothing when the key is released. The sequence can include key presses/releases, saving/restoring modifier state, etc. There may be limitations on which combinations can be used to trigger a macro, e.g. single non-modifier key plus modifiers, but I hope it can be (or become) more flexible than that.

I'd like to release the source code ASAP, even though there's a couple of pieces missing before it gets to v1.0, which are: defining a storage format for macros (including how they're triggered), and defining how the control interface works to allow remappings and macros to be edited on the host PC (preferably in a cross-platform way...).

I haven't decided whether to release it before or after doing either or both of those things

[Hak Foo]

Stupid question: what's the default mapping for a 122 look like?  I'm thinking I'm going to hook it up and panic when I can't find half the editing keys.

I wonder if you could do an approach of "load the main binary at one address, and the macro pack/mapping pack always exists at another address space" so you only have to rewrite the second space.

[Soarer]

Stupid question: what's the default mapping for a 122 look like?  I'm thinking I'm going to hook it up and panic when I can't find half the editing keys.

Roughly speaking, it's done as a regular 102 with extra keys. The block of 10 keys on the left contains stuff like windows keys, PrtSc, etc. It's true though, that the 122s are the ones that need remapping the most - as in, everyone has a different idea about how to make them useful! For the default, I've chosen to have each key send a unique code, so that remapping with e.g. AutoHotkey works well.

I wonder if you could do an approach of "load the main binary at one address, and the macro pack/mapping pack always exists at another address space" so you only have to rewrite the second space.

 
Here's the vague plan - they will be stored in the EEPROM, a control pipe will allow reading and writing it, an OS specific program will talk to the control pipe, and a higher level utility (Java or javascript or ) will talk to the OS specific part.

Thing is, until all of that is in place, it's probably easier to simply edit the source and recompile!

[intealls]

I've got a Teensy++ 2.0 with your firmware hooked up to my MBP Santa Rosa, and I've yet to encounter any multiple/repeated keystrokes! Just ran six speedtests without issue (about 2900 keypresses, ~95 wpm). Seems to work great.

Edit: Hm, just put the computer to sleep and when it woke up W was repeating for some reason. Had to press another key to make it stop.

The problem can be recreated by putting the computer to sleep, banging a couple of keys on the connected keyboard and then waking the computer up.

[Soarer]

Excellent news! Thanks for letting me know, that was the last part that was completely unverified - think I'll have a little drink to celebrate :-)

edit: you edited :-(  So, I guess I do need to add something to handle suspend mode - I knew I wasn't handling it, but I didn't realise it would do that. Is it fine as long as you don't press any keys while it's sleeping?

[intealls]

Sorry 'bout that. :/ Yup, seems fine when no keys are pressed! Gonna test a couple more times.

When no keys are pressed, it does not repeat. Tried it like 8 times or something.

I also tried an old version of hasu's firmware without the SET_IDLE fix, and I can with 100% certainty say that the repeating key issue is non-existant with your firmware.

[Soarer]

Thinking about it, I can't quite figure out what's going wrong - I guess it must somehow be missing the key up event from the keyboard. Does pressing a key wake it up from sleeping? That might re-initialize the converter, and I could clear the key state at that point, as a quick fix.

[intealls]

It does not wake up That was what I was testing. I just tried the same thing on Linux on the same computer, and it worked fine (no repetition). Could it be because OS X still powers the USB ports or something when it's suspended (iDevice-charging)? I don't think they are powered when running Linux.

Hm, if I press one key normally during suspend and wake it up, no repeated keypresses. If I hold down the key for a while (and release it before the computer is woken up) and then wake the computer, that keypress is repeated on wakeup.

[Soarer]

I think handling wake-up will have to wait until I support suspend mode correctly - it is on the wishlist already though!

For now, I've made a quick change to clear the output state whenever the USB connection is reset. I've no idea if it will work or not, but it shouldn't do any harm :-)

[intealls]

It still seems to repeat. :/

Would be great if someone else could try to reproduce it as well, so it's not just my setup. I tried both USB-ports, didn't seem to make any difference though.

[kishy]

I am unable to reproduce, or witness any issues at all after waking from standby (just tried - even with keys held while sending it to sleep).

Dell Inspiron 630m, if it matters. 122-key Model M.

Using a rather old version of the code though, and on next flash I'm going back to dfj's...not due to any failure of Soarer's, but because I'm supposed to already be evaluating for dfj lol.

[intealls]

I think it's a problem related to OS X, Linux (Ubuntu 10.04 I think) on the same machine worked fine (no repeats). Haven't got Windows on this machine, so can't test that. :/

What OS are you using on the Inspiron?

[kishy]

Win7...so yeah...might be OS-related (in fact, there's a good chance it is...standby is a hardware/firmware feature, but how peripherals behave about it is going to relate to drivers I expect)

[Soarer]

It still seems to repeat. :/

 
Thanks for trying it. :-)  I'm still hoping that there is a change I can make that will fix it, without having to add a lot of new code. Especially when I can't easily test (on OS-X) what I write, as I go along!

[Oqsy]

High five!

122 key terminal Model F up and running!!!  Everything is good so far

I can't wait to get some of these added keys mapped with AHK

Thanks for your hard work!

[Soarer]

v0.992 is now available, which works around an annoying issue with Linux.

The problem was that the backslash key would not repeat, and if another key was pressed while it was held down, extra backslashes appeared.

My converter's HID report is a bitmap, and each bit represents a specific HID key code.
The codes are all unique in HID land, but not when mapped to Linux scan codes.
The HID codes for backslash and 'Europe 1' are both mapped to the Linux code for backslash (by Linux).
'Europe 1' comes later in the report than backslash.
So, Linux scans the report, sees backslash down and registers it, but then sees 'Europe 1' up and clears the backslash state.
It would register a press and release of backslash every time it received a report from the keyboard while backslash was held down, but otherwise would not repeat it (since most of the time, it thought the key wasn't pressed).

The fix is that the 'Europe 1' code has been removed from the report. (It really wasn't useful anyway, even to Europeans!).

I'd call it a flaw in Linux, not my converter, but still it had to be fixed!

[Neit]

Hi Soarer,

I would like to wire your converter with both DIN and PS/2 connectors.
Since I'm pretty noob in electronics, I need some advice here.

Is it OK to wire the teensy and connectors like this ?
(followed your instructions on the article and of course I will use DIN OR PS/2, not both at the same time).


Hope that I can.
Oh, and thank you for your great work, I may "resurrect" a terminal keyboard that probably use XT protocol.

[Soarer]

Nice diagram!

Yes, that should be fine. (In fact, I don't think plugging both in at the same time would cause any harm, but don't blame me if it does!)

[Oqsy]

Glad this was brought up, as short-term I will be doing the same with a terminal F, an XT, and a PS/2. I didn't know if a switch was necessary to disable the unused connector(s) for any reason. Long term I will be building a few of these guys for different purposes.

[Neit]

Nice diagram!

Thanks
I wanted to make it clear and "readable" for my first electronic build.

Yes, that should be fine. (In fact, I don't think plugging both in at the same time would cause any harm, but don't blame me if it does!)

Good news!
Anyway, I will not give a try.

I received my teensy today (very fast shipping, ordered the 27th). And, it's very tiny.
I have three more questions about it:

• Will an old IDE cable be fine for wiring, or a bigger section is needed?
• In the article, you recommend the use of an 1Kohm pull-up resistor between Clock and +5V and one other between Data and +5V in case of long cable. I'm pretty scared about this (my soldering skills are fresh), for you, which length is becoming "long" and need the add of resistors?
• Last question, since the teensy is very small. May I do my soldering at the back of it? (where there's only printed circuits, not components, and then avoid some damage by overheating).

[Soarer]

• Will an old IDE cable will be fine for wiring, or a bigger section is needed?

That is fine. (It's probably about the same thickness as the wires in the cable to the keyboard).

• In the article, you recommend the use of an 1Kohm pull-up resistor between Clock and +5V and one other between Data and +5V in case of long cable. I'm pretty scared about this (my soldering skills are fresh), for you, which length is becoming "long" and need the add of resistors?

Even at 5 metres it still worked fine without the pull-ups! But it definately tidied the signal up at that point. I would call more than 2 or 3 metres 'long'.

• Last question, since the teensy is very small. May I do my solders at the back of it? (where there's only printed circuits, not components, and then avoid some damage by overheating).

Yes, either side, as you wish.

Are you putting the sockets in a box? If you are, you might find it easier to wire from the Teensy to the DIN connector, then make the double connections there to also wire to the PS2 socket. DIN connectors usually have large tags, making it fairly easy to solder two wires on.

[Neit]

Even at 5 metres it still worked fine without the pull-ups! But it definately tidied the signal up at that point. I would call more than 2 or 3 metres 'long'.

Okay good. I'll get some resistors just in case.

Are you putting the sockets in a box? If you are, you might find it easier to wire from the Teensy to the DIN connector, then make the double connections there to also wire to the PS2 socket. DIN connectors usually have large tags, making it fairly easy to solder two wires on.

Yes, I was planning on a (lego) box.
Thanks for the tip, it will surely help my soldering!

Can't wait to build it up.
Thanks again for your advices.

[nowsharing]

Wow, awesome work everyone. You've achieved the "impossible."

Could I buy one of these contraptions from anyone?

[bhtooefr]

Man, this code works great.

Now I just need the remappable version.

[slueth]

Wow, awesome work everyone. You've achieved the "impossible."

Could I buy one of these contraptions from anyone?

 
Just buy a teensy and request a sample from tyco electronics for the DIN connectors.  Not that hard to wire up.

[Hak Foo]

if you don't feel like harassing tyco, the socket costs <4 USD from the big online parts dealers, although shipping is a killer.  what I'd love to see is a pre-routed PCB for neat look.  the diy route looks it.

[8_INCH_FLOPPY]

I want to do this, but why is the teensy so damn expensive?

[slueth]

Its because not only can you use it for a keyboard convertor, you can use it for a slew of other projects because it is a USB-based microcontoller.  
Teensy is actually cheap compared to other arduino products.
Basically we are taking a nuke and killing a tick.

[Neit]

Hey,

I Updated the diagram before soldering.
I finally chose to add the resistors for more security.
Still good?

(click to enlarge)
and

[Soarer]

Yep, even better! I like that the socket views are labelled as front and back - it removes any confusion.

[Soarer]

I want to do this, but why is the teensy so damn expensive?

 
Is it though? Even used just as a keyboard converter, I don't think it's unreasonable, considering how much it can do. But then, maybe you're one of those who thinks the blue cube is too expensive also, and have wasted money on a small mountain of crappy $3 converters (I don't mean that as aggressively as it may sound, btw, I have quite a collection!).

As an Atmega breakout, the Teensy can't be beaten on quality OR price... it really is the de facto choice for that reason.

[Findecanor]

There are lots of unused pins, though.
I wonder if they could be used for something useless ...

But, I think it would be even better if each port was on a separate set of pins ... and all worked at once.

[Mr. Perfect]

Very nice diagrams there Neit. Any idea where the lock LEDs would fit into those?

[Soarer]

There are lots of unused pins, though.
I wonder if they could be used for something useless ...

 
DIP switches!!