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, each millisecond the controller tries 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

Advanced task control includes feedhold, interrupt motion, manual feedrate override (MFO), manual spindle rotation speed override (MSO), and retrace.

Feedhold

Feedhold lets a task pause the execution of programs and immediate commands while decelerating all axes to a stop along the programmed path. When this occurs, the task enters the feedhold state. When the feedhold state is released, all programs and immediate commands continue from where they were paused. A task error occurs if you try to move axes that are in a feedhold state. If you want to move axes when they are in a feedhold state, use Interrupt Motion.

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 with the FeedholdInput Parameter and FeedholdSetup Parameter.

When feedhold is first turned on:

  • The Feedhold Active bit of the TaskStatus0 task status item is 1 when motion starts to decelerate because of feedhold.

  • The Feedhold Axes Stopped bit of TaskStatus1 task status item is 1 when motion finishes decelerating because of feedhold.

Both the Feedhold Active and the Feedhold Axes Stopped bits are 1 until feedhold is turned off.

Feedhold has an effect on the types of motion that follow:

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

  • PVT and PT Motion: MovePvt() and MovePt() functions.

  • Home Motion: Home() and HomeAsync() functions.

  • Follower axes commanded by gearing or camming. These axes follow the motion of the leader axis.

Use the TaskFeedholdOn() function to enable the feedhold state of the controller, which causes motion to immediately decelerate. The ramp type is always linear for accelerations into and decelerations out of feedhold.

function TaskFeedholdOn($taskIndex as integer)

Enables software feedhold control on a task.

Arguments

$taskIndex  The task on which to enable software feedhold.

Use the TaskFeedholdOff() function to cause motion to accelerate back to speed. The ramp type is always linear for accelerations into and decelerations out of feedhold.

function TaskFeedholdOff($taskIndex as integer)

Disables software feedhold control on a task.

Arguments

$taskIndex  The task on which to disable software feedhold.

Interrupt Motion

Interrupt motion lets a task pause the execution of programs and immediate commands while it decelerates all axes to a stop along the programmed path. You can use an immediate command to move the axes after motion stops. You can see the status of interrupt motion with the InterruptMotionActive bit in the TaskStatus0 task status item.

Interrupt motion works with the types of motion that follow:

Interrupt motion does not work with the types of motion that follow:

  • PVT and PT Motion: MovePvt() and MovePt() functions.

  • Home Motion: Home() and HomeAsync() functions.

  • Follower axes commanded by gearing or camming. These axes follow the motion of the leader axis

Use the TaskInterruptMotionOn() function to turn on interrupt motion mode.

function TaskInterruptMotionOn($taskIndex as integer)

Enables interrupt motion mode on a task.

Arguments

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

Use the TaskInterruptMotionOff() function to turn off interrupt motion mode.

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.

enum ReturnType
   Interrupt = 1
   Offset = 2
end

Manual Feedrate Override (MFO)

The Manual Feedrate Override (MFO) percentage scales the programmed feedrate on a task. To calculate the feedrate of a move, the controller multiplies the MFO percentage by the programmed feedrate. The range of MFO values you can set must be between the value specified by the MfoMinimum Parameter to the value specified in the MfoMaximum Parameter. If the MFO is set to a negative value, Retrace mode is activated. To control the spindle speed, refer to the TaskMso() function in the Manual Spindle Rotation Speed Override (MSO) section.

Before you use MFO, make sure that you know the important information that follows: 

  • You cannot change the MFO value if the MFOLock task mode is active. For more information, refer to Manual Feedrate Override (MFO) Configuration.

  • 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, 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.

MFO works with the types of motion that follow.

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

  • PVT and PT Motion: MovePvt() and MovePt() functions.

  • Home Motion: Home() and HomeAsync() functions.

  • Follower axes commanded by gearing or camming. These axes follow the motion of the leader axis.

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

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

Use the TaskMfo() function to specify the MFO percentage and scale the programmed feedrate for a task.

To disable MFO on a task, set the MFO to 100% with the TaskMfo() function. This is the default MFO value on all tasks.

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.

Manual Spindle Rotation Speed Override (MSO)

Use the manual spindle rotation speed override (MSO) percentage to manually set the rotation speed of a spindle on a task. To calculate the actual spindle speed, the controller multiplies the MSO percentage by the programmed spindle speed. The MSO value can range from zero to infinity, where setting MSO to 100 percent has no effect on the programmed spindle speed. For information about the programmed spindle speed, refer to S Command on the G-Code Programming page.

Before you use MSO, make sure that you understand the important information that follows: 

  • You cannot change the MSO value if the MFOLock task mode is active. For more information, refer to Manual Spindle Override (MSO) Configuration.

  • The MSO only has an effect on spindle motion (M3, M4, M5).

  • 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 calculates this analog input based on the values that you configure for the SpindleMsoInput parameter. The MSO value represents only the requested spindle rotation speed override. The MaxSpeedClamp Parameter can limit the actual rotation speed.

Use the TaskMso() function to specify the MSO percentage and scale the programmed spindle speed for a task.

To disable MSO on a task, set the MSO to 100% with the TaskMso() function. This is the default MSO value on all tasks.

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.

Retrace

Retrace lets a task re-execute previously executed motion and motion-synchronized functions in reverse order. Each task keeps its own history of moves, storing the most recent number of moves and synchronized commands up to the value specified by the MaxRetraceMoves Parameter. Some moves and AeroScript functions cannot be retraced. 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 find the status of the retrace mode, examine the Retrace bit in the TaskStatus0 task status item.

Unless explicitly noted in the lists that follow, the move or motion-synchronized function does not support retrace and will clear retrace history.

The types of moves that follow can be retraced.

  • Coordinated Motion: MoveLinear(), MoveCw(), and MoveCcw() functions.

  • Rapid Motion: MoveRapid() function. Because MoveRapid() moves are not coordinated motion functions, the controller does not always retrace the same path as forward execution of the program.

  • Delay Motion: MoveDelay() function.

The motion-synchronized functions that follow can be retraced:

  • Dwell()

  • SetupAxisRampType(), SetupAxisRampValue(), and SetupAxisSpeed()

  • SetupCoordinatedRampType(), SetupCoordinatedRampValue(), and SetupCoordinatedSpeed()

  • SetupDependentCoordinatedRampRate()

  • AnalogOutputSet()

  • DigitalOutputSet()

  • VirtualBinaryInputSet(), VirtualBinaryOutputSet(), VirtualRegisterInputSet(), and VirtualRegisterOutputSet()

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 try to 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 activate retrace with the TaskRetraceOn() function. This activates feedhold on the specified task. You can then use the ProgramStart() function to make the controller execute only motion and motion-synchronized functions in reverse order starting from the program line that the specified task was executing.

function TaskRetraceOn($taskIndex as integer)

Enables retrace mode on a task.

Arguments

$taskIndex  The task on which to enable retrace mode.

You can deactivate retrace with the TaskRetraceOff() function. This causes the controller to execute only motion and motion-synchronized functions in forward order through retrace history until it moves to the program line where retrace was activated on the specified task. It does not execute other types of functions. When the controller moves back to the program line where retrace was activated, it executes the AeroScript program normally.

function TaskRetraceOff($taskIndex as integer)

Disables retrace mode on a task.

Arguments

$taskIndex  The task on which to disable retrace mode.

The operations that follow can also disable retrace.

  • If a task error occurs, the controller disables retrace.

  • If you issue the ProgramStop(), ProgramReset(), or ProgramRestart() function, the controller disables retrace.

Activate or Deactivate Retrace with MFO

You can set the MFO value to activate or deactivate retrace. The controller activates retrace if you set the MFO value to a negative value. To then deactivate retrace, set the MFO to a number greater than zero. 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 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.

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.

Related Topics 

Acceleration and Deceleration Ramping

G-Code Programming

Immediate Commands