Reading and Writing Properties Using the REST Web Services
This topic explains how to read a property value and how to write a property value.
Reading a Property Value
To read a property from the local EMS, you can use a GET from the REST client and the following URL:
http://localhost:8000/Thingworx/Things/thing_name/Properties/prop_name
Notice that you are pointing at the local EMS, on port 8000, to retrieve a description. By default, the EMS listens on port 8000. Also by default, the EMS accepts requests only from an application that is running on the same machine as it is (i.e., localhost). You can configure an EMS to accept requests from other IP addresses.
When you execute this request, the EMS pushes it to the ThingWorx Platform. Keep in mind that the EMS has no state. It does not even know that the property exists. It just takes the request URL, breaks it up and repackages it, translates it into the AlwaysOn protocol, and forwards it to the ThingWorx Platform. The platform responds with its current value for that property. The result type is always of base type INFOTABLE, with the property name and current value.
 |
To debug a problem with a property not updating or a service not executing, set the level and publish_levelproperties (in the logger group of the config.json file) to TRACE and in the ws_connection group, set the verbose property to true. That way, you can monitor all the activity passing between the EMS and the ThingWorx Platform.
For example, if the response appears to be returned slowly, by logging at the TRACE level and setting verbose to true, you can check the timestamps for the request and response to calculate the actual time. To match a request with a response, locate the Request ID of the outgoing message and the Request ID included in the incoming response message.
|
Writing a Property Value
To write a property value to the ThingWorx Platform through an EMS for an edge device managed by a Lua Script Resource, select the PUT method in the REST client and use the same URL as a read (GET) for the property. For example:
http://localhost:8000/Thingworx/things/thing_name/Properties/<prop_name>
Then, in the area provided in the client, enter the property name and value, using JSON format:
{
"<prop_name>": "Hello World from Thingworx"
}
It is important to remember that the ThingWorx Platform recognizes the PUT as coming from the edge device and updates the value for the device and does not attempt to write it to the device.
If you shut down the Lua Script Resource and execute the same PUT, the value is written to the ThingWorx Platform for the device that is running EMS rather than the LSR device. The distinction is between writing the value directly to the platform, as opposed to writing the value through the EMS. In both instances the value is accessibl through ThingWorx Composer and available to any subscription or custom Javascript code you write to access the value.
You also need to set the Content-type for a write to the format you are using. In this case, it is application/json. If the device for the property is a Remote Thing, the property is also remote. If that device is not bound, you cannot write the value to the property. If the device is connected through an EMS and Lua Script Resource and the EMS is running, you can start up the Lua Script Resource that is configured for the Remote Thing. Once the Remote Thing is bound, the ThingWorx Platform can send the write request to the EMS.
Note that the ThingWorx Platform instance does not change the property value until the request has made the full round trip:
1. A request is sent from a REST client to the specified ThingWorx Platform.
2. The ThingWorx Platform recognizes it as a remote property and forwards to the remote Thing.
3. If the Remote Thing is running an EMS, the EMS sends it to LSR, which writes it internally.
At this point, the in-memory value on the ThingWorx Platform is still the old value. The LSR should be set up to send the value back up to the platform.
4. Only after the LSR sends the new value back to the ThingWorx Platform does the value change there.