ThingWorx Edge C SDK
The ThingWorx Edge C SDK is a lightweight, but fully functional implementation of the ThingWorx AlwaysOn protocol. It is designed to minimize memory footprint while making it easy to integrate applications into the ThingWorx distributed computing environment of the Internet of Things (IoT). The goal of the C SDK is to make creating applications that use it simple, but to also give developers enough flexibility to create very sophisticated applications. For example, the SDK contains a simple “tasker” framework that you can use to call functions repeatedly at a set interval. You can use the tasker framework to drive not only the connectivity layer of your application, but also the functionality of your application. However, it is not required to use the tasker at all. The API is thread safe and can be used in a complex, multi-threaded environment as well. Other examples of this flexibility are highlighted in this document.
The following sections provide an overview of the purpose and features of the ThingWorx Edge C SDK. Click the title of a section to view its content. Click the title again to hide the content.
Purpose
The primary functions of the ThingWorx Edge C SDK are as follows:
• Establish and manage a secure AlwaysOn connection with an instance of ThingWorx Platform. This includes SSL/TLS negotiation, duty-cycle modulation, and connection maintenance such as re-establishing a connection after network connectivity is lost and restored.
• Enable easy programmatic interaction with the properties, services, and events that are exposed by entities on ThingWorx Platform.
• Implement a callback infrastructure that makes it easy to expose a set of properties and services to ThingWorx Platform. These properties and services can be surfaced from multiple entities. When a request is made from ThingWorx Platform for a registered property or service, a callback is made to a function that you supply during the registration process.
The C SDK uses callback functions to notify your application of requests for property reads and writes as well as requests to execute a service. The callback function signatures are defined in the twApi.h file. Your application can register properties and services (and their metadata) with the API. The metadata is used when browsing remote entities from ThingWorx platform, making it simple to import functionality created in your application as a thing or Thing Template into your application model.
The properties, services, and events for the ThingWorx Platform-side Things are easily accessed through appropriate API calls: twApi_ReadProperty/twApi_WriteProperty, twAPI_InvokeService, and twApi_FireEvent, respectively.
Features
The ThingWorx Edge C SDK supports the following functionality that allows your machine, device, or application to work with ThingWorx Platform:
• Secure Connections — The C SDK provides the OpenSSL library and defaults to rejecting self-signed certificates. It also defaults to building with the OpenSSL binaries. The C SDK supports client and server certificate validation. You can enable or disable SSL/TLS certificate validation. As of release 3.1.0, the C SDK upgraded to OpenSSL 3.1.2.
 | As of v.9.1.x of the ThingWorx Platform JDK 11 is supported. However, it does not fully support TLS 1.3 yet. |
• Compression — As of v.2.1.0, the C SDK supports WebSocket compression at the edge for all WebSocket communications, including file transfers. The zlib compression utility is used to compress and extract files from a ZIP archive. For the version of zlib, refer to the release notes for v.2.1 of the C SDK.
• Edge Extensions — Provide building blocks of functionality that enable you to create re-usable components. For example, a component that parses files. For more information refer to ThingWorx Edge SDK Extensions for the C SDK. The Steam Sensor example application provided with the C SDK is written using Edge Extensions and can be run from a command line. Refer to SteamSensor Example for more inforamtion.
| | A separate ThingWorx Software Content Management (SCM) Edge Extension is available for use with the C SDK. For details, refer to ThingWorx SCM Edge Extension for the ThingWorx Edge C SDK |
• File transfer — The file transfer functionality of the C SDK allows browsing of remote directories and files browsing on an instance of ThingWorx Platform, and permits bidirectional file transfer between an edge device and an instance of ThingWorx Platform.
• Data Shapes — You can create Data Shape definitions that model types of metadata for a remote machine/device.
• Tunneling — The tunneling functionality of the C SDK allows you to establish secure, firewall-transparent application tunnels for applications that use TCP, such as VNC and SSH. As of v.8.4.0 of the ThingWorx Platform, you can use the ThingWorx Remote Access Extension and Remote Access Client to access your edge devices remotely. Refer to ThingWorx Remote Access in the ThingWorx Platform Help Center for more information.
• Proxy settings — If your environment requires edge devices to communicate through a proxy server, you can set up your application to connect to a ThingWorx Platform through a proxy server.
• Offline message storage — Enabled by default, this features queues outgoing messages if the network is down or if the duty cycle is in the “off” state.
• Subscribed properties — Events can subscribe to changes in property values and in aspects of properties.
• Easy build environment — The C SDK supports building with CMake, enabling you to build an application for multiple environments.
• Version information — On startup, the C SDK prints the version number of the C SDK, the SSL/TLS library in use, and its version number.