Lightwave Link: Timers

# Timers

## Timers Introduction

A timer can be used to send a command from the WiFiLink at a predetermined time, with the option to repeat these throughout weeks or months. This is the key to automation.

An example is ‘Wake Up’. This can happen the same time of the day, on select days of the week.
Format

## Example command structure

!FiP"20130917101257"=!R2D5F1,T07:20,S17/04/14,E20/06/16,Dmtwtfxx,Mjfmamjjasond

Store timer “20130917101257” which will turn Room2 Device5 On at 7:20AM from the 17th April 2014 until 20th June 2016, Monday to Friday on every month of the year.

To alter the repeating days and months, you modify the relevant day/month to be an ‘x’ to prevent it from running, or have the day/months initial to have it running. Mjfmxxxjasond would result in the timer not running in April, May and June, for example.

!FiP”<TimerName>”=<Command>,T<Time>,S<StartDate>,E<EndDate>,D<DaysOfWeek>,M<MonthsOfYear>

The command and time are required, while all others are optional. If they are omitted, then it assumed that StartDate = today, EndDate = forever, DaysOfWeek = every day, MonthsOfYear = every month.

Where:

!FiP Store a time
TimerName Timer name. Must be unique
Command The action the timer should perform. Can be any room/device function or an Event
Time Time of the day the Timer should run at in a 24hr HH:MM format
StartDate The date when the timer should run from in a DD/MM/YY format
EndDate The date when the timer should be automatically deleted from the Link in a DD/MM/YY format
DaysOfWeek Which days the timer should run on. Should be in a mtwtfss format, with any day when the timer shouldn’t run at be replaced with an ‘x’
MonthsOfYear Which months the timer should run in. Should be in a jfmamjjasond format, with any month when the timer shouldn’t run at be replaced with an ‘x’

## All Timer Commands

Timer Commands
Store timer !FiP !FiP"20130917101257"=!R2D5F1,T07:20 (Create timer with ID 20130917101257 to turn Room2 Device5 On at 7.20AM every day)
Delete timer !FxP !FxP"20140429171955"|Deleting Timer (Delete timer with the ID 20140429171955)
Cancel ALL events and timers !FcP !FcP”*”
Delete ALL events and timers !FxP !FxP”*”

### Dusk/Dawn Timers

The WiFiLink can trigger timers to occur at variable times such as dusk and dawn. To do this, the timer must be stored with a start time of:

Dawn & Earlier
96:00 Dawn Exactly
96:01 30 mins before dawn
96:02 60 mins before dawn
96:03 90 mins before dawn
96:04 120 mins before dawn
Dawn & Later
97:00 Dawn Exactly
97:01 30 mins after dawn
97:02 60 mins after dawn
97:03 90 mins after dawn
97:04 120 mins after dawn
Dusk & Earlier
98:00 Dusk Exactly
98:01 30 mins before dusk
98:02 60 mins before dusk
98:03 90 mins before dusk
98:04 120 mins before dusk
Dusk & Later
99:00 Dusk Exactly
99:01 30 mins after dusk
99:02 60 mins after dusk
99:03 90 mins after dusk
99:04 120 mins after dusk

Note:

• Moods and All Off commands can be used as the action for a timer.
• The timer name cannot be more than 16 characters.
• The timer name must only contain alphanumeric characters.
• Events and timers use the same memory and so should not have the same name.
• The WiFiLink can store 32 timers in its memory.

## JSON Outputs (Timers)

In recent versions of the Lightwave Link and WiFiLink (2.92 onwards) there have been the introduction of JSON packets in response to almost all commands. When the Link receives the commands above, it will send an OK response initially (described in Example Interactions) and then a second packet containing information on what it has done with the Timer (i.e. create, edit or delete).

It is also possible for the Link to be interrogated for details on the Timers it has stored in its memory.

The format for adding, editing and deleting Timers is:

*!{
"trans":36387,
"mac":"03:45:67",
"time":1420070400,
"pkt":"timer",
"fn":"create",
"name":"T1234567890",
"mod":1462462829
}

where:

Name Value(s) Description
trans 1-4294967295 Transaction number of the JSON packet. Increments every transaction
mac XX:XX:XX Last 6 octets of Links MAC Address
time 1420070400 Timestamp of the transaction in a local UNIX time (i.e if Link is set to UTC+2, this time will be UNIX + (3600*2)
pkt timer This JSON packet output relates to Events
fn create A Timer has been created
edit A Time has been edited
delete A Timer has been deleted
name T1234567890 The ID of the stored Timer
mod 1420070400 The last time the Timer was modified in a local UNIX time (i.e if Link is set to UTC+2, this time will be UNIX + (3600*2)

### Reading Timers

Additionally, it is also possible to obtain the current status of Timers in the Link to understand how many are currently stored, and what the IDs of them are, and what the timer is set to do.

The Timers are stored in an internal table of 32 Timers, and you can interrogate which rows in the table have been used by sending the command @T. The Link will then respond with:

*!{
"trans":36409,
"mac":"XX:XX:XX",
"time":1420070400,
"pkt":"timer",
"fn":"summary",
"stat0":7,
"stat1":0,
"stat2":0,
"stat3":0
}

where the first four values are the same, and the following are:

Name Value(s) Description
fn summary This packet is a summary of the Timer details
stat0 255 Convert this to binary to find out which slots are in use for slots 1-8
stat1 255 Convert this to binary to find out which slots are in use for slots 9-16
stat2 255 Convert this to binary to find out which slots are in use for slots 17-24
stat3 255 Convert this to binary to find out which slots are in use for slots 25-32

To identify which slots are used, you will need to turn the value in statX to a binary format, with the least significant bit (LSB) being the value at the right.

Examples:
stat0 - 00000001 would indicate that the only timer slot in use between 1-8 would be in slot 1.
stat0 - 00000011 would indicate that the timer slots in use between 1-8 are in slots 1 & 2.
stat0 - 00000100 would indicate that the only timer slot in use between 1-8 would be in slot 3.
stat1 - 00000001 would indicate that the only timer slot in use between 9-16 would be in slot 9.
stat2 - 00000011 would indicate that the timer slots in use between 17-24 are in slots 17 & 18.
stat3 - 10000001 would indicate that the timer slots in use between 25-32 are in slots 25 & 32.

For example, if the value is 21, then this converts to binary of 00010101, In the case of this, the slots in use are 1, 3 and 5.

With this information, it is then possible to check the information of the Timers in each slot by sending @?T_ where _ is the number of slot you’d like to check. @?T1, @?T2, @?T3@?T32, for example. The Link will then respond with:

*!{
"trans":160,
"mac":"XX:XX:XX",
"time":1420070400,
"pkt":"timer",
"fn":"read",
"slot":8
"name":"T48768",
"clock":21600,       //Only if timer is a set time
"dusk":0,            //Only if timer is dusk timer
"dawn":0,            //Only if timer is dawn timer
"start":1455667200,
"end":4294967295,
"wk":31,
"mth":2051,
"mod":1420070400,
"cmd":"!R1D1F0"
}

where:

Name Value(s) Description
trans 1-4294967295 Transaction number of the JSON packet. Increments every transaction
mac XX:XX:XX Last 6 octets of Links MAC Address
time 1420070400 Timestamp of the transaction in a local UNIX time (i.e if Link is set to UTC+2, this time will be UNIX + (3600*2)
pkt timer This JSON packet output relates to Timers
fn read The Timer is being read
slot 1-32 The timer slot that is being used in the Links memory
name T48768 The ID of the Timer. Will be unique to the Link
clock 86399 Not in every packet The time that timer will execute at, in seconds past midnight of the Links local time. i.e. 3600 will be 1AM, 41400 will be 11:30AM.
dusk -4 to 4 Not in every packet The timer will execute at dusk. The value of this field indicates if it is set to run at dusk, or however many 30min increments before/after dusk. -4 indicates 2hrs before dusk. 1 indicates 30mins after dusk. 0 indicates dusk exactly
dawn -4 to 4 Not in every packet The timer will execute at dawn. The value of this field indicates if it is set to run at dawn, or however many 30min increments before/after dawn. -2 indicates 1hr before dawn. 3 indicates 1hr30mins after dawn. 0 indicates dawn exactly
start 1420070400 The timestamp from when the timer will begin to run at (i.e. Start date)
end 1500070400 The timestamp from when the timer will stop running at (i.e End date)
wk 0 to 127 Convert this to binary to find out which slots are in use for days 1-7. 58 would be 0111010. This would imply Mon = 0, Tue = 1, Wed = 0, Thu = 1, Fri = 1, Sat = 1, Sun = 1
mth 0 to 4095 Convert this to binary to find out which slots are in use for months 1-12. 1988 would be 011111000100. This would imply Jan = 0, Feb = 0, Mar = 1, Apr = 0, May = 0, Jun = 0, Jul = 1, Aug = 1, Sep = 1, Oct = 1, Nov = 1, Dec = 0
mod 1420070400 The last time the Timer was modified. The client may have a record of the Timer, but it may have been modified on the Link via another client more recently
cmd !R1D1F0 The command that the timer will send out when it is scheduled to run

If you check a slot which has no Timer stored in it using @?T_, then the Link will then respond with:

123,ERR,5,"Slot is empty"

for example:

## Running a Timer

When a timer runs by itself, it will output a packet which can alert a client that it has ran:

*!{
"trans":36387,
"mac":"03:45:67",
"time":1420070400,
"pkt":"timer",
"fn":"trigger",
"name":"T001"
}

The outputs are mostly the same as a timer create, read or delete, but the fn is simply trigger to alert the client that the timer has triggered, together with the name of the timer.

Last updated 29/12/16