Diff: main.cpp

Revision:

17:ab3cec0c8bf4

Parent:

16:c35f905c3311

Child:

18:5e890ebd0023

diff -r c35f905c3311 -r ab3cec0c8bf4 main.cpp
--- a/main.cpp	Mon Dec 29 19:27:52 2014 +0000
+++ b/main.cpp	Fri Feb 27 04:14:04 2015 +0000
@@ -19,96 +19,81 @@
 //
 // Pinscape Controller
 //
-// "Pinscape" is the name of my custom-built virtual pinball cabinet.  I wrote this
-// software to perform a number of tasks that I needed for my cabinet.  It runs on a
-// Freescale KL25Z microcontroller, which is a small and inexpensive device that
-// attaches to the host PC via USB and can interface with numerous types of external
-// hardware.
+// "Pinscape" is the name of my custom-built virtual pinball cabinet, so I call this
+// software the Pinscape Controller.  I wrote it to handle several tasks that I needed
+// for my cabinet.  It runs on a Freescale KL25Z microcontroller, which is a small and 
+// inexpensive device that attaches to the cabinet PC via a USB cable, and can attach
+// via custom wiring to sensors, buttons, and other devices in the cabinet.
 //
-// I designed the software and hardware in this project especially for Pinscape, but 
-// it uses standard interfaces in Windows and Visual Pinball, so it should be
-// readily usable in anyone else's VP-based cabinet.  I've tried to document the
-// hardware in enough detail for anyone else to duplicate the entire project, and
-// the full software is open source.
+// I designed the software and hardware in this project especially for my own
+// cabinet, but it uses standard interfaces in Windows and Visual Pinball, so it should
+// work in any VP-based cabinet, as long as you're using the usual VP software suite.  
+// I've tried to document the hardware in enough detail for anyone else to duplicate 
+// the entire project, and the full software is open source.
 //
-// The device appears to the host computer as a USB joystick.  This works with the
-// standard Windows joystick device drivers, so there's no need to install any
-// software on the PC - Windows should recognize it as a joystick when you plug
-// it in and shouldn't ask you to install anything.  If you bring up the control
-// panel for USB Game Controllers, this device will appear as "Pinscape Controller".
-// *Don't* do any calibration with the Windows control panel or third-part 
-// calibration tools.  The device calibrates itself automatically for the
-// accelerometer data, and has its own special calibration procedure for the
-// plunger (see below).
-//
-// The controller provides the following functions.  It should be possible to use
-// any subet of the features without using all of them.  External hardware for any
-// particular function can simply be omitted if that feature isn't needed.
+// The Freescale board appears to the host PC as a standard USB joystick.  This works 
+// with the built-in Windows joystick device drivers, so there's no need to install any
+// new drivers or other software on the PC.  Windows should recognize the Freescale
+// as a joystick when you plug it into the USB port, and Windows shouldn't ask you to 
+// install any drivers.  If you bring up the Windows control panel for USB Game 
+// Controllers, this device will appear as "Pinscape Controller".  *Don't* do any 
+// calibration with the Windows control panel or third-part calibration tools.  The 
+// software calibrates the accelerometer portion automatically, and has its own special
+// calibration procedure for the plunger sensor, if you're using that (see below).
 //
-//  - Nudge sensing via the KL25Z's on-board accelerometer.  Nudge accelerations are
-//    processed into a physics model of a rolling ball, and changes to the ball's
-//    motion are sent to the host computer via the joystick interface.  This is designed
-//    especially to work with Visuall Pinball's nudge handling to produce realistic 
-//    on-screen results in VP.  By doing some physics modeling right on the device, 
-//    rather than sending raw accelerometer data to VP, we can produce better results
-//    using our awareness of the real physical parameters of a pinball cabinet.
-//    VP's nudge handling has to be more generic, so it can't make the same sorts
-//    of assumptions that we can about the dynamics of a real cabinet.
+// This software provides a whole bunch of separate features.  You can use any of these 
+// features individually or all together.  If you're not using a particular feature, you
+// can simply omit the extra wiring and/or hardware for that feature.  You can use
+// the nudging feature by itself without any extra hardware attached, since the
+// accelerometer is built in to the KL25Z board.
 //
-//    The nudge data reports are compatible with the built-in Windows USB joystick 
-//    drivers and with VP's own joystick input scheme, so the nudge sensing is almost 
-//    plug-and-play.  There are no Windiows drivers to install, and the only VP work 
-//    needed is to customize a few global preference settings.
+//  - Nudge sensing via the KL25Z's on-board accelerometer.  Nudging the cabinet
+//    causes small accelerations that the accelerometer can detect; these are sent to
+//    Visual Pinball via the joystick interface so that VP can simulate the effect
+//    of the real physical nudges on its simulated ball.  VP has native handling for
+//    this type of input, so all you have to do is set some preferences in VP to tell 
+//    it that an accelerometer is attached.
 //
 //  - Plunger position sensing via an attached TAOS TSL 1410R CCD linear array sensor.  
-//    The sensor must be wired to a particular set of I/O ports on the KL25Z, and must 
-//    be positioned adjacent to the plunger with proper lighting.  The physical and
-//    electronic installation details are desribed in the project documentation.  We read 
-//    the CCD to determine how far back the plunger is pulled, and report this to Visual 
-//    Pinball via the joystick interface.  As with the nudge data, this is all nearly
-//    plug-and-play, in that it works with the default Windows USB drivers and works 
-//    with the existing VP handling for analog plunger input.  A few VP settings are
-//    needed to tell VP to allow the plunger.
+//    To use this feature, you need to buy the TAOS device (it's not built in to the
+//    KL25Z, obviously), wire it to the KL25Z (5 wire connections between the two
+//    devices are required), and mount the TAOS sensor in your cabinet so that it's
+//    positioned properly to capture images of the physical plunger shooter rod.
+//
+//    The physical mounting and wiring details are desribed in the project 
+//    documentation.  
+//
+//    If the CCD is attached, the software constantly captures images from the CCD
+//    and analyzes them to determine how far back the plunger is pulled.  It reports
+//    this to Visual Pinball via the joystick interface.  This allows VP to make the
+//    simulated on-screen plunger track the motion of the physical plunger in real
+//    time.  As with the nudge data, VP has native handling for the plunger input, 
+//    so you just need to set the VP preferences to tell it that an analog plunger 
+//    device is attached.  One caveat, though: although VP itself has built-in 
+//    support for an analog plunger, not all existing tables take advantage of it.  
+//    Many existing tables have their own custom plunger scripting that doesn't
+//    cooperate with the VP plunger input.  All tables *can* be made to work with
+//    the plunger, and in most cases it only requires some simple script editing,
+//    but in some cases it requires some more extensive surgery.
 //
 //    For best results, the plunger sensor should be calibrated.  The calibration
 //    is stored in non-volatile memory on board the KL25Z, so it's only necessary
 //    to do the calibration once, when you first install everything.  (You might
 //    also want to re-calibrate if you physically remove and reinstall the CCD 
-//    sensor or the mechanical plunger, since their alignment might change slightly 
-//    when you put everything back together.)  To calibrate, you have to attach a
-//    momentary switch (e.g., a push-button switch) between one of the KL25Z ground
-//    pins (e.g., jumper J9 pin 12) and PTE29 (J10 pin 9).  Press and hold the
-//    button for about two seconds - the LED on the KL25Z wlil flash blue while
-//    you hold the button, and will turn solid blue when you've held it down long
-//    enough to enter calibration mode.  This mode will last about 15 seconds.
-//    Simply pull the plunger all the way back, hold it for a few moments, and
-//    gradually return it to the starting position.  *Don't* release it - we want
-//    to measure the maximum retracted position and the rest position, but NOT
-//    the maximum forward position when the outer barrel spring is compressed.
-//    After about 15 seconds, the device will save the new calibration settings
-//    to its flash memory, and the LED will return to the regular "heartbeat" 
-//    flashes.  If this is the first time you calibrated, you should observe the
-//    color of the flashes change from yellow/green to blue/green to indicate
-//    that the plunger has been calibrated.
+//    sensor or the mechanical plunger, since their alignment shift change slightly 
+//    when you put everything back together.)  You can optionally install a
+//    dedicated momentary switch or pushbutton to activate the calibration mode;
+//    this is describe in the project documentation.  If you don't want to bother
+//    with the extra button, you can also trigger calibration using the Windows 
+//    setup software, which you can find on the Pinscape project page.
 //
-//    Note that while Visual Pinball itself has good native support for analog 
-//    plungers, most of the VP tables in circulation don't implement the necessary
-//    scripting features to make this work properly.  Therefore, you'll have to do
-//    a little scripting work for each table you download to add the required code
-//    to that individual table.  The work has to be customized for each table, so
-//    I haven't been able to automate this process, but I have tried to reduce it
-//    to a relatively simple recipe that I've documented separately.
-//
-//  - In addition to the CCD sensor, a button should be attached (also described in 
-//    the project documentation) to activate calibration mode for the plunger.  When 
-//    calibration mode is activated, the software reads the plunger position for about 
-//    10 seconds when to note the limits of travel, and uses these limits to ensure
-//    accurate reports to VP that properly report the actual position of the physical
-//    plunger.  The calibration is stored in non-volatile memory on the KL25Z, so it's
-//    only necessary to calibrate once - the calibration will survive power cycling
-//    and reboots of the PC.  It's only necessary to recalibrate if the CCD sensor or
-//    the plunger are removed and reinstalled, since the relative alignment of the
-//    parts could cahnge slightly when reinstalling.
+//    The calibration procedure is described in the project documentation.  Briefly,
+//    when you trigger calibration mode, the software will scan the CCD for about
+//    15 seconds, during which you should simply pull the physical plunger back
+//    all the way, hold it for a moment, and then slowly return it to the rest
+//    position.  (DON'T just release it from the retracted position, since that
+//    let it shoot forward too far.  We want to measure the range from the park
+//    position to the fully retracted position only.)
 //
 //  - Button input wiring.  24 of the KL25Z's GPIO ports are mapped as digital inputs
 //    for buttons and switches.  The software reports these as joystick buttons when
@@ -229,13 +214,20 @@
 #include "FreescaleIAP.h"
 #include "crc32.h"
 
+// our local configuration file
+#include "config.h"
+
 
 // ---------------------------------------------------------------------------
-//
-// Configuration details
+// utilities
+
+// number of elements in an array
+#define countof(x) (sizeof(x)/sizeof((x)[0]))
+
+
+// ---------------------------------------------------------------------------
+// USB device vendor ID, product ID, and version.  
 //
-
-// Our USB device vendor ID, product ID, and version.  
 // We use the vendor ID for the LedWiz, so that the PC-side software can
 // identify us as capable of performing LedWiz commands.  The LedWiz uses
 // a product ID value from 0xF0 to 0xFF; the last four bits identify the
@@ -249,13 +241,6 @@
 // single LedWiz already installed in your cabinet, and you didn't ask for
 // a non-default unit number, your existing LedWiz will be unit 0.
 //
-// We use unit #7 by default.  There doesn't seem to be a requirement that
-// unit numbers be contiguous (DirectOutput Framework and other software
-// seem happy to have units 0 and 7 installed, without 1-6 existing).
-// Marking this unit as #7 should work for almost everybody out of the box;
-// the most common case seems to be to have a single LedWiz installed, and
-// it's probably extremely rare to more than two.
-//
 // Note that the USB_PRODUCT_ID value set here omits the unit number.  We
 // take the unit number from the saved configuration.  We provide a
 // configuration command that can be sent via the USB connection to change
@@ -266,235 +251,29 @@
 const uint16_t USB_VENDOR_ID = 0xFAFA;
 const uint16_t USB_PRODUCT_ID = 0x00F0;
 const uint16_t USB_VERSION_NO = 0x0006;
-const uint8_t DEFAULT_LEDWIZ_UNIT_NUMBER = 0x07;
 
-// Number of pixels we read from the sensor on each frame.  This can be
-// less than the physical pixel count if desired; we'll read every nth
-// piexl if so.  E.g., with a 1280-pixel physical sensor, if npix is 320,
-// we'll read every 4th pixel.  It takes time to read each pixel, so the
-// fewer pixels we read, the higher the refresh rate we can achieve.
-// It's therefore better not to read more pixels than we have to.
-//
-// VP seems to have an internal resolution in the 8-bit range, so there's
-// no apparent benefit to reading more than 128-256 pixels when using VP.
-// Empirically, 160 pixels seems about right.  The overall travel of a
-// standard pinball plunger is about 3", so 160 pixels gives us resolution
-// of about 1/50".  This seems to take full advantage of VP's modeling
-// ability, and is probably also more precise than a human player's
-// perception of the plunger position.
-const int npix = 160;
-
-// On-board RGB LED elements - we use these for diagnostic displays.
-DigitalOut ledR(LED1), ledG(LED2), ledB(LED3);
-
-// calibration button - switch input and LED output
-DigitalIn calBtn(PTE29);
-DigitalOut calBtnLed(PTE23);
-
-// Joystick button input pin assignments.  You can wire up to
-// 32 GPIO ports to buttons (equipped with momentary switches).
-// Connect each switch between the desired GPIO port and ground
-// (J9 pin 12 or 14).  When the button is pressed, we'll tell the
-// host PC that the corresponding joystick button is pressed.  We
-// debounce the keystrokes in software, so you can simply wire
-// directly to pushbuttons with no additional external hardware.
-//
-// Note that we assign 24 buttons by default, even though the USB
-// joystick interface can handle up to 32 buttons.  VP itself only
-// allows mapping of up to 24 buttons in the preferences dialog 
-// (although it can recognize 32 buttons internally).  If you want 
-// more buttons, you can reassign pins that are assigned by default
-// as LedWiz outputs.  To reassign a pin, find the pin you wish to
-// reassign in the LedWizPortMap array below, and change the pin name 
-// there to NC (for Not Connected).  You can then change one of the
-// "NC" entries below to the reallocated pin name.  The limit is 32
-// buttons total.
-//
-// Note: PTD1 (pin J2-12) should NOT be assigned as a button input,
-// as this pin is physically connected on the KL25Z to the on-board
-// indicator LED's blue segment.  This precludes any other use of
-// the pin.
-PinName buttonMap[] = {
-    PTC2,      // J10 pin 10, joystick button 1
-    PTB3,      // J10 pin 8,  joystick button 2
-    PTB2,      // J10 pin 6,  joystick button 3
-    PTB1,      // J10 pin 4,  joystick button 4
-    
-    PTE30,     // J10 pin 11, joystick button 5
-    PTE22,     // J10 pin 5,  joystick button 6
-    
-    PTE5,      // J9 pin 15,  joystick button 7
-    PTE4,      // J9 pin 13,  joystick button 8
-    PTE3,      // J9 pin 11,  joystick button 9
-    PTE2,      // J9 pin 9,   joystick button 10
-    PTB11,     // J9 pin 7,   joystick button 11
-    PTB10,     // J9 pin 5,   joystick button 12
-    PTB9,      // J9 pin 3,   joystick button 13
-    PTB8,      // J9 pin 1,   joystick button 14
-    
-    PTC12,     // J2 pin 1,   joystick button 15
-    PTC13,     // J2 pin 3,   joystick button 16
-    PTC16,     // J2 pin 5,   joystick button 17
-    PTC17,     // J2 pin 7,   joystick button 18
-    PTA16,     // J2 pin 9,   joystick button 19
-    PTA17,     // J2 pin 11,  joystick button 20
-    PTE31,     // J2 pin 13,  joystick button 21
-    PTD6,      // J2 pin 17,  joystick button 22
-    PTD7,      // J2 pin 19,  joystick button 23
-    
-    PTE1,      // J2 pin 20,  joystick button 24
-
-    NC,        // not used,   joystick button 25
-    NC,        // not used,   joystick button 26
-    NC,        // not used,   joystick button 27
-    NC,        // not used,   joystick button 28
-    NC,        // not used,   joystick button 29
-    NC,        // not used,   joystick button 30
-    NC,        // not used,   joystick button 31
-    NC         // not used,   joystick button 32
-};
-
-// LED-Wiz emulation output pin assignments.  
-//
-// The LED-Wiz protocol allows setting individual intensity levels
-// on all outputs, with 48 levels of intensity.  This can be used
-// to control lamp brightness and motor speeds, among other things.
-// Unfortunately, the KL25Z only has 10 PWM channels, so while we 
-// can support the full complement of 32 outputs, we can only provide 
-// PWM dimming/speed control on 10 of them.  The remaining outputs 
-// can only be switched fully on and fully off - we can't support
-// dimming on these, so they'll ignore any intensity level setting 
-// requested by the host.  Use these for devices that don't have any
-// use for intensity settings anyway, such as contactors and knockers.
-//
-// Ports with pins assigned as "NC" are not connected.  That is,
-// there's no physical pin for that LedWiz port number.  You can
-// send LedWiz commands to turn NC ports on and off, but doing so
-// will have no effect.  The reason we leave some ports unassigned
-// is that we don't have enough physical GPIO pins to fill out the
-// full LedWiz complement of 32 ports.  Many pins are already taken
-// for other purposes, such as button inputs or the plunger CCD
-// interface.
-//
-// The mapping between physical output pins on the KL25Z and the
-// assigned LED-Wiz port numbers is essentially arbitrary - you can
-// customize this by changing the entries in the array below if you
-// wish to rearrange the pins for any reason.  Be aware that some
-// of the physical outputs are already used for other purposes
-// (e.g., some of the GPIO pins on header J10 are used for the
-// CCD sensor - but you can of course reassign those as well by
-// changing the corresponding declarations elsewhere in this module).
-// The assignments we make here have two main objectives: first,
-// to group the outputs on headers J1 and J2 (to facilitate neater
-// wiring by keeping the output pins together physically), and
-// second, to make the physical pin layout match the LED-Wiz port
-// numbering order to the extent possible.  There's one big wrench
-// in the works, though, which is the limited number and discontiguous
-// placement of the KL25Z PWM-capable output pins.  This prevents
-// us from doing the most obvious sequential ordering of the pins,
-// so we end up with the outputs arranged into several blocks.
-// Hopefully this isn't too confusing; for more detailed rationale,
-// read on...
-// 
-// With the LED-Wiz, the host software configuration usually 
-// assumes that each RGB LED is hooked up to three consecutive ports
-// (for the red, green, and blue components, which need to be 
-// physically wired to separate outputs to allow each color to be 
-// controlled independently).  To facilitate this, we arrange the 
-// PWM-enabled outputs so that they're grouped together in the 
-// port numbering scheme.  Unfortunately, these outputs aren't
-// together in a single group in the physical pin layout, so to
-// group them logically in the LED-Wiz port numbering scheme, we
-// have to break up the overall numbering scheme into several blocks.
-// So our port numbering goes sequentially down each column of
-// header pins, but there are several break points where we have
-// to interrupt the obvious sequence to keep the PWM pins grouped
-// logically.
-//
-// In the list below, "pin J1-2" refers to pin 2 on header J1 on
-// the KL25Z, using the standard pin numbering in the KL25Z 
-// documentation - this is the physical pin that the port controls.
-// "LW port 1" means LED-Wiz port 1 - this is the LED-Wiz port
-// number that you use on the PC side (in the DirectOutput config
-// file, for example) to address the port.  PWM-capable ports are
-// marked as such - we group the PWM-capable ports into the first
-// 10 LED-Wiz port numbers.
-//
-// If you wish to reallocate a pin in the array below to some other
-// use, such as a button input port, simply change the pin name in
-// the entry to NC (for Not Connected).  This will disable the given
-// logical LedWiz port number and free up the physical pin.
-//
-// If you wish to reallocate a pin currently assigned to the button
-// input array, simply change the entry for the pin in the buttonMap[]
-// array above to NC (for "not connected"), and plug the pin name into
-// a slot of your choice in the array below.
-//
-// Note: PTD1 (pin J2-12) should NOT be assigned as an LedWiz output,
-// as this pin is physically connected on the KL25Z to the on-board
-// indicator LED's blue segment.  This precludes any other use of
-// the pin.
-// 
-struct {
-    PinName pin;
-    bool isPWM;
-} ledWizPortMap[32] = {
-    { PTA1, true },      // pin J1-2,  LW port 1  (PWM capable - TPM 2.0 = channel 9)
-    { PTA2, true },      // pin J1-4,  LW port 2  (PWM capable - TPM 2.1 = channel 10)
-    { PTD4, true },      // pin J1-6,  LW port 3  (PWM capable - TPM 0.4 = channel 5)
-    { PTA12, true },     // pin J1-8,  LW port 4  (PWM capable - TPM 1.0 = channel 7)
-    { PTA4, true },      // pin J1-10, LW port 5  (PWM capable - TPM 0.1 = channel 2)
-    { PTA5, true },      // pin J1-12, LW port 6  (PWM capable - TPM 0.2 = channel 3)
-    { PTA13, true },     // pin J2-2,  LW port 7  (PWM capable - TPM 1.1 = channel 13)
-    { PTD5, true },      // pin J2-4,  LW port 8  (PWM capable - TPM 0.5 = channel 6)
-    { PTD0, true },      // pin J2-6,  LW port 9  (PWM capable - TPM 0.0 = channel 1)
-    { PTD3, true },      // pin J2-10, LW port 10 (PWM capable - TPM 0.3 = channel 4)
-    { PTD2, false },     // pin J2-8,  LW port 11
-    { PTC8, false },     // pin J1-14, LW port 12
-    { PTC9, false },     // pin J1-16, LW port 13
-    { PTC7, false },     // pin J1-1,  LW port 14
-    { PTC0, false },     // pin J1-3,  LW port 15
-    { PTC3, false },     // pin J1-5,  LW port 16
-    { PTC4, false },     // pin J1-7,  LW port 17
-    { PTC5, false },     // pin J1-9,  LW port 18
-    { PTC6, false },     // pin J1-11, LW port 19
-    { PTC10, false },    // pin J1-13, LW port 20
-    { PTC11, false },    // pin J1-15, LW port 21
-    { PTE0, false },     // pin J2-18, LW port 22
-    { NC, false },       // Not used,  LW port 23
-    { NC, false },       // Not used,  LW port 24
-    { NC, false },       // Not used,  LW port 25
-    { NC, false },       // Not used,  LW port 26
-    { NC, false },       // Not used,  LW port 27
-    { NC, false },       // Not used,  LW port 28
-    { NC, false },       // Not used,  LW port 29
-    { NC, false },       // Not used,  LW port 30
-    { NC, false },       // Not used,  LW port 31
-    { NC, false }        // Not used,  LW port 32
-};
-
-
-// I2C address of the accelerometer (this is a constant of the KL25Z)
-const int MMA8451_I2C_ADDRESS = (0x1d<<1);
-
-// SCL and SDA pins for the accelerometer (constant for the KL25Z)
-#define MMA8451_SCL_PIN   PTE25
-#define MMA8451_SDA_PIN   PTE24
-
-// Digital in pin to use for the accelerometer interrupt.  For the KL25Z,
-// this can be either PTA14 or PTA15, since those are the pins physically
-// wired on this board to the MMA8451 interrupt controller.
-#define MMA8451_INT_PIN   PTA15
 
 // Joystick axis report range - we report from -JOYMAX to +JOYMAX
 #define JOYMAX 4096
 
 
-// ---------------------------------------------------------------------------
-// utilities
+// --------------------------------------------------------------------------
+//
+// Potentiometer configuration
+//
+#ifdef POT_SENSOR_ENABLED
+#define IF_POT(x) x
+#else
+#define IF_POT(x)
+#endif
 
-// number of elements in an array
-#define countof(x) (sizeof(x)/sizeof((x)[0]))
+
+// ---------------------------------------------------------------------------
+//
+// On-board RGB LED elements - we use these for diagnostic displays.
+//
+DigitalOut ledR(LED1), ledG(LED2), ledB(LED3);
+
 
 // ---------------------------------------------------------------------------
 //
@@ -701,48 +480,79 @@
     return buttons;
 }
 
-// Read buttons with debouncing.  We keep a circular buffer
-// of recent input readings.  We'll AND together the status of
-// each button over the past 50ms.  A button that has been on
-// continuously for 50ms will be reported as ON.  All others
-// will be reported as OFF.
+// Read buttons with debouncing.  
+//
+// Debouncing is the process of filtering out transients from button
+// state changes.  When an electrical switch is closed or opened, the
+// signal can have a brief period of instability that makes the switch
+// appear to turn on and off very rapidly.  This is known as "bouncing".
+//
+// To remove the transients, we filter the signal by requiring each 
+// change to stick for at least a minimum interval (we use 50ms).  We
+// keep a short recent history of each button's state for this purpose.
+// If we see a button change state, we ignore the change if we saw the
+// same button make another change within the same interval.
 uint32_t readButtonsDebounced()
 {
     struct reading {
-        int dt;           // time since previous reading
-        uint32_t b;       // button state at this reading
+        // elapsed time between this reading and the previous reading
+        int dt;
+        
+        // Final button state for each button that changed on this
+        // report.  OR this with a new report (after applying the
+        // mask 'm') to carry forward the changes that occurred in
+        // this report to the new report.
+        uint32_t b;
+        
+        // Change mask at this report.  This is a bit mask of the buttons
+        // that *didn't* change on this report.  AND this mask with a
+        // new reading to filter buttons out of the new reading that
+        // changed on this report.
+        uint32_t m;
     };
     static reading readings[8];  // circular buffer of readings
     static int ri = 0;    // reading buffer index (next write position)
+    static int bPrv = 0;  // immediately previous report
         
     // get the write pointer
     reading *r = &readings[ri];
 
     // figure the time since the last reading, and read the raw button state
-    r->dt = buttonTimer.read_ms();
-    uint32_t b = r->b = readButtonsRaw();
+    int ms = r->dt = buttonTimer.read_ms();
+    uint32_t b = readButtonsRaw();
     
     // start timing the next interval
     buttonTimer.reset();
     
-    // AND together readings over 25ms
-    int ms = 0;
-    for (int i = 1 ; i < countof(readings) && ms < 25 ; ++i)
+    // mask out changes for any buttons that changed state within the
+    // past 50ms
+    for (int i = 1 ; i < countof(readings) && ms < 50 ; ++i)
     {
         // find the next prior reading, wrapping in the circular buffer
         int j = ri - i;
         if (j < 0) 
             j = countof(readings) - 1;
-            
         reading *rj = &readings[j];
-        
-        // AND the buttons for this reading
-        b &= rj->b;
-        
-        // count the time
+
+        // For any button that changed state in the prior reading 'rj',
+        // remove any new change and restore it to its 'rj' state.
+        b &= rj->m;
+        b |= rj->b;
+                
+        // add in the time to the next prior report
         ms += rj->dt;
     }
     
+    // figure which buttons changed on this report vs the prior report
+    uint32_t m = b ^ bPrv;
+    
+    // save the change mask and changed button vector in our history entry
+    r->m = ~m;
+    r->b = b & m;
+    
+    // save this as the prior report
+    bPrv = b;
+    
     // advance the write position for next time
     ri += 1;
     if (ri >= countof(readings)) 
@@ -754,88 +564,6 @@
 
 // ---------------------------------------------------------------------------
 //
-// Non-volatile memory (NVM)
-//
-
-// Structure defining our NVM storage layout.  We store a small
-// amount of persistent data in flash memory to retain calibration
-// data when powered off.
-struct NVM
-{
-    // checksum - we use this to determine if the flash record
-    // has been properly initialized
-    uint32_t checksum;
-
-    // signature value
-    static const uint32_t SIGNATURE = 0x4D4A522A;
-    static const uint16_t VERSION = 0x0003;
-    
-    // Is the data structure valid?  We test the signature and 
-    // checksum to determine if we've been properly stored.
-    int valid() const
-    {
-        return (d.sig == SIGNATURE 
-                && d.vsn == VERSION
-                && d.sz == sizeof(NVM)
-                && checksum == CRC32(&d, sizeof(d)));
-    }
-    
-    // save to non-volatile memory
-    void save(FreescaleIAP &iap, int addr)
-    {
-        // update the checksum and structure size
-        checksum = CRC32(&d, sizeof(d));
-        d.sz = sizeof(NVM);
-        
-        // erase the sector
-        iap.erase_sector(addr);
-
-        // save the data
-        iap.program_flash(addr, this, sizeof(*this));
-    }
-    
-    // reset calibration data for calibration mode
-    void resetPlunger()
-    {
-        // set extremes for the calibration data
-        d.plungerMax = 0;
-        d.plungerZero = npix;
-        d.plungerMin = npix;
-    }
-    
-    // stored data (excluding the checksum)
-    struct
-    {
-        // Signature, structure version, and structure size - further verification 
-        // that we have valid initialized data.  The size is a simple proxy for a
-        // structure version, as the most common type of change to the structure as
-        // the software evolves will be the addition of new elements.  We also
-        // provide an explicit version number that we can update manually if we
-        // make any changes that don't affect the structure size but would affect
-        // compatibility with a saved record (e.g., swapping two existing elements).
-        uint32_t sig;
-        uint16_t vsn;
-        int sz;
-        
-        // has the plunger been manually calibrated?
-        int plungerCal;
-        
-        // plunger calibration min and max
-        int plungerMin;
-        int plungerZero;
-        int plungerMax;
-        
-        // is the CCD enabled?
-        int ccdEnabled;
-        
-        // LedWiz unit number
-        uint8_t ledWizUnitNo;
-    } d;
-};
-
-
-// ---------------------------------------------------------------------------
-//
 // Customization joystick subbclass
 //
 
@@ -904,6 +632,19 @@
 // of nudging, say).
 //
 
+// I2C address of the accelerometer (this is a constant of the KL25Z)
+const int MMA8451_I2C_ADDRESS = (0x1d<<1);
+
+// SCL and SDA pins for the accelerometer (constant for the KL25Z)
+#define MMA8451_SCL_PIN   PTE25
+#define MMA8451_SDA_PIN   PTE24
+
+// Digital in pin to use for the accelerometer interrupt.  For the KL25Z,
+// this can be either PTA14 or PTA15, since those are the pins physically
+// wired on this board to the MMA8451 interrupt controller.
+#define MMA8451_INT_PIN   PTA15
+
+
 // accelerometer input history item, for gathering calibration data
 struct AccHist
 {
@@ -1191,6 +932,113 @@
 
 // ---------------------------------------------------------------------------
 //
+// Include the appropriate plunger sensor definition.  This will define a
+// class called PlungerSensor, with a standard interface that we use in
+// the main loop below.  This is *kind of* like a virtual class interface,
+// but it actually defines the methods statically, which is a little more
+// efficient at run-time.  There's no need for a true virtual interface
+// because we don't need to be able to change sensor types on the fly.
+//
+
+#ifdef ENABLE_CCD_SENSOR
+#include "ccdSensor.h"
+#elif ENABLE_POT_SENSOR
+#include "potSensor.h"
+#else
+#include "nullSensor.h"
+#endif
+
+
+// ---------------------------------------------------------------------------
+//
+// Non-volatile memory (NVM)
+//
+
+// Structure defining our NVM storage layout.  We store a small
+// amount of persistent data in flash memory to retain calibration
+// data when powered off.
+struct NVM
+{
+    // checksum - we use this to determine if the flash record
+    // has been properly initialized
+    uint32_t checksum;
+
+    // signature value
+    static const uint32_t SIGNATURE = 0x4D4A522A;
+    static const uint16_t VERSION = 0x0003;
+    
+    // Is the data structure valid?  We test the signature and 
+    // checksum to determine if we've been properly stored.
+    int valid() const
+    {
+        return (d.sig == SIGNATURE 
+                && d.vsn == VERSION
+                && d.sz == sizeof(NVM)
+                && checksum == CRC32(&d, sizeof(d)));
+    }
+    
+    // save to non-volatile memory
+    void save(FreescaleIAP &iap, int addr)
+    {
+        // update the checksum and structure size
+        checksum = CRC32(&d, sizeof(d));
+        d.sz = sizeof(NVM);
+        
+        // erase the sector
+        iap.erase_sector(addr);
+
+        // save the data
+        iap.program_flash(addr, this, sizeof(*this));
+    }
+    
+    // reset calibration data for calibration mode
+    void resetPlunger()
+    {
+        // set extremes for the calibration data
+        d.plungerMax = 0;
+        d.plungerZero = npix;
+        d.plungerMin = npix;
+    }
+    
+    // stored data (excluding the checksum)
+    struct
+    {
+        // Signature, structure version, and structure size - further verification 
+        // that we have valid initialized data.  The size is a simple proxy for a
+        // structure version, as the most common type of change to the structure as
+        // the software evolves will be the addition of new elements.  We also
+        // provide an explicit version number that we can update manually if we
+        // make any changes that don't affect the structure size but would affect
+        // compatibility with a saved record (e.g., swapping two existing elements).
+        uint32_t sig;
+        uint16_t vsn;
+        int sz;
+        
+        // has the plunger been manually calibrated?
+        int plungerCal;
+        
+        // Plunger calibration min, zero, and max.  The zero point is the 
+        // rest position (aka park position), where it's in equilibrium between 
+        // the main spring and the barrel spring.  It can travel a small distance
+        // forward of the rest position, because the barrel spring can be
+        // compressed by the user pushing on the plunger or by the momentum
+        // of a release motion.  The minimum is the maximum forward point where
+        // the barrel spring can't be compressed any further.
+        int plungerMin;
+        int plungerZero;
+        int plungerMax;
+        
+        // is the plunger sensor enabled?
+        int plungerEnabled;
+        
+        // LedWiz unit number
+        uint8_t ledWizUnitNo;
+    } d;
+};
+
+
+// ---------------------------------------------------------------------------
+//
 // Main program loop.  This is invoked on startup and runs forever.  Our
 // main work is to read our devices (the accelerometer and the CCD), process
 // the readings into nudge and plunger position data, and send the results
@@ -1239,11 +1087,11 @@
         cfg.d.sig = cfg.SIGNATURE;
         cfg.d.vsn = cfg.VERSION;
         cfg.d.plungerCal = 0;
-        cfg.d.plungerZero = 0;
-        cfg.d.plungerMin = 0;
-        cfg.d.plungerMax = npix;
+        cfg.d.plungerMin = 0;        // assume we can go all the way forward...
+        cfg.d.plungerMax = npix;     // ...and all the way back
+        cfg.d.plungerZero = npix/6;  // the rest position is usually around 1/2" back
         cfg.d.ledWizUnitNo = DEFAULT_LEDWIZ_UNIT_NUMBER;
-        cfg.d.ccdEnabled = true;
+        cfg.d.plungerEnabled = true;
     }
     
     // Create the joystick USB client.  Note that we use the LedWiz unit
@@ -1252,6 +1100,15 @@
         USB_VENDOR_ID, 
         USB_PRODUCT_ID | cfg.d.ledWizUnitNo,
         USB_VERSION_NO);
+        
+    // last report timer - we use this to throttle reports, since VP
+    // doesn't want to hear from us more than about every 10ms
+    Timer reportTimer;
+    reportTimer.start();
+
+    // initialize the calibration buttons, if present
+    DigitalIn *calBtn = (CAL_BUTTON_PIN == NC ? 0 : new DigitalIn(CAL_BUTTON_PIN));
+    DigitalOut *calBtnLed = (CAL_BUTTON_LED == NC ? 0 : new DigitalOut(CAL_BUTTON_LED));
 
     // plunger calibration button debounce timer
     Timer calBtnTimer;
@@ -1278,32 +1135,108 @@
     // create the accelerometer object
     Accel accel(MMA8451_SCL_PIN, MMA8451_SDA_PIN, MMA8451_I2C_ADDRESS, MMA8451_INT_PIN);
     
-    // create the CCD array object
-    TSL1410R ccd(PTE20, PTE21, PTB0);
+    // last accelerometer report, in joystick units (we report the nudge
+    // acceleration via the joystick x & y axes, per the VP convention)
+    int x = 0, y = 0;
+    
+    // create our plunger sensor object
+    PlungerSensor plungerSensor;
+
+    // last plunger report position, in 'npix' normalized pixel units
+    int pos = 0;
+    
+    // last plunger report, in joystick units (we report the plunger as the
+    // "z" axis of the joystick, per the VP convention)
+    int z = 0;
+    
+    // most recent prior plunger readings, for tracking release events(z0 is
+    // reading just before the last one we reported, z1 is the one before that, 
+    // z2 the next before that)
+    int z0 = 0, z1 = 0, z2 = 0;
+    
+    // Simulated "bounce" position when firing.  We model the bounce off of
+    // the barrel spring when the plunger is released as proportional to the
+    // distance it was retracted just before being released.
+    int zBounce = 0;
     
-    // last accelerometer report, in mouse coordinates
-    int x = 0, y = 0, z = 0;
+    // Simulated Launch Ball button state.  If a "ZB Launch Ball" port is
+    // defined for our LedWiz port mapping, any time that port is turned ON,
+    // we'll simulate pushing the Launch Ball button if the player pulls 
+    // back and releases the plunger, or simply pushes on the plunger from
+    // the rest position.  This allows the plunger to be used in lieu of a
+    // physical Launch Ball button for tables that don't have plungers.
+    //
+    // States:
+    //   0 = default
+    //   1 = cocked (plunger has been pulled back about 1" from state 0)
+    //   2 = uncocked (plunger is pulled back less than 1" from state 1)
+    //   3 = launching (plunger has been released from state 1 or 2, or 
+    //       pushed forward about 1/4" from state 0)
+    //   4 = launching, plunger is no longer pushed forward
+    int lbState = 0;
     
-    // previous two plunger readings, for "debouncing" the results (z0 is
-    // the most recent, z1 is the one before that)
-    int z0 = 0, z1 = 0, z2 = 0;
+    // Time since last lbState transition.  Some of the states are time-
+    // sensitive.  In the "uncocked" state, we'll return to state 0 if
+    // we remain in this state for more than a few milliseconds, since
+    // it indicates that the plunger is being slowly returned to rest
+    // rather than released.  In the "launching" state, we need to release 
+    // the Launch Ball button after a moment, and we need to wait for 
+    // the plunger to come to rest before returning to state 0.
+    Timer lbTimer;
+    lbTimer.start();
+    
+    // Simulated button states.  This is a vector of button states
+    // for the simulated buttons.  We combine this with the physical
+    // button states on each USB joystick report, so we will report
+    // a button as pressed if either the physical button is being pressed
+    // or we're simulating a press on the button.  This is used for the
+    // simulated Launch Ball button.
+    uint32_t simButtons = 0;
     
     // Firing in progress: we set this when we detect the start of rapid 
     // plunger movement from a retracted position towards the rest position.
-    // The actual plunger spring return speed seems to be too slow for VP, 
-    // so when we detect the start of this motion, we immediately tell VP
-    // to return the plunger to rest, then we monitor the real plunger 
-    // until it atcually stops.
+    //
+    // When we detect a firing event, we send VP a series of synthetic
+    // reports simulating the idealized plunger motion.  The actual physical
+    // motion is much too fast to report to VP; in the time between two USB
+    // reports, the plunger can shoot all the way forward, rebound off of
+    // the barrel spring, bounce back part way, and bounce forward again,
+    // or even do all of this more than once.  This means that sampling the 
+    // physical motion at the USB report rate would create a misleading 
+    // picture of the plunger motion, since our samples would catch the 
+    // plunger at random points in this oscillating motion.  From the 
+    // user's perspective, the physical action that occurred is simply that 
+    // the plunger was released from a particular distance, so it's this 
+    // high-level event that we want to convey to VP.  To do this, we
+    // synthesize a series of reports to convey an idealized version of
+    // the release motion that's perfectly synchronized to the VP reports.  
+    // Essentially we pretend that our USB position samples are exactly 
+    // aligned in time with (1) the point of retraction just before the 
+    // user released the plunger, (2) the point of maximum forward motion 
+    // just after the user released the plunger (the point of maximum 
+    // compression as the plunger bounces off of the barrel spring), and 
+    // (3) the plunger coming to rest at the park position.  This series
+    // of reports is synthetic in the sense that it's not what we actually
+    // see on the CCD at the times of these reports - the true plunger
+    // position is oscillating at high speed during this period.  But at
+    // the same time it conveys a more faithful picture of the true physical
+    // motion to VP, and allows VP to reproduce the true physical motion 
+    // more faithfully in its simulation model, by correcting for the
+    // relatively low sampling rate in the communication path between the
+    // real plunger and VP's model plunger.
+    //
+    // If 'firing' is non-zero, it's the index of our current report in
+    // the synthetic firing report series.
     int firing = 0;
 
     // start the first CCD integration cycle
-    ccd.clear();
+    plungerSensor.init();
     
     // Device status.  We report this on each update so that the host config
     // tool can detect our current settings.  This is a bit mask consisting
     // of these bits:
     //    0x01  -> plunger sensor enabled
-    uint16_t statusFlags = (cfg.d.ccdEnabled ? 0x01 : 0x00);
+    uint16_t statusFlags = (cfg.d.plungerEnabled ? 0x01 : 0x00);
     
     // flag: send a pixel dump after the next read
     bool reportPix = false;
@@ -1366,13 +1299,13 @@
                         
                         // set the configuration parameters from the message
                         cfg.d.ledWizUnitNo = newUnitNo;
-                        cfg.d.ccdEnabled = data[3] & 0x01;
+                        cfg.d.plungerEnabled = data[3] & 0x01;
                         
                         // update the status flags
                         statusFlags = (statusFlags & ~0x01) | (data[3] & 0x01);
                         
                         // if the ccd is no longer enabled, use 0 for z reports
-                        if (!cfg.d.ccdEnabled)
+                        if (!cfg.d.plungerEnabled)
                             z = 0;
                         
                         // save the configuration
@@ -1425,7 +1358,7 @@
         }
        
         // check for plunger calibration
-        if (!calBtn)
+        if (calBtn != 0 && !calBtn->read())
         {
             // check the state
             switch (calBtnState)
@@ -1516,283 +1449,321 @@
         {
             calBtnLit = newCalBtnLit;
             if (calBtnLit) {
-                calBtnLed = 1;
+                if (calBtnLed != 0)
+                    calBtnLed->write(1);
                 ledR = 1;
                 ledG = 1;
                 ledB = 0;
             }
             else {
-                calBtnLed = 0;
+                if (calBtnLed != 0)
+                    calBtnLed->write(0);
                 ledR = 1;
                 ledG = 1;
                 ledB = 1;
             }
         }
         
+        // If the plunger is enabled, and we're not already in a firing event,
+        // and the last plunger reading had the plunger pulled back at least
+        // a bit, watch for plunger release events until it's time for our next
+        // USB report.
+        if (!firing && cfg.d.plungerEnabled && z >= JOYMAX/6)
+        {
+            // monitor the plunger until it's time for our next report
+            while (reportTimer.read_ms() < 15)
+            {
+                // do a fast low-res scan; if it's at or past the zero point,
+                // start a firing event
+                if (plungerSensor.lowResScan() <= cfg.d.plungerZero)
+                    firing = 1;
+            }
+        }
+
         // read the plunger sensor, if it's enabled
-        uint16_t pix[npix];
-        if (cfg.d.ccdEnabled)
+        if (cfg.d.plungerEnabled)
         {
             // start with the previous reading, in case we don't have a
             // clear result on this frame
             int znew = z;
-
-            // read the array
-            ccd.read(pix, npix, ccdReadCB, 0, 3);
-    
-            // get the average brightness at each end of the sensor
-            long avg1 = (long(pix[0]) + long(pix[1]) + long(pix[2]) + long(pix[3]) + long(pix[4]))/5;
-            long avg2 = (long(pix[npix-1]) + long(pix[npix-2]) + long(pix[npix-3]) + long(pix[npix-4]) + long(pix[npix-5]))/5;
-            
-            // figure the midpoint in the brightness; multiply by 3 so that we can
-            // compare sums of three pixels at a time to smooth out noise
-            long midpt = (avg1 + avg2)/2 * 3;
-            
-            // Work from the bright end to the dark end.  VP interprets the
-            // Z axis value as the amount the plunger is pulled: zero is the
-            // rest position, and the axis maximum is fully pulled.  So we 
-            // essentially want to report how much of the sensor is lit,
-            // since this increases as the plunger is pulled back.
-            int si = 1, di = 1;
-            if (avg1 < avg2)
-                si = npix - 2, di = -1;
-    
-            // If the bright end and dark end don't differ by enough, skip this
-            // reading entirely - we must have an overexposed or underexposed frame.
-            // Otherwise proceed with the scan.
-            if (labs(avg1 - avg2) > 0x1000)
+            if (plungerSensor.highResScan(pos))
             {
-                uint16_t *pixp = pix + si;           
-                for (int n = 1 ; n < npix - 1 ; ++n, pixp += di)
+                // We got a new reading.  If we're in calibration mode, use it
+                // to figure the new calibration, otherwise adjust the new reading
+                // for the established calibration.
+                if (calBtnState == 3)
                 {
-                    // if we've crossed the midpoint, report this position
-                    if (long(pixp[-1]) + long(pixp[0]) + long(pixp[1]) < midpt)
-                    {
-                        // note the new position
-                        int pos = n;
+                    // Calibration mode.  If this reading is outside of the current
+                    // calibration bounds, expand the bounds.
+                    if (pos < cfg.d.plungerMin)
+                        cfg.d.plungerMin = pos;
+                    if (pos < cfg.d.plungerZero)
+                        cfg.d.plungerZero = pos;
+                    if (pos > cfg.d.plungerMax)
+                        cfg.d.plungerMax = pos;
                         
-                        // Calibrate, or apply calibration, depending on the mode.
-                        // In either case, normalize to our range.  VP appears to
-                        // ignore negative Z axis values.
-                        if (calBtnState == 3)
-                        {
-                            // calibrating - note if we're expanding the calibration envelope
-                            if (pos < cfg.d.plungerMin)
-                                cfg.d.plungerMin = pos;
-                            if (pos < cfg.d.plungerZero)
-                                cfg.d.plungerZero = pos;
-                            if (pos > cfg.d.plungerMax)
-                                cfg.d.plungerMax = pos;
-                                
-                            // normalize to the full physical range while calibrating
-                            znew = int(round(float(pos)/npix * JOYMAX));
-                        }
-                        else
-                        {
-                            // Running normally - normalize to the calibration range.  Note
-                            // that values below the zero point are allowed - the zero point
-                            // represents the park position, where the plunger sits when at
-                            // rest, but a mechanical plunger has a smmall amount of travel
-                            // in the "push" direction.  We represent forward travel with
-                            // negative z values.
-                            if (pos > cfg.d.plungerMax)
-                                pos = cfg.d.plungerMax;
-                            znew = int(round(float(pos - cfg.d.plungerZero)
-                                / (cfg.d.plungerMax - cfg.d.plungerZero + 1) * JOYMAX));
-                        }
-                        
-                        // done
-                        break;
-                    }
+                    // normalize to the full physical range while calibrating
+                    znew = int(round(float(pos)/npix * JOYMAX));
+                }
+                else
+                {
+                    // Not in calibration mode, so normalize the new reading to the 
+                    // established calibration range.  
+                    //
+                    // Note that negative values are allowed.  Zero represents the
+                    // "park" position, where the plunger sits when at rest.  A mechanical 
+                    // plunger has a smmall amount of travel in the "push" direction,
+                    // since the barrel spring can be compressed slightly.  Negative
+                    // values represent travel in the push direction.
+                    if (pos > cfg.d.plungerMax)
+                        pos = cfg.d.plungerMax;
+                    znew = int(round(float(pos - cfg.d.plungerZero)
+                        / (cfg.d.plungerMax - cfg.d.plungerZero + 1) * JOYMAX));
                 }
             }
 
-            // Determine if the plunger is being fired - i.e., if the player
-            // has just released the plunger from a retracted position.
-            //
-            // We treat firing as an event.  That is, we tell VP when the
-            // plunger is fired, and then stop sending data until the firing
-            // is complete, allowing VP to carry out the firing motion using
-            // its internal model plunger rather than trying to track the
-            // intermediate positions of the mechanical plunger throughout
-            // the firing motion.  This is essential because the firing
-            // motion is too fast for us to track - in the time it takes us
-            // to read one frame, the plunger can make it all the way to the
-            // zero position and bounce back halfway.  Fortunately, the range
-            // of motions for the plunger is limited, so if we see any rapid
-            // change of position toward the rest position, it's reasonably
-            // safe to interpret it as a firing event.  
-            //
-            // This isn't foolproof.  The user can trick us by doing a 
-            // controlled rapid forward push but stopping short of the rest 
-            // position.  We'll misinterpret that as a firing event.  But 
-            // that's not a natural motion that a user would make with a
-            // plunger, so it's probably an acceptable false positive.
-            //
-            // Possible future enhancement: we could add a second physical
-            // sensor that detects when the plunger reaches the zero position
-            // and asserts an interrupt.  In the interrupt handler, set a
-            // flag indicating the zero position signal.  On each scan of
-            // the CCD, also check that flag; if it's set, enter firing
-            // event mode just as we do now.  The key here is that the
-            // secondary sensor would have to be something much faster
-            // than our CCD scan - it would have to react on, say, the
-            // millisecond time scale.  A simple mechanical switch or a
-            // proximity sensor could work.  This would let us detect
-            // with certainty when the plunger physically fires, eliminating
-            // the case where the use can fool us with motion that's fast
-            // enough to look like a release but doesn't actually reach the
-            // starting position.
+            // If we're not already in a firing event, check to see if the
+            // new position is forward of the last report.  If it is, a firing
+            // event might have started during the high-res scan.  This might
+            // seem unlikely given that the scan only takes about 5ms, but that
+            // 5ms represents about 25-30% of our total time between reports,
+            // there's about a 1 in 4 chance that a release starts during a
+            // scan.  
+            if (!firing && z0 > 0 && znew < z0)
+            {
+                // The plunger has moved forward since the previous report.
+                // Watch it for a few more ms to see if we can get a stable
+                // new position.
+                int pos1 = plungerSensor.lowResScan();
+                Timer tw;
+                tw.start();
+                while (tw.read_ms() < 6)
+                {
+                    // if we've crossed the rest position, it's a firing event
+                    if (pos1 < cfg.d.plungerZero)
+                    {
+                        firing = 1;
+                        break;
+                    }
+                    
+                    // read the new position
+                    int pos2 = plungerSensor.lowResScan();
+                    
+                    // if it's stable, stop looping
+                    if (abs(pos2 - pos1) < int(npix/(3.2*8)))
+                        break;
+                        
+                    // the new reading is now the prior reading
+                    pos1 = pos2;
+                }
+            }
+            
+            // Check for a simulated Launch Ball button press, if enabled
+            if (ZBLaunchBallPort != 0 && wizOn[ZBLaunchBallPort-1])
+            {
+                int newState = lbState;
+                switch (lbState)
+                {
+                case 0:
+                    // Base state.  If the plunger is pulled back by an inch
+                    // or more, go to "cocked" state.  If the plunger is pushed
+                    // forward by 1/4" or more, go to "launch" state.
+                    if (znew >= JOYMAX/3)
+                        newState = 1;
+                    else if (znew < -JOYMAX/12)
+                        newState = 3;
+                    break;
+                    
+                case 1:
+                    // Cocked state.  If a firing event is now in progress,
+                    // go to "launch" state.  Otherwise, if the plunger is less
+                    // than 1" retracted, go to "uncocked" state - the player
+                    // might be slowly returning the plunger to rest so as not
+                    // to trigger a launch.
+                    if (firing || znew <= 0)
+                        newState = 3;
+                    else if (znew < JOYMAX/3)
+                        newState = 2;
+                    break;
+                    
+                case 2:
+                    // Uncocked state.  If the plunger is more than an inch
+                    // retracted, return to cocked state.  If we've been in
+                    // the uncocked state for more than half a second, return
+                    // to the base state.
+                    if (znew >= JOYMAX/3)
+                        newState = 1;
+                    else if (lbTimer.read_ms() > 500)
+                        newState = 0;
+                    break;
+                    
+                case 3:
+                    // Launch state.  If the plunger is no longer pushed
+                    // forward, switch to launch rest state.
+                    if (znew > -JOYMAX/24)
+                        newState = 4;
+                    break;    
+                    
+                case 4:
+                    // Launch rest state.  If the plunger is pushed forward
+                    // again, switch back to launch state.  If not, and we've
+                    // been in this state for at least 200ms, return to the
+                    // default state.
+                    if (znew < -JOYMAX/12)
+                        newState = 3;
+                    else if (lbTimer.read_ms() > 200)
+                        newState = 0;                    
+                    break;
+                }
+                
+                // change states if desired
+                if (newState != lbState)
+                {
+                    // if we're entering Launch state, press the Launch Ball button
+                    if (newState == 3 && lbState != 4)
+                        simButtons |= (1 << (LaunchBallButton - 1));
+                        
+                    // if we're switching to state 0, release the button
+                    if (newState == 0)
+                        simButtons &= ~(1 << (LaunchBallButton - 1));
+                    
+                    // switch to the new state
+                    lbState = newState;
+                    
+                    // start timing in the new state
+                    lbTimer.reset();
+                }
+            }
+                
+            // If a firing event is in progress, generate synthetic reports to 
+            // describe an idealized version of the plunger motion to VP rather 
+            // than reporting the actual physical plunger position.
             //
-            // To detremine when a firing even occurs, we watch for rapid
-            // motion from a retracted position towards the rest position -
-            // that is, large position changes in the negative direction over
-            // a couple of consecutive readings.  When we see a rapid move
-            // toward zero, we set our internal 'firing' flag, immediately
-            // report to VP that the plunger has returned to the zero 
-            // position, and then suspend reports until the mechanical
-            // readings indicate that the plunger has come to rest (indicated
-            // by several readings in a row at roughly the same position).
+            // We use the synthetic reports during a release event because the
+            // physical plunger motion when released is too fast for VP to track.
+            // VP only syncs its internal physics model with the outside world 
+            // about every 10ms.  In that amount of time, the plunger moves
+            // fast enough when released that it can shoot all the way forward,
+            // bounce off of the barrel spring, and rebound part of the way
+            // back.  The result is the classic analog-to-digital problem of
+            // sample aliasing.  If we happen to time our sample during the
+            // release motion so that we catch the plunger at the peak of a
+            // bounce, the digital signal incorrectly looks like the plunger
+            // is moving slowly forward - VP thinks we went from fully
+            // retracted to half retracted in the sample interval, whereas
+            // we actually traveled all the way forward and half way back,
+            // so the speed VP infers is about 1/3 of the actual speed.
             //
-            // Tolerance for firing is 1/3 of the current pull distance, or
-            // about 1/2", whichever is greater.  Making this value too small
-            // makes for too many false positives.  Empirically, 1/4" is too
-            // twitchy, so set a floor at about 1/2".  But we can be less
-            // sensitive the further back the plunger is pulled, since even
-            // a long pull will snap back quickly.  Note that JOYMAX always
-            // corresponds to about 3", no matter how many pixels we're
-            // reading, since the physical sensor is about 3" long; so we
-            // factor out the pixel count calculate (approximate) physical
-            // distances based on the normalized axis range.
-            // 
-            // Firing pattern: when firing, don't simply report a solid 0,
-            // but instead report a series of pseudo-bouces.  This looks
-            // more realistic, beacause the real plunger is also bouncing
-            // around during this time.  To get maximum firing power in
-            // the simulation, though, our pseudo-bounces are tiny cmopared
-            // to the real thing.
-            const int restTol = JOYMAX/24;
-            int fireTol = z/3 > JOYMAX/6 ? z/3 : JOYMAX/6;
-            static const int firePattern[] = { 
-                -JOYMAX/12, -JOYMAX/12, -JOYMAX/12, 
-            };
-            if (firing != 0)
+            // To correct this, we take advantage of our ability to sample 
+            // the CCD image several times in the course of a VP report.  If
+            // we catch the plunger near the origin after we've seen it
+            // retracted, we go into Release Event mode.  During this mode,
+            // we stop reporting the true physical plunger position, and
+            // instead report an idealized pattern: we report the plunger
+            // immediately shooting forward to a position in front of the
+            // park position that's in proportion to how far back the plunger
+            // was just before the release, and we then report it stationary
+            // at the park position.  We continue to report the stationary
+            // park position until the actual physical plunger motion has
+            // stabilized on a new position.  We then exit Release Event
+            // mode and return to reporting the true physical position.
+            if (firing)
             {
-                // Firing in progress - we've already told VP to send its
-                // model plunger all the way back to the rest position, so
-                // send no further reports until the mechanical plunger
-                // actually comes to rest somewhere.
-                if (abs(z0 - z2) < restTol && abs(znew - z2) < restTol)
+                // Firing in progress.  Keep reporting the park position
+                // until the physical plunger position comes to rest.
+                const int restTol = JOYMAX/24;
+                if (firing == 1)
                 {
-                    // the plunger is back at rest - firing is done
-                    firing = 0;
-                    
-                    // resume normal reporting
-                    z = z2;
+                    // For the first couple of frames, show the plunger shooting
+                    // forward past the zero point, to simulate the momentum carrying
+                    // it forward to bounce off of the barrel spring.  Show the 
+                    // bounce as proportional to the distance it was retracted
+                    // in the prior report.
+                    z = zBounce = -z0/6;
+                    ++firing;
                 }
-                else if (firing < countof(firePattern))
+                else if (firing == 2)
                 {
-                    // firing - report the next position in the pseudo-bounce 
-                    // pattern
-                    z = firePattern[firing++];
+                    // second frame - keep the bounce a little longer
+                    z = zBounce;
+                    ++firing;
+                }
+                else if (firing > 4
+                    && abs(znew - z0) < restTol
+                    && abs(znew - z1) < restTol 
+                    && abs(znew - z2) < restTol)
+                {
+                    // The physical plunger has come to rest.  Exit firing
+                    // mode and resume reporting the actual position.
+                    firing = false;
+                    z = znew;
                 }
                 else
                 {
-                    // firing, out of pseudo-bounce items - just report the
-                    // rest position
+                    // until the physical plunger comes to rest, simply 
+                    // report the park position
                     z = 0;
+                    ++firing;
                 }
             }
-            else if (z0 < z2 && z1 < z2 && znew < z2
-                     && (z0 < z2 - fireTol 
-                         || z1 < z2 - fireTol
-                         || znew < z2 - fireTol))
-            {
-                // Big jumps toward rest position in last two readings - 
-                // firing has begun.  Report an immediate return to the
-                // rest position, and send no further reports until the
-                // physical plunger has come to rest.  This effectively
-                // detaches VP's model plunger from the real world for
-                // the duration of the spring return, letting VP evolve
-                // its model without trying to synchronize with the
-                // mechanical version.  The release motion is too fast
-                // for that to work well; we can't take samples quickly
-                // enough to get prcise velocity or acceleration
-                // readings.  It's better to let VP figure the speed
-                // and acceleration through modeling.  Plus, that lets
-                // each virtual table set the desired parameters for its
-                // virtual plunger, rather than imposing the actual
-                // mechanical charateristics of the physical plunger on
-                // every table.
-                firing = 1;
-                
-                // report the first firing pattern position
-                z = firePattern[0];
-            }
             else
             {
-                // everything normal; report the 3rd recent position on
-                // tape delay
-                z = z2;
+                // not in firing mode - report the true physical position
+                z = znew;
             }
-        
-            // shift in the new reading
+
+            // shift the new reading into the recent history buffer
             z2 = z1;
             z1 = z0;
             z0 = znew;
         }
-        else
-        {
-            // plunger disabled - pause 10ms to throttle updates to a
-            // reasonable pace
-            wait_ms(10);
-        }
 
-        // read the accelerometer
-        int xa, ya;
-        accel.get(xa, ya);
-        
-        // confine the results to our joystick axis range
-        if (xa < -JOYMAX) xa = -JOYMAX;
-        if (xa > JOYMAX) xa = JOYMAX;
-        if (ya < -JOYMAX) ya = -JOYMAX;
-        if (ya > JOYMAX) ya = JOYMAX;
-        
-        // store the updated accelerometer coordinates
-        x = xa;
-        y = ya;
-        
         // update the buttons
         uint32_t buttons = readButtonsDebounced();
-        
-        // Send the status report.  Note that the nominal x and y axes
-        // are reversed - this makes it more intuitive to set up in VP.
-        // If we mount the Freesale card flat on the floor of the cabinet
-        // with the USB connectors facing the front of the cabinet, this
-        // arrangement of our nominal axes aligns with VP's standard
-        // setting, so that we can configure VP with X Axis = X on the
-        // joystick and Y Axis = Y on the joystick.
-        js.update(y, x, z, buttons, statusFlags);
+
+        // If it's been long enough since our last USB status report,
+        // send the new report.  We throttle the report rate because
+        // it can overwhelm the PC side if we report too frequently.
+        // VP only wants to sync with the real world in 10ms intervals,
+        // so reporting more frequently only creates i/o overhead
+        // without doing anything to improve the simulation.
+        if (reportTimer.read_ms() > 15)
+        {
+            // read the accelerometer
+            int xa, ya;
+            accel.get(xa, ya);
+            
+            // confine the results to our joystick axis range
+            if (xa < -JOYMAX) xa = -JOYMAX;
+            if (xa > JOYMAX) xa = JOYMAX;
+            if (ya < -JOYMAX) ya = -JOYMAX;
+            if (ya > JOYMAX) ya = JOYMAX;
+            
+            // store the updated accelerometer coordinates
+            x = xa;
+            y = ya;
+            
+            // Send the status report.  Note that the nominal x and y axes
+            // are reversed - this makes it more intuitive to set up in VP.
+            // If we mount the Freesale card flat on the floor of the cabinet
+            // with the USB connectors facing the front of the cabinet, this
+            // arrangement of our nominal axes aligns with VP's standard
+            // setting, so that we can configure VP with X Axis = X on the
+            // joystick and Y Axis = Y on the joystick.
+            js.update(y, x, z, buttons | simButtons, statusFlags);
+            
+            // we've just started a new report interval, so reset the timer
+            reportTimer.reset();
+        }
         
         // If we're in pixel dump mode, report all pixel exposure values
         if (reportPix)
         {
+            // send the report            
+            plungerSensor.sendExposureReport(js);
+
             // we have satisfied this request
             reportPix = false;
-            
-            // send reports for all pixels
-            int idx = 0;
-            while (idx < npix)
-                js.updateExposure(idx, npix, pix);
-                
-            // The pixel dump requires many USB reports, since each report
-            // can only send a few pixel values.  An integration cycle has
-            // been running all this time, since each read starts a new
-            // cycle.  Our timing is longer than usual on this round, so
-            // the integration won't be comparable to a normal cycle.  Throw
-            // this one away by doing a read now, and throwing it away - that 
-            // will get the timing of the *next* cycle roughly back to normal.
-            ccd.read(pix, npix);
         }
         
 #ifdef DEBUG_PRINTF
@@ -1832,7 +1803,7 @@
                 ledG = (hb ? 1 : 0);
                 ledB = 0;
             }
-            else if (cfg.d.ccdEnabled && !cfg.d.plungerCal)
+            else if (cfg.d.plungerEnabled && !cfg.d.plungerCal)
             {
                 // connected, plunger calibration needed - flash yellow/green
                 hb = !hb;