UnderAutomation
Une question ?

[email protected]

Contactez-nous
UnderAutomation
⌘Q
Cette page est disponible uniquement en anglais.

Io: read, write and simulate signals

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.

  • Prerequisites
  • Brand support
  • Example
  • Read a signal
  • Write a signal
  • Read and write the comment
  • List the signals of one kind
  • Read several signals
  • Simulate a signal
  • Reference
  • Methods of IIoService
  • IoValue
  • Errors
  • What to read next

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.
  • The license of the brand of the controller, or the 30 day trial. See Licensing.
  • 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 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.

Inputs and outputs
MethodFanucYaskawaUniversal RobotsABBStäubli
Io.ReadSNPX, CGTP (Cgtp)High Speed Ethernet Server, Ethernet ServerRTDE, Primary Interface (Primary)Robot Web ServicesSOAP
Io.WriteBooleanSNPX, CGTP (Cgtp), CGTP (CgtpKcl), TelnetHigh Speed Ethernet Server, Ethernet ServerPrimary Interface (Script), Interpreter Mode (manual)Robot Web ServicesSOAP
Io.WriteNumberSNPX, CGTP (Cgtp), CGTP (CgtpKcl), TelnetHigh Speed Ethernet Server, Ethernet ServerPrimary Interface (Script), Interpreter Mode (manual)Robot Web ServicesSOAP
Io.ReadCommentCGTP (Cgtp), SNPXHigh Speed Ethernet ServerNot availableNot availableNot available
Io.WriteCommentCGTP (Cgtp), SNPXHigh Speed Ethernet ServerNot availableNot availableNot available
Io.ListCGTP (Cgtp)High Speed Ethernet ServerNot availableRobot Web ServicesSOAP
Io.ReadManySNPX, CGTP (Cgtp)High Speed Ethernet Server, Ethernet ServerNot availableNot availableSOAP
Io.SimulateCGTP (Cgtp)Not availableNot availableNot availableNot available
Io.UnsimulateCGTP (Cgtp)Not availableNot availableNot availableNot available
Io9 of 97 of 93 of 94 of 95 of 9

A brand that has no route for a method throws FeatureNotSupportedException (see 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.

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();
}
Click to see the full code

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.

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();
}
Click to see the full code

Read and write the comment

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

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();
}
Click to see the full code

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.

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();
}
Click to see the full code

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.

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();
}
Click to see the full code

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.

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();
}
Click to see the full code

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

Interface
IIoService
C#Python

IO service of a robot controller: digital, group and analog signals, addressed by their native name. The name is the one the pendant and the programs use. It can contain the comment as a program writes it: the comment is ignored for the address, and checked only when CheckComments is true. The library implements this interface. A minor version of the library can add members to it: a class of the application that implements it, for example a test double, then needs the new methods. Errors of the methods other than IsAvailable: FeatureNotSupportedException when the brand has no route for the method, RouteUnavailableException when the method has routes but none of them can be used, ControllerRefusedException when the controller received the command and refused it, RobotControllerException when the route failed (the inner exception is the exception of the brand SDK), and ArgumentException or a derived exception for an invalid argument. IsAvailable only throws ArgumentOutOfRangeException, for a value that is not in the enum. Results: a text and an array are empty when there is no value, never null. The only null values are the Native properties when there is no object of the brand SDK, and Position when the variable is not a position.

MemberTypeDescription
IsAvailable(IoFeature)
Method
bool
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.
  • feature : Method of the service
List(string)
Method
IoValue[]
Lists the signals of one kind, with their names and comments. The values are filled when the controller gives them with the list (HasValue).
  • kind : Kind of signal, as the native names write it (the name without its index)
Read(string)
Method
IoValue
Reads a signal
  • name : Native name of the signal
ReadComment(string)
Method
string
Reads the comment of a signal. Empty when it has none.
  • name : Native name of the signal
ReadMany(string[])
Method
IoValue[]
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 Read(string) for its name: when Read(string) throws for a name (invalid name, refused by the controller), the item has HasValue false and the message of the error in Error, and the other items are still read. A failure of the communication throws, as Read(string) does. The names that the brand cannot read together are read one by one with Read(string). When IsAvailable(IoFeature) is false for this method, call Read(string) for each name.
  • names : Native names of the signals
Simulate(string)
Method
void
Simulates a signal: it is disconnected from the cell and keeps its current value. WriteBoolean(string%Boolean) and WriteNumber(string%Double) then change the value seen by the programs, also for an input. Unsimulate(string) 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 ArgumentException. A refusal that the controller answers throws ControllerRefusedException. Read Simulated to check the result.
  • name : Native name of the signal
Unsimulate(string)
Method
void
Stops the simulation of a signal: it follows the cell again (Simulate(string))
  • name : Native name of the signal
WriteBoolean(string, bool)
Method
void
Writes a digital signal: on or off
  • name : Native name of the signal
  • value : True for on
WriteComment(string, string)
Method
void
Writes the comment of a signal
  • name : Native name of the signal
  • comment : New comment
WriteNumber(string, double)
Method
void
Writes a group signal (integer) or an analog signal
  • name : Native name of the signal
  • value : New value. A group signal takes an integer value.

IoValue

Class
IoValue
C#Python

Value of an input or output signal, with its native name and its comment. The library creates a new object at each call and does not read it back. The setters are public so that tests and serializers can build the object.

MemberTypeDescription
IoValue()
Constructor
Creates a signal value with the default value of each property
Comment
Property
string
Comment of the signal. Empty when it has none or when the controller has no comments.
Error
Property
string
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.
HasValue
Property
bool
False when the value was not read, for example in the result of a list of names and comments
IsOn
Property
bool
Value as a boolean: true when the signal is on, or when its number is not 0
Kind
Property
IoKind
Kind of the signal
Name
Property
string
Native name of the signal, as the pendant and the programs write it
Native
Property
object
Object of the brand SDK this value comes from. Null when there is none.
Number
Property
double
Value as a number: 1 or 0 for a digital signal, the integer of a group, the value of an analog signal
Simulated
Property
bool
True when the signal is simulated: its value does not come from the hardware
ToString()
Method
string
Enum
IoKind
C#Python

Kind of a signal

NameValueDescription
Analog
3
Analog signal
Digital
1
Digital signal: on or off
Group
2
Group of digital signals read or written as one integer
Unknown
0
The kind is not known

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

Errors

The page 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: the same read and write on each brand, with the signal names of each brand.
  • Variable: read and write the variables and registers.
  • State: operating mode and servo power.
  • Errors: catch the exceptions of the common API.