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.
The following PLUGIN keyword has been added to the FairCom EDGE ctsrvr.cfg file, which is located in the c-tree server/config folder:
The following directory has been added to FairCom EDGE under the server folder:
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.
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:
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",
"thingworxAppkey": "ThingWorx app key",
"thingworxCACertificate": "CA Certificate",
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”:
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:
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:
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:
You can navigate and visualize all the databases, tables and fields on this property:
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.
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:
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.
The table below shows the data type mapping between the c-tree fields in FairCom EDGE and ThingWorx properties:
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:
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.
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):