UltraWeatherBug3 HSPI User s Guide A HomeSeer HS3 plug-in to access live local weather conditions, forecasts and severe weather alerts Copyright 2015 ultrajones@hotmail.com Revised 08/08/2015 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 UltraWeatherBug3 HSPI Overview... 4 How It Works... 4 Features... 4 Requirements... 4 UltraWeatherBug3 HSPI Installation... 5 Downloading the HomeSeer Plug-in... 5 UltraWeatherBug3 HSPI Setup... 5 How to Purchase Your WeatherBug Pulse API Key... 5 UltraWeatherBug3 HSPI Configuration... 5 Web Page Layout... 5 UltraWeatherBug3 HSPI Options... 6 UltraWeatherBug3 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 UltraWeatherBug3 Device... 11 Modifying an Existing WeatherBug Device... 11 Deleting an Existing WeatherBug Device... 11 UltraWeatherBug3 HSPI Triggers... 12 UltraWeatherBug3 Alert Trigger... 12 Screenshot... 12 2
UltraWeatherBug3 HSPI Trigger Actions... 12 UltraWeatherBug3 E-Mail Notification... 12 UltraWeatherBug3 Speak... 13 UltraWeatherBug3 HSPI Trigger Conditions... 13 UltraWeatherBug3 Conditions Supported... 13 UltraWeatherBug3 HSPI API Reference... 14 3
Introduction UltraWeatherBug3 is a HomeSeer3 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 UltraWeatherBug3 HomeSeer Plug-in. UltraWeatherBug3 HSPI Overview How It Works UltraWeatherBug3 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 UltraWeatherBug3 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 doesn't 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 Homeseer3.0 or greater 4
UltraWeatherBug3 HSPI Installation Downloading the HomeSeer Plug-in 1. From your HomeSeer web page, select PLUG-INS > Manage. 2. Click the + icon next to Additional Interfaces to expand the list of available HomSeer3 plug-ins. 3. Click the + icon next to the Weather Plug-ins category, then click the checkbox next to the UltraWeatherBug3 (WeatherBug) package to mark the plug-in for installation. 4. Under Pending Updates/Installs, click the Download and Install button. 5. Once the installer finishes, find the UltraWeatherBug3 plug-in under Installed Plug-Ins, then enable it. UltraWeatherBug3 HSPI Setup Before you begin to configure the UltraWeatherBug3 plug-in, you ll need to register for a WeatherBug - Earth Networks API key. As of How to Purchase Your WeatherBug Pulse API Key 1. Sign up for a WeatherBug User account at https://login.enterprise.weatherbug.com/register 2. Check your inbox and follow the instructions WeatherBug sent you by email. 3. Click the "Subscriptions" option in the toolbar, then click on Subscribe to our Pulse API link. 4. Select Basic $20 per month plan, then click subscribe now and follow the onscreen instructions to complete payment 5. Once you have successfully subscribed to a plan, click the Manage API option in the toolbar. 6. From the UltraWeatherBug > Options > WeatherBug API Key section, copy and paste the Primary Key and Secondary Key into the text boxes provided, then click Save Options. UltraWeatherBug3 HSPI Configuration Web Page Layout The UltraWeatherBug3 plug-in has seven web pages that provide access the available features of the plug-in. 5
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. UltraWeatherBug3 HSPI Options All options are set from the Options web page. The following options are supported: 1. Consumer Key This is the Pulse API consumer key issued by WeatherBug. See UltraWeatherBug3 HSPI Setup for more information. 2. Secret key This is the Pulse API secret key issued by WeatherBug. 3. Unit Type Specify the preferred unit types (e.g. U.S. customary units or metric system units). 4. Station Update Specify how often to check the WeatherBug tracking station for updated live weather data. 5. Forecast Update - Specify how often to check for the weather forecast for the defined tracking stations. 6. Alerts Update Specify how often to check for weather alerts. 7. Email To The e-mail address used to send the e-mail notifications to. 8. Email From The e-mail address used to send the e-mail notifications from. 9. Email Subject The e-mail subject template. The following variables are expanded when the email notification is sent: 6
a. $station (e.g. Station1, Station2, etc.) b. $notification-type (e.g. Weather Forecast, Weather Alert) 10. 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-rate f. $heat-index g. $feels-like h. $dew-point i. $dew-point-rate j. $humidity k. $humidity-rate l. $gust-direction m. $gust-speed n. $gust-time o. $wind-speed p. $wind-speed-avg q. $wind-direction r. $wind-direction-avg s. $rain-month t. $rain-rate u. $rain-today v. $rain-year w. $pressure x. $pressure-rate y. $visibility z. $visibility-rate aa. $ob-date bb. $current-condition cc. $todays-temperature-day dd. $todays-temperature-night ee. $todays-short-prediction-day ff. $todays-short-prediction-night gg. $tomorrows-temperature-day hh. $tomorrows-temperature-night ii. $tomorrows-short-prediction-day jj. $tomorrows-short-prediction-night kk. $2-day-temperature-day ll. $2-day-temperature-night 7
mm. $2-day-short-prediction-day nn. $2-day-short-prediction-night oo. $3-day-temperature-day pp. $3-day-temperature-night qq. $3-day-short-prediction-day rr. $3-day-short-prediction-night ss. $last-alert-type tt. $last-alert-title 11. 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. 12. 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 13. Register Link If set to Yes, the UltraWeatherBug3 button will be displayed on all web pages. 14. Debug Mode If set to Yes, the plug-in will write verbose logging to the HomeSeer log file. UltraWeatherBug3 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-rate f. $heat-index g. $feels-like h. $dew-point i. $dew-point-rate j. $humidity k. $humidity-rate l. $gust-direction 8
m. $gust-speed n. $gust-time o. $wind-speed p. $wind-speed-avg q. $wind-direction r. $wind-direction-avg s. $rain-month t. $rain-rate u. $rain-today v. $rain-year w. $pressure x. $pressure-rate y. $visibility z. $visibility-rate aa. $ob-date bb. $current-condition cc. $todays-temperature-day dd. $todays-temperature-night ee. $todays-short-prediction-day ff. $todays-short-prediction-night gg. $tomorrows-temperature-day hh. $tomorrows-temperature-night ii. $tomorrows-short-prediction-day jj. $tomorrows-short-prediction-night kk. $2-day-temperature-day ll. $2-day-temperature-night mm. $2-day-short-prediction-day nn. $2-day-short-prediction-night oo. $3-day-temperature-day pp. $3-day-temperature-night qq. $3-day-short-prediction-day rr. $3-day-short-prediction-night ss. $last-alert-type tt. $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 UltraWeatherBug3 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 UltraWeatherBug3 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 UltraWeatherBug3 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 UltraWeatherBug3 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 UltraWeatherBug3 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 UltraWeatherBug3 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 UltraWeatherBug3 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 UltraWeatherBug3 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 UltraWeatherBug3 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. UltraWeatherBug3 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 UltraWeatherBug3 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 UltraWeatherBug3 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
UltraWeatherBug3 HSPI Triggers UltraWeatherBug3 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 UltraWeatherBug3 HSPI Trigger Actions UltraWeatherBug3 E-Mail Notification This action causes a weather condition, weather forecast or weather alert to be generated for the selected station. 12
UltraWeatherBug3 Speak This action causes HomeSeer to speak with current weather conditions, forecast or weather alert for the selected station. UltraWeatherBug3 HSPI Trigger Conditions UltraWeatherBug3 HSPI conditions allow you to specify that certain conditions must exist before a HomeSeer event will run. UltraWeatherBug3 Conditions Supported 1. Current Conditions 2. Today s Prediction 3. Tomorrow s Prediction The HomeSeer conditions support the following condition categories: 13
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" UltraWeatherBug3 HSPI API Reference To be determined 14