Configuration

The Basics

In the .NET API, Configuration lets you change various aspects of the controller behavior. These changes do not have an effect until the next controller reset.

Aerotech recommends that you use Machine Setup in Studio to configure your controller. See the Configure Workspace page.

You can configure the following items for your Automation1 controller through the .NET API:

• 1D Calibration
• 2D Calibration
• Controller Name
• Controller Start Up
• Galvo 2D Calibration
• Galvo Power Correction
• HyperWire Card
• HyperWire Communication
• Parameters
• Program Automation
• Industrial Ethernet

How to Use

All configuration items are accessed through the Controller.Configuration property. Each configuration item has a corresponding property that then has GetConfiguration and SetConfiguration methods. You can get a configuration item, inspect it, modify it, and set it. If a configuration item has never been set, the GetConfiguration method will throw an exception. Refer to the example that follows.

CalibrationFile calibrationFile1D = controller.Configuration.Calibration1DFile.GetConfiguration();
CalibrationFile calibrationFile2D = controller.Configuration.Calibration2DFile.GetConfiguration();
ConfiguredParameters configuredParameters = controller.Configuration.Parameters.GetConfiguration();
ConfiguredProgramAutomation configuredProgramAutomation = controller.Configuration.ProgramAutomation.GetConfiguration();
ConfiguredIndustrialEthernet configuredIndustrialEthernet =
controller.Configuration.IndustrialEthernet.GetConfiguration();

controller.Configuration.Calibration1DFile.SetConfiguration(CalibrationFile value);
controller.Configuration.Calibration2DFile.SetConfiguration(CalibrationFile value);
controller.Configuration.Parameters.SetConfiguration(ConfiguredParameters value);
controller.Configuration.ProgramAutomation.SetConfiguration(ConfiguredProgramAutomation value);
controller.Configuration.IndustrialEthernet.SetConfiguration(ConfiguredIndustrialEthernet value);

Configured Parameters

Controller parameters dictate how the controller behaves and they are categorized into axis, task, and system categories. See The Three Controller Categories: Axis, Task, and System. Axis controller parameters configure things like units, axis names, and jog speeds and are dependent on the electrical and mechanical device that make up that axis. Task controller parameters configure things like task-based coordinated motion. System controller parameters configure things like memory allocation and communication.

In general, you should not need to change the controller parameters that are already configured. Usually, the parameters that Machine Setup gives you are what you will always want to use.

Changes to Active Parameters are not persisted and the active controller parameter values are lost after a controller reset. You can change most of the controller parameters at runtime. But there are some parameters that you can change only in the configured parameters. These parameters require a controller reset before they have an effect.

Controller parameters have different data types. They are either 32-bit integers, single-precision floating-point numbers, double-precision floating-point numbers, or strings.

Example Code

This example program shows you how to do the operations that follow:

• Get the currently configured parameters from your controller.
• Change the values of configured parameters.
• Set the configured parameters on your controller.

1
2
3
4
5
6
7
8
// Get the current configured controller parameters. This will throw an exception if parameters are not configured.
ConfiguredParameters configuredParameters = controller.Configuration.Parameters.GetConfiguration();
 
// Modify X axis MaxJogSpeed.
configuredParameters.Axis["X"].Motion.MaxJogSpeed.Value = 1.0;
 
// Set the modified controller parameters to be used on the next controller reset.
controller.Configuration.Parameters.SetConfiguration(configuredParameters);

Configured Program Automation

In the .NET API, Configured Program Automation gives you a way to:

• Configure compiled AeroScript programs to load or run automatically on a task when the controller starts.

• Configure AeroScript source files to be included automatically when compiling other AeroScript programs and libraries.

• Configure AeroScript libraries to be loaded and automatically imported when compiling other AeroScript programs and libraries.

Configured Program Automation in the .NET API uses the ConfiguredProgramAutomation class. You can construct a new instance of this class, or you can use the Controller.Configuration.ProgramAutomation.GetConfiguration() method to get an instance of this class that has the current program automation configuration of the controller.

To configure an AeroScript program to automatically load or run on a task when the controller starts, add a new ConfiguredProgramAutomation.CompiledProgram instance to the ConfiguredProgramAutomation.CompiledProgramsToLoad or the ConfiguredProgramAutomation.CompiledProgramsToRun list. A compiled program must be loaded or run on a task. One task cannot load or run more than one compiled program at a time.

To configure an AeroScript source file to be included automatically during AeroScript compilation, add a new ConfiguredProgramAutomation.ProgramSourceFile instance to the ConfiguredProgramAutomation.ProgramSourceFilesToInclude list. If you include an AeroScript source file, you will expose all preprocessor directives defined in the source file to the program being compiled. For more information, see the Preprocessor page.

To configure a compiled AeroScript library to be loaded onto the controller, add a new ConfiguredProgramAutomation.CompiledLibrary instance to the ConfiguredProgramAutomation.CompiledLibrariesToLoad list. When a compiled AeroScript library is loaded onto the controller, it can be imported dynamically. For more information, see Libraries. When you create the ConfiguredProgramAutomation.CompiledLibrary instance and shouldAutoImport is set to true, the compiled library will import automatically during AeroScript compilation.

Example Code

This example program shows you how to do the operations that follow:

• Get the currently configured program automation from your controller.
• Add new compiled programs, source files, and compiled libraries.
• Set the configured program automation on your controller.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Get the current configured program automation from the controller. This will throw an exception if Program Automation is not configured.
ConfiguredProgramAutomation configuredProgramAutomation = controller.Configuration.ProgramAutomation.GetConfiguration();

// NOTE: The following code modifies the currently configured program automation. If you wish to start from scratch, create a new ConfiguredProgramAutomation instance.

// Add a compiled program to automatically run on task 2 whenever the controller starts.
configuredProgramAutomation.CompiledProgramsToRun.Add(new ConfiguredProgramAutomation.CompiledProgram("/compiledprogram.a1exe", 2));

// Add a program source file to automatically include during AeroScript compilation.
configuredProgramAutomation.ProgramSourceFilesToInclude.Add(new ConfiguredProgramAutomation.ProgramSourceFile("/sourcefile.ascript"));

// Add a compiled library that will be automatically imported during AeroScript compilation.
configuredProgramAutomation.CompiledLibrariesToLoad.Add(new ConfiguredProgramAutomation.CompiledLibrary("/compiledlibrary.a1lib", true));

// Set the configuration on the controller.
controller.Configuration.ProgramAutomation.SetConfiguration(configuredProgramAutomation);

Configured Industrial Ethernet

In the .NET API, Configured Industrial Ethernet lets you configure Industrial Ethernet connections and mappings. Automation1 exposes the memory blocks of Industrial Ethernet protocols, such as Modbus, EtherCAT, and EtherNet/IP through Industrial Ethernet mappings. These Industrial Ethernet mappings let you map memory regions used by Industrial Ethernet protocols to arbitrary controller data types. For more information, see Modbus TCP/IP Overview, EtherCAT Overview, and EtherNet/IP Overview.

Configured Industrial Ethernet in the .NET API uses the ConfiguredIndustrialEthernet class. You can use the Controller.Configuration.IndustrialEthernet.GetConfiguration() method to get an instance of this class that has the current Industrial Ethernet configuration of the controller.

To configure an Industrial Ethernet connection on an Automation1 controller, make a new instance of the Industrial Ethernet connection and pass it as an argument to the ConfiguredIndustrialEthernet constructor. For example, to configure a Modbus Server, make a new instance of the ConfiguredIndustrialEthernet.ModbusServerConnection class and pass it as an argument to the ConfiguredIndustrialEthernet constructor.

After you set the Industrial Ethernet configuration on the Automation1 controller and reset the controller, you can get and set the values of individual Industrial Ethernet mappings on the controller with the Controller Variables API.

Example Code

This example program shows you how to do the operations that follow:

• Configure a Modbus Server connection with multiple registers that map to different memory regions of the Modbus Server.

• Set the configured Industrial Ethernet on your controller.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Construct a Modbus Server register to map to a memory region on the Modbus Server connection.
ConfiguredIndustrialEthernet.ModbusRegister registerA = new ConfiguredIndustrialEthernet.ModbusRegister(ModbusRegisterType.InputWords, "RegisterA", 0, 0, 1, "Register A Comment", ModbusRegisterDataType.UInt32);

// Construct another Modbus Server register to map to a different memory region on the Modbus Server connection.
ConfiguredIndustrialEthernet.ModbusRegister registerB = new ConfiguredIndustrialEthernet.ModbusRegister(ModbusRegisterType.OutputBits, "RegisterB", 16, 8, 10, "Register B Comment", ModbusRegisterDataType.Bit);

// Construct the Modbus Server connection with the registers we have created.
ConfiguredIndustrialEthernet.ModbusServerConnection modbusServer = new ConfiguredIndustrialEthernet.ModbusServerConnection("MyModbusServer", 1, new List<ConfiguredIndustrialEthernet.ModbusRegister> { registerA, registerB });

// Construct the Industrial Ethernet configuration to set on the controller and pass in the Modbus Server connection as an argument.
ConfiguredIndustrialEthernet configuredIndustrialEthernet = new ConfiguredIndustrialEthernet(modbusServer);

// Set the configuration on the controller.
controller.Configuration.IndustrialEthernet.SetConfiguration(configuredIndustrialEthernet);

This example program shows you how to do the operations that follow:

• Configure multiple Modbus Client connections with multiple registers that map to different memory regions on the Modbus clients.

• Set the configured Industrial Ethernet on your controller.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Construct a Modbus register to map to a memory region on a Modbus Client connection.
ConfiguredIndustrialEthernet.ModbusRegister registerA = new ConfiguredIndustrialEthernet.ModbusRegister(ModbusRegisterType.InputWords, "RegisterA", 0, 0, 1, "Register A Comment", ModbusRegisterDataType.UInt32);

// Construct another Modbus register to map to a different memory region on a Modbus Client connection.
ConfiguredIndustrialEthernet.ModbusRegister registerB = new ConfiguredIndustrialEthernet.ModbusRegister(ModbusRegisterType.OutputBits, "RegisterB", 16, 8, 10, "Register B Comment", ModbusRegisterDataType.Bit);

// Construct the Modbus Client connection with the registers we have created.
ConfiguredIndustrialEthernet.ModbusClientConnection modbusClient1 = new ConfiguredIndustrialEthernet.ModbusClientConnection("ModbusClient1", 1, "192.1.17.123", 5050, new List<ConfiguredIndustrialEthernet.ModbusRegister> { registerA, registerB });

// Construct a Modbus register to map to a memory region on a second Modbus Client connection. Register names must be unique across Industrial Ethernet connections.
ConfiguredIndustrialEthernet.ModbusRegister registerC = new ConfiguredIndustrialEthernet.ModbusRegister(ModbusRegisterType.OutputWords, "RegisterC", 0, 0, 2, "Register C Comment", ModbusRegisterDataType.Float64);

// Construct a second Modbus Client connection with the register we just created.
ConfiguredIndustrialEthernet.ModbusClientConnection modbusClient2 = new ConfiguredIndustrialEthernet.ModbusClientConnection("ModbusClient2", 2, "192.1.20.123", 12345, new List<ConfiguredIndustrialEthernet.ModbusRegister> { registerC });

// Construct the Industrial Ethernet configuration to set on the controller and pass in the two Modbus client connections as an argument.
ConfiguredIndustrialEthernet configuredIndustrialEthernet = new ConfiguredIndustrialEthernet(new List<ConfiguredIndustrialEthernet.ModbusClientConnection> { modbusClient1, modbusClient2});

// Set the configuration on the controller
controller.Configuration.IndustrialEthernet.SetConfiguration(configuredIndustrialEthernet);

Thread Safety

The Controller.Configuration property is not thread safe. Only one thread at a time can access this property. If it is necessary for two or more threads to access or modify this property, you must use locks to limit the access.