ThingWorx Edge SDK Extensions for the C SDK
ThingWorx Edge Extensions provide building blocks for the C SDK that allow you to create reusable components for application development. These components are intended to simplify the complex tasks required to interface with the hardware used for data acquisition and control in IoT environments. These blocks of modular functionality can be assembled in different combinations, based on the needs of your IoT environment, into a single Thing that represents your device in ThingWorx. An example might be a Raspberry PI that reports the status of a sensor and also collects data from a custom peripheral that writes to a file from a daemon. By combining an EdgeThingShape for PI GPIO access with an EdgeThingShape for file parsing, you can synthesize a new Thing that delivers all collected data back to ThingWorx without having to write new code.
The Edge Extensions provide the convenience of structures that are similar to ThingWorx shapes and templates, without compromising the lightweight, low-footprint executables of C-based applications. The Edge Extensions framework is an optional wrapper around the core ThingWorx Edge C SDK code base and does not change any underlying API. Note that you can continue to use the C SDK without using the Edge Extensions.
The next section explains the terminology for Edge Extensions. For information on constructing an instance of an Edge Thing in C, refer to Constructing an Instance of an Edge Thing in C.
Terminology for Edge Extensions
The C SDK allows the construction of Things that can be bound to the ThingWorx Platform and appear as objects. To construct such Things, the API is used to map memory locations in the remote process to properties on the platform. The API is also used to map C functions in your application to services on the platform. Without Edge Extensions, you would use a series of API commands. The Edge Extensions put these API commands into a C function that can be called to create properties, services, and events on demand, when a Thing name is passed to the function. This C function is the definition of an EdgeThingShape.
Here are important definitions that you need to understand when working with Edge Extensions. Note that these terms are defined in the context of the ThingWorx Edge C SDK:
• An EdgeThingShape is a C function that, when passed a thingName as a parameter, declares a series of properties, services, and events, using the ThingWorx C SDK. Multiple EdgeThingShape functions can be called in a series to create a Thing that can then be bound and used by the platform.
• An EdgeThingTemplate is a special case of an EdgeThingShape. Like an EdgeThingShape, an EdgeThingTemplate is a C function that, when passed a Thing name as a parameter, declares a series of properties, services, and events, using the ThingWorx C SDK. This definition is the same as an EdgeThingShape, except that a Thing can be built from only one EdgeThingTemplate. However, an EdgeThingTemplate function can call the C function for another EdgeThingTemplate from within it to provide inherited functionality.
• In the context of the C SDK, an EdgeThing is the set of property mappings, service mappings, and events created by calling one EdgeThingTemplate function and any number of EdgeThingShape functions.
The following diagram shows an example of an Edge application that has an EdgeThing composed of one template and two shapes:
Constructing an Instance of an EdgeThing in C
To construct in C an instance of the EdgeThing shown in the preceding diagram, each class shown in the diagram becomes a function:
void constructGenericEdgeThingTemplate(char* thingName){
// Perform service and property declarations here
};
void constructMyEdgeThingTemplate(char* thingName){
constructGenericEdgeThingTemplate(thingName);
// Perform service and property declarations here
};
void constructEdgeThingShape1(char* thingName){
// Perform service and property declarations here
};
void constructEdgeThingShape2(char* thingName){
// Perform service and property declarations here
};
void constructEdgeThing(char* thingName){
constructMyEdgeThingTemplate(thingName);
constructEdgeThingShape1(thingName);
constructEdgeThingShape2(thingName);
}
You can use the function, constructEdgeThing(“MyNewThing”) to create as many EdgeThing instances as required by simply giving each instance a new name. By allowing the dynamic loading of EdgeThingShape and EdgeThingTemplate construction functions as collections from shared libraries, the C SDK provides a way to publish reusable code components. These components can be mixed and matched by other developers to create new EdgeThings at runtime.