Feature request: shared outputs

[winxi01]

In some configurations, there may be only a limited number of feedback resources for a higher number of corresponding dof ports. For example, there may be only four contactors available for dof ports for the flippers, sling shots and bumpers (7 dof ports in total).
In this case it would cool if some of the inputs (dof ports) could be assigned to a group of "shared" outputs (contactors) so that one arbitrary unused output of this group fires (if any is available) when the corresponding dof port is triggered.
The PinOne advertises this as "solenoid sharing feature".

[mjrgh]

This is one of the use cases that "computed outputs" were intended for. See outputs.source in the JSON config ref for documentation.

The simplest example would combine a group of N logical DOF ports into a single physical device activation. To do this, you'd create one outputs entry to represent the physical device, and N outputs entries to represent the DOF ports. The N entries for the DOF ports wouldn't be attached to any physical device, so their device.type properties would all be set to "virtual". Their only function would be to accept commands from DOF. You'd map all of your DOF outputs to these port numbers - all of the flippers, slings, and bumpers, in your example. If you have two flippers, two slings, and 6 bumpers, you'd create a total of 10 of these "logical" ports that aren't attached to any physical devices. Then, the single additional port that's mapped to the physical device (a contactor, say) would have its source set to merge the inputs from all of the logical ports.

outputs: [
  { name: "left flipper", device: { type: "virtual" } },    // a virtual port representing the left flipper
  // repeat for all of the other virtual devices to merge
  
  { device: { type: "gpio", gp: 7 },   // this is where the physical contactor that's shared among all of the virtual ports is connected
    source: "or(port('left flipper'), port('right flipper'), port('left sling'), port('right sling'), port('bumper 1'), port('bumper 2'))",  // etc for all ports
  },
],

If you had multiple physical devices, it would be straightforward to do the same thing to assign each physical device to a subset of the ports - one contactor shared by the two flippers, one shared by the two slings, one shared by the six bumpers.

It would be a bit trickier to create a many-to-many "pool" mapping, where all of the logical devices are mapped to the same shared set of physical devices, and you want each logical activation to trigger the "next available" physical device. I think that's what you're describing. It should be possible with a clever combination of logic conditions that take into account the logical port states and the other physical port states, but it might be complex enough to be worth adding some built-in support..

[winxi01]

It would be a bit trickier to create a many-to-many "pool" mapping, where all of the logical devices are mapped to the same shared set of physical devices, and you want each logical activation to trigger the "next available" physical device. I think that's what you're describing. It should be possible with a clever combination of logic conditions that take into account the logical port states and the other physical port states, but it might be complex enough to be worth adding some built-in support..

I think that a reasonably simple approach to implement the many-to-many pool mapping could be to tie each physical device output port m (out of M) to a specific number n of concurrently active virtual dof ports (out of N, while M < N). This number n could be calculated by something like

if(port('virtual dof port 1'), 1, 0) + if(port('virtual dof port 2'), 1, 0) + ... + if(port('virtual dof port N'), 1, 0)

In the source property for the first physical output port one would then have (replace n with the expression from above)

if('n == 1', 255, 0)

for the second physical output port

if('n == 2', 255, 0)

and so on until the physical output port M:

if('n == M', 255, 0)

A drawback with this would be that it can occur that a specific output device is activated by one virtual dof output port but subsequently deactivated by another dof output port. For example, consider the following sequence:

1. All virtual dof ports are low
2. Virtual dof port 1 gets high -> physical output device 1 is active
3. Virtual dof port 2 gets high -> physical output devices 1 and 2 are active
4. Virtual dof port 1 gets low -> output device 2 is deactivated while output device 1 remains active

I'm not sure if this can be solved at the moment because it would involve storing information about the history of the virtual dof output ports.

[mjrgh]

Yeah, I started down the same path you did, and I came to the same conclusion that there'd have to be some kind of memory of which DOF port was being temporarily mapped to which physical device. What I'm picturing is a temporary assignment of virtual port A to physical port B that lasts as long as A is on. There might be some way to contrive it using even more virtual ports (to serve as "variables" in the programming language sense), but I think it would get really complex and ugly and hackish.

I think it would be fairly easy to implement this concept as a special-purpose addition, specifically for the "share group" concept, but I'm also trying to see if there's some more generic 'source' extension that would achieve it. It's not that I'm attached to the idea of doing it exclusively through the 'source' scheme, just that whatever's needed here could conceivably open up even more possibilities by making the "scripting language" (such as it is) more powerful. I probably need to get into the details of what a special-purpose implementation would look like, and see if there's any clean way to fit it into the 'source' system.

[winxi01]

Thanks for pointing this out in such detail. Yes the many-to-many pool mapping is the use case I've in mind. It's good to know that this is possible in principle, I'll have to dive deeper into this to figure out a suitable logic to support this.
The level of flexibility you've put into this nice little device by means of the JSON configuration is truly awesome!

[mjrgh]

0.1.14 has a new Share Group feature that I think will do what you want. I ended up implementing it as a special-purpose feature on the output ports, rather than as an extension to the 'source' scheme, because I couldn't come up with a good way to generalize it. It just seemed like it needed to be handled as a specific case.

There are two new output port elements involved. The first is the type: "shareGroup" device, which designates a port as having a group of shared ports as its underlying physical output. This goes in the outputs array, and creates a logical port that DOF will see as an ordinary port, but which is tied to a pool of physical outputs rather than to a single physical output. When DOF commands one of these ports to turn ON, Pinscape looks for a free port in the associated pool, claims the free port for this specific DOF port, and turns the underlying physical device on. The "claim" lasts as long as DOF leaves this logical port on, and prevents any other DOF port from sending other commands to the same pooled device, so that the DOF event results in a single, coherent physical device effect. When DOF turns the port OFF, Pinscape turns off the underlying physical device, and releases the device back to the pool for use in a future share-group event.

The second element is the underlying port that goes into the pool. These ports represent the physical devices in the shared pool. You don't assign these ports to any effects in the DOF Config Tool - DOF never commands them directly. Instead, these ports get commanded indirectly through the type: "shareGroup" device ports. These ports look exactly like ordinary ports assigned to physical outputs, with the addition of a shareGroup property that gives the name of the group. This is the same name used in the type: "shareGroup" devices in their group property. The name is what creates the association between the shareGroup devices and the pooled physical device ports, and by giving the groups names, the mechanism allows any number of these groups to be created, each with its own collection of DOF ports and pooled physical device ports.

This example shows how you could share two physical output ports among the six standard DOF "bumper" ports.

outputs: [
   // These are the virtual ports that DOF sees and commands.  Assign these ports
   // in the DOF Config Tool to the nominal functions listed.
   { device: { type: "shareGroup", group: "bumpers" } },      // DOF "10 Bumpers Top Left"
   { device: { type: "shareGroup", group: "bumpers" } },      // DOF "10 Bumpers Top Center"
   { device: { type: "shareGroup", group: "bumpers" } },      // DOF "10 Bumpers Top Right"
   { device: { type: "shareGroup", group: "bumpers" } },      // DOF "10 Bumpers Mid Left"
   { device: { type: "shareGroup", group: "bumpers" } },      // DOF "10 Bumpers Mid Center"
   { device: { type: "shareGroup", group: "bumpers" } },      // DOF "10 Bumpers Mid Right"

   // These are the physical device ports that will be activated when the virtual DOF
   // ports above are fired.  Each time a virtual DOF port is fired, the DOF port "claims"
   // one of these ports, and passes the DOF commands on to the underlying physical
   // port.  This "claim" is exclusive, so that no other virtual DOF port will be able to
   // trigger a conflicting effect on the same physical device, and the claim only lasts
   // as long as the DOF effect that triggered it.  As soon as DOF turns the claiming
   // virtual port OFF, the claim is released, and the port goes back into the pool for
   // use in a future effect.
   { device: { type: "gpio", gp: 7 }, shareGroup: "bumpers" },
   { device: { type: "gpio", gp: 8 }, shareGroup: "bumpers" },
],

The implementation in 0.1.14 is only lightly tested, but I think the design is pretty sound, and the firmware seems to execute it as expected. I'm definitely interested in your feedback about how the design fits your use case, though, and of course whether the software does the right thing in your setup.

[winxi01]

Many thanks for this. I'm really excited about this feature — it seems very useful.
I've run some initial tests and noticed three unexpected issues. I also have a suggestion for an enhancement.

I've run the initial tests using a Pico with two connected LEDs and the most recent version of VPX Standalone on Ubuntu. Please note that VPX Standalone's DOF support is still under development, so one or more issues may be related to VPX (libdof).

For the tests, I've used the following simple outputs configuration:

{ device: { type: "shareGroup", group: "flippers" } },   // DOF left flipper (output 1)
{ device: { type: "shareGroup", group: "flippers" } },   // DOF right flipper (output 2)
{ device: { type: "gpio", gp: 7 }, shareGroup: "flippers" }, // Physical LED 1 (output 3)
{ device: { type: "gpio", gp: 8 }, shareGroup: "flippers" }, // Physical LED 2 (output 4)

Issue 1: When the left flipper is fired consecutively, the corresponding LED flickers with every second hit (could not reproduce this for the right flipper):

Issue 2: When the first DOF event occurs for a prolonged period of time, the second DOF event only activates the second output once:

Issue 3: When only one physical output is specified, that output is not triggered by any DOF events. Example configuration:

{ device: { type: "shareGroup", group: "flippers" } },   // DOF left flipper (output 1)
{ device: { type: "shareGroup", group: "flippers" } },   // DOF right flipper (output 2)
{ device: { type: "gpio", gp: 7 }, shareGroup: "flippers" }, // Physical LED 1 (output 3)

Idea for enhanced use case:
Imagine a small pin cab with only two contactors, one mounted on the left side of the cab and one mounted on the right side and, for sake of simplicity, consider a table using only five DOF events: left flipper, right flipper, bumper 1, bumper 2, and bumper 3. One might want to create a share group for all five DOF events that map to both contactors. Additionally, one might want to ensure that the left flipper only triggers the left contactor and the right flipper only triggers the right contactor. With the current implementation, the flippers would trigger either contactor arbitrarily.

For this, I could imagine an additional property forcePort for a device of type shareGroup:

{ device: { type: "shareGroup", group: "flippers and bumpers", forcePort: 6 } },   // DOF left flipper
{ device: { type: "shareGroup", group: "flippers and bumpers", forcePort: 7 } },   // DOF right flipper
{ device: { type: "shareGroup", group: "flippers and bumpers" } },   // DOF bumper 1
{ device: { type: "shareGroup", group: "flippers and bumpers" } },   // DOF bumper 2
{ device: { type: "shareGroup", group: "flippers and bumpers" } },   // DOF bumper 3
{ device: { type: "gpio", gp: 7 }, shareGroup: "flippers and bumpers" }, // Physical left contactor
{ device: { type: "gpio", gp: 8 }, shareGroup: "flippers and bumpers" }, // Physical right contactor

For example, when a DOF event occurs for the left flipper, Pinscape would then simply check if output port 6 (the left contactor) is available rather than iterating through all the available physical devices (of which there are only two in this example).

[mjrgh]

Please note that VPX Standalone's DOF support is still under development, so one or more issues may be related to VPX (libdof).

Try testing against the Config Tool Output Port tester. If the issues don't reproduce there, it's probably something in the experimental clients.

[winxi01]

Thanks for the hint. Could reproduce all three issues with the Config Tool Output Port tester..

Interesting about issue 1 (flickering LED): The Config Tool shows 0 for the Out value on GPIO 8, although the connected LED is flickering:

Steps to reproduce:

1. Connect the Pico
2. Set Port 2 to any value > 0
3. Set Port 2 to 0
4. Set Port 1 to any value > 0
5. Set Port 1 to 0
6. Set Port 1 to any value > 0 again

-> LED on port 4 is flickering.

[mjrgh]

I think I spotted the problem (actually two underlying problems). Test build attached.

Issue32-fix-1.zip

[winxi01]

I think I spotted the problem (actually two underlying problems). Test build attached.

Thanks for the quick patch! I can confirm that all three issues have been fixed.

While testing this fix, I've thought of one other implementation detail: Imagine a simple setup with two DOF ports of the ShareGroup type and one assigned physical output port. Currently, the behavior with overlapping DOF events is as follows:

I think this is consistent with the configuration reference description in that the second DOF event is simply ignored because there is no available physical output device at the time the event fires.

But I wonder if it would be better if it behaved this way:

Suppose the first DOF event is a bumper, which is typically a short burst, and the second DOF event is pressing one flipper button, which may be a longer event. It would probably provide a more realistic gaming experience if the second DOF event were still considered after the first DOF event goes off, so that the physical contactor goes off not before the flipper button is released. Flipper buttons are usually the only devices controlled directly by a button press, so direct feedback on them with an output device should always be preferred.
However, I'm unsure if there are other cases during gameplay where the current behavior is preferable. What do you think?

[mjrgh]

I can see your point. I think flippers might be such a special case that there's no way to get them right with sharing. Even with the current rules, you're going to get your second case (where the solenoid stays on continuously as long as the flipper button is being held down) if the flipper button press occurs slightly BEFORE the first bumper hit. And that seems like it's going to be really displeasing for its own reason: all of the bumper hits that happen while the flipper button is held are going to be completely silent. It seems like it's going to be weird to have all of the feedback effects suddenly stop as long as you're holding the flipper - if I were the player and I didn't know the details of the shared solenoids, I'd think "man, you've got an overloaded power supply, look how all of the effects stop when I hold the button down".

Maybe in a small cab that can only fit one or two solenoids/contactors, the better solution is to put the flippers on SSF effects. Or, alternatively, put everything else on SSF effects and just have the flippers on solenoids. I think the earliest pin cab I ever saw was one of those commercial 32"-screen cabs, and those had some kind of solenoids for just the flippers - everything else was just regular sound effects. And that seemed like a pretty cool thing at the time, I think because the flipper effects are so noticeable, being the thing you're directly in control of.

One possibility for a compromise does occur to me, though. With flippers and contactors, the effect is basically a CLUNK when you press the button, and a counter-CLUNK when you release it, and really nothing in between. Maybe we could let you configure a DOF port in "pulse" mode, so that rather than claiming a contactor for the whole duration of the "effect" (the period between ON and OFF transitions), the port only fires the device briefly AT THE TRANSITIONS. Press the flipper button -> DOF flipper port turns on -> port claims a device and pulses it for 10ms (or whatever; the time could be configurable). The DOF port REMEMBERS WHICH DEVICE it claimed, but releases its claim for now, allowing bumper hits (or anything else) to trigger the same device while the button is being held down. Release the flipper button -> DOF flipper port turns off -> port tries to claim the same device it did at the start of the event, and if it can, it pulses it again. If the device isn't available, you don't get your OFF clunk, but I think that's actually okay, because it means that some other event clunked at roughly the same time, so to the user it's going to sound like you got your clunk, even though it was for a bumper hit that happened at the same instant.

(The point of having the flipper port remember which device it pulsed at the ON transition is to make sure the ON and OFF clunks come from the same place. I think it might be noticeable on a typical short flipper press if the ON and OFF clunks came from different devices.)

This ON/OFF pulse business doesn't work well if you're going for the EM buzzy flipper coil effect, but it's probably difficult to get that with most flipper substitutes anyway. That's probably easier to get with SSF speakers.

[winxi01]

Maybe we could let you configure a DOF port in "pulse" mode, so that rather than claiming a contactor for the whole duration of the "effect" (the period between ON and OFF transitions), the port only fires the device briefly AT THE TRANSITIONS.

This would be especially useful for setups where only one or two contactors are available. The question is if the on-time at a transition can be timed such that the effect of a connected contactor or solenoid is comparable to a single clunk.

Another approach could be to just toggle the output for the physical device at the transitions of the DOF ports (either falling or rising):

However, this would inverse the on- and off-clunks at times and I'm not sure if this could be distracting.

[mjrgh]

Re the forcePort proposal: That seems simple enough and might be worthwhile. Bur I was thinking earlier about a somewhat similar notion, but a bit more complex, which I think amounts to "overlapping groups". Suppose you have three physical contactors for the bumpers, left/right/center, and you want to map these to the six DOF bumpers in such a way that the Left+Center form one group, and the Center+Right form a second group. Likewise, the DOF virtual ports form two groups: (Rear Left + Rear Center + Mid Left + Mid Center) and (Rear Center + Rear Right + Mid Center + Mid Right). This would keep the directionality roughly right while still maximizing sharing. The reason I bring this up is that it seems like your idea might be a special case of this "overlapping groups" notion, so maybe we should see if we can come up with a way to do that before adding a one-off for the more limited case. But I didn't get very far coming up with a concrete design for it, so I just kept things simple with the one-to-one groupings for the initial attempt.

Maybe we could let shareGroup (on the shareable ports) and group (on the DOF type:"shareGroup" devices) be arrays, so that each entity can be in multiple groups. When the DOF port needs to claim a physical port, it asks each group it belongs to for a port until it gets one. That might actually be pretty simple to implement now that I think about it. Let's see, would that handle your use case? I think so: the left flipper DOF port is in group: ["left flipper"], the right flipper DOF port is in group:["right flipper"], and the three DOF bumper ports are in group:"bumpers". The physical left contactor is in shareGroup:["left flipper", "bumpers"], and the right is in shareGroup:["right flipper", "bumpers"]. I think that might actually do the trick - what do you think?

[winxi01]

Maybe we could let shareGroup (on the shareable ports) and group (on the DOF type:"shareGroup" devices) be arrays, so that each entity can be in multiple groups. When the DOF port needs to claim a physical port, it asks each group it belongs to for a port until it gets one. That might actually be pretty simple to implement now that I think about it. Let's see, would that handle your use case? I think so: the left flipper DOF port is in group: ["left flipper"], the right flipper DOF port is in group:["right flipper"], and the three DOF bumper ports are in group:"bumpers". The physical left contactor is in shareGroup:["left flipper", "bumpers"], and the right is in shareGroup:["right flipper", "bumpers"]. I think that might actually do the trick - what do you think?

This sounds like a very good idea and it seems to cover the example use case from above. I think it's more general and straightforward than my proposal above. It would allow for even more complex setups and for carefully adjusting the tradeoff between directionality and the amount of sharing according to individual needs.

For example, I plan to use a total of four contactors in my "Pinball Controller," physically arranged as follows: top left, bottom left, top right, and bottom right. I can imagine the following group assignments:

• (left flipper) -> (bottom left contactor)
• (right flipper) -> (bottom right contactor)
• (left slingshot) -> (top left contactor)
• (right slingshot) -> (top right contactor)
• (left bumpers) -> (bottom left contactor, top left contactor)
• (mid bumpers) -> (all contactors)
• (right bumpers) -> (bottom right contactor, top right contactor)

Another approach that involves slightly more sharing but less directionality could be:

• (left flipper, left slingshot, left bumpers) -> (bottom left contactor, top left contactor)
• (right flipper, right slingshot, right bumpers) -> (bottom right contactor, top right contactor)
• (mid bumpers) -> (all contactors)

[mjrgh]

Thanks for the quick patch! I can confirm that all three issues have been fixed.

Great - I'll take a look at adding the "overlapping groups" scheme (and maybe the ON/OFF pulse idea) and post another test build.

[winxi01]

Great - I'll take a look at adding the "overlapping groups" scheme (and maybe the ON/OFF pulse idea) and post another test build.

I'm looking forward to it!

[winxi01]

One addition to my proposal from above (toggeling output devices). Perhaps it would be feasible to provide a global "toggle mode" option. In this mode, the output devices of shared groups would be toggled at the DOF port transitions rather than being synchronised with the corresponding DOF ports.
The concept of "claimed" devices would be obsolete in this mode. Instead, at the rising edge of a DOF port, Pinscape would look for the device in the corresponding group that had not been toggled for the longest amount of time. At the falling edge of an DOF port, Pinscape would always toggle the device that was toggled at the rising edge of the very same DOF event (for the reasons you stated above).
One thing to consider in this mode is that devices would be on for a potentially longer period of time (which would not be an issue for contactors, but possibly for solenoids). Another thing to note is that, when toggling, only DOF values of 0 or 255 should be considered, not values in between (which shouldn't be an issue for these types of output device).
This mode could drastically improve the availability of output devices, especially useful for a low number of devices, but the downside is that on-clonks and off-clonks are then arbitrary.

[mjrgh]

The new 0.1.16 release implements the scheme above that allows for multiple share groups per DOF port and per physical device port. It also implements a pulse mode option on the DOF ports.

(I don't think I see any upside in a "pulse mode only" variation, since I think you can achieve that if you really wanted to with the per-port pulse mode settings, but I also think you probably don't really want to do that with most ports, which by their nature won't tend to hog ports to begin with. Having another global variant would add a lot of complexity, which creates ongoing maintenance costs and places constraints on future features, so I'd rather keep it to one way of doing things.)

[winxi01]

Thanks for the update! I've tried multiple (two) groups per output port, but couldn't get it to work. With the following config

{ device: { type: "shareGroup", group: "left" } },
{ device: { type: "shareGroup", group: "left" } },
{ device: { type: "shareGroup", group: "right" } },
{ device: { type: "shareGroup", group: "right" } },
{ device: { type: "shareGroup", group: "all" } },
{ device: { type: "shareGroup", group: "all" } },
	
{ device: { type: "gpio", gp: 7 }, shareGroup: ["left", "all"] },
{ device: { type: "gpio", gp: 8 }, shareGroup: ["right", "all"] },

I get the warnings

2025/07/01 22:01:46 Warning: Share group "all" has no physical output ports assigned; check type:"shareGroup" devices in the outputs list for typos in their group: settings
2025/07/01 22:01:46 Warning: Share group "right" has no physical output ports assigned; check type:"shareGroup" devices in the outputs list for typos in their group: settings
2025/07/01 22:01:46 Warning: Share group "left" has no physical output ports assigned; check type:"shareGroup" devices in the outputs list for typos in their group: settings

and no output on either GPIO 7 or 8. Not sure if I'm doing something wrong here.

As a side note, I've also noted that the example config snippets under section Multiple groups in the JSON configuration reference are formatted as normal text which is somewhat hard to read.

[mjrgh]

I'm testing with almost that identical configuration, and it's working on my end. What does your firmware build number say (in the Overview window)? Mine is saying 0.1.16 build 202506302130.

The warnings about empty groups are almost certainly the problem, but I can't see why they're happening - the config lines look right. I'll try copying and pasting your config text literally in case it's some weird character set issue or something I can't see on-screen.

...Nope, copy and pasted your text, works fine here. Unclear what's wrong.

[winxi01]

Sorry, false alarm - I've tested with an older firmware. Updated to 0.1.16 and it works as expected - top!
It was a hard day, should go to bed now...

[mjrgh]

Great, glad that did the trick!