---
title: "Io: read, write and simulate signals"
description: "Read and write the digital, group and analog signals of a robot controller, read their comments, list and simulate them with robot.Io. Brand support table, C# and Python examples."
---

# Io: read, write and simulate signals

`robot.Io` reads and writes the digital, group and analog signals of a robot controller, reads and writes their comments, lists them, and simulates them. A signal 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 signal, for example `DI[1]`, `DO[1]` or `GI[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.
- An output is connected to the cell. Writing it can start a machine, close a gripper or open a valve. Check what the signal does before you write it.

## 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 |
| --- | --- | --- | --- | --- | --- |
| Io.Read | SNPX, CGTP (Cgtp) | High Speed Ethernet Server, Ethernet Server | RTDE, Primary Interface (Primary) | Robot Web Services | SOAP |
| Io.WriteBoolean | SNPX, CGTP (Cgtp), CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Primary Interface (Script), Interpreter Mode (manual) | Robot Web Services | SOAP |
| Io.WriteNumber | SNPX, CGTP (Cgtp), CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Primary Interface (Script), Interpreter Mode (manual) | Robot Web Services | SOAP |
| Io.ReadComment | CGTP (Cgtp), SNPX | High Speed Ethernet Server | Not available | Not available | Not available |
| Io.WriteComment | CGTP (Cgtp), SNPX | High Speed Ethernet Server | Not available | Not available | Not available |
| Io.List | CGTP (Cgtp) | High Speed Ethernet Server | Not available | Robot Web Services | SOAP |
| Io.ReadMany | SNPX, CGTP (Cgtp) | High Speed Ethernet Server, Ethernet Server | Not available | Not available | SOAP |
| Io.Simulate | CGTP (Cgtp) | Not available | Not available | Not available | Not available |
| Io.Unsimulate | CGTP (Cgtp) | Not available | Not available | Not available | Not available |
| Io | **9 of 9** | **7 of 9** | **3 of 9** | **4 of 9** | **5 of 9** |

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

## Example

### Read a signal

`Read` returns an `IoValue`. `IsOn` is true when the signal is on, or when its number is not 0. `Number` gives the integer of a group signal and the value of an analog signal.

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

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

        /**/
        IoValue signal = robot.Io.Read("DI[1]");
        Console.WriteLine($"{signal.Name} ({signal.Kind}): {(signal.IsOn ? "on" : "off")}");

        // Group and analog signals give a number
        Console.WriteLine(robot.Io.Read("GI[1]").Number);
        /**/

        robot.Disconnect();
    }
}
```

**Python : IoRead**
```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", ""))

##
signal = robot.io.read("DI[1]")
print(f"{signal.name} ({signal.kind.name}): {'on' if signal.is_on else 'off'}")

# Group and analog signals give a number
print(robot.io.read("GI[1]").number)
##

robot.disconnect()
```

### Write a signal

`WriteBoolean` writes a digital signal: on or off. `WriteNumber` writes a group signal, which takes an integer value, or an analog signal.

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

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

        /**/
        robot.Io.WriteBoolean("DO[1]", true);
        robot.Io.WriteNumber("GO[1]", 5);
        /**/

        robot.Disconnect();
    }
}
```

**Python : IoWrite**
```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.io.write_boolean("DO[1]", True)
robot.io.write_number("GO[1]", 5)
##

robot.disconnect()
```

### Read and write the comment

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

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

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

        /**/
        robot.Io.WriteComment("DO[1]", "Gripper");
        Console.WriteLine(robot.Io.ReadComment("DO[1]"));
        /**/

        robot.Disconnect();
    }
}
```

**Python : IoComment**
```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.io.write_comment("DO[1]", "Gripper")
print(robot.io.read_comment("DO[1]"))
##

robot.disconnect()
```

### List the signals of one kind

`List` takes the kind of signal 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# : IoList**
```csharp
using UnderAutomation.Robotics.Controllers;

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

        /**/
        // Kind of signal: the native name without its index
        foreach (IoValue signal in robot.Io.List("DI"))
            Console.WriteLine($"{signal.Name} {signal.Comment}");
        /**/

        robot.Disconnect();
    }
}
```

**Python : IoList**
```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 signal: the native name without its index
for signal in robot.io.list("DI"):
    print(f"{signal.name} {signal.comment}")
##

robot.disconnect()
```

### Read several signals

`ReadMany` reads the signals in as few requests as the controller allows. 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# : IoReadMany**
```csharp
using UnderAutomation.Robotics.Controllers;

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

        /**/
        IoValue[] signals = robot.Io.ReadMany(new[] { "DI[1]", "DI[2]", "DO[1]" });

        foreach (IoValue signal in signals)
            Console.WriteLine(signal.HasValue ? $"{signal.Name}: {signal.IsOn}" : $"{signal.Name}: {signal.Error}");
        /**/

        robot.Disconnect();
    }
}
```

**Python : IoReadMany**
```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", ""))

##
signals = robot.io.read_many(["DI[1]", "DI[2]", "DO[1]"])

for signal in signals:
    print(f"{signal.name}: {signal.is_on}" if signal.has_value else f"{signal.name}: {signal.error}")
##

robot.disconnect()
```

### Simulate a signal

`Simulate` disconnects a signal from the cell: it keeps its current value, and `WriteBoolean` and `WriteNumber` then change the value that the programs see, also for an input. `Unsimulate` connects the signal to the cell again. The kinds of signal that can be simulated depend on the brand: another kind throws `ArgumentException`. When the controller refuses, `ControllerRefusedException` is thrown. Read `IoValue.Simulated` to check the result.

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

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

        /**/
        // The signal keeps its value and does not follow the cell
        robot.Io.Simulate("DI[2]");
        robot.Io.WriteBoolean("DI[2]", true);
        Console.WriteLine(robot.Io.Read("DI[2]").Simulated);

        // The signal follows the cell again
        robot.Io.Unsimulate("DI[2]");
        /**/

        robot.Disconnect();
    }
}
```

**Python : IoSimulate**
```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", ""))

##
# The signal keeps its value and does not follow the cell
robot.io.simulate("DI[2]")
robot.io.write_boolean("DI[2]", True)
print(robot.io.read("DI[2]").simulated)

# The signal follows the cell again
robot.io.unsimulate("DI[2]")
##

robot.disconnect()
```

## Reference

In Python, the names are in snake_case: `robot.io.read("DI[1]")`, `robot.io.write_boolean(...)`, `robot.io.read_many([...])`, `robot.io.is_available(...)`. The enum members keep their names, and `signal.kind.name` gives the name of the kind.

### Methods of IIoService

**Members of Controllers.IIoService**
```csharp
public interface IIoService {
    // 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(IoFeature feature)

    // Lists the signals 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.IoValue.HasValue" data-throw-if-not-resolved="false"></xref>).
    IoValue[] List(string kind)

    // Reads a signal
    IoValue Read(string name)

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

    // Reads several signals 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.IIoService.Read(System.String)" data-throw-if-not-resolved="false"></xref> for its name:
    // when <xref href="UnderAutomation.Robotics.Controllers.IIoService.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.IoValue.HasValue" data-throw-if-not-resolved="false"></xref> false
    // and the message of the error in <xref href="UnderAutomation.Robotics.Controllers.IoValue.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.IIoService.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.IIoService.Read(System.String)" data-throw-if-not-resolved="false"></xref>.
    // When <xref href="UnderAutomation.Robotics.Controllers.IIoService.IsAvailable(UnderAutomation.Robotics.Controllers.IoFeature)" data-throw-if-not-resolved="false"></xref> is false for this method, call <xref href="UnderAutomation.Robotics.Controllers.IIoService.Read(System.String)" data-throw-if-not-resolved="false"></xref> for each name.
    IoValue[] ReadMany(string[] names)

    // Simulates a signal: it is disconnected from the cell and keeps its current value. <xref href="UnderAutomation.Robotics.Controllers.IIoService.WriteBoolean(System.String%2cSystem.Boolean)" data-throw-if-not-resolved="false"></xref> and <xref href="UnderAutomation.Robotics.Controllers.IIoService.WriteNumber(System.String%2cSystem.Double)" data-throw-if-not-resolved="false"></xref> then change
    // the value seen by the programs, also for an input. <xref href="UnderAutomation.Robotics.Controllers.IIoService.Unsimulate(System.String)" data-throw-if-not-resolved="false"></xref> connects the signal to the cell again.
    // The kinds of signal that can be simulated depend on the brand (the route list of the brand says which); another kind throws <xref href="System.ArgumentException" data-throw-if-not-resolved="false"></xref>.
    // A refusal that the controller answers throws <xref href="UnderAutomation.Robotics.Controllers.ControllerRefusedException" data-throw-if-not-resolved="false"></xref>. Read <xref href="UnderAutomation.Robotics.Controllers.IoValue.Simulated" data-throw-if-not-resolved="false"></xref> to check the result.
    void Simulate(string name)

    // Stops the simulation of a signal: it follows the cell again (<xref href="UnderAutomation.Robotics.Controllers.IIoService.Simulate(System.String)" data-throw-if-not-resolved="false"></xref>)
    void Unsimulate(string name)

    // Writes a digital signal: on or off
    void WriteBoolean(string name, bool value)

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

    // Writes a group signal (integer) or an analog signal
    void WriteNumber(string name, double value)
}
```

### IoValue

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

    // Comment of the signal. 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; }

    // Value as a boolean: true when the signal is on, or when its number is not 0
    public bool IsOn { get; set; }

    // Kind of the signal
    public IoKind Kind { get; set; }

    // Native name of the signal, 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: 1 or 0 for a digital signal, the integer of a group, the value of an analog signal
    public double Number { get; set; }

    // True when the signal is simulated: its value does not come from the hardware
    public bool Simulated { get; set; }

    public override string ToString()
}
```

**Members of Controllers.IoKind**
```csharp
public enum IoKind {
    // Analog signal
    Analog = 3

    // Digital signal: on or off
    Digital = 1

    // Group of digital signals read or written as one integer
    Group = 2

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

A text is empty when there is no value, never null. The result is a new object at each call.

### 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, for example a kind of signal that the brand cannot simulate.

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

## What to read next

- [Read and write robot IO](/robotics/documentation/how-to-read-write-io): the same read and write on each brand, with the signal names of each brand.
- [Variable](/robotics/documentation/variable): read and write the variables and registers.
- [State](/robotics/documentation/state): operating mode and servo power.
- [Errors](/robotics/documentation/errors): catch the exceptions of the common API.