public/openhab-addons
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Documentation] Markdown improvements for bindings a to e (#13859)

Browse Source 
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
This commit is contained in:
Jerome Luckenbach
2022-12-07 21:09:32 +01:00
committed by GitHub
parent 72efc1cfed
commit caf71f72e6
86 changed files with 1740 additions and 1822 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
bundles/org.openhab.binding.astro/README.md
View File

@@ -1,9 +1,9 @@
# Astro Binding
The Astro binding is used for calculating
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
- many DateTime and positional values for sun and moon.
- Radiation levels (direct, diffuse and total) of the sun during the day
## Supported Things
@@ -21,7 +21,7 @@ No binding configuration required.
## Thing Configuration
All Things require the parameter `geolocation` (as `<latitude>,<longitude>[,<altitude in m>]`) for which the calculation is done.
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.
@@ -30,88 +30,88 @@ This is done by setting `useMeteorologicalSeason` to true in the advanced settin
## 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)
- **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`
- **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
@@ -134,14 +134,14 @@ sunset is 22:10 but `latest` is set to 20:00 so the event/datetime value is move
Things:
```
```java
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
```
```java
astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] {
Channels:
Type rangeEvent : rise#event [
@@ -153,7 +153,7 @@ astro:moon:home [ geolocation="52.5200066,13.4049540", interval=60 ]
or a datetime offset
```
```java
astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] {
Channels:
Type start : rise#start [
@@ -167,7 +167,7 @@ astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] {
or an offset and latest
```
```java
astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] {
Channels:
Type rangeEvent : rise#event [
@@ -179,7 +179,7 @@ astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] {
Items:
```
```java
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" }
@@ -192,7 +192,7 @@ Number:Intensity Diffuse_Radiation "Diffuse Radiation [%.2f %unit%]" {
Events:
```
```java
rule "example trigger rule"
when
Channel 'astro:sun:home:rise#event' triggered START
@@ -207,7 +207,7 @@ Multiple actions are supported by this binding. In classic rules these are acces
Getting sunActions variable in scripts
```
```java
val sunActions = getActions("astro","astro:sun:local")
if(null === sunActions) {
logInfo("actions", "sunActions not found, check thing ID")
@@ -222,15 +222,15 @@ Getting sunActions variable in scripts
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.
- `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.
- `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.
- `moment` (String), values: `START, END` - defaulted to `START` if null.
Example :
```
```java
val sunEvent = "SUN_SET"
val today = ZonedDateTime.now;
val sunEventTime = sunActions.getEventTime(sunEvent,today,"START")
@@ -242,25 +242,23 @@ Example :
Retrieves the elevation (QuantityType<Angle>) of the sun at the requested instant.
Thing method applies to Sun and Moon.
* `timeStamp` (ZonedDateTime) - defaulted to now() if null.
- `timeStamp` (ZonedDateTime) - defaulted to now() if null.
### getAzimuth(timeStamp)
Retrieves the azimuth (QuantityType<Angle>) of the sun at the requested instant.
Thing method applies to Sun and Moon.
* `timeStamp` (ZonedDateTime) - defaulted to now() if null.
- `timeStamp` (ZonedDateTime) - defaulted to now() if null.
Example :
```
```java
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.