Skip to content
Permalink
Browse files

document state machine config

  • Loading branch information...
jabdoa2 committed May 12, 2019
1 parent 90864fa commit aadea2392c08c0d79ee96a8bc23b4d6639f6ae5e
@@ -422,28 +422,7 @@ def _get_index_of_next_heading(self, doc_lines):
# we have a heading sep
return i - 1

def _get_spec_string(self, num, stype, default=None):
if num == 'single':
return_string = 'Single value, '
elif num == 'list' or num == 'set':
return_string = 'List of one (or more) values, each is a '
elif num == 'dict':
return_string = ('Parent setting for one (or more) sub-settings. '
'Each sub-setting is a ')
elif num == 'omap':
return_string = ('Ordered list for one (or more) sub-settings. '
'Each sub-setting is a ')
elif num == 'event_handler':
return_string = 'List of one (or more) device control events (:doc:`Instructions for entering '\
'device control events </config/instructions/device_control_events>`).'
if default is not None and default != "None":
return_string += " Default: " + default
return_string += '\n'
return return_string

else:
raise AssertionError("Invalid config spec num: {}".format(num))

def _get_type_desc(self, stype):
if stype == 'str':
ftype = '``string``'

@@ -511,8 +490,8 @@ def _get_spec_string(self, num, stype, default=None):
ftype = '``gain setting`` (-inf, db, or float between 0.0 and 1.0)'

elif stype.startswith('subconfig'):
ftype = 'sub-configurating containing {} settings'.format(
stype.replace('subconfig(', '')[:-1])
config = stype.replace('subconfig(', '')[:-1]
ftype = ':doc:`{} <{}>`'.format(config, config)

elif stype.startswith('enum'):
ftype = 'one of the following options: {}'.format(
@@ -524,13 +503,39 @@ def _get_spec_string(self, num, stype, default=None):
stype.replace('machine(', '')[:-1])

elif ':' in stype:
stype = tuple(stype.split(':'))
return_string = 'One or more sub-entries, each in the format of '
ftype = '``{}``:``{}``'.format(stype[0], stype[1])
raise AssertionError("Should be catched earlier.")

else:
ftype = stype

return ftype

def _get_spec_string(self, num, stype, default=None):
if num == 'single':
return_string = 'Single value, '
elif num == 'list' or num == 'set':
return_string = 'List of one (or more) values, each is a '
elif num == 'dict':
stype = tuple(stype.split(':'))
return_string = 'One or more sub-entries, each in the format of {} : {}'.format(
self._get_type_desc(stype[0]), self._get_type_desc(stype[1]))
return return_string
elif num == 'omap':
return_string = ('Ordered list for one (or more) sub-settings. '
'Each sub-setting is a ')
elif num == 'event_handler':
return_string = 'List of one (or more) device control events (:doc:`Instructions for entering '\
'device control events </config/instructions/device_control_events>`).'
if default is not None and default != "None":
return_string += " Default: " + default
return_string += '\n'
return return_string

else:
raise AssertionError("Invalid config spec num: {}".format(num))

ftype = self._get_type_desc(stype)

return_string += 'type: {}.'.format(ftype)

if default is not None and default != "None":
@@ -0,0 +1,79 @@
show_config:
============

*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 ``show_config:`` section of your config is where you configure a show to play within a device.

See :doc:`show_player <show_player>` for more details about the settings.


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

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

show:
~~~~~
Single value, type: ``string``.

The show to play.


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

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

loops:
~~~~~~
Single value, type: ``integer``. Default: ``-1``

How often should the show loop? ``-1`` means forever.

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

Whatever, the show should advance manually only.

priority:
~~~~~~~~~
Single value, type: ``integer``. Default: ``0``

Priority for this show.
This is usually added to the mode priority if the device is defined within a
mode.

show_tokens:
~~~~~~~~~~~~
One or more sub-entries, each in the format of ``string`` : ``string``
Dict of show tokens to pass to the show.

speed:
~~~~~~
Single value, type: ``number`` (will be converted to floating point). Default: ``1``

Speed multiplier for this show.

start_step:
~~~~~~~~~~~
Single value, type: ``integer``. Default: ``1``

First step to play.

sync_ms:
~~~~~~~~
Single value, type: ``integer``.

See the :doc:`/shows/sync_ms` documentation for details.


@@ -308,3 +308,10 @@ Default: ``None``.
Event(s) that will be posted when this show has been updated. Note that the
show "update" function has not been implemented yet, so this setting is more
of a placeholder at the moment.


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

show_config: <show_config>
@@ -0,0 +1,51 @@
state_machine_states:
=====================

*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 ``state_machine_states:`` section of your config is where you configure the states of your :doc:`state machine <state_machines>`.

See :doc:`state machines </game_logic/logic_blocks/state_machines>` for details.


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

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

events_when_started:
~~~~~~~~~~~~~~~~~~~~
List of one (or more) values, each is a type: ``string``.

The event will be posted when the state machine enters this state.
This is the entry action for this state in your finite state machine.

events_when_stopped:
~~~~~~~~~~~~~~~~~~~~
List of one (or more) values, each is a type: ``string``.

The event will be posted when the state machine leaves this state.
This is the exit action for this state in your finite state machine.

label:
~~~~~~
Single value, type: ``string``.

The full name/description of this state.

show_when_active:
~~~~~~~~~~~~~~~~~
Single value, type: :doc:`show_config <show_config>`.

A show which is played when the state machine is in this state.
This is kind of an entry action as you could use ``events_when_started`` and
a :doc:`show_player` to achieve the same.
It is meant as a helper because it is common to play one show per step.
@@ -0,0 +1,56 @@
state_machine_transitions:
==========================

*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 ``state_machine_transitions:`` section of your config is where you configure the transitions of your :doc:`state machine <state_machines>`.

Transitions will only be available if the state machine is in one of the states listed in ``source``.
In that case the machine will transition to the state listed in ``target``.
See :doc:`state machines </game_logic/logic_blocks/state_machines>` for details.


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

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

events:
~~~~~~~
List of one (or more) values, each is a type: ``string``.

If the state machine is in one of the states listed in ``source`` this event
will transition the machine to the state listed in ``target``.

source:
~~~~~~~
List of one (or more) values, each is a type: ``string``.

Transitions will only be available if the state machine is in one of the states listed in ``source``.

target:
~~~~~~~
Single value, type: ``string``.

The machine will transition to this state if it is in a state listed in
``source`` and one of the ``events`` is posted.


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

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

events_when_transitioning:
~~~~~~~~~~~~~~~~~~~~~~~~~~
List of one (or more) values, each is a type: ``string``.

This event will be posted when the transition is triggered.
@@ -9,14 +9,14 @@ state_machines:
| Valid in :doc:`mode config files </config/instructions/mode_config>` | **YES** |
+----------------------------------------------------------------------------+---------+

.. overview
+------------------------------------------------------------------------------+
| Related Tutorial |
+==============================================================================+
| :doc:`/game_logic/logic_blocks/integrating_logic_blocks_and_shows` |
+------------------------------------------------------------------------------+

.. overview
The ``state_machines:`` section of your config is where you configure generic :doc:`state machines </game_logic/logic_blocks/state_machines>`.


@@ -27,8 +27,7 @@ The following sections are required in the ``state_machines:`` section of your c

states:
~~~~~~~
One or more sub-entries, each in the format of type: ``str``:``subconfig(state_machine_states)``.

One or more sub-entries, each in the format of ``string`` : :doc:`state_machine_states <state_machine_states>`
List all of your states here. For examples:

.. code-block:: mpf-config
@@ -52,7 +51,7 @@ List all of your states here. For examples:

transitions:
~~~~~~~~~~~~
List of one (or more) values, each is a type: sub-configurating containing state_machine_transitions settings.
List of one (or more) values, each is a type: :doc:`state_machine_transitions <state_machine_transitions>`.

List all your transitions here (we start with the same steps as above):

@@ -100,4 +99,42 @@ Single value, type: ``boolean`` (Yes/No or True/False). Default: ``False``

If set to true MPF will restore the state of a logic_block on mode restart.

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

Log level for the console log for this device.

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

Set this to true to see additional debug output. This might impact the performance of MPF.

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

Log level for the file log for this device.

label:
~~~~~~
Single value, type: ``string``. Default: ``%``

Name of this device in service mode.

tags:
~~~~~
List of one (or more) values, each is a type: ``string``.

Not used.


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

state_machine_transitions: <state_machine_transitions>
state_machine_states: <state_machine_states>


@@ -6,6 +6,10 @@ State Machine Logic Block
+==============================================================================+
| :doc:`/config/state_machines` |
+------------------------------------------------------------------------------+
| :doc:`/config/state_machine_states` |
+------------------------------------------------------------------------------+
| :doc:`/config/state_machine_transitions` |
+------------------------------------------------------------------------------+

+------------------------------------------------------------------------------+
| Related How To Guides |
@@ -16,6 +20,9 @@ State Machine Logic Block
"State machines" are a type of :doc:`Logic Block </game_logic/logic_blocks/index>`
where you can trigger state transitions based on the current state and an event.

Technically, this is a `finite state machine <https://en.wikipedia.org/wiki/Finite-state_machine>`_
as known from CS class.

This is an example:

.. code-block:: mpf-config

0 comments on commit aadea23

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