Documentation

c-treeEDGE IoT Database

Previous Topic

Next Topic

ThingWorx AlwaysOn Connector

This tutorial demonstrates the basics of using the c-treeEDGE ThingWorx AlwaysOn connector.

c-treeEDGE provides a ThingWorx extension built using the AlwaysOn protocol. This approach links the application with ThingWorx Edge SDK (https://developer.thingworx.com/sdks) to directly push data into the platform.

If you can link your edge application with the ThingWorx Edge SDK, you can use any of the existing FairCom APIs to persist data with c-treeEDGE locally.

c-treeEDGE also provides a ThingWorx MQTT extension, as described in Installing and Configuring the c-treeEDGE MQTT ThingWorx Extension. That extension is useful if you are already using MQTT in your application and do not need the enhanced integration of the AlwaysOn protocol.

This section explains how to install c-treeEDGE on the ThingWorx platform. ThingWorx allows enterprise-scale applications to be modeled by dragging and dropping "things."

c-treeEDGE requires creation and configuration of a c-treeEDGE "thing" in ThingWorx. Please refer to the ThingWorx website and the c-treeEDGE Thing download in the ThingWorx Marketplace for more information.

You will need to install and start the c-treeEDGE MicroServer, as described in Download and Installation.


conn_alwayson_edge

The following PLUGIN keyword has been added to the ctsrvr.cfg file:

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 following directory has been added under the edgemicroserver folder:

thingworx

libctthingworx.so - plug-in dynamic library

ctthingworx.json - plug-in configuration

fccert.pem - self-signed certificate for SSL

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

Setup

This guide assumes an existing ThingWorx platform is available.

ThingWorx entity requirements - The c-treeEDGE ThingWorx plug-in requires some entities that are 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 provided in the package. Please import using option “From File” and type of “Entities”:

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

Plug-in Configuration File

ctthingworx.json is a JSON setting file in 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.
  • thingworxAppkey: <string> Application key generated in the ThingWorx platform used for authentication.
    See http://support.ptc.com/help/thingworx_hc/thingworx_8_hc/en/index.html#page/ThingWorx/Help/Security/ApplicationKeys/ApplicationKeys.html
  • 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 c-treeEDGE.
    • thingName: <string> Existing “thing” in the platform to be used as a model to create the new “thing".
    • thingCreator: <string> Name of thing creator.

Example

{

"thingworxHost": "THINGWORX9000",

"thingworxPort": 80,

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

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

"thingworxThings": [

{

"thingName": "ctEdgeThing2",

"thingCreator": "CtreeEdgeThing"

}

]

}

Loading the c-treeEDGE Thing

When c-treeEDGE starts with the active plug-in set accordingly, it connects to the ThingWorx platform and creates a new "thing" with the <Thing name> set in ctthingworx.json file based on the existing <Thing creator name>. If there is already a "thing" with this same name, it tries to use it. If the template does not match, the plug-in initialization will fail.

tw_new_thing

Note that when the c-treeEDGE is down, the following icon will show that the "thing" is disconnected. During disconnection, the following message will be presented:

tw_thing_down

When the c-treeEDGE is up, the following icon will show that the "thing" is connected. During the connection, the following message will be presented:

tw_thing_up

Loading c-treeEDGE Schema

When c-treeEDGE starts, just after connecting to the ThingWorx platform, the plug-in loops through all the databases, tables, and fields and populates them in a property in the “thing.” This property name is ctEdge:

tw_ctEdge

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

tw_filedlist

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

tw_reload

Mapping properties

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

  1. Click the Edit button 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. Check the Sync checkbox.
  4. If you want to select the name of 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.
  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 c-treeEDGE 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.

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

Type Mapping

The table below shows the data type mapping between the c-tree fields in c-treeEDGE 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_MONEY

CT_CURRENCY

CT_SFLOAT

CT_DFLOAT

CT_EFLOAT

CT_SQLBCD

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

In order to enable the mapping between the data persisted in c-treeEDGE and the “thing” in the platform, execute the server ConnectCTEdge. Go to </> Services -> ConnectCTEdge -> <Execute button>:

tw_connect

It 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 c-treeEDGE MicroServer CTSTATUS.FCS log. We'll ignore several of these logged messages for now.

Disconnecting

To disable mapping between data persisted in c-treeEDGE and the “thing” in the platform, execute the server DisconnectCTEdge. Go to </> Services -> DisconnectCTEdge -> <Execute button>:

tw_disconnect.png

TOCIndex