search

quiqueck / homebridge-daily-sensors

Daylight Sensor Plugin for Homebridge that provides a list of predefined (and customizable) sensors that trigger at certain sun positions.
MIT License
18 stars 2 forks source link

readme

homebridge-daily-sensors

This programable switch can be triggered based on userdefine rules related to time, daily events, calendar events, sun elevation or amount of ambient light. Each TriggerEvent can be randomized to make sure that the rules trigger at slightly different times each day.

Simple Configuration

The following configuration is based on the suns elevation (altitude) in London. If the sun rises above 3° the switch will be triggered (with a single press (<= active:true)). If the sun gets below 3° it triggers a double press

  "accessories": [{
      "accessory": "DailySensors",
      "name":"My new daily switch",
      "dayStartsActive":false,    
      "trigger":[{
            "active":true,
            "type":"altitude",
            "value":"0.03",
            "trigger":"both"
      }],
      "location":{
        "longitude":-0.118092,
        "latitude":51.509865
      }
  }]

How does it work?

The plugin calculates typical sun events as well as the suns elevation based on a given location. Each sensor has a given activation state at any given time of a day. Whenever the activation state changes, the Programmable switch is notified. If the state changes from off to on, a single press is sent. if it changes from on to off a double press is generated. The activation state is determined through an array of TriggerEvents.

All TriggerEvent are stored in the trigger:array config variable. Each TriggerEvent has the following basic properties:

The sensor receives a tick event in a certain interval (config variable tickTimer:seconds). At every tick, all TriggerEvents are evaluated in sequence and the state of the sensor is determined (active/deactive) like this:s

Evaluating the sensor at 11:00 PM yields the following sequence: The evaluation starts with the activation state set to false ("dayStartsActive":false). Now the first TriggerEvent is calculated. Since 11:00 AM (the current time) is larger than 10:00 AM (the "value":"10:00 AM" of the TriggerEvent), the event is triggered and sets the activation state to true. The second TriggerEvent does not trigger as its value (1:00 PM) is less than the current time. The resulting activation state for 11:00 PM is true.

Evaluating the same set of TriggerEvents at 2:00 PMgenerates a different activation state. As above, the evaluation starts with the activation state set to false. The first TriggerEvent will trigger as before and changes the activation state to true. However, the second TriggerEvent will also trigger and finally change the activation state back to false. Hence, the resulting activation state for 11:00 PM is true.

In this case the switch will be notified twice a day:

Calendar Connection

You can connect a caldav ready calendar (like iCloud, see https://community.openhab.org/t/solved-apple-icloud-caldav-connection/32510/6 to find the url, username and password to access an iCloud calendar) and use calendar events as triggers. The following config file will connect to the iCloud-calendar https://pxx-caldav.icloud.com/xxxxxx/calendars/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/ with the user name someone@me.com and the application password application-password:

  "accessories": [{
      "accessory": "DailySensors",
      "name":"TheDaily",
      "port":7755,
      "dayStartsActive":false,
      "calendar":{
        "url":"https://pxx-caldav.icloud.com/xxxxxx/calendars/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/",
        "username":"someone@me.com",
        "password":"application-password",
        "type":"caldav"
      },    
      "trigger":[{
        "active":true,
        "type":"calendar",
        "value":"^Urlaub$",
        "trigger":"both"        
      }],
      "location":{
        "longitude":-0.118092,
        "latitude":51.509865
      }
  }]

The activation state changes to true whenever an Event named Urlaub starts and to false whenever it ends.

Web Service

The plugin offers a very simple web interface to force trigger the switch, check and reset the state as well as visualize the activation state of the switch over the day. This is a helpfull tool when debuging a given sequence of TriggerEvents. If you specify a config variable port, a web server will be started and bound. The index page (see below) will display an overview of available Accesories.

Configuration

For example, when using the follwoing config

  "accessories": [{
      "accessory": "DailySensors",
      "name":"TheDaily",
      "port":7755,
      "dayStartsActive":false,    
      "trigger":[{
            "active":true,
            "type":"altitude",
            "value":"0.03",
            "trigger":"both"
      }],
      "location":{
        "longitude":-0.118092,
        "latitude":51.509865
      }
  }]

you may access the web interface through http://[homebridge-ip]:7755/thedaily/. Note that the lowercase name of the accessory is part of the URI. If your name contains non ASCII characters, you may want to specify the path for URL using the webPath variable. Having a config like this:

  "accessories": [{
      "accessory": "DailySensors",
      "name":"My very special Sensor Name",
      "webPath":"/thedaily/me",
      "port":7755,
      //...

will for example start the webservice on the base URL http://[homebridge-ip]:7755/thedaily/me/. Also note that you can have multiple DailySensors on the same port.

Index Page

To receive an overview of the available sensors on a given port you can open http://[homebridge-ip]:7755/. For a setup with tow configured accesories on the same port this will yield the following result:

The Main Index Screen

Visualize TriggerEvents

If you open the root resource of an accesory (http://[homebridge-ip]:7755/thedaily/) the system will display the activation state of the sensor over the course of the entire day as well as display the results of the Evaluation steps for every minute of the day.

The Activation Info Screen

Force a state change

If you access http://[homebridge-ip]:7755/thedaily/1 (or http://[homebridge-ip]:7755/thedaily/0) the switch is triggered with an on (off) event resulting in a single press (double press) notification. This locks the state of the switch to the given value until a activation state changes based on the defined rules.

Clear forced state

If you force a state change as described above, you can restore the normal operation of the switch using http://[homebridge-ip]:7755/thedaily/clear

Query state

You can also query the current state of the switch using http://[homebridge-ip]:7755/thedaily/state

Force reload

Some information is updated once a day (like calendar events). You can force a update of those events using http://[homebridge-ip]:7755/thedaily/reload.

Config Options

There are some additional config variables available:

Regional Holidays

When you want to addres holidays in your expressions, you need to configure the lecation where you want to look up the holidays. You need to at least specify a country, all other values are optional:

Advanced TriggerEvents

Each TriggerEvent can have additional settings that alter its behaviour.

Randomize

Some TriggerEvent-Types can be randomized using the random setting. When this value is non zero, it is used to alter the given TriggerEvent value every day. When using random in a time based trigger, you can specify the amount of minutes added (or subtracted) at max from the value every day. The following example will generate times from 6:50 am to 7:10 am:

    "trigger":[{
        "active":true,
        "type":"time",
        "value":"7:00 AM",
        "random":10
    }]

See the type descriptions below for additional information on the behaviour of random for every type.

Operations

The operation controls how the activation state of the triggered TriggerEvent is applied to the result of the previous TriggerEvent. The behaviour is configured using the op-value. We will use the following trigger sequence as an example in the descriptions below. 

    "dayStartsActive":false,    
    "trigger":[{
        "active":true,
        "type":"time",
        "value":"10:00 AM"
    }]

The following values are recognized:

Trigger Condition

By default an EventTrigger is triggered when the current value (like the current time) is greater than the specified value. Only a triggered event can alter the activation state. Using the trigger parameter, allows you to specify a different behaviour. The following values are possible:

Days Of Week

The daysOfWeek-value contains an array of weekdays (in the specified locale). The event can only trigger on days listed in this array. For example, the following TriggerEvent is only triggered on Weekends after 10:00 am.

    "trigger":[{
        "active":true,
        "type":"time",
        "value":"10:00 AM",
        "daysOfWeek":["sa", "so"]
    }]

Types

The following settings are available for the given TriggerEvent-Types.

Time
Altitude
Lux
Event
Calendar Event
Holiday

In order to use holiday triggers, you need to configure your Region. See Regional Holidays above for details. The event triggers when the current day is a holiday and the type of the holiday is found in the array passed as value-property. See date-holiday for more info on available holiday types.

Expression

This type allows you to write a logical expression to determinthe activation state. The underlying parser is Math.js with a few custom extensions to handle some time and calendar based events.