The following document contains a description of how to install and use the MQTTspB Client URCap on real Universal Robots or Universal Robots Simulator applications (URSim). This includes information on URCap, MQTTspB, and RTDE Clients.
On this page:
This guide will walk you through the process of installing and configuring MQTTspB URCaps in Tatsoft's FrameworX and FactoryStudio.
Step 1: URCap Installation
1.1. Download the OFFLINE SIMULATOR UR SIM version 5.11.0. (The link for downloading is available for Windows.)
Note: For Windows users, a Virtual Machine will be necessary to run the simulator.
1.2. After downloading, create a new folder named "MQTTspB URCaps" in the Programs folder (/Programs/).You can create a new folder by going to Settings → UrCaps → New button.
1.3. Download the *.urcap file and copy it into the newly created PolyScope Programs Folder (/Programs/MQTTspB URCaps).
To complete this step, you will need to install the virtual machine guest additions.
1.4. Launch your programming environment (URSim UR). Navigate to Program Settings → System → UR Caps.Click on the plus (+) button and browse for your *.urcap file.
1.5. 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. Click to open the configuration window.
2.3. Select the MQTT Broker Info tab and fill in the necessary information for the MQTTspB Client.
2.4. Switch to the Communication Manager tab.
2.4.1. Enter the name of the robot.
2.4.2. The MQTTspB Topic/Address
2.4.3. The Robot IP Address (required for RTDE connection).
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.
To make use of this feature, the following system requirements need to be met:
Security is a crucial part of any automation system. MQTTspB Client URCap supports using TLS/SSL secure connections to protect your MQTT communications. This requires configuring certificates, which provide the necessary authentication to establish a secure connection.
For the MQTT Broker to operate effectively, you need several certificate files: a Server Certificate, a Client Certificate, a Client Certificate Key, and the Private Key Password. These files are in the .pem format. You must supply the paths to these .pem files to the publisher.
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. 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.
This new tool will be available after importing the *.urcap file and restarting the simulator.
There are three tabs: MQTT Broker Info, Communication Manager and License.
This tab also contains Start/Stop buttons for both MQTTspB and RTDE Client connections. |
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.
To license your application, you need to create a softkey license which is generated by the equipment
SiteCode.
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.
More licensing methods will be added in the future. |
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.
You can verify the status of modules on the Communication Manager tab, close of the Start/Stop buttons.
There is also available the module status on toolbar where exist the UR+ option. 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> |
To ensure the file is loaded by the program, certain requirements MUST be met:
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.
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 used is as follows:
Where:
<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 different Client. The images below illustrate the model with FRAMEWORXclient.
This section will detail how the DataStructure is modeled.
Can be customized with the XML file only.
String variables that do not exist in RTDE context:
String variables that do not exist in RTDE context.
String variables that do not exist in RTDE context.
This section provides guidance on how to solve some common issues you may encounter while using the MQTTspB Client URCap.
Virtual Machine Issues: Virtual machines can occasionally present their own unique set of challenges. Here are a few common issues and their solutions:
Remember that many issues with virtual machines are specific to the virtualization software being used (e.g., VirtualBox, VMware), so consult the corresponding documentation or support resources for software-specific issues.
Connection Errors: If you're experiencing trouble connecting to the MQTT Broker, ensure you've correctly entered the Broker's information in the MQTT Broker Info tab. Confirm the accuracy of 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 transmitting as expected, verify that the topics/addresses and command buttons in the Communication Manager tab are correctly configured.
URCap Installation Problems: If you're having issues installing the URCap, ensure you've correctly followed the installation steps. The *.urcap file needs to be placed in the correct folder, and PolyScope must be restarted after the installation.
Certificate Errors: If there are errors regarding certificates, ensure that all the necessary certificate files are present and correctly linked. Double-check that the files are in the correct .pem format and that the paths in the publisher are correctly set.
URCaps Revision History | |
---|---|
Version | Notes |
1.0.1.0 1.0.2.0 | Initial release on new documentation standards. Included Quick start and Troubleshooting section. |