ThingWorx Edge C SDK > Getting Started
Getting Started
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 (see Building Applications 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 ThingWorx platform.
As of v.2.0.0, two examples of Edge Extensions are provided, simpleextlib and warehouseextlib, 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, see . 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, the SDK must use the same identifier as well. Without an Identifier, the RemoteThing is referenced by name. The Identifier may be used if a device has access to its serial number via firmware, for instance.
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 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 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 template based on this thing. Then use the 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:
Defining Properties
Defining Events
Define Property Callback Functions
Defining Service Callback Functions
4. If your application requires, set up the following:
Tasks—See Create Your Tasks (Optional).
Bind Event Handler—See Create a Bind Event Handler (Optional).
Synchronized State Handler—See Implementing a Synchronized State Handler
Event Handler for File Transfers—See Create a File Transfer Event Handler (Optional).
Event Handler for Tunneling—See Create a Tunnel Event Handler (Optional).
SSL/TLS for secure communications—See . Using SSL/TLS for Security for details.
5. Initialize the API Singleton.
This initialization function initializes the Subscribed Properties Manager automatically.
6. Register Properties and Services.
Register Events
7. Bind Your Entities (Things).
8. If your application requires it, initialize the following components:
File Manager — Refer to Initialize the File Manager (Optional).
Tunnel Manager — Refer to Initialize the Tunnel Manager (Optional).
9. Connect to the Server and Initiate Tasks.
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 Server-Initiated Interaction.
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 SDK Application-Initiated Interaction.
11. Build your application using CMake. Follow the instructions in . Building Applications 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.