Libraries

The base language contains things such as statements (if/while/repeat), operators and intrinsic functions (+, -, /, length()), labels, function declarations, and literals, among others. A library is a collection of functions, properties, and data types that can be used to extend the language. There are three different types of libraries that exist to extend the language:

Automation1 Standard Library
Aerotech-provided extending libraries
User-defined libraries

Library source files can be compiled into binary library files that can be imported (linked to) by source programs or other libraries. The binary library format allows libraries to be distributed without exposing their source code, making them ideal for protection of intellectual property. For more information, see Protect Your Intellectual Property.

Libraries can be imported to a program either statically or dynamically. With static linking, the code of the library functions is directly included in the final program executable. With this method, the executable can be distributed without needing to distribute the library as well because the executable has all of the information that it needs to be executed. With dynamic linking, the library must be loaded into the memory of the controller, and the program that linked to it can call functions from the library dynamically. This method is useful when multiple programs executing on the controller share the same library. This is also useful for calling functions in special cases such as from a program running from an immediate command.

Library Types

Automation1 Standard Library

The Standard Library is a collection of functions that comes standard with every Automation1 motion controller. This library can be used without explicitly including it in programs, and includes functions such as Enable(), Home(), and GearingOn(). Refer to the Automation1 help for or a complete list of functions that are included with AeroScript.

Aerotech Extending Libraries

Aerotech can provide extending libraries as a way to supplement the Standard Library. These libraries can consist of things that are provided along with a purchased option, or that don’t fit well into the Standard Library. For example, the following things could be placed into a library and provided on an as-needed basis.

Hexapod transformation library
Other customer-specific transformations

User-Defined Libraries

You can create your own AeroScript libraries as well. This ability is useful for if you have sets of functions that you use in various projects, allowing you to make your functions more modular. In addition, this is useful for OEMs that want to distribute libraries to end users with or without the source code.

Creating a Library

Libraries are constructed similarly to programs. However, a library cannot be executed directly like a program, therefore a library cannot contain a program block.

A library can contain program global variables to maintain state information. These variables cannot be accessed directly by consumers of the library. However, they can be accessed through library functions or properties.

var $value as integer

// Function to set the $value variable
library function SetValue($newValue as integer)
$value = $newValue
end

// Function to retrieve the $value variable
library function GetValue() as integer
return $value
end

The library keyword can be specified on the same line before function, property, struct, enum, and gcode declarations to export those concepts from the library. If the library keyword is not used with these declarations, then the concept is not exported from the library, but can still be used internally to the library. The code that follows shows an example of using the library keyword to export a function from a library, as well as omitting the library keyword to prevent a function from being exported.

// This function is visible for consumers of the library
library function MyAdd3($a as integer, $b as integer, $c as integer) as integer
return MyAdd2($a, MyAdd2($b, $c))
end

// This function is internal to the library and cannot be used directly by
// consumers of the library
function MyAdd2($a as integer, $b as integer)
return $a + $b
end

You can use the library keyword to add custom G-codes to libraries. See Custom G-Codes and M-Codes for more information. The example that follows shows how to use the library keyword to export a custom G-code.

var $C as real = 0

// Calling G300 A5 B20 will set $C to 25
library gcode G300
    if defined(A) && defined(B)
        $C = argument(A) + argument(B)
    else
        $C = -999.999
    end
end

If a function is exported from a library by using the library keyword, then all of its arguments (if specified) must have data types that are primitive data types (integer, real, axis, string, handle), or user-defined struct and enum data types that have also been exported with the library keyword. Refer to the example that follows for more information.

// This enum is visible for consumers of the library
library enum Suits
   Spades
   Hearts
   Clubs
   Diamonds
end

// This enum is internal to the library
enum Directions
   Up
   Down
   Left
   Right
end

// This is a valid exported function since the Suits type is exported
library function MyFunc1($arg as Suits)
   // ...
end

// This is not a valid exported function since the Directions type is internal
library function MyFunc2($arg as Directions)
   // ...
end

A similar concept can be applied to a property that is exported from a library with the library keyword. All property indices (if specified) must have data types that are primitive data types (integer, real, axis, string, handle), or user-defined struct and enum data types that have also been exported with the library keyword.

Finally, a similar concept can be applied to a struct that is exported from a library with the library keyword. All struct members must have data types that are primitive data types (integer, real, axis, string, handle), or user-defined struct and enum data types that have also been exported with the library keyword.

Using a Library

In order to use a library, you must import it into the program or other library from which you wish to call its functions. A library can be imported as either static or dynamic depending on your specific needs. The syntax for importing a library is as follows, where the name of the library is a compiled binary library file with the file extension .a1lib.

import "<LibraryName>" as static

import "<LibraryName>" as dynamic

All import statements must be placed at the program-level scope of a source file, outside of any program blocks, function blocks, or other block statements such as if, while, and repeat. When using import as dynamic, the dynamic library must be loaded onto the controller before the program that uses the library can call its functions; otherwise a runtime error will occur.

If a library imports another library, any functions, properties, structs, or enums that were exported from the imported library will not be exported from the importing library.

An example for writing a library and importing it into a program follows.

// Library source file (MyLibrary.ascriptlib)
library function SetAllAnalogOutputs($axis as axis, $voltage as real)
   AnalogOutputSet($axis, 0, $voltage)
   AnalogOutputSet($axis, 1, $voltage)
   AnalogOutputSet($axis, 2, $voltage)
   AnalogOutputSet($axis, 3, $voltage)
end

// Program source file
import "MyLibrary.a1lib" as static

SetAllAnalogOutputs(X, 2.5)
SetAllAnalogOutputs(Y, 2.5)
SetAllAnalogOutputs(Z, 2.5)
SetAllAnalogOutputs(U, 2.5)

Program Automation

The controller lets you automatically load and import libraries into other Automation1 programs or libraries though Program Automation. This feature lets you use libraries without explicit import statements.

For more information, see the Program Automation Module page. This module is part of the Develop workspace.

Next Topic: G-Code (RS-274) Support