UltraWeatherBug HSPI User s Guide A HomeSeer HS2 plug-in to access live local weather conditions, forecasts and severe weather alerts Copyright 2012 ultrajones@hotmail.com Revised 07/16/2012 This document contains proprietary and copyrighted information and may not be copied, reproduced, translated, or reduced to any electronic medium without prior consent, in writing, from ultrajones@hotmail.com.
Table of Contents Introduction... 4 Intended Audience... 4 UltraWeatherBug HSPI Overview... 4 How It Works... 4 Features... 4 Requirements... 4 UltraWeatherBug HSPI Installation... 5 Downloading the HomeSeer Plug-in... 5 Enabling the HomeSeer Plug-in... 5 UltraWeatherBug HSPI Configuration... 6 Web Page Layout... 6 UltraWeatherBug HSPI Options... 6 UltraWeatherBug Speak... 8 Adding WeatherBug HomeSeer Devices... 10 Temperature Devices... 10 Humidity Devices... 10 Wind Devices... 10 Rain Devices... 10 Pressure Devices... 10 Light Devices... 11 Weather Devices... 11 Forecast Devices... 11 UltraWeatherBug Device... 11 Modifying an Existing WeatherBug Device... 11 Deleting an Existing WeatherBug Device... 11 UltraWeatherBug HSPI Triggers... 12 UltraWeatherBug Alert Trigger... 12 Screenshot... 12 UltraWeatherBug HSPI Trigger Actions... 12 2
UltraWeatherBug E-Mail Notification... 12 UltraWeatherBug Speak... 13 UltraWeatherBug HSPI Trigger Conditions... 13 UltraWeatherBug Conditions Supported... 13 UltraWeatherBug HSPI API Reference... 14 RefreshStation Subroutine... 14 Example... 14 GetStations Subroutine... 14 Example... 14 GetStation Subroutine... 15 Example... 15 GetForecast Subroutine... 16 Example... 16 GetAlerts Subroutine... 17 Example... 17 3
Introduction UltraWeatherBug is a HomeSeer HS2 plug-in that allows you to use HomeSeer to access live local weather conditions, forecasts and severe weather alerts. The plug-in reads live weather from any of the 8,000 WeatherBug Tracking Stations. WeatherBug manages and operates a proprietary network of over 8,000 WeatherBug Tracking Stations strategically placed at schools, public safety facilities and television stations throughout the U.S. These professional-grade weather stations generate live neighborhood level reports every second (unlike other weather providers; their data is up to an hour or more old). For more information, see http://www.weatherbug.com. Intended Audience This document is intended for the HomeSeer user that has chosen to install and configure the UltraWeatherBug HomeSeer Plug-in. UltraWeatherBug HSPI Overview How It Works UltraWeatherBug pulls live weather data from any of the 8,000 WeatherBug Tracking Stations and updates HomeSeer devices with the current weather conditions. Features Multiple threading allows UltraWeatherBug to query for live weather, weather forecasts and weather alerts without disrupting the performance of HomeSeer. Supports HomeSeer triggers based on weather alerts. Supports HomeSeer actions to send current weather conditions, 7 day weather forecast or current weather alerts. Error Try/Catch logic to ensure plug-in doesnt fail with an unhandled exception. Web page is non-code behind ASP.Net to allow the user to easily customize the code and interface. Requirements Homeseer 2.2 or greater 4
UltraWeatherBug HSPI Installation Downloading the HomeSeer Plug-in 1. From your HomeSeer web page, select the Updater button. 2. Click the Next button until you find the entry for UltraWeatherBug, the click the checkbox to mark the plug-in for installation. 3. Click the Next button to begin downloading the UltraWeatherBug plug-in package. 4. Restart HomeSeer once the download is complete. Enabling the HomeSeer Plug-in 1. From your HomeSeer web page, select the Setup button. 2. Select the Interfaces tab. 3. From the Built-in Interfaces section, click the Disabled button to enable the UltraWeatherBug plug-in, and then select Save to enable the plug-in. 4. The UltraWeatherBug plug-in is now enabled. Click the UltraWeatherBug button to view the plug-in Status, Options, Stations, Devices, Live Weather, Forecast and Alerts. 5
UltraWeatherBug HSPI Configuration Web Page Layout The UltraWeatherBug plug-in has seven web pages that provide access the available features of the plug-in. The available web pages are as follows: 1. Status Displays the plug-in and WeatherBug status. 2. Options Displays and allows you to change the options associated with the plug-in. 3. Speech Displays and allows you to change the options assoicated with speaking weather conditions, forecasts and alerts. 4. Stations Provide the ability to define up to 5 WeatherBug tracking stations. 5. Devices Allows you to create a HomeSeer device to track the weather conditions. 6. Live Weather Displays the live weather conditions for any of the pre-defined tracking stations. 7. Forecast Displays the 7 day forecast and provides one click access to the WeatherBug web page. 8. Alerts Displays the Weather Alerts for any of the pre-defined tracking stations. UltraWeatherBug HSPI Options All options are set from the Options web page. The following options are supported: 1. Unit Type Specify the preferred unit types (e.g. U.S. customary units or metric system units). 2. Station Update Specify how often to check the WeatherBug tracking station for updated live weather data. 3. Forecast Update - Specify how often to check for the weather forecast for the defined tracking stations. 6
4. Alerts Update Specify how often to check for weather alerts. 5. Forecast Image Size Specify the image size when displaying the weather forecast. 6. Forecast Image Background Specify if the background image is transparent or opaque. 7. Observation Time Zone Offset Set this option to yes to apply your time zone offset to the date and time provided by Weatherbug. The default value is no. 8. Alerts Time Zone Offset Set this option to yes to apply your time zone offset to the date and time provided by Weatherbug. The default value is yes. 9. Email To The e-mail address used to send the e-mail notifications to. 10. Email From The e-mail address used to send the e-mail notifications from. 11. Email Subject The e-mail subject template. The following variables are expanded when the email notification is sent: a. $station (e.g. Station1, Station2, etc.) b. $notification-type (e.g. Weather Forecast, Weather Alert) 12. Live Weather Template The message body used to send live weather e-mail notifications. The following variables are expanded when the e-mail is sent: a. $station (e.g. Station1, Station2, etc.) b. $stationname (e.g. Local HS [1.5 miles away]) c. $stationcity (e.g. New York) d. $temp e. $temp-high f. $temp-low g. $temp-rate h. $feels-like i. $wet-bulb j. $dew-point k. $humidity l. $humidity-high m. $humidity-low n. $humidity-rate o. $gust-direction p. $gust-speed q. $gust-time r. $wind-speed s. $wind-speed-avg t. $wind-direction u. $wind-direction-avg v. $rain-month w. $rain-rate x. $rain-rate-max y. $rain-today z. $rain-year aa. $pressure 7
bb. $pressure-high cc. $pressure-low dd. $light ee. $light-rate ff. $ob-date gg. $current-condition hh. $todays-short-prediction ii. $todays-high jj. $todays-low kk. $tomorrows-short-prediction ll. $tomorrows-high mm. $tomorrows-low nn. $last-alert-type oo. $last-alert-title 13. Forecast Weather Template The message body used to send live weather e-mail notifications. The following variables are expanded when the e-mail is sent: a. All variables supported by the Live Weather Template. b. $forecast (contains the 7 day forecast) c. $forecastn (contains the forecast for the next n days, where n=1-7) Example: $forecast3 will contain the forecast for the next 3 days. 14. Alert Weather Template The message body used to send live weather e-mail notifications. The following variables are expanded when the e-mail is sent: a. All variables supported by the Live Weather Template. b. $posted-date c. $expires-date d. $type e. $tile f. $msg-summary 15. Register Link If set to Yes, the UltraWeatherBug button will be displayed on all web pages. 16. Debug Mode If set to Yes, the plug-in will write verbose logging to the HomeSeer log file. UltraWeatherBug Speak All speech options are set from the Speech web page. The following options are supported: 1. Live Weather Template The template used to speak live weather conditions. The following variables are expanded prior to speaking: a. $station (e.g. Station1, Station2, etc.) b. $stationname (e.g. Local HS [1.5 miles away]) c. $stationcity (e.g. New York) d. $temp e. $temp-high f. $temp-low g. $temp-rate 8
h. $feels-like i. $wet-bulb j. $dew-point k. $humidity l. $humidity-high m. $humidity-low n. $humidity-rate o. $gust-direction p. $gust-speed q. $gust-time r. $wind-speed s. $wind-speed-avg t. $wind-direction u. $wind-direction-avg v. $rain-month w. $rain-rate x. $rain-rate-max y. $rain-today z. $rain-year aa. $pressure bb. $pressure-high cc. $pressure-low dd. $light ee. $light-rate ff. $ob-date gg. $current-condition hh. $todays-short-prediction ii. $todays-high jj. $todays-low kk. $tomorrows-short-prediction ll. $tomorrows-high mm. $tomorrows-low nn. $last-alert-type oo. $last-alert-title 2. Forecast Weather Template The message body used to send live weather e-mail notifications. The following variables are expanded when the e-mail is sent: a. All variables supported by the Live Weather Template. b. $forecast (contains the 7 day forecast) c. $forecastn (contains the forecast for the next n days, where n=1-7) Example: $forecast3 will contain the forecast for the next 3 days. 3. Alert Weather Template The message body used to send live weather e-mail notifications. The following variables are expanded when the e-mail is sent: 9
a. All variables supported by the Live Weather Template. b. $posted-date c. $expires-date d. $type e. $tile f. $msg-summary Adding WeatherBug HomeSeer Devices The UltraWeatherBug plug-in allows you to create a HomeSeer device for temperature, humidity, wind, rain, pressure, light, current conditions and tomorrow s forecast. Temperature Devices Each temperature device you create will be assigned from the WeatherBug house code. To create a temperature device, simply connect to the UltraWeatherBug HSPI Devices web page, then select the Temperature WeatherBug Device Type, then click the Submit button. All available temperature devices will be displayed. Select the HomeSeer devices you want to create by clicking the checkbox under the HomeSeer Device column, then click the Save button. Humidity Devices Each humidity device you create will be assigned from the WeatherBug house code. To create a humidity device, simply connect to the UltraWeatherBug HSPI Devices web page, then select the Humidity WeatherBug Device Type, then click the Submit button. All available humidity devices will be displayed. Select the HomeSeer devices you want to create by clicking the checkbox under the HomeSeer Device column, then click the Save button. Wind Devices Each wind device you create will be assigned from the WeatherBug house code. To create a wind device, simply connect to the UltraWeatherBug HSPI Devices web page, then select the Wind WeatherBug Device Type, then click the Submit button. All available wind devices will be displayed. Select the HomeSeer devices you want to create by clicking the checkbox under the HomeSeer Device column, then click the Save button. Rain Devices Each rain device you create will be assigned from the WeatherBug house code. To create a rain device, simply connect to the UltraWeatherBug HSPI Devices web page, then select the Rain WeatherBug Device Type, then click the Submit button. All available rain devices will be displayed. Select the HomeSeer devices you want to create by clicking the checkbox under the HomeSeer Device column, then click the Save button. Pressure Devices Each pressure device you create will be assigned from the WeatherBug house code. To create a pressure device, simply connect to the UltraWeatherBug HSPI Devices web page, then select the Pressure WeatherBug Device Type, then click the Submit button. All available pressure devices will be 10
displayed. Select the HomeSeer devices you want to create by clicking the checkbox under the HomeSeer Device column, then click the Save button. Light Devices Each light device you create will be assigned from the WeatherBug house code. To create a light device, simply connect to the UltraWeatherBug HSPI Devices web page, then select the Light WeatherBug Device Type, then click the Submit button. All available light devices will be displayed. Select the HomeSeer devices you want to create by clicking the checkbox under the HomeSeer Device column, then click the Save button. Weather Devices Each weather device you create will be assigned from the WeatherBug house code. To create a weather device, simply connect to the UltraWeatherBug HSPI Devices web page, then select the Weather WeatherBug Device Type, then click the Submit button. All available weather devices will be displayed. Select the HomeSeer devices you want to create by clicking the checkbox under the HomeSeer Device column, then click the Save button. Forecast Devices Each forecast device you create will be assigned from the WeatherBug house code. To create a forecast device, simply connect to the UltraWeatherBug HSPI Devices web page, then select the Forecast WeatherBug Device Type, then click the Submit button. All available forecast devices will be displayed. Select the HomeSeer devices you want to create by clicking the checkbox under the HomeSeer Device column, then click the Save button. UltraWeatherBug Device This HomeSeer device allows you to enable or disable the updates from WeatherBug. This is the only HomeSeer device that will be automatically created. Modifying an Existing WeatherBug Device You can modify an UltraWeatherBug device the same way you modify any other HomeSeer device. Simply click on the device name from the HomeSeer device page, and then change the device properties as needed. Note: Once a HomeSeer device is created, the plug-in will not overwrite any of the device properties, so feel free to modify the name, location and location2 properties as you see fit. Deleting an Existing WeatherBug Device You can delete an UltraWeatherBug device the same way you delete any other HomeSeer device. From the HomeSeer device web page, click the device name, then from the HomeSeer modify device web page, click the Delete button. 11
UltraWeatherBug HSPI Triggers UltraWeatherBug Alert Trigger This option allows you to trigger a HomeSeer event when a new weather alert is issued. The following weather alert triggers are supported: 1. Any Triggers when any alert type is issued. 2. Advisory Triggers when a weather advisory is issued. 3. Emergency Triggers when a weather emergency is issued. 4. Statement Triggers when a weather statement is issued. 5. Watch Triggers when a weather watch is issued. 6. Warning Triggers when a weather warning is issued. Screenshot UltraWeatherBug HSPI Trigger Actions UltraWeatherBug E-Mail Notification This action causes a weather condition, weather forecast or weather alert to be generated for the selected station. 12
UltraWeatherBug Speak This action causes HomeSeer to speak with current weather conditions, forecast or weather alert for the selected station. UltraWeatherBug HSPI Trigger Conditions UltraWeatherBug HSPI conditions allow you to specify that certain conditions must exist before a HomeSeer event will run. UltraWeatherBug Conditions Supported 1. Current Conditions 2. Today s Prediction 3. Tomorrow s Prediction The HomeSeer conditions support the following condition categories: 1. No Precipitation (for Current Conditions) and No Chance of Precipitation (for Today s and Tomorrow s Predictions) 2. "Sunny/Clear" 3. "Cloudy/Fair/Hazy" 4. "Rain/Rain Showers/Drizzle" 5. "Sleet/Freezing Rain/Freezing Drizzle" 6. "Snow/Snow Showers/Flurries" 7. "Storms/Thunderstorms" 8. "Foggy" 9. "Windy" 10. "Warm and Humid" 11. "Cold and Dry" 13
UltraWeatherBug HSPI API Reference RefreshStation Subroutine This function allows you to refresh the live weather, forecast and alerts data. Public Sub RefreshStation(ByVal strstationnumber As String) strstationnumber Station1 Station5 Example Sub Main(ByVal parm As Object) Dim strresults As String = "" Cause the plug-in to refresh live weather, weather forecast and weather alerts hs.plugin("ultraweatherbug").refreshstation("station1") End Sub GetStations Subroutine This function allows you to retrieve all data stored internally for all defined weather stations. Public ReadOnly Property GetStations() As SortedList Example Sub Main(ByVal parm As Object) Define our plug-in object Dim hspi As Object = hs.plugin("ultraweatherbug") Get the WeatherBug devices Dim Stations As System.Collections.SortedList = hspi.getstations() If Stations.Count = 0 Then No stations found Else Get the device types we are interested in. The WeatherKeys are: "Temperature", "Humidity", "Wind", "Rain", "Pressure", "Light", "Weather", "Forecast" Dim Keys() As String = hspi.getweatherkeys("temperature") For Each strstationnumber As String In Stations.Keys Dim strstationname As String = Trim(hspi.GetSetting(strStationNumber, "StationName", "")) If strstationname.length > 0 Then For Each strkey As String In Keys Get the weatherbug data for our station and type (e.g. Temperature, Humidity, etc) Dim objweatherdata As Hashtable = Stations(strStationNumber)(strKey) Valid WeatherDataKeys are: Name, Type, Units, String, Icon, Misc, WebURL, LastChange 14
Dim strdevice As String = String.Format("{0} for {1} has a value of {2}", objweatherdata("name"), strstationname, objweatherdata("string")) Next End If Next hs.writelog("debug", strdevice) End If End Sub GetStation Subroutine This function allows you to retrieve data stored internally for the specified station. Public ReadOnly Property GetStation(ByVal strstationnumber As String) As Hashtable strstationnumber Station1 Station5 Example Sub Main(ByVal parm As Object) Define our plug-in object Dim hspi As Object = hs.plugin("ultraweatherbug") Get the WeatherBug device for Station1 Dim strstationnumber As String = "Station1" Dim Station As System.Collections.Hashtable = hspi.getstation(strstationnumber) If Station.Count = 0 Then No stations found Else Dim strstationname As String = Trim(hspi.GetSetting(strStationNumber, "StationName", "")) Dim strdate As String = String.Format("Live Conditions {0}", Station("ob-date")("Value")) Dim strtemperature = Station("temp")("Value") Dim strwind As String = String.Format("{0} at {1}", Station("wind-direction")("Value"), Station("wind-speed")("Value")) Dim strcurrentconditions As String = Station("current-condition")("Value") Dim strcondition As String = Station("current-condition")("Misc") Calculate the current condition image Dim strimagesize As String = "30x25" Dim strimagetype As String = "trans" Dim strconditionicon As String = String.Format("http://img.weather.weatherbug.com/forecast/icons/localized/{0}/en/{1}/{2}.png", strimagesize, strimagetype, strcondition) Do interesting stuff with data above hs.writelog("debug", String.Format("{0} {1} {2}", strstationname, strtemperature, strcurrentconditions)) hs.writelog("debug", String.Format("Current condition image is {0} ", strconditionicon)) 15
And access whatever else you are interested in Valid keys are: temp, feels-like, temp-rate, temp-high, temp-low, dew-point, wet-bulb wind-direction, wind-speed, wind-direction-avg, wind-speed-avg, gust-direction, gust-speed, gust-time humidity, humidity-high, humidity-rate, humidity-low rain-month, rain-rate, rain-rate-max, rain-today, rain-year light, light-rate pressure, pressure-high, pressure-low, pressure-rate ob-date, current-condition todays-short-prediction, todays-high, todays-low tomorrows-short-prediction, tomorrows-high, tomorrows-low Valid sub-keys are: Name, Type, Value, Image, Units, String, Icon, Misc, WebURL, LastChange Dim strweatherdata As String = String.Format("Current wind speed for {0} is {1}", strstationname, Station("wind-speed")("String")) hs.writelog("debug", strweatherdata) End If End Sub GetForecast Subroutine This function allows you to retrieve the 7 days forecast. Public ReadOnly Property GetForecast(ByVal strstationnumber As String) As Hashtable strstationnumber Station1 Station5 Example Sub Main(ByVal parm As Object) Define our plug-in object Dim hspi As Object = hs.plugin("ultraweatherbug") Get the WeatherBug device for Station1 Dim strstationnumber As String = "Station1" Dim Forecast As System.Collections.Hashtable = hspi.getforecast(strstationnumber) If Forecast.Count = 0 Then No forecast found Else Dim DaysOfWeek As System.Collections.ArrayList = hspi.getdaysofweek() Dim strstationname As String = Trim(hspi.GetSetting(strStationNumber, "StationName", "")) For Each DayOfWeek As System.Collections.Hashtable In DaysOfWeek Dim strdayname As String = DayOfWeek("ShortName") Dim strshortperdiction As String = Forecast(strDayName)("short-prediction") Dim strforecastlink As String = Forecast(strDayName)("WebURL") Dim strhigh As String = Forecast(strDayName)("high") Dim strlow As String = Forecast(strDayName)("low") Dim strimagesize As String = hspi.getsetting("options", "ForecastImageSize", "60x50") 16
Dim strimagebackground As String = hspi.getsetting("options", "ForecastImageBackground", "trans") Dim strcondition As String = Forecast(strDayName)("condition") Dim strconditionicon As String = String.Format("http://img.weather.weatherbug.com/forecast/icons/localized/{0}/en/{1}/{2}.png", strimagesize, strimagebackground, strcondition) Do interesting stuff with the forecast above hs.writelog("debug", String.Format("The forecast high for {0} is {1}", strdayname, strhigh)) Next End If End Sub GetAlerts Subroutine This function allows you to retrieve the 7 days forecast. Public ReadOnly Property GetAlerts() As SortedList strstationnumber Station1 Station5 Example Sub Main(ByVal parm As Object) Define our plug-in object Dim hspi As Object = hs.plugin("ultraweatherbug") Get all weather alerts Dim Alerts As System.Collections.SortedList = hspi.getalerts() If Alerts.Count = 0 Then No forecast found hs.writelog("debug", "There are no weather alerts at this time") Else Process each alert For Each stralertid As String In Alerts.Keys Dim Alert As System.Collections.Hashtable = Alerts(strAlertID) Dim strposteddate As String = Alert("posted-date") Dim strexpiresdate As String = Alert("expires-date") Dim stralerttype As String = Alert("type") Dim stralerttitle As String = Alert("title") Dim stralertsummary As String = Alert("msg-summary") If Alert("Station1") = True Then This alert is for station 1 17
Do interesting things with weather alert data hs.writelog("debug", String.Format("{0} Weather alert for station1: {0}", stralerttype, stralerttitle)) End If Next End If End Sub 18