A "virtual pinball cabinet" is a video pinball emulator, usually custom built and usually DIY. There are many ways to build these, but the usual setup is to put a PC motherboard inside a real pinball machine body (either the empty cabinet from an old machine that's beyond repair, or a brand new cabinet built to the same specs as the real machines). A TV goes in place of the playfield and another TV serves as the backglass/translite. Part of the appeal is just re-creating the physical layout of a real machine - it makes for a much better playing experience than you can get with a desktop simulation. Plus, you get to use real pinball buttons for the flippers and a real plunger to launch the ball. It gets even more interesting when you add feedback devices like flashing lights, solenoids, and shaker motors that re-create the light show and mechanical action of the arcade games. Adding an accelerometer makes it better still by making the virtual ball respond to real nudges on the cabinet. Put it all together and the effect can be thoroughly immersive and satisfying. It's not quite like playing a real pinball machine, but it's close - and unless you have your own warehouse or museum space, it's about the only way you can fit hundreds of different pinball games into your house.

This project lets you handle most of the special input/output functions needed for a virtual cabinet using a KL25Z, which inexpensive and takes up very little space. It can provide plunger position tracking, nudge sensing, button input encoding, and force-feedback output device control.

The software makes the KL25Z act like a USB joystick, so it's plug-and-play with both Windows and Visual Pinball. As far as Windows is concerned, it's an ordinary joystick, so no special drivers are needed. Visual Pinball itself has built-in support for joystick input, so the plunger, nudge, and button features only require a few preference settings in VP to get them working. The feedback device controller emulates an LedWiz, which is also already baked into VP and also requires no Windows drivers.

Documentation

The Hardware Build Guide (PDF) has detailed instructions on how to set up a Pinscape Controller for your own virtual pinball cabinet.

Update notes

Feb/March 2015 software versions: If you have a CCD plunger that you've been using with the older versions, and the plunger stops working (or doesn't work as well) after you update to the latest version, you might need to increase the brightness of your light source slightly. Check the CCD exposure with the Windows config tool to see if it looks too dark. The new software reads the CCD much more quickly than the old versions did. This makes the "shutter speed" faster, which might require a little more light to get the same readings. The CCD is pretty tolerant of a wide range of lighting, so you might be perfectly okay with the same light source before and after updating the software (I didn't have to change the light level at all on my system), but if you do have any trouble, have a look at the exposure meter and try a slightly brighter light source if the exposure looks too dark.

Downloads

• Config tool for Windows (.exe and C# source): this is a Windows program that lets you view the raw pixel data from the CCD sensor, trigger plunger calibration mode, and configure some of the software options on the controller.

• Custom VP builds: I created modified versions of Visual Pinball 9.9 and Physmod5 that you might want to use in combination with this controller. The modified versions have special handling for plunger calibration specific to the Pinscape Controller, as well as some enhancements to the nudge physics. If you're not using the plunger, you might still want it for the nudge improvements. The modified version also works with any other input controller, so you can get the enhanced nudging effects even if you're using a different plunger/nudge kit. The big change in the modified versions is a "filter" for accelerometer input that's designed to make the response to cabinet nudges more realistic. It also makes the response more subdued than in the standard VP, so it's not to everyone's taste. The downloads include both the updated executables and the source code changes, in case you want to merge the changes into your own custom version(s).
  
  Note! These features are now standard in the official VP 9.9.1 and VP 10 releases, so you don't need my custom builds if you're using 9.9.1 or 10 or later. I don't think there's any reason to use my 9.9 instead of the official 9.9.1, but I'm leaving it here just in case. In the official VP releases, look for the checkbox "Enable Nudge Filter" in the Keys preferences dialog. (There's no checkbox in my custom builds, though; the filter is simply always on in those.)

• Output circuit shopping list: This is a saved shopping cart at mouser.com with the parts needed for each output driver, if you want to use the LedWiz emulator feature. Note that quantities in the cart are for one output channel, so multiply everything by the number of channels you plan to use, except that you only need one of the ULN2803 transistor array chips for each eight output circuits.

• Lemming77's potentiometer mounting bracket and shooter rod connecter: Sketchup designs for 3D-printable parts for mounting a slide potentiometer as the plunger sensor. These were designed specifically for this potentiometer, but might be useful as a starting point if you're using a different one.

Features

• Plunger position sensing, using a TAOS TSL 1410R CCD linear array sensor. This sensor is a 1280 x 1 pixel array at 400 dpi, which makes it about 3" long - almost exactly the travel distance of a standard pinball plunger. The idea is that you install the sensor just above (within a few mm of) the shooter rod on the inside of the cabinet, with the CCD window facing down, aligned with and centered on the long axis of the shooter rod, and positioned so that the rest position of the tip is about 1/2" from one end of the window. As you pull back the plunger, the tip will travel down the length of the window, and the maximum retraction point will put the tip just about at the far end of the window. Put a light source below, facing the sensor - I'm using two typical 20 mA blue LEDs about 8" away (near the floor of the cabinet) with good results. The principle of operation is that the shooter rod casts a shadow on the CCD, so pixels behind the rod will register lower brightness than pixels that aren't in the shadow. We scan down the length of the sensor for the edge between darker and brighter, and this tells us how far back the rod has been pulled. We can read the CCD at about 25-30 ms intervals, so we can get rapid updates. We pass the readings reports to VP via our USB joystick reports.
  
  The hardware build guide includes schematics showing how to wire the CCD to the KL25Z. It's pretty straightforward - five wires between the two devices, no external components needed. Two GPIO ports are used as outputs to send signals to the device and one is used as an ADC in to read the pixel brightness inputs. The config tool has a feature that lets you display the raw pixel readings across the array, so you can test that the CCD is working and adjust the light source to get the right exposure level.
  
  Alternatively, you can use a slide potentiometer as the plunger sensor. This is a cheaper and somewhat simpler option that seems to work quite nicely, as you can see in Lemming77's video of this setup in action. This option is also explained more fully in the build guide.

• Nudge sensing via the KL25Z's on-board accelerometer. Mounting the board in your cabinet makes it feel the same accelerations the cabinet experiences when you nudge it. Visual Pinball already knows how to interpret accelerometer input as nudging, so we simply feed the acceleration readings to VP via the joystick interface.

• Cabinet button wiring. Up to 24 pushbuttons and switches can be wired to the controller for input controls (for example, flipper buttons, the Start button, the tilt bob, coin slot switches, and service door buttons). These appear to Windows as joystick buttons. VP can map joystick buttons to pinball inputs via its keyboard preferences dialog. (You can raise the 24-button limit by editing the source code, but since all of the GPIO pins are allocated, you'll have to reassign pins currently used for other functions.) (Note: this feature is still experimental; it hasn't been thoroughly tested yet.)

• LedWiz emulation (limited). In addition to emulating a joystick, the device emulates the LedWiz USB interface, so controllers on the PC side such as DirectOutput Framework can recognize it and send it commands to control lights, solenoids, and other feedback devices. 22 GPIO ports are assigned by default as feedback device outputs. This part is still experimental, and it has some limitations, particularly that the KL25Z hardware only has 10 PWM channels - so it can't be used to control a full bank of 5 RGB flashers, for example. The software also doesn't support any of the LedWiz flashing modes. To use this feature to control physical devices, external power driver circuitry is required, because of the paltry 4mA output capacity of the KL25Z GPIO ports. The build guide includes a relatively simple and robust output driver circuit design (including part numbers for the exact components you need) as a reference.

Warning: This is not replacement software for the VirtuaPin plunger kit. If you bought the VirtuaPin kit, please don't try to install this software. The VP kit happens to use the same microcontroller board, but the rest of its hardware is incompatible. The VP kit uses a different type of sensor for its plunger and has completely different button wiring, so the Pinscape software won't work properly with it.