How to install OEE application on Cumulocity IoT Edge

[yiz (Yishu Zhong)]

Authors: @yiz @kanishk.chaturvedi

Introduction

OEE application can be used for configurating and displaying the OEE calculation of production processes. That is beneficial for Cumulocity IoT Edge instances, which are connected to multiple machines and devices in the production environment. Edge administrators can complete the installation of OEE application on the Edge locally by themselves. The purpose of this article is to show how to install OEE application on a Cumulocity IoT Edge instance.

Pre-requisite

To be able to follow this instruction, the following requirements should be fulfilled:

• Completed Edge installation following the Edge guide
• Proper network configuration of Edge
• Enabled Microservice hosting feature of Edge
• Minimum system and OEE app hosting requirements: 6 CPU cores and 10 GB RAM
• Valid Apama license
• OEE installation ZIP-files (Please contact your Sales Rep to get these files)

Network configuration of Edge

Before enabling Microservice hosting feature, the network configuration should be set properly. The Kubernetes services reserved IP range 10.96.0.0/12 cannot be used as the IP address of Edge appliance. Besides, if the address range CIDR overlaps with the Edge appliance’s IP, it needs to be reset. Instructions for network settings can be found here.

Increase system Performance

The minimum system requirements for microservice hosting feature are 4 CPU cores and 8GB RAM. The OEE application requires an additional 2 CPU cores and 2 GB RAM. Therefore, the Edge appliance should have at lease 6 CPU cores and 10 GB RAM in total. If the system performance of the virtual machine needs to be increased, you can first shut down the hypervisor/virtual machine and change the system setting.

When the memory of the Edge appliance has been increased, the JVM must be increased afterwards as the following steps:

• Restart the Edge appliance and log in to it.
• Open the file /usr/share/cumulocity-core-karaf/bin/setenv.
• Edit the parameter JAVA_MAX_MEM as desired.
• Restart karaf service:
  [admin@iot-edge-server ~]$ sudo service cumulocity-core-karaf stop
  and
  [admin@iot-edge-server ~]$ service cumulocity-core-karaf start

The above custom setting will be overwritten after Edge updating, so it needs to be set again.

Installation

The OEE application consists of the following three components:

• The oee-bundle microservice – oee-bundle.zip
• The apama-oeeapp microservice – apama-oeeapp.zip
• The oee web application – oee.zip

All components need to be installed on the management tenant. If the zip file names include version information, remove the version, rename them according to the names above, like “oee-bundle.zip”.

Install Microservices

The Microservices can be installed via the Administration application of the management tenant on the edge or via the REST API. Two methods are described below separately.

If you have access to the Administration application, you can install the microservices via UI on the management tenant:

• Log in to the management tenant and switch to the Administration App
• Click Microservice in the Ecosystem menu in the navigator
• In the resulting dialog box, drop the zip file or browse for it on your file system
• You can subscribe to the microservice during the first installation. You can also subscribe to it after the installation in the properties tab of the microservice.

If you cannot access the UI, you can still install microservices via the REST API:

• Create the application entries for the two microservices. Microservice name in the request body should be the same as the zip file name, so either oee-bundle or apama-oeeapp. Send the following payloads to the endpoint POST application/applications in two separat requests:

  {
    “name”: “oee-bundle”,
    “key”: “oee-bundle-key”,
    “type”: “MICROSERVICE”
  }
  

  {
    “name”: “apama-oeeapp”,
    “key”: “apama-oeeapp-key”,
    “type”: “MICROSERVICE”
  }
  

Here is an example of the response, which is in JSON format with the application ID:

{
  “id”: “21”,
  “name”: “oee-bundle”,
  “key”: “oee-bundle-key”,
  “type”: “MICROSERVICE”
}

Keep the ID in mind. It will be used in the following steps.

• Upload the zip files severally to the platform with the ID you got in the last responses
  POST /application/applications/{id}/binaries
X-Cumulocity-Processing-Mode: TRANSIENT
Content-Type: multipart/form-data
Accept: application/json
Form: “file=@<name>.zip”

An example of the request and response in the Postman is shown in the following figure:

• Subscribe the management tenant to the microservices with the same ID as above
  POST /tenant/tenants/management/applications
{“application”: {“id”: “<id>”}}

Install Web Application

After installing the microservices, the OEE UI can be installed on the management tenant

• Click Applications in the Ecosystem menu in the navigator
• In the All applications page click Add application
• In the resulting dialog box, select Upload web application
• Drop the web application oee.zip or browse for it on your file system

Refresh the page after upload the web application you will see it the application switcher.

Upload Apama license

To make sure that apama-oeeapp microservice is working properly, a valid Apama license needs to be uploaded on the tenant. Via REST API, you can install or upload the Apama license:
POST /tenant/options

{
  “category”, “apama”,
  “key”: “credentials.license”,
  “value”: “<?xml version=\“1.0\” encoding=\“US-ASCII\”?><SoftwareAG_License>…</SoftwareAG_License>”
}

As in the example of payload, all the double quotes must be escaped using “\”, and line breaks must be removed. If the response code is 200, the request is successful. You can also use GET request to /tenant/options/apama/credentials.license to check the uploaded license. After uploading the Apama license, the apama-oeeapp microservice needs to be restarted by un- and re-subscribing to the apama-oeeapp microservice, so that the new license can be detected. To verify that the apama-oeeapp microservice is running with the license, click the Logs tab to check whether there is complete License Data in it or not.

Subscribe OEE Application on a subtenant

For the already created subtenants:

• Log in to the management tenant and click Subtenants in the Tenants menu in the navigator
• Click the tenant on which you need to subscribe to OEE application
• Subscribe the OEE web application and the Oee-bundle microservice under the Applications tab. Do not subscribe to the Apama-oeeapp.
• Log in the subtenant. If you already logged into the subtenant, you need to refresh the page to be able to see the OEE tab in the application switcher.
• Give the users Oeeconfigurator READ and ADMIN permissions to allow them to use OEE application.
  

For the new subtenant creation:

• Log in the management tenant and click Default subscriptions in the Ecosystem in the navigator
• Select OEE and Oee-bundle under the “Subscribed on tenant creation”.
• Save the change. Do not tick Apama-oeeapp here
• OEE application will be one of the default subscribed applications for the subsequent subtenants
• Give the users Oeeconfigurator READ and ADMIN permissions in the subtenant to allow them to use OEE application.
  

Summary

This article shows you the installation process of OEE app and the method to subscribe the app for subtenants. If you are interested in learning more about the OEE application, please contact our sales or schedule an online demo here.

After the successful installation of OEE application, the next step would be using OEE application to monitor the performance of production processes. More information about that can be found in the OEE application guide.

[Stefan_Witschel]

Very good article!

[Thomas_Winkler2 (Thomas Winkler)]

OEE 10.17 is now available in Software Download Center.