Page History

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.

• GraphicalUserInterface:ItisthemainURCapapplication.ItrunsinsidetheRobot(PolyScope), handles the communication parameters and can Start/Stop the client connections.
• RTDEClient: ClientimplementationforRTDEprotocol,runningonanindependentthread. 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:Client implementation for MQTTspB protocol, running on an independent thread. Receives data from the RTDE (through the main program) and publishes to the Broker.

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

The RTDE protocol generates messages every 8ms (125Hz).The MQTT client, however, will not publishatthesamerate. Itwillonlypublishnewdataifanyvariablehaditsvaluechangedsincethe last reading.

MQTT: A lightweight, publish-subscribe network protocol that transports messages between devices. TheSparkPlugBhasadditionalcontrolandstandardsallowing to knowaboutbirth,deathanda betterdataexchangecontrol.FormoreinformationontheSparkplugBspecification,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. Clickonittoopentheconfigurationwindowsintherightpanel.

Image RemovedImage Added

Therearethreetabs:MQTTBrokerInfo,CommunicationManagerandLicense.

• InMQTTBrokerInfo,inserttheinformationfortheMQTTspBClient(similartowhatisdoneat your Project).
• InCommunicationManager,inserttheMQTTspBTopic/Address,RobotIpAddress(forRTDE connection)andcommandbuttons.

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

Communication Manager Tab

• RobotName: Definesthenameoftherobot,thatrepresentsthemainelementinthe Data Structure.
• MqttTopic:Topicintowhichthepayloadwillbepublished.Thesyntaxwillbe: <GroupId>/<NodeId>/<DeviceId>.

• RobotIp:IpAddressfortheRTDEconnection.
• Frequency:FrequencyofreadingforRTDEProtocol.Shouldbeavalueintheintervalof125and 500Hz.

• AutoRun:Flagindicatingifclientshouldstartautomatically.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. ClicktheLoadlicensekeybuttonontheLicensetabtoloadthereceivedkey.

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

Besides filling the configuration parameters manually at the PolyScope Installation Tab, it is 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>

Tomakesurethefileisloadedbytheprogram,somethingsMUSTbeguaranteed:

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

Thefilewillbeparsedevery timethePolyScopeislaunched(aslongastheURCapisalready installed). You CAN NOT 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]isapathnameintreedatamodel;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.

ItisimportanttoknowthatathevariablecustomizationwillbeappliedtothespecifiedBranchandall its children, unless they have their own customization.

ThisentrycanbecustomizedONLYthroughthe.xmlfile.

Robot Runtime DataModel

TheDataModelpublishedtotheMQTTBrokerispre-definedbasedonvariousUDT’s(User-Defined Types). Click here to downlaod 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:PayloadmassKg.RTDEParameterpayload.
   2. PayloadCoG:PayloadCenterofGravity(CoGx,CoGy,CoGz)mm.RTDEParameter payload cog.
   3. PayloadInertia:Payloadinertiamatrixelements(Ixx,Iyy,Izz,Ixy,Ixz,Iyz]expressedinkg.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. SpeedSliderMask:0=do not changespeedsliderwiththisinput. 1=usespeedsliderfraction to set speed slider value. RTDE Parameter speed slider mask.
2. SpeedSliderFraction:Newspeedslidervalue.RTDEParameterspeedsliderfraction.
3. StandardDigitalOutput:Standarddigitaloutputs.RTDEParameterstandarddigitaloutput.
4. Configurable Digital Output:Configurabledigitaloutputs.RTDEParameterconfigurable 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.RTDEParameterinputintregisterX.
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.
12. RTDEParameterexternalforcetorque.

Status:

1. RobotMode:Robotmode.RTDEParameterrobotmode.
2. RobotPowerOn: Poweron.RTDEParameterrobotstatusbits.
3. SecurityStopped: Stoppedduetosafety.RTDEParametersafetystatusbits.
4. Emergencytopped: Emergencystopped.RTDEParametersafetystatusbits.
5. TeachButtonPressed: Powerbuttonpressed.RTDEParameterrobotstatusbits.
6. PowerButtonPressed: Powerbuttonpressed.RTDEParameterrobotstatusbits.
7. ProgramState:Programstate.RTDEParameterruntimestate.

IO:

1. ToolOutputMode:Thecurrentoutputmode.RTDEParametertooloutputmode.
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].RTDEParameteriocurrent.
5. AnalogIn0:Standardanaloginput0[mAorV].RTDEParameterstandardanaloginput0.
6. AnalogIn1:Standardanaloginput0[mAorV].RTDEParameterstandardanaloginput1.
7. AnalogOut1:Standardanalogoutput1[mAorV].RTDEParameterstandardanalogoutput1.
8. EuroMap67:
   1. Current:Euromap24Vcurrent[mA].RTDEParametereuromap6724Vcurrent.
   2. Voltage:Euromap24Vvoltage[V].RTDEParametereuromap6724Vvoltage.
   3. InputStatus:Euromap67inputbits.RTDEParametereuromap67inputbits.
   4. OutputStatus:Euromap67outputbits.RTDEParametereuromap67outputbits.
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 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. RTDEParametersafetymode.
2. SafetyStatus:Safetystatus. RTDEParametersafetystatus.
3. UnlockProtectiveStop:Notimplementedyet.
4. CloseSafetyPopup:Notimplementedyet.

Control:

1. PowerOn:Notimplementedyet.
2. PowerOff:Notimplementedyet.
3. BrakeRelease:Notimplementedyet. gAlarms:
4. 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...