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)

Functionality Overview

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

• Graphical User Interface: This is the main URCap application. It runs within the robot (PolyScope), handles communication parameters, and can start/stop the client connections.
• RTDE Client: This is a client implementation for the RTDE protocol, running on an independent thread. It 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: This is a client implementation for the MQTTspB protocol, running on an independent thread. It receives data from the RTDE (through the main program) and publishes it 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). However, the MQTT client does not publish at the same rate. It only publishes new data if any variable has changed its value since the last reading.

MQTT: A lightweight, publish-subscribe network protocol that transports messages between devices. SparkPlugB includes additional control and standards, allowing for information about birth, death, and 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.

Installation

1. Create an "MQTTspB URCaps" folder inside the programs Folder (/Programs/). This can be done in the Settings → UrCaps → New button.
   
   
   
   
2. Download and Copy the *.urcap file into the PolyScope programs Folder (/Programs/MQTTspB URCaps). 
3. Open your Programming Environment (PolyScope).
4. Go to Program Settings (1) → System (2) → UR Caps (3). Click on the plus (+) button and search for your *.urcap file.
   
5. 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 window in the right panel.

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

• In MQTT Broker Info, enter the information for the MQTTspB Client (similar to what is done at your Project).
• In Communication Manager, enter 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 (if necessary).
• Password: Password defined in MQTT Broker. This will be requested if the Broker needs this configuration (if necessary).
• Server Certificate: Path of the .pem file for the server. This is required if the MQTT Broker uses a server-side certificate for
  authentication. The complete path of the .pem file on the client computer must be provided.
• Client Certificate: Path of .pem Client Certificate. If using server-side only certificate this field does not need to be configured. This must be the complete path of .pem certificate in the client computer. Also, the certificate must be installed.
• Client Certificate Key: Path of the .pem key file of the Client Certificate. This key file is used to authenticate the client-side certificate and establish a secure connection with the MQTT Broker.
• CertificatePassword: Password created when Certificate was exported (if necessary).
• NetworkSecurity: This field is mandatory if MQTT Broker works using a certificate, and must be the same that was configured in MQTT Broker (if necessary). 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. The QoS 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 sent 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 milliseconds.

Communication Manager Tab

• Robot Name: Defines the name of the robot, which 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: Reading frequency for the RTDE Protocol. Should be a value in the range of 125 to 500Hz.

• AutoRun: Flag indicating if the 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.

If you want to load the license key using a USB, follow these steps:

a. Save the license key file to a USB drive.

b. Insert the USB drive into the robot controller.

c. Open the "MQTTspB URCaps" folder inside the "Programs" folder on the robot controller.

d. Copy the license key file from the USB drive into the "MQTTspB URCaps" folder.

e. Go to the License tab in the URCaps and click on the "Load License Key" button.

f. Select the license key file from the "MQTTspB URCaps" folder to load it into the URCaps.

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.

Importing Configuration Parameters

In addition to manually entering configuration parameters in the PolyScope Installation Tab, you can also 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 ensure the file is loaded by the program, certain requirements MUST be met:

1. FileName: The file must be named ConfigFile.xml.
2. FilePath: The file must be located either inside the  (/Programs/MQTTspB URCaps) folder.

The file will be parsed every time PolyScope is launched (as long as the URCap is already installed). You CANNOT 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 the 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 below 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 variable customizations 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 UDTs (User-Defined Types). Click here to download an example *.html file.

When the MQTTspB Client is started, if connected to the Broker, you should be able to see the Robot data 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 in kg. RTDE Parameter payload.
   2. Payload CoG: Payload Center of Gravity (CoGx, CoGy, CoGz) in mm. RTDE Parameter payload cog.
   3. Payload Inertia: Payload inertia matrix elements (Ixx,Iyy,Izz,Ixy,Ixz,Iyz] expressed in kg.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. Controller Temp: Tool temperature in degrees Celsius. RTDE Parameter tool temperature. 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 do not exist in RTDE context:

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

Control

1. Speed Slider Mask: 0 = do not change the speed slider with this input. 1 = use the speed slider fraction to set the 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. 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 Stopped: Emergency stopped . RTDE Parameter: safety status bits.
5. Teach Button Pressed: Teach 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 input registers is reserved for FieldBus/PLC interface usage. RTDE Parameter: input bit registers0 to 31.
   5. Input Bit Registers 32 to 63: This range of the boolean input registers is reserved for FieldBus/PLC interface usage. RTDE Parameter: input bit registers 32 to 63.
   6. 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.
   7. 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.
   8. 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. 
4. Alarms 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 do not 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...