Device Functions

The Automation1 controller gives you read and write access to some drive-level variables, control signals, and status items.

Manual Brake Control

You can use the DriveBrakeOn() and DriveBrakeOff() functions to manually control the brake connected to your drive. These functions control the output specified by the BrakeOutput Parameter. The BrakeOutput parameter defaults to the dedicated brake output on the drive, but you can also set it to a digital output.

You can use these functions to debug the brake operation. You can also use them in an AeroScript program when you want the drive to engage or disengage the brake.

The DriveBrakeOn() and DriveBrakeOff() functions are optional. You can use the BrakeSetup Parameter to automatically disengage the brake when the axis is enabled.

The brake output is fail safe. If the system resets or if the power decreases quickly, the brake automatically engages.

Drive Items

You can use the DriveGetItem() function to get status information from the drive. The drive items supply information about the drive that can be used for debugging. You can use the DriveItem enumeration to select the drive item that you want to get.

This function has an overload that includes the $additionalData argument. Some drive items must use the $additionalData argument to select the correct information.

Refer to the DriveItem enumeration that follows.

Drive Array

The Automation1 controller supplies you with a drive array that is on the drive and can be used for fast data transfer. The drive array can be used with the Drive Data Capture feature to store encoder positions or analog inputs or to specify data for the array modes of various PSO features.

You can use an AeroScript program to read the drive array data into an array variable or write data from an array variable into the drive array.

When you reset the controller, all of the elements in the array are set to zero.

The size of the drive array is in bytes. The size is not the same for all drive types. Use the DriveArraySize drive item to retrieve the size of the data array directly from the drive.

Table: Applicable Drive Types and Drive Array Size

Drive Type	Drive Array Size (in bytes)
FLEX	67,108,864
GI4	67,108,864
GL4	67,108,864
SI4	16,777,216
iXA4, XA4 (1 and 2 axis)	16,777,216
iXA4, XA4 (4 axis)	67,108,864
iXC2, XC2	16,777,216
iXC2e, XC2e	67,108,864
iXC4, XC4	16,777,216
iXC4e, XC4e	67,108,864
iXC6e, XC6e	67,108,864
iXI4, XI4	67,108,864
iXL2e, XL2e	67,108,864
XL4s	16,777,216
iXL5e, XL5e	67,108,864
iXR3, XR3	67,108,864
Virtual Drive	2048

The drive array supports many built-in data types, as determined by the underlying AeroScript feature. You can use the DriveArrayType AeroScript enumeration to specify the feature from which to read and write data to the drive array.

The size of each item that you retrieve depends on the DriveArrayType. The table that follows shows the size in bytes for each item.

Table: DriveArrayType Item Sizes

DriveArrayType Item	Size
AnalogOutputVoltages	4 bytes (32 bits)
DataCapturePositions	8 bytes (64 bits)
PsoBitmapBits	4 bytes (32 bits)
PsoDistanceEventDistances	4 bytes (32 bits)
PsoPulseTimes	4 bytes (32 bits)
PsoPulseCounts	4 bytes (32 bits)
PsoWindowRanges	4 bytes (32 bits)

The byte address that you specify to DriveArrayRead() or DriveArrayWrite() must be evenly divisible by the size of the DriveArrayType item that you specify. For example, if you retrieve DriveArrayType.DataCapturePositions values (8 bytes each), the byte address that you specify to DriveArrayRead() or DriveArrayWrite() must be evenly divisible by 8.

Reading from the Drive Array

You can use the DriveArrayRead() function to read the drive array into an AeroScript array variable. You can specify the byte address where you want to start reading from the drive array and the number of subsequent elements you want to read. The byte address that you specify must be evenly divisible by the size of the DriveArrayType item that you specify. Refer to the table DriveArrayType Item Sizes for information about the size of each DriveArrayType item.

The DriveArrayRead() function will not complete until it retrieves all of the specified elements from the drive array. All user tasks share Drive Array bandwidth. If two or more user tasks call DriveArrayRead() at the same time on axes that are part of the same drive, then the higher task number will block until the call from the lower task number is complete. The function retrieves 304,000 bytes per second, per axis, which lets you read 76,000 32-bit values or 38,000 64-bit values per second. To see the number of values that the controller can retrieve per second, refer to the table that follows.

Table: Maximum DriveArrayRead() Bandwidth

Drive Type	Bytes per Second	32-bit Values per Second	64-bit Values per Second
FLEX	1,216,000	304,000	152,000
GI4	912,000	228,000	114,000
GL4	608,000	152,000	76,000
SI4 (2 axis)	608,000	152,000	76,000
SI4 (4 axis)	1,216,000	304,000	152,000
iXA4, XA4 (1 axis)	304,000	76,000	38,000
iXA4, XA4 (2 axis)	608,000	152,000	76,000
iXA4, XA4 (4 axis)	1,216,000	304,000	152,000
iXC2, XC2, iXC2e, XC2e	304,000	76,000	38,000
iXC4, XC4, iXC4e, XC4e	304,000	76,000	38,000
iXC6e, XC6e	304,000	76,000	38,000
iXI4, XI4 (2 axis)	608,000	152,000	76,000
iXI4, XI4 (4 axis)	1,216,000	304,000	152,000
iXL2e, XL2e	304,000	76,000	38,000
XL4s	304,000	76,000	38,000
iXL5e, XL5e	304,000	76,000	38,000
iXR3, XR3	304,000	76,000	38,000
Virtual Drive	304,000	76,000	38,000

The Automation1 .NET, C, LabVIEW, and Python APIs can also read from the Drive Array by using equivalent functions in their applicable programming languages. But when you use one of the APIs, the throughput is much lower. If an Automation1 API and an AeroScript user task try to read at the same time from axes that are part of the same drive, the API function will block until the AeroScript function is completed.

Table: Estimated Maximum API-Equivalent DriveArrayRead() Bandwidth

Drive Type	Bytes per Second	32-bit Values per Second	64-bit Values per Second
FLEX	600,000	150,000	75,000
GI4	500,000	125,000	62,500
GL4	400,000	100,000	50,000
SI4 (2 axis)	400,000	100,000	50,000
SI4 (4 axis)	600,000	150,000	75,000
iXA4, XA4 (1 axis)	240,000	60,000	30,000
iXA4, XA4 (2 axis)	400,000	100,000	50,000
iXA4, XA4 (4 axis)	600,000	150,000	75,000
iXC2, XC2, iXC2e, XC2e	240,000	60,000	30,000
iXC4, XC4, iXC4e, XC4e	240,000	60,000	30,000
iXC6e, XC6e	240,000	60,000	30,000
iXI4, XI4 (2 axis)	400,000	100,000	50,000
iXI4, XI4 (4 axis)	600,000	150,000	75,000
iXL2e, XL2e	240,000	60,000	30,000
XL4s	240,000	60,000	30,000
iXL5e, XL5e	240,000	60,000	30,000
iXR3, XR3	240,000	60,000	30,000
Virtual Drive	240,000	60,000	30,000

Writing to the Drive Array

You can use the DriveArrayWrite() function to write an AeroScript array variable into the drive array. You can specify the byte address where you want to start writing to the drive array and the number of subsequent elements you want to write. The byte address that you specify must be evenly divisible by the size of the DriveArrayType item that you specify. Refer to the table DriveArrayType Item Sizes for information about the size of each DriveArrayType item.

The DriveArrayWrite() function will not complete until it writes all of the specified elements to the drive array. All user tasks share Drive Array bandwidth. If two or more user tasks call DriveArrayWrite() at the same time on axes that are part of the same drive, then the higher task number will block until the call from the lower task number is complete.

The DriveArrayWrite() function writes a maximum of 216,000 bytes per second, per axis, which lets you write 50,400 32-bit values or 27,000 64-bit values per second. To see the number of values that the controller can write per second, refer to the table that follows:

Table: DriveArrayWrite() Bandwidth

Drive Type	Bytes per Second	32-bit Values per Second	64-bit Values per Second
FLEX	864,000	216,000	108,000
GI4	648,000	162,000	81,000
GL4	432,000	108,000	54,000
SI4 (2 axis)	432,000	108,000	54,000
SI4 (4 axis)	864,000	216,000	108,000
iXA4, XA4 (1 axis)	216,000	54,000	27,000
iXA4, XA4 (2 axis)	432,000	108,000	54,000
iXA4, XA4 (4 axis)	864,000	216,000	108,000
iXC2, XC2	216,000	54,000	27,000
iXC2e, XC2e	216,000	54,000	27,000
iXC4 , XC4	216,000	54,000	27,000
iXC4e, XC4e	216,000	54,000	27,000
iXC6e, XC6e	216,000	54,000	27,000
iXI4, XI4 (2 axis)	432,000	108,000	54,000
iXI4, XI4 (4 axis)	864,000	216,000	108,000
iXL2e, XL2e	216,000	54,000	27,000
XL4s	216,000	54,000	27,000
iXL5e, XL5e	216,000	54,000	27,000
iXR3, XR3	216,000	54,000	27,000
Virtual Drive	216,000	54,000	27,000

The AeroScript array used to write elements to the drive array is made of 64-bit reals, but the data must be valid for the provided DriveArrayType. Thus, for 32-bit value AeroScript features, the data must not be larger than the 32-bit boundary.

The Automation1 .NET, C, LabVIEW, and Python APIs can also write to the Drive Array by using equivalent functions in their applicable programming languages. In the Automation1 APIs, functions that are equivalent to DriveArrayWrite() give approximately 15% less throughput because of communication overhead. If an Automation1 API and an AeroScript user task try to write to axes at the same time on the same drive, the API function will block until the AeroScript function call is completed.

Drive Data Capture

The Automation1 controller lets you capture encoder positions or analog inputs and store them in the drive array. You can trigger data capture with PSO or a high speed digital input.

The drive can capture up to 320,000 points a second and write them to the drive array.

The data capture points of the drive array are stored as 64-bit floating point values.

You can read the captured points by using the DriveArrayRead() or DriveArrayReadFast() functions.

Data capture can have a maximum of two configurations per axis. To specify the configuration, use the $configurationNumber argument. Each configuration has an input, trigger, and array. You cannot capture the same input through more than one configuration on the same axis.

Configuring Drive Data Capture

You can use the DriveDataCaptureConfigureArray() function to configure the drive array for data capture. This function allocates a section of the drive array to store the data capture points. Starting at the $driveArrayStartAdress argument, data capture points are stored in the drive array as they occur. The number of data capture points that are stored in the array is set by the $numberOfPoints argument.

The maximum value of the $numberOfPoints argument is 2,147,483,647, but you can collect an infinite number of points by specifying a value of -1. If you use -1, data capture continues until you disable it. When you collect a number of points that exceeds the size of the drive array, make sure that the points are read from the array before they are overwritten by subsequent captures.

You can use the DriveDataCaptureConfigureInput() function to configure the encoder position or analog input that will be captured. You can use the DriveDataCaptureInput enumeration to select the input that you want to capture. Your drive might not support every enumeration option. See the table that follows for the options that are supported on your drive. If you select an unsupported option for your drive, it defaults to PositionCommand.

Table: DriveDataCaptureInput Drive Support

Drive Support	DriveDataCaptureInput Enumeration
	PositionCommand	PositionFeedback	PrimaryFeedback	AuxiliaryFeedback	AnalogInput0	AnalogInput1	AnalogInput2	AnalogInput3
FLEX	Yes	Yes	No	No	Yes	Yes	Yes	No
GI4	Yes	No	No	Yes	Yes	Yes	Yes	Yes
GL4	Yes	No	Yes	Yes	No	No	No	No
SI4	Yes	Yes	Yes	No	No	No	No	No
iXA4	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
XA4	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
iXC2	Yes	Yes	Yes	Yes	Yes	No	No	No
XC2	Yes	Yes	Yes	Yes	Yes	No	No	No
iXC2e	Yes	Yes	Yes	Yes	Yes	No	No	No
XC2e	Yes	Yes	Yes	Yes	Yes	No	No	No
iXC4	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
XC4	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
iXC4e	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
XC4e	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
iXC6e	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
XC6e	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
iXI4	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
XI4	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
iXL2e	Yes	Yes	Yes	Yes	Yes	No	No	No
XL2e	Yes	Yes	Yes	Yes	Yes	No	No	No
XL4s	Yes	No	Yes	No	No	No	No	No
iXL5e	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
XL5e	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
iXR3	Yes	Yes	Yes	Yes	Yes	Yes	No	No
XR3	Yes	Yes	Yes	Yes	Yes	Yes	No	No

Refer to the DriveDataCaptureInput enumeration that follows.

You can use the DriveDataCaptureConfigureTrigger() function to configure the signal that will trigger a capture of the input. You can use the DriveDataCaptureTrigger enumeration to select the signal you want to use. Your drive might not support every enumeration option. There are also hardware limitations on each signal that cause latency between the trigger event and when the data is captured. See the table for the triggers that are supported on your drive and the corresponding latency, in nanoseconds. If you select an unsupported option for your drive, data capture events will not be triggered.

Table: DriveDataCaptureTrigger Drive Support

Drive Support	DriveDataCaptureTrigger Enumeration (latency in nanoseconds)
	PsoOutput	PsoEvent	HighSpeedInput0 RisingEdge	HighSpeedInput0 FallingEdge	HighSpeedInput1 RisingEdge	HighSpeedInput1 FallingEdge	AuxiliaryMarker RisingEdge	AuxiliaryMarker FallingEdge
FLEX	10	10	NA	NA	NA	NA	NA	NA
GI4	10	10	60	60	NA	NA	NA	NA
GL4	10	10	NA	NA	NA	NA	NA	NA
SI4	NA	NA	60	60	NA	NA	NA	NA
iXA4	10	10	60	60	60	60	NA	NA
XA4	10	10	60	60	60	60	NA	NA
iXC2	10	10	NA	NA	NA	NA	60	60
XC2	10	10	NA	NA	NA	NA	60	60
iXC2e	10	10	NA	NA	NA	NA	60	60
XC2e	10	10	NA	NA	NA	NA	60	60
iXC4	10	10	60	60	60	60	60	60
XC4	10	10	60	60	60	60	60	60
iXC4e	10	10	60	60	60	60	60	60
XC4e	10	10	60	60	60	60	60	60
iXC6e	10	10	60	60	60	60	60	60
XC6e	10	10	60	60	60	60	60	60
iXI4	10	10	60	60	NA	NA	NA	NA
XI4	10	10	60	60	NA	NA	NA	NA
iXL2e	10	10	NA	NA	NA	NA	60	60
XL2e	10	10	NA	NA	NA	NA	60	60
XL4s	10	10	NA	NA	NA	NA	NA	NA
iXL5e	10	10	60	60	60	60	60	60
XL5e	10	10	60	60	60	60	60	60
iXR3	10	10	60	60	NA	NA	60	60
XR3	10	10	60	60	NA	NA	60	60

Refer to the DriveDataCaptureTrigger enumeration that follows.

Enabling Drive Data Capture

After you configure data capture, you must use the DriveDataCaptureOn() function to enable it.

You cannot enable this feature while homing.

You can use the DriveDataCaptureOff() function to disable this feature at any time. This function is optional. This feature also disables when it captures the number of elements specified by the $numberOfPoints argument in the DriveDataCaptureConfigureArray() function.

You can use the DriveGetItem() function to read the number of elements captured by setting $driveItem to DriveItem.DriveDataCaptureSamples and $additionalData to the necessary $configurationNumber.

Drive Encoder Output

Automation1 drives can send encoder feedback signals to external devices. These feedback signals are transmitted as incremental square-wave encoder signals from one or more supported drive connectors. You can use the DriveEncoderOutput* functions to configure a supported drive connector to send these encoder feedback signals.

The Drive Encoder Output feature lets you send encoder signals to other drives. Then these drives use the encoder signals as PSO tracking inputs in multi-axis PSO configurations.

For information about which connectors you can use for Drive Encoder Output, see the hardware manual for your drive. You can download your manual from the Manuals & Help Files section of www.aerotech.com.

Configuring the Drive Encoder Output

You can use the DriveEncoderOutputConfigureInput() function to select the correct feedback source to transmit from the specified drive output connector.

Use the EncoderOutputChannel enumeration to select the output connector that is necessary to configure so it can transmit encoder feedback signals. For information about which output connectors are available on each drive, see your drive hardware manuals.

Refer to the EncoderOutputChannel enumeration that follows.

Use the EncoderInputChannel enumeration to select the source of the encoder signals that you want to send on the output connector:

• For the PrimaryEncoder option: The IncrementalEncoderSquareWave, the IncrementalEncoderSineWave (-MX2, -MX3, -CT2, and -CT4 only), and the CapacitanceSensor primary feedback types are supported.
• For the AuxiliaryEncoder option: The IncrementalEncoderSquareWave and the IncrementalEncoderSineWave (-CT4) feedback types are supported.

When you use the Drive Encoder Output to send Drive Pulse Stream signals (EncoderInputChannel.PulseStream), the format of the signals is controlled by the Pulse Stream feature. Refer to the DrivePulseStreamConfigure() function for available options.

Refer to the EncoderInputChannel enumeration that follows.

You can configure the Drive Encoder Output feature to apply an integer divider to the encoder feedback signals as they are transmitted from the drive output connector. To configure this divider, use the DriveEncoderOutputConfigureDivider() function. Aerotech recommends that you use this divider to make sure that the switching rate of the Drive Encoder Output quadrature signals is not more than the maximum supported rate of 25 MHz, as measured in counts per second. If the PrimaryFeedbackType Parameter of the axis on which you want to configure to this divider is set to IncrementalEncoderSineWave, then the PrimaryEmulatedQuadratureDivider Parameter also has an effect on switching rate of the Drive Encoder Output quadrature signal. In this case, the PrimaryEmulatedQuadratureDivider parameter and the $outputDivider argument are multiplied together to get the divider. When the PrimaryFeedbackType parameter is set to IncrementalEncoderSineWave, Aerotech recommends that you use only the PrimaryEmulatedQuadratureDivider parameter to adjust the switching rate and set $outputDivider to 1.

You can use the DriveEncoderOutputConfigureDirection() function to reverse the drive encoder output signals that are transmitted through encoder output channels.

Controlling the Drive Encoder Output

After you configure a connector for the Drive Encoder Output feature, you can use the DriveEncoderOutputOn() function to enable it. While the connector is enabled, the drive tracks the specified encoder input and sends the counts on the configured output connector. If you are receiving feedback on another drive input, you must also configure the correct feedback parameters for the input you are using. These can include PrimaryFeedbackType Parameter, AuxiliaryFeedbackType Parameter, and the Primary Multiplier and Auxiliary Multiplier parameters.

To disable encoder output, use the DriveEncoderOutputOff() function. The DriveEncoderOutputOff() function does not reset the configuration of the Drive Encoder Output feature. You can immediately use the DriveEncoderOutputOn() function again to enable the feature with the existing configuration.

Pulse Stream

The Automation1 controller lets you generate pulses that are proportional to the speed of one or more real or virtual axes. The pulse stream can be an internal signal that is used as an input to PSO. It can also be a quadrature output signal when used with the Encoder Output feature.

When the pulse stream is enabled, the controller sends pulses to the drive controlling the specified output axis at a 20 kHz rate. The maximum rate for the pulse stream is 95 MHz.

Some of the use cases of the pulse stream are as follows:

• Pulse a laser input signal that is proportional to the velocity command of one or more axes.
• Perform PSO operations based on the position or velocity of one or more axes.

Configuring the Pulse Stream

You can use the DrivePulseStreamConfigure() function to configure which axes are tracked by the controller. The input axes can be real or virtual. The output axis specified by the $outputAxis argument generates the pulse stream.

When you configure the pulse stream to track only one axis, the controller calculates the speed and direction of that axis. When you configure the pulse stream to track multiple axes, the controller calculates a vector speed by calculating the square root of the sum of squares of the position of each axis, without direction information.

The controller calculates the speed in encoder counts. You can use the $inputScaleFactors argument to apply scale factors and track the axes in other units. The scale factors should be set in the same order as the axes you specified with the $inputAxes argument. The scale factors are multiplied to the speed of each axis before the controller calculates the vector speed.

The controller then sends the vector speed to the drive controlling the output axis. The output axis generates a number of pulses corresponding to the vector speed.

Use the $signalMode argument to specify the format of the pulse stream signals sent to the drive. The $signalMode argument has an effect on the format of the signals only when it is used in conjunction with the Drive Encoder Output feature. For more information, refer to Drive Encoder Output.

Refer to the DrivePulseStreamSignalMode enumeration that follows.

Enabling the Pulse Stream

You can use the DrivePulseStreamOn() and DrivePulseStreamOff() functions to enable and disable the pulse stream on the output axis. If you do not use the DrivePulseStreamOn() function, pulses will not be generated.

Drive Position Registers

The Automation1 controller lets you set the different position command and feedback values on the drive.

You can use the StatusGetAxisItem() function to read the Position Command, Position Feedback, and Position Feedback Auxiliary at any time.

Setting Position Command

You can use the DriveSetPositionCommand() function to set the position command of the axis without physically moving the axis to that position. This function sets the position command on the drive at the servo loop level. The drive calculates the difference between the current position command and the new position command specified by the $positionCommand argument. The drive reduces the position feedback by this difference to maintain the current position error.

Setting Position Feedback

You can use the DriveSetPositionFeedback() function to set the position feedback of the axis without physically moving the axis to that position. This function sets the position feedback on the drive at the servo loop level. The drive also sets the position command to the new position feedback value specified by the $positionFeedback argument. This results in no position error to prevent the axis from being commanded back to the original position.

Setting Encoder Hardware Counters

You can use the DriveSetEncoderPosition() function to set the value of the different drive encoder hardware counters. Use the $encoderChannel argument to specify the channel on which to set the counter value and the $encoderValue argument to specify the new counter value in counts. See the DriveEncoderChannel enumeration for the list of available drive encoder channels that you can use with this function.