Transformation Functions

The Automation1 controller provides two methods of applying geometric and kinematic transformations to motion profiles:

  • The Matrix Transformation feature provides rotation, mirror, and translation transformations through the AeroScript API.
  • The C Transformation feature allows running custom real-time C code in a motion program.

The table that follows shows the availability of transformations based on the controller type.

Table: Transformation features and controller types

Feature Availability

Matrix Transformation

PC-based and drive-based controllers

C Transformation

PC-based controllers only

This topic describes the APIs, development environment, and concepts needed to build and run transformations with the Automation1 Controller.

Transformation Behavior and Concepts

Execution Sequence

A maximum of 32 Matrix transformations can execute at the same time. A maximum of 10 C transformations can execute at the same time.

In each controller cycle, the inverse transformation execution sequence is as follows:

  • All matrix transformations execute in numerical order of their transformation indices.
  • All C transformations execute in the order of their configurations specified in the configuration file.
  • Then IFOV executes.

You can also execute all C transformations after IFOV with the TransformationExecutionOrder Parameter.

Chained Transformations

More than one independently defined transformations can be chained together such that the output of one transformation is the input of another. This is performed by configuring one or more of the output axes of a transformation as the input axes to the next transformation in the sequence.

Multitask

Transformations are global and are run task-independently. This means a transformation can be configured on one task and reconfigured, enabled, or disabled in another task. Motion commanded from any task will be transformed by the enabled transformations using the commanded axes.

Abort

The axis of an enabled transformation axes will be aborted in the cases that follow:

  • Any axis in the transformation is aborted, faulted, or disabled.
  • Any axis in a transformation or motion command with directly shared or indirectly shared axes is aborted, faulted, disabled, or controlled by the drive.
  • A task commanding transformed motion is stopped.
  • A C transformation C function returns an error.
  • If one or more of a transformation’s axes are aborted, then the transformation will be disabled.

For more information regarding aborts, faults, and errors, see the Abort() function in Motion Functions or Fault and Error Functions.

Input Axes

The position and velocity of these axes are input to the transformation. Linear, Circular, Rapid, Incremental, Absolute, Freeun, Jog, PT, and PVT motion commanded to these axes will be transformed. Input and output axes may overlap.

Output Axes

The transformation will modify the position and velocity of these axes. Input and output axes may overlap.

Output-Only Axes

An output-only axis is an output axis that was not also specified as an input axis. These axes cannot be commanded motion while the transformation is enabled. Multiple transformations cannot have overlapping output-only axes.

Transformation Rate

The transformation rate is the rate at which the inverse transformation is executed. This rate is equal to the maximum Position Update Rate (drive motion rate) of all axes in the transformation and all axes in transformations with directly shared or indirectly shared axes. This rate is determined using all configured transformations.

TransformationEnableMode

The TransformationEnableMode Parameter is a system parameter that applies to all transformations. This parameter controls how transformations are enabled. When a transformation is enabled, it starts to compute new axis positions, which are usually not equal to the original axis positions. If the controller were to directly command these new positions, it can cause position step changes. Instead, the controller automatically prevents position step changes using two methods, which are controlled using this parameter. The two methods are defined as follows:

  • 0: Compute Automatic Offset (default)

    The controller will apply an offset to each transformation output axis equal to the difference between the original position and new transformed position.

  • 1: Update Program Position

    The controller will update the program position signals of each transformation input axis to be the forward transformed value of the current position. This mode also prevents motion on any input axes that are not also output axes. When using the C transformation feature, this mode requires that the forward transformation for each C transformation is correctly defined in the OnForward() function.

This parameter can be modified only if all transformations are disabled. In both modes, if an axis is no longer part of a transformation (which can occur after a transformation is disabled), then all of its position signals will be updated to the most recent position of that axis. You can modify the active value of this parameter with the ParameterSetSystemValue() function and the enumeration that follows.

enum TransformationEnableMode
   ComputeAutomaticOffset = 0
   UpdateProgramPosition = 1
end

Matrix Transformation

The matrix transformation feature provides built-in functionality to perform rotation, translation, and mirroring. The base transformations are exposed as matrices, which can be combined in many custom configurations to yield the desired final transformation.

Matrices are created using one or more of the following functions:

  • MatrixCreateMirror()
  • MatrixCreateRotateI()
  • MatrixCreateRotateJ()
  • MatrixCreateRotateK()
  • MatrixCreateTranslate()

Transformations are configured using these matrices as arguments to TransformationConfigure(). Up to 32 transformations can be configured. Transformations are numbered 0-31. Transformations can be turned on and off using TransformationEnable() and TransformationDisable().

Refer to the matrix transformation examples in the drop-down that follows or go to AeroScript Example Programs to see full program examples.

Single Matrix Example

// Configure a mirror transformation on axes X, Y
TransformationConfigure(0, [MatrixCreateMirror()], [X, Y], [X, Y])
TransformationEnable(0)

Multiple Matrices Example

// Configure two rotations on axes X, Y, Z.
// This configures the following matrix multiplication:
// [RotateK] * [RotateJ] * [Xin Yin Zin] => [Xout Yout Zout]
TransformationConfigure(1, [MatrixCreateRotateK(45), MatrixCreateRotateJ(90)], [X, Y, Z], [X, Y, Z])
TransformationEnable(1)

Chained Transformations

// The transformation configured on index 1 will execute on axes X, Y
// The transformation on index 2 will execute using the output of the
// transformation on index 1
TransformationConfigure(1, [MatrixCreateMirror()], [X, Y], [X, Y])
TransformationConfigure(2, [MatrixCreateRotateK(45)], [X, Y], [X, Y])
TransformationEnable([1, 2])

Axis Argument Matrix

// The rotation angle is determined by the position of the U axis
TransformationConfigure(1, [MatrixCreateRotateK(U)], [X, Y], [X, Y])
TransformationEnable(1)

Use the functions that follow to create matrices.

function MatrixCreateMirror() as handle

Create a mirror matrix.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateRotateI($angle as real) as handle

Create a rotation matrix that rotates about the first input axis.

Arguments

$angle  The rotation angle.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateRotateI($angle as axis) as handle

Create a rotation matrix that rotates about the first input axis.

Arguments

$angle  The axis that determines the rotation angle. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateRotateJ($angle as real) as handle

Create a rotation matrix that rotates about the second input axis.

Arguments

$angle  The rotation angle.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateRotateJ($angle as axis) as handle

Create a rotation matrix that rotates about the second input axis.

Arguments

$angle  The axis that determines the rotation angle. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateRotateK($angle as real) as handle

Create a rotation matrix that rotates the first two input axes.

Arguments

$angle  The rotation angle.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateRotateK($angle as axis) as handle

Create a rotation matrix that rotates the first two input axes.

Arguments

$angle  The axis that determines the rotation angle. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as real) as handle

Create a translation matrix.

Arguments

$a  The translation value to apply to the first input axis.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as axis) as handle

Create a translation matrix.

Arguments

$a  The axis that determines the translation value of the first input axis. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as real, $b as real) as handle

Create a translation matrix.

Arguments

$a  The translation value to apply to the first input axis.

$b  The translation value to apply to the second input axis.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as axis, $b as real) as handle

Create a translation matrix.

Arguments

$a  The axis that determines the translation value of the first input axis. Motion on this axis will update the transformation.

$b  The translation value to apply to the second input axis.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as real, $b as axis) as handle

Create a translation matrix.

Arguments

$a  The translation value to apply to the first input axis.

$b  The axis that determines the translation value of the second input axis. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as axis, $b as axis) as handle

Create a translation matrix.

Arguments

$a  The axis that determines the translation value of the first input axis. Motion on this axis will update the transformation.

$b  The axis that determines the translation value of the second input axis. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as real, $b as real, $c as real) as handle

Create a translation matrix.

Arguments

$a  The translation value to apply to the first input axis.

$b  The translation value to apply to the second input axis.

$c  The translation value to apply to the third input axis.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as axis, $b as real, $c as real) as handle

Create a translation matrix.

Arguments

$a  The axis that determines the translation value of the first input axis. Motion on this axis will update the transformation.

$b  The translation value to apply to the second input axis.

$c  The translation value to apply to the third input axis.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as real, $b as axis, $c as real) as handle

Create a translation matrix.

Arguments

$a  The translation value to apply to the first input axis.

$b  The axis that determines the translation value of the second input axis. Motion on this axis will update the transformation.

$c  The translation value to apply to the third input axis.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as real, $b as real, $c as axis) as handle

Create a translation matrix.

Arguments

$a  The translation value to apply to the first input axis.

$b  The translation value to apply to the second input axis.

$c  The axis that determines the translation value of the third input axis. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as axis, $b as axis, $c as real) as handle

Create a translation matrix.

Arguments

$a  The axis that determines the translation value of the first input axis. Motion on this axis will update the transformation.

$b  The axis that determines the translation value of the second input axis. Motion on this axis will update the transformation.

$c  The translation value to apply to the third input axis.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as real, $b as axis, $c as axis) as handle

Create a translation matrix.

Arguments

$a  The translation value to apply to the first input axis.

$b  The axis that determines the translation value of the second input axis. Motion on this axis will update the transformation.

$c  The axis that determines the translation value of the third input axis. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as axis, $b as real, $c as axis) as handle

Create a translation matrix.

Arguments

$a  The axis that determines the translation value of the first input axis. Motion on this axis will update the transformation.

$b  The translation value to apply to the second input axis.

$c  The axis that determines the translation value of the third input axis. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

function MatrixCreateTranslate($a as axis, $b as axis, $c as axis) as handle

Create a translation matrix.

Arguments

$a  The axis that determines the translation value of the first input axis. Motion on this axis will update the transformation.

$b  The axis that determines the translation value of the second input axis. Motion on this axis will update the transformation.

$c  The axis that determines the translation value of the third input axis. Motion on this axis will update the transformation.

Returns

A handle to the matrix. This should be passed as an argument to TransformationConfigure().

A maximum of 512 matrices can exist at the same time in a motion program. You can use the MatrixDelete() function to delete unwanted matrices so that your AeroScript program can make more than 512 matrices during its life. Matrices are deleted automatically when a task stops or an error occurs.

For information about how to use the MatrixDelete() function to delete unwanted matrices, refer to the example that follows:

Program Example

var $matrix as handle

$matrix = MatrixCreateMirror()
TransformationConfigure(0, [$matrix], [X, Y], [X, Y])
MatrixDelete($matrix)

$matrix = MatrixCreateRotateK(45)
TransformationConfigure(1, [$matrix], [X, Y], [X, Y])
MatrixDelete($matrix)

TransformationEnable([0, 1])

function MatrixDelete($matrixHandle as handle)

Delete the matrix with the associated handle.

Arguments

$matrixHandle  Handle to the matrix.

function MatrixDelete($matrixHandles[] as handle)

Delete the matrices with the associated handles.

Arguments

$matrixHandles  Array of handles to the matrices.

function TransformationConfigure($transformationIndex as integer, $matrices[] as handle, $inputAxes[] as axis, $outputAxes[] as axis)

Configure a transformation. The transformation must be disabled when this function is called. Any existing configuration on the $transformationIndex will be overwritten. Configured transformations execute in the order of their indices, which means transformations will execute starting with index 0 ascending to 31. For a transformation configured with n matrices provided in the $matrices argument, the matrix multiplication is performed as follows: [matrix_1] * [matrix_2] * .. [matrix_n] * [inputAxes] = [outputAxes]. This computation is executed for every enabled transformation in numerical order of the transformation indices. When enabled, transformations configured on higher indices will use the transformed results from the transformations configured on lower indices. Multiple configurations may reuse the same matrix handles. When a transformation is configured, the matrices are copied. This means that the matrix handle can be deleted with MatrixDelete() after it is configured without affecting the configuration. Up to 512 matrices can be configured to a single index.

Arguments

$transformationIndex  An integer between and including 0 and 31.

$matrices  Array of 1 or more matrices that will be applied to the $inputAxes and output to the $outputAxes.

$inputAxes  Array of 1-3 axes. These axes may be the same as the $outputAxes.

$outputAxes  Array of 1-3 axes. These axes may be the same as the $inputAxes.

function TransformationUnconfigure($transformationIndex as integer)

Remove the configuration from the transformation.

Arguments

$transformationIndex  The index identifier of the transformation.

function TransformationEnable($transformationIndex as integer)

Enable a transformation. This will begin running inverse and forward computations for the specified transformation. All axes part of the transformation must be enabled at any time the transformation is enabled. If the transformation is enabled while there is synchronous motion on the same task, then the motion program will wait for motion to complete before enabling the transformation.

Arguments

$transformationIndex  The index identifier of the transformation.

function TransformationEnable($transformationIndices[] as integer)

Enable multiple transformations simultaneously. This will begin running inverse and forward computations for the specified transformations. All axes part of the transformations must be enabled at any time the transformations are enabled. If the transformations are enabled while there is synchronous motion on the same task, then the motion program will wait for motion to complete before enabling the transformations.

Arguments

$transformationIndices  The index identifiers of the transformations.

function TransformationDisable($transformationIndex as integer)

Disable a transformation. This will stop inverse and forward computations for this transformation.

Arguments

$transformationIndex  The index identifier of the transformation.

function TransformationDisable($transformationIndices[] as integer)

Disable multiple transformations simultaneously. This will stop running inverse and forward computations for the specified transformations.

Arguments

$transformationIndices  The index identifiers of the transformation.

C Transformation

The C Transformation feature provides the ability to build custom C transformations to run on the Automation1 controller in real-time.

To develop a C transformation C project:

  1. Set up the C Development Environment.
  2. Use the CTransformationLibrary API and C Transformation User Defined Functions API to build and compile a C transformation.

To execute a C transformation in the controller:

  1. Create or obtain a compiled C transformation.
  2. Set up the C Transformation Configuration.
  3. Create motion programs using C Transformation AeroScript Functions.

The C Transformation feature has these core design elements:

  • Performance  Custom C code executes in the INtime RTOS and can operate at any Position Update Rate supported by the controller.
  • Parametrization  A single defined transformation can specify up to 128 Properties, which are used to set up the transformation for multiple configurations.
  • Modularity
    • A C transformation is defined in a compiled .rsl file. This .rsl file can be copied to any system. Additionally, the same .rsl file can be reused by multiple configurations in the same system. This allows motion developers at Aerotech or an OEM to develop custom transformations for distribution to end users.
    • C transformations access motion data using transformation axis indices. Transformation axis indices are indexed starting at 0 incrementing up to the desired number of axes. For example, a transformation that uses 3 input axes and 4 output axes will have input transformation axes of [0, 1, 2] and output transformation axes of [0, 1, 2, 3]. These axes are automatically mapped at runtime to the configured controller axes. Additionally, the CTransformationLibrary API provides functions to get the controller axis for a specified transformation axis.

      • This feature allows a predefined C transformation to be independent of the controller axes, allowing any transformation to be configured for any set of axes.

  • Controller Data Access  You can access the data that follows directly from the C transformation.
    • Position
    • Velocity
    • Analog I/O
    • Digital I/O
    • Galvo laster output

C Development Environment

This section describes how to set up a development environment to allow building custom C transformations for use with Automation1.

Obtaining the CTransformation Example Project

The example Visual Studio project and its dependencies are provided within the Automation1 installation directory (C:\Program Files\Aerotech\Automation1-MDK) in the CTransformation folder. The CTransformation folder may be moved to any desired location.

Dependencies

A C Transformation project requires the following dependencies:

  • CTransformationLibrary, provided in CTransformation\Library and CTransformation\Include.
  • INtime CDEV Library, provided in CTransformation\INtime\Library and CTransformation\INtime\Include.

The provided example project has been configured with these dependencies.

IMPORTANT: If the example Visual Studio project is moved without these dependencies, then the project settings must be updated to specify the new paths to the dependencies.

Building with MSBuild and Visual Studio Build Tools 2019

  1. Obtain and run the Visual Studio Build Tools 2019 installer.
    1. Select C++ build tools.
  2. Extract the contents of CTransformation\INtime\BuildEnvironment\VS2019\VS2019_BuildTools.zip to C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\MSBuild\Microsoft\VC\v160\Platforms.
  3. Use MSBuild to build the example project:
    1. Open Developer Command Prompt for VS 2019.
    2. Navigate to CTransformation\Examples\CTransformationRotation.
    3. Execute the command that follows:

      4. msbuild /property:Configuration=Release

Building with Visual Studio Professional 2019

  1. Obtain and run the Visual Studio Professional installer.
    1. Select Desktop development with C++.
  2. Extract the contents of CTransformation\INtime\BuildEnvironment\VS2019\VS2019_BuildTools.zip to C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\MSBuild\Microsoft\VC\v160\Platforms.
  3. Use Visual Studio to build the example project:
    1. Open the project in Visual Studio.
    2. If the Retarget Projects window comes into view, set Windows SDK Version and Platform Toolset to No Upgrade.
    3. Select the Release configuration.
    4. On the Build menu, select Build Solution.

C Transformation User Defined Functions API

This API provides the template for adding custom C code. Each function in this API is provided a TransformationHandle, which is used to access controller data through the CTransformationLibrary API. When a function is implemented, the function declaration must exactly match the declaration in this API.

Each function implemented by the C developer must return an integer value where 0 indicates success and any other integer indicates failure. A failure will cause a task error in the task that enabled the transformation, unless the function that caused the error is OnCleanup().

int OnInverse(TransformationHandle handle)

Runs during inverse transformations while the transformation is enabled. This function runs for every motion point per millisecond, as specified by the Transformation Rate. Return 0 to indicate success.

This function is required.

int OnForward(TransformationHandle handle)

Runs during forward transformations while the transformation is enabled. This function is used to compute forward transformations for the PositionCommand and PositionFeedback signals. Return 0 to indicate success.

This function is optional.

int OnSetup(TransformationHandle handle)

Runs during controller reset startup. Return 0 to indicate success.

This function is optional.

int OnCleanup(TransformationHandle handle)

Runs during controller reset shutdown. The return value is ignored.

This function is optional.

int OnEnable(TransformationHandle handle)

Runs immediately before the first call to OnInverse() after the C transformation is enabled. Return 0 to indicate success.

This function is optional.

int OnDisable(TransformationHandle handle)

Runs immediately after the last call to OnInverse() after the C transformation is disabled. Return 0 to indicate success.

This function is optional.

int OnRequest(TransformationHandle handle, int numArgs, const double args[], double returnData[])

Runs when CTransformationRequest() is called on the transformation. Return 0 to indicate success.

This function is optional.

int OnSetProperty(TransformationHandle handle, const char* property, double value)

Runs when CTransformationSetProperty() is called for the C transformation. This function is also called for each property specified in the configuration file before OnSetup(). Return 0 to indicate success.

This function is optional.

int OnGetProperty(TransformationHandle handle, const char* property, double* value)

Runs when CTransformationGetProperty() is called for the C transformation. Return 0 to indicate success.

This function is optional.

CTransformationLibrary API

This API provides the C Transformation developer access to transformation and controller state information.

bool TransformationGetInverseRate(TransformationHandle handle, int* rate)

Get the Transformation Rate. This is the number of times OnInverse() will run per millisecond.

bool TransformationGetNumInputAxes(TransformationHandle handle, int* numInputAxes)

Get the number of input axes configured for the transformation.

bool TransformationGetNumOutputAxes(TransformationHandle handle, int* numOutputAxes)

Get the number of output axes configured for the transformation.

bool TransformationGetControllerInputAxis(TransformationHandle handle, int transformationAxis, Axis* controllerAxis)

Get the controller axis for the given transformation input axis.

bool TransformationGetControllerOutputAxis(TransformationHandle handle, int transformationAxis, Axis* controllerAxis)

Get the controller axis for the given transformation output axis.

bool TransformationGetCurrentIteration(TransformationHandle handle, int* iteration)

Get the current iteration of OnInverse() for this millisecond. This value will be between 0 and Transformation Rate - 1.

bool MotionGetPositionInputs(TransformationHandle handle, double* inputPositions)

Get the positions for the current motion point. inputPositions is an array of position values indexed by the input transformation axes.

bool MotionSetPositionOutputs(TransformationHandle handle, const double* outputPositions)

Set the position for the transformation output axes. outputPositions must be an array of position values indexed by the output transformation axes. The array must be large enough to hold position values for all output axes.

bool MotionGetVelocityInputs(TransformationHandle handle, double* inputVelocities)

Get the velocity for the transformation input axes. inputVelocities is an array of velocity values indexed by the input transformation axes.

bool MotionSetVelocityOutputs(TransformationHandle handle, const double* outputVelocities)

Set the velocity for the transformation output axes. outputVelocities must be an array of velocity values indexed by the output transformation axes. The array must be large enough to hold velocity values for all output axes.

bool AnalogInputGet(TransformationHandle handle, Axis axis, int index, double* value)

Get the value of the analog input for the specified controller axis and analog input index.

bool AnalogOutputGet(TransformationHandle handle, Axis axis, int index, double* value)

Get the value of the analog output for the specified controller axis and analog output index.

bool AnalogOutputSet(TransformationHandle handle, Axis axis, int index, double value)

Set the value of the analog output for the specified controller axis and analog output index.

bool DigitalInputGet(TransformationHandle handle, Axis axis, int index, int* value)

Get the value of the digital input for the specified controller axis and digital inputindex.

bool DigitalOutputGet(TransformationHandle handle, Axis axis, int index, int* value)

Get the value of the digital output for the specified controller axis and digital output index.

bool DigitalOutputSet(TransformationHandle handle, Axis axis, int index, int value)

Set the value of the digital output for the specified controller axis and digital output index.

bool GalvoLaserOutputGet(TransformationHandle handle, Axis axis, int* value)

Get the value of the galvo laser output for the specified controller axis.

bool GalvoLaserOutputSet(TransformationHandle handle, Axis axis, int value)

Set the value of the galvo laser output for the specified controller axis. Galvo axes on a multi-axis drive must be set to the same value. If the galvo laser output is set by this function, then the galvo laser advance time will be set to 0 for the related time point.

Function Restrictions

The following restrictions apply to functions in this API:

  • Motion setter functions can only be used from OnInverse() and OnForward().
  • Motion getter functions can only be used from OnInverse(), OnForward(), OnEnable(), and OnDisable().
  • IO setter and getter functions can only be used from OnInverse(), OnForward(), OnEnable(), and OnDisable().

C Transformation Configuration

To use a compiled C Transformation .rsl file in a motion program, a C Transformation configuration file must be added to the controller. The configuration file is described in this section.

C Transformation Configuration File Format

The C Transformation configuration defines all transformation configurations and contains all .rsl files that are accessible by the controller. The fields that follow must be specified per transformation configuration within the XML configuration file:

Configuration

Specifies the transformation configuration for a single transformation. Each additional Configuration node specifies an additional transformation. The order of the Configuration nodes defines the order in which the transformations execute during inverse transformations.
Load

Set this to 1 to load the transformation during controller reset startup and make the transformation accessible from AeroScript. At most 10 transformations may be loaded at once. Set this to 0 to not load the transformation.

ConfigurationName

Name used to reference the transformation from AeroScript. This value must be unique for all loaded transformations. The name must be less than or equal to 31 characters.

FileName

Name of the source transformation .rsl file. Multiple configurations may use the same file.

InputAxes

Ordered list of up to 32 axis indices. Motion from these axes is input to the transformation. Each Axis must be an integer.

OutputAxes

Ordered list of up to 32 axis indices. The transformation will output motion to these axes. Each Axis must be an integer.
Properties

A list of up to 128 name-value pairs. Each name must be unique per transformation. Each name may be less than or equal to 31 characters. The value will be treated as a 64-bit IEEE floating point number. Each Property is automatically set for the transformation during controller startup.

To Add a C Transformation Configuration File to the Controller

An example project called CTransformationRotation is located on your PC at C:\Program Files\Aerotech\Automation1-MDK\CTransformation\Examples\CTransformationRotation. To use this example project, do the procedure that follows.

  1. Compile the Visual Studio project, CTransformationRotation, with the Release build configuration. Refer to Building with MSBuild and Visual Studio Build Tools 2019 or Building with Visual Studio Professional 2019 on this page for steps on how to do this if necessary.

  2. Create a new text file and paste the content that follows into it. Save the file as a .config file. 
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<File SchemaVersion="1.0.0.0">
     <FileInformation>
          <SoftwareVersion>2.0.0.1639</SoftwareVersion>
          <OldestCompatibleSoftwareVersion>1.0.0.0</OldestCompatibleSoftwareVersion>
     </FileInformation>
     <Data>
          <Configurations>
               <Configuration>
                    <Load>1</Load>
                    <ConfigurationName>MyCustomRotation</ConfigurationName>
                    <FileName>CTransformationRotation.rsl</FileName>
                    <InputAxes>
                         <Axis>0</Axis>
                         <Axis>1</Axis>
                    </InputAxes>
                    <OutputAxes>
                         <Axis>0</Axis>
                         <Axis>1</Axis>
                    </OutputAxes>
                    <Properties>
                         <Property name="angle" value="45" />
                    </Properties>
               </Configuration>
          </Configurations>
     </Data>
</File>

  3. Open the Automation1 Console, and issue the command that follows.

    4. connect

    If your controller is on a different PC, issue the command that follows, but change the IP address in the command to match the IP address of the PC that your controller is on.

    connect --ip 192.168.1.2

  4. In the Automation1 Console, issue the command that follows, replacing [path to configuration file] with the path to the .config file that you created in step 2. This command adds the compiled C transformation .rsl to the configuration file.

    5. transformation add C:\Program Files\Aerotech\Automation1-MDK\CTransformation\Examples\CTransformationRotation\bin\CTransformationRotation.rsl [path to configuration file]

    IMPORTANT: The command in this step creates the configuration file if one does not exist at the specified path.

  5. Issue the command that follows, replacing [path to configuration file] with the path to the .config file that you created in step 2. This command sends the C transformation configuration file to the controller.

    6. config ctransformation set [path to configuration file]

    IMPORTANT: The command in this step overwrites any existing configuration. Applying any configuration change requires a controller reset.

  6. Issue the command that follows to reset the controller so that the C transformation takes effect.

    7. initialize full

C Transformation AeroScript Functions

This API allows controlling and communicating with C transformations that have been loaded with the controller.

function CTransformationEnable($transformationName as string)

Enable a C transformation. This will begin running inverse and forward computations for the specified transformation. All axes part of the transformation must be enabled at any time the transformation is enabled. If the transformation is enabled while there is synchronous motion on the same task, then the motion program will wait for motion to complete before enabling the transformation.

Arguments

$transformationName  The name specified in the C Transformation configuration.

function CTransformationEnable($transformationNames[] as string)

Enable multiple C transformations simultaneously. This will begin running inverse and forward computations for the specified transformations. All axes part of the transformations must be enabled at any time the transformations are enabled. If the transformations are enabled while there is synchronous motion on the same task, then the motion program will wait for motion to complete before enabling the transformations.

Arguments

$transformationNames  The names specified in the C Transformation configuration.

function CTransformationDisable($transformationName as string)

Disable a C transformation. This will stop running inverse and forward computations for this transformation.

Arguments

$transformationName  The name specified in the C Transformation configuration.

function CTransformationDisable($transformationNames[] as string)

Disable multiple C transformations simultaneously. This will stop running inverse and forward computations for the specified transformations.

Arguments

$transformationNames  The names specified in the C Transformation configuration.

function CTransformationSetInputAxes($transformationName as string, $inputAxes[] as axis)

Set the input axes of a C transformation.

Arguments

$transformationName  The name specified in the C Transformation configuration.

$inputAxes  The input axes of the transformation. Motion from these axes are input to the transformation.

function CTransformationSetOutputAxes($transformationName as string, $outputAxes[] as axis)

Set the output axes of a C transformation.

Arguments

$transformationName  The name specified in the C Transformation configuration.

$outputAxes  The output axes of the transformation. The transformation outputs motion to these axes.

function CTransformationSetProperty($transformationName as string, $property as string, $value as real)

Call the OnSetProperty() C function defined in a C transformation.

Arguments

$transformationName  The name specified in the C Transformation configuration.

$property  The property argument provided to the OnSetProperty() C function.

$value  The value argument provided to the OnSetProperty() C function.

function CTransformationGetProperty($transformationName as string, $property as string) as real

Call the OnGetProperty() C function defined in a C transformation.

Arguments

$transformationName  The name specified in the C Transformation configuration.

$property  The property argument provided to the OnGetProperty() C function.

Returns

The value argument set by the OnGetProperty() C function.

function CTransformationRequest($transformationName as string, $args[] as real)

Call the OnRequest() C function defined in a C transformation.

Arguments

$transformationName  The name specified in the C Transformation configuration.

$args  The args argument provided to the OnRequest() C function.

function CTransformationRequest($transformationName as string, $args[] as real, ref $returnData[] as real)

Call the OnRequest() C function defined in a C transformation.

Arguments

$transformationName  The name specified in the C Transformation configuration.

$args  The args argument provided to the OnRequest() C function.

ref $returnData  The returnData argument set by the OnRequest() C function.

Debugging a C Transformation

There are several methods available to you for debugging a running C Transformation.

  • Using AeroScript functions to interrogate the transformation.

  • Using Data Collection to compare signals with and without the transformation applied.

  • Using printf() function calls from within the transformation.

Using AeroScript C Transformation Functions

You can communicate with the transformation from AeroScript using two methods:

Requests through CTransformationRequest()

This function allows you to send data to the transformation through $args and get data from the C transformation through $returnData. The related transformation function OnRequest() must be implemented to use the CTransformationRequest() function. The OnRequest() function may implement any arbitrary behavior, such as setting or getting global variables within the transformation.

The $args and $returnData are each limited to up to 128 values.

The data sent to or received from the transformation can be arbitrary. For example, $args could contain flags that tell the transformation which data to send back in $returnData.

Properties through CTransformationGetProperty() and CTransformationGetProperty()

The property mechanism is intended to provide the ability to initialize the transformation with certain values at startup so that they can be used in the transformation's OnSetup() function. But, they can also be used at runtime to dynamically send and receive data similar to the request mechanism. This requires implementing the following functions in the transformation:

  • OnSetProperty()

  • OnGetProperty()

Refer to the descriptions of the CTransformationRequest(), CTransformationGetProperty(), and CTransformationGetProperty() in C Transformation AeroScript functions.

Using Data Collection

You can use Data Collection to collect AxisDataSignals with and without the transformation applied to determine the effect of the running transformation on motion.

The individual signals from before and after the transformations are applied depend on the type of transformation – inverse or forward.

  • Inverse transformation functions transform ProgramPosition in program-space to PositionCommandRaw in transformation-space.

  • Forward transformation functions transform PositionCommand and PositionFeedback in transformation-space to ProgramPositionCommand and ProgramPositionFeedback in program-space.

Refer to Controller Motion Signals for more information.

Using the printf() function

You can call printf() from within the transformation. But, Aerotech does not recommend this procedure because it can cause timing issues and real-time errors, which can cause incorrect motion. The statements should be as minimal as possible because larger print statements are more likely to cause errors.

If you use this procedure, call printf() a minimum of one time in the OnSetup() transformation function, which will open the INtime console window. If the INtime console window opens during motion execution, the system might become unstable.