Skip to content
Permalink
Browse files

add subconfig links and document timer transitions

  • Loading branch information...
jabdoa2 committed May 12, 2019
1 parent aadea23 commit e797a5fc8457d521bfd4263908a0c226171ff2f7
Showing with 171 additions and 101 deletions.
  1. +5 −7 config/flippers.rst
  2. +2 −1 config/light_rings.rst
  3. +1 −1 config/light_stripes.rst
  4. +125 −0 config/timer_control_events.rst
  5. +38 −92 config/timers.rst
@@ -127,7 +127,7 @@ This setting is optional because you can also use ``sw_flip_enable`` below but

ball_search_hold_time:
~~~~~~~~~~~~~~~~~~~~~~
Single value, type: ``time string (ms)`` (:doc:`Instructions for entering time strings </config/instructions/time_strings>`) . Default: ``1s``
Single value, type: ``time string (ms)`` (:doc:`Instructions for entering time strings </config/instructions/time_strings>`). Default: ``1s``

How long this flipper will be activated for when it is activated during ball search.

@@ -165,8 +165,7 @@ EOS switch on this flipper (if there is one).

eos_switch_overwrite:
~~~~~~~~~~~~~~~~~~~~~
One or more sub-entries, each in the format of type: ``str``:``str``.

One or more sub-entries, each in the format of ``string`` : ``string``
If you're using an end of stroke switch with this flipper, enter the
switch name here.

@@ -178,7 +177,7 @@ The name of the hold coil winding for dual-wound flipper coils.

hold_coil_overwrite:
~~~~~~~~~~~~~~~~~~~~
Single value, type: sub-configurating containing coil_overwrites settings.
Single value, type: :doc:`coil_overwrites <coil_overwrites>`.

Overwrites settings on the hold_coil.
See :doc:`coil_overwrites` for details.
@@ -202,7 +201,7 @@ to include an option for flippers in ball search. :)

main_coil_overwrite:
~~~~~~~~~~~~~~~~~~~~
Single value, type: sub-configurating containing coil_overwrites settings.
Single value, type: :doc:`coil_overwrites <coil_overwrites>`.

Overwrites settings on the main_coil.
See :doc:`coil_overwrites` for details.
@@ -259,8 +258,7 @@ Disables a flipper from software. Use this together with ``sw_flip_events``.

switch_overwrite:
~~~~~~~~~~~~~~~~~
One or more sub-entries, each in the format of type: ``str``:``str``.

One or more sub-entries, each in the format of ``string`` : ``string``
Overwrites settings on the activation_switch.
See :doc:`switch_overwrites` for details.

@@ -21,6 +21,7 @@ The only difference between :doc:`light_stripes </config/light_stripes>` and
.. literalinclude:: /mpf_examples/light/config/light_groups.yaml
:language: yaml


Required settings
-----------------

@@ -34,7 +35,7 @@ The integer value for how many LEDs are in the ring.

light_template:
~~~~~~~~~~~~~~~
Single value, type: sub-configurating containing lights,device settings.
Single value, type: :doc:`lights <lights>`.

This is a list of sub-settings (indented) that are regular settings from the
:doc:`lights` section of your machine config. Any settings that are valid there
@@ -36,7 +36,7 @@ The integer value for how many LEDs are in the stripe.

light_template:
~~~~~~~~~~~~~~~
Single value, type: sub-configurating containing lights,device settings.
Single value, type: :doc:`lights <lights>`.

This is a list of sub-settings (indented) that are regular settings from the
:doc:`lights` section of your machine config. Any settings that are valid there
@@ -0,0 +1,125 @@
timer_control_events:
=====================

*Config file section*

+----------------------------------------------------------------------------+---------+
| Valid in :doc:`machine config files </config/instructions/machine_config>` | **NO** |
+----------------------------------------------------------------------------+---------+
| Valid in :doc:`mode config files </config/instructions/mode_config>` | **NO** |
+----------------------------------------------------------------------------+---------+

.. overview
The ``timer_control_events:`` section of your config is where you configure control events for your :doc:`timer <timers>`.

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:

.. code-block:: mpf-config

##! mode: mode1
timers:
my_timer:
direction: down
start_value: 10
tick_interval: 125s
control_events:
- 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:

action:
~~~~~~~
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:

``add``
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.

``subtract``
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.

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

``start``
Starts the timer if it's not running. Does nothing if the timer is already running.
Posts the *timer_<name>_started* event.

``stop``
Stops the timer and posts the *timer_<name>_stopped* event. Removes any outstanding "pause" delays.

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

``restart``
Acts as a combination of reset, then start.

``pause``
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.

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

``change_tick_interval``
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.

``reset_tick_interval``
(added in MPF 0.33)

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

event:
~~~~~~
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).

value:
~~~~~~
Single value, type: ``number`` or ``template`` (will be converted to floating point; :doc:`Instructions for entering templates </config/instructions/dynamic_values>`).

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.


@@ -9,7 +9,16 @@ timers:
| Valid in :doc:`mode config files </config/instructions/mode_config>` | **YES** |
+----------------------------------------------------------------------------+---------+

The ``timers:`` section of your config is where configure timers that can "tick" up or down.
.. overview
+------------------------------------------------------------------------------+
| Related Tutorial |
+==============================================================================+
| :doc:`/game_logic/timers/index` |
+------------------------------------------------------------------------------+

The ``timers:`` section of your config is where configure
:doc:`timers </game_logic/timers/index>` that can "tick" up or down.
Timers post events with each tick which you can use to update slides, etc. You can set the
start and stop values of the timers, as well as how fast they tick, how much they change per
tick, and other settings.
@@ -88,105 +97,31 @@ the player missed the skillshot).
A second timer doesn't have any count values associated with it, rather it just "ticks"
once a second. That tick event is used to rotate the lit skillshot.

Settings
--------
See :doc:`timer_control_events` for more details about all the actions available in a timer.

Optional settings
-----------------

Individual timers can use the following options:
The following sections are optional in the ``timers:`` section of your config. (If you don't include them, the default will be used).

bcp:
~~~~
THIS OPTION HAS BEEN REMOVED IN 0.33

Single value, type: ``boolean`` (Yes/No or True/False). Default: ``False``

Controls whether the various timer events (count, start, stop, complete, etc.) are sent to the MPF-MC via BCP.

console_log:
~~~~~~~~~~~~
Single value, type: one of the following options: none, basic, full. Default: ``none``

Log level for the console log for this device.

control_events:
~~~~~~~~~~~~~~~
List of one (or more) values, each is a type: sub-configuration containing control_events settings. Default: ``None``
List of one (or more) values, each is a type: :doc:`timer_control_events <timer_control_events>`.

Timer control events is where you specify what happens to this timer when other events are posted.

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.

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

Options:

``add``
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.

``subtract``
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.

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

``start``
Starts the timer if it's not running. Does nothing if the timer is already running.
Posts the *timer_<name>_started* event.

``stop``
Stops the timer and posts the *timer_<name>_stopped* event. Removes any outstanding "pause" delays.

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

``restart``
Acts as a combination of reset, then start.

``pause``
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.

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

``change_tick_interval``
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.

``reset_tick_interval``
(added in MPF 0.33)

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

Here's an example of control events in action:

.. code-block:: mpf-config

##! mode: mode1
timers:
my_timer:
direction: down
start_value: 10
tick_interval: 125s
control_events:
- 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.
See :doc:`timer_control_events` for more details.

debug:
~~~~~~
@@ -202,7 +137,7 @@ Controls which direction this timer runs in. Options are ``up`` or ``down``.

end_value:
~~~~~~~~~~
Single value, type: ``integer``. Default: ``None``
Single value, type: ``integer`` or ``template`` (:doc:`Instructions for entering templates </config/instructions/dynamic_values>`).

Specifies what the final value for this timer will be. When the timer value equals or exceeds this (for timers counting
up), or when it equals or is lower than this (for timers counting down), the *timer_<name>_complete* event is
@@ -212,9 +147,15 @@ back to its ``start_value:`` and started again.)
Note that you can use a :doc:`dynamic value </config/instructions/dynamic_values>`
for this setting.

file_log:
~~~~~~~~~
Single value, type: one of the following options: none, basic, full. Default: ``basic``

Log level for the file log for this device.

max_value:
~~~~~~~~~~
Single value, type: ``integer``. Default: ``None``
Single value, type: ``integer``.

The maximum value this timer can be. If you try to add value above this, the timer's value will be reset
to this value.
@@ -235,7 +176,7 @@ start control events.

start_value:
~~~~~~~~~~~~
Single value, type: ``integer``. Default: ``0``
Single value, type: ``integer`` or ``template`` (:doc:`Instructions for entering templates </config/instructions/dynamic_values>`). Default: ``0``

The initial value of the timer.

@@ -244,7 +185,7 @@ for this setting.

tick_interval:
~~~~~~~~~~~~~~
Single value, type: ``time string (ms)`` (:doc:`Instructions for entering time strings) </config/instructions/time_strings>` . Default: ``1s``
Single value, type: ``time string (secs) or template`` (:doc:`Instructions for entering time strings </config/instructions/time_strings>` and :doc:`Instructions for entering templates </config/instructions/dynamic_values>`). Default: ``1s``

A time value for how fast each tick is. The default is 1 second, but quite often "pinball time" is slower
than real world time, and a countdown timer will actually tick a speed that's slower than 1 second per
@@ -253,3 +194,8 @@ really short if you want a hurry up, maybe every 100ms removed 77,000 worth of p

.. include:: template_setting.rst

.. toctree::
:maxdepth: 1
:hidden:

timer_control_events: <timer_control_events>

0 comments on commit e797a5f

Please sign in to comment.
You can’t perform that action at this time.