Controller

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

The Basics

The .NET API revolves around the Controller class. All interaction with an Automation1 controller is through an instance of this class. To start using the .NET 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 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. Call the Controller.Connect or Controller.ConnectSecure 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.ConnectUsb 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.

Example Code

Copy

1
2
3
4
5
6
7
8
9
10
11
12
// Connect to the iSMC that is installed on this PC. You can optionally specify an IP address to connect to a remote controller.
Controller controller = Controller.Connect();
 
// Start the Automation1 controller that you are connected to, to make sure 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
21
22
23
24
// The certificate of the Automation1 controller you want to connect to 
// was obtained by using the Automation1 Console.
string expectedCertificate = "-----BEGIN 
CERTIFICATE-----\r\npkiC3jCCAcYCAQEwDQYJKoZIhvcNAQE&BQAw$TEvy$kGA1UEBhMCQ0ExEjAQ
BgNV\r\nBAoMCBblJBEsrDBjbLJdxtHGA1UEAwwJbG9jYWxob3N0MB4XETI0MDExNTA0NDg1\r\nOFoX
DTZ1MDEshifHVVHLhFmlUVyvrxXTC1UEBhMCQ0ExEjAQBgNVBAoMCWxvY2Fs\r\naG9zdDh@MBAGA1UE
AwwJbG9jYWxob3NHICLBIjANBgkqhkiG9w0BAQEFfAOCAQ8A\r\nkII+CHICAQEAxMDz3wfMhqbMy9Yf
SD0SkIpBMqvDn1GfeNY5mMk9ouEDEY+AFuwU\r\nYKMGJfwNiyc<hk9HVl7logudbao14tkwLDdp4P4W
szM+w3XwoUn0kAoAVSmpDeu9\r\nCIb3PUb5cGJU8yw/M0hJ6eAKcco/ZlqpYgDn1uHOMkzFXybjbjbj
Dd05oGTBuZfE\r\nrNNvWLI6Y+10bGQdoA6cMvyEBDZUTZp/Xkd+UwkWnJuU%$IZwfgcKTUDr226XBls
\r\naxZ2sonKHFqf9ZQuiiw1eT61vZjbWViwTVj792gCFTFvn78Msygk1Fq4H1hofL2P\r\naDXNm63A
3RM5B3GAyP8CtTBaDYCzv9mAzQIDAQABMA0GCSqGSIb3%2EBBaaAA4IB\r\nAQA0zxfHITxdI/0l12H5
pHvNmyCqice4TqAN8YFDkHcegMDpWJ+3pKy7bhtXM5tz\r\no9rrCRfBdwURRy2pjCv965oiDiak+IU2
uZ4BHjium8EIIMxLMdb+5hwojWlbsOyz\r\nXy0nlXRFyIuoB2cu59Tqc8YyDoJwAdOjzBeLqWivV/tn
l2wn85cLYme+X7/GY2G3\r\ntth897NVnhUXchGx6fJ01f+q7opodxxR2LQf4eQ16+66fEeKE1gKLke2
t9+V3LYT\r\nATjXehI04aTB32GCk6788FDVaqFrekEKzBP8fU2SHJ9ygA4iRq3viFJ8i9sSa6jr\r\n
ZLRMz7UNcyXWicQQ+taZj/5X\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 controller = Controller.ConnectSecure("192.158.1.23", 
expectedCertificate);

If the Certificate of the Controller Changes

It is possible for the Controller.ConnectSecure() 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. If the controller is not running or is in the process of resetting, an exception will be thrown. The controller runtime is different from the Controller.Configuration property, which is how you configure the behavior of the controller the next time it starts or is reset. Controller.Configuration requires you to reset the controller while Controller.Runtime changes have an immediate effect.

Controller Information

You can use the Controller.Information property to get information about the Automation1 controller to which you are connected. Refer to the example that follows.

Copy

string host = controller.Information.Host;
string controllerName = controller.Information.Name;
string serialNumber = controller.Information.SerialNumber;
Version version = controller.Information.Version;
bool isConnectionEncrypted = controller.Information.IsConnectionEncrypted;

The Controller.Information property also has some events to which you can subscribe. These events let you know when the controller is started, stopped, or reset. You can also use them to get the state of the Automation1 controller if your custom application needs to change its behavior. Refer to the example that follows.

Copy

EventHandler<ControllerEventArgs> ControllerStarted;
EventHandler<ControllerStoppedEventArgs> ControllerStopped;
EventHandler<ControllerEventArgs> ControllerReset;

Machine Controller Definition Files

Machine Controller Definition (MCD) files define an Automation1 controller. These files can include all the parameters, configuration, and files that define your motion control system. MCD files make it easy for you to back up your controller configuration, test parameter changes, and replicate a machine.

You can download and upload MCD files from the .NET API. Refer to the example that follows.

Copy

controller.DownloadMcdToFile(string mdkFilePathToMcd, bool shouldIncludeControllerFiles, bool shouldIncludeConfiguration);
controller.UploadMcdToController(string mdkFilePathToMcd, bool shouldIncludeControllerFiles, bool shouldIncludeConfiguration, bool eraseController);

For more information, see the Machine Controller Definition Files page.

Thread Safety

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

The Controller.Connect , Controller.ConnectSecure, and Controller.Disconnect methods are thread safe. You can call them from two or more threads without interference.

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 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, methods, and events that are available for Controller, refer to the lists that follow.

Controller Properties

Controller Methods

Controller.Information Properties

Controller.Information Events

Controller.Runtime Properties