# Plunger Sensor Viewer

This window is designed to help you install and adjust your plunger sensor. It shows the current position reading and the calibration data. If you're using an imaging sensor (such as a TSL1410R), it shows a real-time view of the captured image.

## Sensor snapshot

For imaging sensors, the "snapshot" box displays the image pixels that your sensor is capturing. This is updated continuously, so that you can immediately see the effects of adjusting the sensor position or the light source.

The pixels are rendered in shades of gray, since the sensors we support are monochromatic. Black pixels correspond to full darkness (or full shadow) on the sensor, and white pixels are fully saturated (maximum brightness at the sensor). Our sensor types are one-dimensional, meaning that the pixel array is one pixel wide. The display stretches out each pixel vertically to make it easier to visualize, so the image might look like a bar code or a series of vertical stripes.

For optimal performance, adjust your sensor and light source as follows:

- Position the sensor so that the shadow edge is always in view, whether the plunger is pushed all the way forward or pulled all the way back.
- The shadow edge should be sharp and narrow. It's easier to get a sharp edge if you use a "point source" - a light source with a small aperture - and you position it relatively far away from the plunger (on the floor of the cabinet, say). The light source should be roughly centered under the sensor and pointing straight at it.
- The light source brightness should be set so that there's a good degree of contrast between the dark and light regions in the image. If the image is all black or dark gray, the light source needs to be brighter. If the image is all white or washed out, the light source needs to be dimmer.

The statistics shown under the image give you some more information about the sensor scan.

The Min and Max Brightness levels are on a scale from 0 to 255. 0 is full darkness, 255 is fully saturated. If your light source is set up properly, the Max value should be at least 30 or 40 higher than the Min value. This indicates a good level of contrast between the lit areas and the shadows.

## Plunger position

If the controller is able to read the plunger position from the sensor, the position will be displayed as a green bar across the bottom of the snapshot box.

If you don't see a green bar, it means that the controller can't read the position. If you're using an imaging sensor, this might be because the image is too dark or too washed out.

## Current calibration display

The snapshot box draws little arrows to show the current calibration limits. The purple arrows show the park position, where the plunger sits when at rest. The red arrows show the maximum retraction position. If the plunger is calibrated properly, the plunger should settle and stay roughly at the park position when you're not moving it.

Real plungers always have at least a little mechanical play, so your plunger won't come to rest at exactly the same spot every time you fire it. It should be fairly consistent, though. If the park position shown isn't fairly close to the actual resting position, re-run the calibration procedure.

## Calibrating

If you just installed the sensor, or you've adjusted its position, you should calibrate it. You can also recalibrate any time if the displayed park position doesn't look right.

To calibrate, make sure the plunger is at rest at its normal park position. Then click the Calibrate button, and follow the on-screen instructions.

Note that the pixel display is disabled during the calibration process. It will resume when the calibration finishes.

## Timing statistics

The scan time shows you how long it takes, on average, to take one position reading from the sensor. For an imaging sensor, this is the time it takes for the sensor to snap a photo (so to speak) and then transfer the image pixels to the microcontroller. The controller has to read the pixels one by one, so the pixel transfer is usually the bulk of the scan time for an image sensor. For an analog sensor (an LVDT or potentiometer, for example), the "scan time" is simply the time it takes to sample the analog voltage level on the sensor output and turn it into a digital reading.

The capture time for images from the TSL141R should be about 2.5ms with the current controller software. That's about 400 frames per second, which would be considered pretty fast in a regular photography or video context. A high frame rate is good for capturing fast motion, which is exactly the situation we have when you pull back and release the plunger.

For non-imaging sensors, the "scan time" is usually negligible (tens of microseconds), since we only have to wait for the analog voltage sampler to take a reading.

The "processing time" shows how long it took for the software to analyze the raw data for the current frame to determine the current plunger position. For an imaging sensor, this reflects the time it takes for the software to analyze the image pixels. For an analog sensor, this is usually zero (or close enough), since we treat the plunger position as linearly proportional to the voltage level. In other words, the "processing" is simply a multiplication, which takes less than a microsecond on the controller's CPU.

The timing statistics are provided mostly as a sanity check, to help determine if things are working as expected. There isn't anything you can do in the configuration to adjust these directly. If the times displayed aren't in the right ballpark, there might be a problem with the software or with your setup that bears looking into.

A couple of notes on the timing. First, the image update rate that you see in the setup window will be much slower than what you see in the statistics. The USB transfer to send the full image to the PC takes a lot longer than reading the image on the microcontroller. This overhead doesn't apply during normal operations - the controller normally analyzes the pixels all by itself and never sends them to the PC. So the statistics really do reflect what's going on in the controller, even though the viewer window can't display updates at the same speed. Second, for the TSL1410R sensor, the "processing time" and "scan time" happen concurrently, because the sensor is already snapping the next photo and transferring it to the controller while the controller is analyzing the previous one. This means that the true frame rate is basically determined by the longer of the sensor scan time and the processing time.

## Contrast enhancement

For a pixel-based sensor, click the "Enhance contrast" checkbox to exaggerate the contrast level in the displayed pixel readout. This makes the display show the bright pixels brighter than they really are, and the dark pixels darker than they really are.

This can be helpful when fine-tuning your sensor installation. The image analysis routines on the KL25Z generally work by finding the dark and light regions in the image, and the edges between regions. Exaggerating the contrast can make this structure more apparent when the physical light level is relatively uniform.

Enhanced contrast is purely a display option. It doesn't in any way affect the way the readings are taken from the sensor, or how the KL25Z processes the readings. In fact, the KL25Z doesn't even know you're using the enhanced contrast; the only effect is on the on-screen display.

## Full resolution and low res

If you're using an image sensor, the Full resolution and Low resolution buttons let you select how many pixels you want to view in the dialog. This doesn't affect how the controller reads the sensor; it only affects the visualization in the dialog. The low res mode is offered simply to let you speed up the frame rate displayed in the dialog.

The resolution setting doesn't change anything outside of the dialog. It has absolutely no effect on how the controller reads the sensor or reports the plunger position in normal pinball play. It also has no effect even within the dialog for non-imaging sensors.

## Jitter Filter

No measuring device is perfect, including the plunger sensors. All sensors have some inherent inaccuracies, which means that they won't always get exactly the same reading twice in a row even when the plunger itself is sitting perfectly still.

On a virtual cab, we don't merely have to take two readings in a row: we have to take readings constantly, tens or hundreds of times per second. We want the game to respond immediately when you move the plunger, so we have to know where it is from moment to moment. With such a rapid series of readings, any inaccuracies in the sensor become apparent on-screen as "jitter", meaning that the virtual plunger jiggles around slightly even when the real plunger is sitting perfectly still.

The "jitter filter" is a special feature in the firmware that lets you filter out this type of random motion to make the on-screen animation more stable and realistic. If your on-screen plunger jitters noticeably, you can use the filter to reduce this. Some sensors need this more than others, so you might not need it at all. If your sensor produces stable animation without the filter, you're better off keeping the filter disabled.

The filter works by setting a "window" size for random motion. Any motion within this window is ignored, so the on-screen plunger will remain motionless even if the sensor readings are fluctuating within the boundaries of the window. The window size is set in terms of the native units for the sensor, which are the same units shown in the sensor display in the plunger viewer window.

Larger window sizes produce stronger filtering, but they also reducing the usable precision of the plunger. Use the lowest setting that produces satisfactory results on your machine. You can disable the filter entirely by setting the window size to 0 (zero).

To help you set up the filter, the viewer window provides a visualization of the filter and its effects. When you enable the filter (by setting a non-zero window size), the green bar at the bottom of the sensor window shows the filtered position, which is what Visual Pinball sees. You'll also see a light green box at the end of the bar; this shows you the current bounds of the filter window. And within the box, a red line shows you the raw position reading from the sensor, before the filter was applied.

The goal is to make the filter window just big enough to contain the random motion, if any, of the raw reading, shown by the red line. With the plunger at rest, start with a small filter window setting, and observe the effect for a little while. If the red line jiggles around so much that the window has to keep jumping around to keep up, increase the window size slightly; repeat until you find a window big enough to contain the random noise.