Xweather Weather

Version v3.7

This driver provides independently selectable weather, current air quality, air quality forecast, tides, localized threats, tropical cyclones, and API usage feedback from the Xweather Weather API. All data features default to disabled.

Integration Designer Setup

1. Add Xweather Weather to the RTI project.

2. Open Driver Properties.

3. During the configured evaluation period, License Key may remain blank.

4. Leave API Base URL at https://data.api.xweather.com unless Xweather has supplied a replacement base URL. Do not include an endpoint or trailing slash.

5. Leave Weather Icon Base URL at https://cdn.aerisapi.com/wxicons/v2 unless a replacement icon host is required. Do not include an icon filename or trailing slash.

6. Enter the Xweather Client ID and Client Secret from the API Keys section of the Xweather web site (https://data.portal.xweather.com/account/keys).

7. Enter the Location. Locations accepted by XWeather are latitude,longitude (e.g., 4.7980,-93.5269); postal code (e.g., 55397); or (e.g., shakopee,mn). Latitude and longitude are recommended for an exact site.

8. Under Features, select Weather, Air Quality, Air Quality Forecast, Tides, Threats, and/or Tropical Cyclones as required. Air Quality Forecast is available only when Air Quality is selected. Tides is limited by Xweather to United States coverage. Threats and Tropical Cyclones have global coverage, although some Threats fields are United States specific. When every feature is disabled, the driver makes no Xweather API requests.

If Tropical Cyclones is selected, choose Global Active Cyclones or Within Radius of Location. For Within Radius of Location, configure a radius from 50 through 5,000 and select Miles or Kilometers under Tropical Cyclone Radius Units. Radius Units is independent of Display Units. Global scope does not filter by Location.

9. If Weather, Tides, Threats, or Tropical Cyclones is selected, choose the required Display Units profile. Individual measurement values do not include a unit suffix; use the Units variable section for GUI labels. Combined weather strings include applicable unit labels.

10. Review the polling intervals and API low-balance threshold.

Current Air Quality and Air Quality Forecast are currently metered by Xweather at 5x.

The Tides default is once daily and is currently listed at 1x.

Threats defaults to 15 minutes and would use approximately 2,880 accesses per 30-day month if billed at 1x.

Tropical Cyclones defaults to 180 minutes and would use approximately 240 accesses per 30-day month at the currently listed 1x cost.

X-Cost-Tokens is authoritative.

11. Enable Trace for normal commissioning logs. Enable Verbose Trace only when complete diagnostic logging is required.

12. When Weather is enabled, display an Xweather icon by drawing a Dynamic Image object and binding its Image feedback to Current Conditions - Weather Image or the required Forecast Day - Weather Image. Do not bind the Dynamic Image to Icon Filename.

Each RTI interface displaying an icon must be able to reach the configured Weather Icon Base URL through DNS and HTTPS.

As an alternative to Dynamic Images, Current Conditions and each Forecast Day publish RTI Condition Index and RTI Weather Icon Index. RTI Condition Index is the normalized 0-19 semantic condition. Bind the 0-39 RTI Weather Icon Index to a 40-state GUI object containing RTI weather artwork in the established state order. Indexes 0-19 are daytime graphics and 20-39 are their nighttime equivalents. RTI artwork is not included with this driver.

13. Add visible Xweather attribution to any interface displaying Xweather data using static text labeled Powered by Vaisala Xweather.

Current Functionality

Direct communication between the RTI XP processor and Xweather

Known and documented weather-data provider

Customer-controlled Xweather API credentials

No dependency on a weather relay

Current conditions

Ten-day forecast

Dynamic weather images

Extensive weather-alert data, states and events

Sunrise, sunset, civil twilight, astronomical twilight and lunar information

Runtime location selection

Standard, Metric, Metric SI and UK Mixed Units profiles

Runtime unit-profile selection

Transparent API request-cost and rate-limit feedback

Configurable polling intervals with estimated monthly usage

Detailed diagnostics and optional verbose TraceViewer logging

Independent enable/disable selection for Weather, Current Air Quality, Air Quality Forecast, Tides, localized Threats, and Tropical Cyclones

Current AQI, category, Health Index, dominant pollutant, sources and individual pollutant measurements

Five-day Air Quality Forecast with daily AQI, Health Index, warning state and pollutant details

Predicted high/low tides, station metadata, next-event feedback and High Tide/Low Tide events for supported United States locations

Localized storm summaries, distance, movement, hail, rotation, tornadic, advisory, radar and lightning threat feedback

Global or radius-filtered active tropical cyclones, current position and intensity, coastal watches/warnings, and primary-cyclone forecast feedback

2,260 unique RTI feedback variables across weather, air quality, forecasts, alerts, sun/moon, tides, localized threats, tropical cyclones, RTI compatibility companions, API usage, rate limits, licensing and diagnostics

RTI Variable Tagging

The driver assigns supported standard RTI weather tags so compatible values can be located through Integration Designer’s Tag Browser and used by interfaces or system components that consume standard weather tags. Tagging supplements the normal driver variable tree; it does not change polling, events, API use or direct variable binding.

Standard tags are assigned directly to Resolved Location Place Name, State and Country; Current Conditions text and RTI Weather Icon Index; current Temperature, Feels Like, Dew Point, Humidity, Wind Speed, Wind Gust and Visibility; and the Day Index, Condition Text, RTI Weather Icon Index, High Temperature, Low Temperature, Humidity, Precipitation Probability, Wind Direction Index and Wind Speed values for Forecast Days 1 through 5.

Some RTI weather tags require legacy string or enumerated-integer formats that differ from the driver’s primary typed feedback. Version 3.3 places these companion values beside the data they describe in Current Conditions, Units and each Forecast Day.

Pressure (RTI Tag) is supplied as a formatted string.

Pressure Direction Index uses 0 for Steady, 1 for Rising and 2 for Falling. Until enough observations exist to calculate a trend, the compatibility value is 0 because the RTI tag format has no Unknown state; the primary Pressure Direction variable reports Unknown during that period.

Wind Direction Index uses 1 through 16 for N through NNW, 17 for Calm and 0 for Variable or unavailable.

Temperature Units Index uses 0 for F and 1 for C.

Speed Units Index uses 0 for mph, 1 for km/h and 2 for m/s.

Pressure Units Index uses 0 for inches, 1 for hPa and 2 for mmHg. The current driver profiles publish only 0 or 1.

Distance Units Index uses 0 for miles and 1 for kilometers.

Every Forecast Day exposes Day Index using 0 for Monday through 6 for Sunday, with 7 representing unavailable or unknown. RTI standard Day tags are assigned only through Forecast Day 5.

Current Conditions and every Forecast Day expose RTI Condition Index using 0 through 19 for the established RTI condition states, as well as RTI Weather Icon Index using 0 through 39 for daytime and nighttime artwork.

Every Forecast Day exposes Wind Direction Index using the same RTI enumeration as Current Conditions.

For a custom GUI, use the Xweather Condition Text, weekday text, Wind Direction and typed measurements unless an RTI tag-aware or state-driven object requires an index. RTI’s current standard weather tag schema defines this forecast schema only through Day 5. Forecast Days 6 through 10 publish the same text and companion indexes but remain intentionally untagged.

Requirements

Each installation requires its own Xweather account and API credentials. Xweather's Pay-as-you-go plan currently includes up to 15,000 metered accesses per month at no charge. Select only the required features and review their polling estimates.

Enabling every feature at its default interval would use approximately 14,820 accesses per 30-day month if Threats and Tropical Cyclones are billed at 1x, leaving too little margin for startup, manual refreshes or other API use.

Under Xweather's current Pay-as-you-go pricing, the first 15,000 metered accesses each month are free and each access above that allowance costs $0.0006.

For example:

16,000 total monthly accesses means 1,000 billable accesses and an estimated charge of $0.60

20,000 total accesses means 5,000 billable accesses and an estimated charge of $3.00

25,000 total accesses means 10,000 billable accesses and an estimated charge of $6.00; and

30,000 total accesses means 15,000 billable accesses and an estimated charge of $9.00

These examples exclude taxes and any other account charges. Xweather's current pricing page and billing portal remain authoritative.

Please note that Xweather measures API accesses rather than simply counting HTTP requests. Certain endpoints may have higher multipliers. The driver provides per-request access cost, driver-session accesses and API rate-limit feedback.

The polling estimates shown in the driver account only for requests generated by this driver. They do not include accesses generated by other applications or Xweather products, such as weather maps, discovery scripts, additional drivers or direct API testing.

Xweather does not expose private account billing data through the Weather API. The driver therefore cannot reproduce the billing portal's month-to-date accesses, free-tier progress, estimated cost or projected cost. The Xweather Subscription and Billing portal remains authoritative for account-wide usage and monetary cost.

Commands

Set Unit Type selects Standard, Metric, Metric SI, or UK Mixed Units presentation values at runtime. When Weather is enabled, it refreshes Conditions and Forecast. The corresponding Units boolean variables provide button feedback.

Set Location accepts an Xweather location in the same format as the Location setting in the Xweather API section of the Driver Properties. Set Location clears feedback for the prior location, and refreshes only enabled endpoints.

To create a city menu, place the city's Set Location command before the Page Link in that city button's macro.

These commands are runtime overrides and revert to the Driver Properties selections after the driver, processor, or project restarts.

Refresh All Enabled Data requests every enabled endpoint. Individual refresh commands request only their applicable enabled service; commands for disabled services are rejected without consuming an API access.

Refresh Current Air Quality, Refresh Air Quality Forecast, Refresh Tides, Refresh Threats, and Refresh Tropical Cyclones request their respective enabled endpoints.

Set Location clears prior-location feedback and refreshes only enabled services.

Successful command-generated refreshes for enabled services consume API accesses.

Feedback and Events

Use Display Units to select Imperial or Metric values.

Use Wind Direction Format to select full friendly names, such as West-Southwest, or abbreviations, such as WSW. Wind Direction contains this compass text; Wind Bearing contains the corresponding value from 0 through 360. Use the weather variables directly for formatted GUI text. Variable names do not include a Display suffix.

Current Conditions provides concise condition text such as Partly Cloudy in the Current Conditions variable. Current Conditions Summary retains the composed condition, temperature, feels-like, wind, and gust presentation. The category also includes coded-weather boolean states, snowfall feedback, and a calculated Pressure Direction.

Pressure Direction is Unknown until two successful condition samples are available.

Each of the ten Forecast Day sections includes the full weekday, abbreviated weekday, and Sunrise/Sunset formatted Time, Time (24), and clock components. Sunrise, Sunset, Solar Transit, Moonrise, Moonset, Moon Transit, Civil Twilight Begin/End, and Astronomical Twilight Begin/End retain the original API date/time and provide ready-to-display Time and Time (24) strings plus 24-hour, AM/PM, 12-hour, minute, and second components. Hour (24), Minute, and Second are two-character presentation strings that retain leading zeros in composite button text. Their corresponding Value variables are typed integers for comparisons and numeric logic. The 12-hour Hour remains an integer and conventionally has no leading zero. Use Time or Time (24) when a complete time is sufficient.

Alert Issued, Begins, Expires, and Updated values retain the original ISO timestamp and provide Date, Time, and Time (24) strings.

Xweather can omit moonrise or moonset when that event does not occur during the requested local calendar date.

Current Weather and Temperature Increase/Decrease events fire only after the first conditions response establishes a baseline.

Sun and Moon feedback represents the current day, while event timers select the next future occurrence from the current and following day returned by Xweather.

Weather-alert events are generated only after the first successful alert request establishes a baseline. A successful no-data alert response means that no active alerts exist.

The Last Alert Event variables identify the action, ID, name, type, category, emergency state, and priority associated with alert lifecycle, emergency-alert, and highest-priority-alert events. Lower numeric priority values represent more significant alerts.

API Usage and Rate Limits contains the last request endpoint, access cost, cost multipliers, driver-session accesses, minute request limits, billing-cycle reset, calculated cycle days remaining and period-rate-limit status. Driver Session Accesses resets when the driver starts and does not represent account-wide month-to-date usage.

Period Rate Limit Enforced and Period Rate Limit Status distinguish an enforced positive API period limit from a zero/zero PAYG response. Xweather's period rate-limit headers do not represent the Pay-As-You-Go (PAYG) plan's included 15,000 accesses.

Current Air Quality provides AQI, category, category-state booleans, dominant pollutant, Health Index, sources, stations, summary, and available Ozone, PM2.5, PM10, Carbon Monoxide, Nitrogen Dioxide, Sulfur Dioxide, and PM1 measurements.

Air Quality Forecast provides up to five daily periods with the same pollutant detail, highest-AQI and warning feedback. Pollutant PPB and micrograms-per-cubic-meter values include availability booleans because Xweather can omit unsupported measurements. AQ events establish a baseline on the first successful response and fire only on later transitions.

Current Air Quality and each of the five Air Quality Forecast periods provide Air Quality Guidance derived from the standard AQI category. Use this text with the category and color feedback so an interface does not depend on color recognition alone. The driver generates the guidance from published EPA AirNow category guidance; Xweather does not return this wording verbatim.

Current Air Quality and each forecast period also provide Health Guidance for Xweather's separate Low, Moderate, High, and Very High Health Index scale.

AQI Green means Good, while Health Index Blue means Low health risk; use the applicable guidance and category so users do not need to interpret the two-color systems.

Color Feedback for RTI Interfaces

Xweather returns six-character hexadecimal color codes, but RTI interfaces cannot directly render those text codes as colors. The driver therefore provides three coordinated variables for every Current Air Quality, Air Quality Forecast, individual pollutant, Health Index, and Weather Alert color:

Color Hex retains the normalized uppercase Xweather value without a leading #. It preserves the authoritative source value for diagnostics and custom integrations.

Color Index is an RTI integer intended for a multistate button, icon, panel or other feedback object.

Color Name is presentation-ready text for labels, diagnostics and interfaces where a color alone would be unclear or inaccessible.

Color Index uses the same palette everywhere in the driver:

0 - Unknown or unavailable

1 - Green

2 - Yellow

3 - Orange

4 - Red

5 - Purple

6 - Maroon

7 - Blue

8 - Cyan / Teal

9 - Pink

10 - Brown / Tan

11 - Gray / Silver

12 - White

13 - Black

The standard AQI scale maps as follows: Good is Green (1), Moderate is Yellow (2), Unhealthy for Sensitive Groups is Orange (3), Unhealthy is Red (4), Very Unhealthy is Purple (5), and Hazardous is Maroon (6).

Xweather's separate Health Index uses a different color scale: Low is Blue (7), Moderate is Green (1), High is Yellow (2), and Very High is Red (4). For example, Current Air Quality may correctly report AQI Green while Health Index reports Blue; these both represent favorable states on their respective scales. Use Air Quality Guidance and Health Guidance to explain the applicable state.

Weather-alert colors use a much larger regional palette. The driver retains the exact source value in Color Hex and assigns Color Index and Color Name to the closest shared color family. Alert name, type, category, priority, emergency state and body remain authoritative; do not use the approximated alert color as the only indication of meaning or severity.

When Xweather omits a color or returns an invalid value, Color Hex is blank, Color Index is 0, and Color Name is Unknown. For GUI design, assign Color Index to a 14-state feedback object, configure states 0 through 13 with the palette above, and display Color Name, Category and the applicable Guidance text wherever users need an explicit explanation.

Tides provides a rolling three-day window with up to 16 high/low predictions, prediction-station details, station distance and bearing, Next High Tide and Next Low Tide feedback, unit-aware heights, and High Tide/Low Tide events. The default daily poll advances the rolling window; Xweather states that the underlying tide predictions update monthly and that tide coverage is limited to the United States.

Threats provides Xweather's latest localized storm summary, source date/time, short and long phrases, approach state, min/average/max distance and movement speed, directions, threat arc, hail, rotation, tornadic, severe-advisory, mesoscale-rotation, radar-intensity and lightning feedback. Explicit availability variables distinguish nullable hail, mesoscale-rotation, radar and lightning objects. Xweather documents global threat coverage, but some detailed radar, hail, rotation, tornadic and NOAA advisory fields are United States specific. Do not interpret a false signature value as a universal safety guarantee. The first response establishes the event baseline; later transitions can fire active, cleared, hail, rotation, tornadic and lightning events.

Threat Data Available and Threat Data Unavailable distinguish valid provider feedback from an unknown state. Active means a successful response contained a localized storm object. Inactive means a successful response confirmed no localized storm object. While loading, after a location change, or when the first request for a location fails, Active and Inactive are both false and Threat Data Unavailable is true. A later transient error preserves the last successful threat values while Threats Status reports the error; use Data Date and Time to identify the retained result's age.

Tropical Cyclones provides up to ten active-system slots. Each slot includes name, ID, basin, classification, category, advisory number, position, movement, sustained wind, gust, pressure, distance/bearing when returned, summary, and NHC coastal breakpoint watch/warning feedback. Five forecast points are provided for the Primary Cyclone, which is Cyclone 1. Global results are not a severity ranking; Within Radius results are limited by the configured Location, radius, and Miles/Kilometers selection. Configured Radius Unit and its Miles/Kilometers boolean feedback can be used for diagnostics or GUI labels. A successful empty response means no active system matches the selected scope.

Tropical cyclone events establish a baseline on the first successful response and fire only on later active/cleared, new, updated, and coastal watch/warning transitions. Coastal breakpoint alerts are available only for applicable Atlantic and East Pacific systems and do not replace local weather-alert feedback. Xweather normally updates tropical-cyclone data every six hours and NHC storms as often as one to three hours near landfall.

Endpoint Polling Health

Endpoint Polling Health reports independent Status, Last Attempt, and Last Success values for every supported endpoint. A successful request to one endpoint therefore cannot conceal a stopped or failing Current Conditions schedule.

Every endpoint timer rearms before beginning its request work. An independent one-minute watchdog uses RTI's System.GetUTCTimeInSeconds clock to recover an endpoint that is overdue by more than its configured interval plus two minutes, provided that no matching request is already active or queued. Watchdog Recoveries, Last Watchdog Endpoint, and Last Watchdog Recovery identify this activity, and Polling Watchdog Recovery can run an RTI macro.

Current Conditions Observation Age is calculated from the API Observation Time. Current Conditions becomes stale when its age exceeds twice the configured Current Conditions poll interval, with a minimum threshold of ten minutes. Data Fresh and Data Stale provide Boolean feedback, and later freshness transitions fire Current Conditions Data Fresh or Current Conditions Data Stale. The first observation establishes the baseline silently. The last reported measurements and icon are retained while stale; use the stale feedback to warn the user rather than presenting fabricated replacement data.

Developed & Supported By

Buttonwood Technologies, LLC

rti@buttonwoodtechnologies.com

https://www.buttonwoodtechnologies.com

Version History

Version 3.7: Standardized dealer documentation, Buttonwood Technologies support information, third-party driver notice and disclaimer, and weather-data safety and operational warnings. Runtime communications, commands, variables, events, and Xweather behavior are unchanged from version 3.6.

Version 3.6: Rearmed endpoint timers before request work; added timer exception handling, overdue-poll watchdog recovery, endpoint-specific Status/Last Attempt/Last Success feedback, and Current Conditions observation-age, stale/fresh feedback, and events. Corrects a field-observed condition in which Current Conditions stopped advancing while Weather Alerts continued successfully.

Version 3.5: Added complete zero-padded Time and Time (24) strings for forecast sunrise/sunset and parsed sun, moon, twilight, and transit events, with presentation and numeric clock components.

Version 3.4: Added two-digit formatting for clock-minute and clock-second presentation.

Version 3.3: Added shared current/forecast weather classification, condition and graphic indexes, weekday and wind-direction indexes, and expanded forecast tagging.

Version 3.2: Added concise Current Conditions text and standard RTI weather tags.

Version 3.1: Added RTI-compatible indexed weather-icon feedback.

Version 3.0: Introduced the expanded multi-service weather architecture and feature-selectable polling.

Version 2.0: Added processor-bound licensing and persistent trial tracking.

Version 1.0: Initial release.

Product Specific Warning

Weather, air-quality, tide, storm, tropical-cyclone, image, and alert data can be delayed, incomplete, unavailable, geographically imprecise, revised, or affected by API, Internet, station, model, and polling limitations. This driver is informational and is not an official warning service, certified forecasting instrument, emergency-management system, or life-safety device. Do not rely on it as the sole source for severe-weather, flooding, marine, air-quality, evacuation, or other safety decisions. Dealers and customers must maintain official government and local-authority warning sources and verify location, units, observation age, service status, and alert coverage.

Third-Party Driver Notice and Disclaimer

This driver is independently developed by Buttonwood Technologies, LLC and is not developed, endorsed, supported, or certified by the manufacturers or service providers with which it interoperates, unless expressly stated otherwise. The driver is provided “AS IS” and “WITH ALL FAULTS,” without warranties of any kind, express or implied, including warranties of merchantability, fitness for a particular purpose, and noninfringement. To the maximum extent permitted by applicable law, Buttonwood Technologies, LLC shall not be liable for indirect, incidental, special, consequential, exemplary, or punitive damages, loss of data, loss of use, service interruption, or lost profits arising from installation or use of the driver. Nothing in this notice excludes or limits liability that cannot lawfully be excluded or limited.