diff --git a/docs/config/fast.md b/docs/config/fast.md index afd348b4d2..d5e747be92 100644 --- a/docs/config/fast.md +++ b/docs/config/fast.md @@ -11,81 +11,52 @@ title: "fast: Config Reference" |[machine](instructions/machine_config.md) config files|**YES** :white_check_mark:| |[mode](instructions/mode_config.md) config files|**NO** :no_entry_sign:| -The `fast:` section of your machine-wide config is where you configure -hardware options that are specific to the FAST Pinball Controller. Note -that we have a how to guide which includes -[all the FAST-specific settings](../hardware/fast/index.md) throughout your entire config file, so be sure to read that -if you have FAST hardware. -``` yaml -fast: - ports: com3, com4, com5 -``` +# 2026 Documentation Update -## Required settings +The following config documentation is relevant for MPF 0.57.4 and 0.80.0. Last updated Dec 18, 2025. -The following sections are required in the `fast:` section of your -config: +The `fast:` section of your machine-wide config is where you configure hardware options that are specific to the FAST Pinball Controller. +The [FAST website](https://fastpinball.com/mpf/config/) also has thorough documentation and examples for MPF 0.57 and 0.80 compatible configurations. -### default_normal_debounce_close: +## fast: config reference -Single value, type: `time string (ms)` -[Instructions for entering time strings](instructions/time_strings.md). Defaults to empty. +The top-level `fast:` key contains subsections for each of the various component networks available with FAST. +You do not need to include any section that is not present in your machine. -Specifies the default value for the debounce time for switches that are -configured with `debounce: normal` when they close. +### net: -Even though this is listed as a required setting, this entry is in the -`mpfconfig.yaml` file, (with a value of `10ms`), so you don\'t have to -enter it here unless you want to override that. +This contains the configuration for the NET IO boards, which handle switches and drivers. +See [fast:net: config reference](fast/fast_net.md) for details. -Also, keep in mind that this setting is only a default. You can override -it for any switch in that switch\'s config. +### exp: -### default_normal_debounce_open: +This contains the configuration for the EXP boards, which handle lights and various motors and accessories. -Single value, type: `time string (ms)` -[Instructions for entering time strings](instructions/time_strings.md). Defaults to empty. +### exp_int: -Specifies the default value for the debounce time for switches that are -configured with `debounce: normal` when they open. +When using the Raspberry PI directly connected to a Neuron board, the Neuron's LED ports are not accesible on the normal `exp` bus. +To enable use of these headers, define the `FP-EXP-2000` model board in the `exp_int` instead of `exp` configuration. +If using other EXP boards, you still define those on the normal `exp` configuration. +For an example, see this [pull request](https://github.com/missionpinball/mpf/pull/1895) on Github. -Even though this is listed as a required setting, this entry is in the -`mpfconfig.yaml` file, (with a value of `10ms`), so you don\'t have to -enter it here unless you want to override that. +### aud: -Also, keep in mind that this setting is only a default. You can override -it for any switch in that switch\'s config. +This contains the configuration for sounds played through the FAST Audio board. -### default_quick_debounce_close: -Single value, type: `time string (ms)` -[Instructions for entering time strings](instructions/time_strings.md). Defaults to empty. +# Pre-2024 Documentation -Specifies the default value for the debounce time for switches that are -configured with `debounce: quick` when they close. +The following documentation was current in mid 2023, some settings and structures may have changed since then: -Even though this is listed as a required setting, this entry is in the -`mpfconfig.yaml` file, (with a value of `2ms`), so you don\'t have to -enter it here unless you want to override that. +## fast: config settings -Also, keep in mind that this setting is only a default. You can override -it for any switch in that switch\'s config. - -### default_quick_debounce_open: - -Single value, type: `time string (ms)` -[Instructions for entering time strings](instructions/time_strings.md). Defaults to empty. - -Specifies the default value for the debounce time for switches that are -configured with `debounce: quick` when they open. - -Even though this is listed as a required setting, this entry is in the -`mpfconfig.yaml` file, (with a value of `2ms`), so you don\'t have to -enter it here unless you want to override that. +The `fast:` section of your machine-wide config is where you configure +hardware options that are specific to the FAST Pinball Controller. Note +that we have a how to guide which includes +[all the FAST-specific settings](../hardware/fast/index.md) throughout your entire config file, so be sure to read that +if you have FAST hardware. -Also, keep in mind that this setting is only a default. You can override -it for any switch in that switch\'s config. ### ports: @@ -95,6 +66,11 @@ empty. A comma-separated list of the serial port names your FAST controller uses. +``` yaml +fast: + ports: com3, com4, com5 +``` + ## Optional settings The following sections are optional in the `fast:` section of your @@ -181,29 +157,6 @@ Single value, type: `integer`. Default: `3` Max backlog for the RGB port to prevent overflows in the FAST CPU. -### watchdog: - -Single value, type: `time string (ms)` -[Instructions for entering time strings](instructions/time_strings.md). Default: `1000` - -The FAST controllers include a "watchdog" timer. A watchdog is a timer -that is continuously counting down towards zero, and if it ever hits -zero, the controller shuts off all the power to the drivers. The idea is -that every time MPF runs a game loop (so, 30 times a second or -whatever), MPF tells the FAST controller to reset the watchdog timer. So -this timer is constantly getting reset and never hits zero. - -But if MPF crashes or loses communication with the FAST controller, then -this watchdog timer won\'t be reset. When it hits zero, the FAST -controller will kill the power to the drivers. This should prevent an -MPF crash from burning up driver or somehow damaging your hardware in -another way. - -You can set the watchdog timer to whatever you want. (This is -essentially the max time a driver could be stuck "on" if MPF crashes.) -The default is 1 second which is probably fine for almost everyone, and -you don\'t have to include this section in your config if you want to -use the default. ## Related How To guides diff --git a/docs/config/fast/fast_aud.md b/docs/config/fast/fast_aud.md new file mode 100644 index 0000000000..d0fea19f88 --- /dev/null +++ b/docs/config/fast/fast_aud.md @@ -0,0 +1,67 @@ +--- +title: "fast:aud: Config Reference" +--- + +# fast:aud: Config Reference + +--8<-- "deeper_config_section.md" + +| Valid in | | +|-----|:----:| +|[machine](../instructions/machine_config.md) config files|**YES** :white_check_mark:| +|[mode](../instructions/mode_config.md) config files|**NO** :no_entry_sign:| + +## aud: config reference + +Within the `fast:` section of your machine-wide config, you configure the audio board processor in the subsection `aud:`. + +### Sample config: + +```yaml +fast: + aud: + port: auto + main_amp_enabled: true + sub_amp_enabled: true + headphones_amp_enabled: true + + main_steps: 20 + sub_steps: 20 + headphones_steps: 20 + + default_main_volume: 32 + default_sub_volume: 32 + default_headphones_volume: 16 + + persist_volume_settings: true + + max_hw_volume_main: 63 + max_hw_volume_sub: 63 + max_hw_volume_headphones: 63 + + main_levels_list: None + sub_levels_list: None + headphones_levels_list: None + + link_sub_to_main: true + link_headphones_to_main: false + + headphones_level: headphones + mute_speakers_with_headphones: true +``` + +### port: + +List of one (or more) values, each is a type: `string`. Defaults to `auto`. + +A comma-separated list of the serial port names your FAST controller uses. + +### baud: + +Single value, int, default: `230400` + +The connection baud rate. + +### FAST Docs: + +For the other properties, see the [FAST Audio Interface MPF Config page](https://fastpinball.com/mpf/config/audio/). diff --git a/docs/config/fast/fast_exp.md b/docs/config/fast/fast_exp.md new file mode 100644 index 0000000000..3d5e6e056c --- /dev/null +++ b/docs/config/fast/fast_exp.md @@ -0,0 +1,75 @@ +--- +title: "fast:exp: Config Reference" +--- + +# fast:exp: Config Reference + +--8<-- "deeper_config_section.md" + +| Valid in | | +|-----|:----:| +|[machine](../instructions/machine_config.md) config files|**YES** :white_check_mark:| +|[mode](../instructions/mode_config.md) config files|**NO** :no_entry_sign:| + +## exp: config reference + +Within the `fast:` section of your machine-wide config, you configure the EXP processor in the subsection `exp:`, and sometimes in `exp_int`. + +### port: + +List of one (or more) values, each is a type: `string`. Defaults to `auto`. + +A comma-separated list of the serial port names your FAST controller uses. + +### baud: + +Single value, int, default: `921600` + +The connection baud rate. + +### boards: + +Dict of string board names to dicts of EXP board properties. Defaults to empty. + +Example: + +```yaml +fast: + exp: + port: auto + boards: + neuron: + model: FP-EXP-2000 + playfield_0081: + model: FP-EXP-0081 +``` + +#### model: + +The product number of the IO board. E.G. `FP-EXP-0081` + +#### ignore_led_errors: + +Single value, boolean, default: `false` + +If false, LED hex communication decode errors will be raised as errors when encountered from this board. +If you encounter instability due to these errors, set this to true to silently ignore them. + +## Using exp_int + +If using a Raspberry Pi connected directly to the Neuron controller, the LED headers on the Neuron will not be available on the normal EXP interface. +In order to access these Neuron LED headers, you must define a parallel structure to the existing `exp:` configuration, and move the Neuron definition over to it. + +Example: + +```yaml +fast: + exp: + boards: + playfield_0081: + model: FP-EXP-0081 + exp_int: + boards: + neuron: + model: FP-EXP-2000 +``` diff --git a/docs/config/fast/fast_net.md b/docs/config/fast/fast_net.md new file mode 100644 index 0000000000..6cad00a4b1 --- /dev/null +++ b/docs/config/fast/fast_net.md @@ -0,0 +1,171 @@ +--- +title: "fast:net: Config Reference" +--- + +# fast:net: Config Reference + +--8<-- "deeper_config_section.md" + +| Valid in | | +|-----|:----:| +|[machine](../instructions/machine_config.md) config files|**YES** :white_check_mark:| +|[mode](../instructions/mode_config.md) config files|**NO** :no_entry_sign:| + +## net: config reference + +Within the `fast:` section of your machine-wide config, you configure the IO network in the subsection `net:`. + +### port: + +List of one (or more) values, each is a type: `string`. Defaults to `auto`. + +A comma-separated list of the serial port names your FAST controller uses. + +### io_loop: + +Dict of string board names to dicts of IO board properties. Defaults to empty. + +Each item defines its own name and has two sub-properties, `model` and `order`. +There is a hard limit of 9 boards in the IO loop. +Note that the Playfield Interchange board is pass-through, and is not listed in the IO loop. + +Example: + +```yaml +fast: + net: + controller: neuron + io_loop: + my_io_board: + model: FP-I/O-0804 + order: 1 + my_second_favorite_board: + model: FP-I/O-0024 + order: 2 +``` + +#### model: + +The product number of the IO board. E.G. `FP-I/O-0804` + +#### order: + +The board number in the IO loop, starting from 1. + +### baud: + +Single value, int, default: `921600` + +The connection baud rate. + +### controller: + +Single value, string, one of: `neuron`, `nano`, `sys11`, `wpc89`, `wpc95` + +The FAST Pinball controller type. + +### watchdog: + +Single value, type: `time string (ms)` +[Instructions for entering time strings](../instructions/time_strings.md). Default: `1000` + +The FAST controllers include a "watchdog" timer. A watchdog is a timer +that is continuously counting down towards zero, and if it ever hits +zero, the controller shuts off all the power to the drivers. The idea is +that every time MPF runs a game loop (so, 30 times a second or +whatever), MPF tells the FAST controller to reset the watchdog timer. So +this timer is constantly getting reset and never hits zero. + +But if MPF crashes or loses communication with the FAST controller, then +this watchdog timer won\'t be reset. When it hits zero, the FAST +controller will kill the power to the drivers. This should prevent an +MPF crash from burning up driver or somehow damaging your hardware in +another way. + +You can set the watchdog timer to whatever you want. (This is +essentially the max time a driver could be stuck "on" if MPF crashes.) +The default is 1 second which is probably fine for almost everyone, and +you don\'t have to include this section in your config if you want to +use the default. + +### default_quick_debounce_open: + +Single value, type: `time string (ms)` +[Instructions for entering time strings](instructions/time_strings.md). Defaults to empty. + +Specifies the default value for the debounce time for switches that are +configured with `debounce: quick` when they open. + +Even though this is listed as a required setting, this entry is in the +`mpfconfig.yaml` file, (with a value of `2ms`), so you don\'t have to +enter it here unless you want to override that. + +Also, keep in mind that this setting is only a default. You can override +it for any switch in that switch\'s config. + +### default_quick_debounce_close: + +Single value, type: `time string (ms)` +[Instructions for entering time strings](instructions/time_strings.md). Defaults to empty. + +Specifies the default value for the debounce time for switches that are +configured with `debounce: quick` when they close. + +Even though this is listed as a required setting, this entry is in the +`mpfconfig.yaml` file, (with a value of `2ms`), so you don\'t have to +enter it here unless you want to override that. + +Also, keep in mind that this setting is only a default. You can override +it for any switch in that switch\'s config. + +### default_normal_debounce_open: + +Single value, type: `time string (ms)` +[Instructions for entering time strings](instructions/time_strings.md). Defaults to empty. + +Specifies the default value for the debounce time for switches that are +configured with `debounce: normal` when they open. + +Even though this is listed as a required setting, this entry is in the +`mpfconfig.yaml` file, (with a value of `10ms`), so you don\'t have to +enter it here unless you want to override that. + +Also, keep in mind that this setting is only a default. You can override +it for any switch in that switch\'s config. + +### default_normal_debounce_close: + +Single value, type: `time string (ms)` +[Instructions for entering time strings](instructions/time_strings.md). Defaults to empty. + +Specifies the default value for the debounce time for switches that are +configured with `debounce: normal` when they close. + +Even though this is listed as a required setting, this entry is in the +`mpfconfig.yaml` file, (with a value of `10ms`), so you don\'t have to +enter it here unless you want to override that. + +Also, keep in mind that this setting is only a default. You can override +it for any switch in that switch\'s config. + +### mute_unconfigured_switches: + +* available MPF 0.57.4/0.80.0.dev12 * #TODO + +Single value, boolean, default: `false` + +Before this change, FAST Switches were configured with mode `00`, meaning they did not report if unconfigured. +With the release of this config setting, switch inputs on the IO board will default to mode `01`, meaning they do report to MPF even if no switch device is configured. +In production mode, or if this setting is set to `true`, unregistered switches will NOT report to MPF on state change. + +### gi_hz: + +Single value, int, default: `30` + +Lights using the light subtype `gi` will use this for their hz setting if unspecified. + +### lamp_hz: + +Single value, int, default: `30` + +Lights using the light subtype `matrix` will use this for their hz setting if unspecified. diff --git a/docs/hardware/fast/config.md b/docs/hardware/fast/config.md index 2cdec581bf..d8bc164c7e 100644 --- a/docs/hardware/fast/config.md +++ b/docs/hardware/fast/config.md @@ -79,7 +79,7 @@ On Mac or Linux, it's easiest to find the port numbers via the terminal window (or console window). To do that, open a new window and run the following command: - ls /dev/tty* +`ls /dev/tty*` This will list all the devices whose names begin with "tty". @@ -90,17 +90,21 @@ first port, the "B" is the second, etc. For example, the four FAST ports might be something like on MAC: - /dev/tty.usbserial-141A - /dev/tty.usbserial-141B - /dev/tty.usbserial-141C - /dev/tty.usbserial-141D +```shell +/dev/tty.usbserial-141A +/dev/tty.usbserial-141B +/dev/tty.usbserial-141C +/dev/tty.usbserial-141D +``` On linux it would look like this: - /dev/ttyUSB0 - /dev/ttyUSB1 - /dev/ttyUSB2 - /dev/ttyUSB3 +```shell +/dev/ttyUSB0 +/dev/ttyUSB1 +/dev/ttyUSB2 +/dev/ttyUSB3 +``` If you have multiple FAST devices they will enumerate more or less randomly dependent on the order they are plugged in. Unfortunately, the @@ -108,14 +112,14 @@ USB devices do not contain any serial number. However, we can pin them based on the USB port they are plugged into. On linux this can be achieved using a UDEV rules such as this: - SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6011", ENV{ID_PATH_TAG}=="pci-0000_00_14_0-usb-0_12_1_0", SYMLINK+="ttyDMD1" +`SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6011", ENV{ID_PATH_TAG}=="pci-0000_00_14_0-usb-0_12_1_0", SYMLINK+="ttyDMD1"` The device will then be available as /dev/ttyDMD1. You can run the following command while plugging in the device to get the relevand ID_PATH_TAG (and also idVendor and idProduct in case they changed with other revisions): - udevadm monitor --property +`udevadm monitor --property` ## 3. Add the ports to your config file @@ -130,13 +134,17 @@ used on a Nano). So an example for Windows might look like this: - fast: - ports: com3, com4, com5 +```yaml +fast: + ports: com3, com4, com5 +``` And an example for Mac or Linux might look like this: - fast: - ports: /dev/tty.usbserial-141B, /dev/tty.usbserial-141C +```yaml +fast: + ports: /dev/tty.usbserial-141B, /dev/tty.usbserial-141C +``` Note that if you have a FAST Core controller but you're not actually using the hardware DMD, then you don't have to enter the first port in @@ -160,12 +168,13 @@ default with a timeout of 1 second. If you would like to disable this, or you'd like to change the timeout, you can do so in the `fast:` section of your machine-wide config. - fast: - ports: com3, com4, com5 # or whatever your ports are - watchdog: 1000 +```yaml +fast: + ports: com3, com4, com5 # or whatever your ports are + watchdog: 1000 +``` -The `watchdog:` setting is the timeout in milliseconds. Use 0 to disable -it. +The `watchdog:` setting is the timeout in milliseconds. Use 0 to disable it. Note that at this time, FAST Pinball controllers only use the watch dog for the NET processor (which controls stuff on the IO boards, like @@ -173,5 +182,4 @@ coils). The watch dog is not used for the DMD or LEDs. ## What if it did not work? -Have a look at our -[FAST troubleshooting guide](../../troubleshooting/index.md). +Have a look at our [FAST troubleshooting guide](../../troubleshooting/index.md). diff --git a/docs/hardware/fast/index.md b/docs/hardware/fast/index.md index 73d48fc96c..71841da28a 100644 --- a/docs/hardware/fast/index.md +++ b/docs/hardware/fast/index.md @@ -6,6 +6,10 @@ title: How to configure MPF for FAST Pinball hardware --8<-- "hardware_platform.md" +# Pre-2024 Documentation + +The documentation in this section was current in mid 2023, some settings and structures may have changed since then: + ## FAST Neuron Controller with MPF 0.57.0 and newer FAST Pinball maintains [their own documentation on fastpinball.com](https://fastpinball.com/mpf) diff --git a/docs/hardware/fast/servos.md b/docs/hardware/fast/servos.md index d88f0072b0..f7b43f0d13 100644 --- a/docs/hardware/fast/servos.md +++ b/docs/hardware/fast/servos.md @@ -51,6 +51,7 @@ then figure out the number based on the list above. By default, standalone numbers like this have to be entered in hex format, so once you find your number, enter it as the hex equivalent: +``` Regular Hex --------- ----- 0 0 @@ -77,6 +78,7 @@ format, so once you find your number, enter it as the hex equivalent: 21 15 22 16 23 17 +``` If you don't want to mess with all this hex stuff, you can set the config number format to "int" via the `fast: config_number_format:` diff --git a/includes/config_section.md b/includes/config_section.md index c64e8e65ab..4e7bcdda45 100644 --- a/includes/config_section.md +++ b/includes/config_section.md @@ -2,4 +2,4 @@ This page is reference material which explains every setting and option for this section of an MPF yaml config file. See the [instructions for config files](instructions/index.md) for formatting and other details. See our guide - to [config file examples](../examples/index.md) for more examples of real configs in action. \ No newline at end of file + to [config file examples](../examples/index.md) for more examples of real configs in action. diff --git a/includes/deeper_config_section.md b/includes/deeper_config_section.md new file mode 100644 index 0000000000..9a5d9e8369 --- /dev/null +++ b/includes/deeper_config_section.md @@ -0,0 +1,5 @@ +??? note "This is a config file reference. Click for instructions." + + This page is reference material which explains every setting and option for this section of an MPF yaml config file. + See the [instructions for config files](../instructions/index.md) for formatting and other details. See our guide + to [config file examples](../../examples/index.md) for more examples of real configs in action. diff --git a/mkdocs.yml b/mkdocs.yml index 8da1e62064..7674a0e1c4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -850,6 +850,9 @@ nav: - Platform-Specific Config Reference: - "fadecandy:": config/fadecandy.md - "fast:": config/fast.md + - "fast:exp:": config/fast/fast_exp.md + - "fast:net:": config/fast/fast_net.md + - "fast:aud:": config/fast/fast_aud.md - "fast_coils:": config/fast_coils.md - "fast_switches:": config/fast_switches.md - "hardware_benchmark:": config/hardware_benchmark.md