minute read

On this API page:

Controller

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

The Basics

The C API revolves around the Automation1Controller handle. All interaction with an Automation1 controller occurs through an instance of this handle. To start using the C API, you must connect to an Automation1 controller to get an instance of an Automation1Controller handle. Then the C functions that are prefixed with Automation1_ in Automation1.h will give you access to the different features on the Automation1 controller.

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.

IMPORTANT: Most Automation1 C functions require the controller to be running.

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:

To connect to a local controller, call the Automation1_Connect() function.
To connect to a remote PC-based controller or a remote drive-based controller, call the Automation1_ConnectWithHost() function.
To connect securely to a local controller, call the Automation1_ConnectSecure() function.
To connect securely to a remote PC-based controller or a remote drive-based controller, call the Automation1_ConnectSecureWithHost() function.
To connect to a drive-based controller that is plugged into your computer over USB, call the Automation1_ConnectWithUsb() function.

Each connection type gives you an Automation1Controller handle.

Copy

bool Automation1_Connect(Automation1Controller* controllerOut);
bool Automation1_ConnectWithHost(const char* host, Automation1Controller* controllerOut);
bool Automation1_ConnectSecure(const char* expectedCertificate, Automation1Controller* controllerOut);
bool Automation1_ConnectSecureWithHost(const char* host, const char* expectedCertificate, Automation1Controller* controllerOut);
bool Automation1_ConnectWithUsb(Automation1Controller* controllerOut);

When you are done interacting with the controller, call the Automation1_Disconnect() function.

Most Automation1 C functions require the controller to be running. The documentation for each feature tells you if the controller must be running.

To see if the controller is running, use the Automation1_Controller_IsRunning() function. If the controller is not currently running, you can start it by using the Automation1_Controller_Start() function.

Copy

bool Automation1_Controller_IsRunning(Automation1Controller controller, bool* isRunningOut);
bool Automation1_Controller_Start(Automation1Controller controller);

To get information about the controller to which you are connected, use the functions that follow:

Copy

bool Automation1_Controller_Name(Automation1Controller controller, char* nameOut, int32_t nameLength);
bool Automation1_Controller_SerialNumber(Automation1Controller controller, char* serialNumberOut, int32_t serialNumberLength);
bool Automation1_Controller_IsConnectionEncrypted(Automation1Controller controller, bool* isConnectionEncryptedOut);

Example Code

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Declare the handle for the controller and the axis index of axis X.
Automation1Controller controller = NULL;
int32_t axisX = 0;

// Connect to the iSMC that is installed on this PC. You can specify an IP address to connect to a remote controller.
// Pass the address of the controller handle to populate it for future function calls.
if (!Automation1_Connect(&controller)) { /* handle error */ }

// Start the Automation1 controller to which you are connected. Do this to make sure the controller is running.
if (!Automation1_Controller_Start(controller)) { /* handle error */ }

// Because the controller is running, you can execute commands.
if (!Automation1_Command_Enable(controller, 1, &axisX, 1)) { /* handle error */ }

// 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.
// You must disconnect to free your memory.
if (!Automation1_Disconnect(controller)) { /* handle error */ }

// Set the controller handle to null because it is not valid after you disconnect from the controller.
controller = NULL;

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
// Declare the handle for the controller.
Automation1Controller controller = NULL;

// The certificate of the Automation1 controller you want to connect to 
// was obtained by using the Automation1 Console.
const char* expectedCertificate = "-----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.
if (!Automation1_ConnectSecureWithHost("192.158.1.23", expectedCertificate, 
&controller)) { /* handle error */ }

If the Certificate of the Controller Changes

It is possible for the Automation1_ConnectSecure() function call 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.

Error Handling

All the C API functions return a bool result that lets you know if the function was successful. You must examine the bool result of each function call to make sure that no error occurred. If an error does occur, you can use the Automation1_GetLastError() and the Automation1_GetLastErrorMessage() functions to get more information about it.

Copy

int32_t Automation1_GetLastError();
void Automation1_GetLastErrorMessage(char* errorMessageOut, int32_t errorMessageMaxLength);

The Automation1_GetLastError() function gives you the error number of the last error that occurred on the C thread that is currently executing.

The Automation1_GetLastErrorMessage() function gives you the string error message of the last error that occurred on the C thread that is currently executing.

C API errors are stored separately for each C thread. Each C thread tracks errors separately in the C API. You cannot get the C API error for one thread from a different thread.

A successful function call does not clear the last error. New errors will overwrite the previous errors.

Errors have error types that help keep similar errors together. In other APIs, these error types become exceptions. But in the C API, there are separate functions that you can use to determine the specific type of an error that occurs.

IMPORTANT: Automation1 error types are hierarchical. You must handle them in the correct order, which is most specific to least specific.

For Example

Make sure that you examine the error number to see if an error is a ControllerCommunication error type before you examine it to see if the error is a Controller error type.

See the Errors and Error Handling section in C API Guidelines for more information.

Example Code

Copy

1
2
3
4
5
6
7
8
9
Automation1Controller controller;
if (!Automation1_Connect(&controller))
{
    int32_t lastError = Automation1_GetLastError();
    char lastErrorMessage[2048];
    Automation1_GetLastErrorMessage(lastErrorMessage, 2048);

    // Print or log the error, clean up, change your process, etc.
}

Machine Controller Definition Files

Machine Controller Definition (MCD) files are files that 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 Machine Controller Definition (MCD) files from the C API.

Copy

bool Automation1_Controller_DownloadMcdToFile(Automation1Controller controller, const char* mdkFilePathToMcd, bool shouldIncludeFiles, bool shouldIncludeConfiguration);
bool Automation1_Controller_UploadMcdToController(Automation1Controller controller, const char* mdkFilePathToMcd, bool shouldIncludeFiles, bool shouldIncludeConfiguration, bool eraseController);

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

Thread Safety

The Automation1_Connect and Automation1_ConnectSecure functions are thread safe. You can call them from two or more threads without interference.

The Automation1Controller handle is thread safe. But some of the functions that accept this handle are not thread safe. Read the thread safety documentation for each C API function.

The Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions are thread safe. C API errors are stored separately for each C thread. Each C thread tracks errors separately in the C API.

The Automation1_Disconnect() function is not thread safe. Use only one thread to call this function for a single Automation1Controller handle.

The Automation1_Controller_Start(), Automation1_Controller_Stop(), and Automation1_Controller_Reset() functions are not thread safe. Only one thread at a time can call these functions. If it is necessary for two or more threads to call these functions, you must use locks to limit the access.

The Automation1_Controller_DownloadMcdToFile() and Automation1_Controller_UploadMcdToController() functions are not thread safe. Only one thread at a time can call these functions. If it is necessary for two or more threads to call these functions, you must use locks to limit the access.

All the other Automation1_Controller_ functions are thread safe. You can call them from two or more threads without interference.

Full Reference

For more information about the functions that are available for Controller, refer to the list that follows.

Functions

> bool Automation1_ConnectSecureWithUser(const char* userName, const char* password, const char* expectedCertificate, Automation1Controller* controllerOut)

Connects securely to an Automation1 controller, using the specified user name and password. Use this overload to log in securely to a controller when the controller is installed on the same computer and has access control enabled. You must specify the controller's certificate because the certificate is used to verify the authenticity of the controller and is used to establish the secure connection. 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 Automation1 controller's certificate does not match the expectedCertificate, this function will not connect and will return false. Make sure to call the Automation1_Disconnect() function to prevent memory from leaking when you are done with the controller. Do a check to make sure that communication over your current connection is encrypted. Call the Automation1_Controller_IsConnectionEncrypted() function.

userName (In): The null-terminated user name for a user with access to the Automation1 controller.

password (In): The null-terminated password for the specified user.

expectedCertificate (In): The null-terminated certificate used to verify the authenticity of the Automation1 controller.

controllerOut (Out): A handle that represents a secure connection to an Automation1 controller. Use this handle only if the function call was successful.

Returns: True if the connection was successful. False if the connection was not successful. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

> bool Automation1_ConnectSecureWithHostAndUser(const char* host, const char* userName, const char* password, const char* expectedCertificate, Automation1Controller* controllerOut)

Connects securely to an Automation1 controller running on the specified host, using the specified user name and password. Use this overload to log in to a controller securely when the controller is installed on a different computer and has access control enabled. You must specify the controller's certificate because the certificate is used to verify the authenticity of the controller and is used to establish the secure connection. 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 Automation1 controller's certificate does not match the expectedCertificate, this function will not connect and will return false. Make sure to call the Automation1_Disconnect() function to prevent memory from leaking when you are done with the controller. Do a check to make sure that communication over your current connection is encrypted. Call the Automation1_Controller_IsConnectionEncrypted() function.

host (In): The null-terminated host name or host IP address of the Automation1 controller to connect to.

userName (In): The null-terminated user name for a user with access to the Automation1 controller.

password (In): The null-terminated password for the specified user.

expectedCertificate (In): The null-terminated certificate used to verify the authenticity of the Automation1 controller.

controllerOut (Out): A handle that represents a secure connection to an Automation1 controller. Use this handle only if the function call was successful.