---
title: "Routing settings: prefer, set or forbid a protocol"
description: "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."
---

# Routing settings: prefer, set or forbid a protocol

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](/robotics/documentation/connect).
- The names of the routes and of the protocols of the brand. See [Which protocol for which task](/robotics/documentation/which-protocol-for-which-task).
- Without settings, the library chooses. The page [Routing](/robotics/documentation/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.

**C# : RoutingPrefer**
```csharp
using UnderAutomation.Fanuc;
using UnderAutomation.Robotics.Adapter.Fanuc;
using UnderAutomation.Robotics.Controllers;

public class RoutingPrefer
{
    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();
    }
}
```

**Python : RoutingPrefer**
```python
from underautomation.fanuc.connection_parameters import ConnectionParameters
from underautomation.robotics.controllers.robot_controller import RobotController

##
parameters = ConnectionParameters("192.168.0.1")

# Routes preferred for every method, then for the methods of the program
parameters.routing.set_text("*", "Snpx, Cgtp")
parameters.routing.set_text("Program.*", "TelnetKcl")

# A protocol that the common API never uses
parameters.routing.set_text("!", "Rmi")

# The same settings as text, for a configuration file
print(parameters.routing.to_text())

robot = 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.

```text
*=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.

**C# : RoutingText**
```csharp
using UnderAutomation.Robotics.Controllers;

public class RoutingText
{
    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();
    }
}
```

**Python : RoutingText**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

##
# Brand, address and routing settings read from a configuration file
brand = "fanuc"
address = "192.168.0.1"
routing = "Program.*=TelnetKcl,CgtpKcl; !=Snpx"

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
for name in parameters.routing.get_valid_routes("Program.Start"):
    print(name)

robot = 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. |

**C# : RoutingManual**
```csharp
using UnderAutomation.Fanuc;
using UnderAutomation.Robotics.Controllers;

public class RoutingManual
{
    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();
    }
}
```

**Python : RoutingManual**
```python
from underautomation.fanuc.connection_parameters import ConnectionParameters
from underautomation.robotics.controllers.robot_controller import RobotController

##
parameters = 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

robot = RobotController()
robot.connect(parameters)

# The moves now have a route, if the controller has the RMI option
route = robot.routing.get_route("Motion.MoveJoint")
print(route.route if route.available else 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 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.

**C# : RoutingProtocolSelection**
```csharp
using UnderAutomation.Fanuc;
using UnderAutomation.Robotics.Controllers;

public class RoutingProtocolSelection
{
    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();
    }
}
```

**Python : RoutingProtocolSelection**
```python
from underautomation.fanuc.connection_parameters import ConnectionParameters
from underautomation.robotics.controllers.protocol_selection import ProtocolSelection
from underautomation.robotics.controllers.robot_controller import RobotController

##
parameters = 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.protocol_selection = ProtocolSelection.Explicit
parameters.rmi.enable = False

robot = 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](/robotics/documentation/routing): read the route that each method uses, and why.
- [Which protocol for which task](/robotics/documentation/which-protocol-for-which-task): the route names of each brand.
- [Errors](/robotics/documentation/errors): `RouteUnavailableException` and the result of each protocol.
- [Motion](/robotics/documentation/motion): the moves, which need a manual route on some brands.