About the Python API

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

The Python API for Automation1 lets you develop custom applications written in Python to interact with an Automation1 controller. With the Python API, you can connect to a controller to get status, execute commands, run your process, and more.

Throughout this documentation, the term Python API refers to the Automation1 Python API by Aerotech. The term Python refers to the Python programming language.

The Python API is packaged with Automation1-MDK. After you install Automation1-MDK, you can find the Python API installed under C:\Program Files\Aerotech\Automation1-MDK\APIs\Python.

Some example programs are also installed with Automation1-MDK. They are installed under C:\Program Files\Aerotech\Automation1-MDK\Examples\Python and will demonstrate how to interact with an Automation1 controller through the Python API. They show common features and use-cases in ways that are easy to understand. They also show you how to create simple scripts that use the Python API to talk to an Automation1 controller.

Supported Languages, Versions, and Operating Systems

The Python API supports Python version 3.8.10 and newer.

The operating systems that follow are supported:

Windows 10 32-bit or Windows 11 32-bit
Windows 10 64-bit or Windows 11 64-bit
Debian 10 64-bit x64

The Python API first became available for Windows and Linux in Automation1 version 2.4. For more information about API versioning, see the Automation1 APIs page.

A 64-bit x64 Linux operating system with one of the configurations that follow might be compatible but is not supported:

GLIBC 2.28 or newer
GLIBCXX 3.4.25 or newer
Libsodium 1.0.17 or newer

Begin a New Project

After you install Automation1-MDK, you can find the Python API installed under C:\Program Files\Aerotech\Automation1-MDK\APIs\Python.

The Automation1 Python API is a Python package that you can install by using the package manager pip.

To install the Python API on Windows

Run the pip install command that follows:

Copy

pip install "C:\Program Files\Aerotech\Automation1-MDK\APIs\Python\automation1"

IMPORTANT: If you are upgrading the Python API version for your custom application, make sure to run the pip install command with the --upgrade flag.

To install the Python API on Linux

Navigate to "C:\Program Files\Aerotech\Automation1-MDK\APIs\Python\automation1". Then copy the "automation1" folder to your Linux machine.
Navigate to "C:\Program Files\Aerotech\Automation1-MDK\APIs\C\Library\Linux\x64". Then copy all the shared object files to a new folder your Linux machine.
Configure the LD_LIBRARY_PATH environment variable to point to the folder with the shared object files from Step 2.
Navigate to the folder from Step 1 that contains the "automation1" folder. This is the parent folder of the "automation1" folder. Then open a new Unix Terminal.
Run the pip install command that follows:

Copy

pip install "./automation1"

IMPORTANT: If you are upgrading the Python API version for your custom application, make sure to run the pip install command with the --upgrade flag.

Write Code Against the Python API

Before you write code, you must access the Python API by importing the automation1 package. All the Python API types are in this package. It is the only package that you must import to use the Python API. After you import the package, you can begin to do work with an Automation1 controller. Refer to the example that follows.

Copy

import automation1 as a1

The Python API revolves around the Controller class. You can access all the controller features through an instance of this class. Typically, it is not necessary for you to construct objects in the Python API. Instead, you access features through properties on the Controller object.

The example that follows shows you how to get information about what your controller is currently doing.

Copy

controller.runtime.status.get_status_items(...)

To get an instance of a Controller object, you must connect to an Automation1 controller. There are static methods on the Controller class that will connect to an Automation1 controller and return a Controller object.

The example that follows shows you how to connect to a locally installed PC-based controller.

Copy

controller = a1.Controller.connect()

You can also connect securely to an Automation1 controller by using the static Controller.connect_secure method.

For more information about the Controller class, see the Controller page. Then read the pages for the features that you want to use:

Status - Get information about what your controller is currently doing.
Data Collection - Collect a snapshot of real-time, deterministic data over a period of time.
Commands - Execute AeroScript commands on your controller.
Tasks - Run and manage your AeroScript programs.

Principles of the Python API

Documentation: You can access in-code documentation for the Python API through the auto-complete features of an editor that supports it.
Types (Classes and Enums): All types, which are classes and enums, are in the automation1 package namespace. To get access to these types from the Python API, you must import this package.
Connect to an Automation1 Controller: Each instance of the Controller class represents one connection to one controller.; Use the static Controller.connect or Controller.connect_secure methods to connect to an Automation1 controller.; You can connect to one or more Automation1 controllers at the same time in the same custom application. You can also connect to the same Automation1 controller multiple times at the same time.; When you connect an Automation1 controller, this process does not automatically start it. When you disconnect a controller, this process does not stop it.
Features: You can access all the Python features through an instance of the Controller class. This class also has properties that you can use to access all the controller features.; For Example: To get information about what your controller is currently doing, use the Controller.runtime.status property.; The Controller.runtime property represents features that you can access only if the controller is started and running.
Objects and Classes: Typically, it is not necessary for you to construct objects in the Python API.; You can access controller features through properties on the Controller class. Use the static Controller.connect or Controller.connect_secure methods to get an instance of this class.; The configuration objects StatusItemConfiguration and DataCollectionConfiguration are the only classes that you must construct.
Status and Information Updates: To get status and information updates, you must poll the controller. See the Status page for more information.
Axes: When you must specify an axis, you can use the axis name or the axis index.
Tasks: When you must specify a task, you can use the task name or the task index.

Python Example Code

This code is written in Python.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import automation1 as a1

# Connect to the iSMC that is installed on this PC. You can use the "host" keyword argument 
# to specify an IP address and connect to the remote controller.
controller = a1.Controller.connect()

# Start the Automation1 controller to which you are connected. Do this to make sure the 
# controller is running.
controller.start()

# Because the controller is running, you can access the Controller.runtime property.
controller.runtime.commands.motion.enable("X")

# Disconnect from the controller when you are done interacting with it.
# When you disconnect the controller, this process does not stop the controller. 
# The controller continues to run.
controller.disconnect()

For more information and examples, see the Controller page.

About the Python API

Supported Languages, Versions, and Operating Systems

Begin a New Project

Write Code Against the Python API

Principles of the Python API

Python Example Code

More Reading