Push Properties
Use this function to update one or more properties with a single message to ThingWorx Platform. You can also use it to send multiple values of the same property to ThingWorx Platform in a single message.
enum msgCodeEnum twApi_PushProperties(enum entityTypeEnum entityType, char * entityName, propertyList * properties, int32_t timeout, char forceConnect)
If many devices are pushing multiple properties very frequently and the error message code 1114 appears in the logs, you may need to change the default timeout for the ThingWorx Platform to respond to a service call. For details, refer to Troubleshooting an Error Pushing/Persisting Properties and Property Lists.
BEST PRACTICES: For best performance, do not push every time a property changes. Collect property updates and send them in batches to the ThingWorx Platform. It takes anywhere from 3 to 500 ms for a round-trip to the ThingWorx Platform from the device. You want to get the most value for each round trip. Sending in batches makes that possible. It may take experimenting with different batches. For example, you could start at 100 updates, then increase to 500, and then 1000. When you have achieved a batch number that gives you the desired performance, then test that over time. You need to take into consideration the traffic on your network as well as the load on the database when updating too frequently. For example, pushing every 3 ms can put a lot of load on a relatively small database. Monitor how many property updates come in on a regular basis. Your environment and organizational needs can help determine if and when you need to re-evaluate how many updates you send in each batch and how often. Also, keep in mind that there is a small latency between the arrival of an update at the platform and its display in a mashup or in ThingWorx Composer.
The following table describes the parameters for this helper function:
The type of entity that the properties belong to. Enumeration values can be found in the file, twDefinitions.h
The name of the entity that the properties belong to.
A pointer to a list of twPrimitives. The calling function retains ownership of this pointer and is responsible for releasing the memory after the call is complete.
The time (in milliseconds) to wait for a response from the platform. A value of -1 uses the DEFAULT_MESSAGE_TIMEOUT as defined in twDefaultSettings.h
A Boolean value. If true and the API is in the disconnected state of the duty cycle, the API forces a reconnect to send the request.
msgCodeEnum — the result of the call. Refer to twDefinitions.h for the enumeration definition.
An example usage of the twApi_PushProperties function is as follows:
void sendPropertyUpdate() {propertyList * proplist = twApi_CreatePropertyList("FaultStatus", twPrimitive_CreateFromBoolean(properties.FaultStatus), 0);
if (!proplist) {
TW_LOG(TW_ERROR,"sendPropertyUpdate: Error allocating property list");
twApi_AddPropertyToList(proplist,"InletValve", twPrimitive_CreateFromBoolean(properties.InletValve), 0);
twApi_AddPropertyToList(proplist,"Temperature", twPrimitive_CreateFromNumber(properties.Temperature), 0);
twApi_AddPropertyToList(proplist,"TotalFlow", twPrimitive_CreateFromNumber(properties.TotalFlow), 0);
twApi_AddPropertyToList(proplist,"Pressure", twPrimitive_CreateFromNumber(properties.Pressure), 0);
twApi_AddPropertyToList(proplist,"Location", twPrimitive_CreateFromLocation(&properties.Location), 0);
twApi_PushProperties(TW_THING, thingName, proplist, -1, FALSE);
Was this helpful?