PS/2 to USB keyboard converter for Teensy with mousekeys and NKRO

[hasu]

This is a PS/2 to USB keyboard converter with some nice features.

• Firmware repo: https://github.com/tmk/tmk_keyboard/tree/master/ps2_usb
  

HISTORY

• 2011/01/23  Initial version
  
• 2011/01/24  FIX: handle keys which need exceptional treatment
  
• 2011/02/25  added V-USB support
  
• 2011/05/31  PS/2 Multimedia key support.
  
• 2011/12/05  ISO/JIS keyboard support.
  

FEATURES

• Mouse keys
      You can emulates mouse move and button click using keyboard.
  
• Multimedia keys
      You can send key event like: system control(Power down, sleep,...), Volume down/up and Mute, Media control, Application launch, Browser control.
  
• USB NKRO(actually 120KRO+8Modifiers)
      You can tolggles NKRO/6KRO feature.
  
• Keymap customization
      You can customize keymaps easily by editing source code. See keymap.c
  

BUILD CONVERTER
Connect CLOCK line to PF0 pin and DATA line to PF1 pin. Needless to say, you need to wire Vcc and GND line too. You can change pin configuration by editing config.h.

This is my PS/2 harness which connect a keyboard to Teensy. Vcc is yellow, GND is green, Data is red and Clock is black in this case.
NOTE: Pullup resistors(1k-10k) on both Data and Clock line are recommended though my converter doesn't has them.



BUILD FIRMWARE

• $ git clone git://github.com/tmk/tmk_keyboard.git
  Or download from here: https://github.com/tmk/tmk_keyboard/downloads
  
• $ cd ps2_usb
  
• Edit config_pjrc.h to macros to define macros for PS/2 signal lines. This is probably not needed.
  
• Edit Makefile for build options and MCU setting. Use 'atmega32u4' for Teensy 2.0 or 'at90usb1286' for Teensy++ 2.0.
  
• Edit your keymaps in keymap.c if needed.
  
• Make. Just type 'make' in a terminal if AVR GCC toolset is properly setup.
• Write a firmware with your Teensy with Teensy Loader.

http://www.pjrc.com/teensy/loader.html
[/LIST]


DEMONSTRATION OF FEATURES
In default configuration, you can try several keymaps, mousekeys and USB NKRO.
Use following magic key combinations to enable some features.

Special functions

• Magic+0:    Qwerty layout with mousekeys
• Magic+1:    Qwerty layout(use if you mind mousekeys)
• Magic+2:    Colemak layout
• Magic+3:    Dvorak layout
• Magic+4:    Workman layout
• Magic+N:    toggles NKRO/6KRO(6KRO by default)
• Magic+Esc:  sends Power Event/Remote wakeup

where Magic=(LShift+RShift) or (LControl+RShift)

Fn layer function

• Fn0+(hjkl): Mouse key move(vi cursor)
• Fn0+(yuio): Mouse wheel(left,down,up,right)
• Fn0+space:  Mouse button1
• Fn0+(mnb):  Mouse buttons(1,2,3)
• Fn0+(zxc):  Media control(Volup, Voldown, Mute)
• Fn1+(hjkl): Cursor move(vi cursor)
• Fn1+(nm,.): Cursor move(Home,PageDown,PageUp,End)

where Fn0=;, Fn1=/


KEYMAP LAYERS
Layer 0: Qwerty with mousekeys

Code: [Select]


,-----------------------------------------------------------.
|  `|  1|  2|  3|  4|  5|  6|  7|  8|  9|  0|  -|  =|Backspa|
|-----------------------------------------------------------|
|Tab  |  Q|  W|  E|  R|  T|  Y|  U|  I|  O|  P|  [|  ]|    \|
|-----------------------------------------------------------|
|CapsLo|  A|  S|  D|  F|  G|  H|  J|  K|  L|  ;|  '|Return  |
|-----------------------------------------------------------|
|Shift   |  Z|  X|  C|  V|  B|  N|  M|  ,|  ,|  /|Shift     |
|-----------------------------------------------------------|
|Ctrl |Gui |Alt |         Space         |Alt |Gui |Menu|Ctrl|
`-----------------------------------------------------------'
; = Fn0(to Layer 5)
/ = Fn1(to Layer 6)

Layer 1: Qwerty

Code: [Select]


,-----------------------------------------------------------.
|  `|  1|  2|  3|  4|  5|  6|  7|  8|  9|  0|  -|  =|Backspa|
|-----------------------------------------------------------|
|Tab  |  Q|  W|  E|  R|  T|  Y|  U|  I|  O|  P|  [|  ]|    \|
|-----------------------------------------------------------|
|CapsLo|  A|  S|  D|  F|  G|  H|  J|  K|  L|  ;|  '|Return  |
|-----------------------------------------------------------|
|Shift   |  Z|  X|  C|  V|  B|  N|  M|  ,|  ,|  /|Shift     |
|-----------------------------------------------------------|
|Ctrl |Gui |Alt |         Space         |Alt |Gui |Menu|Ctrl|
`-----------------------------------------------------------'

Layer 2: Colemak

Code: [Select]


,-----------------------------------------------------------.
|  `|  1|  2|  3|  4|  5|  6|  7|  8|  9|  0|  -|  =|Backspa|
|-----------------------------------------------------------|
|Tab  |  Q|  W|  F|  P|  G|  J|  L|  U|  Y|  ;|  [|  ]|    \|
|-----------------------------------------------------------|
|BackSp|  A|  R|  S|  T|  D|  H|  N|  E|  I|  O|  '|Return  |
|-----------------------------------------------------------|
|Shift   |  Z|  X|  C|  V|  B|  K|  M|  ,|  ,|  /|Shift     |
|-----------------------------------------------------------|
|Ctrl |Gui |Alt |         Space         |Alt |Gui |Menu|Ctrl|
`-----------------------------------------------------------'

Layer 3: Dvorak

Code: [Select]


,-----------------------------------------------------------.
|  `|  1|  2|  3|  4|  5|  6|  7|  8|  9|  0|  [|  ]|Backspa|
|-----------------------------------------------------------|
|Tab  |  '|  ,|  .|  P|  Y|  F|  G|  C|  R|  L|  /|  =|    \|
|-----------------------------------------------------------|
|BackSp|  A|  O|  E|  U|  I|  D|  H|  T|  N|  S|  -|Return  |
|-----------------------------------------------------------|
|Shift   |  ;|  Q|  J|  K|  X|  B|  M|  Wl  V|  Z|Shift     |
|-----------------------------------------------------------|
|Ctrl |Gui |Alt |         Space         |Alt |Gui |Menu|Ctrl|
`-----------------------------------------------------------'

Layer 4: Workman

Code: [Select]


,-----------------------------------------------------------.
|  `|  1|  2|  3|  4|  5|  6|  7|  8|  9|  0|  -|  =|Backspa|
|-----------------------------------------------------------|
|Tab  |  Q|  D|  R|  W|  B|  J|  F|  U|  P|  ;|  [|  ]|    \|
|-----------------------------------------------------------|
|CapsLo|  A|  S|  H|  T|  G|  Y|  N|  E|  O|  I|  '|Return  |
|-----------------------------------------------------------|
|Shift   |  Z|  X|  M|  C|  V|  K|  L|  ,|  ,|  /|Shift     |
|-----------------------------------------------------------|
|Ctrl |Gui |Alt |         Space         |Alt |Gui |Menu|Ctrl|
`-----------------------------------------------------------'

Layer 5: Mousekeys

Code: [Select]


,-----------------------------------------------------------.
|Esc| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Backspa|
|-----------------------------------------------------------|
|Tab  |MwL|MwU|McU|WwU|WwR|MwL|MwD|MwU|MwR|   |   |   |    \|
|-----------------------------------------------------------|
|CapsLo|   |McL|McD|McR|   |McL|McD|McU|McR|Fn0|   |Return  |
|-----------------------------------------------------------|
|Shift   |VoD|VoU|Mut|Mb2|Mb3|Mb2|Mb1|VoD|VoU|Mut|Shift     |
|-----------------------------------------------------------|
|Ctrl |Gui |Alt |         Mb1           |Alt |Gui |Menu|Ctrl|
`-----------------------------------------------------------'
Mc = mouse cursor
Mw = mouse wheel
Mb = mouse button
Vo = Volume, Mut = Mute

Layer 6: Cusorkeys

Code: [Select]


,-----------------------------------------------------------.
|Esc| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Backspa|
|-----------------------------------------------------------|
|Tab  |Hom|PgU| Up|PgU|End|Hom|PgD|PgU|End|   |   |   |    \|
|-----------------------------------------------------------|
|CapsLo|   |Lef|Dow|Rig|   |Lef|Dow| Up|Rig|   |   |Return  |
|-----------------------------------------------------------|
|Shift   |   |   |   |   |   |Hom|PgD|PgU|End|Fn1|Shift     |
|-----------------------------------------------------------|
|Ctrl |Gui |Alt |         Space         |Alt |Gui |Menu|Ctrl|
`-----------------------------------------------------------'



V-USB SUPPORT
You can also use this converter on ATmega(168/328) or arduino with V-USB instead of Teensy.
The converter on V-USB lacks some features now: USB NKRO and System/Media control.

To build a firmware use Makefile.vusb instead of Makefile.

Circuit:

Code: [Select]


V-USB Circuit
-------------
                +---+   +---------------+
USB            GND  |   |   ATmega168   |
===                 C3  |               |
5V <-------+--------+---|Vcc,AVCC       |        PS/2
           R1           |               |        ====
D- <----+--+-----R2-----|INT1        RXD|------->DATA
D+ <----|---+----R3-----|INT0        XCK|------->CLOCK
        Z1  Z2          |               |      ->5V
GND<----+---+--+--+-----|GND            |      ->GND
               |  |     |               |
               |  C2-+--|XTAL1          |
               |     X1 |               |
               +--C3-+--|XTAL2          |
                        +---------------+
R1:     1.5K Ohm
R2,R3:  68 Ohm
Z1,Z2:  Zenner 3.6V
C1,C2:  22pF
C3:     0.1uF
X1:     Crystal 20MHz(16MHz/12MHz)


This is my V-USB converter on breadboard.

[theferenc]

So with this, we could implement any minor changes in key layout we've done, prior to it even getting to the controller?

This is genius!

I've got a bolt modded model M that I split the backspace into 2 keys, and rearranged others (see link in sig, if you're curious).

If I'm reading this correctly, I could use this project to modify the keymap in the converter, thereby obviating the necessity of registry hacks or xmodmap or whatever. Is this correct?

If so, I might need to finally order a teensy.

[Soarer]

I like the github 404 :-p

(https://github.com/tmk/tmk_keyboard/ps2_usb/ should be https://github.com/tmk/tmk_keyboard/tree/master/ps2_usb, I think).

Nice work, again, hasu :-)

[hasu]

I've got a bolt modded model M that I split the backspace into 2 keys, and rearranged others (see link in sig, if you're curious).

If I'm reading this correctly, I could use this project to modify the keymap in the converter, thereby obviating the necessity of registry hacks or xmodmap or whatever. Is this correct?

I think so.
This converter allows you to remap scan code from PS/2 keyboard to any USB code. If your split 2 keys have different PS/2 scan code each, you can rearrange those keys as you like.
Using this converter, I think you will not need registry hacks and AHK for rearrangement of keys.

Get a Teensy and try this!
I need feedback, suggestions and advices to improve my project.

I like the github 404 :-p

(https://github.com/tmk/tmk_keyboard/ps2_usb/ should be https://github.com/tmk/tmk_keyboard/tree/master/ps2_usb, I think).

Nice work, again, hasu :-)

Thank you, Soarer.
I fixed it.

[theferenc]

Just to check, will this work with a teensy++, or just a teensy? I ask because the teensy is currently out of stock. I assume teensy only, so I guess I will just have to wait, which is a shame.

I'm definitely interested in trying this out and providing feedback. Especially since right now, the registry hack thing is only a viable solution for windows. This will make the keyboard work properly, regardless of physical system it is connected to.

Also, the split backspace does send distinct scan codes, so it theoretically should work.

Thanks, Hasu!

[hasu]

theferenc,

I believe it should work on Teensy++. Though I didn't confirm that.
My Teensy++ is located inside my HHKB and is not available for testing now.

Just to check, will this work with a teensy++, or just a teensy? I ask because the teensy is currently out of stock. I assume teensy only, so I guess I will just have to wait, which is a shame.

I'm definitely interested in trying this out and providing feedback. Especially since right now, the registry hack thing is only a viable solution for windows. This will make the keyboard work properly, regardless of physical system it is connected to.

Also, the split backspace does send distinct scan codes, so it theoretically should work.

Thanks, Hasu!

[symphonic1985]

I really love this idea. I have to work on Ubuntu at work where I have much less experience with Autohotkey type things. I'd much rather do things in hardware than have to learn lots of different remapping and hotkey systems.

Once the guilt from all my keyboard purchases has worn off I think that I'll probably grab a teensy to play with this kind of awesomeness.

[sixty]

Great work! I would love to try it, sadly Teensy is entirely sold out everywhere in Germany since everyone uses it for PS3 piracy.

[Soarer]

Great work! I would love to try it, sadly Teensy is entirely sold out everywhere in Germany since everyone uses it for PS3 piracy.

You could try one of these: http://cgi.ebay.co.uk/ws/eBayISAPI.dll?ViewItem&item=280606391720&ssPageName=STRK:MEWAX:IT

It's one of the few Teensy alternatives that actually looks OK Many of them are copies of the original Teensy, not the 2.0 version with atmega32u4 chip. I've just ordered one to test it out... we'll see...

[Soarer]

Hasu, the PrintScreen shouldn't be handled as a sequence, but the fix is easy...

code E0 12 should be ignored
code E0 7C should map to PrtSc HID code

The E0 12 is a fake shift for when E0 is not handled, e.g. a computer that thinks it has an 84 key keyboard attached. Since you handle E0, you don't need to handle the PrtSc sequence specifically. In fact, it makes a bug when PrtSc is held down and repeats! (also maybe when shift is held?)

Basically, this means it can be handled the same as any other normal key :-)

[hasu]

Soarer, thank you for your feedback!

I have fixed the problem you described.

It took some time to check out complex behavior of PS/2 keyboard.
The PS/2 scan code(set 2) is chaos I am not sure why they do like that even though they needed backward compatibility.



This is my result of research.

Code: [Select]

/*
 * PS/2 Scan Code Set 2: Exceptional Handling
 *
 * There are several keys to be handled exceptionally.
 * The scan code for these keys are varied or prefix/postfix'd
 * depending on modifier key state.
 *
 * References:
 *     http://www.microsoft.com/whdc/archive/scancode.mspx
 *     http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/scancode.doc
 *
 *
 * Insert, Delete, Home, End, PageUp, PageDown, Up, Down, Right, Left:
 *     Num Lock: off
 *     modifiers | make                      | break
 *     ----------+---------------------------+----------------------
 *     Ohter     |                    <make> | <break>
 *     LShift    | E0 F0 12           <make> | <break>  E0 12
 *     RShift    | E0 F0 59           <make> | <break>  E0 59
 *     L+RShift  | E0 F0 12  E0 F0 59 <make> | <break>  E0 59 E0 12
 *
 *     Num Lock: on
 *     modifiers | make                      | break
 *     ----------+---------------------------+----------------------
 *     Other     | E0 12              <make> | <break>  E0 F0 12
 *     Shift'd   |                    <make> | <break>
 *
 *     Handling: ignore these prefix/postfix codes
 *
 *
 * Keypad-/:
 *     modifiers | make                      | break
 *     ----------+---------------------------+----------------------
 *     Ohter     |                    <make> | <break>
 *     LShift    | E0 F0 12           <make> | <break>  E0 12
 *     RShift    | E0 F0 59           <make> | <break>  E0 59
 *     L+RShift  | E0 F0 12  E0 F0 59 <make> | <break>  E0 59 E0 12
 *
 *     Handling: ignore these prefix/postfix codes
 *
 *
 * PrintScreen:
 *     With hoding down modifiers, the scan code is sent as following:
 *
 *     modifiers | make         | break
 *     ----------+--------------+-----------------------------------
 *     Other     | E0 12  E0 7C | E0 F0 7C  E0 F0 12
 *     Shift'd   |        E0 7C | E0 F0 7C
 *     Control'd |        E0 7C | E0 F0 7C
 *     Alt'd     |           84 | F0 84
 *
 *     Handling: ignore prefix/postfix codes and treat both scan code
 *               E0 7C and 84 as PrintScreen.
 *
 * Pause:
 *     With hoding down modifiers, the scan code is sent as following:
 *
 *     modifiers | make(no break code)
 *     ----------+--------------------------------------------------
 *     no mods   | E1 14 77 E1 F0 14 F0 77
 *     Control'd | E0 7E E0 F0 7E
 *
 *     Handling: treat these two code sequence as Pause
 *
 */


[Soarer]

Yes, that's how I handle all of those, in fact the only one that actually needs special code is Pause. (As far as I know so far, anyway!)

All very convoluted, and tedious to check them all, but mostly ignoring them seems to be the right thing to do!

[hasu]

Great work! I would love to try it, sadly Teensy is entirely sold out everywhere in Germany since everyone uses it for PS3 piracy.

You could try one of these: http://cgi.ebay.co.uk/ws/eBayISAPI.dll?ViewItem&item=280606391720&ssPageName=STRK:MEWAX:IT

It's one of the few Teensy alternatives that actually looks OK Many of them are copies of the original Teensy, not the 2.0 version with atmega32u4 chip. I've just ordered one to test it out... we'll see...

Teensy is a great platform for easy & rapid development.
But I need more option for hardware. I mean my next target will be V-USB stack with ATmega, tiny is too tight for my firmware.

This is my testbed of V-USB using arduino I setup today.

[theferenc]

hasu, is it possible, using this method, to map the extra keys on a terminal emulator that are usually just ignored by converters? Looking at your keymap layers, it appears that I would just have to add in the extra keys by hand, but that's no big deal for me.

Honestly, I don't really care what the keys are supposed to do, as long as they send unique scan codes from the teensy to the workstation.

[hasu]

theferenc,

I don't know the "terminal emulator" keyboard at all, in particular its scan codes.

My converter supports PS/2(AT) signaling and scan code set 2, if the keyboard uses these you can map easily by just editing keymap.c.
But if scan codes for the extra keys are very different from PS/2 scan code set 2, you will have to write some codes in C to decode them.

[theferenc]

It's the 122 key IBM keyboards. Hopefully it won't be too complicated to decode them. Low level C is sort of my area (I'm a systems coder), so that part, at least, won't be an issue.

If I get it working, I will definitely pass it along.

[kishy]

122 emulator, yeah? There are two varieties AFAIK: ones that send modifier+another key, and ones that send mostly unique codes.

The latter is what sounds like it could be made to work with this doohicky. The first is probably not worth bothering with.

The real terminal keyboards are all Set 3, of course.

[theferenc]

I've got a Teensy++ on the way. So we'll also see if it would be a straight load on that, or if any modifications will be necessary. Based on specs, it should just work, since I don't need many inputs.

[REVENGE]

How hard would it be to change the firmware to accept an arbitrary input protocol (like terminal or XT for example)?

[hasu]

kishy,
I have read "USB converter" page in your signature, is dfj's converter firmware available to public? I couldn't found it by my quick search.
It must be very useful to us if its source code is also available.

REVENGE,
I think it depends on whether you could find enough documentation to implement the protocol.
In my case, PS/2 and ADB have many good resources on the net. Thanks to this I could write initial code and see scan codes from keyboard in first several hours, though
I used several days to research and understand the protocol.

[hasu]

kishy,
I have read "USB converter" page in your signature, is dfj's converter firmware available to public? I couldn't found it by my quick search.
It must be very useful to us if its source code is also available.

I found the answer in dfj's recent post.

Both teensy implementations are not-quite released as open-source yet,  but can be had from the folks on the IRC channel #geekhack if you can  stand it there.

[theferenc]

hasu,

Based on the code and the layout of the KEYMAP macro, it would appear there is a specific ordering to the keys. I assume this 8x22 map comes from the normal matrix of a keyboard somehow.

Basically, if I'm adding a key (I use a 102 key keyboard, as backspace has been split from a single key to 2 keys), do I have to put it in a very specific location, or can I simply replace one of the KB_NO locations, so long as I pick an appropriate name?

Any help would be appreciated!

[hasu]

theferenc,
At first , You need to know scan code for the key. once you know that, just replace KB_NO with matrix position of the code as you said.
Probably You can see the scan code in debug console if your keyboard sends scan code Set2. Run PJRC's hid_listen.exe then press LControl+RShift+d in your target keyboard.


Following is how the converter maps PS/2 codes to USB codes.

This converter stores a scan code from keyboard as a bit in matrix(uin8_t[32] array) in following rule.
For example 'A'(0x1C) is stored like: matrix[0x1C>>3] |= 1<<(0x1C&0x07);
0xE0 prefix code like'PG UP'(0xE0, 0x7D): matrix[(0x7D|0x80)>>3] |= 1<<(0x7D&0x07);
See matrix.c for details.

Then the matrix is mapped to USB code in keymap.c.
'A' is identify as 'K1C' and 'PG UP' as 'KFD'(0x7D|0x80=0XFD) in KEYMAP macro.

PS/2 scan code Set2
http://www.computer-engineering.org/ps2keyboard/scancodes2.html

[intealls]

Awesome work hasu!

I just wanted to quickly describe how to add support for the Europe 2 key (right of the shift key), in case people have trouble understanding shift operations and the like. Add 'K61,' next to 'K12,' on line 24. Change the second 'KB_NO,' on line 39 to  'KB_##61,'.

Then configure your keymaps to use NONUS_BSLASH where the Europe 2 key is located. If you want, you could add an extra #define in usb_keycodes.h like '#define KB_NUBS KB_NONUS_BSLASH', to keep everything nice and tidy in your keymap configuration.

[hasu]

intealls,

Thank you for your nice feedback!
I added short name you suggested and push it to github.


And I'd like to added useful resources for people want to define their own keymaps.

USB HID to PS/2 Translation Table:
You can see PS/2 scan codes and how to handle it in Windows.
http://www.microsoft.com/whdc/archive/scancode.mspx

HID usage table:
You can see all HID Usage IDs(USB keycodes).
http://www.usb.org/developers/hidpage#HID_Usage

[hasu]

V-USB is supported now.
Currently the converter on V-USB lacks some features: USB NKRO and System/Media control.

[doublethink]

Hasu,

This is very impressive.  What about designing a PCB on http://batchpcb.com and then keeping a list of parts from a distributor so people could build their own?

The advantage would be that you could have female ps/2 soldered right to the board, and we could size it to matchup with a plastic housing of some sort. ^_^

[doublethink]

Something like this guy:

http://www.pactecenclosures.com/product-detail.php?classid=31&seriesid=64

They have different sizes, etc.  Mouser is franchise for that company.

[intealls]

I've been using this for a couple of weeks now and I have to say it works great! The only problem I have encountered is that the adapter didn't work properly with my Model M's, after adding the 1K pull-up resistor to the data line (as described in the ADB-USB adapter thread) it works perfect! Typing on one now, feels kind of awesome having a fully programmable M without any hardware modifications. Thanks hasu!

[hasu]

intealls,
Thanks for your feedback! In particular, I'm happy to hear positive one
It seems we had better have pull-up resistors in case. Internal pull-up is not enough


doublethink,
I have not an experience on PCB design, but I'm planning to learn it using Kicad.
Thanks for suggestion.