minute read

On this API page:

Commands

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

The Basics

In the Python API, Commands lets you execute AeroScript commands on the Automation1 controller. This is one of three ways that you can command your controller. You can also command it by running AeroScript programs with Tasks or by using a Command Queue in the Python API.

When you execute AeroScript commands through the Python 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 Python methods have the same blocking behavior as their AeroScript function equivalents. Thus if the AeroScript function blocks, the Python method will block too.

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

Most AeroScript commands execute on a controller task. When you execute AeroScript commands through the Python API, they will execute on Task 1 by default. To change the task on which the commands will execute, specify the optional execution_task_index argument when you call the method.

How to Use

In the Python 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 Python method that has the same arguments as the corresponding AeroScript function. To see a list of all the Python 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(axes)
controller.runtime.commands.motion.movelinear(axes, distances, coordinated_speed)
controller.runtime.commands.motion.disable(axes)

You can execute almost every AeroScript command through the Python 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 the arbitrary AeroScript that you want to execute. Refer to the example that follows.

Copy 
controller.runtime.commands.execute(aeroscript_text)

When you execute AeroScript commands through the Python API, they will execute on Task 1 by default. To change the task on which the commands will execute, specify the optional execution_task_index argument. You can specify a task by task name or task index. Refer to the example that follows.

Copy 
controller.runtime.commands.motion.enable(axes, execution_task_index)
controller.runtime.commands.motion.movelinear(axes, distances, coordinated_speed, execution_task_index)
controller.runtime.commands.motion.disable(axes)

Example Code

Copy 
# Enable the X axis. Move it 10 mm at 5 mm/s for a two-second move. Then disable it.
# All the AeroScript commands execute on Task 1, which is 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

The threading library is the only multithreading library that is officially supported by the Automation1 Python API.

All the methods that operate under the Controller.runtime.commands property are thread safe. When you use the threading library, you can call them from two or more threads without interference.

But just because the Python 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 two or more commands on the same task from different Python threads, an exception will occur.

Also, 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 Python 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

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

aeroscript_text: The AeroScript string text to compile and execute.

execution_task_index: The index of the task to execute the AeroScript command on.

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 you set the AeroScript $areturn[0] property, this method will return 0 by default.

aeroscript_text: The AeroScript string text to compile and execute.

execution_task_index: The index of the task to execute the AeroScript command on.

Returns: The value of the AeroScript $areturn[0] property after the AeroScript command has executed.

Executes an AeroScript command on the Automation1 controller on the specified task and returns an AeroScript integer value (which is an int). 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 you set the AeroScript $ireturn[0] property, this method will return 0 by default.

aeroscript_text: The AeroScript string text to compile and execute.

execution_task_index: The index of the task to execute the AeroScript command on.

Returns: The value of the AeroScript $ireturn[0] property after the AeroScript command has executed.

Executes an AeroScript command on the Automation1 controller on the specified task and returns an AeroScript real value (which is a float). 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 you set the AeroScript $rreturn[0] property, this method will return 0.0 by default.

aeroscript_text: The AeroScript string text to compile and execute.

execution_task_index: The index of the task to execute the AeroScript command on.

Returns: The value of the AeroScript $rreturn[0] property after the AeroScript command has executed.

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 you set the AeroScript $sreturn[0] property, this method will return an empty string by default.

aeroscript_text: The AeroScript string text to compile and execute.

execution_task_index: The index of the task to execute the AeroScript command on.

Return: The value of the AeroScript $sreturn[0] property after the AeroScript command has executed.

Starts a command queue on the specified task and returns a CommandQueue object to manage and add commands to the new command queue. A command queue on a task will store all of the AeroScript commands that you add to it and execute them sequentially, in the order they were added. When you add AeroScript commands to the command queue, this method does not block unless the command queue is full and the should_block_if_full argument is True. If this method does not block, the AeroScript command is added to the command queue and will execute after all of the commands that you previously added are executed. A command queue is typically used to prevent the communication latency that occurs between AeroScript commands while your motion executes with the Commands API. (For example, let's say that you use velocity blending where the communication latency will cause deceleration to occur.) The specified task can execute queued commands only 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.end_command_queue(CommandQueue) method to end the command queue and return the task to its normal state.

See Command Queue in the Python API for more information.

task: The task on which to create a command queue.

command_capacity: The maximum number of unexecuted AeroScript commands that can be stored in the command queue, after which the command queue is full.

should_block_if_full: 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 raised.

Stops the command queue on the task and returns the task to normal AeroScript execution. If an AeroScript command is currently executing, it will be aborted. All of the remaining queued AeroScript commands will be discarded. After you call this method, you cannot continue to use the specified CommandQueue object.

See Command Queue in the Python API for more information.

command_queue: The command queue to end.

milliseconds_timeout: The number of milliseconds to wait to end the command queue. If the command queue requires more than this quantity of time to end, an exception is raised. If the value of this function is set to -1, the function will wait an unspecified quantity of time for the command queue to end.