Page History

System Requirements

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

• Universal Robots Physical robot with PolyScope version 5.11andPhysicalRobot. 
• URCap file (*.urcap)

Functionality Overview

• 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.

Image Removed

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.

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

Image Removed

Image Removed

Image Removed

Image Removed

Image Removed

procedure.
Image Removed

Using the URCap

Image Removed

Image Removed

Image Removed

Configuration Tab

• . 
• SSL Certificates (Optional: only if TLS is to be implemented). 
• Basic understanding of the use and operation of the MQTT protocol. If you are not familiar with MQTT, we suggest you review the appropriate resources to gain a fundamental understanding. 
• Familiarity with the Linux system to access the license files and other robot information. If you're using a Windows system, an SFTP or SCP software (e.g. WinSCP) might be required for transferring files. 

Concepts Review

URCap 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. The MQTT client can connect to an MQTT broker located on any accessible network, not being restricted to the same local network as the robot.

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.

MQTT Broker 

An MQTT broker is a lightweight, efficient messaging middleware used in the Internet of Things (IoT) and other connected applications. It acts as an intermediary between devices and applications, facilitating the exchange of data in a publish-subscribe model. Clients, such as sensors or smart devices, publish messages to specific topics on the broker, which then disseminates these messages to interested subscribers. The broker ensures reliable message delivery, minimal bandwidth usage, and low latency, making it ideal for resource-constrained environments. Its simplicity, scalability, and support for real-time communication make it a popular choice for securely managing and orchestrating communication in decentralized networks. 

For the purpose of this guide, it is assumed that you already have an MQTT broker up and running. If you do not have one in place, please consult the relevant documentation or your system administrator for assistance in setting one up.

SSL Certificates 

Security is a crucial part of any automation system. MQTTspB Client URCap supports using TLS/SSL secure connections to protect your MQTT communications. To utilize this feature, you should acquire certificates in the PEM format from the MQTT broker administrator. 

Please note that to establish a secure connection, you would need several certificate files, including a Server Certificate, a Client Certificate, a Client Certificate Key, and the Private Key Password. Make sure to supply the paths to these .pem files to the publisher when setting up. 

Installation 

This section walks you through the process of installing and configuring MQTTspB URCaps on Universal Robots products: UR20, UR10e, UR3e, UR5e, UR16e, which have the Polyscope software embedded on them. 

Anchor
#step1 #step1

Step 1: URCap Installation

1.1. Ensure that your Universal Robots product is running at least Polyscope version 5.11.0. 

1.2. Download the *.urcap file on your computer. 

 Image Added

1.3. Use WinSCP (or a similar SFTP/SCP software) to connect to your robot. 

 You will need the IP address of the robot for this. The default user is "ur" and the password is "easybot" 

Open WinSCP and create a new session

Image Added

Image Added

1.4. Once connected, navigate to the Programs folder (/Programs/) on the robot's system and create a new folder named "MQTTspB URCaps". 

 Image Added

1.5. Copy the downloaded *.urcap file (or just drag and drop) into the newly created PolyScope Programs Folder (/Programs/MQTTspB URCaps). 

1.6. On your Universal Robots product, navigate to Program Settings → System → UR Caps. Click on the plus (+) button and browse for your *.urcap file. 

Image AddedImage Added

 Image AddedImage Added

1.7. To complete the installation, restart Polyscope. 

Step 2: URCap Configuration

Connecting to the MQTT Broker and Setting up Configuration 

2.1. To begin configuration, navigate to Installation Tab → UR Caps → MQTTspB Publisher. 

2.2. Open the configuration window and select the MQTT Broker Info tab. Fill in the necessary information for the MQTTspB Client. 

Configuration Tab 

  Image Added

• Broker URL: MQTT Broker(Server) URL. 
• Port : This is the port number of the MQTT Broker. The default for MQTT is port 1883 for unencrypted connections and port 8883 for SSL/TLS secure connections. Ensure that the corresponding port is open on any firewalls that may be in place to allow proper communication between the client and server. Communication failures may occur if the specified port is closed by the firewall. Therefore, it is recommended that you check your firewall settings or contact your network administrator if you encounter connection problems. 
• ClientId: Indicates the client identification usedfor 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 forauthentication. 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 indicates the type of network security used in communication with the broker. The options are "None" and "TLS". If you are using TLS, ensure to provide the appropriate certificates. Otherwise, this feature can be bypassed. 
• 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. 

2.3. Switch to the Communication Manager tab.

Image Added

Enter the following information:

• 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 is: <GroupId>/<NodeId>/<DeviceId>. To fully understand the meaning of these terms, refer to the MQTTspB specification. 
• Robot IP: IP address for the RTDE connection. This will be the same IP of your UR device since Polyscope is embedded into the UR. Note: The "Robot IP Address" field accepts only valid IP addresses. Make sure to enter a valid IP address, no other strings are accepted. 
• 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). 

The Robot IP address was previously defined on the System Configuration:

Image Added

Step 3: Running the MQTTspB URCaps 

3.1. In the Communication Manager tab also contains Start/Stop buttons for both MQTTspB and RTDE Client connections.  

Step 4: Obtaining the License 

4.1. Navigate to the 'License' tab. 

Image Added

4.2. Click on the 'Get SiteCode' button. This action will generate a .txt file in the /root/GUI folder. 

4.3. Transfer the generated file to our support team at support@tatsoft.com. If you're transferring the file to a Windows system, you can use WinSCP or a similar SFTP program. 

4.4. Transfer the Site code that our support team sends back to you, to the Universal Robots product. 

4.5. In Polyscope, navigate to 'MQTT Publisher' -> 'License Tab' -> 'Load License Key'. Then select the file and click 'Open'. 

Image Added

MQTTspB and RTDE Client Connections Status

You can verify the status of modules in the Communication Manager tab, near the Start/Stop buttons.

Image Added

There is also a module status available on the toolbar where the UR+ option exists. This is an easy way to verify the current status.

Image Added

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.

Thesyntaxforthisfileisasfollows:

<?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>

Configuration Parameters Guide 

<Robot>

<Name>: 

• Description: The unique name assigned to the robot. 
• Format: String. 

<MQTT_Client>

<BrokerURL>: 

• Description: The URL of the MQTT broker to which the client should connect. 
• Format: String with URL format (e.g.: mqtt://broker.example.com). 

<Port>: 

• Description: The port number for the MQTT connection. 
• Format: Integer (e.g. 1883). 

<ClientId>: 

• Description: Unique identifier for the client in the MQTT broker. 
• Format: String. 

<UserName> and <Password>: 

• Description: Credentials for authentication to the MQTT broker, if required. 
• Format: String. 

<x509Certificate>: 

• Description: Path to the x509 certificate, used when SSL is enabled. 
• Format: Path to the file. 

<CertificatePassword>: 

• Description: Password of the x509 certificate. 
• Format: String. 

<NetworkSecurity>: 

• Description: Specifies the network security type for the MQTT connection. 
• Options: None, SSL. 

<QoS>: 

• Description: Quality of service for MQTT messages. 
• Options: AtMostOnce, AtLeastOnce, ExactlyOnce. 

<KeepAlive>: 

• Description: Time interval (in seconds) that the client must wait between sending control packets. 
• Format: Integer. 

<PublishRate>: 

•  Description: rate at which MQTT messages are published. 
• Format: Integer, in milliseconds. 

<Topic>: 

• Description: The MQTT topic in which the messages are published. 
• Format: String with the topic structure (e.g. GroupId/NodeId/DeviceId_01). 

<AutoRun>: 

• Description: If true, starts MQTT communication automatically upon initialization. 
• Options: true, false. 

<Variables>: 

•  Description: List of variables with additional settings. 
• Format: Commented in XML, by default. Can be uncommented and configured as needed.
  

<RTDE_Client>

<IpAddress>: 

• Description: The IP address of the RTDE client. 
• Format: String with IP address format (e.g. 192.168.1.1). 

<Port>: 

• Description: The port number for the RTDE connection. 
• Format: Integer (e.g. 30004). 

<Frequency>: 

• Description: Communication frequency in Hz. 
• Format: Integer. 

<AutoRun>: 

• Description: If true, starts RTDE communication automatically on initialization. 
• Options: true, false.

For the application to accurately read the file, certain criteria MUST be fulfilled: 

• FileName: The document should be named ConfigFile.xml.
• FilePath: The document should be positioned within the /Programs/MQTTspB URCaps directory.
• PolyScope will interpret this file each time it's initiated (provided the URCap has been installed). Modifying its content while the software operates is NOT permitted.
• In scenarios where the file is absent during PolyScope's boot-up, the configuration fields will be populated with standard settings. Each time a Client is activated or halted, the file is refreshed to mirror the configured parameters. Moreover, if absent, a new file is generated.
• The Variables entry permits users to activate or deactivate DataModel branches and also modify a branch's Change Event Definition. This configuration dictates when an event should be communicated to the MQTT Broker. By default, or if the entry is devoid of data, all alterations will be documented. 

<?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>

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

Robot Runtime DataModel

TheDataModelpublishedtotheMQTTBrokerispre-definedbasedonvariousUDTs(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.Image RemovedMQTT Client. 

Implemented Robot Variables

ThissectionwilldetailhowtheDataStructureismodeled.

Robot Name

CanbecustomizedwiththeXMLfileonly.

Arm Info

Axis:

Troubleshooting 

This section provides guidance on how to solve some common issues you may encounter while using the MQTTspB Client URCap. 

WinSCP Errors: 

WinSCP is commonly utilized to transfer files and access the robot. Here are some frequent issues and their fixes: 

• Connection Timeout or Refused: Ensure you're using the correct IP address and port for the robot. Check if the robot is powered on and reachable on the network. Sometimes, restarting both the robot and the computer can help. 
• Authentication Failed: This error can arise if you enter the wrong username or password. Verify your credentials and try again. 
• Unable to Transfer Files: If you're having problems transferring files, check the available storage on the robot. Additionally, verify the file's format and size are supported by the robot's system. 
• Permission Denied: You might not have the required permissions to access specific directories or files on the robot. Ensure you're logged in with the right user privileges. 
• Host has not answered for more than 15 seconds: This could be due to a temporary network glitch or the robot being busy. Click "Retry" a couple of times. If it continues, check your network connection. 

Connection Errors: 

If you're having difficulty connecting to the MQTT Broker, ensure you've entered the Broker's details accurately in the MQTT Broker Info tab. Validate the Server and Client Certificates, Client Certificate Key, and the Certificate Password. Ensure the .pem files are accessible and correctly linked in the publisher.  

Data Transmission Issues: 

If data isn't being sent as anticipated, confirm that the topics/addresses and command buttons in the Communication Manager tab are set up correctly. 

URCap Installation Problems: 

For any issues encountered during URCap installation, ensure you've followed the installation procedures correctly. The *.urcap file should be in the right directory, and PolyScope must be rebooted post-installation. 

Certificate Errors: 

For certificate-related errors, ensure all essential certificate files are available and appropriately linked. Verify the files are in the correct .pem format and that the paths in the publisher are set accurately. 

In this section:

1. Operator.
2. Supervisor.