Commands

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

The Basics

In the C API, Commands lets you execute AeroScript commands on the Automation1 controller. This is one of three ways that you can command your controller. You can also command it by running AeroScript programs with Tasks and by using a Command Queue in the C API.

When you execute AeroScript commands through the C API, a quantity of fixed overhead occurs. When you execute two commands, one immediately after the other, there is a delay that occurs between the commands. This delay averages from 3 to 5 milliseconds, based on the performance of the PC. It also includes all the network latency delays that might occur.

IMPORTANT: If this delay is not compatible with your production environment, use Command Queue in the C API.

Command Queue lets you queue multiple commands on the controller to prevent overhead and delay. Some AeroScript commands are available only in Command Queue because they cannot accept this overhead and delay. These commands include all the AeroScript commands that require Lookahead Synchronization, such as velocity blending, cutter radius compensation, and corner rounding. If you execute a series of MovePt() or MovePvt() commands, this process also requires a command queue.

All C functions have the same blocking behavior as their AeroScript function equivalents. Thus if the AeroScript function blocks, the C function will block too.

All C functions will apply relative paths as absolute paths, which is different from their AeroScript function equivalents.

All the AeroScript commands execute on a controller task. You must select the task on which to execute the command by specifying the executionTaskIndex argument in each C function.

Tip: It is recommended that you use task 1. Task indices start at 1. Task index 0 is reserved and cannot be used.

How to Use

Commands is part of the controller runtime. Thus, the Automation1 controller must be running before you execute the commands. For more information, see the Controller page.

To execute an AeroScript command, call the C function that has the same arguments as its corresponding AeroScript function. To see a list of all the C functions that you can use for Commands, refer to the Full Reference section of this page. Some commands accept either axes or tasks. You must specify an axis by the axis index. You must specify a task by the task index.

Copy

bool Automation1_Command_Enable(Automation1Controller controller, int32_t executionTaskIndex, int32_t* axes, int32_t axesLength);
bool Automation1_Command_MoveLinear(Automation1Controller controller, int32_t executionTaskIndex, int32_t* axes, int32_t axesLength, double* distances, int32_t distancesLength, double coordinatedSpeed);
bool Automation1_Command_Disable(Automation1Controller controller, int32_t* axes, int32_t axesLength);

You can execute most of the AeroScript commands through the C API. But there might be some special cases where you want to execute custom AeroScript. If this occurs, use the Automation1_Command_Execute() function to specify arbitrary AeroScript to execute.

Copy

bool Automation1_Command_Execute(Automation1Controller controller, int32_t executionTaskIndex, const char* aeroScriptText);

Example Code

Copy

// Enable the X axis. Move it 10 mm at 5 mm/s for a two second move. Then disable it.
// Do all of this on task 1.
int32_t task1 = 1;
int32_t axisX = 0;
double distance = 10.0;
if (!Automation1_Command_Enable(controller, task1, &axisX, 1)) { /* handle error */ }
if (!Automation1_Command_MoveLinear(controller, task1, &axisX, 1, &distance, 1, 5.0)) { /* handle error */ }
if (!Automation1_Command_Disable(controller, &axisX, 1)) { /* handle error */ }

Thread Safety

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

But because the C API is thread safe, this does not mean the controller can process the AeroScript commands that you are trying to execute. A single controller task can execute only one AeroScript command at a time. Thus if you try to execute two or more commands on the same task from different C threads, an error will occur.

Also, a single axis can do motion only from one AeroScript command. Thus if you try to execute a motion command on an axis that is currently executing a previous motion command, an error will occur.

To prevent controller errors from occurring, you must synchronize or coordinate your process.

For Example

You can make a single C thread responsible for a single controller task and some number of motion axes.

Full Reference

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

Functions

> bool Automation1_Command_ExecuteAndReturnAeroScriptString(Automation1Controller controller, int32_t executionTaskIndex, const char* aeroScriptText, char* aeroScriptStringOut, int32_t aeroScriptStringLength)

Executes an AeroScript command on the Automation1 controller on the specified task and returns an AeroScript string value. To get a return value from the AeroScript command, set the value of the AeroScript $sreturn[0] property in the AeroScript command. For Example: Let's say that you set the aeroScriptText argument to "$sreturn[0]=\"HelloWorld\"". As a result, this function sets the aeroScriptStringOut argument to "HelloWorld" after the AeroScript command completes execution.

controller (In): The Automation1 controller on which to perform this AeroScript command.

executionTaskIndex (In): The index of the task on which to execute the AeroScript command.

aeroScriptText (In): The null-terminated AeroScript string text to compile and execute.

aeroScriptStringOut (Out): The null-terminated value of the AeroScript $sreturn[0] property after the AeroScript command completes execution. Use this value only if the function call was successful. This argument must have memory preallocated before you pass it into this function.

aeroScriptStringLength (In): The maximum number of elements to copy into the aeroScriptStringOut argument. This number must not be greater than the length of the aeroScriptStringOut array and must include space for the null-terminator.

Returns: True if the AeroScript command executed successfully on the controller. False if the AeroScript command did not execute on the controller. 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.