How to configure LEDs (FAST Pinball)
Related Config File Sections:
The FAST Nano Controller has a built-in 4-channel RGB LED controller which can drive up to 64 RGB LEDs per channel. This controller uses serially-controlled LEDs (where each LED element has a little serial protocol decoder chip in it), allowing you to drive dozens of LEDs from a single data wire. These LEDs are generally known as "WS2812" (or similar). You can buy them from many different companies, and they're what's sold as the "NeoPixel" brand of products from Adafruit. (They have all different shapes and sizes.)
Most of the settings in the Lights documentation apply to LEDs connected to FAST Pinball controllers, however there are a few FAST-specific things to know.
Overview video about serial LEDs:
Channel and Number Syntax
In MPF lights abstract
a light source which emits arbitrary colors. However, this is not true
for all real lights. Some support only white (GIs), others only a
single-color (i.e. red inserts) and others support full RGB. For that
reason MPF knows
light numbers and channel numbers. Internally, a light consists of one or multiple channels.
For instance, a single-color GI will contain a single white channel.
While a RGB light will control a red, green and a blue channel. A white
light behind a red insert should be a single red channel (because it
cannot emit other colors through the red insert). You can configure
those channels using the
channels setting or use
type to define the channels. See
/mechs/lights/index for details.
However, in most cases a platform supports one type of lights (per
subtype) this would be overly verbose and we added the
setting for configuring lights in the common platform way. For instance
a platform for GIs will configure single channel white lights or a
serial LED controller will configure RGB lights with three channels.
FAST assumes RGB lights by default. For everything else (i.e. RGBW) you have to use channels.
The FAST Nano supports 256 LEDs across four chains (listed as "CH 1" - "CH 4" on the Nano). LEDs 0-63 are on chain 1, 64-127 on chain 2, 128-191 on chain 3 and 192-255 on chain 4 (please note that FAST diagrams label these 4 headers as "channels" but we are using the term "chains" to avoid confusion with the non-RGB "Channels" section below).
FAST numbers use the format:
This is as easy as it gets. Just provide the number of you LED in the chain. Internally, FAST assumes three channels per LED (RGB/GRB WS2811/WS2812 LEDs).
FAST channels use the format:
number is the same as above and
index is a an index from 0 to 2.
This is because serial LEDs are traditionally RGB (or GRB) LEDs with
exactly three channels. However, this is not true for RGBW or similar
LEDs which do not work with this style of numbering. Luckily, you can
chain them instead and have MPF calculate the internal channels for you:
lights: led_0: start_channel: 0 # you could also use number: 0 subtype: led type: rgb # will use red: 0-0, green: 0-1, blue: 0-2 led_1: previous: led_0 subtype: led type: rgbw # will use red: 1-0, green: 1-2, blue: 1-3, white: 2-0 led_2: previous: led_1 subtype: led type: rgbw # will use red: 2-1, green: 2-2, blue: 3-0, white: 3-1
Remember that each chain from the Nano will handle up to 64 RGB LEDs. You likely will have more than just 64 LEDs in your machine resulting in multiple chains. When configuring the
number for subsequent chains, remember to identify the number of the first LED in that chain starting with the first number LED supported in that chain. For example, your first chain should start with LED_0 and your second chain with LED_64, the third with LED_128 and the fourth with LED_192, like this:
lights: led_0: start_channel: 0 # you could also use number: 0 subtype: led type: rgb # will use red: 0-0, green: 0-1, blue: 0-2 led_1: previous: led_0 subtype: led type: rgb # will use red: 1-0, green: 1-2, blue: 1-3 led_2: previous: led_1 subtype: led type: rgb # will use red: 2-0, green: 2-1, blue: 2-2 ## beginning of second chain led_50: start_channel: 64 # even though you only used 3 LEDs on the first chain, this chain needs to start with '64' to signify this is the beginning of a new chain from the Nano board subtype: led type: rgb # will use red: 64-0, green: 64-1, blue: 64-2 led_51: previous: led_50 subtype: led type: rgb # will use red: 65-0, green: 65-1, blue: 65-2 led_52: previous: led_51 subtype: led type: rgb # will use red: 66-0, green: 66-1, blue: 66-2
See WS2811 and WS2812 LEDs in Pinball for details.
RGB LED buffering
Most computers have the ability to send LED updates to the FAST Pinball controller faster than the controller can process them. If this happens, then the LED command messages can get backlogged and it will appear that you have a "delay" in your LEDs and/or you might get weird colors due to corrupt messages.
To help combat this, there are two settings you can adjust:
mpf: default_light_hw_update_hz: 50 fast: rgb_buffer: 3
If you notice that your LEDs seem to be getting behind, you can adjust
default_led_hw_update_hz: setting to be lower. (Frankly the 50hz
by default is too high and we should lower it to 30.) You can probably
drive 128 or so LEDs at 50Hz, but if you have more than that then you
might need to start playing with this number.
Hardware LED fading
You can globally set the fade rate for LEDs connected to a FAST Pinball
controller via the
fast:hardware_led_fade_time: setting. (This is
0ms by default, meaning it's disabled.)
See the fast: section of the config file reference for details.
If you are using RGB LEDs, they might not be perfectly white when you turn them on. They might be pinkish or blueish instead depending on the brand of the LED. To a certain extend this is normal/expected and you can compensate for it by configuring color_correction profiles in light_settings.
What if it did not work?
Have a look at our FAST troubleshooting guide.
Something missing or wrong? You can fix it!
This website is edited by people like you! Is something wrong or missing? Is something out of date, or can you explain it better?
Please help us! You can fix it yourself and be an official "open source" contributor!
It's easy! See our Beginner's guide to editing the docs.
Page navigation via the keyboard: < >
You can navigate this site via the keyboard. There are two modes:
General navigation, when search is not focused:
- F , S , / : open search dialog
- P , , : go to previous page
- N , . : go to next page
While using the search function:
- Down , Up : select next / previous result
- Esc , Tab : close search
- Enter : go to highlighted page in the results