Multiple weather stations (#55)

* Added support for multiple weather stations
naofireblade · Feb 16, 2019 · b2c01b6 · b2c01b6
1 parent 31ef67e
commit b2c01b6
Show file tree

Hide file tree

Showing 10 changed files with 887 additions and 833 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -122,4 +122,7 @@
 
 * Added option to set serial number
 * Changed history timer to make use of advantages in newer fakegato version
-* Fixed precipitation calculation in dark sky api
+* Fixed precipitation calculation in dark sky api
+
+## 2.7.0
+* Added support for multiple weather stations
diff --git a/README.md b/README.md
@@ -4,15 +4,21 @@
 [![GitHub last commit](https://img.shields.io/github/last-commit/naofireblade/homebridge-weather-plus.svg?style=flat-square)](https://github.com/naofireblade/homebridge-weather-plus)
 [![Weather](https://img.shields.io/badge/weather-sunny-edd100.svg?style=flat-square)](https://github.com/naofireblade/homebridge-weather-plus)
 
-This is a weather plugin for [homebridge](https://github.com/nfarina/homebridge) that features current observations, daily forecasts and history graphs. You can download it via [npm](https://www.npmjs.com/package/homebridge-weather-plus).
-
-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.
+This is a weather plugin for [homebridge](https://github.com/nfarina/homebridge) that features current observations, daily forecasts and history graphs for multiple locations and services. You can download it via [npm](https://www.npmjs.com/package/homebridge-weather-plus).
 
 Feel free to leave any feedback [here](https://github.com/naofireblade/homebridge-weather-plus/issues).
 
-## Current Observations
+## Features
+- Get current observations and forecasts for up to 10 days
+- Choose from 4 different weather [services](#choose-your-weather-service)
+- Add [multiple](#multiple-stations-configuration) locations/services
+- See the weather [history](#screenshots) in the Eve App
+- See translations and [icons](#screenshots) in the Eve App
+- Use all values in HomeKit rules with the Eve App
+
+## Observations and Forecasts
 
-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](#screenshots).
+The following **19 observation and forecast values** can be displayed and used in HomeKit rules.
 
 - Air Pressure
 - Cloud Cover
@@ -23,47 +29,21 @@ The following **16 current observation values** can be displayed and used in Hom
 - Ozone
 - Rain Last Hour
 - Rain All Day
+- Rain Chance
 - 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
+- *Observation Time*
+- *Observation Station*
 - *Forecast day*
 
-## History
-
-With the eve app you can view the history for
-
-- Air Pressure
-- Humidity
-- Temperature
-
-## Choose your weather service
+## 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.
 
@@ -82,45 +62,18 @@ This plugin supports multiple weather services. Each has it's own advantages. Th
 ## Installation
 
 1. Install homebridge using: `npm install -g homebridge`
-2. Install this plugin using: `npm install -g homebridge-weather-plus`
+2. Install this plugin using: `npm install -g homebridge-weather-plus` *Note: The installation might take 5 minutes.*
 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](https://github.com/darkskyapp/translations/tree/master/lib/lang). 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.
-
-The **serial** parameter is *optional* and sets the Serial Number of the accessory. If it's not provided the serial number will be set to the **location** if present, or to 999 if not. Note that for proper operation of fakegato when multiple fakegato-enabled weather accessories are present in your system, the serial number must be unique.
-
+Below are example configurations for all weather apis.
 
 ### Dark Sky
 
+The **key** parameter is the API key that you get by registering for the Dark Sky service.
+
 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.
 
 ```json
@@ -130,16 +83,16 @@ The **locationGeo** parameter must be a list with the latitude longitude for you
 		"name": "WeatherPlus",
 		"service": "darksky",
 		"key": "XXXXXXXXXXXXXXX",
-		"locationGeo": [52.5200066, 13.404954],
-		"language": "en",
-		"forecast": [1,2,3,4,5,6,7]
+		"locationGeo": [52.5200066, 13.404954]
 	}
 ]
 ```
 
 ### OpenWeatherMap
 
-**Please use only one location property.**
+The **key** parameter is the API key that you get by registering for the OpenWeather service
+
+**Please choose from one of these location properties.**
 
 The **location** parameter must be a numerical unique city-id (can be found [here](https://openweathermap.org/find))
 
@@ -157,8 +110,6 @@ The **locationGeo** parameter must be a list with the latitude longitude for you
 		"location": 2950159,
 		"locationCity": "Berlin, DE",
 		"locationGeo": [52.5200066, 13.404954],
-		"language": "en",
-		"forecast": [1,2,3,4,5]
 	}
 ]
 ```
@@ -167,8 +118,6 @@ The **locationGeo** parameter must be a list with the latitude longitude for you
 
 The **location** parameter is a text for finding a location with YQL (see [here](https://developer.yahoo.com/weather/))
 
-The **forecast** parameter is *optional* and defines a list of forecast days with 1 for today, 2 for tomorrow etc. Default are none.
-
 ```json
 "platforms": [
 	{
@@ -185,6 +134,7 @@ The **forecast** parameter is *optional* and defines a list of forecast days wit
 
 The **location** parameter can be a city name or a zip. You can also use a station from the **[Personal Weather Station Network](https://www.wunderground.com/weatherstation/overview.asp)** to receive weather information. Just enter pws:YOURID.
 
+The **key** parameter is the API key that you get by registering for the Weather Underground service
 
 ```json
 "platforms": [
@@ -199,7 +149,92 @@ The **location** parameter can be a city name or a zip. You can also use a stati
 ]
 ```
 
-## Example use cases
+## Advanced Configuration
+
+Below are explanations for all advanced parameters of this plugin. Most parameters are *optional*. 
+
+The **forecast** parameter is *optional* and defines a list of forecast days with 1 for today, 2 for tomorrow etc. Default are none.
+
+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. This parameter is global for all weather accessories.
+
+The **units** parameter is *optional* and sets the conventions used for reporting values. The default is "metric". This parameter is global for all weather accessories. 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 **language** parameter is *optional* and sets the translation for the description of the day and the weather report for each API. Available languages can be found [here](https://github.com/darkskyapp/translations/tree/master/lib/lang). 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 **displayName** parameter is *optional* and sets the CurrentConditons accessory's name. The default is "Now". **IMPORTANT NOTE:** If setting multiple weather accessories, ensure that each accessory has a unique name, or you will get an error from *homebridge*. If you do not set this parameter the plugin will take care of that.
+
+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. **IMPORTANT NOTE:** If setting multiple weather accessories, ensure that each accessory has a unique name, or you will get an error from *homebridge*. If you do not set this parameter the plugin will take care of that.
+
+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.
+
+The **serial** parameter is *optional* and sets the Serial Number of the accessory. If it's not provided the serial number will be set to the **location** if present, or to 999 if not. Note that for proper operation of fakegato when multiple fakegato-enabled weather accessories are present in your system, the serial number must be unique.
+
+### Example
+
+```json
+"platforms": [
+        {
+            "platform": "WeatherPlus",
+            "name": "WeatherPlus",
+            "interval": 5,
+            "displayName":"Conditions OWM",
+            "displayNameForecast":"Forecast OWM",
+            "service": "openweathermap",
+            "key": "XXXXXXXXXXXXXXX",
+            "forecast": [1,2],
+            "locationGeo": [45.4999952, 9.3061655],
+            "serial": "OWM"                        
+        }
+    ]
+```
+
+## Multiple Stations Configuration
+
+You can set up multiple stations for different locations and/or weather services by putting your configuration in an **stations** array. The parameters **interval** and **units** are global to all accessories, and must be set at the top level. 
+
+### Example
+
+```json
+"platforms": [
+        {
+            "platform": "WeatherPlus",
+            "name": "WeatherPlus",
+            "interval": 5,
+            "units": "si",
+            "stations":[{
+                "displayName":"Conditions OWM",
+                "displayNameForecast":"Forecast OWM",
+                "service": "openweathermap",
+                "key": "XXXXXXXXXXXXXXX",
+                "forecast": [1,2],
+                "locationGeo": [45.4999952, 9.3061655],
+                "serial": "OWM" 
+            },{
+                "displayName":"Conditions DS",
+                "displayNameForecast":"Forecast DS",
+                "service": "darksky",
+                "key": "XXXXXXXXXXXXXXX",
+                "forecast": [1,2],
+                "locationGeo": [45.4999952, 9.3061655],
+                "serial": "DS",
+            }]
+        }
+    ]
+```
+
+## 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.
@@ -215,7 +250,7 @@ The **location** parameter can be a city name or a zip. You can also use a stati
 Many thanks go to
 - [Kevin Harwood](https://github.com/kcharwood) for his original homebridge-weather-station
 - [Clark Endrizzi](https://github.com/cendrizzi) for his wundergroundnode library
-- [simont77](https://github.com/simont77) for his fakegato-history library, the eve weather emulation and several other great improvements
+- [simont77](https://github.com/simont77) for his fakegato-history library, the eve weather emulation, the multiple stations feature and several other great improvements
 - [GatoPharaoh](https://github.com/GatoPharaoh) for his interval option pull request
 - [David Werth](https://github.com/werthdavid) for integrating the OpenWeatherMap and Yahoo apis
 - [Marshall T. Rose](https://github.com/mrose17) for adding support for imperial units and the displayName parameter