Gateway & Connectors Setup - Common Steps upcoming

This documentation is for an upcoming release of the Gateway and Connector and is for information only.

The process of creating a gateway / connector pair starts with logging into your ThinkIQ instance to configure a gateway and a connector, downloading an installer, and running a local program. The local program accesses the ThinkIQ server and uses your configuration information to create a pair of local objects: a Gateway and a Connector. These objects run locally on a Windows or Linux on-premise computer to enable connecting your local device with a ThinkIQ data ingestion server.

There are several different types of connectors. These instructions apply to every available type.

For information pertaining to a specific connector, see the documentation for that connector.

Installing the Connector - Prerequisites

Before installing a gateway / connector combination, check that your system is compatible:

• If your computer is running Microsoft Windows, does it match the following required hardware and software specifications?
  • x64 CPU architecture
  • Windows 10 or Windows 11
• If your computer is running Linux, does it match the following hardware and software specifications?
  • x64 CPU architecture
  • A Linux distribution compatible with .NET 8.0 (see list here: https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md)
• Is the machine using a modern browser: Edge, Chrome, Firefox, and others? The software will not run on Internet Explorer.
• Does the machine have appropriate outbound connectivity?
  • Can the machine browse to your instance of the ThinkIQ platform, e.g. https://yourcompany.thinkiq.net?
  • Can the machine browse to the Meta Server? 
• Do you have user credentials that allow you to add Gateways/Connectors? The default User Group for this is Configuration.
• Can the machine connect to the data source machine over a network i.e., can it connect remotely?
  • If it cannot the only choice is to install on the physical machine where the data source is running. However, sometimes you cannot install locally – on the source machine. For example, when you are running a PLC on a machine, you cannot install the connector on the same machine
• The ".NET Core Runtime" is required for installation. Download the link and install.
• The OPC Classic .Net API is required for OPC Classic connectors that communication locally over HDA. This includes OPC Classic, OSISoft PI and the Rockwell Historian. The package can be downloaded here.

  

Create the Gateway instance.

1. Browse to your ThinkIQ instance as a user in the Configuration user group.

2. In the Model Explorer tree on the Instances tab, use the Add Instance  (+) button on the base organization (indicated with a tooltip) of your model to add a Gateway. Presently, each connector must be installed under its own gateway. The Gateway is the connection between the on-premise computer and the ThinkIQ platform in the cloud.

 

 

Connecting a local machine to the ThinkIQ network requires both a gateway and a connector. The previous section covered the configuration of a new gateway. The next section looks at configuring a new connector.

Create the Connector Instance

1. In the Model Explorer, navigate to the Gateway under which the Connector will operate. (Usually the one you just created.)
2. Use the Add Instance (+) button to add a connector. The Connector is the connection between the on-premise computer and the data source.

 

 After the connector is created, Activation pending will show in the connector Overview tab. An Activation Code with its expiration date is displayed. You will use the Activation Code when you create the gateway/connector on your local computer. The ThinkIQ system uses the Activation Code to link your local computer to the configuration details that you provided on the ThinkIQ server. The code will expire after four hours. Copy your activation code and use the Download link to download an installer.

 

Local Gateway / Connector Setup on Microsoft® Windows®

The process of getting a gateway and connector set up on a local machine running Microsoft Windows starts with installing the ThinkIQ.Tools.msi package that was downloaded in the previous steps.

1. The installer begins by running compatibility tests and displaying the results.

The operating system and CPU architecture are shown on the first line, with the conclusion that these are Compatible.

The .NET 8.0 runtime is required and is included in the compatibility test. In this example, a complete installation is found and the conclusion is that the installed .NET runtime is Compatible.

If you see this message, you can skip ahead to the next section, titled "Installing the Gateway and Connector."

When a system does not have the .NET 8.0 runtime – or only a portion of the required runtime – a message like the following will appear:

If you see this message, click the Next button and the .NET 8.0 runtime will be installed on your system.

 

Installing the Gateway and Connector

 

1. The installation of the Gateway and Connector itself will start with a request to enter the Activation code that you received from the ThinkIQ server system. After entering the activation code, click 'Next'. (The Activation Code can also be found on the Connectors Overview page.)

   

Note: If the installer does not move past the activation code entry page there may be network security on the host computer/network blocking communication to the ThinkIQ platform and/or meta.iioto.org.

 

2. On the Destination Folders screen, accept the defaults or change the folder(s) if needed, then click Next. The installer will start copying files to the selected destinations. Note that the locations are in the Windows Program Files and Program Data folders.

 

The installation will continue with configuration steps and prompt for information that is different for each of the connector types.
Refer to the following for details:

• OPC UA Live Data 
• OPC Classic (HDA, DA) 
• OsiSoft PI Historian
• Wonderware\AVEVA Historian
• Rockwell Historian

 

________________________________________________________________________________________________________

Once the configuration completes, click OK to close the dialog

Refresh the Connector page. The connector should be updated as shown below. 

 

Has the Installation Succeeded?

To help determine if the installation was a success, and the gateway and connector are running properly, ThinkIQ provides two tools, both of which are located in this folder: C:\Program Files\ThinkIQ\Tools

• ThinkIQ.Connect.exe – allows tests on both the gateway and the connector.
• ThinkIQ.LogView.exe – allows all system logs to be viewed in one location.

ThinkIQ.Connect.exe  

When you start ThinkIQ connect, it appears in minimal mode with just information about the three services and the data root. Green indicators suggest that things are running properly. When any of these are yellow, there is a problem. When any are red, there is a fatal error. 

 

 

To check the status of the gateway / connector system, click on the Show More >> button. The result is shown here:

 

Click on the "Support" tab.

Notice the two buttons labeled Gateway Test and Connector Test. Click the Gateway Test button to verify that the link from your computer to the ThinkIQ servers are being made properly.

 

Click the Connector Test button to verify that the connection to your hardware device is running properly. Here is what the display looks like when both gateway and connector links have been established properly.

 

 

ThinkIQ.LogView.exe

Each of the five major system components writes to log files. The LogView application reads these logs and provides a single view into sequence of steps that have been performed.

 

Looking back in the Model Explorer, check the Overview tab on the connector. When you created the connector you saw the Activation Pending message along with the Activation Code and a Download button. After activation, you should see a Connector Activated message.

The second tab on the connector shows all available tags on the data source. If there are no tags listed, the connection may not have succeeded. (see Troubleshooting)

Once a connector has been installed, it will send meta data about itself to the ThinkIQ platform. This is why you see the tags listed in the Tags tab of the connector. It is not until you historize tags that timeseries data is sent to ThinkIQ data historian.

 

Mapping Tags

To receive time series data from a new connector, its tags must be properly linked to attributes in ThinkIQ system. Learn how to Map Tags to Data Sources.

___________________________________________________________________________________________

 

Windows Services

After installation there will be three services visible in the Window Services control panel: the ThinkIQ OPC UA North Service, the gateway, the ThinkIQ southbound - named for the connector type, for example, 'ThinkIQ OPC UA Connector', or connector, and the ThinkIQ System Monitor, which is responsible for showing that both the northbound and southbound services are running. To stop a connector, simply stop the southbound service. To stop the gateway, stop the northbound service. To stop everything, stop northbound service, southbound service, and the ThinkIQ monitor service.

 

South Service

 After activation, the South Service is set up on the computer where the connector is installed. The South Service Settings box displays the connector settings. These settings are editable by opening the file on the machine where the connector is installed in  C:\Program Files\ThinkIQ\SouthBridgeService\appsettings.json.

Settings that can be customized include the following:

DataStorer
     In the Params row
         DataRootDir    the location where tag data is stored when the system loses connectivity to the cloud.
        MaxFileCount   the maximum number of files that can be stored in the above location. As connectivity is restored and the data is once again flowing to the cloud, the files are deleted. The individual files are generally quite small, but the maximum number to store during store and forward is limited by disk drive size and can be effected by the number of tags being historized.

App Settings
   
    "AcquiredTagChunkSize": 300
    "AttributeChangeCheckTrigger": 0
    "UseOnPremiseAcquiredTagList": false
    "HistSeizedThresholdInSeconds": "1800"
    "UseAcquiredTagListAsWhiteList": false
    "TagChangeCheckIntervalInSeconds": 0
    "OnPremiseAcquiredTagListFilePath": "./OnPremiseAcquiredTagList.txt"
    "AttributeChangeCheckIntervalInSeconds" 0