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.
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. TheirRoutingproperty 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 thanProgram.*. - 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 programparameters.Routing.Prefer(new[] { FanucRoute.Snpx, FanucRoute.Cgtp });parameters.Routing.Set("Program.*", new[] { FanucRoute.TelnetKcl });// A protocol that the common API never usesparameters.Routing.Forbid(new[] { FanucProtocol.Rmi });// The same settings as text, for a configuration fileConsole.WriteLine(parameters.Routing.ToText());RobotController robot = new RobotController();robot.Connect(parameters);robot.Disconnect();}
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 filestring 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 interfaceforeach (string name in parameters.Routing.GetValidRoutes("Program.Start"))Console.WriteLine(name);RobotController robot = new RobotController();robot.Connect(parameters);robot.Disconnect();}
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.
| Brand | Route | Enable it with | Also needed |
|---|---|---|---|
| Fanuc | Rmi | parameters.Rmi.Enable = true | The controller option R912. |
| Universal Robots | InterpreterMode | parameters.InterpreterMode.Enable = true | The 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 itparameters.Rmi.Enable = true;RobotController robot = new RobotController();robot.Connect(parameters);// The moves now have a route, if the controller has the RMI optionRouteInfo route = robot.Routing.GetRoute("Motion.MoveJoint");Console.WriteLine(route.Available ? route.Route : route.Reason);robot.Disconnect();}
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 withEnable = truein the connection parameters is opened, unless it is forbidden.Enable = falsedoes not stop the test: useForbidto 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();}
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.
| Brand | Connection parameters | Routing class | Routes (Prefer, Set) | Protocols (Forbid) |
|---|---|---|---|---|
| Fanuc | UnderAutomation.Fanuc.ConnectionParameters | FanucRouting | FanucRoute | FanucProtocol |
| Yaskawa | UnderAutomation.Yaskawa.ConnectParameters | YaskawaRouting | YaskawaRoute | YaskawaProtocol |
| Universal Robots | UnderAutomation.UniversalRobots.ConnectParameters | UniversalRobotsRouting | UniversalRobotsRoute | UniversalRobotsProtocol |
| ABB | UnderAutomation.ABB.ConnectionParameters | AbbRouting | AbbRoute | AbbProtocol |
| Stäubli | UnderAutomation.Staubli.ConnectionParameters | StaubliRouting | StaubliRoute | StaubliProtocol |
Methods of the routing classes
| Method | What it does | Parameters |
|---|---|---|
Prefer | Sets the routes preferred for every method, in order of preference. | Array of routes of the brand |
Set | Sets the routes of a group or of one method, in order of preference. | string path, array of routes of the brand |
Forbid | Sets the protocols that the common API never uses. | Array of protocols of the brand |
SetText | Sets the routes of a path, as text. Empty removes the setting. | string path: "*", "!", a group or a method. string routes: names separated by commas |
LoadText | Replaces every setting with the settings of a text written by ToText. Empty removes every setting. | string text |
ToText | Returns the settings as text, in the order they were set. | None |
Clear | Removes every setting. | None |
GetValidPaths | Returns the paths that can be set. | None |
GetValidRoutes | Returns 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
| Value | Meaning |
|---|---|
Auto | Default. The library tests the protocols and keeps open the ones it needs. |
Explicit | The 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:
RouteUnavailableExceptionand the result of each protocol. - Motion: the moves, which need a manual route on some brands.