Documentation

FairCom EDGE IoT Database

Previous Topic

Next Topic

Tutorial for the ThingWorx AlwaysOn Plug-in

This tutorial demonstrates the basics of installing and using the FairCom EDGE ThingWorx AlwaysOn Plug-in.

This plug-in built uses the ThingWorx AlwaysOn protocol (https://developer.thingworx.com/sdks).

FairCom EDGE requires the creation and configuration of a FairCom EDGE "thing" in ThingWorx. Refer to the ThingWorx website for more information about using ThingWorx.

You will need to install and start the FairCom EDGE server, as described in Download and Installation in the FairCom EDGE Developer's Guide.


conn_alwayson_edge

The following PLUGIN keyword has been added to the FairCom EDGE ctsrvr.cfg file, which is located in the c-tree server/config folder:

PLUGIN ctthingworx;./thingworx/libctthingworx.so

  • If you are using the ThingWorx AlwaysOn plug-in, be sure there is no semicolon (;) at the beginning of that line. The semicolon is present by default and should be removed.
  • The above example is for Linux. On Windows, the library is called ctthingworx.dll.

The following directory has been added to FairCom EDGE under the server folder:

thingworx

libctthingworx.so - plug-in dynamic library (Linux only)

ctThingWorx.dll - plug-in dynamic library (Windows only)

fccert.pem - self-signed certificate for SSL

ctreeEDGE_entities.xml - required platform entities for the plug-in

FairCom EDGE also adds a new configuration file to the server/config folder: ctthingworx.json. This file is used to configure the ThingWorx AlwaysOn plug-in.

Entity Setup

This guide assumes an existing ThingWorx platform is available.

ThingWorx entity requirements - The FairCom EDGE ThingWorx plug-in requires some entities that this step will make available in the ThingWorx platform:

  • Data shapes: ctEDGE, ctDatabase, ctTable, and ctField
  • Thing Template: CtreeEdgeTemplate
  • Thing creator: CtreeEdgeThing

These entities are available in ctreeEDGE_entities.xml file provided in the FairCom EDGE package (in the server/thingworx folder). Please import them into ThingWorx using the option From File and the type of Entity:

After importing, you should see the following entities in your ThingWorx platform:

FairCom EDGE Plug-in Configuration File

server/config/ctthingworx.json is a JSON setting file which is used to configure how FairCom EDGE communicates with ThingWorx. It has the following format:

{

"thingworxHost": "ThingWorx host",

"thingworxPort": 80,

"thingworxAppkey": "ThingWorx app key",

"thingworxSSLCertificate": "./thingworx/fccert.pem",

"thingworxCACertificate": "CA Certificate",

"thingworxCertType": 2,

"thingworxThings": [

{

"thingName": "ctEdgeThing2",

"thingCreator": "ctEdgeThing"

}

]

}

Where:

  • thingworxHost: <string> Server host name or IP address where the ThingWorx platform is running.
  • thingworxPort: <numeric> Server port where the ThingWorx platform is listening. This corresponds to the Tomcat “HTTP/1.1 Connector Port.”
  • thingworxAppkey: <string> Application key generated in the ThingWorx platform used for authentication.
    See ThingWorx Help Application Keys.
  • thingworxSSLCertificate: <string> SSL certificate file name.
  • thingworxCACertificate: <string> SSL certificate authority name.
  • thingworxCertType: <string> SSL certificate type.
  • thingworxThings: <array> An array of "things" in the platform to be created to map to FairCom EDGE.
    • thingName: <string> Name you want assigned to the new “thing” which will be created in the ThingWorx platform.
    • thingCreator: <string> Name of the existing thing creator in the ThingWorx platform. This will be used as a model to create the new “thing". This came from the ctreeEDGE_entities.xml file you imported into ThingWorx above.

Example File

{

"thingworxHost": "THINGWORX9000",

"thingworxPort": 80,

"thingworxAppkey": "66412e88-8495-4dd7-b409-7d94507e836e",

"thingworxSSLCertificate": "./thingworx/fccert.pem",

"thingworxThings": [

{

"thingName": "ctEdgeThing2",

"thingCreator": "CtreeEdgeThing"

}

]

}

Loading the FairCom EDGE Thing into ThingWorx

After saving your changes to ctsrvr.cfg and the ctthingworx.json file (discussed above), please start / restart the c-tree server to make your changes take effect.

When FairCom EDGE starts with the active plug-in set accordingly, it connects to the ThingWorx platform and creates a new "thing" with the <thingName> set in the ctthingworx.json file based on the existing <thingCreator>. If there is already a "thing" with this same name in ThingWorx, it tries to use it. If the template does not match, the plug-in initialization will fail. Check the FairCom EDGE server\data\CTSTATUS.FCS file, and the various ThingWorx log files (in the C:\ThingworxStorage\logs folder) for error messages.

This is what the new thing looks like if you use the default name “ctEdgeThing2”:

tw_new_thing

Note that when the FairCom EDGE server is not running, the following icon (indicated by the mouse pointer) will show that the "thing" is disconnected.

When the disconnect happens (for example, when the c-tree server is shut down), the following message may be presented briefly:

tw_thing_down

When the connection is established, the following icon may briefly appear to indicate the "thing" is connected:

While connected, the following message will be presented:

tw_thing_up

Note that, in certain situations, neither of these icons will be presented. This indicates a problem, and the log files should be consulted.

Loading FairCom EDGE Schema

When the FairCom EDGE server starts, just after connecting to the ThingWorx platform for the first time and creating the ctEdgeThing2, the plug-in loops through all the databases, tables, and fields in the c-tree server and populates them in a property in the “thing.”

Note that this schema copy only happens when the ctEdgeThing2 thing is actually created in ThingWorx (when the ctEdgeThing2 initially comes into existence). In other words, if the ctEdgeThing2 already exists in ThingWorx, this schema copy will not happen when the FairCom EDGE server starts. In this situation, the user can manually cause the schema copy to happen by executing the GetCTEdge service if desired. This process is described on the following page. The property that contains the copy of the FairCom EDGE schema is called ctEdge:

tw_ctEdge

You can navigate and visualize all the databases, tables and fields on this property:

tw_filedlist

If any schema change happens in FairCom EDGE after the schema has been loaded into the ThingWorx platform, it will not be automatically reloaded when the FairCom EDGE server launches. So, a service is provided in the “thing” to reload this information manually. Go to </> Services -> GetCTEdge -> <Execute button>:

When the “Execute Service” window appears, press the green “Execute” button in the lower right-hand corner to perform the copy.

This service copies the schema (the list of tables in c-tree and their fields / columns) from FairCom EDGE to ThingWorx. It is important to realize that this service does not copy any of the data from the tables (the tables’ rows). To copy table data, the columns of the tables must first be mapped to ThingWorx properties.

Mapping Properties

While navigating through the ctEdge property when getting into the field level, we can set how the field value from FairCom EDGE persistence should be mapped to a property in the current “thing” at the platform. Execute the following steps:

  1. Click the Edit button (green “pencil in a circle” icon, pictured below) for the ctEdge property and navigate to find the field to be mapped.
  2. Click the Edit button for the field record:

    tw_fieldrecord

  3. Put a check mark in the Sync checkbox. This tells the FairCom EDGE plug-in that ThingWorx should be notified whenever a new record is added to the mapped FairCom EDGE table.
  4. If you want to name the new property to be mapped in the platform, enter it in the PropertyName field. If you leave it empty, a new name will be automatically generated. Names should not start with numerical digits or contain periods.
  5. If you want to set a minimum interval to wait before new value changes are updated, you can specify it in the Interval field. The default value of 0 means that every value change on the persistence table in FairCom EDGE will be pushed to the platform. If that frequency of updates is too high for the platform, you can use this setting to limit the frequency of updates to the platform. For example, to update no more than once every 10 seconds, set this field to 10:

    tw_interval

  6. Click the Set button and Done in all the other windows.
  7. Click the Save button on the ctEdge edit window.
  8. Now run/execute the BindCTEdge service, to create the new properties and get them syncing with FairCom EDGE.
  9. Close the ctEdgeThing2 using the “X” button on the left, and then and re-open it. Note that the “minimize” button on the right is NOT adequate.
  10. Switch to the Properties and Alerts tab and the new Properties will be there.

With these steps you are able to set all the mapping between the desired field data persisted in FairCom EDGE and its “thing” in the ThingWorx platform.

Type Mapping

The table below shows the data type mapping between the c-tree fields in FairCom EDGE and ThingWorx properties:

c-tree type

ThingWorx type

CT_BOOL

TW_BOOLEAN

CT_CHAR

CT_CHARU

CT_INT2

CT_INT2U

CT_INT4

CT_INT4U

CT_INT8

CT_INT8U

TW_INTEGER

CT_SFLOAT

CT_DFLOAT

CT_EFLOAT

CT_SQLBCD

CT_MONEY

TW_NUMBER

CT_DATE

CT_TIME_MS

CT_TIME

CT_TIMES

CT_TIMES_MS

TW_DATETIME

CT_FSTRING

CT_FPSTRING

CT_F4STRING

CT_STRING

CT_PSTRING

CT_F2STRING

CT_ARRAY

CT_2STRING

CT_4STRING

CT_FUNICODE

CT_F2UNICODE

CT_UNICODE

CT_2UNICODE

TW_STRING

CT_JSON

TW_JSON

Connecting

To enable the mapping between the data persisted in FairCom EDGE and the “thing” in the platform, execute the service called BindCTEdge. Go to </> Services -> BindCTEdge -> <Execute button>:

This service loops through all the mapping set in the previous section and execute the following steps:

  1. Validate that the mapping property name is set, if it is not, populate it automatically with the following format: <database>_<table>_field.
  2. Validate that the mapping property exists in the “thing.” If it is missing, create it automatically.
  3. Start a “Record Update Callback” on the persisted table to process the insert of new records and update the property in the platform.

After these steps, no matter how the new data records are inserted in the persisted table, the last value is supposed to be populated automatically in the mapped property in the platform.

Note 1: ThingWorx may be slow refreshing existing "things" and after executing these steps new properties may not display. Close the "thing" and reopen it to see your newly-created properties.

Note 2: ThingWorx platform error messages are redirected to the FairCom EDGE database CTSTATUS.FCS log. We'll ignore several of these logged messages for now.

Disconnecting

To disable mapping between data persisted in FairCom EDGE and the “thing” in the platform, execute the service UnbindCTEdge. Go to </> Services -> UnbindCTEdge -> <Execute button> (you may need to scroll down to the bottom to see the UnbindCTEdge service):

TOCIndex