ThingWorx WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR) > REST Web Services and WS EMS > Reading and Writing Properties Using the REST Web Services
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 WS EMS, you can use a GET from the REST client and the following URL:
Notice that you are pointing at the local WS EMS, on port 8000, to retrieve a description. By default, the WS EMS listens on port 8000. Also by default, the WS EMS accepts requests only from an application that is running on the same machine as it is (i.e., localhost). You can configure a WS EMS to accept requests from other IP addresses.
When you execute this request, the WS EMS pushes it to the ThingWorx platform. Keep in mind that the WS 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 see all the activity passing between the WS EMS and the ThingWorx platform.
For example, if the response seems 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 a WS 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:
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 WS 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 WS EMS. In both instances you see the value on the ThingWorx platform.
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 a WS EMS and Lua Script Resource and the WS 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 WS 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 a WS EMS, the WS 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.