minute read

On this API page:

Commands

You are reading our Automation1 API documentation for the .NET programming language.

The Basics

In the .NET API, Commands lets you execute AeroScript commands on the Automation1 controller. You can also command your Automation1 controller by running AeroScript programs with Tasks or by using a Command Queue in the .NET API.

When you execute AeroScript commands through the .NET API, a quantity of fixed overhead occurs. There will be some delay between commands when you execute two of them, one right after the other. This delay averages from 3 to 5 milliseconds, based on the performance of the PC. It also includes all the network latency delays that might occur. If this delay is not compatible with your production environment, use Command Queue.

Command Queue lets you queue up multiple commands on the controller to prevent overhead and delay. Some AeroScript commands are available only in Command Queue because they cannot accept this overhead and delay. These commands include all the AeroScript commands that require Lookahead Synchronization, such as velocity blending, cutter radius compensation, and corner rounding. If you execute a series of MovePt() or MovePvt() commands, this process also requires a command queue. If you do not use one, your profile will stutter and drop out because of the delay that occurs between commands.

All .NET methods have the same blocking behavior as their AeroScript function equivalents. Thus if the AeroScript function blocks, the .NET method will too.

All .NET methods will apply relative paths as absolute paths, which is different from their AeroScript function equivalents.

All AeroScript commands execute on a controller task. By default, AeroScript commands executed through the .NET API will execute on task 1. You can change the task to execute on by specifying the executionTaskName argument in one of the method overloads.

How to Use

In the .NET API, Commands is part of the Controller.Runtime property. For all the APIs that operate under this property, the Automation1 controller must be running before you can execute commands. For more information about this property, see the Controller page.

To execute an AeroScript command, call the .NET method with the same arguments as the corresponding AeroScript function. To see a list of all the .NET methods that you can use for Commands, refer to the Full Reference section. Some commands accept either axes or tasks. You can specify an axis by axis name or axis index. You can specify a task by task name or task index. Refer to the example that follows.

Copy 
controller.Runtime.Commands.Motion.Enable(string axis);
controller.Runtime.Commands.Motion.MoveLinear(string axis, double distance, double coordinatedSpeed);
controller.Runtime.Commands.Motion.Disable(string axis);

You can execute almost every AeroScript command through the .NET API. But there might be some special cases where you want to execute custom AeroScript. If this occurs, use the Controller.Runtime.Commands.Execute method to specify arbitrary AeroScript to execute. Refer to the example that follows.

Copy 
controller.Runtime.Commands.Execute(string stringAeroScript);

By default, AeroScript commands that are executed through the .NET API will execute on task 1. You can change the task to execute on by specifying the executionTaskName argument. You can specify a task by task name or task index. Refer to the example that follows.

Copy 
controller.Runtime.Commands.Motion.Enable(string axis, string executionTaskName);
controller.Runtime.Commands.Motion.MoveLinear(string axis, double distance, double coordinatedSpeed, string executionTaskName);
controller.Runtime.Commands.Motion.Disable(string axis);

Example Code

Copy 
// Enable the X axis, move it 10 mm at 5 mm/s for a 2 second move, then disable it.
// All on task 1, the default task.
controller.Runtime.Commands.Motion.Enable("X");
controller.Runtime.Commands.Motion.MoveLinear("X", 10, 5);
controller.Runtime.Commands.Motion.Disable("X");

Thread Safety

All the methods that operate under the Controller.Runtime.Commands property are thread safe. You can call them from two or more threads without interference.

But because the .NET API is thread safe, this does not mean the controller can process the AeroScript commands that you are trying to execute. A single controller task can execute only one AeroScript command at a time. Thus if you try to execute multiple commands on the same task from different .NET threads, an exception will occur. Similarly, a single axis can do motion only from one AeroScript command. Thus if you try to execute a motion command on an axis that is currently executing a previous motion command, an exception will occur. To prevent controller errors from occurring, you must synchronize or coordinate your process.

For Example

You can make a single .NET thread responsible for a single controller task and some number of motion axes.

Full Reference

For more information about the methods that are available for Commands, refer to the list that follows.

Controller.Runtime.Commands Methods

Starts a command queue on the specified task and returns a new CommandQueue object to manage and add commands to the new command queue. A command queue on a task will store all AeroScript commands added to the command queue and execute them sequentially, in the order they were added. Adding AeroScript commands to the command queue does not block (unless the command queue is full and shouldBlockIfFull is true), instead the AeroScript command is added to the command queue and will be executed in the future once all previously added commands are executed. A command queue is usually used to avoid the communication latency in between AeroScript commands when executing your motion with the Commands API (such as when using velocity blending where the communication latency will cause deceleration to occur). The specified task can only execute queued commands while the command queue is active; non-queued commands from the Commands API and AeroScript programs cannot run while the command queue is active. When you are done with the command queue, use the Controller.Runtime.Commands.EndCommandQueue method to end the command queue and return the task to its normal state.

See the Command Queue in the .NET API page.

taskName: The string name of the task to start a command queue on.

commandCapacity: The maximum number of unexecuted AeroScript commands that can be stored in the command queue, after which the command queue is full. If the number of unexecuted AeroScript commands in the command queue reaches this number, the next AeroScript command added will either block until the command can be added (if shouldBlockIfFull is true) or throw a ControllerOperationException (if shouldBlockIfFull is false).

shouldBlockIfFull: Whether or not to block if you add an AeroScript command when the command queue is full. If true, the add will block until the command can be added. If false, a ControllerOperationException will be thrown.

Returns: A new CommandQueue object to manage and add commands to the new command queue on the specified task.

Stops the command queue on the task and returns the task to normal AeroScript execution. The currently executing AeroScript command, if any, will be aborted. All remaining queued AeroScript commands will be discarded. The specified CommandQueue object is no longer usable after this method is called.

See the Command Queue in the .NET API page.

commandQueue: The command queue to end.

Executes an AeroScript command on the Automation1 controller on task 1.

stringAeroScript: The AeroScript string text to compile and execute.

Executes an AeroScript command on the Automation1 controller on the specified task.

stringAeroScript: The AeroScript string text to compile and execute.

executionTaskName: The string name of the task to execute the AeroScript on.

Executes an AeroScript command on the Automation1 controller on task 1 and returns an AeroScript axis value (which is the index of the axis). To get a return value from the AeroScript command, set the value of the AeroScript $areturn[0] property in the AeroScript command. If no return value is set or the AeroScript command fails before setting the AeroScript $areturn[0] property, this method will return 0 by default.

stringAeroScript: The AeroScript string text to compile and execute.

Executes an AeroScript command on the Automation1 controller on the specified task and returns an AeroScript axis value (which is the index of the axis). To get a return value from the AeroScript command, set the value of the AeroScript $areturn[0] property in the AeroScript command. If no return value is set or the AeroScript command fails before setting the AeroScript $areturn[0] property, this method will return 0 by default.

stringAeroScript: The AeroScript string text to compile and execute.

executionTaskName: The string name of the task to execute the AeroScript command on.

Executes an AeroScript command on the Automation1 controller on task 1 and returns an AeroScript integer value (which is a 64-bit long integer). To get a return value from the AeroScript command, set the value of the AeroScript $ireturn[0] property in the AeroScript command. If no return value is set or the AeroScript command fails before setting the AeroScript $ireturn[0] property, this method will return 0 by default.

stringAeroScript: The AeroScript string text to compile and execute.

Executes an AeroScript command on the Automation1 controller on the specified task and returns an AeroScript integer value (which is a 64-bit long integer). To get a return value from the AeroScript command, set the value of the AeroScript $ireturn[0] property in the AeroScript command. If no return value is set or the AeroScript command fails before setting the AeroScript $ireturn[0] property, this method will return 0 by default.

stringAeroScript: The AeroScript string text to compile and execute.

executionTaskName: The string name of the task to execute the AeroScript command on.

Executes an AeroScript command on the Automation1 controller on task 1 and returns an AeroScript real value (which is a double-precision floating-point number). To get a return value from the AeroScript command, set the value of the AeroScript $rreturn[0] property in the AeroScript command. If no return value is set or the AeroScript command fails before setting the AeroScript $rreturn[0] property, this method will return 0.0 by default.

stringAeroScript: The AeroScript string text to compile and execute.

Executes an AeroScript command on the Automation1 controller on the specified task and returns an AeroScript real value (which is a double-precision floating-point number). To get a return value from the AeroScript command, set the value of the AeroScript $rreturn[0] property in the AeroScript command. If no return value is set or the AeroScript command fails before setting the AeroScript $rreturn[0] property, this method will return 0.0 by default.

stringAeroScript: The AeroScript string text to compile and execute.

executionTaskName: The string name of the task to execute the AeroScript command on.

Executes an AeroScript command on the Automation1 controller on task 1 and returns an AeroScript string value. To get a return value from the AeroScript command, set the value of the AeroScript $sreturn[0] property in the AeroScript command. If no return value is set or the AeroScript command fails before setting the AeroScript $sreturn[0] property, this method will return an empty string by default.

stringAeroScript: The AeroScript string text to compile and execute.

Executes an AeroScript command on the Automation1 controller on the specified task and returns an AeroScript string value. To get a return value from the AeroScript command, set the value of the AeroScript $sreturn[0] property in the AeroScript command. If no return value is set or the AeroScript command fails before setting the AeroScript $sreturn[0] property, this method will return an empty string by default.

stringAeroScript: The AeroScript string text to compile and execute.

executionTaskName: The string name of the task to execute the AeroScript command on.