ThingWorx Model Definition and Composer > Industrial Connections > Industrial Connections Example
  
Industrial Connections Example
Using the Industrial Connections entity in ThingWorx, you can connect to Kepware’s KEPServerEX to model, configure, and bind tags that exist in KEPServerEX to things in the ThingWorx model.
* 
This example assumes ThingWorx 8.0 or later is installed and running.
Creating an Application Key and Thing in ThingWorx
To connect to the KEPServerEX, you must create an application key and a thing that uses the IndustrialGateway thing template.
1. Create an application key in ThingWorx. Copy the Key ID for later use.
2. Create a thing in ThingWorx. Note the Name of this thing, as you will use it later in KEPServerEX.
* 
In this example, the thing is named KEPServerEX.
3. In the Base Thing Template field, select IndustrialGateway.
4. Click Save.
Installing KEPServerEX
1. Install KEPServerEX (6.2 or higher).
2. In the Installer Language dialog box, select a language and click OK.
3. Click Next.
4. Accept the license agreement and click Next.
5. Accept or change the installation location and click Next.
6. Accept or change the data location and click Next.
7. Accept or disable installing a shortcut on the desktop for KEPServerEX and click Next.
8. Select a suite and click Next.
9. Click the icon to the left of Full Installation and select Entire feature will be installed on local hard drive.
10. Click Next.
11. Enable the features appropriate for your environment and click Next.
12. Set a strong administrator password (or skip at this time) and click Next.
13. Click Install.
14. Click Finish.
15. There should be a KEPServerEX icon on the desktop.
Configuring KEPServerEX and Connecting to ThingWorx
1. Run the KEPServerEX 6 Configuration from the desktop icon and the Configuration window opens.
2. Right-click Project and select Properties.
3. In the Property Editor, select ThingWorx.
4. Configure as follows (settings not listed here can stay as the default):
Set Enable to Yes.
Host: the IP or fully-qualified domain name for your ThingWorx instance.
Port: the port that ThingWorx responds on. For example, 80 or 443.
Resource: This can be kept as default.
Application key: the Key ID from the application key that you created previously.
Trust self-signed certificates: If your platform has a self-signed certificate, change to Yes. (Set to No for maximum security.)
Trust all certificates: disables or enables strict certificate checking and may be needed for some self-signed certificates. (Set to No for maximum security.)
Disable encryption: Only set to Yes if you are not using SSL encryption on your platform. (Set to No for maximum security.)
* 
Unencrypted communication is a security risk and should ONLY be enabled during small-scale testing or if the environment is well secured by other means at the perimeter.
Thing name: The name of the IndustrialGateway thing that you created in ThingWorx.
* 
The Thing Name must match the name of the IndustrialGateway thing exactly (case sensitive).
5. Click Apply. The KEPServerEX will attempt to connect to ThingWorx.
* 
During evaluation, it may be helpful to use the Simulator Driver with KEPServerEX for sample data and tags. See the Simulator Driver manual.
Binding Tags in KEPServerEX to Properties in ThingWorx
Now that KEPServerEX is connected to ThingWorx, you can locate the IndustrialGateway Thing that is connected to the KEPServerEX, and you can bind tags in KEPServerEX to properties in ThingWorx.
1. Open Composer.
2. Click Browse > Industrial Connections.
* 
Industrial Connections will not display if the KEPServerEX is not connected. If KEPServerEX is installed, but not connected, click Start Runtime Service from the KEPServerEX icon on your desktop toolbar.
3. With KEPServerEX running, the Industrial Connections Thing displays. If there is not a checkmark in the column with the database icon, the thing must be saved to fully persist it.
a. Click the entity name.
b. Click Save.
4. In the Industrial Connection header drop-down, click Discover. Click the plus sign (+) to expand channels and devices that exist in the KEPServerEX.
5. Clicking on an individual device lists the tags available under it. Put a check next to all the tags you want to add to a new asset and click the Bind to New Entity button.
6. Choose a thing template and click OK.
* 
A remote template type must be selected.
7. The new Thing creation screen displays. The configuration and binding information is configured for the new thing to automatically connect through KEPServerEX. Provide a Name for the thing.
8. Click Save.
* 
The IndustrialThingShape is implemented by the Thing.
9. In the Industrial Thing header drop-down, select Properties and Alerts. Click Refresh. Values will change based on current data from KEPServerEX.
10. Click any property in the Name column to view or edit any property.
* 
Infotable-type properties must have a Push Type of Always pushed.
* 
The following properties are specific to the industrial connections thing:
Tag Address: The address of the tag as it exists in KEPServerEX. The property name and the bound tag address do not need to be the same.
Industrial Data Type: The data type as it exists in KEPServerEX. This corresponds to the base type in ThingWorx.
Push Type: The default push type is Pushed based on value change. While the Pushed based on deadband is similar to Pushed based on value change, there is a subtle difference in the values that are pushed. For example, if the values from the device are 1,2,3, and 4 and the push type is Pushed based on value change with a Push Threshold of 2, then the value that will be pushed up from the edge is 1, but it won’t be pushed up again because the change is only from the last value has only changed by 1. If the push type is set to Pushed based on deadband in this same example, it will push the values of 1 and 3 because the change is between the last value that was pushed instead of the last value from the edge.
* 
The Pushed based on deadband push type is only available for KEPServerEX Industrial Connections.
11. To bind additional tags to an existing entity, click the Add button to access the New Property attributes. Assign a name and other desired properties, taking care to select Remotely bound under Binding. Click Add under Tag Address to select the additional tag(s) to bind to the selected entity.
* 
Alternately, choose the Dynamic tag option, enter a dynamic tag address, and select the Industrial Data Type before clicking Done.
Industrial Gateway Diagnostic Properties
There are several diagnostic properties on the IndustrialGateway that you can use to obtain status information on the KEPServerEX.
* 
All count properties are logged to a value stream.
ActiveTagCount: the number of tags bound to properties in the platform. The number of tags being actively provided by the KEPServerEX to all connected clients.
ClientCount:
The number of all OPC DA clients connected to KEPServerEX.
DateTime:
The current date and time adjusted for the local time zone.
DroppedUpdates:
The number of updates that have been dropped by KEPServerEX rather than being delivered to the platform.
* 
This value should not be used to verify connectivity as it may be this update that is dropped.
ExpiredFeatures: The names of the KEPServerEX features, such as drivers or plugins, that have expired and will no longer provide data until the server run time is stopped and restarted or the feature is licensed.
FullProjectName: The full name and location of the currently-running KEPServerEX project file.
Hostname: The hostname of the machine where KEPServerEX is running.
IndustrialThingCount: The number of remote things using this IndustrialGateway to provide data into the platform.
isConnected: The connection state of the KEPServerEX server.
lastConnected: The last good connection time of the KEPServerEX server.
LicensedFeatures: The names of the KEPServerEX features, such as drivers or plug-ins, that are licensed on this instance of KEPServerEX.
OpcClientNames: The names of the connected OPC DA clients, if they are provided.
ProductName: The name of the software using the Industrial Gateway thing template.
ProductVersion:
The version of the software using the Industrial Gateway thing template.
ProjectName:
The name of the project file in use by KEPServerEX.
ProjectTitle:
The title of the project file in use by KEPServerEX.
PropertyCount:
The number of properties associated with RemoteThings on the platform.
TimeLimitedFeatures:
The names of the KEPServerEX features, such as drivers or plug-ins, that are not licensed on this instance of KEPServerEX but are providing data.
TotalTagCount:
The number of tags assigned to all clients.
UpdatesPerSecond:
The average number of updates being pushed to ThingWorx from KEPServerEX.
Services
There are several services you can use to manage industrial connections.
Service
Description
BrowseItems
The inputs are path and filter. Filter is optional.
* 
Example path: Channel1.Device1.
Returns: The SourceType (for example, Word or Word Array) is the data type as defined in the KEPServerEX and correlates to the base type in ThingWorx.
This Service takes a filter as argument, allowing searches for specific tag names. The filter techniques that can be used in this filter field are:
* Wildcard - matches any set of characters
? Single Char Wildcard - matches any single character
[...] Inclusion character set - matches any single character included between brackets. Ranges of characters can be indicated by a dash: 'c-j'
[!...] Exclusion character set - matches any single character not included between brackets. Ranges of characters can be indicated by a dash: 'c-j', '
# Digit - matches any numeric character
BrowseGroups
The inputs are path and filter. If a path is not defined, all groups are returned.
GetIndustrialThings
Returns all things that are connected via the IndustrialGateway thing template. You can also view the Remote Things mashup in ThingWorx to view this information.
GetPropertySubscriptions
You can use this service (on the remote thing) to return Aspects (properties as defined by the KEPServerEX).
* 
Aspect example:
{ "industrialDataType": "Word", "tagAddress": "Channel2.Device1.Tag11", "scanRate": 1000 }
GetBoundItems
Input a number for maxItems. Returns all tags that are bound to the thing that the service is run from.
* 
Bound tag information can also be found in the Bound Tags area of the Industrial Gateway thing.
GetPropertyDiagnostics
Available on the remote things that is added when using the IndustrialThingShape. This service takes the local name of a property currently bound to the thing that the service is run on and returns the following information:
Description:
The description field on KEPServerEX.
Valid: Boolean. Is the property good on the KEPServerEX?
DriverFriendlyName: the name presented to users for the driver that is used to generate the tag.
Model: The model of device under the driver that is being used to generate the tag.
Error: Boolean. Is the device in error?
Name: The name of the address in KEPServerEX.
DriverPersistedName: The KEPServerEX name of the driver used to generate the tag.
Address: The physical address of the tag in KEPServerEX.
DataType: The industrial data type as KEPServerEX sees it.
ReadOnly: Boolean. If true, the tag is read-only.
CurrentValue: The value of the tag when the service was executed.
CurrentQuality: The quality of the tag when the service was executed.
CurrentTimestamp: The time the tag was read when the service was executed.
GetDiagnosticDigest
Available on the Industrial Gateway thing. This service can take in any tag address and returns the diagnostic information of that tag from KEPSeverEX. This is the only diagnostic service that can use either a static or dynamic address on the KEPServerEX instance to provide information, meaning that the tag does not need to be bound to a property in the platform for this service to return results. The definition of each of the returned fields are the same as for the GetPropertyDiagnostics service (see above).
Importing Things via a CSV File
You can use the CSV import extension to import things into ThingWorx. This extension includes an ImportRepository, ImportHelper, ImportMashup, and TestImport.csv sample file.
* 
This extension is available on the ThingWorx Marketplace.
1. Obtain and import the extension into ThingWorx.
2. Open the ImportMashup.
* 
Clicking the Import Format link displays the format of the file.
3. Click Choose File and navigate to the CSV file to import. The file is uploaded to the platform so that it can read the file.
4. Click Upload.
5. If necessary, click My CSV file has a header row.
6. Click Import.
7. In Composer, you should see all the things the were imported via the CSV file.