UnderAutomation
¿Una pregunta?

[email protected]

Contactos
UnderAutomation
⌘Q
Esta página solo está disponible en inglés.

Routing settings: prefer, set or forbid a protocol

Choose the route of each method of the common robot API: Prefer, Set, Forbid, text in a configuration file, manual routes and ProtocolSelection. C# and Python examples.

  • Prerequisites
  • How the settings are applied
  • Example
  • Prefer, set and forbid
  • Read the settings from a configuration file
  • Enable a manual route
  • Open only the protocols you enable
  • Reference
  • Routing classes of the brands
  • Methods of the routing classes
  • ProtocolSelection
  • What to read next

The routing settings choose which route each method of the common API uses on a Fanuc, Yaskawa, Universal Robots, ABB or Stäubli controller, instead of the default order of the brand. You set them in the connection parameters, in code or as a text from a configuration file, before Connect.

Prerequisites

  • The connection parameters of the brand SDK, for example UnderAutomation.Fanuc.ConnectionParameters. Their Routing property gives the settings of the brand. See Connect to your robot.
  • The names of the routes and of the protocols of the brand. See Which protocol for which task.
  • Without settings, the library chooses. The page Routing explains the default choice.

How the settings are applied

A setting is a list of routes in order of preference, for a path:

  • *: every method.
  • A group, for example Program.*. A group can have more levels: Program.Position.* is more specific than Program.*.
  • One method, for example Program.Start.
  • !: the protocols that the common API never uses.

For each method, the library builds one list: the routes of the setting of the method, then the routes of its groups (the most specific first), then the routes of *, then the default order of the brand. A route that the method does not have on this brand is skipped. The method takes the first route of this list whose protocol answered at Connect. When no route of a setting is usable, the next level is used.

The settings are read once, at Connect. To change them, change the parameters, then connect again. Paths and route names are not case sensitive. A path or route name with an invalid syntax throws ArgumentException when you set it. An unknown path or route throws ArgumentException at Connect, with the list of the valid ones.

Example

Prefer, set and forbid

Prefer sets the routes preferred for every method. Set sets the routes of a group or of one method. Forbid lists the protocols that the common API never uses, also when they are enabled in the connection parameters. An empty array removes the setting.

In Python, the methods that take an array of enum values do not work yet: use set_text, with "*" for Prefer and "!" for Forbid, as in the example.

static void Main()
{
ConnectionParameters parameters = new ConnectionParameters("192.168.0.1");
// Routes preferred for every method, then for the methods of the program
parameters.Routing.Prefer(new[] { FanucRoute.Snpx, FanucRoute.Cgtp });
parameters.Routing.Set("Program.*", new[] { FanucRoute.TelnetKcl });
// A protocol that the common API never uses
parameters.Routing.Forbid(new[] { FanucProtocol.Rmi });
// The same settings as text, for a configuration file
Console.WriteLine(parameters.Routing.ToText());
RobotController robot = new RobotController();
robot.Connect(parameters);
robot.Disconnect();
}
Click to see the full code

Read the settings from a configuration file

The settings have a text form: path=routes, separated by ;, with the routes separated by commas. ToText writes it and LoadText reads it back. RobotConnectionParameters.Create takes the brand, the address and this text: the three values can come from a configuration file.

*=Snpx,Cgtp; Program.*=TelnetKcl,CgtpKcl; Program.Start=CgtpKcl; !=Rmi

GetValidPaths and GetValidRoutes return the paths and the routes that you can set, for example to fill a list in a user interface.

static void Main()
{
// Brand, address and routing settings read from a configuration file
string brand = "fanuc";
string address = "192.168.0.1";
string routing = "Program.*=TelnetKcl,CgtpKcl; !=Snpx";
RobotConnectionParameters parameters = RobotConnectionParameters.Create(brand, address, routing);
// The routes that can be set for a method, for example to fill a list in a user interface
foreach (string name in parameters.Routing.GetValidRoutes("Program.Start"))
Console.WriteLine(name);
RobotController robot = new RobotController();
robot.Connect(parameters);
robot.Disconnect();
}
Click to see the full code

Enable a manual route

Some routes take control of the robot. The library never opens them by itself: they are marked (manual) in the tables of the documentation. Enable the protocol in the connection parameters of the brand. Until then, a method that has only this route throws RouteUnavailableException, and its message says what to enable.

BrandRouteEnable it withAlso needed
FanucRmiparameters.Rmi.Enable = trueThe controller option R912.
Universal RobotsInterpreterModeparameters.InterpreterMode.Enable = trueThe interpreter program running on the robot.
static void Main()
{
ConnectionParameters parameters = new ConnectionParameters("192.168.0.1");
// RMI takes the motion control of the controller: the library opens it only when you enable it
parameters.Rmi.Enable = true;
RobotController robot = new RobotController();
robot.Connect(parameters);
// The moves now have a route, if the controller has the RMI option
RouteInfo route = robot.Routing.GetRoute("Motion.MoveJoint");
Console.WriteLine(route.Available ? route.Route : route.Reason);
robot.Disconnect();
}
Click to see the full code

Open only the protocols you enable

ProtocolSelection tells how the protocols are opened at Connect:

  • Auto (default): the library tests the protocols of the brand one by one and keeps open the ones that a method needs. The protocols named in the settings are tested first. A protocol with Enable = true in the connection parameters is opened, unless it is forbidden. Enable = false does not stop the test: use Forbid to keep the library away from a protocol.
  • Explicit: the library opens the protocols enabled in the connection parameters, with the default values of the brand SDK, and nothing else. The settings still choose among the open protocols.
static void Main()
{
ConnectionParameters parameters = new ConnectionParameters("192.168.0.1");
// Auto (default): the library tests the protocols and keeps the ones it needs.
// Explicit: the library opens the protocols enabled in the parameters, and nothing else.
parameters.Routing.ProtocolSelection = ProtocolSelection.Explicit;
parameters.Rmi.Enable = false;
RobotController robot = new RobotController();
robot.Connect(parameters);
robot.Disconnect();
}
Click to see the full code

Reference

In Python, the names are in snake_case: parameters.routing.set_text(...), load_text(...), to_text(), get_valid_routes(...), protocol_selection. The enum members keep their names.

Routing classes of the brands

The Routing property of the connection parameters of each brand has the type of the brand. The route and protocol enums are in the namespace UnderAutomation.Robotics.Adapter.<Brand>. RobotConnectionParameters.Routing, the same object seen from the base class, is a RoutingSettings: it has no Prefer, Set and Forbid.

BrandConnection parametersRouting classRoutes (Prefer, Set)Protocols (Forbid)
FanucUnderAutomation.Fanuc.ConnectionParametersFanucRoutingFanucRouteFanucProtocol
YaskawaUnderAutomation.Yaskawa.ConnectParametersYaskawaRoutingYaskawaRouteYaskawaProtocol
Universal RobotsUnderAutomation.UniversalRobots.ConnectParametersUniversalRobotsRoutingUniversalRobotsRouteUniversalRobotsProtocol
ABBUnderAutomation.ABB.ConnectionParametersAbbRoutingAbbRouteAbbProtocol
StäubliUnderAutomation.Staubli.ConnectionParametersStaubliRoutingStaubliRouteStaubliProtocol

Methods of the routing classes

MethodWhat it doesParameters
PreferSets the routes preferred for every method, in order of preference.Array of routes of the brand
SetSets the routes of a group or of one method, in order of preference.string path, array of routes of the brand
ForbidSets the protocols that the common API never uses.Array of protocols of the brand
SetTextSets the routes of a path, as text. Empty removes the setting.string path: "*", "!", a group or a method. string routes: names separated by commas
LoadTextReplaces every setting with the settings of a text written by ToText. Empty removes every setting.string text
ToTextReturns the settings as text, in the order they were set.None
ClearRemoves every setting.None
GetValidPathsReturns the paths that can be set.None
GetValidRoutesReturns the routes of the brand that can be set for a path, in the default order. For "!", the protocols of the brand.string path

Prefer, Set and Forbid are on the classes of the brands. The other methods are on RoutingSettings. LoadText, ToText and Clear do not change ProtocolSelection.

ProtocolSelection

ValueMeaning
AutoDefault. The library tests the protocols and keeps open the ones it needs.
ExplicitThe library opens the protocols enabled in the connection parameters, and nothing else.

ProtocolSelection is read by RobotController.Connect only. The classes of the brand SDKs, for example FanucRobot, ignore the routing settings.

What to read next

  • Routing: read the route that each method uses, and why.
  • Which protocol for which task: the route names of each brand.
  • Errors: RouteUnavailableException and the result of each protocol.
  • Motion: the moves, which need a manual route on some brands.