The following document contains a description of how to install and use the MQTTspB Client URCap on Universal Robots Simulator application (URSim).URCap, MQTTspB and RTDE Clients.

EdgeGateway for Universal Robots

System Requirements

To make use of this feature the following system requirements need to be met.

• Universal Robots PolyScope version 5.11 and Physical Robot.
• URCap file (*.urcap).

How Does it Work?

The URCap application consists in three separate processes running in parallel.

• Graphical User Interface: It is the main URCap application. It runs inside the Robot (PolyScope), handles the communication parameters and can Start/Stop the client connections.
• RTDE Client: Client implementation for RTDE protocol, running on an independent thread. Reads real-time data from the Robot and forwards it to the main program so it can be published to an MQTT Broker.
• MQTTspB Client: Client implementation for MQTTspB protocol, running on an independent thread. Receives data from the RTDE (through the main program) and publishes to the Broker.

MQTT and RTDE definitions are available in the end of this section. This program behavior is illustrated as per image below.

The RTDE protocol generates messages every 8ms (125Hz). The MQTT client, however, will not publish at the same rate. It will only publish new data if any variable had its value changed since the last reading.

MQTT: A lightweight, publish-subscribe network protocol that transports messages between devices. The SparkPlugB has additional control and standards allowing to know about birth, death and a better data exchange control. For more information on the SparkplugB specification, please refer to the official documentation. 

RTDE: An interface that provides a way to synchronize external applications with the UR controller over a standard TCP/IP connection, without breaking any real-time properties of the UR Controller. For more information, please refer to the official documentation.

How to Install

1. Download and Copy the *.urcap file into the PolyScope programs Folder ( /programs/).
2. Open your Programming Environment (PolyScope).
3. Go to Program Settings (1) → System (2) → UR Caps (3). Click on the plus (+) button and search for your *.urcap file.
4. Restart the PolyScope to finalize the import procedure.

Using the URCap

This new tool will be available after importing the *.urcap file and restarting the simulator.

1. Go to Installation Tab (1) → UR Caps (2) → MQTTspB Publisher (3)
2. Click on it to open the configuration windows in the right panel.

There are three tabs: MQTT Broker Info, Communication Manager and License.

• In MQTT Broker Info, insert the information for the MQTTspB Client (similar to what is done at your Project).
• In Communication Manager, insert the MQTTspB Topic/Address, Robot Ip Address (for RTDE connection) and command buttons.

• License will contain information about your URCap license status.

Configuration Tab

• Broker URL: MQTT Broker (Server) URL.
• Port: MQTT Broker port. It must be the same port that is configured in the Broker to be listening.
• ClientId: Indicates the client identification used for connecting to the MQTT Broker. If empty, one will be auto generated.
• UserName: Username defined in MQTT Broker. This will be requested if the Broker needs this configuration (optional).
• Password: Password defined in MQTT Broker. This will be requested if the Broker needs this configuration (optional).
• x509Certificate: Path of X509 Client Certificate. If using server-side only certificate this field does not need to be configured. This must be the complete path of X509 certificate in the client computer. Also, the certificate must be installed.
• CertificatePassword: Password created when X509 Certificate was exported (optional).
• NetworkSecurity: This field is mandatory if MQTT Broker works using certificate, and must be the same that was configured in MQTT Broker (optional). The options are None and TLS.
• QoS: Quality of Service (QoS) is an agreement between sender and receiver of a message regarding the guarantees of delivering a message. textbfQoS levels are:
• AtMostOnce: This service level guarantees a best-effort delivery. However, there is no guarantee of delivery, due to the recipient not acknowledging the receipt of the message.
• AtLeastOnce: This service guarantees that a message is delivered at least once to the receiver.
• ExactlyOnce: Highest level of service. It is safer, but slower when compared to the others. When the message flow is complete, all parties involved in the communication are sure the message was send and delivered with success.
• KeepAlive: Ensures that the connection between the Broker and Client is open and both parties are aware of the connection. Default value is 10 seconds.

• Publish Rate: Indicates the time for publishing in ms. The messages to be published are grouped and sent using this period. Default value is 500 milisseconds.

Communication Manager Tab

• Robot Name: Defines the name of the robot, that represents the main element in the Data Structure.
• Mqtt Topic: Topic into which the payload will be published. The syntax will be: <GroupId>/<NodeId>/<DeviceId>.

• Robot Ip: Ip Address for the RTDE connection.
• Frequency: Frequency of reading for RTDE Protocol. Should be a value in the interval of 125 and 500Hz.

• AutoRun: Flag indicating if client should start automatically. This value will be stored in ConfigFile.xml for next program execution. (Default = false).

License Tab

When you first install this URCap, the default license is called Express. It allows you to run your application for two hours straight. After this time, all clients are stopped automatically. You can run the application without limitations once it is licensed.

Licensing Methods

To license your application, you need to create a softkey license which is generated by the equipment

SiteCode.

1. Go to Installation → MQTTspB Publisher → License and click Get Site Code.
2. Send the generated file to one of our employees, and they will generate a license key.
3. Click the Load license key button on the License tab to load the received key.

License - Product Model and Protocol

The Product Model refers to the amount of communication points allowed. As the Data Structure has a fixed max size, all URCap licenses are ”unlimited”.

The protocol available for this application is RTDE.

Import Configuration Parameters From File

Besides filling the configuration parameters manually at the PolyScope Installation Tab, it is also possible to import the parameters through a *.xml file.

The syntax for this file is as follows:

<?xml version="1.0"?>
<Configuration>
	<Robot>
		<Name>My_Robot_Name</Name>
	</Robot>
	<MQTT_Client>
		<BrokerURL>127.0.0.1</BrokerURL>
			<Port>1883</Port>
			<ClientId></ClientId>
			<UserName></UserName>
			<Password></Password>
			<x509Certificate></x509Certificate>
			<CertificatePassword></CertificatePassword>
			<NetworkSecurity>None</NetworkSecurity> <!-- None / SSL -->
			<QoS>AtLeastOnce</QoS>
			<!-- AtMostOnce / AtLeastOnce / ExactlyOnce -->
			<KeepAlive>10</KeepAlive>
			<PublishRate>500</PublishRate>
			<Topic>GroupId/NodeId/DeviceId_01</Topic>
	<AutoRun>false</AutoRun>
	<Variables>
<!--
<Joint_Control_Currents RBE_DeadBand="Absolute;0.1" 
Enable_Publish="true"></Joint_Control_Currents>
<Actual_Tcp_Position RBE_OutOfRange="-2;2" 
Enable_Publish="true"></Actual_Tcp_Position>
<Target_Joint_Accelerations RBE="" 
Enable_Publish="false"></Target_Joint_Accelerations>
<Controller_Info RBE_DeadBand="Percentual;5" 
Enable_Publish="true"></Controller_Info>
-->
	</Variables>
	</MQTT_Client>
	<RTDE_Client>
		<IpAddress>127.0.0.1</IpAddress>
		<Port>30004</Port>
		<Frequency>125</Frequency>
		<AutoRun>false</AutoRun>
	</RTDE_Client>
</Configuration>

To make sure the file is loaded by the program, some things MUST be guaranteed:

1. FileName: The file must be named ConfigFile.xml.
2. FilePath: The file must be located either inside the Documents folder, or inside (∼/programs/GUI/).

The file will be parsed everytime the PolyScope is launched (as long as the URCap is already installed). You CAN NOT alter its information while the program is running.

A sample configuration file can be downloaded here.

Variables entry allows you to Enable/Disable DataModel branches and customize a branch’s Change Event Definition. This definition determines when an event occurs to be published to the MQTT Broker. By default — or when entry is empty/blank —, all value changes will be reported.

The syntax to be used is as follows:

Where:

• [VariableName] is a path name in tree data model; for example Joint Control Currents.
• [RBE DeadBand=<RBE Options>;<Value>] is a report type where users can define an ”Absolute” or ”Percentual” deadband for each Branch — it will be applied to all variables bellow that branch. Value Changes exceeding the deadband will be considered an event. The deadband parameters are separated by a semicolon (;).
• [RBE OutOfRange=<Min>;<Max>] is a report type where users can define a Min/Max threshold for each Branch — it will be applied to all variables bellow that branch. A Value change outside the threshold interval will be considered an event. The deadband parameters are separated by a semicolon (;).

• [Enable Publish=”true” or ”false”] will enable or disable the publishing data of all tree bellow this tree point.

Example

<Joint_Control_Currents 
	RBE_DeadBand="Absolute;0.1" Enable_Publish="true">
</Joint_Control_Currents>

There are two possible RBE DeadBand options:

• Absolute: Deadband value is absolute value.
• Percentual: Deadband is calculated based on percentual values.

It is important to know that a the variable customization will be applied to the specified Branch and all its children, unless they have their own customization.

This entry can be customized ONLY through the .xml file.

Robot Runtime DataModel

The DataModel published to the MQTT Broker is pre-defined based on various UDT’s (User-Defined Types). Click here to downlaod an example *.html file.

When the MQTTspB Client is started, if connected to the Broker, you should be able to see the Robot Model using a different Client. The images below illustrate the model with FRAMEWORXclient.

Implemented Robot Variables

This section will detail how the DataStructure is modeled.

Robot Name

Can be customized with the XML file only.

Arm Info

Axis:

1. Target Joint Positions: RTDE Parameter target q.
2. Target Joint Velocities: RTDE Parameter target qd.
3. Target Joint Accelerations: RTDE Parameter target qdd.
4. Target Joint Currents: RTDE Parameter target current.
5. Target Joint Moments: RTDE Parameter target moment.
6. Joint Control Currents: RTDE Parameter joint control output.
7. Joint Temperatures: Temperature of each joint in degrees Celsius. RTDE Parameter joint temperatures.
8. Joint Voltages: Actual joint voltages. RTDE Parameter actual joint voltage.
9. Joint Position: Actual joint position. RTDE Parameter actual q.

Tool Center Point:

1. Actual TCP Force: Generalized forces in the TCP. It compensates the measurement for forces and torques generated by the payload. RTDE Parameter actual TCP force.
2. Actual TCP Position: Actual Cartesian coordinates of the tool: (x,y,z,rx,ry,rz), where rx, ry and rz is a rotation vector representation of the tool orientation. RTDE Parameter actual TCP pose.
3. Actual TCP Speed: Actual speed of the tool given in Cartesian coordinates. The speed is given in [m/s] and the rotational part of the TCP speed (rx, ry, rz) is the angular given in [rad/s]. RTDE Parameter actual TCP speed.
4. Payload:
   1. Mass: Payload mass Kg. RTDE Parameter payload.
   2. Payload CoG: Payload Center of Gravity (CoGx, CoGy, CoGz) mm. RTDE Parameter payload cog.
   3. Payload Inertia: Payload inertia matrix elements (Ixx,Iyy,Izz,Ixy,Ixz,Iyz] expressed inkg.mm². RTDE Parameter payload inertia.
5. Tool:
   1. Tool Mode: Tool mode. RTDE Parameter tool mode.
   2. Tool Analog Input 0: Tool analog input 0 [mA or V]. RTDE Parameter tool analog input0.
   3. Tool Analog Input 1: Tool analog input 1 [mA or V]. RTDE Parameter tool analog input1.
   4. Tool Output Voltage: Tool output voltage [V]. RTDE Parameter tool output voltage.
   5. Tool Output Current: Tool current [mA]. RTDE Parameter tool output current.
   6. Tool Temperature: Tool temperature in degrees Celsius. RTDE Parameter tool temperature.
   7. Tool Force Scalar: TCP force scalar [N]. RTDE Parameter tcp force scalar.
   8. Wrist3: RTDE Parameter actual TCP pose.

Controler Info

1. Timestamp: Time elapsed since the controller was started [s]. RTDE Parameter timestamp. b Controller Temp: Tool temperature in degrees Celsius. RTDE Parameter tool temperature. c Main Voltage: Safety Control Board: Main voltage. RTDE Parameter actual main voltage.
2. Current: Safety Control Board: Robot current. RTDE Parameter actual robot current. e Avg Robot Power: given by the expression ( Σ(ActualRobotCurrent∗ActualRobotV oltage) )
3. IO Current: I/O current [mA]. RTDE Parameter io current.
4. Tool Current: Tool current [mA]. RTDE Parameter tool output current.

Metadata

UNS

String variables, that don’t exist in RTDE context.

1. Area.
2. Cell.
3. Line
4. Site.

Control

1. Speed Slider Mask: 0 = do not change speed slider with this input. 1 = use speed slider fraction to set speed slider value. RTDE Parameter speed slider mask.
2. Speed Slider Fraction: New speed slider value. RTDE Parameter speed slider fraction.
3. Standard Digital Output: Standard digital outputs. RTDE Parameter standard digital output.
4. Configurable Digital Output: Configurable digital outputs. RTDE Parameter configurable digital output.
5. Standard Analog Output 0: Standard analog output 0 (ratio) [0..1]. RTDE Parameter standard analog output 0.
6. Standard Analog Output 1: Standard analog output 1 (ratio) [0..1]. RTDE Parameter standard analog output 1.
7. Input Bit Registers 0 to 31: This range of the boolean input registers is reserved for FieldBus/PLC interface usage. RTDE Parameter input bit registers0 to 31.
8. Input Bit Register X: X: [64..127] - The upper range of the boolean input registers can be used by external RTDE clients. RTDE Parameter input bit register X.
9. Input Int Register X: X: [0..23] - The lower range of the integer input registers is reserved for FieldBus/PLC interface usage. X: [24..47] - The upper range of the integer input registers can be used by external RTDE clients. RTDE Parameter input int register X.
10. Input Double Register X: X: [0..23] - The lower range of the double input registers is reserved for FieldBus/PLC interface usage. X: [24..47] - The upper range of the double input registers can be used by external RTDE clients . RTDE Parameter input double register X.
11. External Force Torque: Input external wrench when using ft rtde input enable builtin.
12. RTDE Parameter external force torque.

Status:

1. Robot Mode: Robot mode. RTDE Parameter robot mode.
2. Robot Power On: Power on. RTDE Parameter robot status bits.
3. Security Stopped: Stopped due to safety. RTDE Parameter safety status bits.
4. Emergency topped: Emergency stopped . RTDE Parameter safety status bits.
5. Teach Button Pressed: Power button pressed. RTDE Parameter robot status bits.
6. Power Button Pressed: Power button pressed. RTDE Parameter robot status bits.
7. Program State: Program state. RTDE Parameter runtime state.

IO:

1. Tool Output Mode: The current output mode. RTDE Parameter tool output mode.
2. Tool Digital Output 0 Mode: The current mode of digital output 0. RTDE Parameter tool digital output0 mode.
3. Tool Digital Output 1 Mode: The current mode of digital output 1. RTDE Parameter tool digital output1 mode.
4. IO Current: I/O current [mA]. RTDE Parameter io current.
5. Analog In 0: Standard analog input 0 [mA or V]. RTDE Parameter standard analog input 0.
6. Analog In 1: Standard analog input 0 [mA or V]. RTDE Parameter standard analog input 1.
7. Analog Out 1: Standard analog output 1 [mA or V]. RTDE Parameter standard analog output 1.
8. EuroMap67:
   1. Current: Euromap 24V current [mA]. RTDE Parameter euromap67 24V current.
   2. Voltage: Euromap 24V voltage [V]. RTDE Parameter euromap67 24V voltage.
   3. Input Status: Euromap67 input bits. RTDE Parameter euromap67 input bits.
   4. Output Status: Euromap67 output bits. RTDE Parameter euromap67 output bits.
9. Registers:
   1. Output Bit Register X: X: [64..127] - The upper range of the boolean output registers can be used by external RTDE clients. RTDE Parameter output bit register X.
   2. Output Int Register X: X: [0..23] - The lower range of the integer output registers is reserved for FieldBus/PLC interface usage. X: [24..47] - The upper range of the integer output registers can be used by external RTDE clients. RTDE Parameter output int register X.
   3. Output Double Register X: X: [0..23] - The lower range of the double output registers is reserved for FieldBus/PLC interface usage. X: [24..47] - The upper range of the double output registers can be used by external RTDE clients. RTDE Parameter output double register X.
   4. Input Bit Registers 0 to 31: This range of the boolean output registers is reserved for FieldBus/PLC interface usage. RTDE Parameter input bit registers0 to 31.

1. Input Bit Registers 32 to 63: This range of the boolean output registers is reserved for FieldBus/PLC interface usage. RTDE Parameter input bit registers32 to 63.
2. Input Bit Register X: X: [64..127] - The upper range of the boolean output registers can be used by external RTDE clients. RTDE Parameter input bit register X.
3. Input Int Register X: X: [0..23] - The lower range of the integer input registers is reserved for FieldBus/PLC interface usage. X: [24..47] - The upper range of the integer input registers can be used by external RTDE clients. RTDE Parameter input int register X.
4. Input Double Register X: X: [0..23] - The lower range of the double input registers is reserved for FieldBus/PLC interface usage. X: [24..47] - The upper range of the double input registers can be used by external RTDE clients . RTDE Parameter input double register X.

Safety:

1. Safety Mode: Safety mode. RTDE Parameter safety mode.
2. Safety Status: Safety status. RTDE Parameter safety status.
3. Unlock Protective Stop: Not implemented yet.
4. Close Safety Popup: Not implemented yet.

Control:

1. Power On: Not implemented yet.
2. Power Off:Not implemented yet.
3. Brake Release: Not implemented yet. g Alarms:
4. Level: EXCEPTION MESSAGE, ERROR MESSAGE, WARNING MESSAGE, INFO MESSAGE.
5. Message: Alarm message
6. Source: Source that generated the alarm.

OEE:

String variables that do not exist in RTDE context.

1. Availability Info
   1. Available Time
   2. Machine Runtime
2. Performance Info
   1. Parts Could Be Produced
   2. Parts Produced in Total
3. Quality Info
   1. Good Parts Produced
   2. Good Parts Produced in Total

Productivity:

String variables that don’t exist in RTDE context.

1. Personnel
1. Operator
2. Supervisor
2. Work Order
1. Family Info
2. Number of Parts

System Monitor:

1. Avg CPU Load
2. System CPU
3. Process CPU
4. Memory Load
5. Total Memory
6. Used Memory

Revision History

In this section...