The Universal Robots MQTTspB integration (UR MQTTspB) allows you to add a MQTT SparkplugB publisher directly into the Universal Robots using URCap. This guide providers instructions to installing and using the UR MQTTspB and general information about tURCap, MQTT, SparkplugB and RTDE clients.
On this page:
The URCap application consists of three separate processes running in parallel.
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.
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.
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.
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.
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.
1.3. Use WinSCP (or a similar SFTP/SCP software) to connect to your robot.
Using WinSCP for File Transfer If you are not familiar with accessing the filesystem of your Universal Robots (UR) device, we recommend using a tool like WinSCP.
|
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
1.4. Once connected, navigate to the Programs folder (/Programs/) on the robot's system and create a new folder named "MQTTspB URCaps".
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.
1.7. To complete the installation, restart Polyscope.
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
2.3. Switch to the Communication Manager tab.
Enter the following information:
The Robot IP address was previously defined on the System Configuration:
3.1. In the Communication Manager tab also contains Start/Stop buttons for both MQTTspB and RTDE Client connections.
4.1. Navigate to the 'License' tab.
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'.
You can verify the status of modules in the Communication Manager tab, near the Start/Stop buttons.
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.
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> |
<Name>:
<BrokerURL>:
<Port>:
<ClientId>:
<UserName> and <Password>:
<x509Certificate>:
<CertificatePassword>:
<NetworkSecurity>:
<QoS>:
<KeepAlive>:
<PublishRate>:
<Topic>:
<AutoRun>:
<Variables>:
<IpAddress>:
<Port>:
<Frequency>:
<AutoRun>:
For the application to accurately read the file, certain criteria MUST be fulfilled:
A sample configuration file can be downloaded here.
If no file is found when loading up the PolyScope, the configuration fields will be completed with default settings. The file is updated with the configured parameters every time a Client is started or stopped. Also, a new file is created if it does not exist. |
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 utilized is detailed as:
<Joint_Control_Currents RBE_DeadBand="Absolute;0.1" Enable_Publish="true"> </Joint_Control_Currents> |
There are two possible RBE DeadBand options:
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.
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 MQTT Client.
This section will detail how the DataStructure is modeled.
Robot Name
Can be customized with the XML file only.
Arm Info
Controller Info
Metadata
UNS
String variables that do not exist in RTDE context:
Control
Status:
IO:
Safety:
Control:
OEE:
String variables that do not exist in RTDE context.
Productivity:
String variables that do not exist in RTDE context.
System Monitor:
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 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: