<< 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.

Changes in this version

  • 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.

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

December 22, 2021
  • 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
  • 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
  • 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
  • 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
  • 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
  • Add some missing graphics from the last update.
September 9, 2020
  • Add support in the Config Tool for Oak Micros's Pinscape Lite board.
April 21, 2020
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • "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
  • Support for AEDR-8300 and VL6180X plunger sensors
May 8, 2017
  • Bug fixes
March 25, 2017
  • 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
  • Output tester
  • Button tester
  • TV ON tester
February 3, 2017
  • USB protocol extensions for multiple virtual LedWiz support (requires using the special Pinscape version of LEDWIZ.DLL on PC)
January 17, 2017
  • Bug fixes
January 4, 2017
  • Updated firmware workaround instructions for Win 8/10