Using Weather Control Variables
The Weather plug-in can pass on to the
Control plug-in, the web and MQTT the current weather info in Table 2, if available in the retrieved weather data.
| Control Variable* | Description | Example |
|---|---|---|
| Station | Station ID of reporting station | KMLB |
| SStation1 | Search Station ID | KMLB |
| ZipCode1,5 | Search Zip code | 32901 |
| Location | Location of reporting station | Melbourne International Airport, FL |
| Country1 | Country of reporting station | USA |
| CityCode2 | Search City code | 132681 |
| Lat1 | Search Latitude | 40 |
| Long1 | Search Longitude | -75 |
| ObservationTime | Time of latest observation | Last Updated on Aug 3, 1:53 PM7 |
| ObservationTimerfc822 | Latest observation in ARPA format | Thu, 3 Aug 2008 13:53:00 -0400 EDT |
| Weather | Current conditions | Light Rain |
| Temp | Temperature string in F & C | 77 F (25 C) |
| TempF | Temperature in degrees F | 77 |
| TempC | Temperature in degrees C | 25 |
| Humidity | Relative humidity | 90 |
| Wind8 | Wind condition string | From the South at 10 MPH Gusting to 23 MPH |
| WindDir | Wind direction string | South |
| WindDegrees | Wind direction in degrees | 180 |
| WindMPH | Wind speed in MPH | 10 |
| WindKPH | Wind speed in KPH | 6 |
| WindKTS | Wind speed in Knots | 16 |
| WindBft | Wind speed in Beaufort scale | 3 |
| WindGustMPH | Wind gusts in MPH | 23 |
| WindGustKPH | Wind gusts in KPH | 37 |
| WindGustKTS | Wind gusts in Knots | 20 |
| Pressure | Barometric pressure string | 29.92" (or: 1013 mb, 760.0 mm) |
| PressureIn | Pressure in inches | 29.92 |
| PressureMb | Pressure in Millibars | 1013 |
| PressureMm | Pressure in Millimeters | 760.0 |
| PressureRate2 | Barometric pressure change string | - |
| PressureRateIn2 | Pressure change in inches | - |
| PressureRateMb2 | Pressure change in Millibars | - |
| PressureRateMm2 | Pressure change in Millimeters | - |
| Dewpoint | Dew point string in F & C | 40F (4 C) |
| DewpointF | Dew point temperature in F | 40 |
| DewpointC | Dew point temperature in C | 4 |
| HeatIndex3 | Heat index string in F & C | 75F (24 C) |
| HeatIndexF3 | Heat index temperature in F | 75 |
| HeatIndexC3 | Heat index temperature in C | 24 |
| Windchill3 | Wind chill string in F & C | 36F (2 C) |
| WindchillF3 | Wind chill temperature in F | 36 |
| WindchillC3 | Wind chill temperature in C | 2 |
| FeelsLike4,6 | "Feels like" temp in current units | 75 |
| Uvi4 | UV index | 3.5 |
| VisibilityMi | Visibility in miles | 10 |
| VisibilityKm | Visibility in meters | 16100 |
| Clouds4 | Cloud Cover in percent | 50 |
| WeatherIcon | File name of current weather icon | ra.png (NWS), 01d.png (OpenWeather) |
| SunRise4 | Today's Sunrise | 07:58:01 AM7 |
| SunSet4 | Today's Sunset | 06:18:10 PM7 |
| IconBase | Web link to icon database | https://openweathermap.org/img/wn |
| FetchTime | Time of last connection attempt | Mar 08, 09:18:00 PM7 |
| FetchStatus | Status of last connection | Succeeded or Failed |
| SearchType1 | station selection type | H (for HV User Location) |
* Case sensitive
Notes:
1 These items are the values to use for station selection, based on the value of SearchType.
The actual station selected may have values different from these.
2 No longer supported.
3 For NWS, downloaded values are used if available, otherwise calculated.
If OpenWeather, these are always calculated.
4 OpenWeather only.
5 Certain zip codes beginning with zeros and with the rest containing only digits in the range 0-7
will be misinterpreted by the Control plug-in as an octal number.
To prevent this, when sent to the control plug-in,
a zip code has 5 spaces and "ZC" appended to it (to force it to be handled as a string instead of a number).
A Control plug-in widget should then use the printf style and %.5s as the spec.
Since zip codes may not even be available, it might be easier to just use FcLoc.
6 Temperatures are expressed according to the Temp Scale setting in the
General Settings tab.
7 Time and Date are expressed according to the Time Format setting in the
General Settings tab.
8 Winds are expressed according to the Wind Speed setting in the
General Settings tab.
The Weather plug-in can pass on to the
Control plug-in, the web and MQTT the forecast weather info in Table 3, if available in the retrieved weather data.
| Control Variable* | Description | Example |
|---|---|---|
| FcCity1 | City of reporting station | Melbourne |
| FcState1 | State of reporting station | FL |
| FcZip2 | Search Zip code | 32901 ZC |
| FcCountry1 | Country of reporting station | US |
| FcLoc1,3 | Location of reporting station | Melbourne, FL 32901 |
| FcLat2 | Search Latitude | 40 |
| FcLong2 | Search Longitude | -75 |
| FcDaym, FcDaynm | Forecast day, night for day m (m = 1-7) | Monday, Monday Night |
| FcScm, FcScnm5 | Short forecast for day, night m | Mostly Cloudy (NWS), 803 (OpenWeather) |
| FcLcm, FcLcnm5 | Long forecast for day, night m | Mostly cloudy |
| FcHim6 | High temperature for day m | 75 |
| FcLom6 | Low temperature for day m | 50 |
| FcTempMornm6,7 | Morning temperature for day m | 60 |
| FcTempDaym6,7 | Daytime temperature for day m | 72 |
| FcTempEvem6,7 | Evening temperature for day m | 65 |
| FcTempNitem6,7 | Nighttime temperature for day m | 50 |
| FcHumiditym7 | Humidity for day m | 50 |
| FcWindm7,10 | Wind condition string for day m | From the South at 10 MPH Gusting to 23 MPH |
| FcWindDirm7 | Wind direction string for day m | From the South |
| FcWindDegreesm7 | Wind direction in degrees for day m | 190 |
| FcWindMPHm7 | Wind in MPH for day m | 10 |
| FcWindKPHm7 | Wind in KPH for day m | 16 |
| FcWindKTSm7 | Wind in Knots for day m | 7 |
| FcWindGustMPHm7 | Wind gusts in MPH for day m | 23 |
| FcWindGustKPHm7 | Wind gusts in KPH for day m | 37 |
| FcWindGustKTSm7 | Wind gusts in Knots for day m | 20 |
| FcPressureInm7 | Pressure in inches for day m | 29.92 |
| FcPressureMbm7 | Pressure in millibars for day m | 1013 |
| FcPressureMmm7 | Pressure in millimeters for day m | 760.0 |
| FcDewpointm6,7 | Dewpoint for day m | 50 |
| FcFLHim6,7,8 | High Feels Like temperature for day m | 75 |
| FcFLLom6,7,8 | Low Feels Like temperature for day m | 50 |
| FcFLMornm6,7 | Morning Feels Like temperature for day m | 60 |
| FcFLDaym6,7 | Daytime Feels Like temperature for day m | 70 |
| FcFLEvem6,7 | Evening Feels Like temperature for day m | 65 |
| FcFLNightm6,7 | Nighttime Feels Like temperature for day m | 50 |
| FcPopm, FcPopnm | Probability of precip. for day, night m | 10 |
| FcUvim7 | UV index | 3.5 |
| FcCloudsm7 | Cloud Cover in percent | 23 |
| FcSunRisem7 | Sunrise for day m | 07:58:45 AM9 |
| FcSunSetm7 | Sunset for day m | 06:18:01 PM9 |
| FcMoonRisem7 | Moon rise for day m | 07:58:45 AM9 |
| FcMoonSetm7 | Moon set for day m | 06:18:01 PM9 |
| FcMoonPhasem7 | Moon Phase for day m | Waxing Gibbous |
| FcImgm, FcImgnm | Forecast icon for day, night m | 01d.png |
| FcTime | Time of latest observation | Mon, 10 May 2010 19:00:00 EST9 |
| FcFetch4 | Time of last connection attempt | Mon, 10 May 2010 19:05:00 EST9 |
| FcFetchStatus4 | Status of last connection | Succeeded or Failed |
| FcIconBase4 | Current web link to icons | http://forecast.weather.gov/images/wtf/ |
| FcSStation2 | Search Station ID | KBLM |
| FcSearchType2 | Station selection type | Z (for ZipCode) |
* Case sensitive
Notes:
1 FcLoc is a combination of FcCity, FcState, zipcode, and FcCountry.
Depending on search type, not all of these values may be available.
For example, if the forecast is fetched by zip code, country typically is not returned.
If not returned, these variables are set to an empty string,
and FcLoc will consist of the remaining values.
2 These items are the values to use for station selection, based on the value of SearchType.
The actual station selected may have values different from these.
3 Certain zip codes beginning with zeros and with the rest containing only digits in the range 0-7
will be misinterpreted by the Control plug-in as an octal number.
To prevent this, when sent to the control plug-in,
a zip code has 5 spaces and "ZC" appended to it (to force it to be handled as a string instead of a number).
A Control plug-in widget should then use the printf style and %.5s as the spec.
Since zip codes may not even be available, it might be easier to just use FcLoc.
4 Generated by plug-in.
5 OpenWeather sets a weather ID code in the short forecast
and detailed text in the long forecast.
NWS forecasts set both FcLc{n}m and FcSc{n}m to the same "short" text.
In either case, both long and short forecasts are affected by the Line Length setting.
6 Temperatures are expressed according to the Temp Scale setting in the
General Settings tab.
7 OpenWeather only.
8 Generated from highest/lowest of FcFLMorn, FcFLDay, FcFLEve and FcFLNight.
Does not necessarily correspond to the same time period as FcHi, FcLo
9 Time and Date are expressed according to the Time Format setting in the
General Settings tab.
10 Winds are expressed according to the Wind Speed setting in the
General Settings tab.
Configuring Variables
Variables can be selected independently for sending to the Control plug-in, web pages via websockets, and to MQTT.
There are a large number of potential variables for current and forecast weather. To avoid having long lists of "user variables" in the Control plug-in, or sending unneeded information through the websocket or via MQTT, a subset of variables can be selected for each method.
- Open the Configuration dialog: Plugins->Weather.
- Select the Ctrl/Web/MQTT Vars tab.
- Select Control, Web, or MQTT in the Variable Type section.
- Select Current to see the Inactive and Active lists of current weather variables for that type. Variables on the Active list will be sent when weather information is fetched.
- To move a variable from one list to the other, double-click it or select the variable(s) and click on the corresponding arrow.
If only the current weather or only the forecast weather is being used, then ALL of the variables of the other type can be put on the Inactive list.
Moving a variable to the Inactive list only prevents that variable from being sent to the Control plug-in in the future. It does NOT explicitly remove it from the Control plug-in. To see newly inactive variable names disappear from the Control plug-in User Variable list, the Control plug-in may need to be restarted (disabled/enabled via the Plugin Manager, for example).
If weather info is being displayed on web pages via the weather websocket, select which variables are sent over the websocket by selecting Web. Then select Current and Forecast and move variables to the Active List to have them sent over the weather websocket. See Weather Websockets for set up details.
If weather info is being sent via MQTT, further setup is necessary. See MQTT Setup below.
Control Screen Weather Variable Setup
Edit the control screen to add labels, buttons, etc. to display the values of the weather variables using the Control Variable names in Table 2 and Table 3. For example, to display the temperature in degrees Fahrenheit on a widget - add a new widget, select a style, and then setup the text tab on the label properties screen similar to this:
The % will be replaced with the value of the TempF variable.
If only one weather variable is used in the widget, then Type can be set to User Variable and Object to the variable desired. If used in expressions, variable name should be surrounded by "${}". Remember that control variable names are case sensitive. See the Control plug-in Help for more information.
To display an icon depicting the current conditions, after adding a new widget and selecting a style, use the image tab to set up the name of the WeatherIcon control variable. The weather site updates icons according to both weather conditions and time of day. Note: not all icons have day and night versions, and any particular station may or may not use the night versions of the icons totally consistent with real time. METAR stations do not support night versions.
The weather icons are dynamically loaded as needed into a weather/images subdirectory of the plug-in directory. This directory should be used for the path to the icon file.
Since most icons are jpeg coded, the Pixane library needs to be loaded for the Control plug-in to display them properly. See the "Control Plug-in - Pixane library" help page for more info on loading Pixane.
A simple label for a weather icon can be set up like this:
Similar icons can be set up for forecast weather using the FcImg variables.
A more complete example of how various weather variables can be displayed is shown below. This display consists of three label widgets: one with just the names of the data, right-justified, a second one abutting it on the right, with data values left-justified, and a third one (like the above example) with just the weather icon image overlaid on the first one near the bottom.
MQTT Setup
When MQTT is selected in the Variable Type section, The MQTT Settings section is enabled for editing.
Sending Weather Information
To send weather information via MQTT, define a State Topic to use. If you wish the state messages to be retained by the MQTT broker, check Set Retain Flag.
Current and forecast weather is sent in separate MQTT messages with the same topic. The payload is in JSON format.
Current weather example (formatted for readability):
{
"wx": {
"location":"Lincroft, New Jersey, US",
"lat":40.36,
"long":-74.13,
"temp":"66 F (19 C)",
"humidity":72,
"pressure":"29.88\"",
"weather":"Clear sky",
"wind":"From the southwest at 3 MPH",
"uvi":0,
"sunrise":"06:50:04 AM",
"sunset":"06:43:59 PM"
}
}
Forecast weather example (formatted for readability):
{
"fc": {
"loc": "Lincroft, New Jersey, US",
"time":"28 Sep 2021 03:33:16 PM",
"day1": {
"clouds": 76,
"day": "Tue",
"flhi": 73,
"lc": "Moderate rain",
"pop": 100
},
"day2": {
"clouds": 1,
"day": "Wed",
"flhi": 65,
"lc": "Clear sky",
"pop": 5
},
"day3": {
"clouds": 17,
"day": "Thu",
"flhi": 61,
"lc": "Few clouds",
"pop": 0
}
}
}
Note that in the forecast payload, there may be some general items, like "loc", and then forecast-day specific items. These are grouped under "day1", "day2", etc.. Only days that have Active variables will show up. For example, if you only made Active items for "Day2" and "Day4", there will be no "Day1", "Day3", "Day5", "Day6" or "Day7" in the JSON payload.
Controlling Weather Settings
To control weather settings via MQTT, define a "Command Topic" to use. The payload to use is identical to "WeatherSetVar" and "WeatherSet".
Examples, assuming the Command Topic is set to "cmnd/weather/set":
Set Location Selection to "HVLatLong":
Topic: cmnd/weather/set
Payload: "WeatherSet HVLatLong"
Set Location Selection to "Lat/Long", with new values:
Topic: cmnd/weather/set
Payload: "WeatherSet LatLong 40 -74"
Set Data Source to "NWS" for both current and forecasts:
Topic: cmnd/weather/set
Payload: "WeatherSet NWS"
Set Data Source to "OpenWeather" for forecasts:
Topic: cmnd/weather/set
Payload: "WeatherSet forecast OpenWeather"
Trigger a Weather fetch in the background:
Topic: cmnd/weather/set
Payload: "WeatherSetVar"
See Triggering Weather Fetches for complete details of the WeatherSet and WeatherSetVar syntax.
Next:
Forecast Examples
HomeVision Controller Weather Variables
Local Weather Data Files
Speaking Weather Data
Triggering Weather Fetches
Weather Websockets
Custom Objects and Websockets
Weather Info for NetIO
See Also:
Introduction to the Weather Plug-in
Web-Based Weather Data
Disclaimer