How to Configure Components of the C SDK
Once you have decided which components your application requires, you must define the components as explained in this section. This section assumes that you will use CMake to build your application.
Configure the desired components to include in a CMakeLists.txt file, and verify that the SDK supports your platform/OS. If not, refer to the section on building, How to Build an Edge Application with CMake.
The SDK examples directory provides example applications that demonstrate various capabilities of the SDK. Within each of those directories are a win32, osx, and a linux subdirectory, each with their own source code and CMakeLists.txt file. The section, Configuring Options for a CMake Build, includes a table with the options that you can set at the command line with CMake. It is recommended that you use one of these examples to gain an understanding of what source files and configuration settings must be included in your build environment.
To learn about the configuration settings for applications, open the following files in the src/config/ subdirectory of the C SDK installation:
• twConfig.h — This file provides a place for general settings for C SDK applications, including offline message store. Any settings in this file apply to ALL of your projects. To override the settings for specific applications, use a CMakeLists.txt file to change the default configuration. However, if you are not building with CMake, use this file to configure the SDK for your application.
• twDefaultSettings.h — This file contains configuration settings for the C SDK that will apply to all applications written using the C SDK. Some of the settings can be overwritten by calls made prior to initializing the API. The comments in this file provide specific information about the settings.
As of v.2.2.9 of the C SDK, the twConfig data structure has a setting, called enable_tls_hostname_validation. Setting this to TRUE enables TLS host-name validation. Setting it to FALSE disables host-name validation. The default value is TRUE. For more information, refer to the section, TLS
Host Name Validation, in the topic, Setting Up Secure Connections.
 |
Configuration affects the footprint and RAM usage of the SDK, and consequently, any application built using the SDK.
|
Editing the CMakeLists.txt file is not required. You can set options from the CMake command line. For example:
cmake =DMyOption=ON MyProjectFolder
OR
cmake -DUSE_OPENSSL=ON
|
|
The OpenSSL option above is provided as an example. You do not need to set it because this option defaults to ON
|
Continue to the following configuration tasks. Click the title of a section to display the content. Click the title again to hide the content:
Choosing a Threading Model
A threading model tells the C SDK which thread to use to service registered polled functions. The threading model can affect the performance of your client application. If your application performs multiple tasks, such as data acquisition and file transfers, it is strongly recommended that you choose the multi-threading model. The supported threading models are described in the following table:
Model | ENUM | Description |
|---|---|---|
Multi-threaded | TW_THREADING_MULTI=2 | Spins up a separate thread to service registered polled functions. With multi-threading, you can scale up the number of threads that execute a service request as high as your device may require. For new applications using this SDK, multi-threading is the recommended option. |
Tasker | TW_THREADING_TASKER=1 | Tells the C SDK to use the existing, built-in tasker functionality to service registered polled functions. Note that the tasker is limited to 5 threads maximum. |
Single | TW_THREADING_SINGLE=0 | Tells the C SDK to use the thread on which the twOnPolled function is called to service registered polled functions. This option is intended for systems that do not support multiple threads or do not handle multiple threads well. With single threading, an inbound service call can prevent hardware polling from happening. However, since everything is on a single thread, this threading model could prevent platform service calls or duty cycle checks from happening. This model is not recommended for file transfers. |
To set the threading model use the twOnPolled(char* entityName) function.
The next two sections explain how to configure the multi-threaded model and the tasker model.
Configuring Multi-Threaded Model
To tell the SDK to use the multi-threaded SDK model, set TW_THREADING_MULTI to 2. To pass control of polling of any registered polled functions to a given thread, call the twOnPolled function. This function does not exit until the application is terminated.
Configuring the Tasker
The built-in tasker is a simple round-robin execution engine that calls all registered functions at a rate defined when those functions are registered. If using a multitasking or multi-threaded environment you may want to disable the tasker and use the native environment. If you choose to disable the tasker, you must call twApi_TaskerFunction() and twMessageHandler_msgHandlerTask() on a regular basis (every 5 milliseconds or so). Comment out the #define statement for this setting if you are using your own threads to drive the API, as you do not want the tasker to run in parallel with another thread that runs the API.
To properly initialize the Tasker, you must define ENABLE_TASKER:
/*********************************/
/* Tasker Configuration */
/*********************************/
#define ENABLE_TASKER 1
/* Tasker Configuration */
/*********************************/
#define ENABLE_TASKER 1
The Windows-based operating systems have a tick resolution (15ms) that is higher than the tick resolutions requested by the C SDK (5ms). For information about achieving the best performance on a Windows-based operating system, refer to Running on a Windows-based Operating System
To execute all registered polled functions for any Thing Template or Thing Shape, call the twExtPerformPolledFunctions() function. This handler function can be called directly or by the tasker.
Configuring File Transfers
The C SDK has full support for all the remote directory/file browsing capabilities of ThingWorx platform as well as bidirectional file transfer. To use this functionality, define ENABLE_FILE_XFER. This module will add ~15KB of code space to your application, so severely constrained environments may want to omit this functionality.
/*********************************/
/* File Transfer Configuration */
/*********************************/
#define ENABLE_FILE_XFER 1
/* File Transfer Configuration */
/*********************************/
#define ENABLE_FILE_XFER 1
Before you try to transfer a file, you must start all your threads. The function twExt_Start(500, TW_THREADING_MULTI,5); starts all your threads and returns. Once it returns, call twMessageHandler_msgHandlerTask(now,NULL):. Then it is safe to do the file transfers.
The C SDK uses WebSocket compression (zlib) for all WebSocket communications, including file transfers, by default. In general, leaving compression turned on reduces bandwidth used by the edge application, but requires more memory and CPU usage. Choose whether to leave compression enabled, based on the capabilities of your devices and on the available bandwidth. If you need to disable compression, use the twApi_DisableWebSocketCompression() function. This function is in the twApi.c file, which is located in the ./src/api/directory of your C SDK installation. It is described in the twApi.h file, which is located in the ./src/api/ directory. To call the function, add it to your code after you initialize the API by calling twApi_Initialize() and where you configure the API. For example:
/* Configure API */...
tw_Api_SetSelfSignedOk();
twApi_DisableWebSocketCompression();
twApi_SetOfflineMsgStoreDir(offlineMsgStoreDir);
...
This example sets up an offline message store location and disables compression. When the messages that were stored while the device was offline are eventually transmitted, the messages use more memory and CPU. Disabling compression is useful if you have a limited bandwidth or want to keep bandwidth costs down.
For configuration recommendations for optimal performance of large file transfers, refer to Best Practices for Transferring Large Files.
 | This example uses a self-signed certificate. In general, use self-signed certificates ONLY while developing and testing an application. In production, use a highly secure connection. |
Configuring Tunneling
The C SDK has full support for application tunneling. Application tunnels allow for secure, firewall transparent tunneling of TCP client server applications such as VNC and SSH. To use this functionality, you must define ENABLE_TUNNELING. This module adds ~5KB of code space to your application, and upwards of 100KB RAM, depending on usage, so severely constrained environments may want to omit this functionality.
a/*********************************/
/* Tunneling Configuration */
/*If defined, the tunneling system will be enabled.
*/
#define ENABLE_TUNNELING 1
/* Tunneling Configuration */
/*If defined, the tunneling system will be enabled.
*/
#define ENABLE_TUNNELING 1
The Windows-based operating systems have a tick resolution (15ms) that is higher than the tick resolutions requested by the C SDK (5ms). For information about achieving the best performance for tunneling in a Windows-based operating system, refer to Running on a Windows-based Operating System.
Configuring Additional Settings
The C SDK has several settings that you can modify, based on the needs of your application. For example, your devices may require minimizing RAM usage, or you want to improve performance. You can find the defaults for these settings in the file src/config/twDefaultSettings.h. In most cases you do not need to change these settings. If you must change them, exercise caution when making the changes. With the exception of TW_MAX_TASKS, all settings can be modified at runtime by changing the appropriate setting in the global twcfg structure. The structure definition can be found in src/config/twDefaultSettings.h.
 | The default setting for DEFAULT_SOCKET_READ_TIMEOUT in twDefaultSettings.h is 0. This value is recommended for best performance when transferring large files. Refer to Best Practices for Transferring Large Files. |