Command

This chapter describes interfaces that together allow for representation of a command. A command represents an action which can be executed by the command queue of an axis control (group).

State machine

Command state machine shows the state diagram of a command and Command state machine states provides a description for each state.

Command state machine

Command state machine

1. This condition is only valid when the command sequence is configured for the command sequence event response.
2. This condition is only valid when the command sequence is not configured for the command sequence event response.

Note

The “[response triggered]” transitions in Command state machine can occur when the command is part of a command sequence event response, see Command sequence event response for detailed behaviour.

ICommandSequence.Reuse()
ICommandQueue.Queue()
ICommandSequence::Reuse()
ICommandQueue::Queue()
Command state machine states

Command state

Description

Idle

Command is not in queue.

Queued

Command is in queue waiting to be executed.

Running

Command queue is currently executing the command.

Completed

Command execution completed. If desired, the command can be reused.

Failed

Command execution failed. If desired, the command can be reused.

A running command can be aborted by the command queue, see Command abortion for the abortion reasons. In case command execution failed the run exception can be retrieved. A new reference to the failed command can be obtained via ICommandSequence or ICommandQueue:

ICommandSequence.FailedCommands
ICommandQueue.FailedCommand
ICommandSequence::GetFailedCommands()
ICommandQueue::GetFailedCommand()

Types

Commands are divided into types, for example State commands, Signal commands and Move commands. Each type is further explained in the sections below.

State commands

State commands are used to control the State machine of axis controls and axis control groups. State commands are blocking, i.e. the queue waits until the state transition has completed before continuing with the next command. The state commands are listed below:

IEnableOperation
IDisableOperation
ISwitchOn
IDisableVoltage
IShutdown
IOpenLoop
ICloseLoop
IEnableOperation
IDisableOperation
ISwitchOn
IDisableVoltage
IShutdown
IOpenLoop
ICloseLoop

During execution of state commands run-time errors can occur. These are errors that are not known at the moment of queuing, but occur at the start of, or during, execution of the command. The run-time errors are listed below:

AbortedException Execution of command overruled by event response.
InvalidOperationException Command not allowed in current state, see Allowed device control commands.
TimeoutException Command not completed within expected time frame.
CAbortedException Execution of command overruled by event response.
CInvalidOperationException Command not allowed in current state, see Allowed device control commands.
CTimeoutException Command not completed within expected time frame.

Signal commands

Signal commands can be used to set signal values or wait for signal conditions from the command queue. The mechanism to set a signal value using the ISetSignal command is illustrated in Setting a signal relative to command execution.

Setting a signal relative to command execution

Setting a signal relative to command execution

Signal commands are blocking, i.e. the queue waits until the command is complected before continuing with the next command. The signal commands are listed below:

ISetSignal Setting a signal to a specified value
ITriggerMatchSignal Trigger for a signal match condition
IWaitMatchSignal Wait for signal match condition
ISetSignal Setting a signal to a specified value
ITriggerMatchSignal Trigger for a signal match condition
IWaitMatchSignal Wait for signal match condition

During execution of signal commands run-time errors can occur. These are errors that are not known at the moment of queuing, but occur at the start of, or during, execution of the command. The run-time errors are listed below:

ISetSignal

ResourceBusyException Signal cannot be written at this time.

ITriggerMatchSignal

InvalidArgumentException Provided invalid configuration for the signal/condition.
OutOfResourcesException No resource available for wait condition.

IWaitMatchSignal

InvalidArgumentException Provided invalid configuration for the signal/condition.
OutOfResourcesException No resource available for wait condition.
TimeoutException Timeout interval exceeded while waiting for condition.
AbortedException Execution of command aborted by Clear call on ICommandQueue.
AbortedException Execution of command aborted by high priority move command.
AbortedException Execution of command aborted by command sequence event response, see Command sequence event response.
AbortedException Execution of command aborted by Abort call on ICommandSequenceEventResponse.

ISetSignal

CResourceBusyException Signal cannot be written at this time.

ITriggerMatchSignal

CInvalidArgumentException Provided invalid configuration for the signal/condition.
COutOfResourcesException No resource available for wait condition.

IWaitMatchSignal

CInvalidArgumentException Provided invalid configuration for the signal/condition.
COutOfResourcesException No resource available for wait condition.
CTimeoutException Timeout interval exceeded while waiting for condition.
CAbortedException Execution of command aborted by Clear call on ICommandQueue.
CAbortedException Execution of command aborted by high priority move command.
CAbortedException Execution of command aborted by command sequence event response, see Command sequence event response.
CAbortedException Execution of command aborted by Abort call on ICommandSequenceEventResponse.

Miscellaneous commands

Miscellaneous commands do not fit in another of the other categories. Miscellaneous commands are blocking, i.e. the queue waits until the command is complected before continuing with the next command. The miscellaneous commands are listed below:

IWaitDuration Wait for a configurable duration
IWaitDuration Wait for a configurable duration

During execution of IWaitDuration run-time errors can occur. These are errors that are not known at the moment of queuing, but occur during execution of the command. The run-time errors for IWaitDuration are listed below:

AbortedException Execution of command aborted by Clear call on ICommandQueue.
AbortedException Execution of command aborted by high priority move command.
AbortedException Execution of command aborted by command sequence event response, see Command sequence event response.
AbortedException Execution of command aborted by Abort call on ICommandSequenceEventResponse.
CAbortedException Execution of command aborted by Clear call on ICommandQueue.
CAbortedException Execution of command aborted by high priority move command.
CAbortedException Execution of command aborted by command sequence event response, see Command sequence event response.
CAbortedException Execution of command aborted by Abort call on ICommandSequenceEventResponse.

Move commands

Move commands can be used to command motion to an axis. Move commands are blocking up to a configurable Command completion criterion. The configured criterion is used by the command queue to determine whether the next non-move command in the queue can be executed.

Command completion criterion

CommandCompletionCriterion

Description

TrajectoryStart

Command is considered finished by the queue as soon as the trajectory interpolator starts executing the trajectory following from the command.

TrajectoryComplete

Command is considered finished by the queue upon TrajectoryComplete event.

SettlingComplete

Command is considered finished by the queue upon Settling-Complete event. Not supported in combination with non-zero end velocity move commands, or when the SettlingComplete event is not supported.

StabilizingComplete

Command is considered finished by the queue upon Stabilizing- Complete event. Not supported in combination with non-zero end velocity move commands, or when the StabilizingComplete event is not supported.

Note

For grouped moves the completion criterion is met when the completion criteria of all the commands within the group are met.

In addition each move can be configured with one or more parameter sets. The configured parameter sets are applied when the command state changes to Running. If no parameter set is configured the currently active parameters are used. See chapter Parameter set for information on how to define and use parameter sets.

IMoveCommand.CompletionCriterion
IApplyParameterSet.ParameterSets
IMoveCommand::SetCompletionCriterion()
IMoveCommand::GetCompletionCriterion()
IApplyParameterSet::GetParameterSets()
IApplyParameterSet::AddParameterSet()

The move commands are listed below:

IApplyParameterSet Applies a parameter set
IJog Smooth velocity update to given velocity
ISmoothStop Smooth deceleration to zero velocity
IQuickStop State machine transition followed by quick deceleration to zero velocity
IAbsMove Absolute move to position
IRelMove Relative move with distance
IApplyParameterSet Applies a parameter set
IJog Smooth velocity update to given velocity
ISmoothStop Smooth deceleration to zero velocity
IQuickStop State machine transition followed by quick deceleration to zero velocity
IAbsMove Absolute move to position
IRelMove Relative move with distance

During execution of move commands run-time errors can occur. These are errors that are not known at the moment of queuing, but occur at the start of, or during, execution of the command. The run-time errors are listed below:

IMoveCommand base class

InvalidOperationException Axis state not Operation enabled
AbortedException Execution of command aborted by high priority move command.
AbortedException Execution of command aborted by axis control state transition.
AbortedException Execution of command aborted by command sequence event response, see Command sequence event response.

IJog

InvalidArgumentException The requested velocity is higher than the corresponding axis’ MaximumVelocity
InvalidConfigException The configured MaximumVelocity value is higher than it’s DemandVelocityLimit

IAbsMove

InvalidArgumentException The requested end velocity is higher than the corresponding axis’ MaximumVelocity
InvalidConfigException The configured end position is outside configured position limits

IRelMove

InvalidArgumentException The requested end velocity is higher than the corresponding axis’ MaximumVelocity
InvalidConfigException The calculated end position is outside configured position limits

IMoveCommand base class

CInvalidOperationException Axis state not Operation enabled
CAbortedException Execution of command aborted by high priority move command.
CAbortedException Execution of command aborted by axis control state transition.
CAbortedException Execution of command aborted by command sequence event response, see Command sequence event response.

IJog

CInvalidArgumentException The requested velocity is higher than the corresponding axis’ MaximumVelocity
CInvalidConfigException The configured MaximumVelocity value is higher than it’s DemandVelocityLimit

IAbsMove

CInvalidArgumentException The requested end velocity is higher than the corresponding axis’ MaximumVelocity
CInvalidConfigException The configured end position is outside configured position limits

IRelMove

CInvalidArgumentException The requested end velocity is higher than the corresponding axis’ MaximumVelocity
CInvalidConfigException The calculated end position is outside configured position limits

Command group

A command group encapsulates one or more commands for the axis controls in an axis control group. It is executed by the command queue of an axis control group.

Allowed commands

Only a subset of the available commands can be part of a command group. Also, there are restrictions on which commands can be used together in a command group. The following combinations are possible:

  • Combination 1

    • IOpenLoop

    • ICloseLoop

    • None, i.e. no command specified for one or more axis controls in the group.

  • Combination 2

    • IApplyParameterSet

    • IJog

    • ISmoothStop

    • IAbsMove

    • IRelMove

    • None, i.e. no command specified for one or more axis controls in the group.

  • Combination 3

    • IQuickStop. Note that a quickstop must be specified for all axis controls in the group, since a quickstop results in a transition to QuickStopActive.

In addition, the possible combinations are limited by the commands supported by the axis controls in the group.

Run exception behaviour

When starting a group command, the preconditions of each command are validated. When this fails for one sub command then all sub commands and the group command will fail:

  • The sub command that failed: Its run exception will contain the type of exception and the cause provided as text.

  • The group command: Its run exception will contain the same type of exception as the run exception of the failed subcommand. The exception text will refer to the axis that initially failed.

  • The other sub commands: The run exception will be of type aborted, and the exception text will refer to the axis that initially failed.

When one of the sub commands fails when running, e.g. a time-out on the ICloseLoop command:

  • The sub command that failed: Its run exception will contain the type of exception and the cause provided as text.

  • The group command: Its run exception will contain the same type of exception. The exception text will refer to the axis that failed. The run exeception and its status of the group command are set after all sub commands are failed or completed.

  • The other sub commands: These commands run to completion (unless configured differently, i.e. by responses).

Synchronization mode

In case the command group consists of Move commands, the motion can be synchronized by setting the Command sync mode property on the ICommandGroup.

Command sync mode

CommandSyncMode

Description

None

No synchronization of moves on different axes

Start

Synchronize start of moves on different axes

StartStop

Synchronize start and stop of moves on different axes, while respecting configured fixed ratio(s)

Full

Synchronize all phases of the highest order position derivative profile supported by the trajectory generator, of moves on different axes