JSON Configuration Reference

The Pico GPIO port number connected to the serial output pin on the chip, labeled QH on the TI data sheet, or Q7 on the NXP data sheet.

Note that the chip also has an inverted output, labeled QH or Q7 [marked with a bar over the top, denoting inverted logic]. Don't connect this pin to the Pico. Leave it unconnected, or connect it to ground through a high-value resistor (perhaps 100K). (Leaving the pin unconnected might encourage it to act like an antenna, emitting radio-frequency noise, so it might not a bad idea to ground it through a resistor.)

Connect this GPIO port to the to the QH or Q7 pin on the first chip on the daisy chain only. Unlike the "shift" and "load" GPIO ports, don't connect this GPIO to all of the chips on the chain. Connect it to the first chip only.

The QH (or Q7) ports are what form the daisy chain. Connect the second chip's QH serial input port to the first chip's Serial Out pin, which is labeled SER on the TI data sheets, or DS on the NXP data sheet. Connect the third chip's QH/Q7 to the second chip's SER/DS pin, and so on down the chain. The last pin's SER/DS pin should be connected to ground.

The Pico GPIO number port connected to the "load" pin on the chip. This is labeled SH/LD (Shift/Load) on TI data sheets, or /PL (Parallel Load) on NXP data sheets. Connect this port to the SH/LD pins on all of the chips in the chain.

Sets the polarity of the "load" pin that selects LOAD mode. (The "load" pin is labeled SH/LD on TI data sheets, or /PL on NXP data sheets.)

This type of chip has two modes, selected by the "load" pin: SHIFT mode, where the chip transfers the contents of the shift register to the host microcontroller, and LOAD mode, where the chip loads the shift register from the 8 input pins. On the original 74HC165 chips, the mode selection is controlled by the SH/LD pin, and taking the pin LOW puts the chip in LOAD mode.

The reason this property is provided is that there are some other types of serial-input chips that are almost identical to the 74HC165, except that they invert the logic of their version of the SH/LD pin, so that setting the pin to "high" enables load mode. This software option is designed to give the Pinscape 74HC165 code enough flexibility to also work with this almost-identical chips, so that we don't need to create a whole separate chip type in the software to deal with this one small difference. If you're using one of those almost-but-not-quite-74HC165 chips, set loadPolarity according to the sense of your chip's version of the load/shift pin. If LOAD mode is activated by taking the pin HIGH, set this property to true; otherwise set it to false.

The number of chips making up the daisy chain. This is required so that the software knows how many ports to read on each input cycle.

The Pico GPIO port number connected to the "shift clock" pin on the chip, labeled CLK (Serial Clock) on the TI data sheet, or CP (Clock Input) on the NXP data sheet. Connect this port to the CLK pins on all of the chips in the chain.

Sets the clock rate, in Hz, for the shift clock signal sent to the daisy chain on the CLK pin (labeled CP on the NXP data sheet). This determines the data bit rate used to transfer port ON/OFF data from the chips to the Pico. The default is 6000000 (6 MHz), which is a conservative default based on the limits specified in the TI SN74HC165 data sheet. Higher frequencies allow faster polling of the input ports, but the chips will only operate correctly up to a limit, and higher frequencies are also more vulnerable to electronic noise in the wiring. That makes the usable limit vary by setup, so Pinscape makes it an adjustable parameter. The optimal setting is the highest value that works reliably with your setup. The default is conservative enough that it should work for most setups, but should also be fast enough for most needs (at 6 MHz, it takes 12us to transfer the data for 64 ports).

The Pico GPIO port number connected to the DS (serial data) pin on the first chip on the daisy chain only.

Unlike the "shift", "latch", and "enable" GPIO ports, this GPIO is not connected to all of the chips on the daisy chain. Instead, this GPIO connects only to the first chip on the chain. The other chips on the chain still need data port inputs, but each chip gets its input from its nearest neighbor - that's what actually forms the daisy chain, as each chip passes its data output to the next chip's data input. The second chip's "serial in" DS port connects to the first chip's "serial out" port, labeled Q7S on the data sheet. The third chip's DS connects to the second chip's Q7S. And so on down the chain.

For the last chip on the daisy chain, you can leave the Q7S serial data out pin unconnected, or you can connect it to ground through a high-value resistor, perhaps 100K. Connecting it to ground in this fashion might help reduce its propensity to like an antenna, broadcasting radio-frequency noise.

The Pico GPIO port number connected to the OE (output enable) pin on the chips.

Alternatively, this can be an object, using the same syntax as outputs[].device. This allows you to connect the OE pin to a GPIO extender such as a PCA9555, saving a GPIO port on the Pico.

Connect the Pico port you select to the OE pins on all of the chips in the chain. Also connect the port to 3.3V through a pull-up resistor, typically 10K. The pull-up resistor ensures that the OE signal is pulled high, disabling all of the 74HC595 output ports, during the brief time after power-up when the Pico's GPIO pins are in their initial high-impedance state. Without the pull-up resistor, the OE signal would be left floating immediately after power-up, which might cause the 74HC595 ports to randomly activate, firing connected devices briefly.

The Pinscape software uses the OE signal to ensure glitch-free startup. 74HC595 chips power up with random values in the shift register, so it's important to disable all of the 74HC595 output ports immediately at power-up, until the Pico has a chance to set all of the ports to OFF. The Pinscape software initializes all of the ports to OFF very soon after a reset, but there's a brief time window after power-up before this initialization step occurs. If the 74HC595 ports are enabled during this brief time window, attached devices can be randomly triggered, due to the random initial ON/OFF values in the shift register. Pinscape holds the OE line high until it completes the initialization step, which ensures that the random values in the shift register aren't ever visible on the output pins, in turn preventing any random device activation. Connecting OE to both a Pico port and a pull-up resistor ensures that the OE line is held high from the very instant power is applied.

The OE connection is optional. You can simplify your hardware design by simply connecting the OE pin directly to GND (0V), which permanently enables the output ports. But doing this might result in startup glitches, because it will enable the 74HC595 output ports immediately after power-on, when the shift register contains random on/off values. Any shift register positions that are randomly ON will cause the associated ports to turn ON, firing the attached devices. As soon as the Pinscape software starts running, it will turn all of the ports off again, so the initial random device activation will only last for a fraction of a second, which is why we call it a "startup glitch". This might not be a problem at all for some setups, such as when all of the output devices are LEDs; a brief random LED flash at startup probably won't bother anyone. Glitches are more objectionable when noise-making devices like solenoids or motors are involved, since it can be alarming to have a bunch of solenoids all fire at the same time.

The Pico GPIO port number connected to the latch/transfer pin on the chips, which is labeled STCP on some data sheets, RCLK on others. Connect this to the STCP/RCLK pins on all of the chips in the chain. The GPIO port must be the next higher GPIO port after the 'shift' port; for example, if 'shift' is on GPIO 15, 'latch' must be on GPIO 16.

The number of chips in the daisy chain. This is required so that the software knows how many ports to update on each output cycle.

Sets the operating mode for the chain: true configures the chain in PWM mode, false (the default) configures it in digital mode. In digital mode, the outputs are simple on/off switches. When used as DOF ports, any non-zero DOF "brightness" setting switches the port ON, and a zero DOF level switches the port OFF. In PWM mode, the outputs have full DOF brightness control, with the same 0-255 range that DOF uses.

The Pico GPIO port number connected to the the shift clock pin on the chip, labeled SHCP in some data sheets and SRCLK in others. Connect this to the SHCP pins on all of the chips in the chain.

Sets the clock rate, in Hz, for the shift clock (SHCP/SRCLK) signal sent to the daisy chain. This determines the data bit rate used to transfer port ON/OFF data from the Pico to the chips. The default is 4000000 (4 MHz), which is a conservative default based on the limits specified in the TI SN74HC595 data sheet. Higher frequencies allow faster updates of the output ports, but the chips won't function properly if the frequency is too high for them to process, so the optimal frequency is the highest value that works reliably. That will vary from one setup to the next, since many factors affect the maximum usable speed, such as the specific type of 74HC595 chips you're using (there are several variants on the market) and the physical layout of your circuits boards and cabling. The default should be fine for most setups, but if you encounter any glitching on the outputs, you can try reducing the rate to see if that improves matters.

When operating the chip in digital mode (where the ports are purely ON/OFF switches with no brightness control), the clock speed doesn't need to be very fast; a setting as low as 100000 Hz should be fine. The speed is much more important when operating the chips in PWM mode, because it determine the PWM refresh cycle period, which must be at least 100 Hz to avoid visible flicker if you're using the chips to control lighting devices like LEDs. The default setting of 4000000 Hz yields a refresh rate around 240 Hz with an 8-chip daisy chain (and shorter daisy chains are proportionally faster), so it should be a good compromise between PWM refresh rate and signal integrity. If you find that outputs are flaky, you can try reducing the clock speed, but LED flicker might become noticeable if you go below about 1000000 Hz. You can also try increasing the clock rate if you want to take the PWM refresh rate higher, although I don't think there's much benefit to doing so. LED flicker should be fully gone at 200 Hz, so there's no need to go higher just for the sake of lighting devices. The main reason you might want to drive the PWM rate much higher than 200 Hz would be to address acoustic noise problems in inductive devices like solenoids and motors, and to do that, you generally have to raise the PWM rate to about 20 kHz, so that it's beyond the human hearing range. That's unfortunately not possible with these chips, because it would require a shift clock rate in the 300 MHz range, which is far beyond the documented limits of these chips even under the best conditions.

The 7-bit I2C address of the chip. The chip's address is configured by the wiring on its ADDR pin, which can select among four addresses (0x48, 0x49, 0x4A, 0x4B). Set this property according to the ADDR pin wiring.

The input channel number or numbers you're using on the chip. The ADS1115 has four input pins, AIN0 to AIN3, that can be connected to up to four separate analog inputs that you want to measure. This property lets you tell Pinscape how these map to "logical" channels, which are the channels that Pinscape actually reads. If you only need to measure one input voltage with the chip, you only need to configure one logical channel.

The simplest way to connect voltage inputs to the ADS1115 is as "single-ended" inputs, where each AINx pin measures a positive voltage relative to GND. This configuration is suitable for the most common virtual pin cab use case, which is measuring the voltage on a potentiometer, such as a plunger position sensor or a joystick. To use this configuration, simply connect the analog voltage source you wish to measure, such as the wiper pin from a potentiometer, to one of the AINx pins. List the AINx pin number in the channel property. For example, if the pot wiper is connected to AIN3, use channel: 3 to set up a logical channel reading from pin AIN3.

The ADS1115 also allows "double-ended" inputs, where you use two AINx pins to measure the voltage differential between two signals. This lets you use a positive voltage as the reference point, instead of GND. This is especially useful if you have a separate analog power supply with a more precise voltage regulator than the digital 3.3V supply, or if the voltage being measured only varies over a small portion of the 3.3V range. The reference Pinscape Pico expansion boards take advantage of the differential capability by providing a voltage divider to create a 1.65V voltage reference on AIN3, as shown in the diagram below; use channel: "AIN0/AIN3" for this wiring arrangement. The benefit of this setup is that you can use a smaller amplifier range setting in the ADS1115 input stage, since the potentiometer reading can only vary from -1.65V to +1.65V relative to the 1.65V reference on the divider. This effectively adds one bit of resolution to the digitized result.

The ADS1115 only allows double-ended inputs on certain channel pairings, as shown below.

You can set up multiple logical channels, by using an array for the channel property. And you can freely mix and match single-ended and double-ended inputs. For example, channel: ["0/1", 2] sets up two logical channels, one that reads a double-ended input on pins AIN0/AIN1, and a second that reads a single-ended input on AIN2.

The ADS1115 can physically only sample one channel at a time, so if you configure multiple channels, the chip has to cycle through the channels in a round-robin rotation. This slows down the sampling rate for each channel by a factor of N (the number of channels configured), because the chip has to complete an entire sampling period for each channel before moving on to the next. For time-critical devices like a plunger sensor, it's better to devote the whole ADS1115 chip to a single input so that the chip doesn't have to divide its time among other inputs. You can connect up to four ADS1115 chips to the Pico, so if you need multiple inputs and maximum speed per input, the best approach is to connect multiple ADS1115 chips.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected.

The GPIO port connected to the chip's ALERT/RDY pin. You can omit this if the pin isn't connected to a Pico port. It's preferable to connect the pin to the Pico, because it allows more efficient use of the I2C bus by letting the Pico know when a new sample is ready without any unnecessary I2C polling.

The sampling rate, in samples per second. This determines the rate at which the chip produces samples for the Pico to read across the I2C connection; internally, the chip collects samples at a higher rate, and averages them over the I2C reporting period, so longer periods improve the sampling quality by averaging out noise in the signal. The chip only supports certain fixed rates: 8, 16, 32, 64, 128, 250, 474, and 860 samples per second. You can set sampleRate to any value, but the actual rate will be set to the closest of those allowed rates. The default is 860.

Sets the full-scale voltage range for the ADS1115 inputs. The ADS1115 has an internal amplifier that can be configured to scale the voltage input to different ranges. This is useful because it allows you to adjust the voltage range that the chip measures to be as close as possible to the actual physical voltage range that the input will use. The chip can be configured for the following ranges:

You can set this to any numeric value, but the chip can only accept the values listed above, so Pinscape will choose the closest match (the one with the smallest numeric difference from the value you specify) if you enter a value not listed.

The default is 4.096, which is suitable for most Pico applications, where the analog voltage you're measuring is in the same range as the Pico's GPIO port logical range, 0V to 3.3V. If you're connecting a device that uses a wider or smaller range of voltages, you can improve the resolution of the measurements by changing the range setting.

It won't damage the chip if the actual voltage input exceeds the full-scale range. The chip physically tolerates voltages on the AINx inputs from 0V to slightly over the supply voltage, usually 3.3V, regardless of the amplifier range setting. A voltage that exceeds the amplifier range setting simply clips to the maximum digital readout value (+32767).

Important: The voltageRange setting only sets the internal range on the input amplifier stage within the chip. It doesn't make it safe for the input voltage at the AINx pin to exceed the 0 to 3.3V supply voltage range. Never apply a voltage below 0V or above 3.3V to an AINx pin. Refer to the Absolute Maximum Ratings section in the ADS1115 data sheet for details on the safe operating ranges.

The Pico GPIO port number connected to the chip's channel "A" pin.

The Pico GPIO port number connected to the chip's channel "B" pin.

This is an object that specifies the action that's triggered when the logical button is activated by its input source.

Assigns the button a name, which you can use to refer to the button elsewhere in the configuration, such as in a computed output source (via the button() source type).

Marks the button as a USB wake-up button. If this is true, pressing the button while the PC is in sleep mode will send a USB wake-up signal to the PC. (The PC has to be configured to obey wake-up signals, which is usually the default on Windows PCs, but it might require modifying settings in your Windows power preferences and possibly the PC's BIOS.)

For a button with type="shift", this sets the bits that are added into the "global shift state" when the button is pressed.

For any other button type, this sets the value that the following formula must match each time the button is pressed for the button to activate:

global-shift-state AND shiftMask == shiftBits

See shiftMask for more details on how the shift bits and shift mask work together to determine how the button reacts to modifier buttons.

Sets the bits in the "global shift state" that the button is sensitive to.

When the button is pressed, Pinscape combines this button's shiftMask with the current global shift state using a bitwise AND. It then compares the result to the button's shiftBits. If the two values are equal, the press activates the button. Otherwise, the press is ignored.

This can be used to make a button sensitive to one or more modifier buttons, or to make it insensitive to all of the modifier buttons. The table below lists some basic formulas for how to set this up (in combination with shiftBits) to get different effects. For the examples in the table, let's say that we've set up the following shift buttons:

• EXTRA BALL - shiftBits: 0x0001
• EXIT - shiftBits: 0x0002

You can easily extend this idea to add as many more shift buttons as you need, up to a total of 32 of them. Just keep picking the next higher bit value for each added button: 0x0004, 0x0008, 0x0010, etc.

shiftMask has no effect for a button that's defined with type "shift". Shift buttons always mean one thing and always ignore other shift buttons.

Specifies the physical device port or data source that serves as the input for the logical button state. For a physical button, this is a hardware port connected to the button switch, such as a Pico GPIO port or a shift register input port. Buttons can also take their input from software sources, such as the plunger and nudge subsystems, or the IR remote control receiver.

The logical button type, which determines how On/Off state changes on the underlying physical button input are interpreted for the logical button. The default is "push", which is an ordinary momentary pushbutton.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected. This chip has a fixed I2C address, so you only have to specify the bus number; there's no need to specify the address.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected. This chip has a fixed I2C address, so you only have to specify the bus number; there's no need to specify the address.

Settings for software control over the power supply to peripheral devices on the expansion board, if any. Some expansion boards might provide a mechanism that lets the Pinscape software control the power supply to the peripheral chips on the expansion board, via a Pico GPIO port. Software power control is useful because it allows Pinscape to execute a hard reset on all of the on-board peripherals, by cycling their power supply. If your expansion board has such a feature, you can configure it here.

Cycling the power is usually the most certain way of clearing any error or fault conditions on the chips. Some peripherals chips are complex enough that they can glitch or lock up, much like a computer program can, due to bugs in the chip, or invalid commands sent from the Pico, or electrical faults in the external environment. Whatever the cause, some chips that get into such a state can stay stuck there until the power is cycled. One obvious way to cycle the power would be to physically unplug all of the power inputs to the board, but this can be extremely inconvenient in a pin cab, where the board is locked inside the cabinet, and might be hard to reach even after opening up the cabinet. It might seem like the next best thing would be to do a software reset on the Pico, or reboot the whole PC, but those might not be good enough, because they might not actually cut power to the Pico or the expansion board. The Pico gets its power through the USB cable, and most PCs leave USB power on continuously even when the PC is rebooting or shut down. That's why some expansion boards might give the Pico a way to control peripheral power through a GPIO port directly. When you enable this feature, Pinscape uses it to cut power to all of the peripherals during each software reset, ensuring that they're all reset to their pristine power-on conditions every time the Pinscape software starts up, with no need to unplug any cables.

Enables or disables the interface. The interface is enabled by default. The only common reason for disabling it is for strict LedWiz emulation.

Set this to true to enable the virtual USB gamepad, false to omit it from the USB setup.

Sets the data source for the gamepad's RX (rotational X) axis, using the same notation as gamepad.x.

Sets the data source for the gamepad's RY (rotational Y) axis, using the same notation as gamepad.x.

Sets the data source for the gamepad's RZ (rotational Z) axis, using the same notation as gamepad.x.

Sets the data source for the gamepad's Slider #1 axis, using the same notation as gamepad.x.

Sets the data source for the gamepad's Slider #2 axis, using the same notation as gamepad.x.

Sets the data source for the gamepad's X axis. This is optional; if you omit it, the axis will still be present in the USB virtual gamepad you see on the PC, but it'll just sit stationary at the center position all the time. The axis data source is specified as a string, naming the underlying physical control to use as the axis position.

Sets the data source for the gamepad's Y axis, using the same notation as gamepad.x.

Sets the data source for the gamepad's Z axis, using the same notation as gamepad.x.

Sets the operating mode for the bus:

• true - enable the bus unconditionally; this is the default if enable is omitted
• false - disable the bus; equivalent to omitting the i2c0 definition entirely
• "on-demand" - enable the bus only if one or more devices are configured on it

Controls the internal pull-up resistors on the SDA and SCL GPIO ports. Set to true to enable the internal pull-ups, false to disable them. The default if this isn't specified is true.

The I2C bus design requires pull-up resistors on the SDA and SCL lines, to the bus logic level (3.3V for the Pico). One easy way to satisfy this requirement is to enable the Pico's internal GPIO port pull-up resistors on the SDA and SCL ports. However, this isn't considered good practice, because the Pico's internal pull-ups are too weak. Typical I2C pull-up resistors should be in the neighborhood of 4K to 10K ohms (the exact value depends upon how many chips are sharing the bus), whereas the Pico's internal pull-ups are around 50K. The difference can affect signal quality on the bus, so it's better to use external pull-ups where you can choose the appropriate value according to the bus configuration. If your hardware design does include its own pull-ups, it's best to disable the Pico's internal ones, so that they're not added in parallel to the values you specifically chose.

Another scenario where it might be important to disable the internal pull-ups is where the chips on your I2C bus have a separate power supply from the Pico's 3.3V supply. The reference Pinscape Pico Expansion Boards use such a design, to allow the Pico to perform a hard reset on the peripheral chips by power-cycling them under software control. It might be harmful to some peripherals to feed them power via the I2C bus lines while their main power input is disabled, so in this setup it's best to provide power to the I2C pullups through the peripheral power supply rather than through the Pico's main 3.3V power, which is what the internal pull-ups are connected to.

Sets the GPIO port number for the SCL function for this I2C unit. The GPIO port selected must be one of the I2C0 SCL capable pins: 1, 5, 9, 13, 17, or 21.

Sets the GPIO port number for the SDA function for this I2C unit. The GPIO port selected must be one of the I2C0 SDA capable pins: 0, 4, 8, 12, 16, or 20.

Sets the bit rate for the I2C bus; the default is 400000, which is compatible with all of the devices that Pinscape currently supports. The Pico's I2C units support speeds from 0 to 1000000 bits per second, but speeds above 400000 aren't as widely supported by peripheral devices.

Sets the operating mode for the bus:

• true - enable the bus unconditionally; this is the default if enable is omitted
• false - disable the bus; equivalent to omitting the i2c1 definition entirely
• "on-demand" - enable the bus only if one or more devices are configured on it

Controls the internal pull-up resistors on the SDA and SCL GPIO ports. Set to true to enable the internal pull-ups, false to disable them. The default if this isn't specified is true.

The I2C bus design requires pull-up resistors on the SDA and SCL lines, to the bus logic level (3.3V for the Pico). One easy way to satisfy this requirement is to enable the Pico's internal GPIO port pull-up resistors on the SDA and SCL ports. However, this isn't considered good practice, because the Pico's internal pull-ups are too weak. Typical I2C pull-up resistors should be in the neighborhood of 4K to 10K ohms (the exact value depends upon how many chips are sharing the bus), whereas the Pico's internal pull-ups are around 50K. The difference can affect signal quality on the bus, so it's better to use external pull-ups where you can choose the appropriate value according to the bus configuration. If your hardware design does include its own pull-ups, it's best to disable the Pico's internal ones, so that they're not added in parallel to the values you specifically chose.

Another scenario where it might be important to disable the internal pull-ups is where the chips on your I2C bus have a separate power supply from the Pico's 3.3V supply. The reference Pinscape Pico Expansion Boards use such a design, to allow the Pico to perform a hard reset on the peripheral chips by power-cycling them under software control. It might be harmful to some peripherals to feed them power via the I2C bus lines while their main power input is disabled, so in this setup it's best to provide power to the I2C pullups through the peripheral power supply rather than through the Pico's main 3.3V power, which is what the internal pull-ups are connected to.

Sets the GPIO port number for the SCL function for this I2C unit. The GPIO port selected must be one of the I2C1 SCL capable pins: 3, 7, 11, 15, 19, or 27.

Sets the GPIO port number for the SDA function for this I2C unit. The GPIO port selected must be one of the I2C1 SDA capable pins: 2, 6, 10, 14, 18, or 26.

Sets the bit rate for the I2C bus; the default is 400000, which is compatible with all of the devices that Pinscape currently supports. The Pico's I2C units support speeds from 0 to 1000000 bits per second, but speeds above 400000 aren't as widely supported by peripheral devices.

Sets the LedWiz unit number or range for LedWiz emulation on the PC. This tells the LedWiz.dll library on the PC which unit number(s) to use for the virtual LedWiz device(s) it presents to applications. If you don't have any real LedWiz devices in your system (or any other devices that emulate the LedWiz), you should set this to 1, which is the default if you omit it. If you do have any other LedWiz devices (genuine or emulated), set this to a value that doesn't conflict with any of the other devices. For example, if you have two other LedWiz devices with unit numbers 1 and 2, you should set this to 3. That will allow applications to distinguish all three devices without any conflicts. LedWiz unit numbers are limited by the LedWiz's design to the range 1 to 16.

Pinscape Pico doesn't by itself emulate an LedWiz. It doesn't implement the LedWiz USB protocol, so applications that look for the LedWiz purely by its USB interface won't find the Pico, whether you set this property or not. Fortunately, most of the legacy LedWiz-aware applications never look at the USB device interface directly, because Groovy Game Gear (the LedWiz's manufacturer) didn't ever publish the details of the interface; instead, the official application interface to the device was through the LEDWIZ.DLL library that Groovy Game Gear provides. Pinscape Pico takes advantage of this to implement its LedWiz emulation, by providing a replacement version of the LEDWIZ.DLL library that has special knowledge of the Pinscape Pico USB interface.

You can find the replacement DLL at http://mjrnet.org/pinscape/dll-updates.html#LedWiz.dll. Replace any existing copies of LedWiz.dll on your system with that library, and it will provide legacy LedWiz-aware applications with a virtual LedWiz device representing the Pinscape Pico unit. The LedWiz.dll replacement uses the unit number that you set with this property to determine what ID to use for the virtual LedWiz unit presented to applications.

If you have more than 32 logical output ports on this device, LedWiz.dll will create two or more virtual LedWiz units to represent the Pico, because each LedWiz (real or virtual) can only have at most 32 ports. For example, if you've configured 96 logical output ports on the Pico, LedWiz.dll will create three virtual LedWiz units to represent this single Pico. The three units are given sequential ID numbers, starting at the ledWizUnitNum you specify, so if ledWizUnitNum is set to 8, the three units in this example will be assigned LedWiz unit IDs 8, 9, and 10. Alternatively, you can specify exactly which IDs to assign by entering ledWizUnitNum as an array. For example, if you set this to [8, 10, 12], and three virtual LedWiz units are needed, they'll be assigned IDs 8, 10, and 12. (The order of the array doesn't matter; the IDs are always assigned in increasing numerical order.) The array format lets you skip over IDs used by other devices in your system.

Set this to zero to disable the LedWiz.dll emulation for this unit. The LedWiz.dll library won't create a virtual LedWiz to represent this Pico, so the Pico won't be visible at all to legacy LedWiz-aware applications.

LedWiz emulation isn't needed for DOF-based applications, because DOF has direct support for Pinscape Pico.

Sets a name for the device to show in the Config Tool device list. This is purely for display purposes, so it can be anything you like. If you have multiple units attached, this is meant to make it easier to tell which is which when you're looking at the configuration list.

Sets the Pinscape Unit Number for this device. The Unit Number is how DOF and other pinball software identifies the device, and it's really only needed if you have more than one Pinscape Pico attached to your system. You should number each Pinscape Pico unit starting at 1, so the second should be unit 2, etc. Use the same number when you're setting up your DOF Config Tool settings for the device. If you omit this, the default is unit 1, so you don't have to set it at all if you only have one Pinscape Pico. Don't count KL25Z Pinscape units in the numbering - DOF recognizes those as a separate device type, so they have their own separate numbering.

Sets the size of the internal buffer that the receiver uses to store incoming signals while it's processing them. This is in units of pulses received, and it takes about two bytes of RAM per unit. The default is 128, which should be ample.

Sets the GPIO port connected to the DATA/OUT pin of the TSOP384xx IR sensor. This is the only GPIO port connection needed for the sensor (the only other connections it needs are 3.3V power and ground).

Sets the GPIO port where the IR emitter is connected. The emitter must be connected as an "active high" output, meaning that the emitter is activated when the GPIO port is drive high, to 3.3V output.

Set this to true to enable the keyboard emulation. Pinscape won't create its virtual keyboard unless you explicitly tell it to by setting this to true.

Enables or disables LedWiz USB protocol emulation. Disabled by default.

The 7-bit I2C address of the chip. The address is determined by the wiring on the chip's SDO/SA0 pin: if the pin is wired to GND, the address is 0x18; if the pin is wired to 3.3V, the address is 0x19.

Sets the dynamic range for the accelerometer readings, in units of standard Earth gravity. This device allows settings of 2, 4, 8, or 16. The default is 2, which is usually the best setting for a virtual pin cab, since this provides the best sensitivity for mild nudges. Higher ranges sacrifice precision for dynamic range. In a pin cab, we don't really need wide dynamic range, since nudges past a certain point simply result in a TILT condition, so it's more useful to take advantage of the highest available precision to allow finer gradations of effects for milder nudges.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected.

The GPIO port number where the chip's INTERRUPT pin is wired into the Pico, if any. This can be omitted if the interrupt line isn't connected to the Pico. Wiring the interrupt connection is preferred, because it lets the chip notify the Pico immediately when a new sample is available. Without this connection, the Pico has to poll the chip periodically, which can slightly increase the latency between a new sample becoming ready on the chip and the Pico reading it across the I2C bus.

The 7-bit I2C address of the chip. The address is determined by the wiring on the chip's SEL pin: if the pin is wired to GND, the address is 0x1E; if the pin is wired to 3.3V, the address is 0x1D.

Sets the dynamic range for the accelerometer readings, in units of standard Earth gravity. This device allows settings of 2, 4, 6, 8, or 16. The default is 2, which is usually the best setting for a virtual pin cab, since this provides the best sensitivity for mild nudges. Higher ranges sacrifice precision for dynamic range. In a pin cab, we don't really need wide dynamic range, since nudges past a certain point simply result in a TILT condition, so it's more useful to take advantage of the highest available precision to allow finer gradations of effects for milder nudges.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected.

The GPIO port number where the chip's INTERRUPT pin is wired into the Pico, if any. This can be omitted if the interrupt line isn't connected to the Pico. Wiring the interrupt connection is preferred, because it lets the chip notify the Pico immediately when a new sample is available. Without this connection, the Pico has to poll the chip periodically, which can slightly increase the latency between a new sample becoming ready on the chip and the Pico reading it across the I2C bus.

The size, in bytes, of the memory (RAM) buffer that Pinscape uses to store its log messages. The default is 8192 bytes (8K), which is also the minimum size. You can increase the size up to 65536 bytes (64K). The Pico has a limited amount of RAM (about 256K), so the default log buffer is at the low end of the range to avoid eating up too much memory, in case it's needed for other subsystems. You can observe the actual memory usage for your setup using the Config Tool. In most cases, Pinscape only needs about 40K for a fully populated system, leaving lots of memory free for you to increase the log buffer size if you wish. Pinscape automatically reuses space in the buffer as needed by discarding older messages as new messages are added, so it's perfectly okay for the buffer to "overflow". You'll always be able to see the most recent messages no matter how big or small the buffer is; making the buffer larger just lets you see a longer history of messages going back further, since older messages won't have be discarded as quickly as with a smaller buffer. Note that the message history never goes back any further than the last Pico reboot, because the messages are kept in RAM, which is cleared after a reboot.

If true, the log uses ANSI "escape codes" to show each message type in a distinct color (red for errors, yellow for warnings, etc). The default is false (no color coding). The color coding is designed to make it easier to skim through the log and scan for particular types of messages, which can be really helpful if you enabled most of the message types in the "filter" setting. There are two reasons you might wish to turn this off, though. The first is that the color codes take up more space in the log message buffer, so you'll be able to see more older messages if you disable coloring. The second is that some terminal programs might not understand the ANSI codes. The codes have been standard for a very long time, so nearly all good terminal programs handle them properly, but some will just show them as gibberish.

This selects the subset of messages that are kept in the log. Pinscape assigns a "type code" to every message, listed below. The filter lets you select which type codes to keep in the log and which to discard. The property string consists of a list of type codes to include in the log, separated by spaces. For example, to include only warnings and errors, write "warning error". Alternatively, you can tell Pinscape to include everything except the ones you explicitly exclude, by starting the string with a tilde, "~", and then listing the message types to exclude. To include everything except debug messages, for example, you could write "~debug debugex tinyusb". Finally, you can tell Pinscape to include all message types by writing "*".

If true, the log includes a timestamp for each message. The default is false. The Pico doesn't have an on-board clock/calendar, but it can get the date and time from the Windows host whenever it connects to the Config Tool or DOF, and it can include this information log messages. Before the Pico gets the date/time from the Windows host, it just stamps messages with the time since the Pico rebooted, which you can easily identify because they'll show the year 0000. The reason the timestamp is optional is that it takes up space in the log buffer, so the buffer will be able to keep a longer history of older messages if timestamps are omitted.

If true, the log shows the type code for each message. The default is false. The type code takes up additional space in the log buffer, so the buffer will be able to store more older messages if this is disabled.

The 7-bit I2C address of the chip. The address is determined by the wiring on the chip's VPP pin; if the pin is wired to GND, the address is 0x4C, if the pin is wired to 3.3V, the address is 0x6C. Set this property according to the VPP pin wiring.

Sets the dynamic range for the accelerometer readings, in units of standard Earth gravity. This device allows settings of 2, 4, 8, 12, or 16. The default is 2, which is usually the best setting for a virtual pin cab, since this provides the best sensitivity for mild nudges. Higher ranges sacrifice precision for dynamic range. In a pin cab, we don't really need wide dynamic range, since nudges past a certain point simply result in a TILT condition, so it's more useful to take advantage of the highest available precision to allow finer gradations of effects for milder nudges.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected.

The GPIO port number where the chip's INT (interrupt) pin is wired into the Pico, if any. This can be omitted if the interrupt line isn't connected to the Pico. Wiring the interrupt connection is preferred, because it lets the chip notify the Pico immediately when a new sample is available. Without this connection, the Pico has to poll the chip periodically, which can slightly increase the latency between a new sample becoming ready on the chip and the Pico reading it across the I2C bus.

The 7-bit I2C address of the chip. The address is determined by the wiring on the chip's SA0 pin: if the pin is wired to GND, the address is 0x1C; if the pin is wired to 3.3V, the address is 0x1D.

Sets the dynamic range for the accelerometer readings, in units of standard Earth gravity. This device allows settings of 2, 4, or 8. The default is 2, which is usually the best setting for a virtual pin cab, since this provides the best sensitivity for mild nudges. Higher ranges sacrifice precision for dynamic range. In a pin cab, we don't really need wide dynamic range, since nudges past a certain point simply result in a TILT condition, so it's more useful to take advantage of the highest available precision to allow finer gradations of effects for milder nudges.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected.

The GPIO port number where the chip's INT1 (Interrupt #1) pin is wired into the Pico, if any. This can be omitted if the interrupt line isn't connected to the Pico. Wiring the interrupt connection is preferred, because it lets the chip notify the Pico immediately when a new sample is available. Without this connection, the Pico has to poll the chip periodically, which can slightly increase the latency between a new sample becoming ready on the chip and the Pico reading it across the I2C bus.

Sets the dynamic range for the accelerometer readings, in units of standard Earth gravity. This device allows settings of 2, 4, or 8. The default is 2, which is usually the best setting for a virtual pin cab, since this provides the best sensitivity for mild nudges. Higher ranges sacrifice precision for dynamic range. In a pin cab, we don't really need wide dynamic range, since nudges past a certain point simply result in a TILT condition, so it's more useful to take advantage of the highest available precision to allow finer gradations of effects for milder nudges.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected. Note that the MXC6655XA has a fixed I2C address, so you only have to specify the bus it's attached to; there's no need to specify the address.

The GPIO port number where the chip's INT (interrupt) pin is wired into the Pico, if any. This can be omitted if the interrupt line isn't connected to the Pico. Wiring the interrupt connection is preferred, because it lets the chip notify the Pico immediately when a new sample is available. Without this connection, the Pico has to poll the chip periodically, which can slightly increase the latency between a new sample becoming ready on the chip and the Pico reading it across the I2C bus.

Sets the physical accelerometer device that serves as the source of the nudge data stream. This is normally not required, because the nudge system will automatically choose whichever accelerometer device is configured via its device key. If for some reason you have more than one accelerometer attached, you can use this to select the one to use for nudging, by setting source to a string giving the configuration key for the desired device: "mxc6655xa", "lis3dh", etc.

Select the physical accelerometer device axis to use for the X axis for nudging. The nudge X axis is the side-to-side direction in the pin cab. If your accelerometer is rotated from this orientation, you can use nudge.x to select the appropriate device axis to use. This should be one of "+" or "-" followed by "x", "y", or "z", as in "+x" or "-z". You can use "-" to reverse the physical axis if the accelerometer orientation is backwards from the standard pinball simulator orientation, which has positive X going to the right.

Select the physical accelerometer device axis to use for the Y axis for nudging. The nudge Y axis is the front-to-back direction in the pin cab. If your accelerometer is rotated from this orientation, you can use nudge.y to select the appropriate device axis to use. This should be one of "+" or "-" followed by "x", "y", or "z", as in "+x" or "-z". You can use "-" to reverse the physical axis if the accelerometer orientation is backwards from the standard pinball simulator orientation, which has positive Y going towards the back of the cabinet.

Select the physical accelerometer axis to use for the nudge Z axis. The nudge system currently doesn't make any use of the Z axis, so you can omit this, but you can include it for the sake of completeness, and in case it becomes more important in future versions. This should be one of "+" or "-" followed by "x", "y", or "z", as in "+x" or "-z". You can use "-" to reverse the physical axis if the accelerometer orientation is backwards from the standard orientation, which has positive Z facing up.

The logical axis source for the nudge acceleration X axis (left/right), using the same syntax as the gamepad axis properties. The default value if this isn't specified is "nudge.x".

The logical axis source for the nudge acceleration Y axis (front/back), using the same syntax as the gamepad axis properties. The default value if this isn't specified is "nudge.y".

Set this to true to enable the Open Pinball Device interface on this Pinscape Pico unit.

The logical axis source for the plunger position axis, using the same syntax as the gamepad axis properties. The default value if this isn't specified is "plunger.z0".

The logical axis source for the plunger speed axis, using the same syntax as the gamepad axis properties. The default value if this isn't specified is "plunger.speed".

The logical axis source for the nudge velocity X axis (left/right), using the same syntax as the gamepad axis properties. The default value if this isn't specified is "nudge.vx".

The logical axis source for the nudge velocity Y axis (front/back), using the same syntax as the gamepad axis properties. The default value if this isn't specified is "nudge.vy".

The cooling time for the port, in milliseconds. This is an amount of time that must elapse between high-power activations of the port. If the port is activated at high power, turned off, and then reactivated at high power a short time later, the new activation is limited to the powerLimit setting until the cooling time elapses. This is designed to avoid pathological cases where the host is switching the device on and off so rapidly that the high-power time limit never kicks in, but nonetheless leaving it on long enough overall that it could overheat. The cooling time ensures that the duty cycle is reduced in this situation, providing an additional layer of protection in addition to the time limit.

Selects the physical output port associated with this logical DOF port.

If this is set to true, and the port has a source formula, the source computation is applied even when the USB connection to the host is suspended, or when the cable is disconnected. "Suspended" means that the host is physically connected but not sending data, which on Windows is usually the case when the computer is one of the low-power modes - sleep, hibernate, or shutdown. By default, Pinscape stops applying the source formula at these times, on the assumption that you don't want any feedback devices to activate when the host is powered down. There might be times when you do want selected devices to continue operating during host shutdown, though, such as power indicator lights or effects based on time-of-day considerations. Setting this property to true tells Pinscape to continue operating the port's source even when the USB connection is down.

This property doesn't have any effect if the port doesn't have a source formula. Ports that don't have computed sources take their instructions from the host via the USB connection, so they'll necessarily be off when the USB connection is suspended or broken. This property also doesn't have any effect when the power to the main Pico is off, for the obvious reason that the Pinscape software can only run when the Pico is powered. If the Pico receives power only through the USB port, disconnecting the USB cable will have the side effect of removing power to the Pico. In order to continue running when the USB cable is disconnected, the Pico must have a secondary power source through its VSYS pin.

Assigns a string name to the port. The name can be used to refer to the port elsewhere in the configuration file, such as in tvon.relay.port or plunger.zbLaunch.output. Using a port name in these cross-references instead of a port number makes your configuration file more robust, because a port number in a cross-reference would have to be changed every time you insert or delete a port somewhere before the referenced port. A cross-reference by name isn't affected by changes to the order of the port list.

Set this to true to mark the port as a "noisy" port for Night Mode purposes. All ports marked as noisy are disabled when Night Mode is in effect.

The reduced power limit to apply after the full-power activation time limit (timeLimit) has been exceeded, or during the cooling period after a full-power activation (coolingTime). For a digital on/off port without any PWM control, this should be set to zero to completely shut off the device after the time limit has been exceeded (the equivalent of the Chime Logic feature in KL25Z Pinscape). For a PWM-capable port, this can be set to a reduced PWM duty cycle that keeps the device actuated but is safe to maintain for long periods without overheating the device. This is given as a PWM level from 0 to 255, where 0 is fully off and 255 is fully on.

Places this port in a "share group" pool, which makes the physical output device available for dynamic assignment to different logical DOF ports as DOF events are fired. The property value is a string giving the name of the group to which the port belongs, or an array of strings listing one or more groups.

The purpose of a share group is to trick DOF into believing that you have more physical devices than you really do, by sharing a small number of physical devices across a larger number of logical DOF ports. Each time DOF fires one of its logical ports, Pinscape will look in the share group pool for a device that's not currently in use, and will assign it to the DOF port, just for the duration of this one event. When the event ends and DOF sets the port to OFF, the physical device is released back into the pool for use in a future event.

The most common use case for share groups is DOF jet bumper ports. The standard DOF configuration calls for six ports assigned as jet bumpers - back left, back center, back right, middle left, middle center, middle right. This lets DOF make sure that bumper effects in the game are routed to the right spatial location in your cabinet, so that the sound effect sounds like it's coming from the on-screen location of the bumper. In a small pin cab, though, you might not have room for six separate bumper solenoids - there might only be room for one or two. But it's easier to let DOF think you have the standard six, because that lets you use the existing database of effects assignments, which is all based on the assumption that every cab has six bumper devices. Share groups address this use case by letting Pinscape manage the association between six virtual DOF ports, representing the six bumper devices DOF believes every pin cab should have, and the smaller number of physical solenoids you have installed in your cab.

To set up a share group, you have to configure two sets of ports. The first is the virtual DOF ports. This is the larger group of ports that DOF sees. For the DOF bumper ports example, this would be a set of six ports corresponding to the six standard DOF bumpers (back left, back center, etc). Each of these virtual ports is assigned a shareGroup device:

  outputs: [
    // ... other ports ...
    { device: { type: "shareGroup", group: "bumpers" } },   // DOF rear left bumper port
    { device: { type: "shareGroup", group: "bumpers" } },   // DOF rear center bumper port
    { device: { type: "shareGroup", group: "bumpers" } },   // DOF rear right bumper port
    { device: { type: "shareGroup", group: "bumpers" } },   // DOF mid left bumper port
    { device: { type: "shareGroup", group: "bumpers" } },   // DOF mid center bumper port
    { device: { type: "shareGroup", group: "bumpers" } },   // DOF mid right bumper port
    // ... other ports ...
  ],

Those virtual ports are the ones that you assign in your DOF Config Tool configuration. In your DOF Config Tool settings, under Cabinet > Devices > Port Assignments, you assign the numbered Pinscape ports to the named DOF ports - in our example, the six DOF bumper ports.

The second part of a share group is the physical device ports. This is the smaller group of ports that represents the actual physical devices that will be actuated when the DOF effects are triggered. For these ports, you configure them just like a normal device output port, specifying the physical device assignment. Then you add the shareGroup property to the port.

  outputs: [
    // ... other ports
    { device: { type: "gpio", gp: 7 }, shareGroup: "bumpers" },
    { device: { type: "gpio", gp: 8 }, shareGroup: "bumpers" },
    // ... other ports
  ],

Here's how this works during game play. Say that the ball hits the upper left bumper, causing DOF to activate the Pinscape port that you assigned to "10 Bumper Back Left". On the Pinscape side, this port is assigned to a "shareGroup" device with the group name "bumpers", so Pinscape looks for a port with shareGroup:"bumpers" in its properties. In the example above, it'll find the ports assigned to GPIO ports 7 and 8. Pinscape will pick one of these devices that's not already being fired by some other shareGroup port, so let's say that it chooses the one on GPIO 7. Pinscape will activate that port, and it'll also make a note that GPIO 7 is now being used by the Back Left Bumper port for the duration of this event (that is, as long as DOF continues to activate that port).

Now, suppose that we're in multiball mode, and a second ball hits the Mid Right Bumper while this event on GPIO 7 is going on. DOF will fire the Mid Right "shareGroup" device port, and Pinscape will go through the process of identifying an available ports in the "bumpers" group. Since the port on GPIO 7 is already being fired by the Upper Left Bumper event, this event can't use that port. But the port on GPIO 8 is still available, so Pinscape will assign the event to that port.

If a third "bumpers" group event fires while both of these events are still in progress, the third event will simply be ignored, since there aren't any more physical devices available to carry it out.

When DOF finishes with the events on the Back Left Bumper and Mid Right Bumper ports, it'll set the ports to OFF, and Pinscape will release the ports back to the pool of shared "bumper" ports for use in new events.

Pinscape automatically cycles through the pool of shared ports as events arrive, so that the devices get roughly equal use. This is meant to add variety to the effects, so that every bumper hit doesn't sound exactly the same as the last.

Multiple groups: When a physical port's shareGroup property is an array listing multiple groups, the port can be claimed by virtual DOF ports that are assigned to any of the listed groups. Likewise, when a type:"shareGroup" device lists multiple groups in its group property, the device can claim ports from any of the listed groups. This lets you arrange the logical and physical ports into overlapping groups to make better use of the limited number of physical devices.

Going back to our jet bumpers example, suppose we have a mini-cab with just two physical solenoids, one on the left, and one on the right. We'd like to make sure that all of the left-side DOF bumpers get assigned to the left solenoid, so that the sound effects come from the right spatial location, and likewise, that the right-side DOF bumpers get assigned to the right solenoid. That leaves the DOF center bumpers. Since we don't have a third solenoid, we'd like the DOF center bumpers to just go to any solenoid, whichever is available. We can accomplish this with overlapping groups:

  outputs: [
    // ... other ports ...
    //
    // DOF ports
    { device: { type: "shareGroup", group: "left bumpers" } },     // DOF rear left bumper port
    { device: { type: "shareGroup", group: "center bumpers" } },   // DOF rear center bumper port
    { device: { type: "shareGroup", group: "right bumpers" } },    // DOF rear right bumper port
    { device: { type: "shareGroup", group: "left bumpers" } },     // DOF mid left bumper port
    { device: { type: "shareGroup", group: "center bumpers" } },   // DOF mid center bumper port
    { device: { type: "shareGroup", group: "right bumpers" } },    // DOF mid right bumper port
    //
    // Physical ports
    { device: { type: "gpio", gp: 7 }, shareGroup: ["left bumpers", "center bumpers"] },   // left-side physical solenoid
    { device: { type: "gpio", gp: 8 }, shareGroup: ["right "bumpers", "center bumpers"] }, // right-side physical solenoid
    //
    // ... other ports ...
  ],

We've assigned each DOF virtual bumper port to a group based on the cabinet location - left, center, or right. Each physical port is assigned to two groups: one representing its left/right location, and one for the center bumpers. When a DOF "left bumpers" port fires, it can only claim the left-side physical solenoid, since it's the only solenoid in the "left bumpers" group. But when a DOF "center bumpers" port fires, it can claim either physical solenoid, since both are in the "center bumpers" group.

Interaction with direct DOF commands: When a port is assigned to a share group, the port ignores DOF commands sent directly to the port. It only accepts commands from the virtual type:"shareGroup" device port that's currently controlling the share group port. So DOF is still able to send commands to a share group port, but only indirectly, through the port's temporary share group assignment.

Defines a local "data source" for the port, overriding DOF control over the port. Most ports don't have data sources, because you want DOF to control them directly. But in some cases, you want to control a device locally on the Pico, without DOF being involved. In other cases, you might want to apply some modifications to the settings that DOF sends to the port, such as modifying the intensity level, or combining DOF inputs from multiple ports. All of this can be accomplished with data sources. Data sources are essentially formula calculations that you apply to a port, taking some input, applying some calculations, and producing an output that goes to the physical port.

Enter the data source as a string, composed from the functions listed below.

Italics in the function descriptions represent placeholders. These aren't meant to be written literally, but rather must be replaced by the actual values you wish to use. For example, in button(n, on, off), you don't write a literal n where it says n; instead, you substitute a button number. Likewise, you don't write literally on or off in those positions; you substitute the PWM level values to use when the button is ON (pressed) or OFF (not pressed), respectively. So you might write something like 'button(7, 255, 0)' to say that the output port should be at PWM level 255 (100% duty cycle, full brightness) when button 7 is pressed, and PWM level 0 (0% duty cycle, fully off) when the button is not pressed. You can also use another source expression in these positions for more complex effects. For example, 'button(7, blink(500, 500), 0)' makes the output port blink on and off at 500ms intervals when the button is pressed.

You can also use simple algebraic notation, such as #7 * 0.5 (half of the value computed on port #7), 255 - sine(1000) (invert a sine wave), or (255 + sine(1000))/2 (a sine wave offset by half brightness). The syntax follows that of C/C++/Javascript, with the usual set of operators: +, -, *, /, %, =, ==, ===, !=, !==, <, <=, >, >=. The Javascript-like operators === and !== test for "exact" equality, which means that the types and values of the operands are identical; whereas the regular == and != comparisons compare only the values, and only after coercing the values to compatible types.

There are several "datatypes" for the intermediate values used in calculations: DOF port levels, which are integers from 0 to 255; floating point numbers, which can take on a wide range of values (positive or negative values with magnitudes up to about 3.4e+38, and fractions as small as about 1.2e-38); 2D vectors; and RGB values with separate red, green, and blue components. The math operators generally operate upon the components for the vector and RGB types, yielding the same composite type as a result. The final overall result of a calculation is always automatically converted back to a DOF port level value, 0 to 255, before being sent to the hardware. If the calculation yields something else, it's converted as follows: floating-point values are converted to integers and then clipped to the 0-255 range; vector values are converted to their magnitudes, then clipped to the 0-255 range; and RGB values are converted to their grayscale equivalents.

One simple use for computed outputs is to make adjustments to DOF outputs, to correct the DOF output to better fit a particular hardware device. For example, if one of your LEDs is always too dim or too bright, you could use a computed output formula to adjust the DOF value into a better range. If you wanted to cut the DOF brightness setting in half, for example, you could write self/2; or if you just wanted to limit the maximum brightness to 50%, clip(self, 0, 128). Or, if you want to boost the brightness by 2X, self*2. (Of course, you can't boost it above 100%, so any DOF input above 128 would clip to the maximum value of 255.)

The waveform functions - sine(), sawtooth(), blink(), ramp() - can be used to add a dynamic element to a static DOF output. For example, if you want to create a light that blinks whenever ZB Launch Mode is in effect, you could write zblaunchmode(blink(500, 500), 0). For smooth on/off fading instead of blinking, use zblaunchmode(sawtooth(1000), 0).

A more complex use case is to combine multiple DOF channels into a single feedback device output. For example, if there's an RGB DOF signal that you want to convert into a simple grayscale value, the grayscale() function will do the trick: grayscale(#10, #11, #12), where outputs number 10, 11, and 12 are the DOF red, green, and blue channels that you want to convert. Note that using channels 10, 11, and 12 like this doesn't preclude also using them to directly control an RGB LED, so you can get both effects without changing anything in the PC-side DOF configuration. If an RGB LED is connected to ports 10-11-12, it will show the DOF output directly, even though the grayscale() formula is also reading from the ports at the same time, and using it to control the device attached to whichever port the grayscale() formula is defined on.

You can also use computed outputs to do the opposite, taking a single DOF channel and using it to control a full-color RGB, by synthesizing a color signal with a formula. The hsb() function is handy for this sort of thing, since you can use the monochrome DOF channel as the brightness input to the HSB color generator, and synthesize the hue from some other source. To convert a monochrome DOF channel into a rotating color-wheel effect, for example, use the "ramp" function as the hue input: hsb(ramp(2000), 255, #10) yields a color wheel that rotates over 2 seconds (2000 ms), at full saturation, with the brightness coming from the DOF setting for output #10. Alternatively, you could use the DOF input itself as the hue signal, and simply show the light at full brightness whenever the DOF signal is non-zero: hsb(#10, 255, if(#10, 255, 0)). The if() sets the brightness to 255 (100%) whenever the DOF channel has any non-zero value, and sets it to zero otherwise. To wire the synthesized RGB signal to a set of three outputs, you'd place the same formula in each output slot, using the .red, .green, and .blue properties to extract the individual channels, as in hsb(ramp(2000< 255, #10).red.

The arctan function converts a vector quantity into an angle. You could use this in combination with the HSB color generator to display the current nudge accelerometer reading on an RGB LED by using the direction of the nudge as the color, and the force of the nudge as the brightness: hsb(arctan(nudge), 255, nudge.magnitude).

The conditional functions (if, select, nightmode, button, etc) let you apply complex effects that vary according to the current state of the system. For example, rather than making Night Mode completely shut off a particular output, you could instead reduce the PWM level on the output: nightmode(0.5, 1) * self attenuates DOF's setting for PWM level on the current port by half when Night Mode is in effect, and leaves it at the full blast otherwise. button('start', blink(250, 250), 0) blinks the outputs any time the button named "start" is pressed; or, if you prefer a smoother fade in/out effect instead of blinking, button('start', sawtooth(500), 0) or button('start', sine(500), 0) would do the trick.

Sets the full-power activation time limit for the port, in milliseconds. If this is zero or omitted entirely, there's no time limit on the port. When a time limit is imposed, Pinscape will reduce the port's PWM level to its powerLimit setting after the time limit elapses. This is the equivalent of the Flipper Logic in the KL25Z Pinscape software, but gives you more precise control (in combination with the other properties) of the behavior.

The 7-bit I2C address of the chip. The PCA9555's I2C address is configured in the chip's wiring, via its A0/A1/A2 pins. Any address in the range 0x20 to 0x27 can be set in the wiring. Set this property according to the A0-A2 wiring.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected.

Sets the initial output port states. This can be set as an integer giving a bit mask of the on/off states of the ports, or as an array of true/false or 0/1 values.

If expressed as an integer, each bit of the value corresponds to the on/off state of a port (a 0 bit is OFF, a 1 bit is ON). The low-order bit of the value (0x0001) gives the value for port 0_0, and the bits are assigned to ports consecutively in bit order. So port 0_1 is the second bit (0x0002), 0_2 is the third bit (0x0004), and so on, with the high-order bit (0x8000) assigned to port 1_7. This format is obtuse in general, but it has its concise charm for certain cases, such as when you want to set all of the ports to the same level (all OFF is 0x0000, all ON is 0xFFFF), or perhaps if you want to set the whole 1_X block ON and the whole 0_x block off (0xFF00).

If expressed as an array, each element of the array corresponds to one port, starting at 0_0 for the first element, 0_1 for the second element, and so on. For example, to turn all of the 0_X ports OFF and all of the 1_X ports ON, you could write [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1]. This is a lot more verbose than the integer format, but much more readable for cases where the values are mixed.

The GPIO port number where the chip's INT (interrupt) line is connected. This is optional; omit if if the interrupt line isn't connected. The software is more efficient if you connect the interrupt line, because the interrupt signal lets Pinscape detect when the input state of the chip has changed without performing an I2C bus transaction, which saves time on unnecessary I2C polling. Note that the chip's interrupt line is specifically designed to be shared among multiple PCA9555 chips, to conserve GPIO ports on the Pico. You can wire the interrupt lines from multiple PCA9555 chips together, connecting them all to a single Pico GPIO port. The Pinscape software specifically recognizes and supports that configuration.

The 7-bit I2C address of the chip. The PCA9685's address is set by the wiring to its address pins (A0 to A5), for addresses from 0x40 to 0x78, excluding the reserved address 0x70. Set this property according to the chip's physical A0-A5 wiring.

Sets the "drive mode" for the output ports on the chip:

• "totem-pole", "totem" = totem-pole mode. The chip drives an output port to 3.3V when on, and connects it to GND (0V) when off. In this mode, the chip acts as the voltage source for the attached LED or other device, so the device's positive terminal should be connected to the PCA9685 port, and its negative terminal should be connected to ground (with a current-limiting resistor in series as needed).
• "open-drain", "od" = open-drain mode. In this mode, the chip acts as a low-side switch: it connects an output to GND when the port is LOW, and sets the output to high-impedance mode (which acts like an open switch) when the port is HIGH. When this mode is selected, the attached LED's (or other device's) negative terminal should be connected to the PCA9685 port, and its positive terminal should be connected to the (+) voltage supply (with a current-limiting resistor as needed). Open-drain mode is usually combined with inverted-logic mode, set with invertedLogic, so that a logical ON state corresponds to a physical LOW state on the port, with the port connected to GND.

The PCA9685 does not provide current limiters on the ports in either mode, so current-limiting resistors are required for LEDs.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected.

If true, the output ports use inverted logic: the port output is driven LOW when logically ON, and either driven HIGH or placed in high-impedance state (according to the drive mode) when the port is logically OFF. If false (the default), the port output pin is driven LOW when logically OFF and HIGH/high-impedance when logically ON. Inverted logic mode is usually used in combination with the open-drain drive mode, but that's not a requirement.

The Pico GPIO port number connected to the OE (output enable) pin on the chips.

Alternatively, this can be an object, using the same syntax as outputs[].device. This allows you to connect the OE pin to a GPIO extender such as a PCA9555, saving a GPIO port on the Pico.

This is optional; you should only specify it if the OE pin from the chip is physically wired to the Pico. You can alternatively simply connect the OE pin from the chip to GND, which permanently enables the output ports on the chip.

If you wire the OE pin to a Pico GPIO port (or a GPIO extender port), you should also wire it to VCC through a 10K resistor. This will pull the OE line high throughout the initial power-up process, so that all of the PCA9685 output ports remain disabled until the Pinscape software explicitly enables them.

The advantage of wiring the OE pin to the Pico is that it helps ensure glitch-free startup, by leaving all of the output ports on the PCA9685 in a high-impedance state after power-up until the software has finished initializing the chips. This avoids allowing the ports to activate during the brief window between the Pico CPU reset and the completion of software initialization in the firmware. If OE is hard-wired to GND, all ports will be enabled immediately when the power comes on, so ports might fire briefly before the software initializes them. This can be annoying or even alarming if noisy devices like solenoids are controlled through the ports.

If you have multiple PCA9685 chips, you can connect them all to the same port on the Pico. In that case, you should only define the oe property once, for one of the chips in your configuration (it doesn't matter which one you pick). Pinscape has no need to address the OE pin separately for each chip, since it only operates the port for all of the chips as a group at startup and shutdown, so you can save GPIO ports on the Pico by connecting all of the OE pins together.

Sets the GPIO input port or ports assigned to the Pico ADC. This can be a single port number or a list of port numbers (e.g., [26, 27]). The only ADC-capable ports are 26, 27, 28, 29, and 30. Port 30 is a pseudo-GPIO that's hard-wired to the Pico's internal temperature sensor. If you provide a list, the ports must be listed in ascending order. The entries in the port list correspond to the ADC channel numbers that you can use in joystick axis and plunger assignment entries: "pico_adc" is the first channel, assigned to the first GPIO in the list; "pico_adc[1]" is the second channel, assigned to the second GPIO in the list; "pico_adc[2]" is the third channel.

If true, enables auto-zeroing. True by default. This is only meaningful with sensors that use relative positioning, specifically the quadrature encoder sensor. It's ignored for other sensor types. The point of auto-zeroing is that the quadrature sensors can only detect the distance the plunger has moved since the last reading - they can't detect the absolute position of the plunger. As a result, if the sensor misses any small movements that the plunger makes, its internal notion of the position gets out of sync with the actual physical position. Over time, these small errors accumulate, so the actual position and the sensor's reading of the position get further and further out of sync. Auto-zeroing attempts to correct for that by setting the position back to "zero" - the resting position where the plunger settles when you're not manually pulling or pushing on it - whenever the plunger remains completely stationary for an extended period. Thanks to the spring-loaded design of the plunger, it always comes to rest at roughly the same position when you're not actively applying forces to it, and what's more, it's very hard to hold it perfectly stationary for very long by hand. So it's a very safe bet that the plunger is at the equilibrium position any time it's been still for a while. Auto-zeroing exploits this to wash away any accumulated position errors whenever it observes no movement for a little while.

The auto-zeroing "quiet time" interval, in milliseconds (1000 milliseconds equals one second). The default is 5000 (5 seconds). This sets the amount of time that the plunger has to remain stationary before auto-zeroing takes effect. When the plunger is motionless for this long, Pinscape automatically sets it to the "parking" position, on the assumption that the plunger is at rest at the equilibrium position.

Enables the plunger subsystem. True by default.

Applies to proximity sensors only (VCNL4010, VCNL4020); ignored for other sensor types. This sets the "power law" exponent for converting the analog brightness reading that the sensor measures to plunger distance units. The default is 2, which uses the classic "inverse square" physics formula for the brightness of a distant point source of light, which holds that the brightness varies inversely with the square of the distance. You can change this as needed to optimize the linearity of the distance conversion. The inverse-square law applies to point sources of light, which doesn't quite describe the geometry of the IR proximity sensors. You can experiment with the Config Tool's plunger viewer to check how well the on-screen plunger position tracks the true physical position as you move the plunger through its travel range. Ideally, the on-screen plunger should track the real position linearly - that is, moving the real plunger by a given distance should produce the same on-screen distance change across the whole travel range. If the on-screen plunger moves faster at one end of the range than the other, you can try adjusting the power law exponent up or down to see if that improves the linearity. You can set this an integer or number with a fractional part, such as 2.25.

Sets the sensor that serves as the source of the plunger position reading. In most cases, you can omit this, because the plunger system will automatically choose whichever type of physical plunger sensor device you've configured. In most cases, you'll only attach one such sensor, so there will be no confusion about which one is the plunger input. If for some reason you're using multiple sensors that Pinscape recognizes as plunger inputs, you can use plunger.source to specify which one should actually serve as the plunger input. Set this to a string giving the configuration key for the physical sensor device you want to use, such as "tcd1103" or "aedr8300".

If you configure an ADC device with multiple channels, and you want to use one of those for a potentiometer plunger input, you'll have to set this to specify which channel to use. For the Pico on-board ADC, set this to "pico_adc" to use the first configured channel for the plunger, "pico_adc[1]" to use the second channel, "pico_adc[2]" for the third channel, and so on.

Configures the ZB Launch mechanism. ZB Launch lets you use the mechanical plunger as a substitute for a Launch Ball button. Some virtual pin cab builders like to install both of these, but others prefer a cleaner look with just the plunger - that's what most real pinball machines look like, after all. The downside of not installing both is that some tables don't have a plunger at all and just use a launch button, so you don't get the same playing experience with those tables if you don't have a physical Launch Ball button installed. The ZB Launch feature helps fix that by letting you use the plunger almost like a Launch button.

ZB Launch has two elements. The first is a DOF port that lets the PC-side pinball simulator notify Pinscape, by turning on the DOF port, when a plunger-less table is loaded into the simulator. Pinscape uses this signal to enable the ZB Launch feature. The second element a button input to the PC. When ZB Launch is enabled by the DOF signal, Pinscape monitors the plunger position, and converts plunger motion into button presses that it sends to the PC. The button presses simulate the Launch Ball button. Button presses are generated when you either pull back and release the plunger, or just push it forward into the barrel spring. Pushing and holding the plunger is treated as pushing and holding the Launch Ball button.

Sets the default PWM frequency (in Hertz) for Pico GPIO ports that are used as GPIO outputs. The default is 20000, which was chosen because it's high enough to be out of the human hearing range, so it shouldn't produce any audible noise if a GPIO is used to drive a mechanical device. Motors and solenoids have a tendency to vibrate at the PWM frequency when controlled via PWM, which can produce acoustic noise at the same frequency. If this is in the audible range of human hearing - anywhere from about 40 Hz to 20 kHz - it can produce annoying buzzing or whining noises. Frequencies above 20 kHz are too high for most people to hear, so even if we can't eliminate the vibration, we can at least make it so high-pitched that you can't hear it. Your dog might still find it annoying, though. 20000 Hz is also low enough that it shouldn't pose a problem for external amplifier circuitry, such as optocouplers and MOSFETs. GPIOs that control physical devices generally have to be connected through amplifier circuits, and many of those can only handle a limited range of PWM frequencies. 20 kHz is within the tolerable range for typical circuits used for this purpose.

Sets the polarity of the LED. Set this to "low" if the LED's negative terminals (cathodes) are wired to the GPIO ports. Set it to "high" if the LED's positive terminals (anodes) are wired to the GPIO ports. Most RGB LEDs use the "common anode" configuration, where all of the color channels are wired to a single positive voltage supply through a single pin, and the cathodes (the negative terminals) are wired individually to the GPIO ports. That's the "active low" configuration, and it's the default if you omit this property, since it's the most common configuration. Note that this is something that's designed into the LED itself, so it's not a choice you have to make when doing the wiring, but rather just a feature of the LED that you have to determine from the LED's data sheet.

The GPIO port number attached to the blue channel of the status LED.

This optional property lets you configure the color mix formulas for the various primary and secondary colors that the Pinscape software displays via the status LED. Pinscape uses the standard RGB color-space formulas by default, but many RGB LEDs have such unbalanced intrinsic brightness levels for their color elements that the standard formulas don't end up looking anything like the colors they're meant to display. To fix this and get more accurate color rendition, Pinscape lets you specify the actual formula to use for each primary color. You can set all of these, none of these, or any subset; anything you don't set will use the built-in default formula.

For each element, you can use one of the following formats:

• 0xFF00FF - a number, encoded with hex digits, following the HTML RRGGBB convention
• "#FF00FF" - a string, encoded in the standard HTML #RRGGBB color notation
• "#F0F" - a string, encoded in the standard HTML #RGB color notation
• { r: 255, g: 0, b: 255 } - an object, with r, g, and b properties for the color elements, each with a number from 0 to 255

Note that the status LED uses a coarse-grained PWM control that only allows for 16 gradations of brightness in each channel. This means that the three-digit HTML style "#RGB" formula is really all that you need to specify the colors. Despite this, the full six-digit format is accepted, and the range for the numeric format is 0 to 255 for each color, but levels are rounded to the nearest multiple of 16. The coarse PWM control is used because it avoids using any native Pico PWM channels, which are a limited resource that we'd prefer to leave available for other uses. The status light doesn't need such a mix rich of colors that it justifies tying up the resources. (In fact, the original KL25Z version of Pinscape didn't use PWM colors at all, so it could only show the basic primary and secondary colors; the Pico version's coarse-grained PWM lets its show a few extra colors, such as orange.)

The GPIO port number attached to the green channel of the status LED.

The GPIO port number attached to the red channel of the status LED.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected. This chip has a fixed I2C address, so you only have to specify the bus number; there's no need to specify the address.

Configures the Pico's UART serial port. The UART port sets up a pair of GPIO pins on the Pico as a physical serial port, which you can connect through an adapter to a physical COM port (a 9-pin serial port) on your PC.

An adapter is required to shift the PC's COM port voltage level to the Pico's 3.3V logic level. Search online for "RS-232 3.3V GPIO adapter".

The adapter should plug directly into the PC's 9-pin COM port, and should provide four output pins, usually labeled TX, RX, GND, and VCC (or 3.3V). Connect to the Pico as follows:

If you don't have a physical 9-pin serial port on your PC, you can still use the Pico UART connection, by connecting it to a PC USB port through a USB-to-UART adapter. There are some advantages to doing this instead of using the "virtual" COM port over the Pico's main USB connection, but also the drawback that it requires another adapter. In this case, the thing to search for is a "USB 3.3V UART adapter". The wiring on this type of adapter should be exactly the same as shown above; the only difference is that this adapter plugs into a USB port on the PC rather than a 9-pin COM port.

The UART port and the virtual USB COM port serve exactly the same purpose, so you don't usually need both. In fact, you don't need either one; serial port access is mostly just a convenience for troubleshooting, since it lets you easily access the Pinscape message log and command console. Troubleshooting is, we hope, something that you won't have to do very much of, and even then only when you're initially setting up your system. If all goes well, you shouldn't need a serial port at all, since you should be able to do everything necessary to set up the system through the Pinscape Config Tool.

If you do want to set up a COM port, the USB virtual COM port is the easier of the two to set up, because it doesn't require any extra cabling and doesn't take up any GPIO ports. The UART COM port does have one nice advantage, though: because it's a physical serial connection, it doesn't get "dropped" when the Pico reboots, so you can just connect a terminal window and leave it open forever (or until you reboot Windows, anyway). The USB connection, in contrast, does get dropped every time the Pico reboots, so you have to manually restart the terminal session on each reboot. The UART COM port is more work to set up, but it doesn't suffer from the reboot issue. If you're planning to do development work on the Pinscape C++ firmware, the UART setup is definitely the way to go; otherwise, you'll probably be perfectly happy with the virtual USB COM port.

Configures the USB virtual serial port (also known as a "CDC" port). This works just like the UART serial port, but it doesn't require any GPIO ports on the Pico, and it doesn't require any special cabling, because it runs over the Pico's main USB cable alongside all of the other USB communications. You also don't need any special device driver setup if you're using Windows 10 or later, since Windows 10 and 11 include built-in USB CDC drivers. If you're Windows 8 or earlier, you might need to install a device driver; search for "USB CDC driver" for your operating system version.

The USB COM port is disabled by default. To enable it, simply include this object in the JSON configuration. To connect to the port, you'll need a terminal program on the PC, such as PuTTY. Get the COM port number from the Config Tool's Overview page - it will be listed in the USB Interfaces section. Go to PuTTY, set the Connection Type to Serial, type the COM port number into the Serial Port box, and set the speed to 115200.

Note that the USB COM port is purely optional! You don't have to set this up to configure Pinscape or to use Pinscape with any of the pinball players. The COM port is just there to let you view the message log and access the command console. It's not a necessity - it's more of a troubleshooting aid, and more for power users who are comfortable working with command lines and terminals.

The Pico GPIO port number connected to the sensor's FM (master clock) pin.

The Pico GPIO port number connected to the sensor's ICG (integration clear gate) pin.

Set this to true if there's a logic inverter chip wired between the chip's logic inputs (FM, ICG, SH) and the Pico GPIO ports. The chip's data sheet recommends using a logic inverter because of the relatively high capacitance of the chip's input gates, which some microcontrollers can't drive at the high clock speeds required. This property is true by default, since this is the recommended hardware configuration. Set it to false if the chip's logic inputs are connected directly to Pico GPIO ports with no logic inverter.

The Pico GPIO port number connected to the sensor's OS (analog pixel output) pin. This must be one of the Pico's ADC capable pins, GPIO 26, 27, or 28. Note that the OS pin shouldn't be connected to the Pico GPIO port directly; the chip's data sheet recommends a transistor circuit between the OS port and the ADC input, because the output signal from the chip is too weak for most ADCs to read directly.

The Pico GPIO port number connected to the sensor's SH (shift gate) pin.

The 7-bit I2C address of the chip. The TLC59116's I2C address is set by the wiring to its address pins (A0 to A3). It can be set to addresses from 0x60 to 0x6f, excluding the reserved addresses 0x68 and 0x6B. Set this property according to the chip's physical A0-A3 wiring.

The I2C bus number, 0 for I2C0 or 1 for I2C1, where the chip is connected.

The GPIO port number connected to the chip's RESET pin. Omit this if the RESET pin isn't connected to the Pico (in which case it should be hard-wired to 3.3V through a 10K resistor).

Connecting the RESET pin allows the Pico to perform a hardware reset on the chip under software control, which Pinscape uses to reset the chip during startup. This can be helpful to clear any fault conditions on the chip without the need to power-cycle the whole system.

The Pico GPIO port number connected to the chip BLANK pins. This must be connected to the BLANK pins for all of the chips in the chain.

"Dot correction" data. This is an array of integers, from 0 to 63, that adjusts the PWM duty cycle of each port individually. This is an adjustment that's applied on top of the live value set by DOF or other sources. Its purpose is to compensate for slight differences in the native brightnesses of the individual pixels when the chip is driving a dense pixel array, such as a dot matrix display. Setting a port's DC level to 63 runs the port at full brightness; lower values slightly reduce the brightness. The idea is that you'd adjust brighter pixels downwards until all pixels look the same when driven at the same nominal duty cycle.

This is only used if you connect the DCPRG and VPRG pins from the chips to Pico GPIO ports. In a Pinscape setup, those pins are normally simply connected to GND, which leaves all of the output ports at full brightness by default, with no dot-correction adjustments. Any dcData array is ignored in that case. It's unlikely that dcData wlil be needed in any virtual pin cab setups, but capability is there if needed.

The Pico GPIO port number connected to the chip DCPRG pins. This is optional; if connected, connect it to the DCPRG pins for all of the chips in the chain. If it's not connected to a GPIO port, simply connect all of the DCPRG pins to GND; that's the normal way to connect it in a Pinscape setup. The purpose of the DCPRG pin is to enable "dot correction", which is a feature of the chips designed for applications where the chips are driving dense pixel arrays, where small differences in the native brightnesses of adjacent pixels might be bothersome. In a Pinscape setting, the chips usually drive a diverse collection of devices that wouldn't benefit from dot correction, so this pin is usually left unconnected rather than taking up another GPIO port.

The Pico GPIO port number connected to the chip GSCLK pins. Connect this port to the GSCLK pins for all chips in the chain. This GPIO port must be the next higher port number after the SCLK port. For example, if SCLK is on GPIO 17, GSCLK must be on GPIO 18.

The number of TLC5940 chips connected to the daisy chain. This is required so that the software knows how many port settings to send to the chain on each update cycle.

The PWM frequency, in Hertz (cycles per second). The default is 200; this can be set from 1 to 7324 Hz (the upper bound is a hardware limit of the chip). When the chip is driving LEDs, the frequency affects visible flicker; anything above about 200 Hz should eliminate any flicker. When the chip is driving mechanical devices (motors and solenoids), the PWM frequency sometimes interacts with the mechanisms to cause acoustic vibration at the PWM frequency, which can be audible as buzzing or whining sounds. Adjusting the PWM frequency can often mitigate this. The PWM frequency can only be adjusted across the whole chain (it can't be set individually per port).

The Pico GPIO port number connected to the chip SCLK pins. Connect this port to the SCLK pins for all chips in the chain.

The Pico GPIO Port number connected to the first chip's SIN pin. This GPIO port connects only to the SIN pin of the first chip in the chain. For each subsequent chip in the chain, connect SIN to the previous chip's SOUT (the second chip's SIN connects to the first chip's SOUT, the third chip's SIN connects to the second chip's SOUT, etc).

The Pico GPIO port number connected to the chip VPRG pins. This is optional; if connected, connect it to the VPRG pins for all of the chips in the chain. If it's not connected to a GPIO port, simply connect all of the VPRG pins to GND. This pin works with DCPRG to enable dot correction, which isn't normally needed in a virtual pinball setting.

The Pico GPIO port number connected to the chip XLAT pins. Connect this port to the XLAT pins for all chips in the chain. This GPIO port must be the next higher port number after the BLANK port. For example, if BLANK is on GPIO 15, XLAT must be on GPIO 16.

The Pico GPIO port number connected to the chip BLANK pins. Connect this port to the BLANK pins for all of the chips in the chain.

The number of TLC5947 chips connected to the daisy chain. This is required so that the software knows how many port settings to send to the chain on each update cycle.

The Pico GPIO port number connected to the chip SCLK pins. Connect this port to the SCLK pins for all chips in the chain.

The Pico GPIO Port number connected to the first chip's SIN pin. This GPIO port connects only to the SIN pin of the first chip in the chain. For each subsequent chip in the chain, connect SIN to the previous chip's SOUT (the second chip's SIN connects to the first chip's SOUT, the third chip's SIN connects to the second chip's SOUT, etc).

The Pico GPIO port number connected to the chip XLAT pins. Connect this port to the XLAT pins for all chips in the chain. This GPIO port must be the next higher port number after the BLANK port. For example, if BLANK is on GPIO 15, XLAT must be on GPIO 16.

The GPIO port number where the chip's CLK (serial clock) pin is connected.

The GPIO port number where the chip's SI (serial input) pin is connected.