minute read

On this API page:

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 method 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 
# 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()

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 method is thread safe. You can call it 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

Gets a way to change the configuration of the Automation1 controller. Configuration is what defines the behavior of the Automation1 controller. Changes to configuration usually require a controller reset before they have an effect.

See the Configuration page.

Gets a way to read and write controller files on the Automation1 controller.

See the Files page.

Gets whether the Automation1 controller has started and is currently running (that is, running AeroScript programs or performing motion). If the controller is running, you can safely access the controller's runtime components through the Controller.runtime property.

Gets the name of the connected Automation1 controller.

Gets a way to use the Automation1 controller's runtime components. Accessing this property is valid only if the controller is running. You can examine the state of the Automation1 controller with the Controller.is_running property.

Gets the serial number of the connected Automation1 controller.

Controller Methods

Connects to an Automation1 controller that is running on the specified host with the supplied username and password. Use this method to create and interact with an Automation1 controller.

host: The host name or host IP address of the Automation1 controller to connect to.

username: The username for a user that has access to the Automation1 controller.

password: The password for the specified user.

Returns: A new Controller object that represents a connection to the Automation1 controller.

Connects to an Automation1 drive-based controller that is connected to the same Windows computer over USB. Use this method to create and interact with an Automation1 drive-based controller that is connected to the same Windows computer over USB.

Returns: A new Controller object that represents a connection to the Automation1 controller.

Disconnects from the Automation1 controller. Disconnecting will not change the running state of the Automation1 controller (that is, if it has started and is running, it will remain running). After you call this method, this Controller object is no longer usable.

Resets the Automation1 controller, by putting the Automation1 controller into a fresh state and performing any initialization. The Automation1 controller will be unavailable while the reset occurs.

Starts the Automation1 controller if it is not already running. When you connect to the Automation1 controller, this process will not change the running state of the controller. Thus, use this method to start the controller after you connect. If the controller is already running, this method does nothing. You can examine the state of the Automation1 controller with the Controller.is_running property.

Stops the Automation1 controller if it is currently running. If the controller is already stopped, this method does nothing. You will stay connected to the Automation1 controller after you stop it. When you stop the Automation1 controller, this does not change your connection.

Downloads a machine controller definition (.mcd) file from the controller and saves it to the specified MDK file path. A downloaded machine controller definition file can contain both controller configuration and controller files. This file can be uploaded to any controller to copy this controller's configuration and files. When you use this function, a minimum of one of the parameters should_include_files and should_include_configuration must be true.

mdk_file_path_to_mcd: The MDK file path to save the downloaded machine controller definition (.mcd) file.

should_include_files: Whether or not controller files should be included in the download.

should_include_configuration: Whether or not controller configuration should be included in the download.

Uploads the machine controller definition (.mcd) file to the controller from the specified MDK file path. When you use this function, a minimum of one of the parameters should_include_files and should_include_configuration must be true. Before you call this function, make sure there is nothing important on the controller that can be overwritten or erased. Consider downloading a machine controller definition file as a backup before you upload a different machine controller definition file that can overwrite data.

mdk_file_path_to_mcd: The MDK file path of the machine controller definition (.mcd) file to upload.

should_include_files: Whether or not controller files should be included in the upload.

should_include_configuration: Whether or not controller configuration should be included in the upload.

erase_controller: Whether or not the controller should be erased before you upload the new files.

Controller.runtime Properties

Gets a way to execute AeroScript commands on the Automation1 controller.

See the Commands page.

Gets a way to collect data on the Automation1 controller. Data collection is a feature that gathers a set of data in a real-time, deterministic way. Data collection is different from status because status is not real-time and it is not time-series data. Status also has variable latency when you are retrieving it.

See the Data Collection page.

Gets a way to get and set active controller parameters that are in use by the Automation1 controller. Changes to active controller parameters are not persisted and the active controller parameter values are lost after a controller reset. To save changes to controller parameters permanently, use the Controller.configuration property.

See the Active Parameters page.

Gets a way to retrieve status from the Automation1 controller. Retrieved status represents a moment in time. Status is different from data collection because status is not real-time and it is not time-series data. Status also has variable latency when you are retrieving it.

See the Status page.

Gets the collection of controller tasks on the Automation1 controller, accessed by task name or task index.

See the Tasks page.

Gets a way to get and set controller variables on the Automation1 controller.

See the Controller Variables page.