Fork me on GitHub

pimatic-sunrise by Oliver Schneider | github | npm

pimatic sunrise Plugin

Events for sunrise, sunset and more.

{
  "plugin": "sunrise",
  "latitude": 37.371794,
  "longitude": -122.03476
}

The Plugin uses suncalc. The following events are supported:

  • sunrise: sunrise (top edge of the sun appears on the horizon)
  • sunriseEnd: sunrise ends (bottom edge of the sun touches the horizon)
  • goldenHourEnd: morning golden hour (soft light, best time for photography) ends
  • solarNoon: solar noon (sun is in the highest position)
  • goldenHour: evening golden hour starts
  • sunsetStart: sunset starts (bottom edge of the sun touches the horizon)
  • sunset: sunset (sun disappears below the horizon, evening civil twilight starts)
  • dusk: dusk (evening nautical twilight starts)
  • nauticalDusk: nautical dusk (evening astronomical twilight starts)
  • night: night starts (dark enough for astronomical observations)
  • nightEnd: night ends (morning astronomical twilight starts)
  • nauticalDawn: nautical dawn (morning nautical twilight starts)
  • dawn: dawn (morning nautical twilight ends, morning civil twilight starts)
  • nadir: nadir (darkest moment of the night, sun is in the lowest position)

Note: night and nightEnd have been deprecated as these events yield invalid results for several locations due to a bug in the underlying suncalc package. The night starts and night ends predicates are also affected.

Device Configuration

Optionally, you can setup a SunriseDevice to get sunlight times displayed for a given location. If no location is provided with the device configuration the location given with the plugin configuration applies. The attributes property is used to define which sunlight-related attributes shall be exposed by the device. The name given for an attribute is one of the sunlight event names listed above.

If a label text is set for an attribute the text will be used as an acronym for the attribute on display. Otherwise, the acronym will be constructed from the event name. If the label text is an empty string no acronym will be displayed.

If you wish to obtain the times in the timezone of the location at the given coordinates you can additionally set the timezone property. This will transform the times to the given timezone and will cut off the timezone offsets before converting the resulting times to the localized time string. For a list of valid "TZ" timezone strings, see Wikipedia - List of Timezones.

If the timezone property is absent or the property is set to an empty string no transformation will be performed. Additionally, it is possible to set a utcOffset offset time in hours relative to the timezone. This is useful for example if you wish to neglect daylight savings, i.e. you can set the timezoneto UTC and provide the required utcOffset value.

Note, by default, all times will be given in the local time zone of the system on which pimatic is installed. If you wish to use a different timezone, e.g. universal time to neglect daylight savings, you can set the localTimezone and localUtcOffset properties. However, these properties are only applicable if the timezone property has been set.

{
      "id": "sunrise-1",
      "class": "SunriseDevice",
      "name": "Sunrise",
      "latitude": 52.5072111,
      "longitude": 13.1449592,
      "attributes": [
        {
          "name": "sunrise",
          "label": "Sunrise Time"
        },
        {
          "name": "sunset",
          "label": "Sunset Time"
        }
      ]
}

Plugin Config Options

sunrise config
OptionDescriptionDefault
latitude
number
latitude
37.371794
longitude
number
longitude
-122.03476

Device Config Options

pimatic-sunrise device config schemas

SunriseDevice

Sunrise Device
OptionDescriptionDefault
latitude
number
Latitude, if omitted the latitude given set as part of the plugin configuration applies
longitude
number
Longitude, if omitted the latitude given set as part of the plugin configuration applies
localTimezone
string
The local time zone to be applied. If empty the timezone derived from the system will be used
""
localUtcOffset
number
Local timezone offset to be added localTimezone. Useful if target timezone is UTC
0
timezone
string
The target timezone to which the times shall be transformed. No transformation if empty
""
utcOffset
number
Target timezone offset to be added timezone. Useful if timezone is UTC
0
attributes
array of objects
Attributes which shall be exposed by the device
[
  {
    "name": "sunrise",
    "label": "Sunrise"
  },
  {
    "name": "sunset",
    "label": "Sunset"
  }
]
Elements
pimatic-sunrise is written by Oliver Schneider