MPF config file reference: FAST Pinball drivers & coils¶
MPF 0.57 Configuration Reference for FAST Pinball Hardware
This page is parrt of the reference material for users of the Mission Pinball Framework and FAST Pinball hardware. If you're new to MPF and FAST, read the MPF + FAST overview first. If you are a programmer writing your own software, see our Developer's Reference Guide.
Note that this guide only applies to MPF 0.57. If you're using MPF 0.56 or older, then the FAST Pinball configuration section of the Mission Pinball website has everything you need.
The coils: section of your MPF config files contains settings and names for all coils in your machine.
When using FAST Pinball hardware, you'll need to know how to enter the number: setting for each coil. There are also optional FAST-specific advanced settings you can configure for each coil.
Here's an example of the coils: section of an MPF config file when FAST Pinball hardware is used:
coils:
trough_eject:
number: 3208-0 # (1)!
platform_settings:
recycle_ms: 10ms
pwm2_ms: 15ms
knocker:
number: cab-7 # (2)!
- I/O board called "3208", driver 0
- I/O board called "cab", driver 7
Some drivers are 'digital outputs', not 'coils'
MPF has the concept of "digital outputs" which is what you use when you use a driver to power some other lower-current device instead of a coil. (Digital outputs and coils are essentially the same under the hood, they just have a bit different interface and settings.) The FAST Pinball Cabinet I/O board uses these to control coin door LEDs and interface with bill validators or ticket dispensers. See the Mission Pinball documentation on digital outputs for details.
number:¶
With FAST Pinball hardware, the coil number is the name of the I/O board, then a dash, then the number of the driver control output from the I/O board.
The name of the I/O board is whatever you called that board in the net: io_loop: section of your config.
The driver number is printed on the I/O board driver header, starting with "D". In the MPF config, you just enter the number without the D. Note that these start with zero, so the I/O 1616 board uses driver numbers 0-15, the 3208 is 0-7, etc.
The FAST Modern Platform supports a maximum of 48 drivers
The FAST Modern Platform supports a maximum of 48 drivers across whatever combination of I/O boards you want.
Understanding how MPF coil settings map to physical FAST Pinball hardware¶
MPF contains lots of settings for coils. It's important to understand how the MPF settings relate to the physical hardware so you can configure your coils correctly, so we're going to walk through all the power-related settings and explain how they work with FAST Pinball hardware.
coils:
some_coil:
number: lower_playfield-1
default_pulse_ms: 10ms # 0-255ms
default_pulse_power: 1.0 # 0.0-1.0
default_hold_power: 0.5 # 0.0-1.0
platform_settings: # These are FAST-specific settings
recycle_ms: 10ms # 0-255ms
pwm2_ms: 15ms # 0-25500ms (Yes! Up to 25.5 seconds!)
default_timed_enable_ms: 2s # not used with FAST hardware, ignored
default_recycle: true # not used with FAST hardware, ignored
pulse_with_timed_enable: false # not used with FAST hardware, ignored
What's with all these "default" settings?¶
In MPF configs, you'll notice that most of these coil settings specify the "default" settings. You can think of these defaults as the regular settings that will apply to that coil every time it's activated. However, there are occasions in MPF when the defaults are not used. For example, ball devices have the ability to increase pulse times and power after ejects fail or during ball search.
Every coil in MPF allows you to optionally specify the max values that will never be exceeded under any condition. By default, the max power (for both pulse and hold) is 1.0 (100%), and the max times (for both pulse and hold) are "None" (which means no limits). You can add any or all of these settings to each coil config if you want to set some max values that will never be exceeded.
max_pulse_ms: None
max_pulse_power: 1.0
max_hold_duration: None
max_hold_power: 1.0
default_pulse_ms:¶
How long the initial pulse will be (1-255ms) whenever this coil is pulsed. The default is 10ms. You will most likely spend many hours fine tuning these values for your machine. :)
default_pulse_power:¶
The power (0.0-1.0) that this coil will be pulsed at for its initial pulse. This is a decimal percentage between 0 and 1. The default is 1, which is 100% power.
FAST hardware has a power resolution of ⅛, so your power options are:
| Value | Power |
|---|---|
| 0.0 | 0% |
| 0.125 | 12.5% |
| 0.25 | 25% |
| 0.375 | 37.5% |
| 0.5 | 50% |
| 0.625 | 62.5% |
| 0.75 | 75% |
| 0.875 | 87.5% |
| 1.0 | 100% |
If you enter a power value that's not one of these, MPF will round it to the nearest value.
default_hold_power:¶
The power (0.0-1.0) that this coil will be held at after its initial pulse. The value here works in the same way as the default_pulse_power: setting above: 0.0 - 1.0 with a resolution of ⅛.
Remember that in order for MPF to be able hold a coil at full 100% power, you also need to add allow_enable: true to the coil settings. (This is a safety setting so that a configuration typo doesn't burn up a coil that wasn't meant to be held on for a long time.)
coils:
left_flipper_hold:
number: lower_playfield-1
allow_enable: true
platform_settings:¶
All devices in MPF can have a platform_settings: subsection which contain additional configuration options for features specific to that hardware. In the case of FAST Pinball coils, there are two settings here:
recycle_ms:¶
Also called "cooldown time", this is the number of ms (0-255) that a coil must be off before it can be activated again. The default is 0, meaning the coil could be activated again immediately.
A good rule of thumb is that cooldown time can be about 2x the pulse time. It's ok to configure all your coils for a recycle time, even your flippers (which you only might want to do for a couple of ms). The key is to experiment and see what feels right.
This setting is often used in conjunction with a switch's debounce settings to fine-tune autofire devices (like slingshots) to prevent "machine gunning" where the switch bounces and the coil fires multiple times. See the Flippers & Autofires for details.
pwm2_ms:¶
This setting controls how long the secondary pulse (or hold) of a coil is. The exact way it's used depends on other coil settings and what type of device it's configured in.
FAST Pinball drivers can be pulsed for up to 25.5 seconds, which means this pwm2_ms: setting has a valid range from 0 to 25500. These longer times are nice for things like diverters, where you might want it to activate for several seconds to ensure the ball got diverted.
Mapping MPF settings to FAST Serial Protocol settings¶
Even though this is a guide for MPF uses and you most likely don't care about the FAST Serial Protocol, it's helpful to understand how the MPF settings map to the FAST Serial Protocol settings. Here's an annotated config file which shows the FAST Serial Protocol DL: commands that are sent to the FAST hardware for each coil setting in MPF.
#config_version=6
coils:
c_baseline: # DL:00,81,00,10,0A,FF,00,00,00
number: io3208-0 # 00
c_allow_enable: # DL:01,81,00,10,0A,FF,00,FF,00
number: io3208-1 # 01
allow_enable: true
c_custom_pulse: # DL:02,81,00,10,17,AA,00,00,00
number: io3208-2 # 02
default_pulse_ms: 23 # 17
default_pulse_power: 0.53 # AA
c_custom_recycle: # DL:05,81,00,10,0A,FF,00,00,1B
number: io3208-5 # 05
platform_settings:
recycle_ms: 27 # 1B
c_long_pwm2: # DL:06,81,00,70,0A,FF,14,EE,00
number: io3208-6 # 06
default_hold_power: 0.75 # EE
platform_settings:
pwm2_ms: 2000 # 14 (2000ms / 100)
c_default_hold_power: # DL:07,81,00,10,0A,FF,00,88,00
number: io3208-7 # 07
default_hold_power: 0.25 # 88
c_longer_pwm2: # DL:08,81,00,70,0A,FF,C8,EE,00
number: io0804-0 # 08
default_hold_power: 0.75 # EE
platform_settings:
pwm2_ms: 20000 # C8 (20000ms / 100)
c_2_stage_pulse: # DL:0A,81,00,10,18,FE,14,AA,00
number: io0804-2 # 0A
default_pulse_ms: 24 # 18
default_pulse_power: 0.875 # FE
default_hold_power: 0.5 # AA
platform_settings:
pwm2_ms: 20 # 14
c_pwm2: # DL:0B,81,00,10,14,AA,14,AA,00
number: io0804-3 # 0B
default_pulse_ms: 20 # 14
default_pulse_power: 0.53 # AA
default_hold_power: 0.51 # AA
platform_settings:
pwm2_ms: 20 # 14
c_flipper_main: # DL:0D,81,00,10,0A,FF,00,00,00
number: io1616-1 # 0D
default_pulse_ms: 10 # 0A
c_flipper_hold: # DL:0E,81,00,10,0A,FF,00,00,00
number: io1616-2 # 0E
allow_enable: true
c_flipper_single_wound: # DL:0F,81,00,10,0E,FF,00,01,00
number: io1616-3 # 0F
default_pulse_ms: 14 # 0A
default_hold_power: 0.125 # 20
Unused settings¶
FAST Pinball drivers have some unique capabilities that make some of the MPF coil settings unnecessary. Here are the settings that are not used with FAST Pinball hardware:
default_timed_enable_ms: (Not Used)¶
This setting is not used with FAST Pinball hardware and any value entered for a FAST coil will be ignored. Instead, use the pwm2_ms: setting. (Why did we do this and not just map default_timed_enable_ms: to pwm2_ms:? Because the pwm2_ms: settings controls things differently depending on how the coil is used, e.g. sometimes it's a hold time, sometimes it's a secondary pulse, etc., and we didn't want to make it confusing by having the same setting mean something different from what its name implies.)
default_recycle: (Not Used)¶
The default_recycle: setting in MPF is a boolean (True/False), but with FAST drivers you can set the recycle time in a more granular way with the recycle_ms: setting. So the default_recycle: setting is not used and any value there is ignored.
pulse_with_timed_enable: (Not Used)¶
FAST hardware does not need this setting and anything entered here will be ignored. Why? Because FAST hardware can long hold a coil up to 25500ms (25.5 seconds) without any special settings. Just set the pwm2_ms: up to a value of 25500 and the platform will take care of the rest.
Documentation Feedback? Requests? Confused?
Hi! I'm Brian, and I'm responsible for the documentation at FAST Pinball. If you have any feedback, requests, corrections, ideas, or any other thoughts about the docs, please let me know!
You can email me at brian@fastpinball.com. I maintain this site in my spare time, so there might be a week or so delay if you email me.
If you have a more pressing need, reach out to us via Slack, or email Aaron Davis.
Thanks!
N or > jump the next page, P or < for previous, search with S or ?