Skip to main content

imp.wakeup(interval, callback, name)

Sets a timer and registers a function which will be called when the timer fires

Availability

Device + Agent

Parameters

Name Type Description
interval Float The length of time in seconds to elapse before the timer fires (0—10737418)
callback Function The function to call when the timer fires. The function is called with no parameters
name String An optional, agent-only name for the timer (see below)

Returns

The new timer object or null on error

Description

This method sets a timer to trigger the imp or the agent and call the specified function after the specified interval. The method does not block: the imp may enter a sleep state during the interim period or continue running code. When Squirrel runs out of device code to execute, it will automatically enter shallow sleep.

While this method is available to both imps and agents, it does not work between them: an agent, for example, can’t set a timer to call a function on the imp, or vice versa. However, the function called can of course include a device.send() or agent.send(), as appropriate, which in turn triggers the desired function.

The method returns a reference to the timer object it has instantiated. This allows you to store references to the timers you have created. Any timer can be subsequently passed to imp.cancelwakeup() to disable and delete the timer. When the timer fires, the reference will not be nulled, even though the timer no longer exists. imp.wakeup() will return null if the device is unable to create a new timer for any reason.

The timer has only centisecond (0.01s) resolution. The code

imp.wakeup(0.0, functionToCall);

acts like

imp.onidle(functionToCall);

while

imp.wakeup(0.000001, functionToCall);

acts like

imp.wakeup(0.01, functionToCall);

The imp supports timer durations of up to 230 centiseconds — ie. 124 days.

If the imp is handling some other event at the moment the timer fires, that other code is not interrupted. Instead, the second timer event is queued and is executed when all previously queued event handlers have returned, ie. when the imp would otherwise be idle. As such, the called function may run after a greater duration than that specified in the imp.wakeup() call.

For more information on lower-power suspend modes, refer to server.sleepfor() and server.sleepuntil().

Agents are able to maintain a queue of no more than 100 imp.wakeup() timers; devices are limited only by the amount of free memory into which the timer queue can grow. Having too many timers in play — for instance, creating multiple timers in a tight loop — is an easy way to fill the device’s memory, causing further memory allocation operations of any type to fail. Agents will throw a runtime error as soon as more than 100 timers are queued. It is therefore strongly recommended that yoi keep track of the timers you establish.

Named Agent Timers

The optional parameter, name, allows you to specify an identifier for a timer created by an agent — this functionality is not available on the device. If you provide a name, any existing agent timers which share that name will automatically be cancelled.

A timer’s name is not the same as the reference to that timer returned by imp.wakeup(). If you need to cancel a named timer, you must cancel it manually by passing a reference to it as an argument to imp.cancelwakeup().

Naming timers can be used to prevent your code from inadvertently spawning multiple loops in cases where you (correctly) use a timer to drive a loop:

function poll() {
    imp.wakeup(1.0, poll);
}

poll();    // Initiates a loop; loop count = 1
poll();    // Initiates a loop; loop count = 2

The above code causes poll() to be called every second. Adding a second call to the function after the first results in two loops, which may not be intended and increases the likelihood that you are more likely to hit the agent’s 100-timer limit (see above). Adding a name to the imp.wakeup() call will prevent this because any subsequent calls to poll() will cause the existing timer (and thus the loop) to be cancelled:

function poll() {
    // Name the timer to prevent extra loops being spawned
    imp.wakeup(1.0, poll, "poll.timer");
}

poll();    // Initiates a loop; loop count = 1
poll();    // Cancels the first loop, initiates a loop; loop count = 1

Example Code

This code regularly samples the value of an imp pin configured as an analog input. It does this in the function poll(), which uses imp.wakeup() to call itself again in one second’s time, establishing a non-blocking loop.