Oracle by Example brandingConfigure Oracle IoT PI System Gateway Software to Integrate with PI System

section 0Before You Begin

This 15-minute tutorial shows you how to install, configure, and run the Oracle IoT PI System Gateway software that integrates a PI System server with the Oracle Internet of Things (IoT) Production Monitoring Cloud Service application.

Background

Oracle IoT PI System Gateway software integrates with the OSIsoft PI Server to retrieve factory, floor, machine, and product data, and then sends and synchronizes this data to an instance of Oracle IoT Production Monitoring Cloud Service.

The following diagram illustrates the Oracle IoT PI System Gateway software, the PI System server, and the Oracle IoT Production Monitoring Cloud Service application.

The architecture diagram for integration of the Pi System server with Oracle IoT Production Monitoring Cloud Service
Description of the illustration integrator_diagram.png

In this tutorial, you use a demo PI System server, fuel controller sensor data, and Oracle IoT Production Monitoring Cloud Service application for the integration.

What Do You Need?

  • A Windows, Mac, or Linux laptop or a desktop with Java SE Runtime (JRE) 8
  • Access to any PI System server that has real-time sensor data
  • Access to an instance of Oracle Internet of Things Production Monitoring Cloud Service
  • Downloaded the Oracle IoT Gateway Software for PI System from the Oracle IoT Cloud Service Gateway Software Downloads page

section 1Create a Factory

Before you integrate, a factory should exist in your Oracle IoT Production Monitoring Cloud Service instance.

  1. Sign in to your instance of Oracle IoT Production Monitoring Cloud Service.
  2. The Map view of the Operation Center is displayed. Click Menu main menu icon.
  3. On the left navigation bar, click Design Center and then Factories.
  4. On the Factories page, click Add create new icon.
  5. On the Factory page, enter the following mandatory details:
    • ID: DemoFactory
    • Name: Demo factory
  6. Note the Factory ID for later use. Click Save and then click Close X.

section 2Install and Configure the Oracle IoT Cloud Gateway Software for PI System

  1. Extract the iotcs-pi-system-gateway-<version>.zip file.
  2. To configure the gateway software for your Oracle IoT Production Monitoring Cloud Service instance, in the /config/pi-gateway.properties file, enter values for the following fields as described in the file:
    • iotcs.host
    • iotcs.username
    • iotcs.password (not mandatory. If left empty, you will be prompted for a password on the console when the script runs. On a production instance, make sure that you do not save the password.)
    • pisystem.host
    • pisystem.port
    • pisystem.username
    • pisystem password (not mandatory. If left empty, you will be prompted for a password on the console when the script runs. On a production instance, make sure that you do not save the password. )
    • factory.id (more information in Section 1. The gateway software will create a factory if it does not exist.)
    • mapping.files (more information in Section 3)

section 3Create a Mapping File

For each machine type to be configured in the Oracle IoT Production Monitoring Cloud Service instance, you need to create a separate mapping/CSV file. In this section, you review a sample Fuel.csv that is used when the machine types do not exist in your Oracle IoT Production Monitoring Cloud Service instance.

  1. Click fuel.csv, save them in the iotcs-pi-system-gateway-<version>/config folder.
  2. Notice the following format used in Fuel.csv:
    • First column heading is the ID of the machine type, and second column heading is the name of the machine type, which is Fuel in the example. For Fuel.csv, the first column heading is left blank. If machine types already exist in your Oracle IoT Production Monitoring Cloud Service instance or imported from Oracle Manufacturing Cloud, then add the machine type ID field name in the first row first column of the mapping file.
    • Remaining column headings are the sensor attribute names attached to the machine type. Sinusoid and FuelGasFlow are examples.
    • First column from second row are the machine IDs that should be unique in the Oracle IoT Production Monitoring Cloud Service instance. Fuel1 is an example.
    • Second column from second row are the machine names. Fuel1 is an example.
    • Remaining columns from second row have tags of the sensor attributes, which are as follows, in the example: 
        F1DPW6Wlk0_Utku9vWTvxg45oAAQAAAAUElTUlYxXFNJTlVTT0lE, 
      F1AbEIRAQC7zjPUOfBqai218IAwF86n73045hGAxAANOhDHzg1C1SPoJqCFg8zXXXV
      kovvgUElTUlYxXE5VR1JFRU5cTlVHUkVFTlxUVUNTT05cRElTVElMTElORyBQUk9DRVNTXEVRVU
      QTUVOVFxCLTExN3xGVUVMIEdBUyBGTE9X
    • Tags are specially formatted strings of text that identify a unique PI System point or attribute.

    Note: If you use the OSIsoft demo PI System server at https://devdata.osisoft.com:443, then the CSV file maps the incoming sensor data to the Fuel1 machine in the Oracle IoT Production Monitoring Cloud Service instance.

  3. If you do not use the demo PI System server, refer to the sample CSV file and create a new mapping file for each machine type.
  4. Ensure that your new or updated CSV files are referenced in the pi-system-gateway.properties file accurately. Since each machine type has a CSV file, you can provide their names in the mapping.files field, separated by a comma. 
    #example
mapping.files= config/Fuel.csv, config/Fuel2.csv

section 4Integrate the PI System Server with the Oracle IoT Production Monitoring Cloud Service Application

  1. Ensure that you've completed Section 2 of this tutorial before you run the commands provided in this section. If your system is behind a firewall, ensure that you've set the values for HTTP_PROXY and HTTPS_PROXY in your system settings. 
    #example
export HTTP_PROXY="some.proxy.com:port"
    export HTTPS_PROXY="some.proxy.com:port"
    For Windows environment, create HTTP_PROXY and HTTPS_PROXY as environment variables, and set their values on your system.
  2. From the command line, go to the directory where you extracted iotcs-pi-system-gateway-<version>.zip and change to the ./bin directory. With the pi-system-gateway.properties configured accurately, run the IoT PI System Gateway to start data ingestion from the PI System server. 
    # for Windows
    pi-system-gateway.bat
    
# or 
# for Linux
./pi-system-gateway.sh

section 5Verify the Integration

Verify that the device messages are received by your Oracle IoT Production Monitoring Cloud Service instance from the machines managed by the PI System server.

  1. Click Menu main menu icon and then click Operation Center. The Map view appears.
  2. On the map, locate and zoom in to the area where DemoFactory is located.
  3. Click the Factory factory icon icon. On the floor plan of the factory, click the Fuel1 machine icon.
  4. The dashboard of the Fuel1 machine appears. On the navigation bar, click Machine Sensors sensor icon.
  5. On the sensor data graph, select Time Period as Last 1 Hour. Notice that the values of the Sinusoid and FuelGasFlow attributes are displayed on the graph.
    Description of messages.png follows
    Description of the illustration device_messages.png

more informationWant to Learn More?