ThingWorx Edge C SDK > Configuring Components of the C SDK
  
Configuring 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 sections on building ( Building Applications with CMake) and porting ( Porting to Another Platform), which describes the requirements and process for porting the SDK.
Provided within the SDK examples directory are 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, Building Applications with CMake includes a table that lists and briefly describes the options that you can set at the command line with CMake. It is HIGHLY RECOMMENDED that you use one of these examples to gain an understanding of what source files and configuration settings need to 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 will 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 explains all of the configuration settings for the C SDK. The comments in this file provide specific information about the settings.
* 
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
Continue to the following configuration tasks:
Configuring the Tasker
Configuring File Transfers
Configuring Tunneling
Configuring Additional Settings
Configuring the Tasker
The built-in tasker is a simple round-robin execution engine that will call 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). Un-define this setting if you are using your own threads to drive the API, as you do not want the tasker running in parallel with another thread running the API.
To properly initialize the Tasker, you must define ENABLE_TASKER:
/*********************************/
/* 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 in a Windows-based operating system, see Running on a Windows-based Operating System.
Back to top
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
As of v.2.1, 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 your 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. Its description is 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 are stored while the device is offline are eventually transmitted, the messages will use more memory and CPU. Disabling compression is useful if you have limited bandwidth or want to keep bandwidth costs down. .
* 
This example allows the use of 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 will add ~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
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, see 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 things such as minimizing RAM usage or improving performance. The defaults for these settings are found 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 of the 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 500 ms. If you are using SSL/TLS to connect to ThingWorx platform and a websocket read times out in the middle of reading a record, the SSL state is lost. As a result, the SDK tries to start reading the record header again, and the operation fails. To detect this situation, check the log for the SDK for the error, twTlsClient_Read: Timed out after X milliseconds, and consider increasing the value of the DEFAULT_SOCKET_READ_TIMEOUT. You can change the setting at runtime by modifying the value of twcfg.socket_read_timeout.