self.machine.leds.*

class mpf.devices.led.Led(self_inner, *args, **kwargs)

Bases: mpf.core.system_wide_device.SystemWideDevice

An RGB LED in a pinball machine.

Accessing leds in code

The device collection which contains the leds in your machine is available via self.machine.leds. For example, to access one called "foo", you would use self.machine.leds.foo. You can also access leds in dictionary form, e.g. self.machine.leds['foo'].

You can also get devices by tag or hardware number. See the DeviceCollection documentation for details.

Methods & Attributes

Leds have the following methods & attributes available. Note that methods & attributes inherited from base classes are not included here.

clear_stack()

Remove all entries from the stack and resets this LED to 'off'.

color(color, fade_ms=None, priority=0, key=None, mode=None)

Add or update a color entry in this LED's stack, which is how you tell this LED what color you want it to be.

Parameters:
  • color -- RGBColor() instance, or a string color name, hex value, or 3-integer list/tuple of colors.
  • fade_ms -- Int of the number of ms you want this LED to fade to the color in. A value of 0 means it's instant. A value of None (the default) means that it will use this LED's and/or the machine's default fade_ms setting.
  • priority -- Int value of the priority of these incoming settings. If this LED has current settings in the stack at a higher priority, the settings you're adding here won't take effect. However they're still added to the stack, so if the higher priority settings are removed, then the next-highest apply.
  • key -- An arbitrary identifier (can be any immutable object) that's used to identify these settings for later removal. If any settings in the stack already have this key, those settings will be replaced with these new settings.
  • mode -- Optional mode instance of the mode that is setting this color. When a mode ends, entries from the stack with that mode will automatically be removed.
color_correct(color)

Apply the current color correction profile to the color passed.

Parameters:color -- The RGBColor() instance you want to get color corrected.
Returns:An updated RGBColor() instance with the current color correction profile applied.

Note that if there is no current color correction profile applied, the returned color will be the same as the color that was passed.

fade_task(dt)

Perform a fade depending on the current time.

Parameters:dt -- time since last call
gamma_correct(color)

Apply max brightness correction to color.

Parameters:color -- The RGBColor() instance you want to have gamma applied.
Returns:An updated RGBColor() instance with gamma corrected.
get_color()

Return an RGBColor() instance of the 'color' setting of the highest color setting in the stack.

This is usually the same color as the physical LED, but not always (since physical LEDs are updated once per frame, this value could vary.

Also note the color returned is the "raw" color that does has not had the color correction profile applied.

classmethod mode_stop(mode: mpf.core.mode.Mode)

Remove all entries from mode.

Parameters:mode -- Mode which was removed
off(fade_ms=None, priority=0, key=None, **kwargs)

Turn LED off.

Parameters:
  • key -- key for removal later on
  • priority -- priority on stack
  • fade_ms -- duration of fade
on(fade_ms=None, priority=0, key=None, **kwargs)

Turn LED on.

Parameters:
  • key -- key for removal later on
  • priority -- priority on stack
  • fade_ms -- duration of fade
remove_from_stack_by_key(key)

Remove a group of color settings from the stack.

Parameters:key -- The key of the settings to remove (based on the 'key' parameter that was originally passed to the color() method.)

This method triggers a LED update, so if the highest priority settings were removed, the LED will be updated with whatever's below it. If no settings remain after these are removed, the LED will turn off.

remove_from_stack_by_mode(mode: mpf.core.mode.Mode)

Remove a group of color settings from the stack.

Parameters:mode -- Mode which was removed

This method triggers a LED update, so if the highest priority settings were removed, the LED will be updated with whatever's below it. If no settings remain after these are removed, the LED will turn off.

set_color_correction_profile(profile)

Apply a color correction profile to this LED.

Parameters:profile -- An RGBColorCorrectionProfile() instance
stack = None

A list of dicts which represents different commands that have come in to set this LED to a certain color (and/or fade). Each entry in the list contains the following key/value pairs:

priority: The relative priority of this color command. Higher numbers
take precedent, and the highest priority entry will be the command that's currently active. In the event of a tie, whichever entry was added last wins (based on 'start_time' below).
start_time: The clock time when this command was added. Primarily used
to calculate fades, but also used as a tie-breaker for multiple entries with the same priority.
start_color: RGBColor() of the color of this LED when this command came
in.
dest_time: Clock time that represents when a fade (from start_color to
dest_color) will be done. If this is 0, that means there is no fade. When a fade is complete, this value is reset to 0.
dest_color: RGBColor() of the destination this LED is fading to. If
a command comes in with no fade, then this will be the same as the 'color' below.
color: The current color of the LED based on this command. This value
is updated automatically as fades progress, and it's the value that's actually written to the hardware (prior to color correction).
key: An arbitrary unique identifier to keep multiple entries in the
stack separate. If a new color command comes in with a key that already exists for an entry in the stack, that entry will be replaced by the new entry. The key is also used to remove entries from the stack (e.g. when shows or modes end and they want to remove their commands from the LED).
mode: Optional mode where the brightness was set. Used to remove
entries when a mode ends.
classmethod update_leds(dt)

Write leds to hardware platform.

Called periodically (default at the end of every frame) to write the new led colors to the hardware for the LEDs that changed during that frame.

Parameters:dt -- time since last call
write_color_to_hw_driver()

Set color to hardware platform.

Physically update the LED hardware object based on the 'color' setting of the highest priority setting from the stack.

This method is automatically called whenever a color change has been made (including when fades are active).