Installing and Navigating the Directories of the C SDK
Installation
To install the ThingWorx Edge C SDK, follow these steps:
1. The distribution bundle for ThingWorx Edge C SDK is available through the PTC Support site, Order or Download Software Updates page, at https://support.ptc.com/appserver/cs/software_update/swupdate.jsp. If you are not already logged in to the PTC Support site, you are prompted to log in before access to this page is granted.
2. On the Order or Download Software Updates page, click the link appropriate to your situation:
◦ Download Software by Sales Order Number — if you are downloading for the first time and have your Sales Order Number (SON).
◦ Order or Download Software Updates — if you have a support agreement with PTC that allows software downloads.
3. Either way, on the Customer Search page, enter your Customer Name and Customer Number and click Next.
4. If you chose to download by SON, enter your SON in the page that appears, and click Submit. Otherwise, continue to the next step.
5. On the PTC Software Download Step 2 page, select the product family, THINGWORX EDGE SDK, as shown here:
6. Click the plus sign to expand Release SDKs.
7. Expand the ThingWorx Edge SDK node to display the options for choosing a release.
8. Depending on whether you want a new or previous release, this step varies:
◦ For a new release, expand the Most Recent Version node.
◦ For previous releases, expand the Show all Other Available Versions node.
9. Depending on whether you want a new or previous release, this step varies:
◦ Under Most Recent Version, locate the distribution zip file, C-SDK-v-v-v-b, where v-v-v is the release number and b is the build number,
◦ Under Show all Other Available Versions, expand the Version nodes until you see the desired distribution zip file, C-SDK-v-v-v-b.
10. Click the Download now link, HTTPS. If you want to compare checksums, clickView SHA-256 checksum and select to copy the checksum to your computer's clipboard.
11. Select a location for extracting the distribution bundle, and unzip it.
12. To verify the installation, continue to the next section, which briefly describes the contents of the installation..
 | The distribution bundle does not provide the older OpenSSL libraries but does provide a template that you can use if you want to implement another version of OpenSSL. The file is called twTemplateSSL.h and is located in the ../src/tls subdirectory of the C SDK installation. |
Directories and Files
The following table describes the directories and files of the C SDK. Note that the notation ./ indicates the top-level directory, which is named for the release, c-sdk-v.v.v.b and <version> in the second-level directory replaces v.v.v.b.
This Directory | Contains | Refer to |
|---|---|---|
./c-sdk-<version> | The file, version.properties, which provides the major, minor, and revision numbers that comprise the SDK version. The file, CMakeLists.txt, which provides the options for building a C SDK application. Note that such a file is provided for each of the C SDK examples.The README_BUILDING.txt provides brief instructions on building the C SDK using CMake. This directory also contains the subdirectories, doc, examples, src, test, and tools. The rest of this table describes the contents of these main directories. | |
./c-sdk-<version>/doc | The PDF files for the Developer's Guide and the release notes for the current version of the SDK. Also contains the mainpage.md file that provides an overview of the contents of the src directory. | For older versions of the C SDK than 2.2.2, refer to the original ThingWorx Edge SDKs and WS EMS Help Center, |
./c-sdk-<version>/doc/html | All the files and the search subdirectory for the Doxygen documentation. | To view the Doxygen documentation in a browser, open any of the *.html files in the html directory. |
./c-sdk-<version>/examples | Subdirectories for the various examples: ExtUseExample, simpleextlib, SteamSensor, and warehouse_extlib. Each subdirectory contains the source files for the example. The SteamSensor example also provides an XML file that contains entities for the example. You must import this XML file into ThingWorx Platform (using ThingWorx Composer) before running the example. Each example provides the CMakeLists.txt file needed to build the example with CMake. | |
./c-sdk-<version>/lib | Contains the OpenSSL libraries for the current C SDK release. | Note that OpenSSL is prebuilt so that it does not need to be compiled, just linked. For other third-party libraries, refer to the ../src/forkedThirdParty and ../src/thirdParty subdirectory descriptions in the table of src directory content below. |
./c-sdk-<version>/src | This directory contains subdirectories that contain all of the source code (*.c and *.h files) for the C SDK. | |
./c-sdk-<version>/test | This directory contains subdirectories for the test suite for the C SDK. | |
./c-sdk-<version>/tools | This directory contains Python scripts for building OpenSSL (build_openssl.py) and the C SDK (cross-build-csdk). | Refer to the readme.md file in each subdirectory to learn how to use these tools. |
This Subdirectory | Contains | Refer to | ||
|---|---|---|---|---|
../src/api | The API source (*.c) and header (*.h) files. twApi.c, twApi.h. | |||
twConstants.h | Contains all of the constants for the C SDK. For v.2.2.5, the MAX_ENTITY_NAME_LENGTH has moved to the twConstants.h file, as MAX_ENTITY_NAME_LEN. The value is 256. Files that previously defined this value now contain a #include for twConstants.h. These files are: • twApi.c • twOfflineMsgStore.c • twInfoTable.c • twMessages.c. | |||
twDefinitions.h contains the enumerated message types, message codes (status, errors), as well as type definitions (characteristic, BaseType, entityType). | ||||
twErrors.h contains definitions for different types of errors, including websocket, messaging, primitive/infotable, api, tasker, logger, utils, system socket, file transfer, tunneling, and managed property. It also contains the #defines for the msgCodeEnum errors. | ||||
twExt.h and twMacros.h | Files for use with the Edge Extensions for the C SDK. The twMacros.h file provides a set of macros that simplify Thing, Shape, template, and Primitive declarations. Refer to Using Edge Extensions with the ThingWorx Edge C SDK for details about Edge Extensions. | |||
twPasswds.c and twPasswds.h | The header and implementation files for the password callback functions. Refer to the paragraph following the first example in the topic, Initializing the API Singleton for information about application key callbacks and to Password
Callback Functions (C SDK 2.2.0 and later) for information about using password callbacks. | |||
twProperties.h contains definition structures and metadata functions for creating properties. twProperties.c contains the implementations of functions for creating and deleting property definitions. | ||||
twServices.h contains service definition structures and metadata functions for services. twServices.c contains the implementations of functions for creating and deleting services. | ||||
twVersion.h contains the #define for the version of the C SDK. twVersion.h.template contains | ||||
../src/config | Two configuration files, twConfig.h and twDefaultSettings.h. As its name implies, the twDefaultSettings.h file contains the default settings for many of the C SDK, parameters, in case you decide to use default values and not include your own specific settings in your project. You can also change values here to use different default values for your projects. The twConfig.h file is provided should you need to override common settings provided in the CMakeList.txt file. You can also use it if you are using Windows Solution (sln) or gcc Makefiles (the use of sln and make files is deprecated). Use this file only if you are not using one of the provided files (twConfig.h and twDefaultSettings.h) to do per project configuration. Note that the settings in these files apply to ALL of your projects that use the SDK.
| |||
../src/fileTransfer | This directory contains the source and header files for the file transfer functionality of the C SDK, twFileManager.c, twFileManager.h, twFileTransferCallbacks.c, and twFileTransferCallbacks.h. | |||
../src/forkedThirdParty | libcfu and ntlm | These subdirectories contain the third-party libraries that have been modified to work with the C SDK. Read also the readme.txt. Refer to the row for the thirdParty subdirectory for information about the remaining third-party libraries. | ||
../src/messaging | The following source and header files: • twBaseTypes.c, twBaseTypes.h contain the definitions of the Base Types of the SDK. • twInfoTable.c, twInfoTable.h contain the definitions of functions related to creating an infotable with the SDK. • twMessages.c, twMessages.h • twMessaging.c, twMessaging.h | |||
../src/primitiveUtils | twPrimitiveUtils.c and twPrivitiveUtils.h | Provides a set of functions for rapidly declaring Thing Shapes and infotables, using a variable of arguments. | ||
../src/shapes | twShapes.c and twShapes.h | Supports EdgeThingShape and EdgeThingTemplates for the Edge Extensions of the C SDK. Refer to Using Edge Extensions with the ThingWorx Edge C SDK. | ||
../src/standardProps | twStandardPropx.c and twStandardProps.h | Provides a default property handler that stores all current property values in the heap. The header file defines the property change listener functions for C SDK Edge Extensions. Refer to Property Change Listeners. | ||
../src/stubs | This directory contains code for mocking out API calls during the unit testing process and is required to compile. However, it does not provide any new features or capabilities in the released product | |||
../src/subscribedProps | Source and header files (subscribedProps.c and subscribedProps.h) that contain the functionality to support subscribed properties. | |||
../src/thirdParty | Third-party libraries for the C SDK that have not been modified by PTC, including cJson, tomcrypt, wildcard, and zlib. | As of C SDK v.2.2.5, the third-party libraries that PTC modified (libcfu and ntlm) are statically linked and available in the ../src/forkedThirdParty directory, as described above. The remaining third-party libraries are in this subdirectory. The libraries compile with warning disabled. When building the C SDK, you should not notice any difference. There are no additional library files to copy. OpenSSL is in the <csdk>/lib subdirectory. | ||
../src/threadUtils | twThreadUtils.c and twThreadUtils.h | Provides simple thread management for ThingWorx C SDK functionality. Refer to Choosing
a Threading Model. | ||
../src/tls | The files needed to use SSL/TLS with the SDK. The file twTemplateSSL.h provides a template for implementing a custom version of OpenSSL. | |||
../src/tunneling | The source (twTunnelManager.c) and header (twTunnelManager.h) files for the Tunneling feature. | Refer to the section, Configuring Tunneling, in the topic, How to Configure Components of the C SDK. ThingWorx Remote Access Extension in the ThingWorx Platform Help Center | ||
../src/utils | The source and header files for utilities provided by the SDK: • cryptoWrapper.c, cryptoWrapper.h • list.c (for doubly-linked list utilities) • stringUtils.c, stringUtils.h • twDict.c, twDict.h • twHttpProxy.c, twHttpProxy.h • twList.h • twLogger.c, twLogger.h • twMap.c, twMap.h • twNtlm.c, twNtlm.h • twOfflineMsgStore.c, twOfflineMsgStore.h • twPath.c, twPath.h • twTasker.c, twTasker.h • twZipTar.c, twZipTar.h | |||
tw-c-sdk/src/websocket | The source (twWebsocket.c) and header (twWebsocket.h) files for the WebSocket Client (abstraction layer). |
The following table briefly describes the contents of the test subdirectory, which contains all the source code files, entity files, and CMakeList.txt files needed to build and run the tests.
This Subdirectory | Contains |
|---|---|
etc | Subdirectories and files to support the test applications, including XML files that contain entities used in the tests. The entities For the tests to run successfully, you must import the entities into your ThingWorx Platform. |
graphite-c-client | graphite-client.c and graphite-client.hl This test is a simple, pure C client for Graphite that enables you to send metrics to Graphite/Carbon using Graphite plain-text protocol. |
include | Header files to support the test utilities. |
integration | Integration tests for the C SDK that test different features, including file transfers, offline message storage, property writes, services, and more. |
integration_slow | BindingIntegrationTestsSlow.c, which tests multiple combinations of binding and connecting. OfflineMsgStoreIntegrationTestsSlow.c, which tests filling up the offline message store and flushing it, in different ways. |
lib | TestServices.c, TestUtilities.c, crossPlatformTestSupport.c, testmain.c, and twPrimitiveUtils.c |
performance | Performance tests that exercise binding, file transfer, ListForeach, property writes, and service execution. Also includes Kepware tests that represent high bandwidth throughput of properties (up to 10000 unique integer properties pushed up to a single thing in under one second). |
src | csdk_tests.c is the main executable for the test under Linux and Windows. |
unit | Subdirectories and files for unit tests of twApi, twFileManager, twOfflineMessageStore, and more. Also contains the CMakeLists.txt file that is needed to build the tests. |
unity | The Unity Project test framework for C from MIT. |
CMakeLists.txt | File required for building the test suite using CMake. |