Quick Introduction to MonitorsDuring both normal (uploading data from devices) and abnormal (alarms triggered for device health) operation of a customer's DC environment, the platform generates events for a variety of scenarios. A push monitor is an interface that can be used to write device cloud applications that take advantage of event driven programming to watch for or "monitor" when these events occur. A push monitor involves a customer HTTP server (or a client application that connects with TCP) to wait for events to be received. Push monitors can be "persistent", so that if the server crashes or is unavailable, events that may have been missed by the monitor can be re-sent or replayed.Performance is improved by using monitors because you don’t have to poll for data and only those events which match the monitor "topic" will be delivered. Monitors effectively provide an event driven alternative to repeated queries with (possibly complex) conditions. Monitors also provide a way to receive events from many devices which otherwise may require many queries to retrieve.There are a wide variety of events that occur and the events also indicate an operation (for example, create, update, delete of a resource) · DataPoint event - when a device uploads a data point· DataStream event - when operations on a data stream occur· DeviceCore event - When a device itself created, updated or deleted· FileData and FileDataCore events - when files are manipulated on the platform· Job and JobResult events - when jobs on the system created, run, or are completed· AlarmStatus event - Alarms are triggered, reset or acknowledged· XbeeAttributeDataCore and XbeeCore events - Xbees and Xbee attribute data is created, update or deleted· Others....Query MonitorA query monitor is a simplified version of a push monitor. The use of a query monitor requires no customer server. As its name implies, events are retrieved from a query monitor using a web service query instead of an event driven model. There are still benefits to using a query monitor over more traditional queries.A query monitor specifies topics in a fashion that is identical to a push monitor. The specified monitor topics limit the amount of data saved for a query monitor. The topics function incrementally at the time events occur in the system, causing a significant savings at query time. There is no filtering required at query time, only streaming data from the platform.The query monitor topics can specify multiple data streams, devices or other criteria, thereby letting a single monitor function as a data sink for events from many devices. If an application uses simple web service queries for those individual resources or devices, many queries are required, for the query monitor, only few queries are required. DemonstrationThis demo uses XML data files and the cURL command line tool to operate on Device Cloud, allowing easy copy and paste from the examples. The demo uses the devicecloud.digi.com web site and a particular device. You can easily use API explorer to perform the same operations. Paste the data files appropriately into the payload section and add the required parameters to the path text box. In the example, we’ve saved the data files to a location indicated by the $DIR environment variable, and specified my user and password in the $USER variable
In addition, the demo uses an existing device 00000000-00000000-00409DFF-FF123456 for testing DataPoints. Any device in your account should do fine, do not use a device that may already have production monitors or alerts associated with it, because you could impact production behaviors.Create a query monitorCreate a query monitor much like a push monitor, but notice the very simple payload. It needs to define only the type of monitor and the topics (in this case a single topic).
Perform an Event Generating ActionA wide variety of scenarios will send data to a monitor. In this case, we're keeping it simple, we've defined a monitor with a DataPoint and are simply going to be uploading data points. 
It’s important to note here that we are NOT uploading data to the monitor.Instead, we are simulating uploading data from a device, and the platform is generating a DataPoint event as a result of the data uploaded. In this example, the difference is subtle, but important. The system generates events based on actions occurring in the platform. If we were to change or delete the datapoint, an appropriate event would be created for that action as well. Some events are less closely related to a physical piece of data in the system, but more closely related to some action. For example, AlarmStatus events occur when an alarm is triggered
Query data in the monitorWe now have a monitor that has saved a single DataPoint event. We can query for it using a simple monitors/history call with no parameters. Since there is only one event, the query will return all events from the monitor.
| curl -u $USER http://devicecloud.digi.com/ws/v1/monitors/history/440495 |
The output shows the data point itself, and information about the event that was sent.· The event was an INSERTION event· The event was sent for a particular topic and timeNote the returned "polling_cursor" and "polling_uri" values. Either of those values can be used in a subsequent call (the next poll) to retrieve only NEW data from this point forward (we'll see this in a subsequent step).
Generate more eventsWe can now add 3 additional data points to the stream. These data point objects match the monitor topic and respectively have data values 100, 200, 300. They cause 3 more events to be generated for the monitor.
Upload each of them, here you can see the output of each command.
Query data using pollingWe can now using the polling cursor (returned from the first monitors/history API call) to continue to retrieve subsequent saved events from the monitor. In this example, we also use the size parameter set to 1, purely for demonstration purposes so we can see how continual polling works.In production applications, you'd never want to poll with a size of 1, it'll take forever and drive more load on the system, possibly also resulting in hitting throttling limits.Additionally, don't poll too often, or again, you'll end up with throttling.We see here that only the 2nd data point (DataPoint1.xml with a value of 100) is returned and we get a new value for the polling cursor.
Continue polling a couple of more times, polling for DataPoint2 and DataPoint3. Note that each time, we update the uri that we pass to the subsequent call using the polling_cursor or polling_uri results from the previous call, thereby walking through all of the results.
No data, but polling can continueWhen we have been polling through available data on a monitor, eventually, we reach the end of the data available. In that case, we get no results back, but we still get a polling_cursor and a polling_uri. We can come back later after we allow time for more events to come in and continue. The cursor is valid and we can continue to use it until we get data returned for it.
We can query at the beginning of the data again by leaving out the cursor parameter. For example a new empty query (with size=1) returns only the first DataPoint again.
Last updated:
Jan 01, 2024