ThingWorx Edge C SDK > Introducing the ThingWorx Edge C SDK
Introducing the ThingWorx Edge C SDK
This section provides an introduction to the ThingWorx Edge C SDK, explains its purpose, requirements for using it, and main features. It then explains how to install the SDK and provides a table that shows the directories and files in the installation. Finally, this section provides a Getting Started section, which contains an overview of the process for creating an application using this SDK. This process references later sections of this document where you can find more details.
About the 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 ThingWorx C SDK assumes the use of the C language as defined by the ANSI C89 specification (
The primary functions of the 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 running 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 Composer, 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 ThingWorx platform-side things are easily accessed through appropriate API calls: twApi_ReadProperty/twApi_WriteProperty, twAPI_InvokeService, and twApi_FireEvent, respectively.
The C SDK supports the following functionality that allows your machine, device, or application to work with ThingWorx platform:
Secure Connections—As of v.2.0.0,.the C SDK provides the OpenSSL library and defaults to rejecting self-signed certificates. It also defaults to building with these binaries. It also provides a template for you to use if you want to use another SSL/TLS implementation in your application. The C SDK supports client and server certificate validation. You can enable or disable SSL/TLS certificate validation.
Security for Passwords—As of v.2.2.0, the C SDK uses a callback function to retrieve an Application Key, digest, certificate password, or proxy user password, or a passphrase for a keystore. This change improves the security of these sensitive pieces of information. See Initializing the API Singleton for information on using the callback to retrieve an Application Key for authentication with ThingWorx platform.
Compression—As of v.2.1, 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, see 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 see ThingWorx Edge SDK Extensions for the C SDK.
Software Content Management (SCM) Edge Extension — As of v.2.1.3, the C SDK includes an Edge Extension that supports ThingWorx SCM capability to create and deploy a package that contains a script to be run on the edge device. Any scripting language is supported, as long as the edge device has the executable for that scripting language installed. For example, you could use Python, Javascript, or nodejs.
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 the 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.
Proxy settings — If your environment requires edge devices to communicate through a proxy server, you can set up your application to connect to 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. If FIPS mode is enabled, it prints FIPS Enabled.
As of release 2.2.1, the non-FIPS distribution bundles of the C SDK include OpenSSL 32– and 64–bit libraries, version 1.0.2q, which, on Windows platforms are based on the Visual Studio 2015 runtime library. The FIPS distribution bundles include 32–bit OpenSSL libraries, v.1.0.2l, which are based on the Visual Studio 2012 runtime library. In addition, the axTLS library is no longer included in any of the distribution bundles..