Transformation Functions

The Automation1 controller supplies two methods that you can use to apply geometric and kinematic transformations to motion profiles:

• The Matrix Transformation feature supplies rotation, mirror, and translation transformations through the AeroScript API.
• The C Transformation feature lets you run custom real-time C code in a motion program.

The table that follows shows which transformations are available based on the controller type.

Table: Transformation Features and Controller Types

This page tells you about the APIs, development environment, and concepts necessary 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

Two or more independently defined transformations can be chained together so that the output of one transformation is the input of another. You can do this 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 on a different 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 about 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, Freerun, Jog, PT, and PVT motion commanded to these axes will be transformed. Input and output axes might overlap.

Output Axes

The transformation will modify the position and velocity of these axes. Input and output axes might 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 the 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

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.

Matrix Transformation 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.

MatrixCreateTranslate() Overloads

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])

C Transformation

The C Transformation feature lets you build custom C transformations that 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 on the controller:

1. Create or get a compiled C transformation.
2. Set up the C Transformation Configuration.
3. Create motion programs that use C Transformation AeroScript Functions.

The C Transformation feature has these core design elements:

• Performance  Custom C code executes in real time on the controller and can operate at any Position Update Rate supported by the controller.
• Parametrization  A single defined transformation can specify a maximum of 128 Properties, which are used to set up the transformation for multiple configurations.
• Modularity
  • A C transformation is defined in a compiled library file. This library file can be copied to any system. Also, the same library file can be reused by multiple configurations in the same system. This lets motion developers at Aerotech or an OEM develop custom transformations for distribution to end users.
  • C transformations access motion data by using transformation axis indices. Transformation axis indices are indexed starting at 0. They increment 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. Also, the CTransformationLibrary API supplies functions to get the controller axis for a specified transformation axis. This feature lets a predefined C transformation be independent of the controller axes. Thus you can configure any transformation 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 laser output

C Development Environment

This section tells you how to configure a development environment that lets you build custom C transformations to use with Automation1.

Aerotech recommends that you use virtual axes while you develop and debug C Transformations. This prevents incorrect motion from being commanded to physical drives or motors connected to your controller. For information about how to configure virtual axes, see Virtual Axis Overview.

Get the CTransformation Example Project

The C Transformation example project and its dependencies are supplied within the Automation1 installation directory (C:\Program Files\Aerotech\Automation1-MDK) in the CTransformation folder. You can move the CTransformation folder to any location.

Dependencies

On PC-based and drive-based controllers, a C Transformation project requires the dependencies that follow:

• CTransformationLibrary, which is supplied in CTransformation\Library and CTransformation\Include.

On PC-based controllers only, a C Transformation project requires the additional dependencies that follow:

• INtime CDEV Library, which is supplied in CTransformation\INtime\Library and CTransformation\INtime\Include.

For PC-based controllers, the supplied Visual Studio example project is configured with the two dependencies.

To build the example project for your controller platform, refer to the procedures that follow.

Building for PC-based Controllers with MSBuild and Visual Studio Build Tools 2019

1. Get and run the Visual Studio Build Tools 2019 installer.
   1. Select C++ build tools.
2. Extract the contents of CTransformation\Platforms\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:

   msbuild /property:Configuration=Release

Building for PC-based Controllers with Visual Basic Professional 2019

1. Get and run the Visual Studio Professional installer.
   1. Select Desktop development with C++.
2. Extract the contents of CTransformation\Platforms\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. To open the project in Visual Studio, double-click the CTransformationRotation.sln solution file.
   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.

Building for Drive-based Controllers with GCC

1. Go to the ARM Developer website and download the ARM GNU compiler toolchain that applies the host architecture on your development system. You must download the toolchain for the AArch32 GNU/Linux target with hard float (arm-none-linux-gnueabihf).
2. Install the cross-compiler. Add the installation to your PATH manually. The installation directory is C:\Program Files (x86)\Arm GNU Toolchain arm-none-linux-gnueabihf\13.3 rel1\bin by default.

WARNING: Do not select the Add path to environment variable option. If you install the cross-compiler for Windows hosts, this option can compromise your system’s PATH environment variable. If this occurs, other programs installed on your computer might not operate correctly.

FOR A LINUX HOST OR WINDOW SUBSYSTEM FOR LINUX (WSL)

If you are using a Linux host or Windows Subsytem for Linux (WSL), you can also install this toolchain with a Linux package manager. Use the command that follows:

Copy

sudo apt install g++-arm-linux-gnueabihf

IMPORTANT: If you install the cross-compiler toolchain for a Linux host or WSL, the name of the compiler program will be different from the name shown in these instructions. In this case, use arm-linux-gnueabihf-gcc instead of arm-none-linux-gnueabihf-gcc in the commands that follow.

3. Navigate to CTransformation\Examples\CTransformationRotation.
4. Open a Windows Command Prompt in this directory. If you are using a Linux host, open the default terminal.
5. Execute the command that follows:
Copy
arm-none-linux-gnueabihf-gcc transformation.c -I ../../Include -L ../../Library/Drive-based/ -lm -lctransformationlibrary -fPIC -shared -ffast-math -mcpu=cortex-a15 -mtune=cortex-a15 -marm -mfloat-abi=hard -mfpu=neon-vfpv4 -W"l,-e,_init,-z,now,-z,relro,-z,noexecstack" -o libctransformationrotation.so

For more information about the options that you can use when you compile with GCC, see the GCC documentation.

C Transformation User Defined Functions API

This API supplies 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().

CTransformationLibrary API

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

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 library file in a motion program, you must add a C Transformation configuration file to the controller. For more information about the configuration file, refer to the section that follows.

C Transformation Configuration File Format

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

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 CTransformationRotation project. Do the option that applies to your controller:
• For PC-based controllers, build the Visual Studio project with the Release build configuration. For instructions about how to do this, refer to the Building for PC-based Controllers with MSBuild and Visual Studio Build Tools 2019 or Building for PC-based Controllers with Visual Basic Professional 2019 section of this page.
• For drive-based controllers, refer to the Building for Drive-Based Controllers with GCC section of this page.
2. Create a new text file and paste the content that follows into it. Save the file as a .config file.

IMPORTANT: For drive-based controllers, change the value of the <FileName> attribute from CTransformationRotation.rsl to libctransformationrotation.so. Do this in the content that follows.

Copy

<?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. Then issue the connect command that follows based on your controller configuration:
• If you are connecting to a local PC-based controller, issue the command that follows.

connect

• If you are connecting to a PC-based or drive-based controller remotely, issue the command that follows. Make sure that you change the IP address in the command to match the IP address of the controller to which you want to remotely connect.

connect --ip 192.168.1.2

• If you are using a drive-based controller that is connected over USB, issue the command that follows.

connect --usb

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

For a PC-based controller, issue the command that follows:

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

For a drive-based controller, issue the command that follows:

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

If you moved the example project to a different location on your PC, replace the C:\Program Files\Aerotech\Automation1-MDK\CTransformation\Examples\CTransformationRotation\ path with the path to the new location of the example project.

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. Replace [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.

config ctransformation set [path to configuration file]

IMPORTANT: The command in this step overwrites any existing configuration. If you apply any configuration changes, you must reset the controller.

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

initialize full

C Transformation AeroScript Functions

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

Debugging a C Transformation

There are several methods that you can use to debug a running C Transformation:

• Use AeroScript functions to interrogate the transformation.
• Use Data Collection to compare signals with and without the transformation applied.
• Use 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 lets you 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 might 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 you to use 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.

See Controller Motion Signals for more information.

Using the printf() Function

You can call printf() from within a C 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.

The output from any printf() statements that you include in your C Transformations is printed to the log file CTransformation.log on the controller. This log file is included automatically in the export file that you download from the Automation1 Status Utility. See Download an Export File for more information. You can also retrieve the log file by using the Automation1 Console command that follows. Replace [path to output directory] with the path to a directory on your PC where you want the log file to be downloaded.

On PC-based controllers, you can also configure printf() statements to output to the INtime console. This causes an INtime console window to open. Then a printf() output comes into view in that console window instead of in the controller log file. To do this, use the Automation1 Console command that follows.

To reset this configuration so that printf() statements print their output to the controller log file, use the Automation1 Console command that follows.

If you use the printf() function in your C Transformations, call printf() a minimum of one time in the OnSetup() transformation function. This makes sure that the controller log file or INtime console is configured for output during the controller reset. If you configured the -LOGTOSCREEN argument so that printf() statements output to the INtime console, this will also open the INtime console window.