Before You Begin
The best place to start is by examining the examples provided in the tw-c-sdk/examples directory. In addition to the *.c and *.h files, each example subdirectory contains the CMakeLists.txt file that you need to build the examples using CMake. Refer to How to Build an Edge Application with CMake for more information. The SteamSensor and ExtUseExample also contain an import subdirectory, in which you will find the XML file that you need to import into your ThingWorx Platform prior to running the example. The XML files set up everything needed to run and view the results of these examples on your ThingWorx Platform. For the SteamSensor example, this XML file adds a mashup that shows log files being downloaded from the client to the platform.
As of v.2.0.0, two examples of Edge Extensions are provided, simpleextlib and warehouse_extlib, and the ExtUseExample shows how to load these two example extensions. In addition, the SteamSensor example was rewritten to use the macros that were introduced with the Edge Extensions. For information about these examples, refer to Examples of Using Edge Extensions with the C SDK.
ThingWorx Configuration
The SDK requires that a RemoteThing be created in ThingWorx in order to communicate. Creating a RemoteThing is as simple as creating a Thing that is derived from one of the RemoteThing Thing Templates and optionally has an Identifier.
 |
If an Identifier is supplied for the Thing in ThingWorx Composer, the SDK must use the same Identifier to ensure successful communications with the ThingWorx Platform. If an Identifier is not supplied for the Thing, the RemoteThing is referenced by its ThingName. An example of a use case for Identifiers is a device that has access to its serial number via firmware.
|
If many Things are to be created with the same properties, services, and events, it is recommended that a Thing Template be derived from one of the supplied RemoteThing Thing Templates. It will be much easier to maintain the Things and will require less memory on ThingWorx Platform. One way to do this is to create a Thing, using a RemoteThing Thingg Template, and then browse the client application created with the SDK for its properties, services, and events. Once this work has been completed, create a custom Thing Template based on this Thing. Then to create additional Things, use the custom Thing Template instead of recreating all the properties, services, and events on each Thing.
Application Development
This section provides an overview of the main steps for developing an application using the C SDK.
1. Configure the components that your application will use. The components may include the following:
◦ Tasker (optional, Configuring the Tasker)
◦ File Transfer (Configuring File Transfers)
◦ Application Tunneling (Configuring Tunneling)
◦ Handling of Offline Messages (Handling Offline Messages)
◦ Any additional settings (Configuring Additional Settings)
2. If you need to minimize code footprint, follow the instructions in the section, Minimizing Code Footprint.
3. Define the properties, events, and services that you want to expose to the server and create the required callback functions. Callback functions can be created to handle individual properties and services, or a single property or service callback can be created to handle all of those types of entities.
Refer to the following sections:
4. If your application requires, set up the following:
◦ Tasks—Refer to Creating a Data Collection Task.
◦ Bind Event Handler—Refer to Create a Bind Event Handler (Optional).
◦ Synchronized State Handler—Refer to Implementing a Synchronized State Handler
◦ Event Handler for File Transfers—Refer to Create a File Transfer Event Handler (Optional).
◦ Event Handler for Tunneling—Refer to Create a Tunnel Event Handler (Optional).
◦ SSL/TLS for secure communications—Refer to .Using SSL/TLS for Security for details.
5. Initialize the API Singleton to use the tw_ApiInitialize() function. If you need to use a proxy server to access ThingWorx Platform, use the twApi_InitializeWithProxy() function. Refer to Initializing with Proxy Server Configuration for details.
 |
These functions initialize the Subscribed Properties Manager automatically.
|
7. Binding Your Entities (Things).
8. If your application requires them, initialize the following components:
◦ File Manager — Refer to Initializing the File Manager (Optional).
◦ Tunnel Manager — Refer to Initializing the Tunnel Manager (Optional).
10. Once your connection is alive and active, any requests made on the server for registered properties and services are automatically forwarded to your application, and the appropriate callback function is called. For information about server-initiated actions and callback functions, refer to the following topics:
Helper functions are available to push properties to the server, execute a service on another entity in the system, or trigger an event on the server. Refer to Initiating Interactions with a ThingWorx Platform.
11. Build your application using CMake. Follow the instructions in .How to Build an Edge Application with CMake
|
|
As of v.2.1, WebSocket compression is enabled by default for ALL WebSocket communications, including file transfers and pushing property values to ThingWorx Platform. If you need to disable compression, use the twApi_DisableWebSocketCompression() function. You can find information for the function in the files, twApi.h and twApi.c in the ../src/twApi/ subdirectory of your C SDK installation.
|