Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
228 lines (171 sloc) 11.6 KB

homebridge-weather-plus

npm npm GitHub last commit Weather

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

If you update from a version before 2.0.0 you have to adapt your config. See the samples below. You might consider switching your weather service to the newly supported dark sky service.

Feel free to leave any feedback here.

Current Observations

The following 16 current observation values can be displayed and used in HomeKit rules. Use a 3rd party app like Elgato Eve to see all values, translations and some nice icons.

  • Air Pressure
  • Cloud Cover
  • Condition
  • Condition Category (Sun = 0, Clouds = 1, Rain = 2, Snow = 3)
  • Dew Point
  • Humidity
  • Ozone
  • Rain Last Hour
  • Rain All Day
  • Solar Radiation
  • Temperature
  • UV-Index
  • Visibility
  • Wind Direction
  • Wind Speed
  • Wind Speed Maximum
  • Observation Time
  • Observation Station

Forecast

The plugin also features forecasts for up to 7 days. The following 16 forecast values can be displayed.

  • Air Pressure
  • Cloud Cover
  • Condition
  • Condition Category (Sun = 0, Clouds = 1, Rain = 2, Snow = 3)
  • Dew Point
  • Humidity
  • Ozone
  • Rain Chance
  • Rain All Day
  • Temperature Min
  • Temperature Max
  • UV-Index
  • Visibility
  • Wind Direction
  • Wind Speed
  • Wind Speed Maximum
  • Forecast day

History

With the eve app you can view the history for

  • Air Pressure
  • Humidity
  • Temperature

Choose your weather service

This plugin supports multiple weather services. Each has it's own advantages. The following table shows a comparison to help you choosing one.

Dark Sky (recommended) OpenWeatherMap Yahoo (currently offline) Weather Underground (legacy)
Current observation values 15 7 10 13
Forecast values 16 9 4 10
Forecast days 7 5 10 4
Location geo-coordinates city name, city id, geo-coordinates city name city name or zip
Personal weather stations ✔️ ✔️
Free ✔️ ✔️ ✔️ (only legacy accounts)
Register here here not needed here

You can add more services by forking the project and submitting a pull request.

Installation

  1. Install homebridge using: npm install -g homebridge
  2. Install this plugin using: npm install -g homebridge-weather-plus
  3. Gather an API key for a weather service from the register link in the table above
  4. Update your configuration file. See the samples below.

Configuration

Below are explanations for all parameters and examples for all weather apis. Most parameters are optional.

The key parameter is the API key that you get by registering for a weather service in the table above.

The language parameter is optional and sets the translation for the description of the day and the weather report. Available languages can be found here. The default is en.

The forecast parameter is optional and defines a list of forecast days with 1 for today, 2 for tomorrow etc. The default is none.

The units parameter is optional and sets the conventions used for reporting values. The default is "metric". The choices are:

  • "si" (or "metric")
  • "us" (or "imperial")
  • "ca" to report wind speeds in km/h instead of m/s
  • "uk" to report visibility in miles and wind speeds in km/h instead of m/s

The interval parameter is optional and sets the update interval in minutes. The default is 4 minutes because the rate for free API keys is limited.

The displayName parameter is optional and sets the CurrentConditons accessory's name. The default is "Now".

The displayNameForecast parameter is optional and sets the Forecast accessories name. If the forecast parameter is present, then the names of the forecasts are prefixed with the displayNameForecast parameter.

The currentObservations parameter is optional and sets how the 3 current observations temperature, humidity and pressure are displayed. You can choose one of these 2 options:

  • "eve" (this combines all 3 values into one row in the eve app but shows nothing in the Apple Home app)
  • "normal" (default, this shows all 3 values in a seperate row in the eve app and shows the temperature in the Apple Home app)

The fakegatoParameters parameter is optional. By default, history is persisted on filesystem. You can pass your own parameters to fakegato-history module using this paramter, in order to change the location of the persisted file or use GoogleDrive persistance. See https://github.com/simont77/fakegato-history#file-system and https://github.com/simont77/fakegato-history#google-drive for more info. IMPORTANT NOTE: Do not modify the parameter for the fakegato internal timer.

Dark Sky

The locationGeo parameter must be a list with the latitude longitude for your location (dont forget the square brackets). You can use this page to find your coordinates: http://www.mapcoordinates.net/en.

"platforms": [
	{
		"platform": "WeatherPlus",
		"name": "WeatherPlus",
		"service": "darksky",
		"key": "XXXXXXXXXXXXXXX",
		"locationGeo": [52.5200066, 13.404954],
		"language": "en",
		"forecast": [1,2,3,4,5,6,7]
	}
]

OpenWeatherMap

Please use only one location property.

The location parameter must be a numerical unique city-id (can be found here)

The locationCity parameter must be a city-name with an optional country code e.g. "Berlin, DE" (you can check it here)

The locationGeo parameter must be a list with the latitude longitude for your location (don't forget the square brackets). You can use this page to find your coordinates: http://www.mapcoordinates.net/en.

"platforms": [
	{
		"platform": "WeatherPlus",
		"name": "WeatherPlus",
		"service": "openweathermap",
		"key": "XXXXXXXXXXXXXXX",
		"location": 2950159,
		"locationCity": "Berlin, DE",
		"locationGeo": [52.5200066, 13.404954],
		"language": "en",
		"forecast": [1,2,3,4,5]
	}
]

Yahoo

The location parameter is a text for finding a location with YQL (see here)

The forecast parameter is optional and defines a list of forecast days with 1 for today, 2 for tomorrow etc. Default are none.

"platforms": [
	{
		"platform": "WeatherPlus",
		"name": "WeatherPlus",
		"service": "yahoo",
		"location": "Berlin, DE",
		"forecast": [1,2,3,4,5,6,7]
	}
]

Weather Underground

The location parameter can be a city name or a zip. You can also use a station from the Personal Weather Station Network to receive weather information. Just enter pws:YOURID.

"platforms": [
	{
		"platform": "WeatherPlus",
		"name": "WeatherPlus",
		"service": "weatherunderground",
		"key": "XXXXXXXXXXXXXXX",
		"location": "New York",
		"forecast": [1,2,3,4]
	}
]

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.

Screenshots

Current Conditions in Elgato Eve app History graph in Elgato Eve app

(c) Screenshots are taken from the Elgato Eve app

Contributors

Many thanks go to

  • Kevin Harwood for his original homebridge-weather-station
  • Clark Endrizzi for his wundergroundnode library
  • simont77 for his fakegato-history library, the eve weather emulation 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

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

Attribution