UnderAutomation
Une question ?

[email protected]

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

Variable: read and write variables and registers

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.

  • Prerequisites
  • Brand support
  • Example
  • Read a variable
  • Write a variable
  • Read and write a position
  • Read and write the comment
  • List the variables of one kind
  • Read several variables
  • Reference
  • Methods of IVariableService
  • VariableValue
  • Errors
  • What to read next

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

Variables
MethodFanucYaskawaUniversal RobotsABBStäubli
Variable.ReadCGTP (Cgtp), SNPXHigh Speed Ethernet Server, Ethernet ServerDashboard Server, Primary Interface (Primary)Robot Web ServicesNot available
Variable.WriteIntegerCGTP (Cgtp), SNPXHigh Speed Ethernet Server, Ethernet ServerInterpreter Mode (manual)Robot Web ServicesNot available
Variable.WriteRealCGTP (Cgtp), SNPXHigh Speed Ethernet Server, Ethernet ServerInterpreter Mode (manual)Robot Web ServicesNot available
Variable.WriteStringCGTP (Cgtp), SNPXHigh Speed Ethernet Server, Ethernet ServerInterpreter Mode (manual)Robot Web ServicesNot available
Variable.WriteBooleanCGTP (Cgtp), SNPXHigh Speed Ethernet Server, Ethernet ServerInterpreter Mode (manual)Robot Web ServicesNot available
Variable.ReadPositionCGTP (Cgtp), SNPXNot availableNot availableRobot Web ServicesNot available
Variable.WritePositionCGTP (Cgtp), SNPXNot availableNot availableRobot Web ServicesNot available
Variable.ReadCommentCGTP (Cgtp), SNPXHigh Speed Ethernet ServerNot availableNot availableNot available
Variable.WriteCommentCGTP (Cgtp), SNPXHigh Speed Ethernet ServerNot availableNot availableNot available
Variable.ListCGTP (Cgtp)High Speed Ethernet ServerPrimary Interface (Primary)Robot Web ServicesNot available
Variable.ReadManyCGTP (Cgtp), SNPXHigh Speed Ethernet Server, Ethernet ServerNot availableNot availableNot available
Variable11 of 119 of 116 of 118 of 110 of 11

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

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

Write a variable

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

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

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.

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

Read and write the comment

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

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

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.

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

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.

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

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

Interface
IVariableService
C#Python

Variable service of a robot controller: variables, registers and system variables, 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(VariableFeature)
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
VariableValue[]
Lists the variables of one kind, with their names and comments. The values are filled when the controller gives them with the list (HasValue).
  • kind : Kind of variable, as the native names write it (the name without its index)
Read(string)
Method
VariableValue
Reads a variable
  • name : Native name of the variable
ReadComment(string)
Method
string
Reads the comment of a variable. Empty when it has none.
  • name : Native name of the variable
ReadMany(string[])
Method
VariableValue[]
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 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(VariableFeature) is false for this method, call Read(string) for each name.
  • names : Native names of the variables
ReadPosition(string)
Method
RobotPosition
Reads a position variable or register
  • name : Native name of the variable
WriteBoolean(string, bool)
Method
void
Writes a boolean variable
  • name : Native name of the variable
  • value : New value
WriteComment(string, string)
Method
void
Writes the comment of a variable
  • name : Native name of the variable
  • comment : New comment
WriteInteger(string, int)
Method
void
Writes an integer variable
  • name : Native name of the variable
  • value : New value
WritePosition(string, RobotPosition)
Method
void
Writes a position variable or register, for the motion group of the value (Group) 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 Same without a configuration object of the brand.
  • name : Native name of the variable
  • position : New value
WriteReal(string, double)
Method
void
Writes a real variable
  • name : Native name of the variable
  • value : New value
WriteString(string, string)
Method
void
Writes a string variable
  • name : Native name of the variable
  • value : New value

VariableValue

Class
VariableValue
C#Python

Value of a variable or register, with its native name, its comment and its type. 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
VariableValue()
Constructor
Creates a variable value with the default value of each property
Comment
Property
string
Comment of the variable. 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
Name
Property
string
Native name of the variable, 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, for the types Integer and Real. A boolean gives 1 or 0. 0 for the other types.
Position
Property
RobotPosition
Value as a position, for the type Position. Null for the other types.
Text
Property
string
Value as text, for every type. A boolean is "True" or "False". Numbers use the invariant culture.
Type
Property
VariableType
Type of the variable
ToString()
Method
string
Enum
VariableType
C#Python

Type of a variable or register

NameValueDescription
Boolean
4
Boolean
Integer
1
Integer number
Other
6
Another type of the controller (structure, array...): the value is in Text and in Native
Position
5
Position
Real
2
Real number
String
3
Text
Unknown
0
The type is not known

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.

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.

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

What to read next

  • Read and write robot variables: the same code on the brands that have a variable route, with the native names of each brand.
  • Io: read and write the signals of the controller.
  • Motion: read the position of the robot and move it.
  • Errors: catch the exceptions of the common API.