Page History

Quick Start Guide

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. 

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 

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

2.2. Click to open the configuration window. 

Step 3: Connecting to the MQTT Broker and Setting up Configuration 

3.1. Select the MQTT Broker Info tab and fill in the necessary information for the MQTTspB Client. 

3.2. Switch to the Communication Manager tab. Here, enter the name of the robot, the MQTTspB Topic/Address, and the Robot IP Address (required for RTDE connection). 

Remember to ensure that your target audience understands the technical language used in this guide. It could also be beneficial to include more explanatory detail or troubleshooting steps for complex procedures.

System Requirements

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

• UniversalRobotsPolyScopeversion5.11andPhysicalRobot.
• URCapfile(*.urcap)
• SSL Certificates

Overview

TheURCapapplicationconsists of threeseparateprocessesrunninginparallel.

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

MQTTandRTDEdefinitionsareavailableintheendofthissection. This program behavior is illustrated as per image below.

Image Added

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,pleasereferto 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. Download the OFFLINE SIMULATOR UR SIM version 5.11.0. The link for downloadingisavailable for Windows. Note thatyou'llneed a Virtual Machine (VM) torunthesimulator. Both VirtualBoxorVMWare are compatible.
2.  Configure your Virtual Machine. Detailedinstructions for configurationcanbefoundonthe Universal Robots site. 
3. Create an "MQTTspB URCaps" folder inside the programsFolder (/Programs/). This can be done in the Settings → UrCaps → New button.
   
   
   Image Added Image Added
   Image Added Image Added
4. 1. Download?and Copy the *.urcap file into the PolyScope programs Folder (/Programs/MQTTspB URCaps). For this step you need to install the Guest Additions for your virtual machine software if you using VirtualBox or the VMware Tools if you using VMWare. The sudo password of VM is on the virtual machine's home screen - easybot. 
   2. If you are using Virtual Box, even you install the Gust Additions, you maybe still cannot drag and drop or copy files. In option, you can configure a Shared Folder to share the urcap file for the virual machine. Additionly, you can change the screen resolution typing xrandr in command shell to see the screen name and after this typing xrandr --output <screen_name> --mode <resolution>. 
    
5. OpenyourProgrammingEnvironment(PolyScope).
6. GotoProgramSettings(1) → System(2) → URCaps(3). Clickontheplus (+)buttonand search for your *.urcap file.
   Image Added
7. RestartthePolyScopetofinalizetheimportprocedure.
   Image Added
   

Using the URCap

Thisnewtoolwillbeavailableafterimportingthe*.urcap fileandrestartingthesimulator.

1. GotoInstallationTab(1) → URCaps(2) → MQTTspBPublisher(3).
2. Clickonittoopentheconfigurationwindow intherightpanel.

Image Added

Therearethreetabs:MQTTBrokerInfo,CommunicationManagerandLicense.

• InMQTTBrokerInfo, enter theinformationfortheMQTTspBClient(similartowhatisdoneat your Project).
• In Communication Manager, enter the MQTTspB Topic/Address, Robot IP Address (for RTDE connection), and command buttons.

Image Added

• LicensewillcontaininformationaboutyourURCaplicensestatus.

Image Added

Configuration Tab

• BrokerURL:MQTT Broker(Server)URL.
• Port:MQTT Broker port.ItmustbethesameportthatisconfiguredintheBrokertobelistening.
• ClientId: Indicatestheclientidentificationusedfor 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 mandatoryif 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 guaranteeofdelivery,duetotherecipientnotacknowledgingthereceiptofthemessage.
• AtLeastOnce:This service guarantees that a message is delivered at least once to thereceiver.
• ExactlyOnce: Highestlevelofservice. It issafer,butslowerwhencomparedtotheothers. When themessageflowiscomplete, allpartiesinvolvedinthecommunicationaresurethemessage 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.

• PublishRate: Indicatesthetimeforpublishinginms. Themessagestobepublishedaregrouped 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.
• MqttTopic:Topicintowhichthepayloadwillbepublished.Thesyntaxwillbe: <GroupId>/<NodeId>/<DeviceId>.

• RobotIp:IP addressfortheRTDEconnection. Note: The "Robot IP Address" fieldacceptsonlyvalid IP addresses. Make suretoenter a valid IP address, no otherstrings are accepted.
• Frequency: Reading frequency for the RTDE Protocol. Should be a value in the range of 125 to 500Hz.

• AutoRun:Flagindicatingif the clientshouldstartautomatically.Thisvaluewillbestoredin ConfigFile.xmlfornextprogramexecution.(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

Tolicenseyourapplication,youneedtocreateasoftkeylicensewhichisgeneratedbytheequipment

SiteCode.

1. GotoInstallation → MQTTspBPublisher → LicenseandclickGetSiteCode.
2. Send the generated file to one of our employees, and they will generate a license key.
3. ClicktheLoad License KeybuttonontheLicensetabtoloadthereceivedkey.

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

TheprotocolavailableforthisapplicationisRTDE.

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>

To ensure the file is loaded by the program, certain requirements MUSTbe met:

1. FileName:ThefilemustbenamedConfigFile.xml.
2. FilePath:Thefilemustbelocatedeitherinsidethe (/Programs/MQTTspB URCaps) folder.

The file will be parsed every time PolyScope is launched (as long as the URCapis already installed). You CANNOT alter its information while the program is running.

Asampleconfigurationfilecanbedownloaded here.

VariablesentryallowsyoutoEnable/DisableDataModelbranchesandcustomizeabranch’sChange 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.

Thesyntaxtobeusedisasfollows:

Where:

• [VariableName]isapathnamein thetreedatamodel;forexampleJointControlCurrents.
• [RBE DeadBand=<RBEOptions>;<Value>]isareporttypewhereuserscandefinean”Absolute”or”Percentual”deadbandforeachBranch—itwillbeappliedtoallvariablesbellowthatbranch. ValueChangesexceedingthedeadbandwillbeconsideredanevent.Thedeadbandparameters are separated by a semicolon (;).
• [RBEOutOfRange=<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 outsidethe threshold interval will be considered an event.The deadband parameters are separated by a semicolon (;).

• [EnablePublish=”true”or”false”]willenableordisablethepublishingdataofalltreebellowthis tree point.

Example

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

TherearetwopossibleRBEDeadBandoptions:

• Absolute:Deadbandvalueisabsolutevalue.
• Percentual:Deadbandiscalculatedbasedonpercentualvalues.

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

ThisentrycanbecustomizedONLYthroughthe.xmlfile.

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 Added

Implemented Robot Variables

ThissectionwilldetailhowtheDataStructureismodeled.

Robot Name

CanbecustomizedwiththeXMLfileonly.

Arm Info

Axis:

1. Target JointPositions:RTDEParametertarget q.
2. TargetJoint Velocities:RTDEParametertarget qd.
3. TargetJointAccelerations:RTDEParametertargetqdd.
4. TargetJointCurrents:RTDEParametertargetcurrent.
5. TargetJointMoments:RTDEParametertargetmoment.
6. JointControlCurrents:RTDEParameterjointcontroloutput.
7. Joint Temperatures:Temperature of each joint in degrees Celsius.RTDE Parameter joint temperatures.
8. JointVoltages: Actualjointvoltages. RTDEParameteractualjointvoltage.
9. Joint Position:Actualjointposition.RTDEParameteractual q.

Tool Center Point:

1. ActualTCPForce:GeneralizedforcesintheTCP.Itcompensatesthemeasurementfor 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, ryandrzisarotationvector representation ofthetoolorientation.RTDEParameter actual TCP pose.
3. Actual TCP Speed: ActualspeedofthetoolgiveninCartesiancoordinates. Thespeed isgivenin[m/s]andtherotationalpartoftheTCPspeed(rx,ry,rz)istheangulargiven in [rad/s]. RTDE Parameter actual TCP speed.
4. Payload:
   1. Mass:Payloadmass in kg.RTDEParameterpayload.
   2. PayloadCoG:PayloadCenterofGravity(CoGx,CoGy,CoGz) in mm.RTDEParameter payload cog.
   3. PayloadInertia:Payloadinertiamatrixelements(Ixx,Iyy,Izz,Ixy,Ixz,Iyz]expressedin kg.mm².RTDEParameterpayloadinertia.
5. Tool:
   1. ToolMode:Toolmode.RTDEParametertool mode.
   2. ToolAnalogInput0:Toolanaloginput0[mAorV].RTDEParametertoolanaloginput0.
   3. ToolAnalogInput1:Toolanaloginput1[mAorV].RTDEParametertoolanaloginput1.
   4. Tool OutputVoltage:Tooloutputvoltage[V].RTDEParametertooloutput voltage.
   5. ToolOutputCurrent: Toolcurrent[mA].RTDEParametertooloutputcurrent.
   6. Tool Temperature:TooltemperatureindegreesCelsius.RTDEParametertooltemperature.
   7. ToolForceScalar:TCPforcescalar[N].RTDEParametertcpforcescalar.
   8. Wrist3:RTDEParameteractualTCPpose.

Controler Info

1. Timestamp: Timeelapsedsincethecontrollerwasstarted[s]. RTDEParametertimestamp. Controller Temp: TooltemperatureindegreesCelsius. RTDEParametertool temperature. Main Voltage: Safety Control Board: Main voltage. RTDE Parameter actual main voltage.
2. Current: SafetyControlBoard: Robotcurrent. RTDEParameteractual robot current. eAvg Robot Power: givenbytheexpression(Σ(ActualRobotCurrent∗ActualRobotVoltage))
3. IOCurrent:I/Ocurrent[mA].RTDEParameteriocurrent.
4. ToolCurrent:Toolcurrent[mA].RTDEParametertooloutputcurrent.

Metadata

UNS

Stringvariables thatdo notexistinRTDEcontext:

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. SpeedSliderFraction:Newspeedslidervalue.RTDEParameter : speedsliderfraction.
3. StandardDigitalOutput:Standarddigitaloutputs.RTDEParameter :standarddigitaloutput.
4. Configurable Digital Output:Configurabledigitaloutputs.RTDEParameter :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]-Theupperrangeofthebooleaninputregisterscan be used by external RTDE clients. RTDE Parameter :  input bit register X.
9. Input IntRegister X: X: [0..23] - The lower range of the integer input registers is reservedforFieldBus/PLCinterfaceusage. X:[24..47]-TheupperrangeoftheintegerinputregisterscanbeusedbyexternalRTDEclients.RTDEParameter : inputintregisterX.
10. Input Double Register X:X:[0..23]-Thelowerrangeofthedoubleinputregisters 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. ExternalForceTorque:Inputexternalwrenchwhenusingftrtdeinputenablebuiltin. RTDEParameter :externalforcetorque.

Status:

1. RobotMode:Robotmode.RTDEParameter: robotmode.
2. RobotPowerOn: Poweron.RTDEParameter:robotstatusbits.
3. SecurityStopped: Stoppedduetosafety.RTDEParameter:safetystatusbits.
4. Emergency Stopped: Emergencystopped.RTDEParameter:safetystatusbits.
5. TeachButtonPressed: Teach buttonpressed.RTDEParameter:robotstatusbits.
6. PowerButtonPressed: Powerbuttonpressed.RTDEParameter:robotstatusbits.
7. ProgramState:Programstate.RTDEParameter:runtimestate.

IO:

1. ToolOutputMode:Thecurrentoutputmode.RTDEParameter:tooloutputmode.
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. IOCurrent:I/Ocurrent[mA].RTDEParameter:iocurrent.
5. AnalogIn0:Standardanaloginput0[mAorV].RTDEParameter:standardanaloginput0.
6. AnalogIn1:Standardanaloginput0[mAorV].RTDEParameter:standardanaloginput1.
7. AnalogOut1:Standardanalogoutput1[mAorV].RTDEParameter:standardanalogoutput1.
8. EuroMap67:
   1. Current:Euromap24Vcurrent[mA].RTDEParameter:euromap6724Vcurrent.
   2. Voltage:Euromap24Vvoltage[V].RTDEParameter: euromap6724Vvoltage.
   3. InputStatus:Euromap67inputbits.RTDEParameter: euromap67inputbits.
   4. OutputStatus:Euromap67outputbits.RTDEParameter: euromap67outputbits.
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 registersis 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]-Thelowerrangeofthedoubleoutputregisters is reserved for FieldBus/PLC interface usage.X: [24..47] - The upper range of thedoubleoutputregisterscanbeusedbyexternalRTDEclients. RTDEParameter: output double register X.
   4. Input Bit Registers 0 to 31: Thisrangeoftheboolean input registersisreserved for FieldBus/PLC interface usage. RTDE Parameter: input bit registers0 to 31.
   5. InputBit Registers 32 to 63: Thisrangeoftheboolean input registersisreserved for FieldBus/PLC interface usage. RTDE Parameter: input bit registers 32 to 63.
   6. Input Bit Register X:X:[64..127]-Theupperrangeoftheboolean 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]-Thelowerrangeofthedoubleinputregisters 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. SafetyMode: Safetymode. RTDEParameter:safetymode.
2. SafetyStatus:Safetystatus. RTDEParameter:safetystatus.
3. UnlockProtectiveStop:Notimplementedyet.
4. CloseSafetyPopup:Notimplementedyet.

Control:

1. PowerOn:Notimplementedyet.
2. PowerOff:Notimplementedyet.
3. BrakeRelease:Notimplementedyet. 
4. Alarms Level:EXCEPTIONMESSAGE,ERRORMESSAGE,WARNINGMESSAGE,INFO MESSAGE.
5. Message:Alarmmessage.
6. Source:Sourcethatgeneratedthealarm.

OEE:

Stringvariablesthatdo notexistinRTDEcontext.

1. AvailabilityInfo
   1. AvailableTime.
   2. MachineRuntime.
2. PerformanceInfo
   1. PartsCouldBeProduced.
   2. PartsProducedinTotal.
3. QualityInfo
   1. GoodPartsProduced.
   2. GoodPartsProducedinTotal.

Productivity:

Stringvariablesthatdo notexistinRTDEcontext.

1. Personnel
1. Operator.
2. Supervisor.
2. WorkOrder
1. FamilyInfo.
2. NumberofParts.

System Monitor:

1. AvgCPULoad.
2. SystemCPU.
3. ProcessCPU.
4. MemoryLoad.
5. Total Memory.
6. UsedMemory.

Revision History

In this section...