Polling Updates for EdgeThingShapes
A common use case for a Thing is to update its values at periodic intervals, particularly if it is responsible for sampling data changes or if it provides simulated data. This capability is available for Edge Extensions as well. During the process of constructing a shape, the constructor function can register to receive and call back. This process is called the processScanRequest() function in the SDK. Since the process of registering to receive and call back in an Edge Extension constructor is similar to the functionality of the processScanRequest() function, the same terminology is used in this example.
To be able to generate a polling event, the C SDK must control thread execution and have a hook into it that works with single- and multiple-thread models. Even though you can manually construct your own threads, the SDK provides three common threading modes — single, simple and multi, which should satisfy most needs.
Once your connection has been established, calling this new SDK API method returns control of threading to the SDK, allowing it to manage your threads:
void twExt_Idle(uint32_t dataCollectionRate,enum twThreadingModel threadingModel);
Here the dataCollection rate is in milliseconds and threadingModel can be one of the following:
• TW_THREADING_SINGLE
• TW_THREADING_SIMPLE
• TW_THREADING_MULTI
If you are integrating the SDK into your own application, you could call twExt_Idle() from your own thread, maintain control of your threads, and later terminate this thread as part of your shutdown sequence.
 |
Using TW_THREADING_MULTI is the best practice choice for all new applications.
|
Once twExt_Idle() is called, the calling thread does not exit unless terminated. Depending on the selected threadingModel, one, two, or multiple threads will be spawned for use by the SDK.
Each ETS and ETT can register functions to be called periodically by the Idle loop. These functions can be used to simulate or sample data from a real data source such as a peripheral device. The new SDK call to register a polled function follows:
void twExt_RegisterPolledFunction(twOnPolled polledFunction,char* shapeName);
Providing a twOnPolled() function causes it to be called by the SDK at the frequency specified by dataCollectionRate (defined in milliseconds). The twOnPolled() function is called once for each Thing that has registered a particular EdgeThingShape or EdgeThingTemplate. The SDK provides the name of the Thing that it intends to operate on. Here is an example of a twOnPolled() function:
void steamSensorDataGenerationTask(char* thingName) {
TW_LOG(TW_TRACE,"steamSensorDataGenerationTask: Executing");
TW_SET_PROPERTY(thingName, "TotalFlow", TW_MAKE_NUMBER(rand() /
(RAND_MAX / 10.0)));
TW_SET_PROPERTY(thingName, "Pressure", TW_MAKE_NUMBER(18 + rand() /
(RAND_MAX / 5.0)));
TW_SET_PROPERTY(thingName, "Location",
TW_MAKE_LOC((rand() - RAND_MAX) / RAND_MAX / 5,
(rand() - RAND_MAX) /
RAND_MAX / 5, 0));
TW_SET_PROPERTY(thingName, "Temperature",
TW_MAKE_NUMBER(400 + rand() / (RAND_MAX / 40)));
/* Update the properties on the server */
TW_PUSH_PROPERTIES_FOR(thingName);
}
A twOnPolled() function is passed only the thingName that it is expected to update. This information is sufficient for it to be able to modify its own properties or call its own services.