summaryrefslogtreecommitdiff
path: root/README
blob: d85f512c714000fd1337723fa8bc34dfa800ee21 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
t.m.k. Keyboard Firmware
========================
This is keyboard firmware for Teensy(AVR USB MCU) and V-USB board.

source code repository:
http://github.com/tmk/tmk_keyboard

This firmware is used in following projects:
HHKB mod:   http://geekhack.org/showwiki.php?title=Island:12047
Macway mod: http://geekhack.org/showwiki.php?title=Island:11930
PS2 to USB: http://geekhack.org/showwiki.php?title=Island:14618
ADB to USB: http://geekhack.org/showwiki.php?title=Island:14290

The project is heavily based on PJRC USB Keyboard/Mouse Example and
owes a debt to preceding keyboard firmware projects.
http://www.pjrc.com/teensy


Features
--------
Mouse key
    control mouse cursor from keyboard.
System Control Key
    Power Down, Sleep, Wake Up & USB Remote Wake up
Media Control Key
    Volume Down/Up, Mute
USB NKRO
    send 120 keys(+ 8 modifiers) at most simultaneously.
PS/2 mouse support
    integrate PS/2 mouse(TrackPoint) into keyboard as composite device.


Limitations
-----------


Files & Directories
-------------------
Target:
hhkb/                           keyboard controller for PFU HHKB pro
macway/                         keyboard controller for Macway mod
ps2_usb/                        PS2 to USB keyboard converter
adb_usb/                        ADB to USB keyboard converter

USB Protocol Stack:
pjrc/                           PJRC  USB stack
vusb/                           V-USB USB stack
ps2.[ch]                        PS/2 protocol
adb.[ch]                        ADB protocol


Build
-----
To compile needs AVR GCC, AVR Libc and GNU make.
You can use WinAVR on Windows.  http://winavr.sourceforge.net/

$ cd <target>
$ make

The firmware will be compiled as a file tmk_<target>.hex.


Build your own firmware
-----------------------
Copying exsistent target(macway) is easy way.
1. Copy contens of macway/ to your own target directory.
2. Edit Makefile. See next section.
3. Edit config.h. See next section.
4. Edit matrix.c. You will need to fix followings at least.
     matrix_init()
     matrix_scan()
     read_col()
     unselect_rows()
     select_row()
5. Edit keymap.c. NOTE: It is not final design and a bit messy.
   You will need to fix followings at least.
     KEYMAP
     fn_layer[]
     fn_keycode[]
     keymaps[]
6. Build.

If you have a build error like following, comment out "--relax" option in Makefile.common.
    (.vectors+0x30): relocation truncated to fit: R_AVR_13_PCREL against symbol `__vector_12'


Build Options
-------------
<target>/Makefile:
1. Set target name for your firmware.
     TARGET = tmk_<target>
2. Choose a MCU and its frequency.
     MCU = atmega32u4       # Teensy 2.0
     #MCU = at90usb1286      # Teensy++ 2.0
     F_CPU = 16000000
3. Choose optional modules as needed. Comment out to disable optional modules.
     MOUSEKEY_ENABLE = yes	# Mouse keys
     PS2_MOUSE_ENABLE = yes	# PS/2 mouse(TrackPoint) support
     EXTRAKEY_ENABLE = yes	# Enhanced feature for Windows(Audio control and System control)
     NKRO_ENABLE = yes		# USB Nkey Rollover

<target>/config.h:
1. USB vendor/product ID and device description
     #define VENDOR_ID       0xFEED
     #define PRODUCT_ID      0xBEEF
     /* device description */
     #define MANUFACTURER    t.m.k.
     #define PRODUCT         Macway mod
     #define DESCRIPTION     t.m.k. keyboard firmware for Macway mod
2. Keyboard matrix configuration
     #define MATRIX_ROWS 8
     #define MATRIX_COLS 8
     #define MATRIX_HAS_GHOST
3. Mouse keys configuration if needed.
4. PS/2 mouse configuration if needed.


Debuging & Rescue
-----------------
Use PJRC's hid_listen.exe to see debug messages.
Press <COMMAND> + H to debug menu. 
(see config.h for <COMMAND> key combination.)

Pressing any 3 keys when connected enables debug output.
Pressing any 4 keys when connected makes bootloader comes up.


Projects related
----------------
PJRC USB Keyboard/Mouse Example
    http://www.pjrc.com/teensy/usb_keyboard.html
    http://www.pjrc.com/teensy/usb_mouse.html
kbupgrade
    http://github.com/rhomann/kbupgrade
    http://geekhack.org/showwiki.php?title=Island:8406
c64key
    http://symlink.dk/projects/c64key/
rump
    http://mg8.org/rump/
    http://github.com/clee/rump
dulcimer
    http://www.schatenseite.de/dulcimer.html
humblehacker-keyboard
    http://github.com/humblehacker
    http://www.humblehacker.com/keyboard/
    http://geekhack.org/showwiki.php?title=Island:6292
ps2avr
    http://sourceforge.net/projects/ps2avr/


EOF