minute read

On this API page:

Python API Guidelines

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

This page tells you about the guidelines that you must obey to correctly use the Python API. It also includes information that is important to know when you start to write a large-scale custom application that uses the Python API.

IMPORTANT: Before you read these guidelines, make sure that you read the About the Python API page first. This page builds on that information.

The Three Controller Categories: Axis, Task, and System

The Automation1 controller is divided into three categories - axis, task, and system.

Each Automation1 controller has a fixed number of axes - 32 axes for a PC-based controller and 12 axes for a drive-based controller. The axis category consists of these axes and their configuration, parameters, and status.

Each Automation1 controller also has some number of controller tasks. The tasks can be different based on the type of controller and your license key. The task category consists of these controller tasks and their configuration, parameters, and status.

The system category consists of the Automation1 controller and its configuration, parameters, and status.

These three categories are important in the Python API because different types of information are available for each one. For example, controller parameters, status, and data collection are all divided into these categories. Each class has three different properties, one for each category:

  • axis property - A collection that is indexed by an axis name or an axis index.
  • task property - A collection that is indexed by a task name or a task index.
  • system property - The Automation1 controller is the only system. The system property does not require you to specify a system from which to get or set the parameters.

If you must specify an axis, you can use the axis name or the axis index for the axis argument, which accepts a string or integer.

If you must specify a task, you can use the task name or the task index for the task argument, which accepts a string or integer.

Errors and Exception Handling

For all error conditions, exceptions will occur. For function argument validation, TypeError and ValueError exceptions will occur.

The Python API also defines its exception types. Most Python API exceptions inherit from the ControllerException class. This class is used for all errors that are caused by the Automation1 controller. ControllerException is never raised. But one of its inherited classes is raised for specific error cases. Refer to the table that follows.

Table: Python API Exceptions Inherited from the ControllerException Class

Inherited ControllerException Class Description

ControllerArgumentException

Raised when an argument to an Automation1 function or command is not valid.

ControllerOperationException

Raised when the controller cannot execute a function or a command.

ControllerAxisAbortException

Raised when an axis abort occurs during the execution of a command.

ControllerAxisFaultException

Raised when the controller generates an axis fault during the execution of a command.

ControllerStateException

Raised when the controller cannot execute a function or a command because the controller is not in the expected state, such as stopped, running, or resetting.

ControllerCommunicationException

Raised when there is a problem communicating with the controller.

ControllerDisconnectedException

Raised when you are no longer connected to the controller.

Axis Faults and Task Errors

Python API exceptions are different from axis faults and controller task errors. An exception is raised when an error occurs. The exception represents an error in one moment in time.

But axis faults and task errors are continuous error conditions that exist on an axis or on a controller task.

For Example

If an axis moves into its end-of-travel limit, it will generate an end-of-travel limit axis fault. This axis fault stays until you acknowledge it.

If an AeroScript program divides by zero, it will cause a task error to occur on the task it was running. This task error stays until you stop the program.

An axis fault or a controller task might cause an exception to be raised.

For Example

If you execute motion on an axis and that motion causes the controller to generate an axis fault, a Python API exception will be raised.

If you execute an AeroScript command that causes a task error, a Python API exception will also be raised.

In these examples, the continuous axis fault or continuous task error caused an exception to be raised. The fault or error continues to stay after you handle the exception.

To get active axis faults and controller task errors, use Status.

Match the Python API Version with the Automation1 Controller Version

The version of the Python API that you use in your custom application must match the version of the Automation1 controller that you are connecting to.

For Example

If you want to connect to an Automation1 controller that is running version 2.2.0, then your custom application must reference and use version 2.2.0 of the Python API.

Upgrade the Python API Version for Your Custom Application

To upgrade the version of the Python API that you are using, do the steps that follow.

To Upgrade YOUR version of the Python API:

  1. Download and install the version of Automation1 to which you want to upgrade. You can download the Automation1 software from the Software Downloads page of the Aerotech website.
  2. Install the Automation1-MDKSetup.exe file. This file is part of the Automation1 software that you downloaded.

    3. Tip: This file is located in the Installation folder. See the Install the Automation1-MDK section of the Install the Software page for more information.

  3. After you install the software, restart the PC.
  4. Go to Begin a New Project. In that section, do the procedure that is specific to your machine:
    • To Install the Python API on Windows
    • To Install the Python API on Linux

    IMPORTANT: When you run the pip install command during this procedure, make sure to run it with the --upgrade flag.

For minor software versions, source compatibility is preserved in the Python API. But major software versions, such as 2.0.0, 3.0.0, or 4.0.0, might contain source compatibility changes. The release notes for each software version will tell you if there are compatibility changes.

IMPORTANT: If one or more compatibility changes occur, you must update your custom application code with the new Python API changes.

Distribute Your Custom Application

To get access to the Python API, you must install Automation1-MDK on a Microsoft Windows PC. After you build your custom application, you can distribute and run it to any supported operating system. For information about which operating systems are supported, see Supported Languages, Versions, and Operating Systems.

To run your custom application, it is not necessary to have Automation1-MDK installed. But you must have the Python API package installed with all the necessary files on your target system. For a list of the files that are required based on your operating system, see Begin a New Project.

Thread Safety

The Python API consists of thread-safe and non-thread-safe methods and properties. To learn about the thread safety of the controller features:

  • Read the documentation for each controller feature.
  • Use the threading library. It is the only multithreading library that is officially supported by the Automation1 Python API.
  • Refer to the Full References for Automation1 Python API page. This page helps you find the documentation for the controller features.

Use the Python API in a Graphical User Interface

When you use the Python API in a graphical user interface application, you must contend with these behaviors of the API:

Latency and Communication Loss - Most methods and properties in the Python API communicate with the Automation1 controller. When they communicate, latency and communication loss can occur. You can install the Automation1 controller locally. Or you can install a remote Automation1 controller on a different device. If you install the controller remotely, the communication latency is higher and will be controlled by your local area network. This communication latency can add several milliseconds of delay to these methods and properties in the Python API.

Methods That Block Until a Controller Operation Completes - Some methods in the Python API will block until a controller operation completes.

For Example

Let's say that you execute a MoveLinear() AeroScript command through the Controller.runtime.commands.motion.movelinear method. This method will block until the linear move is complete. One linear move can occur from 1 millisecond to multiple seconds.

WARNING: Because of these API behaviors, you must not call the Python API methods and properties from the UI thread. If you do this, your UI will become unresponsive while the Automation1 controller does its operation.

For more information about the problems that can occur if you call Python API methods and properties from the UI thread, refer to the use-case scenario that follows.

Use-Case Scenario - Call API Methods from the UI Thread (Not Recommended)

Let's say that you have a GUI application with a Move button that moves your X axis 10 millimeters over 5 seconds with a speed of 2 millimeters per second. You decide to call API methods from the UI thread by doing the steps that follow:

  1. You click the Move button. It executes a linear move through the Controller.runtime.commands.motion.movelinear method in the button-clicked event handler.
  2. There is also an Abort button that aborts all motion if an emergency occurs. You click this button. It executes an abort through the Controller.runtime.commands.motion.abort method in the button-clicked event handler.
  3. You click the Move button again. Because the movelinear method was executed on the UI thread, your application freezes or becomes unresponsive for 5 seconds while the MoveLinear() AeroScript command is executing. During these 5 seconds, an emergency occurs!
  4. You click the Abort button to abort all motion. But because the UI thread is blocked until the movelinear method is complete, that button cannot execute the abort method.

As referred to in the use-case scenario, it is very important for you to not block the UI thread. If you do, unsafe conditions can occur.

To Prevent Methods from Blocking the UI Thread

You must use threads or asynchronous programming. Python gives you many different ways to use them. The decision is yours. The way in which you use threads or asynchronous programming does not have an effect on how the UI thread operates. This process is always the same. The UI thread does not call methods or properties in the Python API. Instead, you must use a background thread that interacts with the Python API. This interaction keeps the UI thread responsive.

You have some options that you can use to implement threads or asynchronous programming. They are as follows:

  • Use one background thread that interacts with the Python API.
  • Spawn a new thread for each operation on the controller.

IMPORTANT: For these two options, you must read and understand the thread safety of the Python API and the operations that you are trying to do.

To learn more about threading, read the threading — Thread-based parallelism article from Python.

In the previous use-case scenario, the user blocked the UI thread by trying to call API methods from the thread. As a result, the user could not abort motion when an emergency occurred. But the user could have prevented this problem by executing the commands on new threads or Python tasks. By doing one of these options, a new use-case scenario can occur as follows.

Use-Case Scenario - Call API Methods by Spawning New Threads (Best Practice)

Let's say that you have a GUI application with a Move button that moves your X axis 10 millimeters over 5 seconds with a speed of 2 millimeters per second. You decide to call API methods by spawning a new thread for each operation on the controller by doing the steps that follow:

  1. You click the Move button. It executes a linear move through the Controller.runtime.commands.motion.movelinear method in a new thread that is spawned in the button-clicked event handler.
  2. There is also an Abort button that aborts all motion if an emergency occurs. You click this button. It executes an abort through the Controller.runtime.commands.motion.abort method in a new thread that is spawned in the button-clicked event handler.
  3. You click the Move button again. Because the movelinear method is executing on a background thread, your application stays responsive for the 5 seconds that are necessary for the command to fully execute. During these 5 seconds, an emergency occurs!
  4. You click the Abort button to abort all motion. Because each command is executing on a background thread and Commands is thread safe, the abort executes immediately. The abort stops all motion and the linear move stops.