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 two ways that you can command your controller. The other way to command it is by running AeroScript programs with Tasks.

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.

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

1
2
3
4
5
# 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