Timer¶

Overview¶

The Timer API is used to set repeating timers. It is fundamental for creating many types of Intelligent Modules that use polling to update the UI and perform repeating actions. Every time the timer completes, an EventHandler function will be called. This is typically used to poll and update aspects of the UI and/or perform some repeating operations at a regular interval.

Timer.¶

Timer.New¶

User Timer.New() to create a new named Timer Object.

MyTimer = Timer.New() --Creates a new Timer called MyTimer

You will then use that object to run the timer. Up to 8 timers may be created per Intelligent Module.

TimerName¶

The following methods and properties are available for a Timer object with name TimerName.

TimerName.ID¶

Get the ID index for a timer.

MyTimer = Timer.New()

MyTimerID = MyTimer.ID -- MyTimerID = 1

IDs are assigned in order of creation starting with 1. This can be used to learn the ID of a timer and then use it in the EventHandler callback function described below.

TimerName:Start(period)¶

This method starts the named timer with a period given in seconds.

MyTimer:Start(1) --Starts the timer with a period of 1 second

The minimum timer period is dependant on which device the IM is running.

Radius NX, Edge and Prism class devices, are updated at a maximum of 4 Hz so the smallest allowable timer period is 0.25 seconds.

Server D100, is updated at a maximum of 1 Hz so the smallest allowable timer period is 0.1 seconds.

Note that, Composer may have a hard time keeping up with previewing the graphics changes of a faster timer period, depending on graphics load. At 100ms, the fastest update period in Composer, graphics load is more likely to affect actual timer period update rate.

If you want the timer at the lowest possible period supported by the platform, it is advised to utilize Device.LocalUnit.TimerResolution to configure the timer:

MyTimer:Start(Device.LocalUnit.TimerResolution/1000) --Starts the timer with the minimum period supported by the device

When using the above method, it is important that TimerClick () method accounts for the potential variability in the Timer period as needed.

Since the Device.LocalUnit.TimerResolution was introduced in 9.0, it will not function in 8.x installations. To ensure backwards compatibility with publicly distributed IMs, see Example 6 below.

TimerName:Stop¶

This method stops the named timer. It can be restarted

MyTimer:Stop --Stops the timer

TimerName.EventHandler(TimerName)¶

Assign the callback function for the named timer that will be called whenever the timer reaches its set time.

This can be done in two ways. With a dedicated function:

function TimerClick ()

--Do lots of stuff every time

end

MyTimer.EventHandler = TimerClick

Alternately, you can use an anonymous function:

MyTimer.EventHandler = function ()

--Do lots of stuff every time

end

You can optionally pass the Timer object as an argument in the callback function. This allows access to the Timer.ID, which allows you to use the same callback function for multiple timers.

function TimerClick (TimerName)

if TimerName.ID == MyTimerID then

--Do stuff for the first timer

else

--Do different stuff for every other timer

end

end

MyTimer.EventHandler = TimerClick

MyTimerID = MyTimer.ID

MyOtherTimer.EventHandler = TimerClick

Usage Examples¶

The following examples illustrate how these can be used:

Example 1 – Putting it all together¶

This example shows how Timers are used to update the UI and/or perform some repeating actions at a regular interval.

function TimerClick ()

--Do lots of stuff every time

end

MyTimer = Timer.New()

MyTimer.EventHandler = TimerClick

MyTimer:Start(.25)

First you define the function that you want to be called, every time the timer completes. Then create the Timer and set your function as the EventHandler for your timer. Finally, start the timer.

Example 2 – What goes in the Event Handler?¶

One of the more common things you will put within your TimerClick () function is to get the input value of named components in your user interface, and then do something with them.

function TimerClick ()

currentFaderValue = NamedControl.getValue("MyFader")

if currentFaderValue > .5 then

NamedControl.setValue("MyLED", 1)

end

end

Normally, you will never stop this type of Timer. It will simply go forever, checking the status of the UI and updating it. But you will often want to check if each UI element has actually changed, and only perform the processing if it has.

Example 3 - Stop it Now!¶

If you want the actions to only be performed a single time when the timer completes, simply add a Timer.Stop() to the end of your TimerClick() function:

function TimerClick ()

--Do lots of stuff one time after 10 seconds

MyTimer:Stop() --Stop the Timer.

end

MyTimer = Timer.New()

MyTimer.EventHandler = TimerClick

MyTimer:Start(10)

Example 4 - Multiple Timers - But you probably don’t want to do this¶

If you need multiple timers at different rates, you can simply create more than one timer.

function FastTimerClick ()

--Do stuff that needs to be done very often

end

function SlowTimerClick ()

--Do other stuff that can happen less regularly

end

FastTimer = Timer.New()

FastTimer.EventHandler = FastTimerClick

FastTimer:Start(.25) -- Calls EventHandler every .25s

SlowtTimer = Timer.New()

SlowTimer.EventHandler = SlowTimerClick

SlowTimer:Start(10) -- Calls EventHandler every 10s

This can alternately be handled with a single event handler.

function TimerClick (ID)

if ID == 1 then

--Do stuff for the fast timer

elseif ID == 2 then

--Do different stuff for the slow timer

end

end

FastTimer = Timer.New()

FastTimer.EventHandler = TimerClick

FastTimer:Start(.25) -- Calls EventHandler ever .25s

SlowtTimer = Timer.New()

SlowTimer.EventHandler = TimerClick

SlowTimer:Start(10) -- Calls EventHandler ever 10s

This is useful for updating some internal control processing at a fast rate, while polling and updating the UI at a slower rate.

But this isn’t the most efficient way to handle this need in most cases; instead, see the next example.

Example 5 - Multiple Timers - The Better Way!¶

A better way to handle the need for multiple timers than described in the example above, is to have a single fast timer with a multiplier counter limiting some of the work in the callback to occur less frequently.

timerMultiplier = 10

timerCounter = 0

function TimerClick ()

-- Do stuff every timer the timer occurs

timerCounter = timerCounter + 1

if timerCounter >= timerMultiplier then

--Do other stuff that can happen less regularly

timerCounter = 0 --Reset the timerCounter

end

end

MyTimer = Timer.New()

MyTimer.EventHandler = TimerClick

MyTimer:Start(.25)

This is more efficient using less processing and can be used as long as the slow timer is a multiple of the fast timer.

Example 6 - Minimum Timer Period - The Safe Way!¶

Note that since the Device.LocalUnit.TimerResolution was introduced in 9.0, it will not function in 8.x installations. To ensure backwards compatibility with publicly distributed IMs, it should be implemented as follows:

MyTimer = Timer.New() MyTimer.EventHandler = TimerClick minRate = 250

if (Device.LocalUnit.TimerResolution) then minRate = Device.LocalUnit.TimerResolution end

if (minRate < 100) then minRate = .1 else minRate = minRate / 1000 end

MyTimer:Start(minRate)