Wunderground PWS Weather Trigger

Version 1.16

What this driver does

Polls a Weather Underground Personal Weather Station (PWS) every few minutes and exposes live weather readings as RTI system variables. Up to 10 configurable threshold rules can fire RTI macros (or events) when readings cross levels. Also exposes sunrise / sunset, wind compass direction, and lightning events. Use it for: retract awnings on high wind, close windows on rain, change HVAC modes on temperature, scene changes at sunset, alert on UV high, lightning notifications, etc.

Licence (free, sign-up required)

This driver is free, but a licence key is required to keep firing macros / events past a 120-minute trial. Live weather readings always keep updating - only the threshold triggers pause once the trial ends.

1. Add the driver in Integration Designer and open Driver Properties.

2. Under System Variables, read MAC For Key- this processor's MAC address.

3. Sign up for a free account at the Smart Home Programming store and request a licence key for that MAC.

4. Paste the key into the Licence Keyfield under the Licence category. The status changes to "Licensed" and triggers run permanently.

The Licence Statusand Trial Time Remainingsystem variables show the current state. The Trial Warning(5 minutes left) and Trial Expiredevents let you put a reminder on a panel.

Finding your station ID

A PWS station ID is a string like IDOONANT3 or IBRISBAN287. Find one near your house in one of three ways:

Method 1 - WunderMap (recommended, visual)

1. Open https://www.wunderground.com/wundermap in a browser.

2. Type your suburb in the search box top-left, or pan / zoom to your area.

3. Coloured dots mark every PWS. Click any one.

4. The popup shows the station ID at the top - copy it.

Method 2 - Search wunderground.com

1. Go to https://www.wunderground.com

2. Type your suburb / postcode in the search bar.

3. Scroll down to the "Nearby Weather Stations" section.

4. Click any station name. The browser URL changes to wunderground.com/dashboard/pws/IXXXXXXX - the part after /pws/ is the station ID.

Method 3 - Google

Search for: "wunderground PWS YOUR_SUBURB"- the first result is usually a dashboard URL containing the station ID.

Tips for picking a good station

- Closer is better. 1-3 km radius is fine. Beyond 5 km the weather may differ noticeably.

- Look for the green QC tick on the map - it means Wunderground's quality control is passing.

- Avoid stations that haven't updated for several hours.

- Some stations report extras (lightning, solar) - others only basics. Click the station's dashboard page to see what fields it publishes.

Quick start

1. Find a PWS using the methods above and copy its ID.

2. Paste the station ID into the driver's Station ID config field.

3. Leave the API Key field at its default value - it works for any public PWS without signup.

4. Pick the number of threshold slots you need (0-10) under Threshold Slots.

5. Configure each slot: a friendly name, parameter, comparison, threshold value, hysteresis, and a macro to run.

6. Push to processor. The driver polls every 5 minutes by default.

Threshold rules explained

Each slot watches one weather reading (temp, wind, rain, etc.) and fires when the value crosses your threshold. Pick the comparison mode:

- Crosses Above - fires once when value goes from below to above the threshold. Use for "wind got dangerous", "temp got hot".

- Crosses Below - fires once when value drops below threshold. Use for "wind safe again", "temp got cold".

- While Above - fires every poll while value is above. Use for continuous-state alarm panels.

- While Below - fires every poll while value is below.

Hysteresis prevents flapping if the reading hovers near the threshold. Example: Crosses Above 50, hysteresis 5 - fires when value > 50, then has to drop to 45 or below before it can fire again.

Slot Name (display label)

Each slot has a "Slot Name" field. Whatever you type appears in the IDesign Events tab so the trigger reads "Slot 1 - Strong Wind Gust > Triggered" instead of a generic "Slot 1". This makes macros much easier to wire when you have 10 slots active.

Combine With Slot (AND logic)

Each slot can be linked to another slot. The current slot only fires when BOTH itself and the linked slot are tripped. Use for compound conditions:

- Slot 1: Wind Gust / While Above / 40 (the "windy" half)

- Slot 2: Rain Rate / Crosses Above / 0.5 / Combine With = Slot 1

- Result: Slot 2 fires only when rain starts AND it's already windy. (i.e. "storm conditions")

Leave Combine With set to Disabled for standalone slots. For three-way AND logic, build that in your RTI macro using "system variable test" against the Slot N Tripped sysvars.

Pairing slots for symmetric automation

Common pattern: two slots together for "do X when high, undo X when safe again":

- Slot 1: Wind Gust / Crosses Above / 50 / hysteresis 5 / Macro = Retract Awnings

- Slot 2: Wind Gust / Crosses Below / 45 / hysteresis 0 / Macro = Restore Awnings

The hysteresis gap between 45 and 50 stops oscillation if gust hovers near 50.

Macro picker vs event tag

Each slot offers two ways to trigger automation:

Run Macro (preferred) - dropdown of every macro in your project. Pick one and the driver runs it directly when the slot fires.

Or Event Tag (legacy) - type a custom event tag string. Wire it to a macro via the Events tab in IDesign.

A generic event tag SLOT1_TRIP, SLOT2_TRIP, etc. always fires regardless.

Available tags and system variables

Key sysvars exposed by the driver:

- Temp / HeatIndex / WindChill / Dewpoint / Humidity / Pressure - current atmospheric readings

- WindSpeed / WindGust / WindDir / WindDirCompass - wind readings

- RainRate / RainTotal / IsRaining - precipitation

- UV / SolarRadiation - solar readings

- SunriseTime / SunsetTime / IsDaylight / MinutesToSunrise / MinutesToSunset - solar schedule

- WindFromN/NE/E/SE/S/SW/W/NW - 8-point compass booleans for macro conditions

- LightningSupported / LightningStrikeCount / LightningDistance / LightningLastTime - lightning data

- Slot1Tripped .. Slot10Tripped - boolean trip state per threshold slot

- Online / LastUpdate / LastUpdateAge / LastError - connection status

- StationID / Neighborhood / Country / Latitude / Longitude - station metadata

- LicenceValid / LicenceStatus / TrialActive / TrialTimeRemaining / MACForKey - licence state

- BrowseList / BrowseTitle - Browse Menu list widget binding

Key events:

- STATION_ONLINE / STATION_OFFLINE / API_KEY_INVALID / CONNECTION_ERROR - connection events

- RAIN_STARTED / RAIN_STOPPED - precipitation edge events

- SUNRISE / SUNSET - solar schedule events

- WIND_FROM_N/NE/E/SE/S/SW/W/NW - wind compass shift events

- LIGHTNING_DETECTED / LIGHTNING_NEARBY - lightning events

- SLOT1_TRIP .. SLOT10_TRIP - per-threshold trigger events

- TRIAL_WARNING / TRIAL_EXPIRED - licence lifecycle events

Key functions:

- Poll Now - force an immediate data fetch

- Reset All Trip Flags - clear every slot's tripped state and re-arm

- Reset Slot Trip Flag - clear and re-arm one specific slot

- Browse Select / Browse Back / Show Browse Home - Browse Menu navigation (wire via Browse / Browse Back / Browse Home tags)

Sunrise and sunset events

Calculated from the station's lat / long using NOAA solar geometry. Recomputed daily at midnight. Two events fire:

- SUNRISE - at sunrise local time

- SUNSET - at sunset local time

Configurable offsets (Sun and Lightning Tuning category):

- Sunrise Offset - minutes before / after actual sunrise. e.g. -30 means fire 30 min BEFORE sunrise (open blinds early). +60 means fire 60 min after.

- Sunset Offset - same idea for sunset (close blinds 30 min before sunset).

Related sysvars:

- SunriseTime / SunsetTime - HH:MM strings of today's actual times.

- IsDaylight - boolean, true during daylight hours.

- MinutesToSunrise / MinutesToSunset - countdowns updated every poll.

Wind from compass

The driver reduces the 16-point compass to 8 cardinal directions and fires an event each time the wind shifts. Eight events available: WIND_FROM_N, WIND_FROM_NE, WIND_FROM_E, WIND_FROM_SE, WIND_FROM_S, WIND_FROM_SW, WIND_FROM_W, WIND_FROM_NW.

Eight matching boolean sysvars (WindFromN, WindFromNE, etc.) let your macros do conditional logic like "fire if wind from any northerly direction" = WindFromN OR WindFromNE OR WindFromNW.

Lightning events

The driver listens for lightning fields in the observation. Many stations don't report lightning - check the LightningSupported sysvar to confirm. Stations that DO report it (e.g. Tempest, some Ambient Weather and newer Ecowitt models):

- LIGHTNING_DETECTED - fires whenever the per-hour strike count increases

- LIGHTNING_NEARBY - fires when the nearest reported strike is within the proximity threshold (default 10 km, configurable)

Related sysvars: LightningStrikeCount, LightningDistance, LightningLastTime.

System events

Beyond per-slot triggers and the above, the driver fires:

- STATION_ONLINE - fresh data resumed after being stale.

- STATION_OFFLINE - no fresh data for the configured stale window (default 20 min).

- API_KEY_INVALID - HTTP 401 from the API.

- CONNECTION_ERROR - any other HTTP error.

- RAIN_STARTED / RAIN_STOPPED - precipitation rate edge events.

Each of these can also have an optional macro picker under System Event Macros.

Web Object dashboard

The driver pushes a live snapshot of all readings to a cloud dashboard. To add it to your touchpanel:

1. In IDesign, add a Web Object to a page.

2. Set the URL to: https://shpdrivers.services/wupws/?mac=YOUR_PROCESSOR_MAC

3. Replace YOUR_PROCESSOR_MAC with the processor's MAC address with colons stripped (e.g. 0015260AEC70 for MAC 00:15:26:0A:EC:70).

The dashboard shows current temp, weather icon, wind / humidity / rain / UV cards, sunrise / sunset, and a gear icon opening a theme picker (background, accent, card shadow, border, backdrop overlay). Settings save per-device.

Disable cloud push by un-ticking "Enable Cloud Dashboard" under the Web Object Dashboard config category.

Browse Menu (for remotes without Web Objects)

For hardware remotes (T-class, ISR and any panel that can't render a Web Object), the driver provides an on-screen weather list with icons. It mirrors the dashboard: Current Conditions, 5-Day Forecast, Wind, Sun and UV, Lightning, Alerts, and Station Status. Tap a category to drill in; tap Back to return to the home list.

Wiring it up (one drag each):

1. Add a List widget to a page. Drag the Browse tag onto it. IDesign auto-binds the list contents AND the row-selection handler - no macros needed.

2. Optionally add a button and drop the Browse Back tag on it (returns to the home list).

3. Optionally add a button and drop the Browse Home tag on it (jumps to the home list from anywhere).

4. To show the current category name as a heading, bind a text field to the BrowseTitle system variable.

The list updates itself every time new weather data arrives, so on-screen values stay current. "Refresh Now" rows force an immediate poll; "Reset All Trip Flags" (under Alerts) clears tripped slots.

Row icons are small weather PNGs fetched from the cloud (sun, cloud, rain, storm, thermometer, wind, etc.). They load automatically with no setup. If you self-host them instead, set the "Icon Base URL" field under the Browse Menu config category. If a panel can't reach the internet the menu still works - rows simply show without icons.

If the default API key stops working

The default API key (e1f10a1e78da46f5b10a1e78da96f525) is the one Wunderground's own dashboard uses. It has been stable for years but can theoretically change. If you ever see API_KEY_INVALID events:

1. Open https://www.wunderground.com/dashboard/pws/IDOONANT3 (any public PWS) in Chrome.

2. Press F12 to open Developer Tools, click the Network tab.

3. Refresh the page. Look in the Network list for any request to api.weather.com.

4. The request URL contains apiKey=XXXXXXXX... - copy that 32-character key.

5. Paste it into the driver's API Key config field.

Rate limit

The Wunderground API allows 1500 calls per day per key. At the default 5-minute poll interval the driver makes 288 calls/day - well within budget. Don't poll faster than every 1 minute.

Units

- Metric (default) - degrees C, km/h, mm, hPa

- Imperial - degrees F, mph, inches, inHg

- UK Hybrid - degrees C, mph, mm, hPa (UK convention)

Threshold values must be in the same units as your selection. Wind direction is always degrees (0-360).

Manual functions

- Poll Now - force an immediate fetch outside the schedule.

- Reset All Trip Flags - clear every slot's tripped state and re-arm.

- Reset Slot Trip Flag - clear and re-arm one specific slot.

Debug console

The driver opens a TCP listener on port 12520 (configurable). Telnet to it from any machine on the LAN:

telnet PROCESSOR_IP 12520

Type help() for a list of commands: pollNow(), dumpState(), dumpSlots(), dumpConfig(), dumpReadings(), simulateValue("temp", 40). Useful for live troubleshooting and threshold testing.

Support

Email: david@smarthomeprogramming.com.au

Web: smarthomeprogramming.com.au