89. KL25Z Software Setup

The KL25Z is a "microcontroller", which is basically a tiny computer. Unlike a desktop computer, though, it doesn't require an operating system in the usual sense. There's no equivalent of Windows or Linux to install. Instead, you only have to install one thing: the Pinscape firmware. That serves as both the operating system and the application software. It controls all of the virtual pinball functions of the KL25Z, including the sensors, buttons, and feedback devices, and it handles communications with Windows.
In addition to the Pinscape firmware that runs on the KL25Z, there's a separate Pinscape program that runs on your Windows PC, called the Config Tool. This provides an interactive interface for setting up the device, configuring it, and testing it. You don't need to leave the Config Tool running all the time; it's only needed to set up the device. You can also run it again at any time to change options, update the firmware, or troubleshoot problems (it includes some testing features that can help debug the hardware setup).
The software installation process is all controlled from the PC. The Config Tool handles the KL25Z software setup, so the first step is to install the Config Tool on your PC. You can download it here:
To install, download the ZIP file above and unpack it into a folder on your hard disk. Use any location that's convenient. Open the folder and double-click the "PinscapeConfigTool" application.
The config tool should automatically go out and find the latest firmware version and download it for you. The firmware files are fairly small (in the 100K byte range), so this should only take a few seconds if you have a broadband Internet connection.
To install the firmware, click the link "Set up a new KL25Z" in the config tool window. The program will lead you through the process of setting up the device and installing the firmware.
If the Config Tool doesn't recognize your device at all, you might need to manually install a new version of the KL25Z boot loader; see KL25Z Boot Loader update below.
If all goes well, you should see a Pinscape device listed when you get back to the main menu screen. This will give you options to configure settings and test the device's inputs.
You'll also see the LED on the KL25Z flash a status indicator pattern. Alternating green/yellow or green/blue indicate healthy operation. See KL25Z Status Lights for the full list of status light patterns.

KL25Z Boot Loader update

In the old days before about 2018, KL25Z's shipped from the factory with a "boot loader" that didn't work with Windows 8 or 10. The boot loader is the part of the device's software that lets you install new software - such as Pinscape - onto the device, so it's a pretty critical component. More recent versions of the KL25Z have a newer version of the boot loader that does work properly with Windows 8 and 10, so if you bought your KL25Z any time after 2018 or so, you probably won't have to worry about this. But just in case you happen to have found a vendor selling dusty old stock from the back of the warehouse, I wanted to mention this.
In most cases, the Pinscape Config Tool will automatically test the boot loader version when you use the Set up a new KL25Z procedure described above, and walk you through the update process if it's necessary. If you were able to go through that procedure successfully, you can skip the rest of this section. But if the Config Tool didn't recognize your device when you tried to set it up, you might need to refresh the boot loader manually. The procedure is below.
However, there's an important and rather obnoxious catch-22 you need to know about first: This procedure might only work on Windows versions 7 and earlier. It might not work on Windows 8 or 10. Old versions of the factory firmware had a bug that made them incompatible with 8 and 10. This is the obnoxious catch-22: you need the boot loader to update the boot loader, so if you have the old version that doesn't work on your Win 8/10 machine, you can't use it to install the new version that does work on Win 8/10. There are some complex workarounds that people have found, such as running Windows 7 in a virtual machine box. You can find that information in a Web search, but I'm not going to reproduce it here, because it's very complex and tedious, and no one should need it any more. If you just bought a KL25Z, and find that it doesn't work with your Windows 8/10 machine (and you don't have an old Win 7 machine lying around), I'm going to suggest that you send back the KL25Z as defective, and ask the seller to send you a fresher one that was manufactured in 2019 or later.
And again, if the Config Tool recognized your device and you were able to go through the Set up a new KL25Z procedure successfully, you don't need to worry about this procedure.
Finally, this is a one-time procedure that you should never have to do again for this particular KL25Z. It's not necessary to repeat this when updating Pinscape versions.
Here's the procedure:
  • In your Web browser, go to pemicro.com/opensda/
  • Find the section OpenSDA Firmware (MSD & Debug). Click on the Firmware Apps link. You'll be asked to create a free account or to provide your email address to receive a download link. Choose the option you prefer and download the file.
  • Unzip the downloaded file to a local folder on your hard disk.
  • Unplug all USB cables from your KL25Z. If you have any other KL25Z cards already installed, unplug all of those as well.
  • Open the My Computer window on your Windows desktop, so that you can view attached disk drives.
  • Press and hold the KL25Z reset button.
  • Keep holding the reset button while you plug a USB cable into the programming port on the KL25Z, and plug the other end into a USB port on your computer.
  • Release the reset button.
  • You should see a new thumb drive icon appear in the My Computer window, with a name like BOOTLOADERAPP. This represents the KL25Z's programming port. (The name might be different depending on the old boot loader version. As long as a new drive appeared when you plugged in the USB port, that should be the right one, no matter what it's called.)
  • In the PEMicro software you downloaded above, find the file BOOTUPDATEAPP_Pemicro_v111.SDA. (The digits at the end are the version number, so they can vary.)
  • Drag and drop that file onto the KL25Z thumb drive.
  • Wait for Windows to finish copying the file, then unplug the KL25Z.
  • We're now going to repeat the steps above with a different .SDA file. As before, press and hold the reset button on the KL25Z, and plug in a USB cable between the KL25Z programming port and your computer. Release the reset button. In the downloaded files, find MSD-DEBUG-FRDM-KL25Z_Pemicro_v114.SDA, and drag it onto the thumb drive. (As before, the digits at the end might vary.) Unplug the USB cable after Windows finishes copying the file.
  • To confirm that everything worked, reconnect the KL25Z programming port to your PC without pressing the reset button. The thumb drive should appear again, but it should now be titled FRDM-KL25Z. You should also see a steady (non-blinking) green LED on the card while it's plugged in.
  • If any of this doesn't match what you see, the update might not have worked. If you attempted the upgrade from Windows 8 or higher, that's probably the problem. The old (pre-2018) factory firmware is incompatible with Windows 8-10 and will fail silently and mysteriously, with no error messages, if you're on Win 8-10. If you did the update from Windows 7 or earlier and it still didn't work, it's possible that the procedures have changed since this writing. Try looking for instructions (.txt and/or .pdf files) in the files you downloaded from PEMicro, to see if there's any information on new procedures.
  • If all went as expected, your KL25Z is now ready to use. With the updated firmware in place, the device should now work on all versions of Windows from XP to 10 and hopefully beyond.

Software updates

I update the Pinscape firmware periodically to fix bugs and add new features. I always try to maintain compatibility with existing installations when making changes, so you can generally update to the latest no matter which version you started with. However, it's completely up to you whether or not you want to keep up to date with the latest changes. There's something to be said for not messing with a working system, but it's also nice to have the latest bug fixes and features.
The Config Tool automatically checks for updates (unless you tell it not to) each time you run it, but it doesn't install them on its own. You have to tell it to install updates. So your firmware will never mysteriously change when you're not expecting it.
You can download the latest versions and archived versions of the firmware and Config Tool at the Pinscape web site:

KL25Z USB ports

The KL25Z features two USB ports. They're not interchangeable - each port has a specific function.
You don't have to memorize which port is which. The ports are labeled in tiny text on the bottom side of the board. Just flip the board over and look for the labels if you're ever in doubt.
The "KL25Z port" is the one that Pinscape uses for all of its joystick emulation, keyboard emulation, and LedWiz emulation functions. This port must always be plugged in during normal operation.
The "OpenSDA port" is the "programming" port. It doesn't actually connect to the microcontroller proper; it's connected to a separate processor on the board that's just there to handle firmware downloads. This port is only needed when you want to update the firmware, so you don't have to leave it plugged in all the time. But you can; it doesn't interfere with normal operations. I find it more convenient to leave it plugged in all the time, especially in a pin cab setting where you'd have to open up the cabinet to plug it in manually.
The OpenSDA port emulates a USB thumb drive, so you'll see a virtual hard disk (usually called "KL25Z") appear on your Windows desktop whenever the cable to this port is plugged in. This isn't a true disk drive, so don't copy random files there - doing so can mess up the Pinscape firmware. This virtual drive's only function is to program the KL25Z's flash memory with new firmware.