lights:
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 for formatting and other details. See our guide to config file examples for more examples of real configs in action.
| Valid in | |
|---|---|
| machine config files | YES  |
| mode config files | NO  |
The lights: section of your config is where you configure physical
lights for your hardware platform.
Note
As of MPF 0.50, all lights have been combined into this single lights
configuration. If you are using 0.33 or earlier, please see
matrix_lights: for incandescent
bulbs and leds: for LEDs.
Concepts
MPF supports white, single-color or multi-color lights. Traditional GIs are single white. Similar, single-color red lights are possible (i.e. red inserts). RGBW lights are possible as well. They maintain an additional white channel for better color reproduction.
To support all those different kinds of lights with a single interface for various hardware generations MPF abstracts two concepts: Light numbers and channel numbers.
Light Numbers
Configuring the number of a light is often the simplest way.
Internally, your hardware platform will turn this into one or multiple
channels (see below) depending on the subtype configured. For
instance, if lights are usually RGB the platform will parse the number
into three channels.
This is an example:
lights:
my_led:
number: 7 # might also be 8-7 or 8-1-0 depending on your platform
This is often the easiest way to start and will work in most cases.
Channel Numbers
Channel numbers can be configured in channels and describe the number
for a single light channel each. This channel number is then used when
the talking to the hardware. For single-color or white light this can be
the same as number. However, for some serial LED platforms this might
be also number * 3 or a more complex conversion.
This is an example:
lights:
rainbow_star:
type: rgb
channels:
red:
number: 9-29
green:
number: 9-30
blue:
number: 9-40 # this light is not sequential to the previous
This syntax allows the greatest flexibility but is also the most verbose one.
You can either use channels to arbitrarily map channels to colors or
you can use start_channel + type (color order) to define the first
channel and then map colors sequentially to the following channels as
defined in the color order. Instead of start_channel you can also
chain lights by configuring the previous light and let MPF (with help
by the hardware platform) figure out the channel number.
This is an example:
lights:
rainbow_star: # this will use red: 9-29, green: 9-30 and blue: 9-31
type: rgb
start_channel: 9-29
rainbow_star2: # this will use red: 9-33, green: 9-32 and blue: 9-34
type: grb # notice the changed order here
previous: rainbow_star
This syntax covers almost all practical cases and is beneficial with serial LEDs as the above channels syntax is very verbose. It allows the service mode to disable broken LEDs if they were removed from a serial chain. Numbers will then be recalculated omitting disabled LEDs. The syntax also works for parallel LEDs and other types of lights.
See the documentation page of your hardware platform for more details about numbers and channels.
Optional settings
The following sections are optional in the lights: section of your
config. (If you don't include them, the default will be used).
channels:
Single value, type: dict. Defaults to empty.
Instead of a single number address for a light, you can enter channels
corresponding to the multi-color channels of an RGB or RGBW LED. Each
channel entry can contain any of the lights parameters listed on this
page, but at least number is required.
lights:
rainbow_star:
type: rgb
channels:
red:
number: 9-29
green:
number: 9-30
blue:
number: 9-31
Note that a light must have either channels or number defined, but
cannot have both. See LEDs
for more details about how to configure channels for different types of
LEDs.
color_correction_profile:
Single value, type: string. Defaults to empty.
If provided, a color correction profile will be applied to all color settings this light receives. By order of operations, the light will be set to the requested color first and then the color correction profile will be applied on top.
default_on_color:
Single value, type: color (color name, hex, or list of values
0-255). Default: ffffff
For multi-color LEDs, the color defined here will be used when the light is enabled via "on" (as opposed to being enabled with a specific color). Not intended for single-color lights.
Color values may be a hex string (e.g. 22FFCC), a list of RGB values (e.g. [50, 128, 206]), or a color name (e.g. turquoise). MPF knows 140+ standard web color names, and you can define your own custom colors in the named_colors: section of your config.
fade_ms:
Single value, type: time string (ms)
(Instructions for entering time strings). Defaults to empty.
When this light receives instructions to change color, it can interpolate from its current value to the new value over a fade time. If no value is provided, the machine default will be used. If this light is part of a show that defines a fade time, the show's value will supercede this light's setting.
number:
Single value, type: string. Defaults to empty.
This is the number of the light which specifies which output the hardware bulb or LED is physically connected to. The exact format used here will depend on which control system you're using and how the light is connected.
See the How to configure "number:" settings guide for details.
Note that a light must have either channels or number defined, but
cannot have both.
platform:
Single value, type: string. Defaults to empty.
Name of the platform this LED is connected to. The default value of
None means the default hardware platform will be used. You only need
to change this if you have multiple different hardware platforms in use
and this coil is not connected to the default platform.
See the Mixing-and-Matching hardware platforms guide for details.
There is a special platform drivers which will reference a driver
which has to be configured in the number setting. It can be used if
you got a light which is connected to a driver in your platform. That
might be the case for GIs for example. This is an example for a driver as light:
coils:
light_connected_to_a_driver:
number: 42 # number depends on your platform
allow_enable: true # this will allow 100% enable without pwm
lights:
light_on_a_driver:
number: light_connected_to_a_driver # map this light to a driver
platform: drivers
platform_settings:
Single value, type: dict. Defaults to empty.
Platform-specific light settings. Consult your platform documentation for details.
previous:
Single value, type: string name of a lights: device. Defaults to empty.
Instead of specifying the number for each light in a chain you can also use the previous setting. To do this only specify the number of the first light in the chain and then link all consequent light using the previous setting:
lights:
led_0:
number: 0
subtype: led
type: rgb
led_1:
previous: led_0
subtype: led
type: rgbw
led_2:
previous: led_1
subtype: led
type: rgbw
MPF will then calculate the number based on the light of the previous light. Make sure MPF knows how many channel each light has (i.e. by specifying the type parameter). This is not supported in all platforms but in most of them.
start_channel:
Single value, type: string. Defaults to empty.
In most platforms MPF will calculate the internal address of a light and how many channels it has using the number parameter. If you got unusual types of lights (such as RGBW LEDs) you can instead provide this internal address and the number of channels (i.e. using type). This is an example:
lights:
led_0:
start_channel: 0-0
subtype: led
type: rgbw
Consult the manual of your platform for details.
subtype:
Single value, type: string. Defaults to empty.
If you hardware platform supports multiple types of lights you need to
set a subtype to tell your platform how to address this light (to
prevent number collisions). Typical values are led, matrix or
gi. Consult your platform documentation for details.
type:
Single value, type: string. Defaults to empty.
Default value is rgb.
This describes the channel order of an LED. Can be 1 to many channels (if supported by hardware). Valid channels: r (red), g (green), b (blue), w (white=minimum of red, green and blue), + (always on), - (always off).
When using serial LEDs (e.g. with FAST or Fadecandy), use rgb for WS2812 and grb for WS2811 LEDs.
x:
Single value, type: number (will be converted to floating point).
Defaults to empty.
This is used for display_light_player to determine the position of this light on the playfield and use it as a huge display.
y:
Single value, type: number (will be converted to floating point).
Defaults to empty.
This is used for display_light_player to determine the position of this light on the playfield and use it as a huge display.
z:
Single value, type: number (will be converted to floating point).
Defaults to empty.
Currently not used anywhere.
console_log:
Single value, type: one of the following options: none, basic, full.
Default: basic
Log level for the console log for this device.
debug:
Single value, type: boolean (true/false). Default: false
If True, this light will log its configuration and color changes to
the debug log.
file_log:
Single value, type: one of the following options: none, basic, full.
Default: basic
Log level for the file log for this device.
label:
Single value, type: string. Default: %
Name of the light in service mode.
tags:
List of one (or more) values, each is a type: string. Defaults to
empty.
Lights can be referenced by their tags in light_players. Typical tags are gi for all GIs or playfield_inserts for all inserts on the playfield.
Related How To guides
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