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)
- On-the-fly Config Selection
- 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
Conn. TeensyTeensy pins
GND -------- GND
Vcc/+5V ---- Vcc
Data ------- PD0
Clock ------ PD1
See PJRC for Teensy pinouts
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
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
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):
CapsLock LED ------ PF5
NumLock LED ------- PF6
ScrollLock LED ---- PF7
Teensy++ 2.0 (AT90USB1286):
CapsLock LED ------ PD3Installation
NumLock LED ------- PD4
ScrollLock LED ---- PD5
There's great instructions
on the PJRC site that cover loading a hex file into the Teensy, for any common OS.Troubleshooting
The converter outputs some cryptic diagnostic information when in use, and it's especially useful to see what is happening when it starts up.
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 verifiedDell 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.11History
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 releaseDownloads