Mastership

Mastership is the write lock of the controller. Only one client holds it at a time, and a client that does not hold it cannot change anything. Reading never needs it. The service is robot.Rws.Mastership.

The mastership belongs to the connection that took it. Every call made through the same AbbController is the holder. It stays held until you release it or until the connection ends.

Domains

The mastership is not global, it is taken per domain. MastershipDomain has four values, and the two controller generations do not cut the controller the same way.

You can ask for any of the four values on any controller. The service maps them onto the domains the connected controller really has. GetDomains tells you which ones it exposes.

AbbController robot = new AbbController();
robot.Connect("192.168.0.1");
// Domains the connected controller really exposes
foreach (MastershipDomain domain in robot.Rws.Mastership.GetDomains())
    Console.WriteLine(domain);

// Motion is needed to move a mechanical unit
robot.Rws.Mastership.Request(MastershipDomain.Motion);
robot.Rws.Mastership.Release(MastershipDomain.Motion);

// Edit covers the system parameters and the RAPID programs at once
robot.Rws.Mastership.Request(MastershipDomain.Edit);
robot.Rws.Mastership.Release(MastershipDomain.Edit);

// Without argument, every domain is taken and given back
robot.Rws.Mastership.Request();
robot.Rws.Mastership.Release();
robot.Disconnect();
}

Request and release

Request takes a domain, Release gives it back. Without argument, both work on every domain of the controller at once.

Take the mastership as late as possible and give it back as early as possible. While you hold it, the operator of the robot cannot change the same domain from the teach pendant. Put the release in a finally block, so a failed write does not leave the lock taken.

AbbController robot = new AbbController();
robot.Connect("192.168.0.1");
// Take the write lock of the RAPID domain
robot.Rws.Mastership.Request(MastershipDomain.Rapid);
try
{
    robot.Rws.Rapid.SetSymbolValue("RAPID/T_ROB1/user/reg1", "12");
    robot.Rws.Rapid.SetSymbolValue("RAPID/T_ROB1/user/reg2", "34");
}
finally
{
    // Give it back as early as possible, even when the write failed
    robot.Rws.Mastership.Release(MastershipDomain.Rapid);
}
robot.Disconnect();
}

A few points to know:

• Request fails when somebody else already holds the domain, and also when this connection already holds it.
• Release() without argument is accepted even when nothing is held. It is safe to call in a finally block.
• In manual mode, the controller only grants the mastership once the operator has given your client the right to act on their behalf.
• When a value of the enum covers several domains of the connected controller, Request takes them all. If one of them is refused, the parts already taken are given back before the error is reported.

Who holds the mastership

GetInfo returns a MastershipInfo per domain: who holds it, and whether it is this connection. HeldByMe is the property to test before a write.

AbbController robot = new AbbController();
robot.Connect("192.168.0.1");
// State of every domain of the controller
foreach (MastershipInfo info in robot.Rws.Mastership.GetInfo())
{
    Console.WriteLine($"{info.Domain} : holder {info.Holder}, held by me {info.HeldByMe}");
    Console.WriteLine($"  application {info.Application}, location {info.Location}");
}

// State of a single domain
MastershipInfo motion = robot.Rws.Mastership.GetInfo(MastershipDomain.Motion);

if (motion.Holder == MastershipHolder.None)
    Console.WriteLine("Motion is free, it can be taken");
else if (!motion.HeldByMe)
    Console.WriteLine("Somebody else holds Motion, a write would fail with 403");
robot.Disconnect();
}

Holder is a MastershipHolder: None when the domain is free, Remote for a client on the network, Local for a device attached to the controller like the teach pendant, Internal when the controller itself holds it during an operation that must not be interrupted.

Implicit mastership

Two operations take the mastership for you, use it for a single request and give it back immediately: Panel.SetSpeedRatio and Controller.Restart. This is the default. Pass false for the useImplicitMastership parameter when your own code already holds the mastership, otherwise the controller refuses the second request on a domain you already hold.

AbbController robot = new AbbController();
robot.Connect("192.168.0.1");
// The mastership is taken for this single call and given back right after
robot.Rws.Panel.SetSpeedRatio(50);

// Same behaviour for a restart of the controller
robot.Rws.Controller.Restart(ControllerRestartMode.Restart);

// Set the flag to false when your own code already holds the mastership
robot.Rws.Mastership.Request();
try
{
    robot.Rws.Panel.SetSpeedRatio(100, false);
}
finally
{
    robot.Rws.Mastership.Release();
}
robot.Disconnect();
}

Every other write operation needs an explicit Request.

What happens without mastership

The controller answers with the HTTP status code 403, and the SDK throws an RwsException with StatusCode set to 403. The same code is used when the user account lacks the UAS grant, so check the mastership state to tell the two cases apart.

AbbController robot = new AbbController();
robot.Connect("192.168.0.1");
try
{
    // No mastership taken, the controller refuses the write
    robot.Rws.Rapid.SetSymbolValue("RAPID/T_ROB1/user/reg1", "5");
}
catch (RwsException ex) when (ex.StatusCode == 403)
{
    // Find out who holds the domain
    MastershipInfo info = robot.Rws.Mastership.GetInfo(MastershipDomain.Rapid);
    Console.WriteLine($"{info.Domain} is held by {info.Holder} ({info.Application})");
}
robot.Disconnect();
}

Operations that need the mastership:

Try it in the demo application

Everything on this page can be tried without writing code, in the Mastership (RWS) page of the demo application.

The demo application is open source. The C# source of this page is RwsMastershipControl.cs.

API reference

// Gets the domains the connected controller can give the mastership of (synchronous)
MastershipDomain[] GetDomains();

// Gets who holds the mastership of every domain of the controller (synchronous)
MastershipInfo[] GetInfo();

// Gets who holds the mastership of one domain (synchronous)
MastershipInfo GetInfo(MastershipDomain domain);

// Gives back the mastership of every domain of the controller (synchronous)
void Release();

// Gives back the mastership of one domain (synchronous)
void Release(MastershipDomain domain);

// Takes the mastership of every domain of the controller (synchronous)
void Request();

// Takes the mastership of one domain (synchronous)
void Request(MastershipDomain domain);

Every method also exists in an asynchronous version, with the same name followed by Async and an optional CancellationToken.