Page History

 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.

EdgeGateway for Universal Robots 

System Requirements

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

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

How Does it Work?

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.

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.

How to Install

1. Create a "MQTTspB URCaps" folder inside the programsFolder (/Programs/). This can be done in the Settings → UrCaps → New button.
   
   
   
   
2.  > > Download < < andCopythe*.urcapfileintothePolyScopeprogramsFolder (/Programs/MQTTspB URCaps). 
3. OpenyourProgrammingEnvironment(PolyScope).
4. GotoProgramSettings(1) → System(2) → URCaps(3). Clickontheplus (+)buttonand search for your *.urcap file.
   
5. RestartthePolyScopetofinalizetheimportprocedure.
   
   

Using the URCap

Thisnewtoolwillbeavailableafterimportingthe*.urcap fileandrestartingthesimulator.

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

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.

• LicensewillcontaininformationaboutyourURCaplicensestatus.

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:Passwordcreatedwhen Certificate wasexported(if necessary).
• NetworkSecurity: Thisfieldismandatoryif MQTT Broker worksusing a certificate,andmustbethe same that was configured in MQTT Broker (if necessary). The options are None and TLS.
• QoS:QualityofService(QoS)isanagreementbetweensenderandreceiverofamessageregarding 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.
• 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.

Import Configuration Parameters From File

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>]isareporttypewhereuserscandefineaMin/Maxthreshold for each Branch — it will be applied to all variables bellow 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.

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

WhentheMQTTspBClientisstarted,ifconnectedtotheBroker,youshouldbeabletoseetheRobot Model using a different Client. The images below illustrate the model with FRAMEWORXclient.

Implemented Robot Variables

ThissectionwilldetailhowtheDataStructureismodeled.

RobotName

CanbecustomizedwiththeXMLfileonly.

ArmInfo

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.

1. InputBit Registers 32 to 63: Thisrangeoftheboolean input registersisreserved for FieldBus/PLC interface usage. RTDE Parameter: input bit registers 32 to 63.
2. Input Bit Register X:X:[64..127]-Theupperrangeoftheboolean input registers can be used by external RTDE clients. RTDE Parameter: input bit register X.
3. 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.
4. 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