Accessing the controller

Controller object

By using a Controller object you can get access to the different domains of the robot controller, for example I/O signals, RAPID, file system and elog messages.

To create a Controller object you normally make a call to the Controller.Connect() method:

ControllerInfo info = new ControllerInfo(new Guid("systemid"));
Controller aController = Controller.Connect(info, ConnectionType.Standalone, validateServerCertificate: true);

The ControllerInfo object, may have been retrieved during a network scan, see NetworkScanner. It is also possible to add an optional argument if the IP address of the controller or the system ID (guid) should be used. The connectionType type argument can be used to access a connection that was already established in RobotStudio, or if we want a new standalone connection. The validateServerCertificate argument can be used for OmniCore controllers to validate SSL certificates which is essential for secure communication.

The Controller.OnCertificateError event can be used to handle unverified certificates and will trigger upon connection if there are any certificate errors.

Controller.OnCertificateError += (sender, e) =>
{
    var result = MessageBox.Show(
     $"Do you want to accept the certificates?",
     e.ControllerName + ": Certificate verification required!",
     MessageBoxButtons.YesNo,
     MessageBoxIcon.Question);

    e.Response = result == DialogResult.Yes
        ? CertificateErrorResponse.AcceptOnce
        : CertificateErrorResponse.Reject;
};

If the PC application is supposed to work with a single controller it can be specified in an App.config file. The default constructor can then be used to create the controller object, for example aController = new Controller(). For more information, see .

If several classes in your application need to access the controller, it is recommended that they all reference the same Controller object. This is done either by passing the Controller object as an argument to the constructor or by using a Controller property.

Note

You should be aware that the .NET objects created for operations toward the robot controller will access native resources (C++ and COM code). The .NET garbage collector does not collect such objects, but these must be disposed of explicitly by the application programmer.

Memory management in PC applications

An important feature of the .NET runtime environment is the garbage collector, which reclaims not referenced memory from the managed heap. Generally, this means that the programmer does not have to free memory that has been allocated by the use of new. There is no way of knowing exactly when garbage collection will be performed however.

For a PC application indeterministic deallocation of resources is usually not a problem (as opposed to a FlexPendant application, which runs on a small device with limited memory). The IDispose interface, however, can be used in a PC application to obtain deterministic deallocation of resources. Using this interface you can make an explicit call to the Dispose method of any disposable object.

If your application is running in a Single Threaded Apartment (STA) the Dispose call will dispose of managed objects, but native resources (created internally by the PC SDK) will remain. To release these native objects, the method ReleaseUnmanagedResources should be called periodically, for example when you click a certain button or each time data has been written to the controller. The method call is not expensive.

For an application running in a Multi Threaded Apartment (MTA) the Dispose call will remove both managed and native objects.

Note

The method Controller.ReleaseUnmanagedResources should be called once in a while to avoid memory leaks in PC SDK applications running in STA.

The method Controller.ReleaseUnmanagedResources is obsolete and it must not be used from PC SDK 5.60.

Dispose

It is the creator of a disposable object that is responsible for its lifetime and for calling Dispose. A check should be done that the object still exists and any subscriptions to controller events should be removed before the Dispose call. This is how you dispose of a Controller object:

if (aController != null)
{
    aController.Dispose();
    aController = null;
}

Logon and logoff

Before accessing a robot controller, the PC SDK application has to log on to the controller. The UserInfo parameter of the Logon method has a DefaultUser property that can be used. By default all robot systems have such a user configured.

aController.Logon(UserInfo.DefaultUser);

If it is necessary for your application to handle users with different rights, these users can be configured by using the UserAuthorizationManagement namespace or by using the UAS administration tool in RobotStudio. This is how you create a new UserInfo object for login purposes.

UserInfo aUserInfo = new UserInfo("name", "password");

Note

It is necessary to log off from the controller at application shut down at the latest. aController.LogOff();

Mastership

In order to get write access to some of the controller domains the application has to request mastership. The Rapid domain, that is, tasks, programs, modules, routines and variables that exist in the robot system, is one such domain. The Configuration domain is another.

For more information, see Mastership.

It is important to release mastership after a modification operation. One way of doing this is applying the using statement, which results in an automatic disposal of the Mastership object at the end of the block. Another possibility is releasing mastership in a Finally block, which is executed after the Try and Catch blocks. See how it can be coded in the examples of Start program execution.

Controller events

The Controller object provides several public events, which enable you to listen to operating mode changes, controller state changes, mastership changes and so on.

aController.OperatingModeChanged +=
    new EventHandler<OperatingModeChangeEventArgs>(OperatingModeChanged);
aController.StateChanged += new EventHandler<StateChangedEventArgs>(StateChanged);
aController.ConnectionChanged +=
    new EventHandler<ConnectionChangedEventArgs>(ConnectionChanged);

Note

Controller events use their own threads. Carefully study Controller events and threads to avoid threading conflicts.

Caution

When setting up/activating a controller event, you may or may not receive an initial event as there is no guarantee that an event will be triggered. Hence you must read the initial state from the controller.

Backup and Restore

Using the Controller object you can call the Backup method. The argument is a string describing the directory path on the controller where the backup should be stored. You can also restore a previously backed up system. This requires mastership of Rapid and Configuration and can only be done in Auto mode.

Backup sample

As the backup process is performed asynchronously you can add an event handler to receive a BackupCompleted event when the backup is completed. The backup directory should be created in the system backup directory, or else an exception will be thrown.

string backupDir = "(BACKUP)$" + backupDirName;
this.aController.BackupCompleted +=
    new EventHandler<BackupEventArgs>(aController_BackupCompleted);
this.aController.Backup(backupDir);

Restore sample

The Restore method is synchronous, that is, execution will not continue until the restore operation is completed.

string restoreDir = "(BACKUP)$" + dirName;
using (Mastership mc = Mastership.Request(this.aController.Configuration),
    mr = Mastership.Request(this.aController.Rapid))
{
    this.aController.Restore(restoreDir, RestoreIncludes.All,
    RestoreIgnores.All);
}

Note

You need to be logged in with required grants to perform the above functions.

VirtualPanel

You can programmatically change the operating mode of the virtual controller using the VirtualPanel class and its ChangeMethod method. This blocks the application thread until you manually accept the mode change to Auto using the Virtual FlexPendant. An alternative to blocking the application thread eternally is to add a time-out and use a try-catch block to catch the TimeoutException.

VirtualPanel vp = VirtualPanel.Attach(aController);
try
{
    //user need to acknowledge mode change on flexpendent
    vp.ChangeMode(ControllerOperatingMode.Auto, 5000);
}
catch (ABB.Robotics.TimeoutException ex)
{
    this.textBox1.Text = "Timeout occurred at change to auto";
}
vp.Dispose();

There are also the asynchronous method calls BeginChangeOperatingMode and EndChangeOperatingMode. It is important to use the second method in the callback since it returns the waiting thread to the thread-pool.

VirtualPanel vp = VirtualPanel.Attach(aController);
vp.BeginChangeOperatingMode(ControllerOperatingMode.Auto, new AsyncCallback(ChangedMode), vp);

The callback method must have the following signature and call the EndChangeOperatingMode as well as dispose the VirtualPanel.

private void ChangedMode(IAsyncResult iar)
{
    VirtualPanel vp = (VirtualPanel) iar.AsyncState;
    vp.EndChangeOperatingMode(iar);
    vp.Dispose();
    //....some code
}

Learn more

This Application manual only covers some of the PC SDK functionality. To get the full potential of the PC SDK you should make use of the API Reference.

You can be an active learner by becoming a member of the User Forums. The Developer Tools should be your first priority for resolving any coding issues. For more information, see User Forum.