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 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_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);

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;

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 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