Skip to main content

ThingWorx

Latest Version: 1.0.0

This library allows your agent code to work with the ThingWorx platform via the ThingWorx REST API.

This version of the library supports the following functionality:

  • Access ThingWorx platform (verified with PTC hosted instance only).
  • Thing creation and deletion.
  • Thing Property creation.
  • Setting a value of Thing Property.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

To add this library to your project, add #require "ThingWorx.agent.lib.nut:1.0.0" to the top of your agent code

Library Usage

Prerequisites

Before using the library you need to have:

  • An endpoint of your ThingWorx platform instance — it may look like https://PP-1802281448E8.Devportal.Ptc.Io
  • A ThingWorx Application Key

Callbacks

All requests that are made to the ThingWorx platform occur asynchronously. Every method that sends a request has an optional parameter which takes a callback function that will be executed when the operation is completed, whether successfully or not. The callback’s parameters are listed in the corresponding method description, but every callback has at least one parameter, error. If error is null, the operation has been executed successfully. Otherwise, error is an instance of the ThingWorx.Error class and contains the details of the error.

Some methods require callbacks to be specified, others need only be passed a callback if you wish.

ThingWorx Class Usage

Constructor: ThingWorx(endpoint, appKey)

This method returns a new ThingWorx instance.

Parameter Data Type Required? Description
endpoint String Yes ThingWorx platform endpoint. Must include the scheme, eg. "https://PP-1802281448E8.Devportal.Ptc.Io"
appKey String Yes ThingWorx Application Key. For more information, please see the ThingWorx documentation

Example

#require "ThingWorx.agent.lib.nut:1.0.0"

const MY_PLATFORM_ENDPOINT = "<YOUR_PLATFORM_ENDPOINT>";
const MY_APP_KEY = "<YOUR_THINGWORX_APP_KEY>";

tw <- ThingWorx(MY_PLATFORM_ENDPOINT, MY_APP_KEY);

ThingWorx Class Methods

createThing(thingName[, thingTemplateName][, callback])

This method creates a new Thing, enables and restarts it. For more information, please see the ThingWorx documentation.

Parameter Data Type Required? Description
thingName String Yes Name of the new Thing. Must be unique across the ThingWorx platform instance
thingTemplateName String Optional A Thing Template which may be used for the Thing creation. If not specified, the standard ThingWorx "GenericThing" template is used. For more information, please see the ThingWorx documentation
callback Function Optional Executed once the operation is completed

This method returns nothing. The result of the operation may be obtained via the callback function, which has the following parameter:

Parameter Data Type Description
error ThingWorx.Error Error details, or null if the operation succeeds

existThing(thingName, callback)

This method checks if Thing with the specified name exists.

Parameter Data Type Required? Description
thingName String Yes Name of the Thing
callback Function Yes Executed once the operation is completed

This method returns nothing. The result of the operation may be obtained via the callback function, which has the following parameters:

Parameter Data Type Description
error ThingWorx.Error Error details, or null if the operation succeeds
exist Boolean true if the Thing exists, or false if the Thing does not exist or the operation fails

deleteThing(thingName[, callback])

This method deletes Thing with the specified name.

Parameter Data Type Required? Description
thingName String Yes Name of the Thing
callback Function Optional Executed once the operation is completed

This method returns nothing. The result of the operation may be obtained via the callback function, which has the following parameter:

Parameter Data Type Description
error ThingWorx.Error Error details, or null if the operation succeeds

createThingProperty(thingName, propertyName, propertyType[, callback])

This method creates a new Property of the specified Thing and restarts the Thing. For more information, please see the ThingWorx documentation.

Parameter Data Type Required? Description
thingName String Yes Name of the Thing
propertyName String Yes Name of the new Property. Must be unique across the specified Thing
propertyType String Yes Type of the new Property. Must be one of the types described in the ThingWorx documentation
callback Function Optional Executed once the operation is completed

This method returns nothing. The result of the operation may be obtained via the callback function, which has the following parameter:

Parameter Data Type Description
error ThingWorx.Error Error details, or null if the operation succeeds

setPropertyValue(thingName, propertyName, propertyValue[, callback])

This method sets a new value of the specified Property. For more information, please see the ThingWorx documentation.

Parameter Data Type Required? Description
thingName String Yes Name of the Thing
propertyName String Yes Name of the Property
propertyValue Boolean, Integer, Float,
String, Key-Value Table,
Blob, Null
Yes New value of the Property
callback Function Optional Executed once the operation is completed

This method returns nothing. The result of the operation may be obtained via the callback function, which has the following parameter:

Parameter Data Type Description
error ThingWorx.Error Error details, or null if the operation succeeds

setDebug(value)

This method enables (value is true) or disables (value is false) the library debug output (including error logging). It is disabled by default. The method returns nothing.

ThingWorx.Error Class

This class represents an error returned by the library and has the following public properties:

  • type — The error type, which is one of the following THING_WORX_ERROR enum values:
    • LIBRARY_ERROR — The library is wrongly initialized, a method is called with invalid argument(s), or an internal error has occurred. The error details can be found in the details property. Usually this indicates an issue during application development which should be fixed during debugging and therefore should not occur after the application has been deployed.
    • REQUEST_FAILED — An HTTP request to the ThingWorx platform failed. The error details can be found in the details, httpStatus and httpResponse properties. This error may occur during the normal execution of an application. The application logic should process this error.
    • UNEXPECTED_RESPONSE — An unexpected response from the ThingWorx platform. The error details can be found in the details and httpResponse properties.
  • details — A string containing a human readable description of the error.
  • httpStatus — An integer indicating the HTTP status code, or null if the type property is LIBRARY_ERROR
  • httpResponse — A table of key-value strings holding the response body of the failed request, or null if the type property is LIBRARY_ERROR.

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version Source Code Notes
1.0.0 GitHub Initial release

License

The ThingWorx class is licensed under MIT License.