xwhatsit's Grand Unified IBM Capsense USB controller thread

[xwhatsit]

IBM Capsense USB Controllers

Rather than duplicating effort between the previous threads, we should try to keep everything here from now on.

I've developed a set of USB controllers for the IBM capacitive keyboards (Model F and Beamspring). These allow keyboards that otherwise have no way to hook them up to a modern PC to be used (Beamsprings), offer an alternative to Soarer's excellent converter (standard Model Fs), and also an alternative to the other intriguing capsense project around, the DPH controller. It allows the potential to go a bit further than just a converter if you're trying to do something a bit unusual—like build your own keyboard using old Model F bits, add extra keys that the original controller won't support, or get full make/break scancodes with NKRO on a terminal keyboard.

At any given time, the code as well as schematics/PCBs/precompiled binaries are available at http://downloads.cornall.co/ibm-capsense-usb

Features include:

• Open source! (GPLv3)
• Approx. 500Hz scan rate with fast debounce
• Full NKRO (without needing to add diodes—yay capacitive keys) over USB on all Windows/Linux/Mac OS X, while retaining boot-mode compatibility for BIOS etc.
  
• Auto-calibration of capsense thresholds
• Media/consumer keys mappable
• Layer support with 3 function keys; function keys support chording
• Macro support
• Cross-platform (Windows/Linux/Mac OS X) graphical configuration utility to set layout/layers/configure scanning
• Expansion header on all boards to support LEDs, solenoid drivers (for some Beamsprings), buzzers (on Kishsavers) etc.
• Compact surface-mount design without needing to plug in external Teensys etc.

The Controllers

Beamspring-USB-Rev4

This supports the standard Beamspring boards, such as the 5251, 3278, 3727 etc., which have a 23x4 matrix. It will not work on a Beamspring Displaywriter despite the identical 30-pin connector, as these have a 12x8 matrix—see below for that controller.

This can be paired with the solenoid driver board (see below) for Extra Loud Click, if your Beamspring is fitted with a solenoid (the 3727 is the only one I'm aware of that isn't).

USB connects via an on-board mini-USB socket.

PCB at OSHPark: http://oshpark.com/shared_projects/bOXMsRYH



Beamspring-Displaywriter-USB-Rev1

This is to support the unusual Beamspring Displaywriter keyboards, which have a very different 12x8 matrix, with interleaved rows. They will not work with a Model F Displaywriter; as far as I'm aware these have built-in (non-removable) controllers.

USB connects via an on-board mini-USB socket.

PCB at OSHPark: http://oshpark.com/shared_projects/KcxYPs3y



Model-F-USB-Rev1


(photo shows Rev1 boards)
Rev2 PCB below (black lines show the actual board cutout):


This should work with all Model F keyboards (including the Kishsaver) which have separate controllers. Unfortunately this excludes the XT and a couple of other terminal boards, which have a controller-on-board which can't be removed (except maybe with a hacksaw).

Some Model F keyboards have less than 16 columns; columns can be set to `skip' using the GUI util.

These do unfortunately require soldering; IBM used a soldered-on ribbon cable for the Model F controllers, that first needs to be removed from the old controller, then attached to this one.

In the Rev2 board (unlike the Rev1 in the photo below, which has a flying lead), a USB micro (not mini!) is socket is used. This is to reduce board size a bit and these days USB micro sockets are much more common.

PCB at OSHPark: http://oshpark.com/shared_projects/eTR858GJ



Accessory boards

Beamspring-USB-Solenoid-Driver-Rev2

(photo shows prototype, not Rev2)

This is drive the solenoid fitted to most beamspring keyboads. It runs off the USB voltage supply to the main controller, and uses a current-limited switch-mode power supply to boost up to 9V. This is then used to fire the solenoid when a key is pressed for Extra Loud Click coupled with Small Blinking Light.

PCB at OSHPark: http://oshpark.com/shared_projects/qdZwUHLH


Model-F-3178-Adaptor-Rev1



An adaptor board for IBM 3178 keyboards, which were kind of an unusual Model F version of a 3278/3727 Beamspring. They unfortunately have a different pinout and require this adaptor.

PCB at OSHPark: http://oshpark.com/shared_projects/bD4fQlCX




GUI Util

This is a Qt application which runs on Linux, Windows and Mac OS X. Its main purpose is to allow you to set which key location corresponds to which scancode:

...but also allows tweaking expansion port settings, like whether to run in LED mode for Caps/Num/Scroll Lock indicators, or whether to fire a solenoid (and adjust timings of it etc.).

This also is handy for diagnostic output to show which keys are being sensed as up or down.



Building your own
Give it a go! Sourcecode/schematics/PCB layouts are here: http://downloads.cornall.co/ibm-capsense-usb . You can order pre-Gerbered PCBs from OSHPark by using the links above, or checking my profile on OSHPark here: http://oshpark.com/profiles/xwhatsit . There are people around (me included) who will help you if you run into issues. Surface-mount is easier than through-hole, it just looks scary!


Pricing/Availability
As mentioned above, these are open-source. If you have a soldering iron and flux, consider building your own! Don't be put off the surface mount soldering, several people (some with no previous surface-mount experience) have now built their own.

However if you're not into picking up resistors with tweezers, I can build one for you and pre-program and test it first. For this, check out the group buy thread over here: http://geekhack.org/index.php?topic=58192

[CPTBadAss]

Ha this is great! I can't believe I didnt see this sooner. I've been following the beamspring work you've done, xwhatsit, for a while. Can't wait to get my hands on a beamspring board and actually use it .

[jwaz]

You should split this post into a the sort of upper FAQ part and lower GB section to run the actual buy, the MST forum isn't really for commercial activities.

That said, I'm stoked at the progress of this project and will definitely be in the GB for at least a couple boards.

[xwhatsit]

Oh right! Roger that. Sorry, didn't really see this as a commercial thing. I'll split it up shortly.

[poxeclipse]

Guys, there is a deadline of June 1st, for the capsense controller & extras. Put your orders now. The DT guys seem more active than us.

[xwhatsit]

Pics of first Rev2 Model-F-USB (with micro-USB connector instead of flying lead, more space for mounting holes for Kishsavers etc.):

[0100010]

Can the 6 pin expansion port support both a 4704 buzzer and 3 LEDs?

[xwhatsit]

Yes; although there's no code to do that currently it wouldn't take much to add it. There's four GPIO; in theory 2 are used in the solenoid mode; one of them is used to enable the 9V boost converter when the USB interface allows the controller to draw the full 500mA. This is obviously not required when using the little Kishsaver's piezo, which runs at 5V.

Once I've finished the macro stuff (progress screenshot attached) I'll look to add that mode.

[antdes457]

xwhatsit, do you know if there's a maximum number of simultaneous keystrokes on your controller?

I'm currently using Soarer's controller in a F 122 terminal keyboard and there is about 1-2 missing strokes
when pressing key clusters like 234we or many other 2D combinations. I also lose modifiers when this happens.

Do you think it's a capacitive keyboard limitation or more on the controller side?

[xwhatsit]

From the ibm-capsense-usb controller itself it's completely NKRO. Certainly with all the Beamsprings and Model Fs I have that I've fitted controllers to, I can press as many keys as I like.

The capacitive keyswitch tech itself is completely NKRO. I've never used an original IBM capacitive controller (apart from briefly a while ago with my PC-AT), but perhaps they have an internal limitation on number of simulataneous keystrokes.

I'm pretty sure Soarer's converter is fully NKRO as well (it must be, as I borrowed most of his ideas when I implemented NKRO on my controller), so if it's anywhere it must be in the original controller or perhaps you've got a dodgy keyboard. I know with the F122s that there is less mechanical tension between the steel plates in the middle of the board, because of its size—this is what causes the different “ping” tones in different places. Maybe having so many keys pressed is moving the backplate away a little?

Now that people have got cheap Model F controllers being manufactured in China (i.e. not my expensive and far-away workbench) you could chuck one in cheaply enough

[antdes457]

Hi,

Will try a controller from eBay.

Anyways, the original controller + Soarer's seem to take so much juice on my Raspberry Pi that it crashes after a while and other USB ports go dead.

With the current setup, NKRO works for as long as I don't press too many keys at the exact same time.

I forgot to tell, but releasing 4 keys while holding shift will also lose the modifier, so it looks like it's more of a controller issue. Maybe the buffer for one clock cycle is too small or something. Unfortunately, I don't own a logic analyzer to spy on the IBM controller.

Thanks!

[antdes457]

Just installed the new controller and now NKRO works as expected.

However, looks like there is no good threshold right now... I totally lose caps lock and '0' over a 133 threshold and spacebar triggers other keys in the bottom row all the time. It could be a solder issue on that row maybe.

Edit: as I suspected, the metal bar in the space bar is causing noise with friction.

[xwhatsit]

If the spacebar always triggers other keys (regardless of threshold, ignoring the rest of the board) then it is probably a short somewhere.

[antdes457]

I removed the metal bar and it's gone...

[xwhatsit]

Bizarre! You mean the stabiliser?

[antdes457]

Hmm, maybe I moved dirt away... Stabilizer is back and no more false triggerings on every presses.

[antdes457]

I removed the cap under zero and blew, now 9 acts funny. Sounds like there's stuff between the plates.

EDIT: All fixed. It's capacitance based, so yeah, good moisture sensor... 

[antdes457]

Last update: spacebar started acting up again. I now put a bit of tape where the black paint was scraped by the stabilizer bar. Let's see how it holds. I'll start a new thread if there are more problems rather than spam this one.

[__red__]

xwhatsit,

Do you know the range of capacitance that your controller is able to detect?  I'm just finishing the molds of my "Glass-Clear" Model F Barrels / Keys / Feet and starting on transparent "PCB" fabrication.  If you can give me an indication of the capacitative ranges I should aim for that would help a lot.

Obviously, the greater the distance between key-down and key-up the better it will be at noise rejection.

Thanks,



Red

[xwhatsit]

antdes457: More than likely there's some foam crud between the plates (or on the bottom of a foot). This is interesting, I've never seen a back-to-back controller swapout before. Given you had no trouble before it would seem my controller is a little more sensitive to these sorts of problems. I wonder if that's because of hardware reasons or if the original controller just filtered stuff more?

__red__: I've never properly quantified it, it's a little tricky with all the parasitic capacitances floating around. I've seen values for the original Beamspring setup of around 4pF pressed and 40pF unpressed, so that's what I aimed for when I was doing some really early testing, but I suspect it's probably a bit more than that.

Are you doing glass PCBs like this guy?

Very pretty!

Despite the fact you'd likely have a different dielectric constant from the original FR-4 (or whatever it was IBM used for the "pad card"), you wouldn't go too far wrong following a similar sort of pad layout, provided your new transparent feet respond similarly to the originals. Have you put graphite into the feet or are you going to add a conductive layer on the bottom?

[Melvang]

Quick question for you xwhatsit.  Is there any special reason for the plastic sheet in my PC-AT?  I don't remember my XT having one, and I accidentally damaged mine in my garage.  The wind caught it and blew it on the floor and I didn't see it.  It got stepped on and there is a few dents and dings.  I am not really worried about the damage, but I was thinking about using something else that I don't have to be quite so gentle with.

Again, I just want to say thanks for answering my questions I have been bugging you about in PM's on DT.  In case you are wondering I got the controller mount figured out including completing the ground plane between the plate and the controller given the controller location.

http://i.imgur.com/7aqokLb.jpg

[xwhatsit]

You know what I don't know... in fact I can't recall where the plastic sheet fits now. It's between the pad card and the bottom plate isn't it?

It's probably just there for insulation, although I would have thought the soldermask would have been enough for that. I don't think there are any vias which break through the soldermask.

I don't think you'll hurt anything by leaving it out, other than having to reassemble everything again if it doesn't

That looks like it's going to be very tidy. I've long thought the guts of the IBM capsense boards were good enough to put on display without a case.

[Melvang]

You know what I don't know... in fact I can't recall where the plastic sheet fits now. It's between the pad card and the bottom plate isn't it?

It's probably just there for insulation, although I would have thought the soldermask would have been enough for that. I don't think there are any vias which break through the soldermask.

I don't think you'll hurt anything by leaving it out, other than having to reassemble everything again if it doesn't

That looks like it's going to be very tidy. I've long thought the guts of the IBM capsense boards were good enough to put on display without a case.

Thanks for the vote of confidence.  Its not that I think its ugly, I am just going for the naked exposed plate clean look with a PC-AT, so it is taking a little trimming.  Both plates are the exact same width, the tab where the LED pcb is gone, and the two tabs for the controller are going away as well. 

You are right, the plastic sheet goes between the pcb card and the back plate.  Instead of the plastic sheet I am going to spray the front of the back plate with rattle can plastidip.  It is basically a spray on thin rubber type coating.  If it doesn't work out, it just peels right off.  The back of the back plate and both sides of the top plate are getting this, along with the new foam, and my floss mod, it has a very unique sound, while still retaining probably 90% of the feel.

This is my floss mod video from my AT. 

Also, I somewhere I scratch the solder mask on the bottom of the PCB, exposing some of the trace of the ground plane.  Should I put something on the scratch to prevent corrosion of the copper?  I would think a quick bit of clear fingernail polish would work great here.

[xwhatsit]

What! No ping!

I wouldn't bother about trying to cover up the exposed copper. It will oxidise a bit but you're not trying to solder to it so that's fine.

[__red__]

The Patent states that the plastic sheet is a dialectic to reduce parasitic capacitance between neighboring keys.

From everything I've seen, probably more critical if you were using the original controller than xwhatsit's.

xhatsit - This is the method I was planning on using:


http://fab.cba.mit.edu/content/processes/PCB/vinylcut.html

[alh84001]

Forgive me if I'm being dense, but I can't seem to find a way to set the key to "<>". That is the key right of the left shift in ISO layouts. Help me out, because I must be missing something simple.

[antdes457]

I'd try "Non-US \ and |".

[Melvang]

So I got my Kish working with one exception regarding the buzzer.   It works as expected but when I set a key to "toggle exp" the buzzer fires and doesn't shut off.  Do I have the buzzer wired up wrong?



I know it's a crappy pic and I can get a better pic posted tonight, black is gnd green is driver and red is vcc.

[baobrien]

Hi Everybody,

I've got a couple of XT Model Fs here, and it looks like all of the column and row lines are broken out to nice easy-to-solder pads. I've modified the Model F USB controller to match up with these pads and will try just cutting the traces from the matrix to the stock controller. I still need to make some measurements on the pads, but will post my modified controller when I get a chance to.

[baobrien]

I've modified the capsense USB model F controller so that it should work with the model F XT, and I've ordered a few boards. All I've done is change out the connector with a few .1" pin headers to match where the row and column lines are broken out on the XT controller. I'll keep everybody up to date on how the board works out.

KiCad files for the modified controller are up at https://baobrien.org/capsense-model-f-xt.zip

[alh84001]

Nice. Moar pics!

[baobrien]

The boards have shipped from DirtyPCBs and should be here Friday.

Here's the DirtyPCBs rendering:



And where I plan on cutting traces on the XT controller

[baobrien]

aaand I just noticed that the grounds are bumped .1" in the wrong direction. Oh well, I'll just have to use wires for those ones.

[mrduul]

Fantastic information.

[alienman82]

removed.

[Red October]

So I just grabbed a Displaywriter version of this off eBay to try to breathe some life into my glorious Displaywriter keyboard, and something is slightly amiss... I got it installed correctly, but the programming utility seems to think that the keyboard is a Model F, not a Displaywriter keyboard.  There doesn't seem to be a way to change this, and the .pdf manual doesn't mention this condition, only to note that it correctly matches the keyboard you physically have.  Did I cock something up, or is there a failure?  I'm can't seem to be able to set the voltage threshold somewhere that works, either, and, because of this mismatch, I'm not sure where to look next for failure.  I've already done away with the rubber condom doohickey, it had crumbled to flakes of which more than a few had wandered onto the main circuit card.  I cleaned the main card with contact cleaner and lint-free wipers, but that didn't make it do anything that resembled correctly operating any more so than what it did before did.

Also, for the Displaywriter keyboard, at least, when you take the actual keyboard module apart, don't go mucking about looking for books and a big flat surface that's not the one you're working on and all that, just flip it over and install it backwards with a couple turns of a couple screws.  Because you really don't want to lose pieces of 35+-year-old keyswitches.  The IBM manual mentions this technique, but almost offhandedly, after giving you a diagram of how you should form the book-assemblage and everything, but it really should be S.O.P.

[Ellipse]

xwhatsit software quirks - an F107 user discovered some bugs in the xwhatsit software on OS X and Linux - if anyone could try to write a patch for the code it would help those who do not use Windows!

* Problem: The pre-built config tool for Mac OS X detects the controller
  twice at different addresses; picking the wrong one hangs the config
  tool, but seems to have no other adverse effects.
  Workaround: kill the config tool and try again until it works.

* Problem: Linux config tool won't build with GCC 6.x due to an
  intentional breaking change in GCC's handling of "-Isystem".
  Workaround: build the tool and all C++ dependencies with GCC 5.4.x

* Problem: Linux config tool crashes X11 and corrupts the console keymap
  when attempting to set the sensitivity threshold.
  Workaround: Borrow a MacBook and use the OS X version of the tool.
  I suspect that this is related to the double-detection bug seen on OS
  X, but I don't have the debugger-fu needed to determine the actual
  mechanism-of-lossage at work here.

[OldIsNew]

Building your own
Give it a go! Sourcecode/schematics/PCB layouts are here: http://downloads.cornall.co/ibm-capsense-usb . You can order pre-Gerbered PCBs from OSHPark by using the links above, or checking my profile on OSHPark here: http://oshpark.com/profiles/xwhatsit . There are people around (me included) who will help you if you run into issues. Surface-mount is easier than through-hole, it just looks scary!

I couldn't  find specs on the SMD package sizes of the various caps, resistors, etc. used in the solenoid driver (and the model F controller). Does anyone know if  they are listed somewhere?  I can guesstimate, but it would be nice to have the actual specs used before ordering components.

[gwideman]

Short version: In the IBM Capsense USB Util version 0.9.0, where is the Base Layer  (or any layer) "Store in EEPROM" button?

Longer version: I downloaded the latest software, 0.9.0, from http://downloads.cornall.co/ibm-capsense-usb/, and also doc installation_model_f.pdf.  I followed the instructions in that doc, and am now typing successfully on the newly-xwhatsit-ified keyboard. (Well, except for super-stiff spacebar.)

However, that doc shows a UI somewhat different from the actual 0.9.0. Perhaps, the doc is for an earlier version. Not much of a problem, except that section 6.2.3 says to use the "Store in EEPROM" button to save the keyboard configuration to EEPROM, and the screenshot shows such a button just above the row of tabs.  In the actual program, there are no buttons above those tabs. just two panels: "State" and "Control" (with the latter containing only a huge "Emergency halt" button).

So how do we get the keyboard layout (assignment of matrix position to PC scan code) to store into the EEPROM?

Thanks. -- Graham

[alh84001]

Any change in the layers should be stored automatically.

[gwideman]

Any change in the layers should be stored automatically.

Thanks for your reply, but I'm unsure what you mean.

Are you saying that you think that the current software stores layer changes into the EEPROM automatically? Or are you advocating that the software do that, but currently it does not?

If the former, then what is/was the function of the "Store in EEPROM" button? Or perhaps you have some info that older versions needed that button, but later versions made storage automatic?

[darkcruix]

I wonder, if there are macOS users who are on 10.13 High Sierra?
When I try to run the pre-compiled GUI it crashes instantly. The error report shows: "terminating with uncaught exception of type std::runtime_error: error initialising hidapi"
If someone found a workaround, please let me know.

[enrique.aliaga]

Same here. Running macOS 10.12.6 Sierra. The GUI utility crashes immediately after trying to launch it. It looks like the "hdapi" dependency (whatever it does) was broken by macOS Sierra.

I used the software when running OS X 10.11 El Capitan and had no issues whatsoever. I wonder if there is any fix in the works, or we Mac users are doomed to find a Windows PC in order to configure our beloved Model F keyboards.

[darkcruix]

I hope there is someone available who can look at the code and create a new, working app out of the source code.
I will retrieve the source code next week and will have a look at it. I hope I can understand it (being a n00b I can't promise anything, but I will try to see, if I can ultimately compile it after all).

[darkcruix]

Update: I uploaded the latest compiled version, which I have tested on 3 Macs without issues. Please let us know, if it also works for you on newer systems

[darkcruix]

UPDATE: I am writing this with the F122 I had troubles with. There has been a tiny issue with ground on the middle contacts. De-soldering and re-soldering solved the issue.




I bought a F122 with a cracked ribbon cable to the original controller. I had to replace the cable with single ones, which I soldered to the PCB and the xwhatsit controller.
Sadly it doesn't show any registered key presses, when I hold the flipper plastic over two areas where a keypress would normally be happening.

Any ideas what could cause this issue? I have added two pictures of the soldering and PCB. At least the PCB looks good to me and I can't see any issues with it.
Any ideas, what I need to check to get this resolved?

I can manually cross-wire the rows and columns and it registers fine. I also checked ground wiring and I don't see any problems with it.

Thanks!

[ljosa]

Are the Beamspring-USB-5251-Rev4 and Model-F-USB-Rev2 versions of the xwhatsit functionally identical, just with different connectors, pinouts, and physical size?

[darkcruix]

I want to add a lock LED and need some guidance on the wiring.
Actually, the problem I would like to solve is to have an indicator whenever I press the select button for Fn Layer 2, that it is active. Obviously, A Num Lock LED activation would help me also, as I could create a Macro that toggles both.
Anyway, before I blindly start attaching LEDs to the PINs of the extension header, I want to check with you folks who have more knowledge around this.

[PancakeMSTR]

I made a [Digikey Cart] if anyone is interested (for the beamspring PCB). I'd also appreciate it if anyone could point out any errors.

[darkcruix]

I made a [Digikey Cart] if anyone is interested (for the beamspring PCB). I'd also appreciate it if anyone could point out any errors.

I have ordered all parts in the cart and also ordered the blank PCB (ordered everything to be able assembling two).
Once I have it, I will give it a shot and if all goes well, I will give a quick update and guide.