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 NO 🚫
mode config files NO 🚫

The timer_control_events: section of your config is where you configure control events for your timer.

They're entered as a list (with dashes) under the control_events: section. All control events have an event: and action: setting. (When the "event" is posted, the "action" is taken. Some actions require an additional value: setting. For example, for the "add" action which adds time, you need to to specify how much time you want to add. But other actions, like "start" or "stop" don't need values.

Here's an example of control events in action:

##! mode: mode1
    direction: down
    start_value: 10
    tick_interval: 125s
      - event: start_my_timer
        action: start
      - event: reset_my_timer
        action: reset
      - event: add_5_secs
        action: add
        value: 5

In the example above, when the event start_my_timer is posted, the timer called "my_timer" will start running. When the event add_5_secs is posted, 5 seconds will be added to whatever the current value of "my_timer" is, etc.

Required settings

The following sections are required in the timer_control_events: section of your config:


Single value, type: one of the following options: add, subtract, jump, start, stop, reset, restart, pause, set_tick_interval, change_tick_interval, reset_tick_interval.

Take a look at the various types of actions you can perform on timers with control events:


: Adds the time (specified in the value: setting) to the timer. If the value would be higher than the timer's max_value: setting, then the value is set to the max value. Posts the timer_(name)_time_added event.

This action does not change the timer's running state.

The timer is checked for done after the value has been added. (So,
for example, if you have a timer that's set to count up, and the
timer finishes at 10, and the timer is currently at 6, and you add
value of 5, then the timer will be complete.


: Subtracts time (specified in the value: setting) from the timer. Posts the timer_(name)_time_subtracted event and checks to see if the timer is complete.


: "Jumps" the timer to a specific new value (specified in the value: setting) and checks to see if the timer is complete.


: Starts the timer if it's not running. Does nothing if the timer is already running. Posts the timer_(name)_started event.


: Stops the timer and posts the timer_(name)_stopped event. Removes any outstanding "pause" delays.


: Changes the timers current value back to the start_value:. Nothing else is touched, so if the timer is running, it stays running, etc.


: Acts as a combination of reset, then start.


: Pauses the timer for a given value: time (in seconds). Note that the timer pause value is real world seconds and does not take the timers tick interval into consideration. If the pause value is 0, the timer is paused indefinitely. Posts the timer_(name)_paused event.


: Sets the tick interval to a new value (specified in the value: setting).


: Changes the tick interval by multiplying the current tick interval by the new one specified in the value: setting. In other words, if you want to make the tick interval 10% faster, than set this to value: 1.1. If you want to make it 50% slower, set this to value: 0.5, etc.


: (added in MPF 0.33)

Resets the timer's tick interval back to the original from the
`tick_interval:` setting.


Single value, type: string.

The event which will trigger this value.

Optional settings

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


Single value, type: number or template (will be converted to floating point; Instructions for entering templates).

The value for this action. Not all actions require a value (i.e. start and stop do not). You can use placeholders here to calculate it during runtime.

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