Instructions

AchieveCondition

The AchieveCondition instruction is a compound instruction that requires exactly two child instructions (or instruction trees). The first child is the condition to achieve, while the second child is an action that will be taken if the condition was not satisfied on the first try. If the action is asynchronous, i.e. it returns RUNNING while executing, it will be interrupted if the condition is satisfied before the action has finished.

The following instruction trees are equivalent:

# With AchieveCondition
AchieveCondition
├── <Condition>
└── <Action>

# Using a ReactiveFallback
ReactiveFallback
├── <Condition>
└── Sequence
    ├── ForceSuccess
    │   └── <Action>
    └── <Condition>

Note

This instruction has no custom attributes.

Example

This procedure will execute two branches in parallel:

  • The first branch is an AchieveCondition instruction that will check if the live variable is equal to one. If this is not the case, it will execute its second child, which is a simple wait instruction, which is asynchronous. This means that it will be interrupted as soon as the condition becomes true.

  • The second branch consists of a short wait instruction, followed by a copy instruction that will make sure the aforementioned condition will be satisfied.

This procedure will succeed, since the second branch makes sure the condition will be satisfied, at least after the wait instruction.

<ParallelSequence>
    <AchieveCondition>
        <Equals leftVar="live" rightVar="one"/>
        <Wait timeout="1.0"/>
    </AchieveCondition>
    <Sequence>
        <Wait timeout="0.2"/>
        <Copy inputVar="one" outputVar="live"/>
    </Sequence>
</ParallelSequence>
<Workspace>
    <Local name="live" type='{"type":"uint64"}' value='0' />
    <Local name="one" type='{"type":"uint64"}' value='1' />
</Workspace>

AchieveConditionWithOverride

The AchieveConditionWithOverride instruction is a compound instruction with one or two child instructions (or instruction trees). The first child is the condition to achieve, while the second optional child is an action that will be taken if the condition was not satisfied on the first try.

Its behavior is very similar to the AchieveCondition instruction, except that:

  • When the condition is not satisfied, even after trying the optional action, the user will be offered three choices:

    • Retry: start the whole execution again, i.e. check condition and optionally execute the action.

    • Override: return SUCCESS. This overrides the fact that the condition was not (yet) satisfied.

    • Abort: return FAILURE immediately.

  • The second child is optional.

Attribute name

Attribute type

Mandatory

Description

dialogText

StringType

no

Text to display in the user dialog (default: Condition is still not satisfied. Please select action.)

Example

This procedure will check if the live variable is equal to one. Since this is not the case, it will try its child action, which waits for one second. Afterwards, the condition is again evaluated and still found to be false. This will trigger the user input part, where the user can select between Retry, Override or Abort. Depending on this choice, the AchieveConditionWithOverride instruction will restart from the beginning, return SUCCESS or FAILURE respectively.

<AchieveConditionWithOverride>
    <Equals leftVar="live" rightVar="one"/>
    <Wait timeout="1.0"/>
</AchieveConditionWithOverride>
<Workspace>
    <Local name="live" type='{"type":"uint64"}' value='0' />
    <Local name="one" type='{"type":"uint64"}' value='1' />
</Workspace>

AchieveConditionWithTimeout

The AchieveConditionWithTimeout instruction is a compound instruction with exactly two child instructions (or instruction trees). The first child is the condition to achieve, while the second child is an action that will be taken if the condition was not satisfied on the first try. If the action is asynchronous, i.e. it returns RUNNING while executing, it will be interrupted if the condition is satisfied before the action has finished.

Its behavior is again similar to the AchieveCondition instruction, except that:

  • After performing the action (if the condition was not immediately satisfied), the instruction allows for a certain time to achieve the condition.

AchieveConditionWithTimeout is fully equivalent to a ReactiveFallback as shown in the following two equivalent instruction trees:

# With AchieveConditionWithTimeout
AchieveConditionWithTimeout timeout="10.0"
├── <Condition>
└── <Action>

# Using a ReactiveFallback
ReactiveFallback
├── <Condition>
└── Sequence
    ├── ForceSuccess
    │   └── <Action>
    └── Fail timeout="10.0"

Attribute name

Attribute type

Mandatory

Description

timeout

Float64Type

yes

Timeout in seconds

Note

The list of variable names to monitor is required for the instruction to know when to re-evaluate the condition during the timeout period. On every listed variable change, it will evaluate this condition.

Warning

The comma-separated list of variable names should not contain whitespace after the comma!

Example

This procedure will check if the live variable is equal to one. Since this is not the case, it will try its child action, which waits for one second. Afterwards, the condition is again evaluated and still found to be false, i.e. FAILURE. The AchieveConditionWithOverride instruction will allow for the condition to become true with a given timeout of three seconds. Since the live variable never changes, after this period, the procedure will exit with a FAILURE status.

<AchieveConditionWithTimeout timeout="3.0">
    <Equals leftVar="live" rightVar="one"/>
    <Wait timeout="1"/>
</AchieveConditionWithTimeout>
<Workspace>
    <Local name="live" type='{"type":"uint64"}' value='0' />
    <Local name="one" type='{"type":"uint64"}' value='1' />
</Workspace>

ExecuteWhile

The ExecuteWhile instruction is a compound instruction with exactly two child instructions (or instruction trees). The first child is the instruction tree to execute, while the second child denotes a condition that must be satisfied during the first child’s execution. As soon as this condition fails, i.e. returns FAILURE, the execution of the first child is interrupted and the parent ExecuteWhile instruction will return FAILURE. Only when the first child was successfully executed, while satisfying the condition all the time, will the parent instruction return SUCCESS.

The following instruction trees are equivalent:

# With ExecuteWhile
ExecuteWhile
├── <Action>
└── <Condition>

# Using a ReactiveSequence
ReactiveSequence
├── <Condition>
└── Async
    └── <Action>

Note

If the action is already asynchronous, i.e. it can return RUNNING, a simple ReactiveSequence is a better choice to achieve this behavior.

Note

This instruction has no attributes.

Note

The list of variable names to monitor is required for the instruction to know when to re-evaluate the condition during execution of the first child instruction tree. On every listed variable change, it will evaluate this condition.

Warning

The comma-separated list of variable names should not contain whitespace after the comma!

Example

This procedure will continuously check if the live variable is zero and will exit with FAILURE status as soon as this is not the case. At the same time, while the condition is still true, it will execute its first child, which is a simple wait instruction. Since the wait instruction will succeed after one second and the condition will remain true, this procedure will finish with a SUCCESS status after one second.

<ExecuteWhile>
    <Wait timeout="1.0"/>
    <Equals leftVar="live" rightVar="zero"/>
</ExecuteWhile>
<Workspace>
    <Local name="live" type='{"type":"uint64"}' value='0' />
    <Local name="zero" type='{"type":"uint64"}' value='0' />
</Workspace>

WaitForCondition

The WaitForCondition instruction is a compound instruction with exactly one child instruction (or instruction tree). The child denotes the condition to wait for, where the SUCCESS status of the child means that the condition is satisfied and FAILURE that it is not.

The following instruction trees are equivalent:

# With WaitForCondition
WaitForCondition timeout="5.0"
└── <Condition>

# Using a ReactiveFallback
ReactiveFallback
├── <Condition>
└── Fail timeout="5.0"

Note

This instruction has no custom attributes.

Note

The list of variable names to monitor is required for the instruction to know when to re-evaluate the condition during the timeout period. On every listed variable change, it will evaluate this condition.

Warning

The comma-separated list of variable names should not contain whitespace after the comma!

Example

This procedure will monitor the live variable and wait with a timeout of two seconds for it to become one. Since the live variable never changes and does not fulfill the condition, this procedure will exit with a FAILURE status after two seconds.

<WaitForCondition timeout="2.0">
    <Equals leftVar="live" rightVar="one"/>
</WaitForCondition>
<Workspace>
    <Local name="live" type='{"type":"uint64"}' value='0' />
    <Local name="one" type='{"type":"uint64"}' value='1' />
</Workspace>