### Sidebar

time_math_tutorial

This is an old revision of the document!

## Time math

### Introduction

Creating rules for pilight eventing based on time can be a tedious job and such rules can be difficult to debug. For that reason a few new operators, an extended datetime protocol and an extended switch action have been created.

### Compatibility

The new operators, the extended datetime protocol and the extended switch action are ONLY compatible with the manually installed nightly of pilight version 6.0. Both the source code and the installation procedure are based on the new pilight library structure. Compiling against a pilight version with the old library structure will fail.

You are strongly advised to install the most recent pilight nightly version before the installation of the time math modules. With older pilight versions they may give errors or unpredictable results.

For instructions on how to install pilight manually please look here.

### Protocol and operators

The new operators are plustime (+t), minustime (-t) and random (~). The extended datetime protocol provides, as an additional item, the time in hh.mm format (like in the sunriseset protocol). The extended switch action offers the posssibility to switch a device for a random duration.

With these modules you can create very simple rules to switch devices depending on the time of the day or sunrise- or sunset time.

### Usage

#### Plustime and minustime

The plustime operator adds any number of minutes to a given time and the minustime operator subtracts any number of minutes from a given time.

Examples:

 IF datetime.time == sunriseset.sunset THEN … performs action at sunset IF datetime.time == sunriseset.sunset +t 90 THEN… performs action 90 minutes (1½ hours) after sunset IF datetime.time == sunriseset.sunrise -t 180 THEN … performs action 180 minutes (3 hours) before sunrise

#### Random

With the random operator you can make things happen at a different time each day.

The general format of the random operator is “low limit ~ high limit”, but by adding two decimals to “high limit” the resulting value can be made unique.
So, if the same value is desired, add the same decimals (as with 0 ~ 90.01 shown in the examples below), but if you want a new random value, add different decimals (as with 10 ~30.02 in the second example below). Only the integer part of the high limit is used as the actual high limit.

Examples:

 IF datetime.time == 23.00 +t (0 ~ 90.01) THEN … performs action daily between 23.00 and 00.30 IF datetime.time == 23.00 +t (0 ~ 90.01) +t (10 ~ 30.02) THEN … performs action 10 to 30 minutes after the action above

#### switch action

With the extended switch action you make a device swith on or off for a random duration. In addition you can set the unit size.

Examples:

 IF … THEN switch DEVICE … TO on FOR 1 ~ 10 switches the device on for a period of between 1 and 10 seconds IF … THEN switch DEVICE … TO on FOR 1 ~ 10 UNIT 60 switches the device on for a period of between 1 and 10 minutes IF … THEN switch DEVICE … TO on FOR 1 ~ 10 UNIT 3600 switches the device on for a period of between 1 and 10 hours

These operators, this protocol and this action aren't part of pilight (yet). But don't worry, you can simply add them yourself as modules. This is how.

### Installation

Log on as superuser and cd to your pilight folder:

```pi@raspi2 ~ \$ sudo su
root@raspi2:/home/pi/# cd pilight```

Stop the pilight service:

`root@raspi2:/home/pi/pilight# service pilight stop`

`root@raspi2:/home/pi/pilight# git clone --depth 5 -b master https://github.com/niekd/pilight-time-stuff.git`

This will create a folder called pilight-time-stuff in your pilight folder with two subfolders: operators and protocols.

Copy all files from these folders to the corresponding pilight folders:

```root@raspi2:/home/pi/pilight# cp pilight-time-stuff/operators/*.* libs/pilight/events/operators/
root@raspi2:/home/pi/pilight# cp pilight-time-stuff/protocols/*.* libs/pilight/protocols/
root@raspi2:/home/pi/pilight# cp pilight-time-stuff/actions/*.* libs/pilight/events/actions/```

Then compile the sources to create the modules (.so files).

```root@raspi2:/home/pi/pilight# gcc -fPIC -shared libs/pilight/events/operators/plustime.c -Ilibs/pilight/events -Iinc -o plustime.so -DMODULE=1
root@raspi2:/home/pi/pilight# gcc -fPIC -shared libs/pilight/events/operators/minustime.c -Ilibs/pilight/events -Iinc -o minustime.so -DMODULE=1
root@raspi2:/home/pi/pilight# gcc -fPIC -shared libs/pilight/events/operators/random.c -Ilibs/pilight/events -Iinc -o random.so -DMODULE=1
root@raspi2:/home/pi/pilight# gcc -fPIC -shared libs/pilight/protocols/newdatetime.c -Ilibs/pilight/protocols -Iinc -o newdatetime.so -DMODULE=1
root@raspi2:/home/pi/pilight# gcc -fPIC -shared libs/pilight/events/actions/switch-rnd.c -Ilibs/pilight/events -Iinc -o switch-rnd.so -DMODULE=1```

Next copy all the .so files you have just created to the appropriate subfolders of /usr/local/lib/pilight:

```root@raspi2:/home/pi/pilight# cp plustime.so minustime.so random.so /usr/local/lib/pilight/operators/
root@raspi2:/home/pi/pilight# cp newdatetime.so /usr/local/lib/pilight/protocols/
root@raspi2:/home/pi/pilight# cp switch-rnd.so /usr/local/lib/pilight/actions/```

### Configuration

Edit the configuration of your datetime device by changing the protocol from “datetime” to “newdatetime” and adding the “time” property to match with the newdatetime protocol, so it looks someting like this:

```                "datetime": {
"protocol": [ "newdatetime" ],
"id": [{
"longitude": 4.6,
"latitude": 52.3,
}],
"year": 2015,
"month": 1,
"day": 31,
"weekday": 7,
"hour": 20,
"minute": 4,
"second": 48,
"time": 20.04
},```

Now you can start pilight and the new operators and protocol will be loaded and can be used in your rules.

Note: After installation, the pilight-time-stuff folder and its contents are not required anymore and may be deleted.

Have fun!