Task and Program Functions

The Automation1 controller contains multiple user tasks that you can use to run AeroScript programs in a deterministic real-time context. You can configure and change the behavior of AeroScript programs through the controller parameters, Aerotech Automation1 Studio, and AeroScript functions.

Optional Purchase Necessary: The standard user tasks available to you are indexed as 1 – 4. If you purchase the Controller Plus license, the user tasks increase to 1 – 31. For drive-based controllers, the user tasks increase to 1 – 9. Contact your Aerotech sales representative to speak about your licensing needs.

Use the Manage Tasks dialog to specify the names and number of tasks that are available to execute AeroScript programs. For information about how to use this dialog to configure two or more tasks, see Tasks Category. On AeroScript programs, you can:

Load a program to a task.
Start a program.
Pause a program.
Stop a program.
Debug a program by setting breakpoints in Aerotech Automation1 Studio.
Step through a program with step into, step over, and step out functionality that you can use in Aerotech Automation1 Studio and with AeroScript functions.

Program Control

The ProgramRun() function lets you run an AeroScript program on a user task. This function puts the task into the Program Running task state. This function has the same effect as using the ProgramLoad() function followed by the ProgramStart() function.

function ProgramRun($taskIndex as integer, $controllerFileName as string)

Runs a program on the specified task.

Arguments

$taskIndex The task on which to run the program.

$controllerFileName The path, file name, and extension of the file on the controller file system to load into the controller's memory, associate to a task, and start the task.

The ProgramLoad() function lets you load an AeroScript program on a user task without causing the controller to start executing the program. This function puts the task into the Program Ready task state. In this state, you can start the execution of the program by using the ProgramStart() function.

You can also use the ProgramStart() function to cause a task in the Program Paused or Program Feedhold states to continue executing the program. And you can use the ProgramStart() function to cause a task in the Program Complete state to restart the execution of the completed program.

function ProgramLoad($taskIndex as integer, $controllerFileName as string)

Loads a program to the specified task.

Arguments

$taskIndex The task on which to load the program.

$controllerFileName The path, file name, and extension of the file on the controller file system to load into the controller's memory and to associate to a task.

function ProgramStart($taskIndex as integer)

Starts execution of a program on the specified task.

Arguments

$taskIndex The task on which to start the program.

The ProgramPause() function lets you pause the execution of an AeroScript program. If you try to pause a program while the controller is executing a program line, it will fully execute that line. Then it will pause the execution of the program. This function puts the task into the Program Paused task state.

function ProgramPause()

Pauses execution of the program.

function ProgramPause($taskIndex as integer)

Ends execution of the program on the specified task.

Arguments

$taskIndex The task on which to pause the program.

The ProgramExit() function lets you stop the AeroScript program that is executing on the current task. This function puts the task into the Program Complete task state.

The ProgramStop() function lets you stop an AeroScript program that is executing on a different task. This function unloads the program from the task. You can also issue the ProgramStop() function on the current task.

function ProgramExit()

Ends execution of the program.

function ProgramStop($taskIndex as integer)

Stops execution of a program on the specified task.

Arguments

$taskIndex The task on which to stop the program.

The ProgramReset() function lets you reset the execution of an AeroScript program to its first program line. This function puts the task into the Program Ready task state and does not automatically restart the execution of the program. To restart the execution of the program while the task is in the Program Ready task state, use one of the functions that follow:

To only restart the execution of the program, use the ProgramStart() function.
To reset the program to its first line and restart the execution, use the ProgramRestart() function. This function puts the task back into the Program Running task state.

function ProgramReset()

Resets execution of the program.

function ProgramReset($taskIndex as integer)

Resets execution of the program on the specified task.

Arguments

$taskIndex The task on which to reset the program.

The ProgramRestart() function lets you reset the execution of an AeroScript program to its first line and start the execution of the program. This function has the same effect as using the ProgramReset() function followed by the ProgramStart() function.

function ProgramRestart()

Restarts execution of the program.

To debug AeroScript programs, you can use the ProgramStepInto(), ProgramStepOut(), and the ProgramStepOver() functions.

The ProgramStepInto() function lets you execute one line of an AeroScript program. If the controller is executing a program line that is on a function call, the ProgramStepInto() function causes the controller to execute the AeroScript program until it moves to the first line of the function. Then it puts the task into the Program Paused task state.

The ProgramStepOver() function lets you execute one line of an AeroScript program. If the controller is executing a program line that is on a function call, the ProgramStepOver() function causes the controller to execute the program until it fully executes the function. Then it puts the task into the Program Paused task state.

The ProgramStepOut() function lets you execute one line of an AeroScript program. If the controller is executing a program line that is part of a function, the ProgramStepOut() function causes the controller to execute the program until it fully executes the function. Then the ProgramStepOut() function puts the task into the Program Paused task state. If the controller is executing a program line that is not part of a function, the ProgramStepOut() function causes the controller to execute the full program.

function ProgramStepInto($taskIndex as integer)

Executes one line of a program on a task, or steps one level into a function call.

Arguments

$taskIndex The task on which to execute one line of the program.

function ProgramStepOver($taskIndex as integer)

Executes one line of a program on a task, or steps one over a function call.

Arguments

$taskIndex The task on which to execute one line of the program.

function ProgramStepOut($taskIndex as integer)

Executes one line of a program on a task, or steps one level out of a function call.

Arguments

$taskIndex The task on which to execute one line of the program.

For information about how AeroScript program functions correspond to buttons in Aerotech Automation1 Studio, refer to the table that follows.

Table: Program Function Buttons

AeroScript Function	Automation1 Studio Button
`ProgramLoad()`	Load
`ProgramRun()`	Run
`ProgramPause()`	Pause
`ProgramStop()`	Stop
`ProgramStepOver()`	Step Over
`ProgramStepInto()`	Step Into
`ProgramStepOut()`	Step Out

Task Scheduling

When you run an AeroScript program, the controller tries each millisecond to execute the number of program lines specified by the ExecuteNumLines Parameter. The controller might execute fewer lines than the value specified by this parameter if one of the conditions that follow applies:

The controller is executing an AeroScript function that is non-deterministic.
The controller is executing an AeroScript function, such as the Callback() function, which requires multiple milliseconds to complete.

If you configure a task to operate in the automatic motion wait mode, either with the DefaultTaskWaitMode Parameter or the SetupTaskWaitMode() function, the controller uses the value of the ExecuteNumLinesAfterMove Parameter as an alternative to the ExecuteNumLines Parameter. The ExecuteNumLinesAfterMove parameter value determines the number of program lines to execute at the time that a move completes.

If you configure a task to operate in a critical section, the controller ignores the default behavior of the ExecuteNumLines Parameter and the ExecuteNumLinesAfterMove Parameter. As an alternative, the task continuously executes program lines until one of the conditions that follow occurs:

The task encounters a function that requires multiple milliseconds to execute.
A specified critical section timeout value is exceeded.
The task exits the critical section.

Each critical section contains:

CriticalSectionStart() function - Starts a critical section on a task.
Timeout Values - Specify a timeout value to the CriticalSectionStart() function so that the controller gives time to other operations by temporarily releasing the critical section. Do this if you want the program to execute as many lines as possible without starving the controller.
CriticalSectionEnd() function - Ends a critical section on a task.
CriticalSectionEndAll() function - Ends all the active critical sections on a task.

Critical sections are nested. You can call CriticalSectionStart() multiple times without calling CriticalSectionEnd(). Each call to CriticalSectionEnd() corresponds to the most recent call to CriticalSectionStart(). If you specify timeouts, they are applied until a new call to CriticalSectionStart() is made, or until CriticalSectionEnd() is called. If CriticalSectionEnd() is called, the previous timeout becomes active again.

function CriticalSectionStart()

Starts a critical section on the current task.

function CriticalSectionStart($timeout as integer)

Starts a critical section on the current task with a specified timeout.

Arguments

$timeout The quantity of time, in microseconds, that the task runs before it releases its time slice.

function CriticalSectionEnd()

Ends a critical section on the current task.

function CriticalSectionEndAll()

Ends all critical sections on the current task.

Advanced Task Control

Feedhold

You can use the TaskFeedholdOn() function to enable the feedhold state of the controller, which causes motion to immediately decelerate. You can use the TaskFeedholdOff() function to cause motion to accelerate back to speed. The ramp type is always linear for this acceleration and deceleration.

The state of the hardware feedhold inputs is logical ORed with the state set by the TaskFeedholdOn() function or the TaskFeedholdOff() function. The controller does not release this feedhold state until all the feedhold conditions are false. You can configure the hardware feedhold inputs and their modes of operation by using the FeedholdInput Parameter and FeedholdSetup Parameter.

The feedhold state stops the execution of programs and immediate commands. The controller continues the execution of programs and immediate commands after it releases the feedhold state.

The Feedhold Active bit of Task Status 0 changes to 1 when the motion starts to decelerate because of a feedhold until the time the motion starts to accelerate back to speed because of a feedhold release.

The Feedhold Axes Stopped bit of Task Status 1 changes to 1 when deceleration ends because of a feedhold until the time that the motion starts to accelerate back to speed because of a feedhold release.

Different motion types respond to feedhold requests as follows:

Asynchronous motion, which includes the MoveAbsolute() function, MoveFreerun() function, and so on, does not respond to feedhold requests.
Spindle motion responds to feedhold requests only if G101 command is active.
Motion produced by the MovePvt(), MovePt(), or Home() function does not respond to feedhold requests.

Follower axes, such as those commanded by gearing or camming, do not respond to feedhold requests directly, but follow the motion of the leader axis. If the controller is executing a MoveRapid() function when you issue a feedhold state, all the axes decelerate to a stop.

If the controller is executing a coordinated move function such as (MoveLinear() function, MoveCw() function, MoveCcw() function) at the time that the feedhold state is issued, the axes decelerate to a stop while maintaining the programmed path.

The feedhold state will pause programmed motion on a task. By default, a task error occurs if you try to move axes that are feedheld by a task. If you want to move axes after they have been feedheld by a task, use the TaskInterruptMotionOn() function as an alternative to the TaskFeedholdOn() function.

function TaskFeedholdOff($taskIndex as integer)

Disables software feedhold control on a task.

Arguments

$taskIndex The task on which to disable software feedhold.

function TaskFeedholdOn($taskIndex as integer)

Enables software feedhold control on a task.

Arguments

$taskIndex The task on which to enable software feedhold.

MFO

The TaskMfo() function specifies the manual feedrate override (MFO) percentage for the task and scales the programmed feedrate for the motion types that follow:

All coordinated motion, which includes the MoveLinear() function, MoveCw() function, and the MoveCcw() function.
Motion generated by the MoveRapid() function.

The MFO percentage multiplied by the programmed feedrate determines the true feedrate of the move. The MFO value can vary from the value specified in the MfoMinimum Parameter to the value specified in the MfoMaximum Parameter. If the MFO is set to a negative value, retrace mode is activated. Refer to the Retrace section of this page for more information.

MFO does not have an effect on the motion types that follow:

The MovePvt() function
The motion of camming follower axes
The motion of gearing follower axes
The camming follower axis positions
The gearing follower axis positions
Home() motion

To control the spindle speed, refer to the TaskMso() function in the MSO section of this topic.

The MFO value does not change if the MFOLock task mode is active. For more information, refer to M48 Command in the G-code and M-code Functions topic.

The controller will internally limit the MFO value if the value that you specify can cause one or more of the conditions that follow to occur:

An axis speed that exceeds the MaxSpeedClamp Parameter setting.
An axis speed in a MoveCw() or MoveCcw() move that exceeds the DefaultCoordinatedCircularAccelLimit Parameter setting.
A coordinated move duration is shorter than the CoordinatedMoveDurationMinimum Parameter setting.
The MFO is set to greater than 100% and the controller is executing a MoveRapid() move. When this occurs, the controller clamps the MFO to 100% during the MoveRapid() move.

If limiting occurs, the Limit MFO Active bit of Task Status 2 changes to 1 for the duration of the move.

The MFO does not have an effect on coordinated moves if they are in the deceleration phase, which is the end phase of the move.

During a coordinated move, the operation of an MFO change is usually delayed by a time interval in milliseconds, which is determined by the MotionUpdateRate Parameter.

If the MfoAnalogInput Parameter is enabled and configured, the controller overwrites the MFO value with the value that it gets from the specified analog input.

The controller uses programmed acceleration rates or times during all MFO changes, which include acceleration and deceleration ramping. MFO changes result in linear ramping for all ramp types, which are Linear, S-Curve, and Sinusoidal.

function TaskMfo($taskIndex as integer, $mfoPercent as real)

Sets the MFO (manual feedrate override) for a task.

Arguments

$taskIndex The task on which to set the MFO value.

$mfoPercent The MFO percentage to set.

MSO

You can use the TaskMso() function to set the manual spindle rotation speed override (MSO) for a spindle on a task. The MSO is a percentage in the range of zero to infinity, where 100 percent represents normal motion for which MSO does not have an effect. To calculate the actual spindle speed, the controller multiplies the MSO percentage by the programmed spindle speed. For information about the programmed spindle speed, refer to S Command. This override has an effect only on spindle (M3, M4, M5) motion. You cannot change the override if the MSOLock task mode is active, which is Bit 12 of TaskMode.

If the SpindleMsoInput Parameter is not set to 0, the controller overwrites the MSO value with the value that it calculates from the specified analog input. The controller determines this analog input based on the values that you configure for the SpindleMsoInput parameter. The MSO value reflects only the requested spindle rotation speed override. The MaxSpeedClamp Parameter might limit the actual rotation speed.

function TaskMso($taskIndex as integer, $msoPercent as real)

Sets the MSO (manual spindle override) for a task.

Arguments

$taskIndex The task on which to set the MSO value.

$msoPercent The MSO percentage to set.

Interrupt Motion

You can use the TaskInterruptMotionOn() function to turn on interrupt motion mode. When interrupt motion mode is on, the controller decelerates motion to a stop on all the axes that are in the specified task. After the motion comes to a stop, you can use a valid immediate command to move the axes.

To turn off interrupt motion mode, use the TaskInterruptMotionOff() function.

function TaskInterruptMotionOff($taskIndex as integer, $returnType as ReturnType)

Disables interrupt motion mode on a task.

Arguments

$taskIndex The task on which to disable interrupt motion mode.

$returnType The type used to determine how axes are returned when interrupt motion mode is disabled.

function TaskInterruptMotionOn($taskIndex as integer)

Enables interrupt motion mode on a task.

Arguments

$taskIndex The task on which to enable interrupt motion mode.

Retrace

When you activate retrace, the controller executes motion and motion-synchronized functions in reverse order, through functions that were previously executed. The controller executes coordinated motion functions in reverse, which include the MoveLinear() function, MoveCw() function, and the MoveCcw() function. When this occurs, motion retraces in reverse along the path that was made during forward execution of the program. The controller also executes in reverse order the motion that is generated by MoveRapid() functions. But because MoveRapid() moves are not coordinated motion functions, the controller does not always retrace the same path as forward execution of the program. During retrace, the controller also executes some synchronized non-motion functions.

When you activate retrace with the TaskRetraceOn() function, the controller activates feedhold on the specified task. Use the ProgramStart() function to make the controller execute motion and motion-synchronized functions in reverse order.

The controller keeps a history of moves and synchronized commands that it can use for retrace. The number of moves and synchronized commands in the retrace history is determined by the value that you specify for the MaxRetraceMoves Parameter.

Some AeroScript functions cannot be retraced. They include asynchronous motion, file operations, the Home() function, and other functions. If you execute one of these functions during normal program execution, the controller clears the retrace history. If the controller moves to the end of the retrace history during retrace, a task error occurs.

To prevent the controller from moving to the end of the retrace history and causing an error, use the TaskRetraceClearHistory() function. When retrace is active, the controller does not retrace past the TaskRetraceClearHistory() function. The controller stays on the TaskRetraceClearHistory() function until retrace is disabled. When retrace is not active, the controller ignores the TaskRetraceClearHistory() function.

function TaskRetraceClearHistory()

Defines the start of the retrace mode history and clears any existing retrace mode history.

You can also activate or deactivate retrace by setting the MFO value. If you set the MFO value to a negative value, the controller activates retrace. If you activated retrace by setting the MFO to a negative value, you can deactivate it by setting the MFO to a positive value. The MFO method of retrace is different from the TaskRetraceOn() and TaskRetraceOff() functions. This is because retrace activates and deactivates immediately and the controller does not enable the feedhold state.

Before you set MFO to a negative value, you must set the MfoMinimum task parameter to a negative value that is less than or equal to the value that you want for the MFO.

For Example

Let's say that you set the MFO value to -100%. The value of the MfoMinimum parameter must be less than or equal to -100%.

To activate retrace, call the TaskMfo() function with a negative value such as -100%. The controller immediately starts to execute the program in the reverse direction.

To deactivate retrace, call the TaskMfo() function with a positive value such as 100%. The controller immediately starts to execute the program in the forward direction.

The operations that follow can disable retrace:

If a task error occurs, the controller automatically disables retrace.
If you issue a ProgramStop(), ProgramReset(), or ProgramRestart() function, these functions cause the controller to disable retrace.
If MFO is set to a positive value. Refer to the MFO section of this page for more information.

To find the status of the retrace mode, examine the Retrace bit of the TaskStatus0 task status item. Refer to enum TaskStatus0 on AeroScript Enums.

After you disable retrace mode and run the AeroScript program, the controller executes forward through the retrace history until it moves to the program line where retrace was activated. While the controller is moving forward through the retrace history, it executes only AeroScript functions that are synchronized commands. It does not execute other types of functions. When the controller moves to the program line where retrace was activated, it executes the AeroScript program normally.

To enable or disable retrace, use one of the functions that follow.

function TaskRetraceOff($taskIndex as integer)

Disables retrace mode on a task.

Arguments

$taskIndex The task on which to disable retrace mode.

function TaskRetraceOn($taskIndex as integer)

Enables retrace mode on a task.

Arguments

$taskIndex The task on which to enable retrace mode.

Miscellaneous Task Functions

To retrieve the task index of the current task, use the function that follows.

function TaskGetIndex() as integer

Gets the index of the current task.

Returns

The index of the current task.

Restricted Task Access

You can use the TaskControlRestrict() function to restrict or allow program operations on a task. This function prevents interference on critical tasks from the buttons of Automation1 Studio, another AeroScript task, or by the .NET, C, and Python API. Aerotech recommends that you use this function with background tasks that are always running to monitor status and to handle errors, faults, and safety conditions.

function TaskControlRestrict($taskIndex as integer)

Configures a task so that program and task operations are restricted when issued from outside the running program. This function can be used to prevent a critical task from being interfered with or stopped.

Arguments

$taskIndex The task on which to restrict program operations.

function TaskControlAllow($taskIndex as integer)

Configures a task so that program and task operations are allowed when issued from outside the running program. This is the default controller behavior. This function can be used to turn off restrictions that were previously set with TaskControlRestrict().

Arguments

$taskIndex The task on which to allow program operations.

After the TaskControlRestrict() function is executed on a task, the functions and features in the list that follows are disabled on that task. When you use these features and specify a restricted task from the .NET API, C API, Python API, Automation1 Studio, or from another AeroScript task, the feature fails to execute and reports an error.

ProgramStepInto(), ProgramStepOver(), and ProgramStepOut()
TaskFeedholdOn()
TaskInterruptMotionOn() and TaskInterruptMotionOff()
TaskMfo()
TaskMso()
ProgramPause()
ProgramReset()
ProgramStop()
Retrace
Breakpoints
Command Queue
Immediate Commands
sync() function call

When you call the TaskControlRestrict() function on a task, all of the features that are disabled on that task can still be executed by the AeroScript program that is running on the restricted task. For example, you can call ProgramPause() from within a restricted AeroScript program, but you cannot pause that program from another AeroScript task or from the .NET API, C API, Python API, or Studio.

The TaskControlRestricted bit of the TaskStatus0 task status item indicates if a task is restricted. Refer to enum TaskStatus0 on AeroScript Enums.

Task Restrictions

The task restrictions are removed when one or more of the following occurs.

You issue the TaskControlAllow() function from a different task or from the AeroScript program that is running on the restricted task.
The AeroScript program that is running on the restricted task completes its execution.
A task error occurs on the restricted task.
The AeroScript program that is running on the restricted task causes an axis fault.
You reset the controller.

To make a task that cannot be stopped, you must do all of the following.

Issue the TaskControlRestrict() function.
Set the TaskTerminationAxes Parameter to 0 to prevent an axis fault from causing a task error.
In the restricted program, use an onerror statement and configure an error handling function to recover from task errors.

Go to Task Control Restriction Example Program to see an example program that uses task control restriction.