About the C API

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

The C API for Automation1 lets you develop custom applications written in C or C++ to interact with an Automation1 controller. With the C API, you can connect to a controller to get status, execute commands, run your process, and more.

Throughout this documentation, the term C API refers to the Automation1 C API by Aerotech. The term C refers to the C programming language.

The C API is packaged with Automation1-MDK. After you install Automation1-MDK, you can find the C API installed under C:\Program Files\Aerotech\Automation1-MDK\APIs\C.

The C API is available as a dynamic library for 32-bit and 64-bit Windows. It is also available as a shared object for 64-bit x64 Linux.

Some example programs are also installed with Automation1-MDK. They are installed under C:\Program Files\Aerotech\Automation1-MDK\Examples\C and will demonstrate how to interact with an Automation1 controller through the C API. They show common features and use-cases in ways that are easy to understand. They also show you how to create Visual Studio projects for the Windows version of the C API.

Supported Languages, Versions, and Operating Systems

The C API exposes a C99 interface. You can also use versions of C++ that are compatible with C99.

When you use Microsoft Visual Studio, Aerotech recommends that you use Visual Studio 2019 or newer.

The operating systems that follow are supported:

Windows 10 32-bit or Windows 11 32-bit
Windows 10 64-bit or Windows 11 64-bit
Debian 10 64-bit x64

The C API first became available for Windows in Automation1 version 1.2 and Linux in Automation1 version 2.0. For more information about API versioning, see the Automation1 APIs page.

On Windows, the Microsoft Visual C++ Redistributable 2019 or newer is required. This redistributable is installed with Automation1-MDK. If you run your custom application on a PC that does not have Automation1-MDK installed, then you must install the redistributable manually.

A 64-bit x64 Linux operating system with one of the configurations that follow might be compatible but is not supported:

GLIBC 2.28 or newer
GLIBCXX 3.4.25 or newer
Libsodium 1.0.17 or newer

Begin a New Project

After you install Automation1-MDK, you can find the C API installed under C:\Program Files\Aerotech\Automation1-MDK\APIs\C.

The C API is available as a dynamic library for 32-bit and 64-bit Windows. It is also available as a shared object for 64-bit x64 Linux.

The C API has some header files that are required for you to build your project. They are installed under C:\Program Files\Aerotech\Automation1-MDK\APIs\C\Include. The Automation1.h header file is the main header file. But all the other header files in this folder are required so you can build custom applications. You must configure your C project to reference the header files from this folder.

IMPORTANT: Make sure that your C code files include only the Automation1.h header file. Do not include other Automation1 header files.

The C API has some library files that are required to build and run a custom C application. They are as follows:

Library\Windows\x86\Automation1C.dll
Library\Windows\x86\Automation1C.lib
Library\Windows\x86\Automation1Compiler.dll
Library\Windows\x64\Automation1C64.dll
Library\Windows\x64\Automation1C64.lib
Library\Windows\x64\Automation1Compiler64.dll
Library\Linux\x64\libautomation1c.so
Library\Linux\x64\libautomation1compiler.so

When you build an application, the files required for the application will depend on your runtime operating system.

The DLL and LIB files are Windows dynamic libraries for 32-bit and 64-bit Windows. You must configure your C project to link against the LIB files. The DLL files are required at runtime. You must copy these DLL files with your custom application. Typically, you copy them into the directory that has the executable file (.exe) for your custom application.

libautomation1c.so and libautomation1compiler.so are shared objects for Linux. You must configure your C project to link against the libautomation1c.so file. If your custom application runs on Linux, these files are required at runtime. You must install them on your Linux operating system or add them to LD_LIBRARY_PATH.

Write Code Against the C API

Before you write code, you must access the C API by including the Automation1.h header file. Make sure that your C code files include only the Automation1.h header file. Do not include other Automation1 header files. You can access all the C API types and functions through this header file. After you include the header file, you can begin to do work with an Automation1 controller.

The C API revolves around the Automation1Controller handle and C functions that are prefixed with Automation1_ and accessible through Automation1.h. You can use these functions to access all the controller features.

To get an instance of an Automation1Controller handle, you must connect to an Automation1 controller. There are some functions that will connect to an Automation1 controller and give you an Automation1Controller handle. Refer to the example that follows:

Copy

Automation1Controller controller;
Automation1_Connect(&controller);

You can also connect securely to an Automation1 controller by using the Automation1_ConnectSecure function.

For more information about the Automation1Controller handle, see the Controller page.

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

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

For more information, read the pages that follow for the features that you want to use:

Status - Get information about what your controller is currently doing.
Data Collection - Collect a snapshot of real-time, deterministic data over a period of time.
Commands - Execute AeroScript commands on your controller.
Tasks - Run and manage your AeroScript programs.

Principles of the C API

C Version: The C API exposes a C99 interface. You can also use versions of C++ that are compatible with C99.
Documentation: Each function is fully documented in the Automation1 C API header files. You can also access in-code documentation for the C API through the auto-complete features of an editor that supports it.; The C API headers are installed under C:\Program Files\Aerotech\Automation1-MDK\APIs\C\Include.
Functions and Typedefs: You can access all the functions and typedefs through the Automation1.h header file. To get access to these functions and typedefs from the C API, you must include this header file. Do not include other Automation1 header files.
Connect to an Automation1 Controller: Each instance of the Automation1Controller handle represents one connection to one controller:; To connect to a local controller, call the Automation1_Connect() or Automation1_ConnectSecure() functions. These function give you an Automation1Controller handle.; To connect to a remote PC-based controller or a remote drive-based controller, call the Automation1_ConnectWithHost() or Automation1_ConnectSecureWithHost() functions. These function give you an Automation1Controller handle.; To connect to a drive-based controller that is plugged into your computer through USB, call the Automation1_ConnectWithUsb() function. This function gives you an Automation1Controller handle.; You can connect to one or more 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.; When you connect an Automation1 controller, this process does not automatically start it. When you disconnect a controller, this process does not stop it.; When you complete your work with a controller, you must disconnect from it so you can free your memory.
Features: In the Automation1.h header file, you can access all the C API features through functions that are prefixed with Automation1_. These functions must have an Automation1Controller handle to a connected controller.; For Example: To get information about what your controller is currently doing, use the Automation1_Status_GetResults() function.
Status and Information Updates: To get status and information updates, you must poll the controller. See the Status page for more information.; There are no events for errors and axis faults.
Axes: When you must specify an axis, you must use the axis index. The C API does not support axis names. You can use the Automation1_Controller_GetAxisIndexFromAxisName() function to get the axis index for an axis name.
Tasks: When you must specify a task, you must use the task index. The C API does not support task names. You can use the Automation1_Controller_GetTaskIndexFromTaskName() function to get the task index for a task name.

C 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 that you are connected to. 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 the controller to free your memory.
if (!Automation1_Disconnect(controller)) { /* handle error */ }

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

About the C API

Supported Languages, Versions, and Operating Systems

Begin a New Project

Write Code Against the C API

Principles of the C API

C Example Code

More Reading