Skip to content


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 YES ✅


This section can also be used in a show file in the blinkenlights: section of a step.

The blinkenlight_player: section of your config is where you add or remove colors to or from a blinkenlight based on events. It's also used in shows (via the blinkenlights: section) to add or remove colors in that show step.

Example from a config file:

      action: add
      color: red
      key: mykey1
      action: remove
      key: mykey1

In the example above, when the event called some_event is posted, the color red will be added to my_blinkenlight1's list of colors (this will cause the light to immediately start flashing if it wasn't already). The new color will have the key mykey1. The key is used like a name of the color, so that it can be removed later using that key. When the event some_other_event is posted, the red color (key mykey1) will be removed from the blinkenlight.

Example blinkenlight player from a show:

##! show: test
- time: 0
      action: add
      color: blue
      key: blue_color
    my_blinkenlight2: purple

The first example shows the full config, while the second shows the "express" config. (What's an "express config?" Details here.

The blinkenlight player's express config is the "add" action.

See Blinkenlight player for details.

Optional settings

The following sections are optional in the blinkenlight_player: section of your config. (If you don't include them, the default will be used).


Single value, type: one of the following options: add, remove, remove_mode, remove_all. Default: add

What action the blinkenlight should perform. The remove_all action will remove all the colors from the blinkenlight, effectively turning it off. The remove_mode action will remove all the colors that were added by the mode that the remove_mode action is coming from (remember that a blinkenlight can have colors added from lots of different modes -- that's its whole purpose!).


Single value, type: color_or_token. Default: white

The only action that requires a color setting is the add action. It sets the color to add to this blinkenlight. Color values may be a hex string (e.g. 22FFCC), a list of RGB values (e.g. [50, 128, 206]), a color name (e.g. turquoise), or a brightness value (i.e. AA or 120). MPF knows 140+ standard web color names, and you can define your own custom colors in the named_colors: section of your config. If you use brightness on an RGB light MPF will use the brightness for every channel. For instance brigness AA will result in color AAAAAA.


Single value, type: string. Defaults to empty.

You can think of this value as a name for the color you're adding or removing from the blinkenlight. If you add a color, then the key allows you to remove the color later using the key to specify which color to remove. If you don't specify a key, then the color is considered "keyless" (see Blinkenlight player for more information about keyless colors).

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