FHEM module with a collection of various routines for astronomical data
Define
define <name> Astro [global]
Defines the Astro device (only one is needed per FHEM installation).
Optional parameter 'global' will mark this device for global configuration options, see SUNRISE_EL compatibility mode below for details.
Readings with prefix Sun refer to the sun, with prefix Moon refer to the moon.
The suffixes for these readings are:
- Age = angle (in degrees) of body along its track
- Az,Alt = azimuth and altitude angle (in degrees) of body above horizon
- Dec,Ra = declination (in degrees) and right ascension (in HH:MM) of body position
- HrsVisible,HrsInvisible = Hours of visiblity and invisiblity of the body
- Lat,Lon = latitude and longituds (in degrees) of body position
- Diameter = virtual diameter (in arc minutes) of body
- Distance,DistanceObserver = distance (in km) of body to center of earth or to observer
- PhaseN,PhaseS = Numerical and string value for phase of body
- Sign,SignN = Circadian sign for body along its track
- Rise,Transit,Set = times (in HH:MM) for rise and set as well as for highest position of body
Readings with prefix Obs refer to the observer.
In addition to some of the suffixes gives above, the following may occur:
- Date,Dayofyear = date
- JD = Julian date
- Time,Timezone,TimezoneS = obvious meaning
- IsDST = 1 if running on daylight savings time, 0 otherwise
- GMST,LMST = Greenwich and Local Mean Sidereal Time (in HH:MM)
An SVG image of the current moon phase may be obtained under the link
<ip address of fhem>/fhem/Astro_moonwidget?name='<device name>'.
Optional web parameters are [&size='<width>x<height>'][&mooncolor=<color>][&moonshadow=<color>]
Notes:
- Calculations are only valid between the years 1900 and 2100
- Attention: Timezone is taken from the local Perl settings, NOT automatically defined for a location
- This module uses the global attribute
language to determine its output data
(default: EN=english). For German output, set attr global language DE.
If a local attribute on the device was set for language it will take precedence.
- The time zone is determined automatically from the local settings of the
operating system. If geocordinates from a different time zone are used, the results are
not corrected automatically.
- Some definitions determining the observer position are used
from the global device, i.e.
attr global longitude <value>
attr global latitude <value>
attr global altitude <value> (in m above sea level)
These definitions are only used when there are no corresponding local attribute settings on the device.
-
It is not necessary to define an Astro device to use the data provided by this module.
To use its data in any other module, you just need to put LoadModule("Astro");
at the start of your own code, and then may call, for example, the function
Astro_Get( SOME_HASH_REFERENCE,"dummy","text", "SunRise","2019-12-24");
to acquire the sunrise on Christmas Eve 2019. The hash reference may also be undefined or an existing device name of any type. Note that device attributes of the respective device will be respected as long as their name matches those mentioned for an Astro device.
attribute=value pairs may be added in text format to enforce
settings like language that would otherwise be defined by a real device.
You may also add parameters to customize your request:
Astro_Get( SOME_HASH_REFERENCE, ["dummy","text"], {html=>1} );
Astro_Get( SOME_HASH_REFERENCE, ["dummy","text","SunRise,SunSet,SunAz,SunDistanceObserver"], {html=>1, long=>2} );
- Functions that can replace those from SUNRISE_EL are available under the same name and adding a as a prefix in front of it (for example, use
asunrise() instead of sunrise()). A single Astro device can act as a global configuration device for such functions if it was created using the global define parameter. If you don't want to create any Astro device at all, you may put LoadModule("Astro"); into your 99_myUtils.pm to only load the SUNRISE_EL replacement functions.
Set
-
set <name> update
trigger to recompute values immediately.
Get
Attention: Get-calls are NOT written into the readings of the device. Readings change only through periodic updates.
-
get <name> json [<reading>,[<reading>]] [-1|yesterday|+1|tomorrow]
get <name> json [<reading>,[<reading>]] MM-DD [-1|yesterday|+1|tomorrow]
get <name> json [<reading>,[<reading>]] YYYY-MM-DD [-1|yesterday|+1|tomorrow]
get <name> json [<reading>,[<reading>]] HH:MM[:SS] [-1|yesterday|+1|tomorrow]
get <name> json [<reading>,[<reading>]] YYYY-MM-DD HH:MM[:SS] [-1|yesterday|+1|tomorrow]
returns the complete set of an individual reading of astronomical data either for the current time, or for a day and time given in the argument. yesterday, tomorrow or any other integer number may be given at the end to get data relative to the given day and time.
Formatted values as described below may be generated in a subtree text by adding text=1 to the request.
-
get <name> text [<reading>,[<reading>]] [-1|yesterday|+1|tomorrow]
get <name> text [<reading>,[<reading>]] MM-DD [-1|yesterday|+1|tomorrow]
get <name> text [<reading>,[<reading>]] YYYY-MM-DD [-1|yesterday|+1|tomorrow]
get <name> text [<reading>,[<reading>]] HH:MM[:SS] [-1|yesterday|+1|tomorrow]
get <name> text [<reading>,[<reading>]] YYYY-MM-DD HH:MM[:SS] [-1|yesterday|+1|tomorrow]
returns the complete set of an individual reading of astronomical data either for the current time, or for a day and time given in the argument. yesterday, tomorrow or any other integer number may be given at the end to get data relative to the given day and time.
The return value may be formatted and/or labeled by adding one or more of the following key=value pairs to the request:
- unit=1 = Will add a unit to numerical values. Depending on attribute lc_numeric, the decimal separator will be in regional format as well.
- long=1 = A describtive label will be added to the value.
- long=2 = Same as long=1 but the label will be separated from the value by a colon.
- long=3 = Same as long=2 but Sun or Moon will be added as a prefix.
- long=4 = Same as long=3 but the separator will be used to separate Sun/Moon instead.
-
get <name> version
Display the version of the module
Attributes
-
<interval>
Update interval in seconds. The default is 3600 seconds, a value of 0 disables the periodic update.
-
<language>
A language may be set to overwrite global attribute settings.
-
<lc_numeric>
Set regional settings to format numerical values in textual output. If not set, it will generate the locale based on the attribute language (if set).
-
<lc_time>
Set regional settings to format time related values in textual output. If not set, it will generate the locale based on the attribute language (if set).
-
<recomputeAt>
Enforce recomputing values at specific event times, independant from update interval. This attribute contains a list of one or many of the following values:
- MoonRise,MoonSet,MoonTransit = for moon rise, set, and transit
- NewDay = for 00:00:00 hours of the next calendar day
- SunRise,SunSet,SunTransit = for sun rise, set, and transit
- *TwilightEvening,*TwilightMorning = for the respective twilight stage begin
-
<timezone>
A timezone may be set to overwrite global and system settings. Format may depend on your local system implementation but is likely in the format similar to Europe/Berlin.
- Some definitions determining the observer position:
attr <name> longitude <value>
attr <name> latitude <value>
attr <name> altitude <value> (in m above sea level)
attr <name> horizon <value> custom horizon angle in degrees, default 0. Different values for morning/evening may be set as <morning>:<evening>
These definitions take precedence over global attribute settings.
-
<disable>
When set, this will completely disable any device update.
- Standard attributes alias, comment, event-on-update-reading, event-on-change-reading, room, eventMap, loglevel,
webCmd
=end html
=begin html_DE