Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Git repository: https://github.com/BASLQC/ibm-wheelwriter-usb-controller/
A drop-in Teensy USB replacement controller for the aging IBM Model M, F/AT/XT/Terminal, and Wheelwriter Buckling Spring Keyboards.
The IBM Buckling Spring keyboards are widely regarded as the best keyboards ever built. They were designed to emulate the feel and sounds of an IBM Selectric typewriter, and were bundled with every IBM PC (AT, XT, PS/2) as well as IBM Terminals.
However, the Model M's PS/2 keyboard socket is an aging format, long since superseded by the all-purpose USB port. You need an active PS/2 converter to USB, a passive one will not work. The Model Ms are getting rarer and more expensive with every passing year. And that's if your keyboard is lucky enough to have a PS/2 socket:
- The AT Model F keyboards require a special adapter to PS/2 jacks. They also have a secret full NKRO ability, that simply cannot be realized through the PS/2 jack.
- The Model M Terminal RJ-45 keyboards (which can be found for dirt cheap at $10-25) use an RJ-45 plug that is totally unusable with modern computers and cannot be converted.
- The IBM Wheelwriter Series of typewriters don't even have keyboard output of any kind. They're typewriters.
Most importantly, the old keyboard controller inside is beginning to show it's age, and the keymaps are not customizable.
Thus, this project aims to build, test, and mass produce a Teensy/Arduino USB Keyboard controller, for use as a drop in replacement into any IBM Buckling Spring keyboard. Not to mention that a modern controller board removes all the overhead of a PS/2 converter, and allows customizable key layouts (especially useful if you have a F13-F24 row!).
This way, you can buy a dirt cheap RJ-45 IBM Terminal keyboard for $10-25, and pop in this $40 USB controller board, giving you a buckling spring keyboard for half the price of a comparable Model M.
A custom USB Controller board for the Model M ranks as one of the top 10 most wanted mods for the IBM Buckling Spring Keyboards.
The user Phosphorglow from Deskthority made a similar complete controller (with matrix) for the IBM Model M. It's just a matter of wiring together the membrane and a Teensy dev chip, using a breadboard and off-the-shelf Trio-mate membrane socket. You can even set your own custom keys by modifying the firmware.
I modified his controller to work with a gutted IBM Personal Wheelwriter 2, that I bought for $10 and gutted for an Accurate Emulation Arcade.
Model M and Wheelwriter Keyboards
This controller is for IBM Buckling Spring keyboards that use a membrane Trio-mate connector. No soldering required, just unplug it from the old controller and plug it into our USB Controller.
- IBM Model M (PS/2 Port) - The standard Model M keyboard that everyone knows and loves. It was bundled with the IBM Personal/System 2.
- IBM Model M (RJ-45 Port) - A Terminal variant of the Model M which looks exactly the same, but has a RJ-45 jack that cannot be used with a computer, and has no Caps Lock/Num Lock LEDs. But just plug in this USB Controller and it's rescued from obsolescence. You can usually find one of these for $10-25, since nobody wants them.
IBM Wheelwriter - The best typewriter ever made in the 80's and
90's. It's keyboard uses the same kind of Trio-mate membrane
connector, with 14 pins and 8pins (and two 15 pin sockets due to
useless loopback leads). I grabbed a broken Wheelwriter, stripped
out the broken parts, and used the massive space within as a base
for an Accurate Emulation
I could even convert it into a gaming rig case, with lots of room;
and put the monitor on top of it.
- PLEASE, FOR THE LOVE OF GOD, DO NOT RIP OPEN A WORKING WHEELWRITER. If you find a working one at a thrift shop, sell it on eBay for $100-250. Don't reduce the supply of these valuable typewriters. You can get a broken one for dirt cheap on eBay, and the keyboard will always work, regardless of whether the carriage is broken or the silicon is toast.
Basically, all we do is wire up the membrane to the Teensy. Then we upload Soarer's keyboard controller and a custom configuration to the Teensy. Yes, that's all you need to do; the magic of the Arduino.
The membrane on the IBM Model M and Wheelwriter keyboards use Flexible
Flat Cables for
output. They are
0.1 in (2.54 mm) in spacing, perfect for breadboards
or perf boards!)
There's no need to desolder the FFC sockets from the original controller, just buy some new ones. These sockets are known as "Trio-Mate connectors", and are extremely easy and cheap to find.
The components should cost about $40:
- $20 - Teensy 2.0 (24 usable pins) - A cheap, tiny, and simple microcontroller
board. The Teensy is the bread and butter of custom keyboard makers, since it can
report to the computer as a USB HID device, using Soarer's Keyboard Controller.
- $24 (or $8-10 for clones)) - Arduino Micro (24 usable pins](https://geekhack.org/index.php?topic=53444.msg1242849#msg1242849)) - Unlike the first Arduino, this rendition uses the same Atmel microprocessor as the Teensy 2.0, so it is able to report as a USB HID device. The Arduino Micro is Open Source hardware, which makes Chinese-made clones very prevalent and affordable. Of course, the flip side is that e-packet shipping can take a month, and US stockpiles only buy the $24 genuine edition. So if you're impatient, stick with the Teensy, but if you're building in volume, this is the right board for you.
- $11-15 - Teensy LC (24 usable pins) - These Teensy 3.1 ARM-based boards are half the price of a Teensy 2.0. However, Soarer's Keyboard Controller has not been and cannot be ported to this board, since the original author is MIA and no source code was posted. You will have to use TMK or Nasu's firmware instead, which are significantly less intuitive to configure.
- $2 - Trio-mate 16pin (2.54mm Pitch)
6-520315-6- The keyboard membrane connects to the controller using these common, cheap Trio-Mate sockets. You can find them on Mouser: 315 / 415 or RS-Components.
6-520315series has conveniently bent pins that stick well to breadboards and make soldering to perfboards easier.
- There is also the
6-520415-6series, which has straight pins that are a bit more inconvenient to solder (and bounce right off breadboards). However, they are only $0.74 apiece, compared to $2.13 for
315-6bent pins. That's a better deal for mass production.
- The socket is one pin bigger than you need, so just push the ribbon cable toward the left and leave the 16th pin unconnected. Unfortunately, even though the IBM Keyboards use 15-pin, TE Connectivity no longer produces them. Mouser's lead time for them is 17 weeks! You might as well use a 16-pin socket instead, and just leave the extra pin unconnected. Alternatively, if you have a Wheelwriter, you can slice off the first (unused) pin and connect it to a 14-pin socket.
- $2 - Triomate 8pin (2.54mm Pitch) - The second segment of the
keyboard plugs into an 8-pin Trio-mate socket. These come in
5-520314-8non-locking variants. Note that on most Wheelwriters, there are 7 extra pins on the right which uselessly loop back. If you don't want to cut them off, buy a second 16-pin instead of an 8-pin socket.
Electronics - For quick and dirty prototyping, I first designed
and debugged the setup on a solderless breadboard. Later on, I can
use Adafruit's solder board, or I can get a PCB printed for $9
- $5 - Breadboard - A simple plastic setup where all the
vertical wires are connected. Unfortunately, the Trio-mate
connectors have very short header pins, so use some kind of IC
Socket to raise them up.
- $5 - Adafruit PCB Breadboard (Alternative) - A more permanent, thinner, professional looking PCB-style breadboard, where you solder in the wires. All the thin permanence of a PCB, with the freedom of a solderless breadboard.
- $9 apiece - Custom-printed PCB (Alternative) - This is beyond my ability, but you can send a PCB design to small-run manufacturers for resale. I might actually try to sell some IBM Model M USB controllers if I figure everything out. Though it might just be better to use the Adafruit PCB, since the wiring is so simple...
- Breadboard Jumper Wires - Easy to use; just plug them in and go.
- Resistors - Not sure how many, but these are used to modify the strength of electronic signals.
- $5 - Breadboard - A simple plastic setup where all the vertical wires are connected. Unfortunately, the Trio-mate connectors have very short header pins, so use some kind of IC Socket to raise them up.
Plugging it in
Photo Credit: Sethstorm, should probably make my own
The ActionWriter is compatible with this guide. Shown above is the connection to a Teensy 2.0 as well as an illustration of the importance of properly planning breadboard/PCB layouts. Thinking harder could have significantly reduced the cabley mess pictured.
Teensy 2.0++ Pinout:
(to the cable socket, in left to right order)
Strobe pins, 13 pin strip (1 = leftmost pin as pictured above) 1 : D0 2 : D1 3 : D2 4 : D3 5 : D4 6 : C0 7 : C1 8 : C2 9 : C3 10: C4 11: C5 12: C6 13: C7 Sense pins, 8 pin strip (1 = left most pin) 1: F0 2: F1 3: F2 4: F3 5: F4 6: F5 7: F6 8: F7
Teensy 2.0 Pinout
Since I only had a Teensy 2.0 on hand (which has fewer pins), I had to make do with this layout:
1: B0 2: B1 3: B2 4: B3 5: B7 6: D0 7: D1 8: D2 9: D3 10: C6 11: C7 12: B4 13: D7 Sense pins, 8 pin strip (1 = left most pin) 1: F0 2: F1 3: F4 4: F5 5: F6 6: F7 7: B6 8: B5
Since the Teensy 2.0 is very short, some pins are placed in inconvenient locations. I simply solder a header pin pointing up, and use a F-M jumper pin to
Creating and Flashing the Teensy Firmware
Set up Teensy Loader
- First, set up the Teensy loader. It works on Windows, Mac OS X, and Linux.
- Plug in the Teensy with a Mini-USB cable.
- Start the Teensy Loader.
- Make sure to run as root, with
- Press the button on the Teensy to enter bootloader mode.
Install Soarer's Controller
- In the Teensy Loader, click the Open HEX File Button.
- Select the right HEX file for your Teensy Variant:
- Teensy 2.0:
- Teensy 2.0++:
- Click the Program button.
- Click the Restart button.
Configure Soarer's Controller
First, git clone this repository.
- From the
tools/folder, extract the binaries and put them in the
- Then, go to the
config/folder. Choose a config to use, and modify them if necessary.
- Finally, send a config over to the teensy. For example, we will use
Make sure to run all commands as root, with
sudo ./scas ww2-teensy2plus.sc output.scb sudo ./scwr output.scb
Keyboard Configs to use
I've produced some keyboard configs for various types and keyboards to work with:
- IBM Model M
- IBM Personal Wheelwriter 2/1000
- IBM Wheelwriter 3
- IBM Wheelwriter 5
Sethstorm from Geekhack already made a Wheelwriter to Teensy Matrix map forSoarer's Firmware here. The ActionWriter is not identical to the Wheelwriter but there are enough similarities that this template will need only minimal tweaking for use on ActionWriters as well.
- First, install the Teensy Loader, and check if you can load firmware to the Teensy.
- Next, download and extract a copy of Soarer's Firmware. Just paste this as the configuration and go.
# # Wheelwriter 5 Matrix (ISO Enter) # A sane, yet minimalist layout. # # Layout Notes: # Layout mostly follows AT(Ctrl between Tab/Left Shift, Caps Lock below Right Shift) aside from ISO Enter/F11/F12. # # Top two keys in the 5-key vertical block are PgUp/PgDn respectively. # Bottom two keys in the 5-key vertical block are F11/F12 respectively. # # The middle key in the 5-key vertical block on the right can be used as follows: # [Modifier]-WASD : Cursor keys (Up/Left/Down/Right) # [Modifier]-[Number key] : Equivalent numpad key # [Modifier]-[Backspace] : Del (for those wishing to perform Ctrl-Alt-Del, use Ctrl-Alt-Modifier-Backspace) # [Modifier]-[PgDn] : Left Win/GUI key # [Modifier]-[`] : Escape key # matrix scanrate 1 debounce 5 blocking 0 sense PF0 PF1 PF2 PF3 PF4 PF5 PF6 PF7 strobe PD0 UNASSIGNED UNASSIGNED UNASSIGNED UNASSIGNED UNASSIGNED UNASSIGNED UNASSIGNED LALT strobe PD1 F10 F7 F1 F3 F4 F5 F11 SPACE strobe PD2 F9 F8 F2 UNASSIGNED TAB F6 LCTRL CAPS_LOCK strobe PD3 UNASSIGNED UNASSIGNED UNASSIGNED UNASSIGNED UNASSIGNED UNASSIGNED UNASSIGNED LSHIFT strobe PD4 UNASSIGNED A BACK_QUOTE 1 Q UNASSIGNED Z 8 strobe PC0 UNASSIGNED S UNASSIGNED 2 W UNASSIGNED X I strobe PC1 UNASSIGNED D UNASSIGNED 3 E UNASSIGNED C K strobe PC2 G F 5 4 R T V B strobe PC3 H J 6 7 U Y M N strobe PC4 UNASSIGNED K EQUAL_SIGN 8 I RIGHT_BRACE COMMA I strobe PC5 UNASSIGNED L 3 9 O 5 PERIOD 6 strobe PC6 QUOTE SEMICOLON MINUS 0 P LEFT_BRACE BACKSLASH SLASH strobe PC7 UNASSIGNED FN2 BACKSPACE PAGE_UP PAGE_DOWN 6 ENTER F12 end macroblock endblock layerblock FN2 2 endblock remapblock layer 2 W UP A LEFT S DOWN D RIGHT BACKSPACE DELETE BACK_QUOTE ESC PAGE_DOWN LGUI 1 PAD_1 2 PAD_2 3 PAD_3 4 PAD_4 5 PAD_5 6 PAD_6 7 PAD_7 8 PAD_8 9 PAD_9 0 PAD_0 endblock
If I felt like mass-producing these Model M USB controller boards, I could choose to hand-wire and solder onto a bunch of Adafruit PCB Breadboards. One great coincidental feature of these breadboards is that they slide right into the existing Model M standoffs.
Alternatively, I could have silicon PCB boards with the wires custom printed. This way, I don't have to use any large wires, and it takes less work. Just solder in the Triomates, plug in a Teensy with header, and you're good to go.
I bet they will be popular around geekhack for a definitive and easy USB conversion for IBM Model M devices.
IBM Model F
The IBM Model F does not use a flat membrane Trio-mate connector, unlike the Model M and Wheelwriter boards. Unfortunately, it's keyboard ribbon is soldered directly to the board itself.
XWhatit has a Grand Unified IBM Capsense USB Controller board just for this purpose. Just desolder the Model F membrane connector, solder it to this connector, and you're done. Though that's if you can even obtain one, or if you can build one (through the difficult processor of soldering tiny resistors).
There has to be a Teensy-based Alternative... It replaces all the little electronics with just one $15 board.
- Should be very similar to the Retroconnector, just using a Teensy 2.0 instead, and Triomate sockets.
Advanced NKRO Mod
The earliest IBM Buckling Spring keyboards, the Model F, had full NKRO; you could press every key on the keyboard and it would register. (nowadays, it requires this USB controller to unlock that ability)
Unfortunately, with the Model M keyboard, IBM decided to cut costs and only allow two to three characters to be printed at a time, regardless of how many keys you press.
While most typists won't notice the difference, the lack of NKRO can hamper the fastest typists. NKRO is also incredibly important for gamers, who use the WASD combination to move around.
If you already have a Model M, and really want to get deep into the workings of the keyboard for a difficult, but rewarding mod; the No-key RollOver Mod (NKRO) is for you. But if you're just a random guy wanting a buckling spring keyboard with NKRO, just buy a Terminal Model F RJ-45 board, and drop in our USB Controller.
- Deskthority Forums - Model M Matrix Teensy
- Deskthority Forums - Matt3o: Workshop Threads
- Deskthority Forums - Soarer's Controller
- Deskthority Forums - Need a part for a connector on IBM Model M Controller Board
- Deskthority Forums - Converting IBM Wheelwriter 5000 for PS/2
- Adafruit - Convert IBM Model M Keyboard to Bluetooth
- YouTube - MrInterface Tutorial - Soarer's Protocol Conversion