Configuration

ThingWorx configuration for FairCom Edge

Abstract

how to configure the connection between FairCom Edge and ThingWorx

Section	Description
Entity setup	The FairCom Edge ThingWorx connector requires some entities. This section describes how to load those entities into the ThingWorx platform.
FairCom Edge setup	This section provides a procedure for the FairCom Edge setup.
ThingWorx connector setup	The section provides a procedure for exporting a certificate from your browser and a detailed example and description of the configuration file.

Entity setup

This guide assumes an existing ThingWorx platform is available and you have the credentials necessary to log into that platform.

The FairCom Edge ThingWorx connector requires the following entities to be loaded into the ThingWorx platform:

Data shapes:
- FairComServer
- FairComDatabase
- FairComTable
- FairComField
Thing template (FairComTemplate)
Thing creator (FairComThing)

Setup

Follow this procedure to import the entities into ThingWorx:

Log into ThingWorx.
Open the Import window.
1. In the Import Option dropdown menu, select From File.
2. In the Import Type dropdown menu, select Entity.
3. Click Browse to specify the file.
4. Navigate to and open the ctreeEdge_entities.xml file that is provided in the FairCom Edge package in the server/thingworx folder.
5. Click Import.
When importing is complete, ensure that the entities pictured are in your ThingWorx platform.
Note
As the ctreeEDGE_entities.xml file can change from version to version of FairCom Edge, it is important to import the file that shipped with your copy of FairCom Edge, even if you have previously imported a different version of the file into ThingWorx.

FairCom Edge setup

Install the FairCom Edge server as described in Install.
Note
Do not start the FairCom Edge server yet.
Navigate to and open the FairCom Edge services.json file in the config folder.

Locate the "http8080" listener object near the top of the file and ensure the "enabled" property is set to true.

{
  "serviceName": "http8080",
  "description": "Port 8080 using insecure HTTP protocol…",
  "port": 8080,
  "protocol": "http",
  "enabled": true
},

Save any changes.
Locate the "thingworx" "otherService" object near the bottom of the file and set its "enabled" property to true.
Note
The "serviceLibrary" property will have different values on Linux and Mac platforms.
```
{
  "serviceName": "thingworx",
  "serviceLibrary": "./thingworx/ctthingworx.dll",
  "enabled": true
},
```
Save your changes to the services.json file.
Important
Do not start the FairCom Edge server yet.

ThingWorx connector setup

Important

Determine whether your ThingWorx server is configured to accept secure (https) or non-secure (http) connections by checking the URL used to connect to ThingWorx for either https:// (secured connection) or http:// (non-secure connection).

Exporting a certificate from your browser:

If you are using a secure connection (https://), download the root certificate from the site certificate for the ThingWorx platform you are connecting to. You can do this in the Chrome browser by following these steps:

Note

If you are using a non-secure connection (http), this procedure does not apply and can be skipped.

Using Chrome, navigate and log in to ThingWorx.
Click the lock icon () in the address/URL bar.
Select Connection is secure to show the connection details.
Select Certificate is valid to show the certificate viewer.
Select the Details tab.
Select the root certificate in Certificate Hierarchy.
Click Export.
Set the type to Base64-encoded ASCII, single certificate (.pem;.crt) in Save As.
Navigate to your FairCom Edge server/thingworx folder.
Enter a filename, specifying the .pem file extension — for example CACert.pem.
Click Save.

Configuration file

The FairCom Edge services.json file in the config folder is used to configure how FairCom Edge communicates with ThingWorx.

Example 1. File template

{
  "thingworxHost": "ThingWorx host",
  "thingworxPort": 80,
  "thingworxAppkey": "ThingWorx app key",
  "thingworxSSLCertificate": "./thingworx/fccert.pem",
  "thingworxCACertificate": "CA Certificate",
  "thingworxCertType": 2,
  "thingworxThings": [
    {
      "thingName": "FairComThing2",
      "thingCreator": "FairComThing"
    }
  ]
}

Table 1. Property summaries

Property

Description

Type

Limits

"thingworxHost"

contains the server hostname or IP address where the ThingWorx platform is running

string

"thingworxPort"

contains the server port where the ThingWorx platform is listening, corresponding to the Tomcat HTTP/1.1 Connector Port

integer

80 for non-secure connections

443 for secure connections

"thingworxAppkey"

contains an application key generated in the ThingWorx platform for authentication

Note

Generate a key in the platform and give its value to FairCom Edge.

string

Application Keys

"thingworxSSLCertificate"

contains the SSL certificate file name that is provided in the FairCom product distribution and is typically in the server/thingworx folder

string

"thingworxCACertificate"

contains the SSL certificate authority file name that is the root certificate file that was exported from your browser

string

"thingworxCertType"

contains the SSL certificate type

string

"thingworxThings"

contains an array of things that will be created in the ThingWorx platform where the values can be mapped to FairCom Edge table columns

Note

If you want to map FairCom Edge data to multiple ThingWorx things give this array one entry for each ThingWorx thing.

array

"thingName"

contains the name for the new ThingWorx platform thing

string

"thingCreator"

contains the name of the existing ThingWorx thing that will be used as a model to create the new thing

Note

This comes from the ctreeEDGE_entities.xml file you imported into ThingWorx.

string

Example 2. Example file

It is recommended that you add the "debug" property to the file and set it to true to cause FairCom Edge to log additional information to its data\CTSTATUS.FCS log file.

While this can clutter up the log file, it is helpful when debugging connection problems with ThingWorx. Later, once any connection problems are debugged, the "debug" property can be removed or set to false.

{
  "debug": true,
  "thingworxHost": "THINGWORX9000",
  "thingworxPort": 80,
  "thingworxAppkey": "66412e88-8495-4dd7-b409-7d94507e836e",
  "thingworxSSLCertificate": "./thingworx/fccert.pem",
  "thingworxCACertificate": "./thingworx/CACert.pem",
  "thingworxCertType": 2,
  "thingworxThings": [
    {
      "thingName": "FairComThing2",
      "thingCreator": "FairComThing"
    }
  ]
}