The Pinscape Pico Config Tool helps set up a Raspberry Pi Pico with the Pinscape Pico firmware. It provides interactive tools for installing the firmware, managing your configuration settings, and testing and troubleshooting your hardware setup. The Pinscape Pico firmware is designed to turn a Pico into a full-featured I/O controller for a virtual pinball cabinet, allowing pinball simulators running on your PC to access arcade-style buttons, accelerometers, plunger sensors, and feedback devices in the cabinet.
If you're setting up a new Pico, you can find step-by-step instructions in New Device Setup.
The left panel shows a list of available devices. The rest of the window shows a set of tools for the selected device. Click on one of the device buttons in the left panel to select the device you want to work with, then select a tool via the tabs across the top of the window.
The device list includes the following items:
You can force any Pico into Boot Loader mode by holding down the BOOTSEL button on top of the Pico while you plug in its USB cable. Boot Loader mode is built into ROM inside the Pico's CPU, so it's impossible to accidentally delete it; it's always ready to go, no matter what firmware you've installed on the Pico in the past.
Boot Loader mode is the first step to installing Pinscape (or any other firmware) onto a new Pico. After Pinscape is installed, you shouldn't ever need to repeat the BOOTSEL button/cable plugging maneuver, because the Pinscape firmware can get back to Boot Loader mode under software control through the Config Tool. But you can still use the BOOTSEL button as a last resort if the Pinscape software becomes unresponsive.
After you select a device, the available tools will appear as tabs across the top of the window. Select a tab to access its tool window. The tools for an existing Pinscape Pico device (a Pico with the Pinscape firmware installed) are:
For information on the what goes in the configuration file, refer to the following:
Once Pinscape is installed on a Pico, you can update the firmware without going through that whole BOOTSEL procedure again.
The Config Tool will now automatically reboot the Pico into Boot Loader mode and copy the new firmware file onto the Pico. When the copy finishes, the Pico will reset again and launch the new Pinscape software. There's no need to unplug any cables or press the BOOTSEL button during this process.
The Config Tool uses a small text file, in JSON format, to store settings from one session to the next. It uses this to remember the window location, for example. By default, the program looks for this file in its own folder, where the program's .EXE file is stored. In some cases, you might want to be able to specify a different location; for example, if you're running the program from a network drive or a read-only drive, or you're sharing the program .EXE among multiple users who want to keep their own separate settings files.
To override the default settings file location, specify a command-line option when launching the program:
GUIConfigTool --settings c:\users\mjr\ConfigToolSettings.json
Naturally, you should replace the c:\users\... path in the example above with the actual folder path you want to use.
You can supply command-line options to the program by launching it from the Windows "Run" dialog (press Windows+R, type the command line into the box), or from a DOS command-line window, also known as a CMD or command shell window (Windows+R, type CMD, press return). If you want to use the same options on every launch, it's convenient to create a Windows Shortcut file that includes the command line options. Refer to any Windows help site for instructions on how to do that.
If you want to tell the program to ignore the saved settings entirely when it starts up, and use defaults instead, the command line options is:
GUIConfigTool --default-settings
The program will still save settings when it exits, but this prevents it from loading the old settings when it starts. This might be helpful if the old settings are creating a problem, such as hiding the window somewhere in the off-screen wilderness. You can alternatively just delete the old settings file, or hand-edit it to fix whatever's wrong. The file uses a human-readable JSON format. Be aware that hand-editing the file isn't recommended in general, though, because the program overwrites the file with the new settings every time it runs, so any hand-edits you make will be overwritten after the next session.
Pinscape Pico also comes with a command-line configuration tool, which provides access to the core configuration functions with a more minimalistic UI. The command-line version is particularly useful if you want to invoke configuration commands from automation tools such as Windows batch files, AutoHotKey scripts, or Visual Basic, since all of those tools make it easy to invoke a command-line program.
To run the command-line tool, open a DOS box (from the Windows desktop, press Start+R, type CMD, and press return), "CD" to the folder containing the Pinscape Pico files, and type ConfigTool.
c:\users\mjr> cd /d C:\PinscapePico C:\PinscapePico> configtool
If you run the program with no arguments, it will show a list of the available options.
Pinscape Pico comes with a C++ API for Windows that makes it relatively easy for C++ programmers to control the device through the USB interfaces. All of the Config Tool's access to the device goes through that API, so you can use it to write custom software that does anything the Config Tool can do. You can find the files in the PinscapePicoAPI folder (under the main Pinscape Pico install folder). The documentation for the API is contained in the header (.h) files you'll find in that folder.
The API is currently only for C++ programs, but virtually every other programming language processor on Windows has some way to invoke C/C++ interfaces, so you might still be able to find a way to import it even if you're using some other language.
Alternatively, you can bypass the C++ API by programming directly to the USB protocols. The C++ API is essentially just a convenience that repackages the USB communications in a format that's easier to work with in C++. The protocols are fully documented; see the USBProtocol folder (under the main Pinscape Pico install folder). The protocols are documented in comments in the C++ header (.h) files you'll find there. Even though the comments are mixed in with C++ declarations, you should still find the comments readable even if you're not conversant with C++ coding, since the comments are meant to describe the protocol at the byte level, which is independent of programming language. The C++ declarations are just there because they embody the concrete C++ expression of the protocol elements.
The Pico is one of the best documented microcontroller's I've encountered. Here are some links to the official documentation from Rasbperry Pi, the company that created the Pico.
Pinscape Pico is firmware for the Raspberry Pi Pico microcontroller board that turns the Pico into a full-featured I/O controller for virtual pinball machines. The project is a sequel to the original Pinscape for KL25Z. It has most of the same features as the original, plus many new enhancements that were made possible by the greater power of the Pico platform. Like the original Pinscape, this is an open-source project, with published source code for all components and a permissive license (BSD 3-clause) that allows personal and commercial use, as well as full leave to add (and publish) your own fixes, features, and enhancements.
The firmware program is written in C++, and is based on the official Raspberry Pi Pico SDK. It takes extensive advantage of the Pico's hardware capabilities to optimize performance. It has support for numerous external hardware peripherals relevant to virtual pinball I/O, including devices for button inputs, PWM and digital output switching, plunger sensors, IR remote control signaling, and accelerometers. It can emulate multiple USB input devices (simultaneously), including keyboards, gamepads, and XBox controllers. No device drivers are needed; everything needed is built into Windows.
The project includes a set of Windows GUI and command-line tools to aid in configuring and troubleshooting the Pico setup, as well as extensive programmatic interfaces that allow you to create your own tools. The USB interfaces for configuration and control functions are fully documented, and the project includes a high-level C++ API for accessing the USB interfaces, to make it easy to write custom Windows-side software that accesses special device features. ("Easy" as far as that word can ever be applied to writing Windows programs, anyway; the API at least takes care of the Pinscape details for you, but, of course, it's still Windows programming.)
The Pinscape Pico project (including the firmware for Pico as well as the Windows tools and API libraries) is copyrighted 2024 Michael J Roberts, and released under a open-source license (BSD 3-Clause).
See License.txt for the full text of the Pinscape Pico license, as well as copyright notices and licenses for the third-party open-source components and libraries that the project incorporates.