This is the documentation the latest work-in-progress version of MPF!
This is the documentation for MPF 0.56, which is the “dev” (next) release of MPF that is a work-in-progress. This is probably ok, and means you’ll be on the latest, cutting-edge version of MPF.
However, if you want a more stable version, select the
v:stableversion from the lower-left corner of this page, which is the most recent version that is not getting new updates.
If you are new to MPF, we have recently rewritten the installation process which only applies to this “latest” 0.56, so you probably want to stay here because the prior installation process doesn’t work on the latest OS and Python versions.
How MPF handles “quick response” mechs (flippers, slingshots, etc.)¶
As you can imagine, many types of mechanisms in a pinball machine require near “instant” response to switches. For example, you do not want any “lag” between the time you press the flipper button and the time the flipper physically moves.
To address this, MPF and the control systems handle “quick response” devices in a special way. This includes things like:
- pop bumpers
- kicking targets
- kickback lanes
- and maybe others?
What’s the problem?¶
To understand why MPF and the hardware control systems work this way, first think about how MPF works in general.
When you configure (and enable) a flipper in MPF, what you’re really doing is saying, “when this switch becomes active, fire this coil” (and do that as fast as possible).
The challenge is that MPF is software running on a computer connected to a pinball control system via USB. So if you think about the entire process that needs to happen to flip a flipper, you have:
- The hardware control system is continuously scanning switches to see if they change state.
- The player pushes the flipper button.
- The hardware control system notices the change.
- The hardware control system adds the message with the switch state change to the queue to be sent to the computer via USB.
- The computer processes the USB message.
- MPF gets notification of the switch change.
- MPF looks at its configuration and notices that a coil should be fired.
- MPF creates the instruction to fire the coil.
- That instruction is put in the queue to be sent to the hardware controller via USB.
- The USB bus transfers that command to the hardware controller.
- The hardware controller receives that command and fires the coil attached to the flipper.
Of course computers are really fast, and this can all happen in 10 or 20ms. But again, with the desire for “instant” response of these devices, that isn’t fast enough.
The solution? “Hardware rules”¶
So the way this is handled is that all the pinball control systems have the ability to have simple “rules” written to them which lets them do simple things on their own.
These rules are very simple and only involve switches and coils. For example, a rule might be “when this switch is activated, pulse that coil”, or “when this switch is released, cut off the power to that coil”.
Then when one of these “hardware rules” (as we call them in MPF) is written to the hardware pinball controller, that controller can handle it all by itself with minimal delay (usually in a millisecond or two) without having to deal with USB and MPF and all that.
These rules are not permanently stored on the hardware controller, and in fact they’re constantly added, removed, and updated throughout the course of a game. (Rules for flipper buttons and coils are removed when a ball ends and added when a ball starts, etc.)
By the way, even when MPF writes hardware rules to the pinball controller, the switch notification is still sent to MPF (since you might want to have scoring or play a sound or something when that switch is hit). It’s just that in that case, the switch notification is sent to MPF for MPF’s game logic purposes, but the actual coil firing would have already happened thanks to the hardware rule on the pinball controller.
This is all automatic¶
The good news about these hardware rules is that there’s nothing you need to do to use them. This is just one of the things that MPF does behind the scenes, thanks to the smart people who designed the pinball controllers.
What kind of rules does MPF use?¶
- Pulse + Cancel: This means that we pulse a coil when a switch becomes active and cancel the pulse when the switch becomes inactive.
- Pulse + Cancel + Hold: This means that we pulse and then enable a coil with pwm when a switch becomes active and cancel the pulse when the switch becomes inactive.
- Just Pulse: This means that we pulse a coil when a switch becomes active but never cancel the pulse.
- Pulse + Cancel + Hold + EOS: This means that we pulse and then enable a coil with pwm when a switch becomes active and cancel the pulse when the switch becomes inactive. Additionally, the pulse is changed to pwm when EOS becomes inactive (it’s usually normally closed).
For most platforms 1 and 2 is basically the same rule (e.g. rule 1 is rule 2 with
hold power = 0).
We use type 2 for single wound flippers. For dual wound we use type 1 on the main/high power coils and type 2 on the hold coil (often with 100% pwm = full enable). When flippers have EOS we use type 4 rules (for dual wound flippers with hold=0). Rule 3 is used for pop bumpers.
Not all platforms support all types of rules. In those cases we use the next best available rule (e.g. 1 instead of 3 or the other way around).