kuka.deviceconnector installation guide€¦ · backtotoc kuka.deviceconnectorinstallationguide 3...

KUKA.DeviceConnector Installation Guide

Back to TOCKUKA.DeviceConnector Installation Guide

2 Issued: 8/9/2019 Version: 1.0

©2019 KUKAU.S. Holdings Company LLC. All rights reserved. Reproduction, modification, publication,distribution, or display of this document, in whole or in part, is prohibited except with the prior writtenpermission of KUKAU.S. Holdings Company LLC.

The information in this document may change without notice. KUKAU.S. Holdings Company LLCassumes no liability related to the use of the information in this document.

Disclaimer

Every reasonable effort has been made to ensure that the user experience provided in this document isaccurate. However, it may differ from the current KUKA Connect user experience due to continuousimprovements.



Contents

Target Group 4Conventions 4Licenses 5Intended Use 5Use 5Misuse 5

Safety 6Documentation Feedback 6Introduction 7Product Description 9Prerequisites 10Pre-deployment Planning 10Pre-deployment Checklist 11Contacting KUKA Customer Support 12Creating Static IP Address List 12Whitelisting 12Network Interface and Subnet 12Setting up an Intermediate Broker 12Deploying the Intermediate Broker 13

Installing and Deploying the KUKA.DeviceConnector 14Integrated KUKAOption Package (iKOP) 14KUKAOption Package (KOP) 14

KUKA.DeviceConnector Interface 19Uninstalling the KUKA.DeviceConnector 20Removing the Intermediate Broker 20Removing the KUKA.DeviceConnector from the Robot Controller 21

KUKA Connect in the Cloud 21KUKA Service 22Requesting Support 22



Target Group

This documentation is aimed at users with the following knowledge and skills:

General IT networking skills

Knowledge of the robot controller system

Conventions

This document uses the following conventions for notes, cautions, and warnings:

NoteA note provides a tip, emphasizes important information, or provides a reference to relatedinformation.

A caution statement alerts you to situations that could result in equipment damage or lossof data.

Awarning statement indicates conditions or situations that are potentially lethal orextremely hazardous to you.



Licenses

The KUKA license conditions and the license conditions of open-source software used can be found in thefollowing folders:

Under .\LICENSE on the data storagemedium with the installation files of the KUKA software.

Under D:\KUKA_OPT\DEVICECONNECTOR\LICENSE after installation on the robot controller.

In the license folder under the name of the option package in theOptions catalog after installationin WorkVisual.

Note: Further information about open-source licenses can be requested [email protected].

Intended Use

Use

The KUKA.DeviceConnector is a supported software-based connectivity solution for the KUKA Connectplatform. By leveraging the latest technology, the KUKA.DeviceConnector is able to pull data from yourKUKA robot controller, encrypt it, then send the data through a secure connection to the cloud. Fromthere, you can view the processed data by logging in to KUKA Connect.

This guide is intended to help you deploy the KUKA.DeviceConnector.

Misuse

Any use or application deviating from the intended use is deemed to bemisuse and is not allowed.

The KUKA.DeviceConnector may only be used with KUKA robots with KRC4 controllers and systemsoftware KSS 8.3.20 or later and KUKA Connect as described in this guide. Users may not edit any techpackage configuration files.

mailto:[email protected]



The following resources are required:

Stable internet and network connection of the robots and intermediate broker should be presentto prevent data loss.

Available bandwidth of the network should be capable of handling the amount of robot data beingtransmitted by the KUKA.DeviceConnector.

Robot controllers should not be overburdened and should have adequate available resources toeffectively run the KUKA.DeviceConnector tech package.

Using the tech package with an unstable internet connection will result in inconsistent datatransfer and/or data loss.

Safety

The safety information for the industrial robot can be found in the "Safety" chapter of the Operating andProgramming Instructions for System Integrators or the Operating and Programming Instructions forEnd Users.

The "Safety" chapter in the operating and programming instructions of the KUKA SystemSoftware (KSS)must be observed. Death to persons, severe injuries or considerabledamage to property may otherwise result.

Documentation Feedback

Your comments are valuable in helping us improve our technical documentation. Please send yourdocumentation suggestions or corrections to [email protected] and referenceDOCUMENTATION FEEDBACK in the Subject line of the email. Specify the document title, page number,section, and error/correction or suggestion.




Introduction

The KUKA.DeviceConnector is a software-based connectivity solution installed on the robot controller.While at your facility, data from the controller is encrypted using TLS v1.0 and sent to a customer-owneddevice running KUKA data transmission software (an "intermediate broker"). When leaving your facility,data is encrypted with TLS v1.2 between the intermediate broker and the KUKA Connect cloud. The datais decrypted and the relevant robot data is extracted so users can monitor their robots in KUKA Connect.

Note: The KUKA.DeviceConnector only supports KUKA robots with KRC4 controllers and systemsoftware KSS 8.3.20 or later.

Figure 1. The KUKA Connect platform diagram.



This guide will help you successfully plan for and deploy the necessary hardware by explaining:

KUKA Connect network diagrams

Pre-deployment planning

Pre-deployment checklist

Contacting KUKA Customer Support

Creating a Static IP address list

Whitelisting

Network interface and subnet

Setting up an intermediate broker

Deploying the intermediate broker

Installation and deployment procedures

Integrated KUKAOption Package

KUKAOption Package

Unistalling the KUKA.DeviceConnector

Removing the intermediate broker

Removing the KUKA.DeviceConnector from the robot controller

KUKA Connect in the cloud



Product Description

The KUKA.DeviceConnector is installed on the robot controller. At your facility, data from the controller isencrypted using TLS v1.0 and sent to an intermediate broker, where it is decrypted. When sent to thecloud, the data is encrypted again using TLS v1.2 and sent to KUKA Connect.

Note: An intermediate broker is defined as a customer-owned device running KUKA datatransmission software.

Figure 2. The KUKA Connect network diagram for the KUKA.DeviceConnector.



Prerequisites

The following hardware and software requirements must bemet before using theKUKA.DeviceConnector with KUKA Connect:

Table 1. The KUKA Connect hardware and software requirements.

Hardware Operating System

KRC4 controller with KUKA robot KSS 8.3.20 or later

Note: The KUKA.DeviceConnector does not support the Sunrise operating system.

Pre-deployment Planning

Pre-deployment planning must be completed before you install and deploy the KUKA.DeviceConnector.Executing planning beforehand ensures quick deployment once the software is installed.



Pre-deployment ChecklistUse this checklist and the sections that follow to review and complete your pre-deployment tasks beforeyou install the KUKA.DeviceConnector to ensure successful deployment.

Robot Connection Plan

How many robots are you connecting?

Do all robots have KUKA Operating system KSS 8.3.20 or later?

IP Address

Have you selected and documented a static LAN IP address for thehardware that is hosting the intermediate broker? It is necessary tohave the IP address documented for configuration during deployment.

Note: A second static LAN IP address is required if your robots are ona separate network.

Whitelisting

Do you have a firewall?

Have you whitelisted the host name and port 8883 for theKUKA.DeviceConnector?

Note: You need to whitelist port 8883 bidirectionally to establish ahandshake.

Network Interface and Subnet

Do you have two separate network interfaces: one for robots (LAN)and one for outbound internet (WAN)?

Are the robot and the intermediate broker on the same subnet?

How many robot subnets do you have?

What are the addresses for your robot subnets?

Intermediate Broker

Have you selected a hardware with a Linux-based server to host theintermediate broker? The KUKA.DeviceConnector only supports Linux-based servers and Windows 10 (if there is no virtual machineinstalled).

Installation Method

Have you determined the best installation method (either theKUKA Option Package or Integrated KUKA Option Package)?

Security

Does your facility utilize CPC and/or Non-Admin?



Contacting KUKA Customer Support

Network setup and connectivity requirements may vary by facility. KUKA Connect Customer Support canassist with setting up the KUKA.DeviceConnector. Contact KUKA Connect Customer Support [email protected].

Creating Static IP Address List

Select and document the static LAN for the server where the intermediate broker is located to enablecommunication to your robot networks.

One static IP address is required if your robots are on an Internet-enabled network. If this is not the case,two static IP addresses are required: one for the robot network and one for the Internet-enablednetwork.

Keep the IP address(es) handy during the deployment process.

Whitelisting

To ensure connectivity to the cloud, you may need to create a whitelist as part of pre-deploymentplanning.

To determine if you need to whitelist, answer these questions:

Do you have a firewall?

If you do have a firewall, do you typically whitelist items?

If a whitelist is needed, contact the KUKA Connect support team at [email protected] toreceive the correct items to whitelist.

Network Interface and Subnet

Does your network interface haveWAN and LAN connections?

If your network has separateWAN and LAN connections and you do not wish to connect your robotnetwork directly to the cloud then you will need to create an additional subnet for each network that youwould like to be separated. Provide the address for every subnet, along with the completed pre-deployment checklist to [email protected].

Setting up an Intermediate Broker

The KUKA.DeviceConnector uses an intermediate broker installed on an internal server or dedicatedcomputer to connect KUKA robots to the KUKA Connect cloud. The intermediate broker is a Dockerimage installed on hardware that has network connectivity as well as access to the robot network. You






are responsible for providing all hardware for the intermediate broker. KUKA.DeviceConnector's use ofopen source software keeps hardware and software requirements to a minimum.

The primary requirement is the ability to run Docker Community Edition (Docker CE). The Docker CErequirements can be accessed by referencing the Docker documentation.

Before you can deploy the intermediate broker, you must have Docker CE installed.

Deploying the Intermediate Broker

The intermediate broker must be installed on an internal server with access to the internet and the robotnetwork.

Note: You must have Docker CE installed prior to installing the intermediate broker.

To install the intermediate broker:

1. Identify an internal server to support the robot network and run Docker CE.2. Contact the KUKA Connect Customer Support team at [email protected] for a copy of

the intermediate broker Docker image. This item is available with your purchase of KUKA Connect.3. Place the Docker image into a directory that is easy to access on the internal server.4. Using a command line tool, navigate to the directory from step 3.5. Enter the following in the command line, replacing /path/to/broker.tar with your file path

and the name of the file you received from KUKA.

docker load < /path/to/broker.tar

After the command runs, the console will display a Loaded image output:

Loaded image: <IMAGE_NAME>

Note: The image's file name in the Loaded image output may not match your original input. Ifthis is the case, make sure to enter the Loaded image output file name in step 6.

6. After the image is loaded, enter the following in the command line. Replace <IMAGE_NAME>withthe file name from the Loaded image output.

$ docker run -p 8883:8883 --log-opt max-size=5m <IMAGE_NAME>

Editing any part of the installation files will impact the performance of the intermediatebroker. KUKA takes no responsibility for undesired behavior resulting from unauthorizedmodifications of the tech package or intermediate broker configuration files.

https://docs.docker.com/install/#supported-platforms

https://docs.docker.com/install/#supported-platforms




Figure 3. Command line output example when the intermediate broker has successfully connected tothe KUKA Connect cloud.

Note: For customers in China, the address will display as mqtt.connect.kuka-robotics.cn:8883.

Installing and Deploying the KUKA.DeviceConnector

After completing the pre-deployment tasks, download and install the KUKA.DeviceConnector on therobot controller. There are two different installation methods:

1. KUKA Option Package (KOP)2. Integrated KUKAOption Package (iKOP)

Note: KUKA.DeviceConnector supports KUKA robots with KRC4 controllers with system software KSS8.3.20 or later. KUKA.DeviceConnector does not support the Sunrise operating system.

It is recommended that all relevant controller data is archived before installing theKUKA.DeviceConnector.

Integrated KUKA Option Package (iKOP)

The iKOP installation uses theWorkVisual software to install the KUKA.DeviceConnector tech package onyour controller. Follow your organization's WorkVisual tech package installation procedure or referencetheWorkVisual documentation in KUKA Xpert for more information.

IfWorkVisual is not available, install the KUKA.DeviceConnector using the KOP.

KUKA Option Package (KOP)

To install the KUKA.DeviceConnector using the KOP:

https://xpert.kuka.com/



1. Extract the .zip file that was downloaded as a part of your KUKA Connect purchase.2. Copy the .zip file to a flash drive and unzip the contents.

Note: Do not unzip the files using a Mac computer as this will cause them to not work asintended.

3. Connect the flash drive to the SmartPAD.4. Log in to SmartHMI as Expert or Admin.5. Select the Robot icon in upper left corner of the SmartHMI screen.6. Select Start-up > Additional software.

Figure 4. Installing KUKA.DeviceConnector on SmartHMI.

7. Select New software in the lower left corner of the SmartHMI screen. A list of software availablefor download will display.



Figure 5. Selecting the KUKA.DeviceConnector software for installation in SmartHMI.

8. Select KUKA.DeviceConnector. If the desired software folder is not displayed, select Refresh. Ifthe correct folder now displays, skip to step 11.

9. If the download list still does not contain the KUKA.DeviceConnector folder, select Configure toconfigure the file path location.

Figure 6. Configuring the file path to the KUKA.DeviceConnector.

10. Select the correct file path location from the displayed list and select Save. If the correct file path



is not displayed, select an empty cell and then Path Selection. The available file path locationsare displayed.

11. Select the file path location for the KUKA.DeviceConnector folder and select Save. The windowcloses. If the KUKA.DeviceConnector folder does not appear in the list, select Refresh or repeatsteps 7 and 8.

Figure 7. Selecting a file path in the KUKA.DeviceConnector.

12. Highlight the KUKA.DeviceConnector folder and select Install.13. Review and accept the security prompt and the license agreement.14. To complete installation, restart the controller by selecting Restart in the lower right corner of

the SmartHMI screen.15. Access the KUKA.DeviceConnector by selecting the robot icon in the upper left corner of the

controller.16. Select Diagnosis >DeviceConnector.



Figure 8. The IP address and port information in the Configuration Tab of theKUKA.DeviceConnector.

17. Select the Configuration tab.18. Enter the IP address and port information for the intermediate broker hardware.19. Select Apply.20. Remove the flash drive from the SmartPAD.21. The KUKA.DeviceConnector will begin running automatically.



KUKA.DeviceConnector Interface

Figure 9 shows the essential parts of the KUKA.DeviceConnector interface viewed on SmartHMI afterinstallation is complete.

Figure 9. Themain screen for the KUKA.DeviceConnector interface.

Table 2. Names and definitions of essential parts of the KUKA.DeviceConnector interface onSmartHMI labeled in Figure 9.

No. Description

1 Controls to start and stop the client

2Connection status display (disconnected, initializing,connecting, sending)

3 General connection information

4 Current tab with connection state information

5 Configuration tab

Note: All items in Table 2 are only visible after installing the software on the SmartHMI.



Figure 10. The Configuration tab of the KUKA.DeviceConnector interface.

Table 3. Names and definitions of essential parts of the KUKA.DeviceConnector interface onSmartHMI labeled in Figure 10.

No. Description

1 Configure IP address of the intermediate broker

2 Port is 8883

Uninstalling the KUKA.DeviceConnector

To uninstall the KUKA.DeviceConnector, remove the intermediate broker Docker image and uninstall theKUKA.DeviceConnector from the robot controller.

It is recommended that all relevant controller data is archived before uninstalling theKUKA.DeviceConnector.

Removing the Intermediate Broker

To stop running the intermediate broker, restart the server on which it is hosted or follow these stepsfrom the command line:



1. Enter: docker container list2. Identify the intermediate broker docker container file from the displayed list.3. Enter: docker container kill followed by the name of the intermediate broker container file.

Removing the KUKA.DeviceConnector from the Robot Controller

If you installed the KUKA.DeviceConnector using WorkVisual then follow your organization’s procedurefor uninstalling tech packages or reference theWorkVisual documentation in KUKA Xpert.

If you do not have access to WorkVisual then uninstall the KUKA.DeviceConnector directly from thecontroller by following these steps:

1. Login to the controller as Expert.2. Select the Robot icon.3. Select Additional Software.4. Select KUKA.DeviceConnector.5. Select Uninstall.6. Restart the controller.

KUKA Connect in the Cloud

Your company’s Organizational Administrator ("Org admin") for KUKA Connect will receive a separateemail with instructions for signing in to KUKA Connect to begin configuring the product for yourcompany’s users.

To get started with KUKA Connect, review the Getting Started and Administrative pages in the KUKAConnect Help Center. You will find information on setting up users, robots, and available features.

https://connect.kuka.com/

https://connect.kuka.com/HelpCenter/Getting_Started.html

https://connect.kuka.com/en/HelpCenter/Admin_Setup.html

https://connect.kuka.com/en/HelpCenter/Home.html

https://connect.kuka.com/en/HelpCenter/Home.html



KUKA Service

Requesting Support

This documentation provides information on operation and operator control, and provides assistancewith troubleshooting. For further assistance, please contact your local KUKA subsidiary.

The following information is required for processing a support request:

Description of the problem, including information about the duration and frequency of the fault

As comprehensive information as possible about the hardware and software components of theoverall system

Diagnostic package KRCDiagFor versions of KUKA System Software older than V8: Archive of the software (KRCDiag is notavailable here)

The following list gives an indication of the information which is relevant in many cases:

Model and serial number of the kinematic system, e.g., themanipulator

Model and serial number of the controller

Model and serial number of the energy supply system

Designation and version of the system software

Designations and versions of other software components or modifications

Application used

External axes used

kuka.deviceconnector installation guide€¦ · backtotoc kuka.deviceconnectorinstallationguide 3...

Documents