C SDK Tutorial Part 2

[#1]

• Step 3: Run Sample Code
• Step 4: ExampleClient Connection

 

Step 3: Run Sample Code

The C code in the sample download is configured to run and connect to the Entities provided in the ThingWorxEntitiesExport.xml file. Make note of the IP address of your ThingWorx Composer instance. The top level of the exported zip file will be referred to as [C SDK HOME DIR].

1. Navigate to the [C SDK HOME DIR]/examples/ExampleClient/src directory.

2. Open the main.c source file.
   
   

   Operating System          Command

   Linux/Ubuntu	gedit main.c OR vi main.c
   Mac	open –e main.c
   Windows	start main.c

3. Modify the Server Details section at the top with the IP address for your ThingWorx Platform instance and the Application Key you would like to use. Change the TW_HOST definition accordingly.
   
   NOTE: By default, TW_APP_KEY has been set to the Application Key from the admin_key in the import step completed earlier. Using the Application Key for the default Administrator is not recommended. If administrative access is absolutely necessary, create a user and place the user as a member of the Admins security group.

   /* Server Details */
   #define TW_HOST "127.0.0.1"
   #define TW_APP_KEY "ce22e9e4-2834-419c-9656-e98f9f844c784c"

4. If you are working on a port other than 80, you will need to update the conditional statement within the main.c source file. Search for and edit the first line within the main function. Based on your settings, set the int16_t port to the ThingWorx platform port.
5. Click Save and close the file.

6. Create a directory to build in, for this example call it bin.
   
   

   Operating System           Command

   Linux/Ubuntu	mkdir bin
   Mac	mkdir bin
   Windows	mkdir bin

7. Change to the newly created bin directory.
   
   

   Operating System          Command

   Linux/Ubuntu	cd bin
   Mac	cd bin
   Windows	cd bin

8. Run the CMake command using your specific IDE of choice.
   NOTE: Include the two periods at the end of the code as shown below. Use cmake -G to see a list of supported IDEs.
   

cmake ..​

Once your build completes, you will find the build products in the bin directory, and you can open the project in your IDE of choice.

NOTE: You should receive messages confirming successful binding, authentication, and connection after building and running the application.

You should be able to see a Thing in your ThingWorx Composer called SimpleThing_1 with updated lastConnection and isConnected properties. SimpleThing_1 is bound for the duration of the application run time.

The below instructions will help to verify the connection.

1. Click Monitoring.
2. Click Remote Things from the list to see the connection status.

You will now be able to see and select the Entity within the list.

Step 4: ExampleClient Connection

The C code provided in the main.c source file is preconfigured to initialize the ThingWorx C Edge SDK API with a connection to the ThingWorx platform and register handlers. In order to set up the connection, a number of parameters must be defined. This can be seen in the code below.

#define TW_HOST "127.0.0.1"
#define TW_APP_KEY "ce22e9e4-2834-419c-9656-ef9f844c784c

#if defined NO_TLS
    #define TW_PORT = 80;
#else
    #define TW_PORT = 443;
#endif 

The first step of connecting to the platform: Establish Physical Websocket, we call the twApi_Initialize function with the information needed to point to the websocket of the ThingWorx Composer. This function:

• Registers messaging handlers
• Allocates space for the API structures
• Creates a secure websocket

err = twApi_Initialize(hostname, port, TW_URI, appKey, NULL, MESSAGE_CHUNK_SIZE, MESSAGE_CHUNK_SIZE, TRUE);

if (TW_OK != err) {
    TW_LOG(TW_ERROR, "Error initializing the API");
    exit(err);
}

If you are not using SSL/TLS, use the following line to test against a server with a self-signed certificate:

twApi_SetSelfSignedOk();

In order to disable HTTPS support and use HTTP only, call the twApi_DisableEncryption function. This is needed when using ports such as 80 or 8080. A call can be seen below:

twApi_DisableEncryption();

The following event handlers are all optional. The twApi_RegisterBindEventCallback function registers a function that will be called on the event of a Thing being bound or unbound to the ThingWorx platform. The twApi_RegisterOnAuthenticatedCallback function registered a function that will be called on the event the SDK has been authenticated by the ThingWorx Platform. The twApi_RegisterSynchronizeStateEventCallback function registers a function that will be called after binding and used to notify your application about fields that have been bound to the Thingworx Platform.

twApi_RegisterOnAuthenticatedCallback(authEventHandler, TW_NO_USER_DATA);
twApi_RegisterBindEventCallback(NULL, bindEventHandler, TW_NO_USER_DATA);
twApi_RegisterSynchronizeStateEventCallback(NULL, synchronizeStateHandler, TW_NO_USER_DATA);

NOTE: Binding a Thing within the ThingWorx platform is not mandatory, but there are a number of advantages, including updating Properties while offline.

You can then start the client, which will establish the AlwaysOn protocol with the ThingWorx Composer. This protocol provides bi-directional communication between the ThingWorx Composer and the running client application. To start this connection, use the line below:

err = twApi_Connect(CONNECT_TIMEOUT, RETRY_COUNT);
    
if(TW_OK != err){
    exit(-1);
}

Click here to view Part 3 of this guide.