<< Pinscape Resources Home

First-time installation

VirtuaPin plunger kit customers: please read the warning below before proceeding

If you have your KL25Z in hand, the easiest way to get started is with the Pinscape Config Tool:

  1. Download the latest Config Tool here
  2. Unpack the ZIP file into a folder on your hard disk
  3. Run the PinscapeConfigTool.exe application by double-clicking on the file
  4. Click the "Set up a new KL25Z" button. This will lead you through the process of preparing your KL25Z and installing the Pinscape firmware.

If you don't have a KL25Z yet, you can learn about the Pinscape project at the mbed project page.

Updates - Latest Release

The Pinscape Config Tool on Windows normally checks for updates and downloads them for you automatically, but you can also manually download the latest versions here.

Note: This firmware update turned up an error in DOF, so you'll also need to update DOF to a September 2024 (or later) release, available on the DOF updates page.

See the release history below for a summary of changes.

Source Code

The source code for the firmware and config tool are available in online version control systems. You can build the firmware via the mbed online compiler, and you can build the config tool with the free Community Edition of Visual Studio on Windows.

Attention VirtuaPin plunger kit customers!

If you bought a VirtuaPin plunger or controller kit that came with a KL25Z board, please don't install Pinscape before reading this warning. Installing the Pinscape firmware on your KL25Z will erase and replace your pre-installed VirtuaPin firmware. The KL25Z can only have one firmware program installed at a time, so loading Pinscape or any other new firmware will erase your existing VirtuaPin firmware, and you won't be able to restore it without sending the device back to VirtuaPin. VirtuaPin doesn't allow you to install their firmware at home, because they're worried that you'd illegally share copies if they let you download it. The only way you can restore their firmware is to physically ship the board back to the store and ask them to reinstall it.

Apart from that practical issue, I should also point out that the Pinscape software was never meant to be a replacement for the VirtuaPin firmware. The VirtuaPin product is a full hardware system with its own wiring and peripheral devices (such as their plunger sensor), and the VirtuaPin firwmare is tailored to that particular hardware setup. The Pinscape firmware is designed for the Pinscape DIY hardware setup. VirtuaPin's kit does happen to include the same retail KL25Z that Pinscape uses, but it comes with that proprietary firmware pre-installed. If you want a KL25Z for running Pinscape, I'd recommend just buying a separate "blank" KL25Z - they're only about $15, and readily available from several vendors, such as Mouser, Amazon, and eBay. With a "blank" KL25Z, you won't have to erase any pre-installed firmware that you paid extra for.

With those warnings in mind, if you're absolutely sure that you don't want to continue using the VirtuaPin firmware, the Pinscape firmware will work as a replacement, since it's built for the same KL25Z board and has equivalents of all of the main features. As of the June 2021 Pinscape firmware release, Pinscape also supports the sensor that comes with VirtuaPin's v3 plunger kit (the Vishay VCNL4010 proximity sensor), so you can keep your plunger setup as well if you migrate. (Note that this isn't true of the older VirtuaPin kits prior to v3, since those came with different sensor chips that Pinscape doesn't have support for. If you want to keep using your VirtuaPin plunger, make sure you have the VCNL4010-based kit before committing to this plan. Look for the printed legend VCNL4010 on the little circuit board at the end of your plunger assembly.) You'll also have the option to switch to any of the several other plunger sensors that Pinscape supports, but that's up to you.

Should I update to the latest?

I'm often asked whether or not it's a good idea to update your system when a new version comes out. There's the obvious trade-off with any new software release: "ooh, shiny and new!" versus "if it ain't broke, don't fix it."

My usual advice is yes, get the latest, unless you have an unusual situation that makes upgrading difficult or impossible. There are several reasons:

  • Bug fixes. Each new release usually includes several fixes for minor bugs that you might not have run into, but might at some point. So updates usually make older features more stable and reliable. It might not always seem like that, because I sometimes inadvertently add new bugs when trying to fix old ones. But even when that happens, there are usually more more improvements than new problems.
  • Future updates. Even if you don't need any features in this release, there might be a future release with something you do really want. It'll be easier to upgrade then if you've been keeping your system up-to-date all along, since you won't have to suddenly jump ahead by several versions. If there are any problems on your system with changes along the way, you'll catch them sooner, which means I'll be able to fix them sooner, so hopefully that future update with the features you want will be problem-free for you.
  • Testing. Selfishly, I'd really prefer everyone to update for the sake of testing, so that any new bugs that are there get found more quickly, which lets me fix them more quickly.
  • Support. Also selfishly, it's easier for me to help you out with any bugs you find if you're working with the latest, so that I don't have to dig back into old versions of the source code.
  • Bugs aren't forever (hopefully). Even if you do run into a problem in a new release, hopefully won't be there long, because I'll try to fix it if you let me know about it.
  • It's low-risk, because it's easy to return to an older version if necessary. Old release versions are archived below, so you can always find them, and installation is low hassle. It's not like big Windows apps where they make it difficult to "downgrade" to old versions.

Archived Release Builds

This section lists past releases of the firmware and config tool. If you run into a bug in a new update, you can revert to an older version below. But please let me know if you do this, because I might not otherwise hear about the bug!

It's better to use matching versions of the firmware and config tool if possible (that is, both from the same release date). I try to maintain compatibility across versions between the config tool and firmware, so it should be okay to mix versions if you have a good reason, but it's still better to use a matching set when possible to ensure that both pieces of software are working with the same feature set. New UI features in the Config Tool often depend upon corresponding new functions in the firmware, so you might not see a new feature in the UI (or it might be limited, or not work properly) if you have older firmware installed.

How to install old versions

Config tool: Unpack the .zip file into a folder on your PC's hard disk. Open the folder. Double-click the "PinscapeSetupTool.exe" application file.

Firmware: Run the Config Tool. Click the "Update" button in the device list entry for the controller you'd like to update. Select the downloaded file when the tool asks which .bin file to install.

List of archived versions

October 5, 2024
Pinscape_Controller_KL25Z_20241005.bin (Firmware)
PinscapeConfigTool-20241005.zip (Config Tool)
  • Improved TSL14xx optical plunger sensor edge detection: With the addition of the new plunger speed reporting in the 8-18-2024 release, it became more important for the plunger sensor to be able to track the plunger during fast motion. This made it noticeable that the edge detection algorithm that the v2 firmware has used for many years isn't able to take good readings when the plunger is near the peak speeds it hits when you pull it back and release it to be driven forward by the main spring. This firmware version adds two new algorithms that do a better job at high-speed tracking. One of the new algorithms, "Steady Slope", seems to be the best across all speed ranges, so it's the one I recommend as the top choice. However, the choice of algorithm is now configurable, in case the new algorithm doesn't perform as well for some installations. It's possible that the "best" algorithm will vary depending on optical conditions, such as the type of light source you're using and its position relative to the sensor. I particularly wanted to make sure that you can keep using the original algorithm if you prefer, since it's so well time-tested. Briefly, the available algorithms are:
    • "Steepest slope": this is the original algorithm that has been used for many years, and has proven to work well, except when the plunger is moving at very high speeds. This scans the image for point with the biggest difference in brightness between adjacent pixels. When the plunger is stationary, this works well, because the shadow cast by the plunger has a sharp edge that the algorithm readily detects. But when the plunger is moving rapidly, the edge is blurred in the image by the motion, so the point with the steepest difference is less clear. At high speeds, the edge is so spread out by motion blur that there are often bigger absolute differences in adjacent pixels due to random noise, which fools the algorithm and makes it sometimes pick the wrong position.
    • "Steepest slope across a gap": this is a tweak of the original algorithm that looks for the biggest difference in brightness across a gap, rather than between immediately adjacent pixels. This takes into account the "penumbra" of the shadow as well as motion blur. This algorithm estimates the current speed of the plunger based on recent readings to determine how wide the gap should be. This algorithm is better than the original "steepest slope" at tracking high speeds, but it's not as good as the "steady slope" method below, probably because it has to make a guess about the expected gap size, whereas "steady slope" adapts automatically with no need to make a guess first.
    • "Steady Slope": this is the new default algorithm, and it's the one I recommended, since it performs best in my testing. It scans for an edge by looking for a region with a steady slope of pixel brightnesses from bright to dark. The reasoning behind this approach is that the width of this sloping region changes according to how fast the plunger is moving, because fast plunger motion creates the equivalent of the motion blur that you can see in an ordinary photo of a fast-moving object, smearing out the edge of the plunger shadow across a range of pixels on the sensor. By looking for a steady slope, rather than looking for a slope of a pre-determined width, the algorithm automatically adapts to the amount of blurring in each image, so it reads fast- and slow-moving positions equally well. It also seems to have the best noise tolerance of the algorithms, producing the least "jitter" in the raw readings when the plunger is stationary.
    The "Steady Slope" algorithm is now selected by default, and I think it'll perform better than the other options on virtually all systems, but you can change if you wish via the Plunger Viewer window in the Config Tool. The Plunger Viewer lets you see the immediate effect of switching algorithms, so you can easily compare how the different options perform on your system.
August 18, 2024
Pinscape_Controller_KL25Z_20240818.bin (Firmware)
PinscapeConfigTool-20240818.zip (Config Tool)
  • Note: this build turned up an error in the Pinscape driver in DOF, so you'll need an updated version of DOF to go with it. A test build with the fix is available on the Pinscape Release Builds page http://mjrnet.org/pinscape/swversions.php.
  • Configurable PWM frequency for GPIO outputs: in the Outputs section of the settings page, you can set the PWM frequency used for GPIO outputs. This is particularly useful if you're running any inductive devices (motors, solenoids) through GPIO output ports, and they make noise when run at low speeds. The noise is probably due to mechanical vibration at the PWM frequency. Past firmware versions used fixed PWM rates that were in the audible range of human hearing, so it was possible for mechanical vibration in attached devices to translate to acoustic noise, like whining or buzzing. This version lets you adjust the PWM rate to fix such problems. The default rate is now 20000 Hz, which is above the human hearing range. Note that some amplifier/booster circuits might have a limit on how high a PWM frequency they can switch - optocoupler-based circuits in particular might not work at frequencies much above 20000 Hz. If you find that output ports with amplifier or booster circuits stop working with this release, try reducing the PWM frequency setting - your amplifiers might not be able to handle the new, higher frequency. That's the whole reason it's now configurable rather than just fixed at a higher rate; I didn't want to create a new problem by fixing an old one. You'll need a new (August 2024 or later) firmware version to use the adjustable frequency setting.
  • New velocity features: This release contains two new, experimental features designed to improve the fidelity of nudging and plunger action in the simulators. First, nudge input can now be sent to the simulators as velocity information instead of accelerations. Second, the device now calculates the plunger speed and can send it to the simulator. Both of these additions can improve the simulation quality by giving the simulator more detailed information on the real-time state of the sensors. For a discussion of the theory behind these additions, see http://mjrnet.org/pinscape/OpenPinballDevice/NewPinCabInput.htm. These features are still experimental, and are not yet supported in any of the published simulators, but I'm in the process of submitting the necessary code to support them in Visual Pinball. It's my hope that Visual Pinball will be the first simulator to support the new system. For details on enabling the new features, see https://github.com/mjrgh/Pinscape_Controller/releases/tag/Build20240818.
December 22, 2021
Pinscape_Controller_KL25Z_20211222.bin (Firmware)
PinscapeConfigTool-20211222.zip (Config Tool)
  • Added support for Arnoz's pin cab circuit boards to the firmware and Config Tool. (Arnoz offers a number boards with functionality similar to the Pinscape Expansion Boards, all fully assembled and ready to use. See https://shop.arnoz.com.)
  • Fixed some problems in the pin selector popups that sometimes caused incorrect pin mappings when you selected pins by clicking on the pictures of the power and chime expansion boards.
July 16, 2021
Pinscape_Controller_KL25Z_20210716.bin (Firmware)
PinscapeConfigTool-20210716.zip (Config Tool)
  • Fixed a firmware bug that caused feedback devices to randomly turn on if you activated night mode immediately after rebooting the PC, before running any programs that accessed the feedback devices (e.g., VP, or any other DOF program). The problem was that the firmware's internal notion of the feedback device states wasn't properly initialized in this case, so switching to night mode caused the feedback ports to assume random states, which had the obviously unwanted effect of randomly firing some/many/all of the devices. This should now be fixed.
June 2, 2021
Pinscape_Controller_KL25Z_20210602.bin (Firmware)
  • A new plunger sensor is now supported: the Vishay VCNL4010 proximity sensor. This sensor's accuracy isn't as good as the potentiometer or quadrature options, but it's not bad, and it's inexpensive and really easy to set up. This is the sensor that comes with the latest version (v3) of the VirtuaPin plunger kit, so you already have one on hand if you bought that product; if not, you can buy the sensor on a ready-to-use circuit board for about $7.50 from Adafruit. Full setup instructions are in the Pinscape Build Guide.
May 8, 2021
PinscapeConfigTool-20210508.zip (Config Tool)
  • Add a warning for VirtuaPin customers to the KL25Z setup process about how installing Pinscape will replace any existing VirtuaPin firmware pre-installed on the board. Some VirtuaPin customers have tried installing Pinscape, believing that it would be installed alongside the VirtuaPin firmware, not realizing that the KL25Z can only run one thing at a time.
April 29, 2021
Pinscape_Controller_KL25Z_20210429.bin (Firmware)
PinscapeConfigTool-20210429.zip (Config Tool)
  • Add a "watchdog" to the firmware to monitor the MMA8451Q accelerometer chip status, and try to reset it if it stops producing samples. I've had occasional reports that the accelerometer "freezes" even though the firmware itself is still running correctly, which suggests that the MMA8451Q chip can stop responding. It's unclear whether this is due to a hardware fault on the chip, or a bug in the Pinscape firwmare, but evidence seems to point towards a hardware fault: it only seems to affect a few boards, the problem is apparently readily repeatable on the boards it does affect, and the Pinscape firmware itself continues running when the problem occurs. So on the assumption that it's a hardware fault, the watchdog attempts to clear the problem by resetting the MMA8451Q chip if the chip stops producing samples or if the samples don't show any vibration at all for a long period ("long" in this case is about two seconds). The KL25Z hardware design makes it impossible to do a full power-cycle reset of the MMA8451Q without power-cycling the whole board, so the watchdog can only attempt a software reset, which might not be sufficient if this is due to a true hardware defect rather than just a software state problem on the accelerometer. I'm hoping that further testing on boards where the problem has been observed will determine if the fix helps.
  • Add experimental support for the VCNL4010 chip to the firmware and Config Tool. The support hasn't been tested against live hardware yet, so at the moment it's for testing purposes only, but feel free to give it a try if you have one of these sensors. (This is the sensor that comes with the latest (V3) VirtuaPin plunger kit.)
September 10, 2020
PinscapeConfigTool-20200910.zip (Config Tool)
  • Add some missing graphics from the last update.
September 9, 2020
PinscapeConfigTool-20200909.zip (Config Tool)
  • Add support in the Config Tool for Oak Micros's Pinscape Lite board.
April 21, 2020
Pinscape_Controller_KL25Z_20200421.bin (Firmware)
PinscapeConfigTool-20200421.zip (Config Tool)
  • Added a "zoom" control to the plunger sensor viewer in the Config Tool for imaging sensors (TLS1410, TCD1103). The new control is only meaningful when an image sensor type is in use, so it won't be visible with non-imaging sensors like potentiometers, quadrature sensors, etc. The zoom control is mostly to help get a clear enough view to adjust lens focus with the TCD1103, but it could be helpful with other image sensors as well just to get a clearer view of the pixel structure.
  • Fixed a bug in the firmware that only sent IR commands for the TV ON sequence if they were contiguously grouped in the first slots. IR for the TV ON sequence can now be placed in any slots.
  • Made some small changes to the TCD1103 plunger sensor support in the firmware to improve the quality of the image data transfer.
February 18, 2020
Pinscape_Controller_KL25Z_20200218.bin (Firmware)
PinscapeConfigTool-20200218.zip (Config Tool)
  • The Config Tool's plunger sensor viewer has a new visualization for quadrature sensors, showing the current "A" and "B" channel readings, and the inferred location along the bar code scale. This requires the latest firmware, which adds reporting on the raw "A" and "B" channel readings.
January 22, 2020
Pinscape_Controller_KL25Z_20200122.bin (Firmware)
PinscapeConfigTool-20200122.zip (Config Tool)
  • Added support in the Config Tool for Oak Micros's Pinscape All-In-One board.
  • The firmware's analog voltage sensing procedure for the potentiometer has been greatly improved, which should make for more precise readings with less jitter and noise. If you've been using the "Jitter Filter" to reduce visible instability in the position readings, you should try readjusting the filter to see if the changes let you use a smaller filter window. You might even be able to turn the filtering off entirely. (The firmware now uses a more accurate sampling mode in the ADC hardware, along with continuous sampling and a rolling average over several milliseconds. The earlier scheme used instantaneous samples only, which tend to be much noisier. The sampling interval is still shorter than the USB update interval, so there's no downside to this in terms of performance or latency. The old instantaneous sampling approach was basically just discarding a lot of data that it could have been collecting to improve the accuracy, which is what we do now.)
  • Added support in the Config Tool and in the Pinscape firmware for two new plunger sensor types (TCD1103, AEAT-6012). These sensors are both still under development, so we haven't added any plans for them to the Build Guide yet, but the software support for them is now in place for if and when we can finalize the designs.
  • Fixed a bug in the firmware that made the "Reverse orientation" option not work quite right for the AEDR-8300 sensor.
March 5, 2019
Pinscape_Controller_KL25Z_20190305.bin (Firmware)
PinscapeConfigTool-20190305.zip (Config Tool)
  • Added "Chime Logic", which lets you set minimum and maximum ON times for the port. Setting a minimum time can be useful for devices need a certain minimum activation time to reach full strength. The maximum time can be used for devices like chimes that only produce the right effect when triggered with a very fast ON/OFF cycle, as well as for coils that can overheat if left on for too long. The time settings available for Chime Logic provide fairly fine gradations of short time spans (single milliseconds to tends of milliseconds).
  • Flipper Logic is now enabled for digital (non-PWM) ports. (In the past, it was only offered on PWM ports.) For a digital port, the "hold" power is fixed at 0% (fully off), since intermediate power levels between 0% and 100% aren't possible without PWM support on the port (and that's precisely what a "digital" port is: one without PWM capabilities). The effect is that Flipper Logic acts like a simple time limiter on the port.
  • Fixed a firmware bug that prevented assigning the same physical button to both the Shift and Night Mode Toggle functions. (In the past, the Night Mode part of it didn't work if you did this.)
  • Config Tool windows should now adapt properly to monitor "zoom" settings in the Windows desktop layout. In past versions, Config Tool windows sometimes changed sizes unexpectedly on redraws if a monitor was set to a zoom factor other than 100%.
January 30, 2018
PinscapeConfigTool-20180130.zip (Config Tool)
  • When setting up a new KL25Z, the Config Tool now automatically checks the boot loader version that's currently installed on the device, and advises as to whether or not it needs to be updated before Pinscape can be installed. This saves unnecessary updates for newer KL25Z's that have compatible firmware pre-installed.
January 28, 2018
Pinscape_Controller_KL25Z_20180128.bin (Firmware)
  • Changed PWM frequency for feedback device ports to 2 kHz
  • Fix accelerometer rotation bug introduced in stuttered joystick report update (2017-12-13)
December 13, 2017
Pinscape_Controller_KL25Z_20171213.bin (Firmware)
PinscapeConfigTool-20171213.zip (Config Tool)
  • Adjustable timing for joystick and accelerometer reports, for optimizing VP nudge performance (WARNING: this version also has a bug that makes accelerometer readings erratic; the bug is fixed in the Jan 12 2018 version [20180128])
October 20, 2017
Pinscape_Controller_KL25Z_20171020.bin (Firmware)
PinscapeConfigTool-20171020.zip (Config Tool)
  • Plunger "reversed orientation" option
  • Option for joystick reporting on Rx/Ry/Rz axes instead of X/Y/Z (can be used in case of conflicts with other joystick devices)
May 12, 2017
Pinscape_Controller_KL25Z_20170512.bin (Firmware)
PinscapeConfigTool-20170512.zip (Config Tool)
  • "Flipper Logic": set individual output ports to fire at full power and then reduce power after a specified interval, to help protect coils and solenoids that might overheat if left at full power for long periods
  • New command-line tool for controlling Pinscape from command scripts
May 10, 2017
Pinscape_Controller_KL25Z_20170510.bin (Firmware)
PinscapeConfigTool-20170510.zip (Config Tool)
  • Support for AEDR-8300 and VL6180X plunger sensors
May 8, 2017
Pinscape_Controller_KL25Z_20170508.bin (Firmware)
PinscapeConfigTool-20170508.zip (Config Tool)
  • Bug fixes
March 25, 2017
Pinscape_Controller_KL25Z_20170325.bin (Firmware)
PinscapeConfigTool-20170325.zip (Config Tool)
  • IR remote control features
  • New accelerometer options
    • Select the dynamic range
    • Enable/disable auto-centering
    • Set custom auto-centering time
  • New Shift Button option: "Shift AND Key" mode makes the shift button send its own keystroke immediately whether or not you press another key
February 25, 2017
PinscapeConfigTool-20170225.zip (Config Tool)
  • Output tester
  • Button tester
  • TV ON tester
February 3, 2017
Pinscape_Controller_KL25Z_20170203.bin (Firmware)
  • USB protocol extensions for multiple virtual LedWiz support (requires using the special Pinscape version of LEDWIZ.DLL on PC)
January 17, 2017
Pinscape_Controller_KL25Z_20170117.bin (Firmware)
  • Bug fixes
January 4, 2017
Pinscape_Controller_KL25Z_20170104.bin (Firmware)
  • Updated firmware workaround instructions for Win 8/10