This window is designed to help set up a Pinscape Pico device's output controller ports, by letting you directly test the Pinscape ports without having any pinball simulation software involved. This bypasses all of the layers of software that the games use, to help isolate any problems. If the port doesn't work in Visual Pinball or other games, but it does work here, you can tell that the problem lies in one of the game software layers. If the port doesn't work here, the problem somewhere in the device setup, either in the physical wiring, the electronics, or in the Pinscape firmware.
This window tests the "logical" output ports, which are the numbered ports that you set up in your JSON configuration file for use in DOF and other game software. Your configuration defines the mapping of each logical port to a physical port, which represents the hardware location where the feedback device (light, solenoid, motor, etc) is wired into the Pico or one of its peripheral chips. A physical port can be one of the Pico GPIO ports, or a port on one of the supported external chips: a PWM controller (TLC59116, TLC5940, PCA9685), a shift register chip (74HC5595), or a GPIO extender (PCA9555). The Device Port Tester window provides a more direct view of the hardware ports that bypasses the whole DOF/logical port setup.
This window shows the list of logical (DOF) ports in the left panel, and the list of configured physical devices in the right panel. You can use the sliders in the left panel to adjust the PWM level on each logical port, and observe the effect on the physical device ports. This lets you play the role that a game program or DOF would normally play, sending commands to the DOF ports to control feedback effects, but without any external game software involved. It also lets you see the inner workings of the ports in more detail than you can see through game programs.
You can't control the physical device ports directly in this view, since they're under the control of the logical ports.
The logical ports in the left panel are the software ports that programs like DOF can access to create feedback effects. We call these "logical" ports because they're entirely software abstractions. What they mean physically is up to you to define in the JSON configuration file.
Each logical port is numbered. Programs like DOF that access the ports for feedback effects work in terms of the port number. The port numbers correspond to the order of the ports in your JSON configuration file, with the first entry labeled Port #1.
This shows the physical device port that the logical port is assigned to. Ports that aren't mapped to physical outputs are shown as Virtual.
This column shows each port's attributes, as a series of icons:
| Gamma correction is enabled for the port. The nominal output level is adjusted when sent to the underlying physical device to make brightness changes to an attached LED look more "linear" to the human eye, so that, for example, brightness level 128 looks about half as bright to the eye as brightness level 255. The eye perceives brightness logarithmically, so the electronic notion of "half power" doesn't translate directly to the perceptual notion of "half brightness". Gamma correction applies an adjustment to the electronic power level on the port to make the apparent brightness more linear to a human viewer. | |
| "Noisy" port. This port is designated as being associated with a noisy device, which tells the Night Mode feature to disable the port when Night Mode is engaged. | |
|
"Inverted" port (the icon is the symbol used in electronic schematics
to represent a logic inverter). The logical port's PWM level is reversed when
sent to the underlying physical device. When the logical port is set to the maximum
PWM level 255, the underlying physical port is set to 0% duty cycle, which
turns the port fully off. When the logical port is at PWM level 0, the
underlying port is turned fully on, at 100% duty cycle. In general, PWM
level X is inverted to PWM level 255-X when send to the physical device.
Note that this doesn't tell you anything about the physical voltage on the port. This just says that the logical PWM level is inverted when sent to the port. Some of the physical output controller chips use "active high" wiring, where the port outputs 3.3V or some other positive voltage when ON, whereas other chips use "active low" wiring, where the port is pulled to 0V when ON. The high or low voltage when a port is ON is intrinsic feature of the particular chip, and it isn't affected one way or the other by the "Inverted" status of the logical port. |
|
| Flipper Logic is enabled on the port. This means that the port has time limitations for continuous ON activation, as specified in your JSON configuration file. Pinscape Pico has a flexible range of options for port time limiters, with the ability to cut the power entirely to the port when the time limit expires, or just reduce it to a safer level, if PWM control is available for the port. | |
|
Computed port: This port has a source,
defined in the JSON configuration, which calculates the PWM level for the port based
on the scripting formula defined in the JSON file. A computed port
ignores the DOF input level and instead uses the result of the source
formula. The formula take its input from sources like button states, accelerometer
input, the plunger position, the current time, and various waveform
generators. Pinscape updates the formula result every few milliseconds,
so the port always shows the "live" result based on the all of its inputs.
Computed ports are still shown as logical ports, and DOF and other programs can still send commands to the port. But in most cases, a computed port ignores its DOF input, since the source formula takes precedence. The reason that DOF input is still allowed is that the DOF input itself can be used as an input to a source formula, so it might still be useful for some ports. |
The Host level box shows the current port PWM level setting as set by the PC (the "host"). When you're playing a pinball game that uses feedback effects through DOF, this is the level most recently commanded by DOF. When you're using the Output Tester window, DOF isn't involved, but you can manually adjust the desired host level with the slider control next to the level box.
The Host level is basically the input to the logical port. For a "Direct" port, this usually just passes through directly to the underlying physical device. If you have Flipper Logic enabled, that will override the host setting when the configured maximum ON time expires. Gamma correction likewise tweaks the numeric level to change it from a linear brightness level to a gamma-corrected power level. And if the Inverted attribute is set on the port, the Host level will be reversed on the 0-255 scale (so level X becomes level 255-X) when sending the level to the underlying physical port. Regardless of all of these adjustments, though, the Host level always records the last level commanded by the host, even if the various other settings change the actual output value before it reaches the physical port.
This is the calculated port PWM level, after applying the source calculation for a computed port. For Direct ports, this just follows the Host level. For Computed ports, this reflects the live result of the source calculation.
As with the Host level, the Calc level reflects the result of the source calculation only, before any of the standard adjustments are applied (the Inverted attribute, gamma correction, and Flipper Logic time limiters).
This is the final PWM output level that the logical port sends to its assigned physical device port, after applying Flipper Logic timers and the Inverted attribute. (This doesn't take into account gamma correction, though, since that's handled later on, after rescaling the DOF 0-255 value to the physical device's native PWM resolution. This lets the gamma correction take advantage of the greater PWM step resolution that some devices use. That can make a big difference at the low end of the brightness scale, where the gamma curve flattens out to subtle gradations between levels that can't be represented in only 8 bits. You can see the numerical effect of gamma correction, if any, on the physical device port in the right panel, which shows the result in the device's native units.)
The logical port value is always on a scale of 0 to 255, where 0 is fully off and 255 is fully on, at 100% duty cycle. Intermediate values represent linearly proportional duty cycles, so 127 is about 50% duty cycle, or half brightness/half power. "Duty cycle" refers the percentage of time that the physical output port is switched on. PWM (Pulse Width Modulation) is a technique for controlling brightness or power by rapidly switching the voltage on and off, hundreds or thousands of times per second (depending on the specific physical device used).
Each port row is equipped with a slider control that lets you adjust the output level on the port, to test that the outputs are working as expected and to see the effect of different settings. The slider adjusts the Host level, which is the same level that DOF sets when it sends commands to Pinscape. This lets you see the effect of all of the source formula calculations and attribute adjustments when applied to any given DOF level.
Note that you can adjust the slider control with the mouse or with the keyboard. Click on the slider to give it focus, which lets you control it with the keyboard:
The right panel shows the physical output devices, including the Pico's GPIO ports (which can be programmed individually as output controller ports) and external peripheral chips that you've set up through the JSON configuration file.
The panel shows the ports grouped by physical chip. Each chip's ports are listed by number, with a box showing the current output level on the port:
Note that output port status is shown even for ports that aren't mapped to logical output ports. The diagram includes ports that are configured as outputs for other purposes, such as sending logic/control signals to peripheral chips.