Controller

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

The Basics

The Python API revolves around the Controller class. All interaction with an Automation1 controller occurs through an instance of this class. To start using the Python API, you must connect to an Automation1 controller to get an instance of the Controller class. Then the properties on this class will give you access to the various Automation1 controller features.

When you connect to a controller, this process does not automatically start it. You can connect to a non-running Automation1 controller without starting it.

When you disconnect a controller, this process does not stop a controller that is currently running.

The Controller.runtime property represents features that you can access only if the controller is started and running. For more information, refer to the Controller Runtime section below.

You can connect to many 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.

How to Use

You can connect to multiple controllers at the same time, or connect to the same controller multiple times. There are different ways to connect:

Call the Controller.connect or Controller.connect_secure methods to connect to a specific controller, either a locally installed PC-based controller, a remote PC-based controller, or a remote drive-based controller.
Call the Controller.connect_usb method to connect to a drive-based controller that is plugged into your computer over USB.

When you are done interacting with the controller, call the Controller.disconnect method from the controller instance.

Example Code

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Import the Automation1 Python API package. For convenience, import this package as “a1”.
import automation1 as a1

# Connect to the iSMC that is installed on this PC. If you want to connect to a remote controller
# on a different PC, specify an IP address.
controller = a1.Controller.connect()

# Start the controller to which you are connected to make sure that it is running.
controller.start()

# With the controller running, you can access the 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 does not stop it. The controller will continue to run.
controller.disconnect()

Connect to the Controller Securely

IMPORTANT: After you read this section, make sure to read the Securing Your Automation1 Controller page.

Automation1 supports secure communication between the iSMC and your custom application. This connection is authenticated and encrypted (with TLS). Aerotech recommends that you use secure communication for remote connections over Ethernet. A secure connection has a small increase to communication latency on the order of 10s of microseconds. For most applications, this latency will not have an effect on performance.

Each Automation1 controller has a unique digital certificate for authentication. To establish secure communications with an Automation1 controller, you must first get the certificate of the controller. The first time that you connect, you can get it through a private channel or by using a process named trust-on-first-use. To make sure that you connect to the correct controller and get the correct certificate, Aerotech recommends that you connect over a private channel. To do this, use one of the methods that follow:

For drive-based controllers, connect over USB.
For PC-based controllers, connect locally on the same PC.

Subsequent connections will use this certificate to authenticate the connection. They might also use Ethernet.

Example Code - Connect Securely to an Automation1 Controller

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# The certificate of the Automation1 controller you want to connect to 
# was obtained by using the Automation1 Console.
expected_certificate = "-----BEGIN 
CERTIFICATE-----\r\nMIICLzCCAbUCA22eWzAKBggqhkjOPQQDBDCBgjELMAkGA1UEBhMCVVMxFTA
TBgNV\r\nBAgMDFBlbm5zeWx2YW5pYTETMBEGA1UEBwwKUGl0dHNidXJnaDERMA8GA1UECgwI\r\nQW
Vyb3RlY2gxFDASBgNVBAsMC0F1dG9tYXRpb24xMR4wHAYDVQQDDBVBdXRvbWF0\r\naW9uMUNvbnRyb
2xsZXIwIBcNMjQwOTE3MTMyMDM4WhgPMjA5MjEwMDUxNjM0NDVa\r\nMIGCMQswCQYDVQQGEwJVUzEV
MBMGA1UECAwMUGVubnN5bHZhbmlhMRMwEQYDVQQH\r\nDApQaXR0c2J1cmdoMREwDwYDVQQKDAhBZXJ
vdGVjaDEUMBIGA1UECwwLQXV0b21h\r\ndGlvbjExHjAcBgNVBAMMFUF1dG9tYXRpb24xQ29udHJvbG
xlcjB2MBAGByqGSM49\r\nAgEGBSuBBAAiA2IABB6Ohr6gzOTyKxs13AgTqqYCg3XQID89Etd+qHxS+
UUfRA4I\r\nbUnpDPQiieAnkHpI0cbeIuLO1Gg0/xjoGGkVamqraWNuS2kG9256Tq8T6tKSzT+j\r\n
qGDZVbkwqKDeJ5T/bDAKBggqhkjOPQQDBANoADBlAjBAspPj8M/GgfgyY3Hr0tgb\r\n+VZq1VsWett
4yziQ7uxmAFXFu68jnkL6GsrPdebQ2hkCMQC/LAp5ZEWKgJ7XCq/V\r\nprSqOzdeXkvByljqpQa5af
O0zadJ1/2UXYzWHgCLxmAdy1g=\r\n-----END CERTIFICATE-----";

# Connect securely to the iSMC on a remote controller with example IP address 
# 192.158.1.23.
# After you establish a secure connection, you can use the controller as normal.
controller = a1.Controller.connect_secure(host="192.158.1.23", 
expected_certificate=expected_certificate)

If the Certificate of the Controller Changes

It is possible for the Controller.connect_secure() method to not connect because the controller cannot be authenticated. If this occurs, the expected certificate that you passed in is no longer valid for the controller to which you are trying to connect.

If you passed in the correct certificate, this might have occurred because you or an administrator manually regenerated the certificate of the controller. If this is true, you must update the certificate you are passing in to the new one. For information about how to get the certificate of a controller, refer to the steps of the To Manually Get the Certificate of a Controller procedure.

If the certificate was not manually generated, it is possible that you are not connecting to the correct controller or the controller is compromised. You or an administrator must connect to the controller. For PC-based controllers, use a local connection. For drive-based controllers, use a USB connection. Then manually regenerate the certificate of the controller. For information about how to do this, see To Regenerate the Certificate of a Controller.

Controller Runtime

The Controller.runtime property represents features that you can access only if the controller is started and running. When you make changes to this property, they have an immediate effect.

WARNING: If the controller is not running or is in the process of resetting, do not try to access the Controller.runtime property. If you do, an exception will be raised.

The Controller.configuration property lets you configure the behavior of the controller the next time that it starts or is reset. When you make changes to this property, you must reset the controller for them to have an effect.

Thread Safety

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

The Controller.is_running property is thread safe. You can call it from two or more threads without interference.

The Controller.connect and Controller.connect_secure methods are thread safe. You can call them from two or more threads without interference.

The Controller.disconnect method is not thread safe. Call this method from one thread only.

The Controller.start, Controller.stop, and Controller.reset methods are not thread safe. Only one thread at a time can call these methods. If it is necessary for two or more threads to call these methods, you must use locks to limit the access.

For all the other properties on the Controller class, see their respective reference pages for information about their thread safety.

Full Reference

For more information about the properties and methods that are available for Controller, refer to the lists that follow.

Controller Properties

Controller Methods

Controller.runtime Properties