self.machine.lights.*

class mpf.devices.matrix_light.MatrixLight(self_inner, *args, **kwargs)

Bases: mpf.core.system_wide_device.SystemWideDevice

Represents a light connected to a traditional lamp matrix in a pinball machine.

This light could be an incandescent lamp or a replacement single-color LED. The key is that they're connected up to a lamp matrix.

Accessing lights in code

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

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

Methods & Attributes

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

add_handler(callback)

Register a handler to be called when this light changes state.

Parameters:callback -- Monitor callback to add
clear_stack()

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

fade_task(dt)

Update the brightness depending on the time for a fade.

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

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 mode entries from stack.

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

Turn this light off.

Parameters:
  • fade_ms -- Int of the number of ms you want this light to fade to the brightness in. A value of 0 means it's instant. A value of None (the default) means that it will use this lights's and/or the machine's default fade_ms setting.
  • priority -- Int value of the priority of these incoming settings. If this light 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 brightness. When a mode ends, entries from the stack with that mode will automatically be removed.
  • **kwargs -- Not used. Only included so this method can be used as an event callback since events could pass random kwargs.
on(brightness=255, fade_ms=None, priority=0, key=None, mode=None, **kwargs)

Turn light on.

Add or updates a brightness entry in this lights's stack, which is how you tell this light how bright you want it to be.

Parameters:
  • brightness -- How bright this light should be, as an int between 0 and 255. 0 is off. 255 is full on. Note that matrix lights in older (even WPC) machines had slow matrix update speeds, and effective brightness levels will be far less than 255.
  • fade_ms -- Int of the number of ms you want this light to fade to the brightness in. A value of 0 means it's instant. A value of None (the default) means that it will use this lights's and/or the machine's default fade_ms setting.
  • priority -- Int value of the priority of these incoming settings. If this light 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 brightness. When a mode ends, entries from the stack with that mode will automatically be removed.
  • **kwargs -- Not used. Only included so this method can be used as an event callback since events could pass random kwargs.
remove_from_stack_by_key(key)

Remove a group of brightness settings from the stack.

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

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

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

Remove a group of brightness settings from the stack.

Parameters:mode -- Mode which was removed

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

remove_handler(callback=None)

Remove a handler from the list of registered handlers.

Parameters:callback -- Monitor callback to remove
stack = None

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

priority: The relative priority of this brightness 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_brightness: Brightness this light when this command came in. dest_time: Clock time that represents when a fade (from

start_brightness to dest_brightness ) 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_brightness: Brightness of the destination this light is fading
to. If a command comes in with no fade, then this will be the same as the 'brightness' below.
brightness: The current brightness of the light based on this command.
(0-255) This value is updated automatically as fades progress, and it's the value that's actually written to the hardware.
key: An arbitrary unique identifier to keep multiple entries in the
stack separate. If a new brightness 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 light).
mode: Optional mode where the brightness was set. Used to remove
entries when a mode ends.
update_hw_light()

Set brightness to hardware platform.

Physically updates the light hardware object based on the 'brightness' setting of the highest priority setting from the stack.

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

classmethod update_matrix_lights(dt)

Write changed lights to hardware.

Parameters:dt -- time since last call