openHAB

This page is part of archived documentation for openHAB 3.4. Go to the current stable version

# Astro Binding

The Astro binding is used for calculating

  • many DateTime and positional values for sun and moon.
  • Radiation levels (direct, diffuse and total) of the sun during the day

# Supported Things

This binding supports two Things: Sun and Moon

# Discovery

If a system location is set, "Local Sun" and a "Local Moon" will be automatically discovered for this location.

If the system location is changed, the background discovery updates the configuration of "Local Sun" and "Local Moon" automatically.

# Binding Configuration

No binding configuration required.

# Thing Configuration

All Things require the parameter geolocation (as <latitude>,<longitude>[,<altitude in m>]) for which the calculation is done. The altitude segment is optional and sharpens results provided by the Radiation group. Optionally, a refresh interval (in seconds) can be defined to also calculate positional data like azimuth and elevation.

Season calculation can be switched from equinox based calculation to meteorological based (starting on the first day of the given month). This is done by setting useMeteorologicalSeason to true in the advanced setting of the sun.

# Channels

  • thing sun
    • group rise, set, noon, night, morningNight, astroDawn, nauticDawn, civilDawn, astroDusk, nauticDusk, civilDusk, eveningNight, daylight
      • channel
        • start, end (DateTime)
        • duration (Number:Time)
    • group position
      • channel
        • azimuth, elevation (Number:Angle)
        • shadeLength (Number)
    • group radiation
      • channel
        • direct, diffuse, total (Number:Intensity)
    • group zodiac
      • channel
        • start, end (DateTime)
        • sign (String), values: ARIES, TAURUS, GEMINI, CANCER, LEO, VIRGO, LIBRA, SCORPIO, SAGITTARIUS, CAPRICORN, AQUARIUS, PISCES
    • group season
      • channel:
        • spring, summer, autumn, winter (DateTime)
        • name,nextName (String), values SPRING, SUMMER, AUTUMN, WINTER
        • timeLeft (Number:Time)
    • group eclipse
      • channel:
        • total, partial, ring (DateTime)
        • totalElevation, partialElevation, ringElevation (Number:Angle)
    • group phase
      • channel
        • name (String), values: SUN_RISE, ASTRO_DAWN, NAUTIC_DAWN, CIVIL_DAWN, CIVIL_DUSK, NAUTIC_DUSK, ASTRO_DUSK, SUN_SET, DAYLIGHT, NIGHT
  • thing moon
    • group rise, set
      • channel
        • start, end (DateTime)
    • group phase
      • channel:
        • firstQuarter, thirdQuarter, full, new (DateTime)
        • age (Number:Time)
        • ageDegree (Number:Angle)
        • agePercent, illumination (Number:Dimensionless)
        • name (String), values: NEW, WAXING_CRESCENT, FIRST_QUARTER, WAXING_GIBBOUS, FULL, WANING_GIBBOUS, THIRD_QUARTER, WANING_CRESCENT
    • group eclipse
      • channel:
        • total, partial (DateTime)
        • totalElevation, partialElevation (Number:Angle)
    • group distance
      • channel:
        • date (DateTime)
        • distance (Number:Length)
    • group perigee
      • channel:
        • date (DateTime),
        • distance (Number:Length)
    • group apogee
      • channel:
        • date (DateTime)
        • distance (Number:Length)
    • group zodiac
      • channel
        • sign (String), values: ARIES, TAURUS, GEMINI, CANCER, LEO, VIRGO, LIBRA, SCORPIO, SAGITTARIUS, CAPRICORN, AQUARIUS, PISCES
    • group position
      • channel
        • azimuth, elevation (Number:Angle)

# Trigger Channels

  • thing sun
    • group rise, set, noon, night, morningNight, astroDawn, nauticDawn, civilDawn, astroDusk, nauticDusk, civilDusk, eveningNight, daylight
      • event START, END
    • group eclipse
      • event: TOTAL, PARTIAL, RING
  • thing moon
    • group rise
      • event START
    • group set
      • event END
    • group phase
      • event: FIRST_QUARTER, THIRD_QUARTER, FULL, NEW
    • group eclipse
      • event: TOTAL, PARTIAL
    • group perigee
      • event: PERIGEE
    • group apogee
      • event: APOGEE

# Channel config

Offsets: For each event group you can optionally configure an offset in minutes. The offset must be configured in the channel properties for the corresponding thing.

The minimum allowed offset is -1440 and the maximum allowed offset is 1440.

Earliest/Latest: For each trigger channel and start, end datetime value, you can optionally configure the earliest and latest time of the day.

e.g sun#set earliest=18:00, latest=20:00

sunset is 17:40, but earliest is set to 18:00 so the event/datetime value is moved to 18:00.

OR

sunset is 22:10 but latest is set to 20:00 so the event/datetime value is moved 20:00.

# Full Example

Things:

astro:sun:home  [ geolocation="52.5200066,13.4049540,100", interval=60 ]
astro:moon:home [ geolocation="52.5200066,13.4049540", interval=60 ]

or optionally with an event offset

astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] {
    Channels:
        Type rangeEvent : rise#event [
            offset=-30
        ]
}
astro:moon:home [ geolocation="52.5200066,13.4049540", interval=60 ]

or a datetime offset

astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] {
    Channels:
        Type start : rise#start [
            offset=5
        ]
        Type end : rise#end [
            offset=5
        ]
}

or an offset and latest

astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] {
    Channels:
        Type rangeEvent : rise#event [
            offset=-10,
            latest="08:00"
        ]
}

Items:

DateTime         Sunrise_Time       "Sunrise [%1$tH:%1$tM]"                   { channel="astro:sun:home:rise#start" }
DateTime         Sunset_Time        "Sunset [%1$tH:%1$tM]"                    { channel="astro:sun:home:set#start" }
Number:Angle     Azimuth            "Azimuth"                                 { channel="astro:sun:home:position#azimuth" }
Number:Angle     Elevation          "Elevation"                               { channel="astro:sun:home:position#elevation" }
String           MoonPhase          "MoonPhase"                               { channel="astro:moon:home:phase#name" }
Number:Length    MoonDistance       "MoonDistance [%.1f %unit%]"              { channel="astro:moon:home:distance#distance" }
Number:Intensity Total_Radiation    "Radiation [%.2f %unit%]"                 { channel="astro:sun:home:radiation#total" }
Number:Intensity Diffuse_Radiation  "Diffuse Radiation [%.2f %unit%]"         { channel="astro:sun:home:radiation#diffuse" }

Events:

rule "example trigger rule"
when
    Channel 'astro:sun:home:rise#event' triggered START
then
    ...
end

# Rule Actions

Multiple actions are supported by this binding. In classic rules these are accessible as shown in the example below:

Getting sunActions variable in scripts

 val sunActions = getActions("astro","astro:sun:local")
 if(null === sunActions) {
        logInfo("actions", "sunActions not found, check thing ID")
        return
 } else {
        // do something with sunActions
 }

# getEventTime(phaseName, date, moment)

Retrieves date and time (ZonedDateTime) of the requested phase name. Thing method only applies to Sun thing type.

  • phaseName (String), values: SUN_RISE, ASTRO_DAWN, NAUTIC_DAWN, CIVIL_DAWN, CIVIL_DUSK, NAUTIC_DUSK, ASTRO_DUSK, SUN_SET, DAYLIGHT, NIGHT. Mandatory.

  • date (ZonedDateTime), only the date part of this parameter will be considered - defaulted to now() if null.

  • moment (String), values: START, END - defaulted to START if null.

Example :

 val sunEvent = "SUN_SET"
 val today = ZonedDateTime.now;
 val sunEventTime = sunActions.getEventTime(sunEvent,today,"START")
 logInfo("AstroActions","{} will happen at : {}", sunEvent, sunEventTime.toString)

# getElevation(timeStamp)

Retrieves the elevation (QuantityType) of the sun at the requested instant. Thing method applies to Sun and Moon.

  • timeStamp (ZonedDateTime) - defaulted to now() if null.

# getAzimuth(timeStamp)

Retrieves the azimuth (QuantityType) of the sun at the requested instant. Thing method applies to Sun and Moon.

  • timeStamp (ZonedDateTime) - defaulted to now() if null.

Example :

 val azimuth = sunActions.getAzimuth(sunEventTime)
 val elevation = sunActions.getElevation(sunEventTime)
 logInfo("AstroActions", "{} will be positioned at elevation {} - azimuth {}",sunEvent, elevation.toString,azimuth.toString)

# Tips

Do not worry if for example the "astro dawn" is undefined at your location. The reason might be that you live in a northern country and it is summer, such that the sun is not 18 degrees below the horizon in the morning. For details see this Wikipedia article (opens new window). The "civil dawn" event might often be the better choice.

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← Atlona →