homebridge-weather-plus-with-pws-sync

v1.1.1

Published

2 years ago

A comprehensive weather plugin for homekit with current observations, forecasts and history.

Downloads

homebridge-weather-plus

This is a weather plugin for homebridge that features current observations, daily forecasts and history graphs for multiple locations and services. You can download it via npm.

Screenshots 2 and 3 are taken from the Elgato Eve app.

If you like this plugin and find it useful, I would be forever grateful for your support:

Feel free to leave any feedback here.

Features

Get 27 observation and forecast values for up to 7 days
Choose from 3 different weather services
Add multiple locations/services
See the weather history in the Eve App
See all values, translations and icons in the Eve App
See all values in the Home app with compatibility mode "Home"
Use all values in HomeKit rules with the Eve App
Configure everything easily with the homebridge config-ui-x

Choose your Weather Service

This plugin supports multiple weather services. Each has its own advantages. The following table shows a comparison to help you to choose one.

| | Dark Sky 1 | OpenWeatherMap (recommended) | Weather Underground 2 | |----------------------------|:--------------------------------------------:|:----------------------------------------------------------------:|:----------------------------------------------------------------:| | Current observation values | 19 | 15 | 12 | | Forecast values | 22 | 18 | 0 | | Forecast days | today + 7 | today + 7 | 0 | | Location | geo-coordinates | city name, city id, geo-coordinates | station id | | Personal weather stations | :x: | :heavy_check_mark: | :heavy_check_mark: | | Free | :heavy_check_mark: (only existing users) | :heavy_check_mark: | :heavy_check_mark: (only if you own a station) | | Register | closed | here | here |

You can add more services easily by forking the project and submitting a pull request for a new api file.

1 It is no longer possible to register as a new user for Dark Sky. Existing users can use the service until 31 Dec 2022.
2 You can use the weather underground service only if you can provide weather data from your own station in exchange.

Installation

Install homebridge using: npm install -g homebridge
Install this plugin using: npm install -g homebridge-weather-plus Note: The installation might take 5 minutes.
Gather an API key for a weather service from the register link in the table above
Configure via the plugin homebridge-config-ui-x or update your configuration file manually. See the explanations and samples below.

Observations and Forecasts

The following observation and forecast values can be displayed and used in HomeKit rules.
I recommend using the Eve app to see all the values. However, if you don't want to use a 3rd party app, use the compatibility mode home for displaying most values in the Apple home app.

Air Pressure
Cloud Cover
Condition
Condition Category 3, 4
Dew Point
Humidity
Ozone
Rain Currently
Rain Last Hour
Rain All Day
Rain Chance
Snow Currently
Solar Radiation
Sunrise Time
Sunset Time
Temperature
Temperature Min
Temperature Max
Temperature Apparent
UV-Index
Visibility
Wind Direction
Wind Speed
Wind Speed Maximum
Observation Time
Observation Station
Day of the forecast

3 Simple: clear (0), overcast (1), rain (2), snow (3)
4 Detailed: clear (0), few clouds (1), broken clouds (2), overcast (3), fog (4), drizzle (5), rain ( 6), hail (7), snow (8), severe weather (9)

Configuration

Below are example configurations for all weather apis.

Dark Sky

key
The API key that you get by registering for the Dark Sky service.

locationGeo
List with the latitude and longitude for your location (don't forget the square brackets). You can get your coordinates: here.

"platforms": [
{
"platform": "WeatherPlus",
"service": "darksky",
"key": "YOUR_API_KEY",
"locationGeo": [52.5200066, 13.404954]
}
]

OpenWeatherMap

key
The API key that you get by registering for the OpenWeather service.

locationId5
Numerical city id, can be found here.

locationCity5
City name and optional country code, can be found here.

locationGeo5
List with the latitude and longitude for your location (don't forget the square brackets). You can get your coordinates: here.

5 You need only one of these location options.

"platforms": [
{
"platform": "WeatherPlus",
"service": "openweathermap",
"key": "YOUR_API_KEY",
"locationId": 2950159,
"locationCity": "Berlin, DE",
"locationGeo": [52.5200066, 13.404954]
}
]

Weather Underground

Since March 2019 you need to register your own weather station with Weather Underground to get weather data in exchange. After you registered your weather device (here), you can use the API.

key
The API key that you get by registering for the Weather Underground service.

stationId
Your personal StationID.

"platforms": [
{
"platform": "WeatherPlus",
"service": "weatherunderground",
"key": "YOUR_API_KEY",
"stationId": "YOUR_STATION_ID"
}
]

Weewx

Weewx is an open source software for your weather station monitoring that can be found (here), to utilize this plugin you need to have the following extension that create a JSON input that can be found here. Once that is installed a JSON response needs to be created using the following template that creates a JSON file on your server which can be created by adding a new file called YOUR_FILE_NAME_HERE.json.tmpl. and adding it to the skin.conf file.

{
    "observations":[
    {
        "stationID": "$station.location",
        "softwareType": "weewx $station.version",
        "realtimeFrequency": "$current.interval",
        #if $current.radiation.has_data
        "solarRadiation": $current.radiation.raw,
        #end if
        #if $current.rain.raw > 0
        "rainbool": true,
        #else
        "rainbool": false,
        #end if
        "lon": $station.stn_info.longitude_f,
        "epoch": $current.dateTime.raw,
        "lat": $station.stn_info.latitude_f,
        #if $current.UV.has_data
        "uv": $current.UV,
        #end if
        #if $current.windDir.has_data
        "winddir": $current.windDir.raw,
        #end if
        #if $current.outHumidity.has_data
        "humidity": $current.outHumidity.raw,
        #end if
        #if $current.o3.has_data
        "o3": $current.o3.raw
        #end if
        "imperial": {
                        #if $current.outTemp.has_data
                        "temp": $current.outTemp.degree_F.raw,
                        #end if
                        #if $day.outTemp.has_data
                        "maxtemp": $day.outTemp.max.degree_F.raw,
                        "mintemp": $day.outTemp.min.degree_F.raw,
                        #end if
                        #if $current.appTemp.has_data
                        "apptemp": $current.appTemp.degree_F.raw,
                        #end if
                        #if $current.dewpoint.has_data
                        "dewpt": $current.dewpoint.degree_F.raw,
                        #end if
                        #if $current.windSpeed.has_data
                        "windSpeed": $current.windSpeed.mile_per_hour.raw,
                        #end if
                        #if $current.windGust.has_data
                        "windGust": $current.windGust.mile_per_hour.raw,
                        #end if
                        #if $current.barometer.has_data
                        "pressure": $current.barometer.inHg.raw,
                        #end if
                        #if $hour.rain.has_data
                        "precip1h": $hour($hours_ago=1).rain.sum.inch.raw,
                        #end if
                        #if $current.rainRate.has_data
                        "precipRate": $current.rainRate.inch_per_hour.raw,
                        #end if
                        #if $day.rain.has_data
                        "rainday": $day.rain.sum.inch.raw
                        #end if
        },
        "metric": {
                        #if $current.outTemp.has_data
                        "temp": $current.outTemp.degree_C.raw,
                        #end if
                        #if $day.outTemp.has_data
                        "maxtemp": $day.outTemp.max.degree_C.raw,
                        "mintemp": $day.outTemp.min.degree_C.raw,
                        #end if
                        #if $current.appTemp.has_data
                        "apptemp": $current.appTemp.degree_C.raw,
                        #end if
                        #if $current.dewpoint.has_data
                        "dewpt": $current.dewpoint.degree_C.raw,
                        #end if
                        #if $current.windSpeed.has_data
                        "windSpeed": $current.windSpeed.km_per_hour.raw,
                        #end if
                        #if $current.windGust.has_data
                        "windGust": $current.windGust.km_per_hour.raw,
                        #end if
                        #if $current.barometer.has_data
                        "pressure": $current.barometer.mbar.raw,
                        #end if
                        #if $hour.rain.has_data
                        "precip1h": $hour($hours_ago=1).rain.sum.mm.raw,
                        #end if
                        #if $current.rainRate.has_data
                        "precipRate": $current.rainRate.mm_per_hour.raw,
                        #end if
                        #if $day.rain.has_data
                        "rainday": $day.rain.sum.mm.raw
                        #end if
        },
        "metric_si": {
                        #if $current.outTemp.has_data
                        "temp": $current.outTemp.degree_C.raw,
                        #end if
                        #if $day.outTemp.has_data
                        "maxtemp": $day.outTemp.max.degree_C.raw,
                        "mintemp": $day.outTemp.min.degree_C.raw,
                        #end if
                        #if $current.appTemp.has_data
                        "apptemp": $current.appTemp.degree_C.raw,
                        #end if
                        #if $current.dewpoint.has_data
                        "dewpt": $current.dewpoint.degree_C.raw,
                        #end if
                        #if $current.windSpeed.has_data
                        "windSpeed": $current.windSpeed.meter_per_second.raw,
                        #end if
                        #if $current.windGust.has_data
                        "windGust": $current.windGust.meter_per_second.raw,
                        #end if
                        #if $current.barometer.has_data
                        "pressure": $current.barometer.mbar.raw,
                        #end if
                        #if $hour.rain.has_data
                        "precip1h": $hour($hours_ago=1).rain.sum.mm.raw,
                        #end if
                        #if $current.rainRate.has_data
                        "precipRate": $current.rainRate.mm_per_hour.raw,
                        #end if
                        #if $day.rain.has_data
                        "rainday": $day.rain.sum.mm.raw
                        #end if
        },
        "uk_hybrid": {
                        #if $current.outTemp.has_data
                        "temp": $current.outTemp.degree_C.raw,
                        #end if
                        #if $day.outTemp.has_data
                        "maxtemp": $day.outTemp.max.degree_C.raw,
                        "mintemp": $day.outTemp.min.degree_C.raw,
                        #end if
                        #if $current.appTemp.has_data
                        "apptemp": $current.appTemp.degree_C.raw,
                        #end if
                        #if $current.dewpoint.has_data
                        "dewpt": $current.dewpoint.degree_C.raw,
                        #end if
                        #if $current.windSpeed.has_data
                        "windSpeed": $current.windSpeed.mile_per_hour.raw,
                        #end if
                        #if $current.windGust.has_data
                        "windGust": $current.windGust.mile_per_hour.raw,
                        #end if
                        #if $current.barometer.has_data
                        "pressure": $current.barometer.mbar.raw,
                        #end if
                        #if $hour.rain.has_data
                        "precip1h": $hour($hours_ago=1).rain.sum.mm.raw,
                        #end if
                        #if $current.rainRate.has_data
                        "precipRate": $current.rainRate.mm_per_hour.raw,
                        #end if
                        #if $day.rain.has_data
                        "rainday": $day.rain.sum.mm.raw
                        #end if
        }
    }
    ]
}

key
Weewx doesnt use a key but uses the key as the location for your JSON file. Just place the URL in the key and the app will use that to pull the json location.

locationCity
Used to indicate Weewx version. The homekit plugin requires an location field that is used to run. It technically can be any text you want but I just have added the Current Weewx versin..

"platforms": [
{
"platform": "WeatherPlus",
"service": "weatherunderground",
"key": "http://weewx.lan/homekit.json",
"locationCity": "V.4.3.1"
}
]

Advanced Configuration

Below are explanations for a lot of advanced parameters to adjust the plugin to your needs. All parameters are * optional*.

compatibility
Compatibility for the Apple Home app, the Eve app or both. This is required due to limitations in the Apple Home app recognized weather conditions. The default is "eve".
"eve" (recommended) Use this for the Eve app or another 3rd party HomeKit App. All conditions will be displayed. The Apple Home app will show only temperature and humidity.
"eve2" Same as above but the values for temperature, humidity and pressure will be grouped into a single row. The Apple Home app will show nothing.
"home" Use this if you don't want to install a 3rd party HomeKit App but want to see as many values as possible in the Apple Home app6. 3rd party apps will show some useless sensors that are required for Home app support.
"both" Combines eve and home. You will need to hide some useless sensors in the Eve app that are required for Home app support. But after that you will get a solution that looks nice in the Home app and in 3rd party apps at the same time.

6 The following values will be represented as occupancy sensors that trigger on specific limits: CloudCover > 20%, UVIndex > 2, WindSpeed > 4 m/s, Rain, Snow

conditionCategory
Detail level of the condition category. Not available for WeatherUnderground. Default is "simple".
"simple" 4 different categories
"detailed" 10 different categories

extraHumidity (compatibility "eve" or "both")
Separate humidity from the weather accessory to an own accessory if set to true. Default is false.

forecast
List of forecast days with 0 for today, 1 for tomorrow, 2 for in 2 days etc. Default are none []. Maximum depends on the chosen weather service.

hidden
List of observation and forecast values that should not be displayed. Possible options are ["AirPressure", "CloudCover", "Condition", "ConditionCategory", "DewPoint", "ForecastDay", "Humidity", "ObservationStation", "ObservationTime", "Ozone", "Rain1h", "RainBool", "RainChance", "RainDay", "SnowBool", "SolarRadiation", "TemperatureMin", "UVIndex", "Visibility", "WindDirection", "WindSpeed", "WindSpeedMax"] . Don't forget the square brackets.

interval
Update interval in minutes. The default is 4 minutes because the rate for free API keys is limited.

language
Translation for the current day and the weather report. Available languages can be found here. The default is en.

nameNow
Name for the current condition accessory. The default is "Now". You could set this to your city name or weather service type.

nameForecast
Name for the forecast accessories. Adds a prefix to the forecast days. You could set this to your city name or weather service type as well.

now Option to hide the Now accessory if you only need forecasts. Default is true which shows the Now accessory. Set to false to hide it.

units
Conversions used for reporting values. The default is "metric". The options are:
"si" or "metric"
"sitorr" to report air pressure in mmhg
"us" or "imperial"
"ca" to report wind speeds in km/h "uk" to report visibility in miles and wind speeds in miles/h

thresholdAirPressure (compatibility "home" or "both")
At what threshold should the air pressure sensor trigger? Provide a number without unit. The range depends on your unit setting (sitorr -> mmhg, otherwise -> hPa).

thresholdCloudCover (compatibility "home" or "both")
At what threshold should the cloud cover sensor trigger? Provide a number between 0 (clear) and 100 (overcast).

thresholdUvIndex (compatibility "home" or "both")
At what threshold should the UV-Index sensor trigger? Provide a number >= 0. See https://en.wikipedia.org/wiki/Ultraviolet_index

thresholdWindSpeed (compatibility "home" or "both")
At what threshold should the wind speed sensor trigger? Provide a number without unit. The range depends on your unit setting (si/metric/sitorr -> m/s, ca -> km/h, uk/us/imperial -> miles/h).

fakegatoParameters
Customization of the history storage system. By default, the history is persisted on the filesystem. You can set your own option using this parameter. In order to change the location of the persisted file or to use GoogleDrive. Do not modify the parameter for the fakegato internal timer.

Example

"platforms": [
{
"platform": "WeatherPlus",
"service": "darksky",
"key": "XXXXXXXXXXXXXXX",
"locationGeo": [52.5200066, 13.404954],
"compatibility": "both",
"conditionCategory": "detailed",
"forecast": [0, 1, 2, 3, 4,5, 6],
"hidden": ["CloudCover", "DewPoint"],
"interval": 5,
"language": "en",
"nameNow": "Berlin",
"nameForecast": "Berlin Forecast",
"now": true,
"units": "metric"
}
]

Multiple Stations Configuration

You can set up multiple stations for different locations and weather services by putting your configuration in a ** stations** array. The following parameters are global and must be placed outside of the array: platform, interval, units.

Each stations must have a unique displayName. If you don't set one, the plugin will take care of that.

Example

"platforms": [
{
"platform": "WeatherPlus",
"interval": 5,
"units": "si",
"stations": [
{
"displayName": "Berlin",
"displayNameForecast": "Berlin forefacst",
"service": "darksky",
"key": "YOUR_API_KEY",
"forecast": [0, 1, 2, 3, 4,5, 6],
"locationGeo": [52.5200066, 13.404954]
},
{
"displayName": "Los Angeles",
"displayNameForecast": "Los Angeles forecast",
"service": "darksky",
"key": "YOUR_API_KEY",
"forecast": [1],
"locationGeo": [34.0536909, -118.2427666]
}
]
}
]

Example Use Cases

Switch on a blue light in the morning when the chance for rain is above 20% today (or white when the forecast condition is snow / yellow when it's sunny).
Start your automatic garden irrigation in the evening, depending on the amount of rain today and the forecast for tomorrow.

Hint: To trigger rules based on time and weather condition you will need a plugin like homebridge-delay-switch. Create a dummy switch that resets after some seconds. Set this switch to on with a timed rule. Then create a condition rule that triggers when the switch goes on depending on weather conditions of your choice.

Contributors

Many thanks to the awesome contributors who support the project with pull requests (chronological order):

simont77 for his fakegato-history library, the eve weather emulation, the multiple stations feature and several other great improvements
GatoPharaoh for his interval option pull request
David Werth for integrating the OpenWeatherMap and Yahoo apis
Marshall T. Rose for adding support for imperial units and the displayName parameter
Bill Waggoner for his fix for the crashing weatherunderground api
Russell Sonnenschein for adding the new 2019 weatherunderground api
Jay O'Conor for improving the value rounding and fixing the wind sensor for non metric units
Angela Herring for adding compatibility mode for total precip and improving the WeatherUnderground integration

This plugin is a fork of homebridge-weather-station which is no longer being developed. That one was a fork of homebridge-wunderground.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

homebridge-weather-plus

Features

Choose your Weather Service

Installation

Observations and Forecasts

Configuration

Dark Sky

OpenWeatherMap

Weather Underground

Weewx

Advanced Configuration

Example

Multiple Stations Configuration

Example

Example Use Cases

Contributors

Attribution