Timer events

With the addition of timer events to the execution context, a wide variety of custom behaviours is now possible. The added functionality of course comes with some new considerations about how to write your scripts.

1. Execution contexts are not re-used, so any variables or assignments not made to the asset object will be lost between events.
2. If a device event is supposed to cancel a timer, but the device has not reported in, the timer may fire while the device is outside of cellular coverage, or before it can send in the event.
3. Timer events only fire after all other events have been processed. That means if there is a backlog of events to process for an asset, the timer will not necessarily fire at the moment requested.

How to control and handle a timer

There are two new gloabl methods embedded in the execution context; setTimer and clearTimer. The setTimer function takes two arguments, the timer ID, and a valid Date object as the desried date/time to invoke the TimerEvent. The clearTimer takes only one argument; the timer ID. A timer ID is a number with a value between 128 and 255. Values of 127 and lower are reserved for system use.

When a timer event is fired, it fires only two events in this order:

1. timer TimerEvent
   The event fired by a invoking setTimer.
2. finalize FinalizeEvent
   After all events have been fired, this one happens last so developers can perform any last checks or clean-ups.

Here's a simple example for setting and handling a timer event:

var timerId = 128,
    threshold = 60 * 60 * 1000;   // 1 hour
asset.on("position", function(event) {
    clearTimer(timerId); // clear timer with each new position
    var callAt = threshold + event.position.dts.valueOf();
    if (callAt > new Date()) setTimer(timerId, callAt); // only set the timer if it's in the future
});
asset.on("timer", function(event) {
    if (event.number == timerId) {
        // do something
    }
});

Here's an example from a script that sets the out-of-date tag on an asset:

var timerId = 209,
    threshold = 5 * 60 * 1000, // 5 minutes
    tagName = "out-of-date";
asset.on("finalize", function(event) {
    clearTimer(timerId);
    var indexOod = this.tags.indexOf(tagName);
    if (!this.position || (new Date() - this.position.dts) >= threshold) {
        if (indexOod < 0) this.tags.push(tagName);
    } else {
        if (threshold > 0) {
            var callAt = threshold + this.position.dts.valueOf();
            if (callAt > new Date()) setTimer(timerId, callAt); // only set the timer if it's in the future
        }
        if (indexOod > -1) this.tags.splice(indexOod, 1);
    }
});