---
title: "Variable: read and write variables and registers"
description: "Read and write the variables, registers and system variables of a robot controller, with their comments, and list them with robot.Variable. Brand support table, C# and Python examples."
---

# Variable: read and write variables and registers

`robot.Variable` reads and writes the variables, registers and system variables of a robot controller, with their comments, and lists them. A variable is addressed by its native name, the one that the pendant and the programs use. The result type is the same on every brand. The methods that you can call depend on the brand: see the table below.

## Prerequisites

- A connected `RobotController`. See [Connect to your robot](/robotics/documentation/connect).
- The license of the brand of the controller, or the 30 day trial. See [Licensing](/robotics/documentation/license).
- The native name of the variable, for example `R[1]` or `PR[1]` on a Fanuc controller. The name can contain the comment as a program writes it: the comment is ignored for the address, and checked only when `CheckComments` of the connection parameters is true.
- The write methods change the controller.

## Brand support

Each cell gives the protocol that the method uses on this brand, in the default order. The page [Routing](/robotics/documentation/routing) explains how the library chooses it. The table is generated from the route data of the library. (manual) marks a route that you enable yourself. "n of m" is the number of methods of the service that have a route on this brand.

Routes of each method in the default order. The first route is used, the next ones are fallbacks. (manual) marks a route that you enable yourself.

| Method | Fanuc | Yaskawa | Universal Robots | ABB | Stäubli |
| --- | --- | --- | --- | --- | --- |
| Variable.Read | CGTP (Cgtp), SNPX | High Speed Ethernet Server, Ethernet Server | Dashboard Server, Primary Interface (Primary) | Robot Web Services | Not available |
| Variable.WriteInteger | CGTP (Cgtp), SNPX | High Speed Ethernet Server, Ethernet Server | Interpreter Mode (manual) | Robot Web Services | Not available |
| Variable.WriteReal | CGTP (Cgtp), SNPX | High Speed Ethernet Server, Ethernet Server | Interpreter Mode (manual) | Robot Web Services | Not available |
| Variable.WriteString | CGTP (Cgtp), SNPX | High Speed Ethernet Server, Ethernet Server | Interpreter Mode (manual) | Robot Web Services | Not available |
| Variable.WriteBoolean | CGTP (Cgtp), SNPX | High Speed Ethernet Server, Ethernet Server | Interpreter Mode (manual) | Robot Web Services | Not available |
| Variable.ReadPosition | CGTP (Cgtp), SNPX | Not available | Not available | Robot Web Services | Not available |
| Variable.WritePosition | CGTP (Cgtp), SNPX | Not available | Not available | Robot Web Services | Not available |
| Variable.ReadComment | CGTP (Cgtp), SNPX | High Speed Ethernet Server | Not available | Not available | Not available |
| Variable.WriteComment | CGTP (Cgtp), SNPX | High Speed Ethernet Server | Not available | Not available | Not available |
| Variable.List | CGTP (Cgtp) | High Speed Ethernet Server | Primary Interface (Primary) | Robot Web Services | Not available |
| Variable.ReadMany | CGTP (Cgtp), SNPX | High Speed Ethernet Server, Ethernet Server | Not available | Not available | Not available |
| Variable | **11 of 11** | **9 of 11** | **6 of 11** | **8 of 11** | **0 of 11** |

A brand that has no route for a method throws `FeatureNotSupportedException` (see [Errors](/robotics/documentation/errors)). Ask `robot.Variable.IsAvailable(VariableFeature.ReadMany)` before the call.

## Example

### Read a variable

`Read` returns a `VariableValue`. `Type` tells which property holds the value: `Number` for an integer or a real, `Text` for every type, `Position` for a position. A boolean gives 1 or 0 in `Number`, and "True" or "False" in `Text`.

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

public class VariableRead
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        // Native name of the variable: the one of the pendant and the programs
        VariableValue variable = robot.Variable.Read("R[1]");
        Console.WriteLine($"{variable.Name} ({variable.Type}) = {variable.Number}, comment: {variable.Comment}");

        // Text of the value, for any type
        Console.WriteLine(variable.Text);
        /**/

        robot.Disconnect();
    }
}
```

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

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
# Native name of the variable: the one of the pendant and the programs
variable = robot.variable.read("R[1]")
print(f"{variable.name} ({variable.type.name}) = {variable.number}, comment: {variable.comment}")

# Text of the value, for any type
print(variable.text)
##

robot.disconnect()
```

### Write a variable

There is one write method per type: `WriteInteger`, `WriteReal`, `WriteString` and `WriteBoolean`.

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

public class VariableWrite
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        robot.Variable.WriteInteger("R[1]", 42);
        robot.Variable.WriteReal("R[2]", 3.14);
        robot.Variable.WriteString("SR[1]", "Hello");
        /**/

        robot.Disconnect();
    }
}
```

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

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
robot.variable.write_integer("R[1]", 42)
robot.variable.write_real("R[2]", 3.14)
robot.variable.write_string("SR[1]", "Hello")
##

robot.disconnect()
```

### Read and write a position

`ReadPosition` returns a `RobotPosition`, and `WritePosition` writes one. The configuration of a Cartesian value is not completed from the current configuration of the robot: a brand whose stored positions keep a configuration refuses a posture `Same` without a configuration object of the brand. Read the position first, change what you need and write it back, as in the example.

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

public class VariablePosition
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        RobotPosition position = robot.Variable.ReadPosition("PR[1]");
        Console.WriteLine($"X {position.Pose.X}, Y {position.Pose.Y}, Z {position.Pose.Z}");

        position.Pose.Z += 10;
        robot.Variable.WritePosition("PR[1]", position);
        /**/

        robot.Disconnect();
    }
}
```

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

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
position = robot.variable.read_position("PR[1]")
print(f"X {position.pose.x}, Y {position.pose.y}, Z {position.pose.z}")

position.pose.z += 10
robot.variable.write_position("PR[1]", position)
##

robot.disconnect()
```

### Read and write the comment

`ReadComment` returns an empty text when the variable has no comment.

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

public class VariableComment
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        robot.Variable.WriteComment("R[1]", "Part counter");
        Console.WriteLine(robot.Variable.ReadComment("R[1]"));
        /**/

        robot.Disconnect();
    }
}
```

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

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
robot.variable.write_comment("R[1]", "Part counter")
print(robot.variable.read_comment("R[1]"))
##

robot.disconnect()
```

### List the variables of one kind

`List` takes the kind of variable as the native names write it: the name without its index. The result has the names and the comments. `HasValue` is true only when the controller gives the values with the list.

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

public class VariableList
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        // Kind of variable: the native name without its index
        foreach (VariableValue register in robot.Variable.List("R"))
            Console.WriteLine($"{register.Name} {register.Comment}");
        /**/

        robot.Disconnect();
    }
}
```

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

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
# Kind of variable: the native name without its index
for register in robot.variable.list("R"):
    print(f"{register.name} {register.comment}")
##

robot.disconnect()
```

### Read several variables

`ReadMany` reads the variables in as few requests as the controller allows, for example for the page of a table. The result has one item per name, in the order of the names. A name that fails does not stop the others: its item has `HasValue` false and the message in `Error`. A failure of the communication throws. When `IsAvailable` is false for `ReadMany`, call `Read` for each name.

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

public class VariableReadMany
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        // One item per name. A name that fails does not stop the others: read its Error.
        VariableValue[] values = robot.Variable.ReadMany(new[] { "R[1]", "R[2]", "R[3]" });

        foreach (VariableValue value in values)
            Console.WriteLine(value.HasValue ? $"{value.Name} = {value.Text}" : $"{value.Name}: {value.Error}");
        /**/

        robot.Disconnect();
    }
}
```

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

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
# One item per name. A name that fails does not stop the others: read its error.
values = robot.variable.read_many(["R[1]", "R[2]", "R[3]"])

for value in values:
    print(f"{value.name} = {value.text}" if value.has_value else f"{value.name}: {value.error}")
##

robot.disconnect()
```

## Reference

In Python, the names are in snake_case: `robot.variable.read("R[1]")`, `robot.variable.write_integer(...)`, `robot.variable.read_many([...])`, `robot.variable.is_available(...)`. The enum members keep their names, and `variable.type.name` gives the name of the type.

### Methods of IVariableService

**Members of Controllers.IVariableService**
```csharp
public interface IVariableService {
    // Returns true when the method can be called on the connected controller.
    // The answer depends on the brand, on the routing settings and on the protocols that answered at the connection, not on the state of the controller.
    bool IsAvailable(VariableFeature feature)

    // Lists the variables of one kind, with their names and comments. The values are filled when the controller gives them with the list (<xref href="UnderAutomation.Robotics.Controllers.VariableValue.HasValue" data-throw-if-not-resolved="false"></xref>).
    VariableValue[] List(string kind)

    // Reads a variable
    VariableValue Read(string name)

    // Reads the comment of a variable. Empty when it has none.
    string ReadComment(string name)

    // Reads several variables in as few requests as the controller allows, for example the page of a table.
    // The result has one item per name, in the order of the names. Each item is the result of <xref href="UnderAutomation.Robotics.Controllers.IVariableService.Read(System.String)" data-throw-if-not-resolved="false"></xref> for its name:
    // when <xref href="UnderAutomation.Robotics.Controllers.IVariableService.Read(System.String)" data-throw-if-not-resolved="false"></xref> throws for a name (invalid name, refused by the controller), the item has <xref href="UnderAutomation.Robotics.Controllers.VariableValue.HasValue" data-throw-if-not-resolved="false"></xref> false
    // and the message of the error in <xref href="UnderAutomation.Robotics.Controllers.VariableValue.Error" data-throw-if-not-resolved="false"></xref>, and the other items are still read.
    // A failure of the communication throws, as <xref href="UnderAutomation.Robotics.Controllers.IVariableService.Read(System.String)" data-throw-if-not-resolved="false"></xref> does. The names that the brand cannot read together are read one by one with <xref href="UnderAutomation.Robotics.Controllers.IVariableService.Read(System.String)" data-throw-if-not-resolved="false"></xref>.
    // When <xref href="UnderAutomation.Robotics.Controllers.IVariableService.IsAvailable(UnderAutomation.Robotics.Controllers.VariableFeature)" data-throw-if-not-resolved="false"></xref> is false for this method, call <xref href="UnderAutomation.Robotics.Controllers.IVariableService.Read(System.String)" data-throw-if-not-resolved="false"></xref> for each name.
    VariableValue[] ReadMany(string[] names)

    // Reads a position variable or register
    RobotPosition ReadPosition(string name)

    // Writes a boolean variable
    void WriteBoolean(string name, bool value)

    // Writes the comment of a variable
    void WriteComment(string name, string comment)

    // Writes an integer variable
    void WriteInteger(string name, int value)

    // Writes a position variable or register, for the motion group of the value (<xref href="UnderAutomation.Robotics.Controllers.RobotPosition.Group" data-throw-if-not-resolved="false"></xref>) when the brand has motion groups.
    // The configuration of a Cartesian value is not completed from the current configuration of the robot: a brand whose stored positions keep a configuration
    // refuses a posture <code>Same</code> without a configuration object of the brand.
    void WritePosition(string name, RobotPosition position)

    // Writes a real variable
    void WriteReal(string name, double value)

    // Writes a string variable
    void WriteString(string name, string value)
}
```

### VariableValue

**Members of Controllers.VariableValue**
```csharp
public sealed class VariableValue {
    // Creates a variable value with the default value of each property
    public VariableValue()

    // Comment of the variable. Empty when it has none or when the controller has no comments.
    public string Comment { get; set; }

    // Message of the error of this item in the result of ReadMany: the message that Read throws for this name. Empty when the value was read.
    public string Error { get; set; }

    // False when the value was not read, for example in the result of a list of names and comments
    public bool HasValue { get; set; }

    // Native name of the variable, as the pendant and the programs write it
    public string Name { get; set; }

    // Object of the brand SDK this value comes from. Null when there is none.
    public object Native { get; set; }

    // Value as a number, for the types <xref href="UnderAutomation.Robotics.Controllers.VariableType.Integer" data-throw-if-not-resolved="false"></xref> and <xref href="UnderAutomation.Robotics.Controllers.VariableType.Real" data-throw-if-not-resolved="false"></xref>. A boolean gives 1 or 0. 0 for the other types.
    public double Number { get; set; }

    // Value as a position, for the type <xref href="UnderAutomation.Robotics.Controllers.VariableType.Position" data-throw-if-not-resolved="false"></xref>. Null for the other types.
    public RobotPosition Position { get; set; }

    // Value as text, for every type. A boolean is "True" or "False". Numbers use the invariant culture.
    public string Text { get; set; }

    public override string ToString()

    // Type of the variable
    public VariableType Type { get; set; }
}
```

**Members of Controllers.VariableType**
```csharp
public enum VariableType {
    // Boolean
    Boolean = 4

    // Integer number
    Integer = 1

    // Another type of the controller (structure, array...): the value is in <xref href="UnderAutomation.Robotics.Controllers.VariableValue.Text" data-throw-if-not-resolved="false"></xref> and in <xref href="UnderAutomation.Robotics.Controllers.VariableValue.Native" data-throw-if-not-resolved="false"></xref>
    Other = 6

    // Position
    Position = 5

    // Real number
    Real = 2

    // Text
    String = 3

    // The type is not known
    Unknown = 0
}
```

A text and an array are empty when there is no value, never null. The result is a new object at each call. `RobotPosition` is described on the page [Motion](/robotics/documentation/motion).

### Errors

The page [Errors](/robotics/documentation/errors) explains each exception and how to avoid it.

- `FeatureNotSupportedException`: the brand has no route for the method.
- `RouteUnavailableException`: the method has routes, but none of them can be used, for example because the protocol did not answer at the connection.
- `ControllerRefusedException`: the controller received the command and refused it.
- `RobotControllerException`: the route failed. Its inner exception is the exception of the brand SDK.
- `ArgumentException`: an invalid argument.

`IsAvailable` only throws `ArgumentOutOfRangeException`, for a value that is not in the enum.

## What to read next

- [Read and write robot variables](/robotics/documentation/how-to-read-write-variables): the same code on the brands that have a variable route, with the native names of each brand.
- [Io](/robotics/documentation/io): read and write the signals of the controller.
- [Motion](/robotics/documentation/motion): read the position of the robot and move it.
- [Errors](/robotics/documentation/errors): catch the exceptions of the common API.