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.
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]orGI[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 whenCheckCommentsof 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.
| 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). 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 numberConsole.WriteLine(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.
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();}
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();}
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 indexforeach (IoValue signal in robot.Io.List("DI"))Console.WriteLine($"{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.
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();}
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 cellrobot.Io.Simulate("DI[2]");robot.Io.WriteBoolean("DI[2]", true);Console.WriteLine(robot.Io.Read("DI[2]").Simulated);// The signal follows the cell againrobot.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
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.
| Member | Type | Description |
|---|---|---|
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.
|
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).
|
Read(string) Method | IoValue | Reads a signal
|
ReadComment(string) Method | string | Reads the comment of a signal. Empty when it has none.
|
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.
|
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.
|
Unsimulate(string) Method | void | Stops the simulation of a signal: it follows the cell again ( Simulate(string))
|
WriteBoolean(string, bool) Method | void | Writes a digital signal: on or off
|
WriteComment(string, string) Method | void | Writes the comment of a signal
|
WriteNumber(string, double) Method | void | Writes a group signal (integer) or an analog signal
|
IoValue
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.
| Member | Type | Description |
|---|---|---|
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 |
Kind of a signal
| Name | Value | Description |
|---|---|---|
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.