Page History

The  The following document contains a description of how to install and use the MQTTspB Client URCap on Real real Universal Robots or Universal Robots Simulator application 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?

TheURCapapplicationconsistsinthreeseparateprocessesrunninginparallel.

• Graphical User Interface: ItThis is the main URCap application. It runs insidewithin the Robotrobot (PolyScope), handles the communication parameters, and can Startstart/Stop stop the client connections.
• RTDE Client: ClientThis is a client implementation for the RTDE protocol, running on an independent thread. Reads It reads real-time data from the Robot robot and forwards it to the main program so it can be published to an MQTT Broker.
• MQTTspB Client: Client This is a client implementation for the MQTTspB protocol, running on an independent thread. Receives It receives data from the RTDE (through the main program) and publishes it to the Brokerbroker.

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

The RTDE protocol generates messages every 8ms (125Hz).The However, the MQTT client , however, will does not publish at the same rate. It will only publishpublishes new data if any variable hadhas changed its value changed since the last reading.

MQTT: A lightweight, publish-subscribe network protocol that transports messages between devices. TheSparkPlugBhas includes additional control and standards, allowing to knowfor information about birth, death, and a 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 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. Clickonittoopentheconfigurationwindowswindow intherightpanel.

Therearethreetabs:MQTTBrokerInfo,CommunicationManagerandLicense.

• InMQTTBrokerInfo,insert enter theinformationfortheMQTTspBClient(similartowhatisdoneat your Project).
• In Communication Manager, insertenter the MQTTspB Topic/Address, Robot IpIP 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 (optional).
• Password:Password defined in MQTT Broker. This will be requested if the Broker needs this configuration (optional).
• Server Certificate: Path of the .pem file for the server. This is required if the Broker needs this configuration (optional)MQTT Broker uses a server-side certificate for authentication. The complete path of the .pem file on the client computer must be provided.
• x509Certificate:Path ofX509 Client Certificate. If using server-side only certificate this field does not need to be configured.This must be the complete path of X509 certificate in the client computer. Also, the certificate must be installed.
• CertificatePassword:PasswordcreatedwhenX509 Certificate wasexported(optional).
• NetworkSecurity: Thisfieldismandatoryif MQTT Broker worksusingcertificate,andmustbethe same that was configured in MQTT Broker (optional). The options are None and TLS.
• QoS:QualityofService(QoS)isanagreementbetweensenderandreceiverofamessageregarding the guarantees of delivering a message. textbfQoS 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 send 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 milisseconds milliseconds.

Communication Manager Tab

• Robot Name: Defines the name of the robot, thatwhich represents the main element in the Data Structure.
• MqttTopic:Topicintowhichthepayloadwillbepublished.Thesyntaxwillbe: <GroupId>/<NodeId>/<DeviceId>.

• RobotIp:IpAddressIP addressfortheRTDEconnection.
• Frequency:FrequencyofreadingReading frequency for the RTDE Protocol. Should be a value in the intervalrange of 125and 500Hz 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. ClicktheLoadlicensekey 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 keyLicense 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

Besides filling the In addition to manually entering configuration parameters manually at in the PolyScope Installation Tab, it is you can also possible to 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 makesureensure the file is loaded by the program, somethingscertain requirementsMUSTbeguaranteed met:

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

The file will be parsed every time the PolyScope is launched(aslongastheURCapisalready installed). You CAN NOT 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 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.

ItisimportanttoknowthatathevariablecustomizationwillbeappliedtothespecifiedBranchandall its children, unless they have their own customization.

ThisentrycanbecustomizedONLYthroughthe.xmlfile.

Robot Runtime DataModel

TheDataModelpublishedtotheMQTTBrokerispre-definedbasedonvariousUDT’sUDTs(User-Defined Types). Click here to downlaod 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 Kgin 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. bController Temp: TooltemperatureindegreesCelsius. RTDEParametertool temperature. cMain 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, thatdon’texistinRTDEcontext. :

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 speed: 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 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 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. EmergencyStopped: Emergencystopped.RTDEParameter:safetystatusbits.
5. TeachButtonPressed: Powerbuttonpressed.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: Thisrangeofthebooleanoutputregistersisreserved for FieldBus/PLC interface usage. RTDE Parameter: input bit registers0 to 31.

1. InputBit Registers 32 to 63: Thisrangeofthebooleanoutputregistersisreserved for FieldBus/PLC interface usage. RTDE Parameter: input bit registers32 registers 32 to 63.
2. Input Bit Register X:X:[64..127]-Theupperrangeofthebooleanoutputregisters 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. g 
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:

Stringvariablesthatdon’texistinRTDEcontext.

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