diff --git a/Examples/README.md b/Examples/README.md index 00f13e3..f2c54d2 100644 --- a/Examples/README.md +++ b/Examples/README.md @@ -1,59 +1,61 @@ -# ThingWorx Examples +# ThingWorx Examples # This document describes the example application provided with the [ThingWorx library](../README.md). -## DataSender Example +## DataSender Example ## -This example creates ThingWorx Thing named `test_thing` (if it does not exist already) with two predefined Properties and periodically updates the Properties values: -- the values are updated every 10 seconds. -- the Properties are: - - `data` - integer value, converted to string, which starts at 1 and increases by 1 with every update. It restarts from 1 every time when the example is restarted. - - `measure_time` - integer value, the time in seconds since the epoch. +This example creates a ThingWorx Thing named `test_thing` (if it does not exist already) with two predefined Properties: -## Setup and Run +- *data* — An integer value, converted to string, which starts at 1 and increases by 1 with every update. It restarts from 1 every time the example is restarted. +- *measure_time* — An integer value, which is the time in seconds since the epoch. -### ThingWorx Evaluation Server Configuration +The application updates the Properties values every 10 seconds. + +## Setup and Run ## -- Login to [ThingWorx Developer Portal](https://developer.thingworx.com/login) in your web browser. -- Click **Evaluation Server** icon in the top right corner of the Developer Portal. **Note:** The initial provisioning of Evaluation Server for a new account usually takes between 3-5 minutes. -- Copy **Hostname** value from the pop up and paste into a plain text document or equivalent. This will be used as the value of the *THING_WORX_ENDPOINT* constant in the imp agent code. -- Click **Launch**. You will be redirected to the ThingWorx Composer page (usually a new tab). +### ThingWorx Evaluation Server Configuration ### + +- Login to the [ThingWorx Developer Portal](https://developer.thingworx.com/login) in your web browser. +- Click the **Evaluation Server** icon in the top right corner. **Note** The initial provisioning of Evaluation Server for a new account usually takes between 3-5 minutes. +- Copy the **Hostname** value from the pop-up and paste it into a plain text document or equivalent. This will be used as the value of the *THING_WORX_ENDPOINT* constant in the imp agent code: ![LaunchThingWorx](../png/LaunchThingWorx.png?raw=true) -- In the **ThingWorx Composer** **Home** tab click **Application Keys "+"** button in the **SECURITY** menu. +- Click **Launch**. You will be redirected to the ThingWorx Composer page (usually a new browser tab) +- In the **ThingWorx Composer** page’s **Home** tab, click **+** under **Application Keys** in the **SECURITY** section: ![AddAppKey](../png/AddAppKey.png?raw=true) - Enter any Application Key **Name**, eg. `testAppKey`. -- Click **Search** button in **User Name Reference** field and choose **Administrator** user. +- Click **Search** in the **User Name Reference** field under **General Information**, and choose the **Administrator** user: ![AppKeyUser](../png/AppKeyUser.png?raw=true) -- Choose date and time for **Expiration Date** field. -- Click **Done**. -- Click **Save**. +- Choose a date and time for **Expiration Date** field. +- Click **Done** then click **Save**: ![AppKeyExpirationDate](../png/AppKeyExpirationDate.png?raw=true) -- In the **General Information** page of your Application Key select and copy **keyId** field and paste into a plain text document or equivalent. This will be used as the value of the *THING_WORX_APPLICATION_KEY* constant in the imp agent code. +- On the **General Information** page select and copy the **keyId** field and paste into a plain text document or equivalent. This will be used as the value of the *THING_WORX_APPLICATION_KEY* constant in the imp agent code: ![AppKeyId](../png/AppKeyId.png?raw=true) -### DataSender Example Setup and Run +### Setting Up and Running the Application ### -- In the [Electric Imp's IDE](https://ide.electricimp.com) create new Product and Development Device Group. -- Assign device to the newly created Device Group. -- Copy the [DataSender source code](./DataSender.agent.nut) and paste it into the IDE as the agent code. -- Set *THING_WORX_ENDPOINT* constant in the agent example code to the value of Evaluation Server Hostname you retrieved and saved in the previous steps, prefixed by `https://`. The value should look like `"https://PP-1802281448E8.Devportal.Ptc.Io"`. -- Set *THING_WORX_APPLICATION_KEY* constant in the agent example code to the value of Application Key Id you retrieved and saved in the previous steps. +- In [Electric Imp’s impCentral™](https://impcentral.electricimp.com) create a Product and Development Device Group. +- Assign a development device to the newly created Device Group. +- Open the code editor for the newly created Device Group. +- Copy the [DataSender source code](./DataSender.agent.nut) and paste it into the code editor as the agent code. +- Set the *THING_WORX_ENDPOINT* constant in the agent example code to the value of Evaluation Server Hostname you retrieved and saved above. Ensure it is prefixed with `https://`. The value should look like `"https://PP-1802281448E8.Devportal.Ptc.Io"`. +- Set the *THING_WORX_APPLICATION_KEY* constant in the agent example code to the value of the Application Key ID you retrieved and saved above: ![SetThingWorxConsts](../png/SetThingWorxConsts.png?raw=true) - Click **Build and Force Restart**. -- Check from the logs in the IDE that data sendings are successful. +- Use the code editor’s log pane to confirm that data is being sent successfully: ![DataSenderLogs](../png/DataSenderLogs.png?raw=true) -**Note:** the hosted ThingWorx Evaluation Server is stopped after 3 hours of inactivity and, typically, it takes about one minute to start it again. -You need to ensure the Server is started before running the Example. -To start the Server: -- Click **Evaluation Server** icon in the top right corner of the ThingWorx Developer Portal. -- Check the Server status in the pop up. If it is **Stopped**, click **Start** button. +### Notes ### + +- The hosted ThingWorx Evaluation Server is stopped after three hours of inactivity and, typically, it takes about one minute to start it again. +- You need to ensure the Server is started before running the example. To start the Server: + - Click the **Evaluation Server** icon in the top right corner of the ThingWorx Developer Portal. + - Check the Server status in the pop-up. If it is **Stopped**, click **Start**. -### Monitor the Properties Values in ThingWorx +### Monitor the Properties Values in ThingWorx ### -- In the **ThingWorx Composer** **Home** tab click **Things** in the **MODELING** menu. -- Click *test_thing* in the **Things** table. +- In the **ThingWorx Composer** page’s **Home** tab, click **Things** in the **MODELING** section. +- Click *test_thing* in the **Things** table: ![ThingsTable](../png/Things.png?raw=true) -- In the **test_thing** tab click **Properties** in the **ENTITY INFORMATION** menu. -- Ensure the Properties table contains **data** and **measure_time** Properties and their values are updated periodically if **Refresh Properties** button is clicked. +- In the **test_thing** tab, click **Properties** in the **ENTITY INFORMATION** section. +- Ensure the Properties table contains **data** and **measure_time** Properties, and that their values are updated periodically if **Values** column’s refresh button is clicked: ![ThingProperties](../png/ThingProperties.png?raw=true) diff --git a/README.md b/README.md index 2ee2fdd..134958a 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ This version of the library supports the following functionality: - Thing Property creation. - Setting a value of Thing Property. -**To add this library to your project, add** `#require "ThingWorx.agent.lib.nut:1.0.0"` **to the top of your agent code.** +**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 ## @@ -18,38 +18,51 @@ This version of the library supports the following functionality: 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`). -- ThingWorx Application Key (see [here](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/create-appkey)). +- A [ThingWorx Application Key](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/create-appkey)). ### 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](#thingworxerror-class) class and contains the details of the error. +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](#thingworxerror-class) 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 ## ### 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. Example: `"https://PP-1802281448E8.Devportal.Ptc.Io"`. | -| *appKey* | String | Yes | ThingWorx Application Key. See [here](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/create-appkey). | +| *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](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/create-appkey) | + +#### Example #### + +``` +#require "ThingWorx.agent.lib.nut:1.0.0" + +const MY_PLATFORM_ENDPOINT = ""; +const MY_APP_KEY = ""; -This method returns a new *ThingWorx* instance. +tw <- ThingWorx(MY_PLATFORM_ENDPOINT, MY_APP_KEY); +``` ### createThing(*thingName[, thingTemplateName][, callback]*) ### -This method creates a new Thing, enables and restarts it. See [here](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/use-rest-api-create-new-thing). +This method creates a new Thing, enables and restarts it. For more information, please see [the ThingWorx documentation](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/use-rest-api-create-new-thing). | 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. See [here](https://developer.thingworx.com/resources/guides/thingworx-foundation-quickstart/thing-template). If not specified, the standard ThingWorx `"GenericThing"` template is used. | -| *callback* | Function | Optional | Executed once the operation is completed. | +| *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](https://developer.thingworx.com/resources/guides/thingworx-foundation-quickstart/thing-template) | +| *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 parameters: +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](#thingworxerror-class) | Error details, or `null` if the operation succeeds. | +| *error* | [ThingWorx.Error](#thingworxerror-class) | Error details, or `null` if the operation succeeds | ### existThing(*thingName, callback*) ### @@ -57,15 +70,15 @@ 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. | +| *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](#thingworxerror-class) | Error details, or `null` if the operation succeeds. | -| *exist* | Boolean | `true` if the Thing exists; `false` if the Thing does not exist or the operation fails. | +| *error* | [ThingWorx.Error](#thingworxerror-class) | 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]*) ### @@ -73,48 +86,48 @@ 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. | +| *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 parameters: +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](#thingworxerror-class) | Error details, or `null` if the operation succeeds. | +| *error* | [ThingWorx.Error](#thingworxerror-class) | 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. See [here](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/use-rest-api-add-property-thing). +This method creates a new Property of the specified Thing and restarts the Thing. For more information, please see [the ThingWorx documentation](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/use-rest-api-add-property-thing). | 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. One of the types described [here](https://support.ptc.com/cs/help/thingworx_hc/thingworx_7.0_hc/index.jspx?id=ThingProperties&action=show). | -| *callback* | Function | Optional | Executed once the operation is completed. | +| *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](https://support.ptc.com/cs/help/thingworx_hc/thingworx_7.0_hc/index.jspx?id=ThingProperties&action=show) | +| *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 parameters: +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](#thingworxerror-class) | Error details, or `null` if the operation succeeds. | +| *error* | [ThingWorx.Error](#thingworxerror-class) | Error details, or `null` if the operation succeeds | ### setPropertyValue(*thingName, propertyName, propertyValue[, callback]*) ### -This method sets a new value of the specified Property. See [here](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/use-rest-api-set-property-value). +This method sets a new value of the specified Property. For more information, please see [the ThingWorx documentation](https://developer.thingworx.com/resources/guides/thingworx-rest-api-quickstart/use-rest-api-set-property-value). | 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. | +| *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 parameters: +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](#thingworxerror-class) | Error details, or `null` if the operation succeeds. | +| *error* | [ThingWorx.Error](#thingworxerror-class) | Error details, or `null` if the operation succeeds | ### setDebug(*value*) ### @@ -125,12 +138,12 @@ This method enables (*value* is `true`) or disables (*value* is `false`) the lib 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 an application development which should be fixed during debugging and therefore should not occur after the application has been deployed. + - *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 with human readable details of the error. -- *httpStatus* — An integer indicating the HTTP status code, or `null` if *type* property is *LIBRARY_ERROR* -- *httpResponse* — A table of key-value strings holding the response body of the failed request, or `null` if *type* property is *LIBRARY_ERROR*. +- *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*. ## Examples ## @@ -140,6 +153,6 @@ Working examples are provided in the [Examples](./Examples) directory and descri Tests for the library are provided in the [tests](./tests) directory and described [here](./tests/README.md). -## License +## License ## The ThingWorx library is licensed under the [MIT License](./LICENSE)