Gateway & Connectors Setup - Common Steps

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.

Connector Install and Configuration

Double click on the ThinkIQ.Gateway.msi package downloaded above.

1. If the ".NET Core Runtime" is not installed, the prompt below will be shown. In this case, cancel the installation, download, run, and install the dependencies sited at the top of this article.

2. After installing the .Net Core runtime,restart Connector installation. With ".NET Core Runtime" installed, the prompt to enter the activation code will be displayed. The Activation Code can also be found on the Connectors 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.

3. 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?

There are a few ways to check if your connector installation has succeeded.

1. The first item to check is 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.
2. 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