qmk_firmware/ps2_usb/README

PS/2 to USB keyboard converter
==============================

This firmware converts PS/2 keyboard protocol to USB.


Demostration build
------------------
In this demo build, you can try several layouts,
mouse keys and USB NKRO.

Special keys:
    Magic+0:    Qwerty with mouse keys(default)
    Magic+1:    Qwerty
    Magic+2:    Colemak
    Magic+3:    Dvorak
    Magic+4:    Workman
    Magic+N:    toggles NKRO/6KRO(6KRO by default)
    Magic+Esc:  sends Power Event
    where Magic=(LShift+RShift) or (LControl+RShift)

Keybinds:
    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)

    Fn2+(esdf): Mouse key move(invert T cursor)
    Fn2+(qwrt): Mouse wheel(left,down,up,right)
    Fn2+space:  Mouse button1
    Fn2+(,./):  Media control(Volup, Voldown, Mute)
    where Fn0=;, Fn1=/, Fn2=a


Features
--------
Mouse keys
    You can emulates mouse move and button click using keyboard.
System/Media control
    You can sends Power event, Volume down/up and Mute.
USB NKRO(actually 120KRO+8Modifiers)
    You can tolggles NKRO/6KRO.(Not tested on Mac.)
Keymap customization
    You can customize keymaps easily by editing source code.


Build for Teensy
----------------
0. Connect PS/2 keyboard to Teensy by 4 lines(Vcc, GND, Data, Clock).
1. Define following macros for PS/2 connection in config_pjrc.h:
   PS2_DATA_PORT
   PS2_DATA_PIN
   PS2_DATA_DDR
   PS2_DATA_BIT
   PS2_CLOCK_PORT
   PS2_CLOCK_PIN
   PS2_CLOCK_DDR
   PS2_CLOCK_BIT
2. Edit Makefile for build options and MCU setting.
2. make
3. program Teensy.
   http://www.pjrc.com/teensy/loader.html


Build for V-USB
---------------
0. Build V-USB controller board and connect PS/2 keyboard.
1. Define macros in config_vusb.h if needed.
2. Edit Makefile.vusb for build options and MCU setting.
3. make -f Makefile.vusb
4. program your V-USB controller.


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)


Keymap
------
You can change a keymap by editing code of keymap.c like following.
How to define the keymap is probably obvious. You can find  key
symbols in usb_keycodes.h.
If you want to define more than one keymap, see hhkb/keymap.c and
macway/keymap.c as examples. To define keymap(layer) switching may
needs a bit of your effort at this time.

    /* Default Layer: plain keymap
     * ,---.   ,---------------. ,---------------. ,---------------. ,-----------.     ,-----------.
     * |Esc|   |F1 |F2 |F3 |F4 | |F5 |F6 |F7 |F8 | |F9 |F10|F11|F12| |PrS|ScL|Pau|     |Pwr|Slp|Wak|
     * `---'   `---------------' `---------------' `---------------' `-----------'     `-----------'
     * ,-----------------------------------------------------------. ,-----------. ,---------------.
     * |  `|  1|  2|  3|  4|  5|  6|  7|  8|  9|  0|  -|  =|Backspa| |Ins|Hom|PgU| |NmL|  /|  *|  -|
     * |-----------------------------------------------------------| |-----------| |---------------|
     * |Tab  |  Q|  W|  E|  R|  T|  Y|  U|  I|  O|  P|  [|  ]|    \| |Del|End|PgD| |  7|  8|  9|   |
     * |-----------------------------------------------------------| `-----------' |-----------|  +|
     * |CapsLo|  A|  S|  D|  F|  G|  H|  J|  K|  L|  ;|  '|Return  |               |  4|  5|  6|   |
     * |-----------------------------------------------------------|     ,---.     |---------------|
     * |Shift   |  Z|  X|  C|  V|  B|  N|  M|  ,|  ,|  /|Shift     |     |Up |     |  1|  2|  3|   |
     * |-----------------------------------------------------------| ,-----------. |-----------|Ent|
     * |Ctrl |Gui |Alt |         Space         |Alt |Gui |Menu|Ctrl| |Lef|Dow|Rig| |      0|  .|   |
     * `-----------------------------------------------------------' `-----------' `---------------'
     */
    KEYMAP(
    ESC, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12,           PSCR,SLCK,BRK,          PWR, F13, F14,
    GRV, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, BSPC,     INS, HOME,PGUP,    NLCK,PSLS,PAST,PMNS,
    TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS,     DEL, END, PGDN,    P7,  P8,  P9,
    CAPS,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,     ENT,                         P4,  P5,  P6,  PPLS,
    LSFT,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,          RSFT,          UP,           P1,  P2,  P3,
    LCTL,LGUI,LALT,          SPC,                     RALT,RGUI,APP, RCTL,     LEFT,DOWN,RGHT,    P0,       PDOT,PENT
    ),


Multimedia keys
---------------
Following lists PS/2 special keys supported by Windows.
http://msdn.microsoft.com/en-us/windows/hardware/gg463372.aspx

Key                         PS/2(Set2)      HID
---------------------------------------------------
System Power                E0 37           01 0081
System Sleep                E0 3F           01 0082
System Wake                 E0 5E           01 0083
System Mute                 E0 23           0C 00E2
Volume Up                   E0 32           0C 00E9
Volume Down                 E0 21           0C 00EA
Scan Next Track             E0 4D           0C 00B5
Scan Previous Track         E0 15           0C 00B6
Stop                        E0 3B           0C 00B7
Play/Pause                  E0 34           0C 00CD
Media Select                E0 50           0C 0183
Mail                        E0 48           0C 018A
Calculator                  E0 2B           0C 0192
My Computer                 E0 40           0C 0194
WWW Search                  E0 10           0C 0221
WWW Home                    E0 3A           0C 0223
WWW Back                    E0 38           0C 0224
WWW Forward                 E0 30           0C 0225
WWW Stop                    E0 28           0C 0226
WWW Refresh                 E0 20           0C 0227
WWW Favorites               E0 18           0C 022A


EOF