State Machine Blocks

State machine blocks define their behavior using a state machine, instead of an activity. State machine blocks are useful when some functionality naturally fits to a single control state variable, and it is easy to express this functionality by mutually exclusive states on that single control state variable. A lamp with distinct states on and off is an example. In such cases it may be simpler to express a block using a state machine than an activity. Note that state machine blocks can not contain other blocks. If you want to combine behavior from other blocks, use a block with an activity instead.

Like blocks that use activities, state machine blocks have an external contract, also expressed as a state machine. For state machine blocks, this contract is automatically generated and updated whenever the state machine is changed.

Pins

Since this type of block is meant to be used in other enclosing blocks, it must have pins. Pins for a state machine block are defined within the tab Pins:

As with the other blocks, there are different kinds of pins:

  • starting pins to start a block
  • streaming input pins to pass data to a block while it is active
  • streaming output pins to pass data from a block while it is active
  • terminating pins to terminate a block

Like with the other nodes, pins can pass data by passing objects, thus have a type. In the above example only card is typed with String.

State Machine

The state machine describes the internal behavior of the block. It is specified as a transition table within the State Machine tab. Each row in the table contains a transition. The columns show the source state, trigger, guard, actions and the target state of the transition.

Source and Target States

Each transition has a source state and a target state. Source states can be initial states, choices and normal states. Target states can be final states, choices and normal states.

  • The state machine must have one or more initial transitions, with an initial state as source. These transitions are triggered by starting input pins.
  • A state machine usually also has one or more final states, which often output a token via terminating output pins.
  • Choice states are used to introduce decisions. A choice state must only have one incoming transition. This means, there is only one transition that has a specific choice state as target. Choice states must have more than one outgoing transition, and each of them must have a guard. This works similar to an if-statement. Transitions starting at a choice must not have triggers. In this example in choice state d0 the method isCardValid() is used as guard. In case it returns true, the next state is waitingForSki, otherwise it would be final.

Triggers

A trigger indicates when a transition takes place. A trigger can be:

  • a starting pin (STM table: “in via pinName”),
  • an input pin (STM table: “in via pinName”),
  • a timeout of an internal timer (STM table: “timeout timerName”),
  • an internal event (STM table: “EVENT_NAME”).

Timers and internal events can be created by selecting New Timer / New Event as trigger when creating or editing a state machine transition. An existing timer can be started or stopped by choosing “start timerName” or “stop timerName” when creating or editing a state machine transition. This will then appear in the actions column of this transition. Existing timers have to be started, and started timers have to be used as trigger.

Actions

Actions define what is happening when a transition is executed. Each transition towards a normal state may have an arbitrary number of actions. An action can be

  • an output pin (STM table: “out pinName;”),
  • a terminating pin (STM table: “out pinName;”),
  • a method call (STM table: “call methodName;”),
  • a start timer action (STM table: “start timerName;”),
  • a stop timer action (STM table: “stop timerName;”).

Methods that are called as actions have to be provided in the Java file of the state machine block. Once a method with empty parameter list and void as return value is defined in the Java file, this method is offered as possible action when creating or editing a state machine transition. When choosing it, it will appear in the actions column of this transition. Timers have to be created first as trigger before being able to start or stop them as action of a transition.

State Machine and Java Code

The state machine is tightly coupled with Java code. The Java file of an STM block contains variables for parameter nodes with type and methods for guards and actions.

Block Contract

Each time the state machine is edited, the block contract is generated automatically from the state machine specification. The contract is shown as transition table in the Contract tab:

Both, the State Machine and the contract can be shown as diagram:

The contract describes how the block looks from the outside and how it has to be used when being integrated. So it has the same purpose as for local blocks. However it is generated from the state machine specification and does not have to be specified or changed. It can be understood as abstraction of the state machine behavior. Depending on the state machine, it might happen, that 2 or more state machine states are merged into one block contract state.