99. Accelerometer (Nudge) Setup

The KL25Z has an on-board accelerometer, which is a sensor that measures the amount of acceleration applied to it. With a little classical Newtonian physics, we can use acceleration measurements to infer related information about the physical motion of the pin cab, which we can feed into a physics simulation like Visual Pinball so that nudging the cabinet can translate into a suitable effect on the game.
Analog acceleration sensing adds a whole new kind of "control" to pinball simulation, on par with real flipper buttons and mechanical plungers. Physical interaction with the game via subtle and not-to-subtle nudges is a huge part of real pinball that's completely lost in desktop pinball. Desktop pinball tries to make up for it with a "nudge key" that you can press, but that's not even close to the real thing; it's like trying to replace the feeling of throwing a ball with a button labeled "throw ball". The physical interaction you have with a real pinball machine is automatic, subconscious, intuitive, and the effect on the game is proportional and directional. A pin cab with an accelerometer brings that same mode of interaction to virtual pinball.
The KL25Z's accelerometer is built-in, and the Pinscape software uses it by default to send readings to the PC. So there's very little to set up on the controller side, other than physically installing the KL25Z to take best advantage of the sensor. There are some options you can set to fine-tune the input, though. And there's a small amount of work needed on the PC side to configure pinball programs to use nudge input.
This section is specifically about setting up Pinscape nudging. You might also want to take a look at Nudge & Tilt, which looks at the subject more generally.

Positioning the KL25Z

The KL25Z's accelerometer is a three-axis type - it measures accelerations side-to-side, front-to-back, and up-and-down. The accelerometer chip is mounted on the KL25Z board so that the axes align with the plane of the board.
To take the best advantage of this, we want to align those native axes on the device with the axes of the cabinet, so that it's easy for the software to translate the sensor readings from the device to the motion of the cabinet. Specifically, the KL25Z board should be roughly flat on the floor, and it should be square with the front and sides of the cabinet.
"Square" with the front and sides means that the sides of the board are parallel with the corresponding cab walls. That makes any of the following orientations work (viewing the main cabinet from directly above):
So that tells us how to orient that board. The exact placement within the cabinet is a little more flexible. To a certain extent, it shouldn't matter too much where you place it, because the board will always move with the cabinet no matter where you put it. But the cabinet's motion has some subtleties because of the way it sways on the four legs, so I think it's best to locate the board close to the front, roughly centered side-to-side. That'll place it closest to where you're actually applying the nudge forces, so it should make it pick up motions in the same directions as your nudges, or at least as close as possible.
Finally it's very important to tightly attach the KL25Z to the cabinet floor. It should be secured to the cabinet so that it moves exactly as the cabinet moves. It shouldn't have any play that lets it slip around on its own; you want it to precisely track the motion of the cabinet. If you're mounting the KL25Z stadalone, attach it with a couple of screws through the mounting holes near the USB connectors, and make sure all four rubber feet are firmly planted. If you're using the expansion boards, the KL25Z plugs in via pin sockets that are a good tight fit, so you just have to make sure the main board itself is securely installed on standoffs.
To summarize:
  • Place the board flat on the floor of your cab
  • Top side facing up (the side with the IC chips)
  • Square with the sides, in one of the four orientations shown above
  • Close to the front of the cabinet
  • Roughly centered side-to-side
  • Mounted securely so that it moves precisely as the cabinet moves

Config Tool nudge setup

The Config Tool has a few settings for the accelerometer that you can configure. To edit settings:
  • Launch the Pinscape Config Tool
  • Click the Settings icon for your device
  • Scroll down to the Accelerometer orientation section.
The most important thing to set here is the device orientation. Select the radio button that matches the orientation of the physical device.
Dynamic range: this setting lets you change the maximum acceleration that the device can register. There's a trade-off: a wider dynamic range also means lower precision (the ability to distinguish small differences in degree). The KL25Z's accelerometer chip can be set to a maximum range of 1G, 2G, 4G, or 8G (meaning N times the acceleration due to Earth's gravity). The 1G setting has the best ability to distinguish fine shades of differences at small accelerations, down to about 1/10000 of a "G", but any actual acceleration higher than 1G (about 10 meters per second) will just read as the maximum 1G. 8G is at the other extreme: it can distinguish strong accelerations up to 8 times Earth's gravitational acceleration (which are very strong accelerations indeed), but at the low end can only distinguish to about 1/1000 of a "G".
In my opinion, the high-precision 1G setting is the best option for pin cab. A 1G acceleration is pretty strong in this context, and I don't see any practical need to distinguish nudges that are even stronger than that. We're better off with the finer gradations of subtle nudges that this setting can distinguish.
Auto-centering: If you could mount the KL25Z perfectly flat in your cabinet, it would read "zero" on the X and Y axes all the time naturally. If you have even a slight tilt, though, Earth's gravity will register as a slight constant pull on these axes. Since this is practically impossible to eliminate in the physical mounting, the Pinscape software compensates for it by subtracting out any constant acceleration on either axis. This compensation is called auto-centering.
The auto-centering option is enabled by default, with a default interval of 5 seconds. That means that any time the accelerometer hasn't been registering any significant motion for 5 seconds, the firmware will take the average reading over that period to be the true rest position of the physical device.
You can change this to disable centering entirely, or to change to a longer or shorter period. If you disable auto centering, you can use the joystick viewer in the Config Tool to manually re-zero the readings at any time.
I'd recommend leaving auto-centering enabled. The true physical orientation in space of you pin cab will inevitably change slightly over time, as a natural consequence of your pin cab shifting on its footings. The KL25Z accelerometer is so sensitive that it'll pick up these slight shifts. If you don't allow the software to compensate by auto-centering frequently, you'll see a constant small bias in the readings, as though you were constantly nudging the machine slightly. The constant compensation provided by the auto-centering software keeps these biases from developing.

Testing nudge input

The Config Tool has a built-in viewer/tester for the joystick interface.
  • Launch the Pinscape Config Tool
  • Click the Joystick icon for your device
That brings up the joystick viewer window:
This lets you view the information that the device is sending to Windows, to verify that the USB joystick interface is working properly and that the accelerometer, plunger, and button inputs are working as expected.
The little diagram at the left labeled "Accelerometer" shows you the current nudge readings. The little crosshairs in the middle represents the accelerometer reading in 2D space; up/down corresponds to the front-to-back direction on your cabinet, and left/right corresponds to left/right on your cabinet.
Check the orientation: When you give your cabinet a push from any direction, you should see the crosshairs jump briefly in the same direction as the force you applied. Push the cabinet from the front, and the crosshairs should briefly deflect upwards; push from the left, and the crosshairs should deflect to the right.
If the crosshairs move in the wrong direction when you nudge the cabinet, go back and check the device orientation setting to make sure it matches the way you positioned the KL25Z in the cabinet.
Button inputs: The red circles at the bottom represent the joystick buttons. These don't represent the physical button inputs on your KL25Z - they're strictly the joystick button presses that Windows sees through the joystick device interface. If you programmed a button to send a keyboard key instead of a joystick button, you won't see anything light up in the joystick viewer when you press the button.

Windows calibration = bad

Windows has its own joystick device calibration procedure, which you get to via the Windows control panel called "Set up USB game controllers". Don't use it!
Everyone always wants to run this. They see the calibration option in Windows and think it must be there to help. It is there to help, but only for real joystick devices. It's a disaster to use with nudge/plunger devices, because they're not anything like real joysticks. Nudge/plunger devices only pretend to be joysticks so that they don't need separate device drivers.
If you accidentally ran the Windows calibration before you read this warning (everyone does!), you'll need to delete the Windows calibration. The Windows calibration will screw up the Pinscape readings and make your nudge and plunger inputs act erratically. Fortunately, they made it pretty easy to reset the unwanted calibration data:
  • Open the "Set up USB game controllers" control panel (press Windows+R, type joy.cpl, press Enter)
  • Select the Pinscape device
  • Go to the Settings tab
  • Click Reset to Defaults

Visual Pinball setup

VP can use accelerometer input for simulated nudging. This isn't enabled by default; you have to adjust some settings in VP to get it working.
For instructions, see "How to configure VP for an accelerometer" in Nudge & Tilt.

FX2/FX3 setup

Pinball FX2 and FX3 can also simulate nudging using an accelerometer, but they don't use the joystick interface that Pinscape provides. Instead, they require input through the XBox controller interface.
To bridge the gap, there's a program called x360ce that can make a joystick device emulate an XBox controller. That can reportedly be used to make Pinscape nudging work in FX2/FX3.
I don't use this in my own system, so I don't have any details about how to set it up. I anyone wants to write up instructions, I'll be happy to include them here.

Conflicts with other joystick devices

Windows is happy to let you attach multiple joysticks to your system at the same time, and doesn't have any trouble telling them apart. However, not all applications are so accommodating. Some people have run into conflicts between the Pinscape device and other joysticks or joystick-emulating devices.
There are two main ways to deal with conflicts:
  • Temporarily disable one of the devices when running applications where the conflicts occur
  • Switch one or the other device to use different "axis" assignment for their data input
These techniques are described in more detail below.

Temporarily disabling a device

Many of the Microsoft software development kits (SDKs) include a tool called devcon, which lets you temporarily enable and disable individual devices. This can be a good way to deal with a conflicts with another device that you only use with certain applications. That is, you simply disable the other device when you're not using the specific applications it's needed for.
For example, one person on the forums reported a conflict with a special arcade controller device he only uses with certain video game programs. The arcade device was creating a conflict with the Pinscape device in Visual Pinball. But he didn't actually use the arcade device with Visual Pinball, so the simple solution was to disable it when Visual Pinball is running, eliminating the conflict in VP.
Installing devcon: The program comes with the Windows SDK, which you can download from the Microsoft site separately or as part of Visual Studio. You might also be able to find a plain devcon download with a Web search, although I don't think Microsoft makes it officially available separately from the SDKs.
Identifying the device: To disable a device with devcon, you need to know its USB ID. devcon itself has a way to list devices and their IDs. From a CMD prompt, go to the folder where you installed devcon.exe and run this command:
devcon listclass HIDClass
That will show you a list of devices with their cryptic internal ID strings on the left, and a device description on the right. The only problem is that the device descriptions aren't very specific; they're mostly vague things like "HID-compliant game controller". I think the easiest way to figure out which one corresponds to your device is the differential approach:
  • Plug the device in
  • Run the devcon listclass HIDClass command
  • Unplug the device
  • Run devcon listclass HIDClass again
  • Compare the lists - the item(s) missing from the second list represent the device you just unplugged
Disabling the device: Once you've figured out which cryptic ID string corresponds to your device, you can disable it as follows:
  • Open a CMD prompt window in Run as Administrator mode (necessary because we're messing with device drivers)
  • Go to the folder where you installed devcon.exe
  • Type devcon disable "@xxxx", where xxxx is the full ID string from the "listclass" list
Re-enabling the device: Same procedure as above, but replace the devcon disable command with devcon enable.
Automating it: You can automate the disable-enable procedure by putting it into a .BAT script. However, keep in mind that you'll have to run the .BAT script with "Run as Administrator" mode.

Axis settings

Another way to deal with conflicts is to tell Pinscape to report its input on a different set of axes than it normally uses. This can be useful if you're getting conflicting readings on the two devices in a program that can't distinguish between different joysticks, such as Visual Pinball.
Most joystick devices send their input to Windows via the main joystick position axes, known as the X and Y axes. That's how Pinscape normally sends its accelerometer inputs. There's also a third standard joystick axis, called the Z axis, that Pinscape uses for plunger input.
Pinscape has an option to switch its inputs from using the X-Y-Z axes to a separate set of axes, called the "R" axes - Rx, Ry, Rz. The axis assignment change can be made in the Config Tool's Settings page, under the Joystick section:
In case you're wondering, the "R" stands for rotation. In a real joystick, the R axes are used to report twisting motions on the stick. For Pinscape purposes, it doesn't really matter what the "R" axes were designed for; we just use them as an alternative way to send the same inputs.
The Rx-Ry-Rz setting can work around conflicts in VP with other joysticks that use the X-Y-Z axes. VP can't distinguish between joysticks, but it can distinguish the different axes.
If you do change Pinscape to report readings on Rx/Ry/Rz, you have to update the joystick input settings in VP and other programs to match. VP will normally look for input on the X/Y/Z axes, so if you change to Rx/Ry/Rz, you have to tell VP to look there instead.
The downside of using Rx/Ry/Rz axes is that some pinball programs are either hard-coded to use the Z axis for the plunger, or can't use the "R" axes at all. Future Pinball can't use the R axes at all, for example. You'd lose compatibility with such programs if you moved Pinscape to Rx/Ry/Rz. So I always recommend using the default X/Y/Z axis settings whenever possible, and only changing to the "R" axes as a last resort when you have a conflict with another device that you can't resolve in any other way.
Note that Pinscape only lets you change to the "R" axes as a group. Both the plunger and nudge inputs have to be on the same axis type.