Difference between revisions of "MythWeather Grabber Script Format"

From MythTV Official Wiki
Jump to: navigation, search
(add required datatypes)
(→‎Animated Map)
 
(18 intermediate revisions by 3 users not shown)
Line 41: Line 41:
 
-->
 
-->
 
==  Static Map ==
 
==  Static Map ==
 +
A static map is an image, which is downloaded to a local file by the
 +
grabber. The map is a string like /dir1/dir2/filename.png. This
 +
represents a local file  /dir1/dir2/filename.png.
 +
 +
Data provided:
 +
 
* smdesc
 
* smdesc
 
* updatetime
 
* updatetime
 
* map
 
* map
 +
* copyright
  
 
== Animated Map ==
 
== Animated Map ==
 +
A animated map is an animated gif image, which is downloaded to a local file by the grabber. The animatedimage is a string like /dir1/dir2/filename.gif. This represents a local file /dir1/dir2/filename.gif
 +
 +
Data provided:
 +
 
* amdesc
 
* amdesc
 
* updatetime
 
* updatetime
 
* animatedimage
 
* animatedimage
 +
* copyright
  
 
== Severe Weather Alerts ==
 
== Severe Weather Alerts ==
Line 73: Line 85:
  
 
= Commands =
 
= Commands =
 +
The below commands are ordered by sequence of being called by MythWeather.
  
 
== The Version Command (-v) ==
 
== The Version Command (-v) ==
  
−
All grabber scripts must return an identifying string when run with the '-v' argument. The command returns a comma separated list of the script name, script version, author, and author's email, and output must end with a newline character.
+
This command is called when MythWeather enters the Screen Setup page. It is used to populate a list of available grabbers, for which the user can subsequently create screens. The command returns a comma separated list of the script name, script version, author, and author's email, and output must end with a newline character. If the script version changes from that stored in the database, MythWeather will repopulate the field list and timeouts as detailed below.
  
 
<pre>
 
<pre>
Line 82: Line 95:
 
BBC-Current-XML,0.2,Stuart Morgan,stuart@tase.co.uk
 
BBC-Current-XML,0.2,Stuart Morgan,stuart@tase.co.uk
 
</pre>
 
</pre>
−
 
−
 
−
== The Timeout Command (-T) ==
 
−
 
−
All grabber scripts must return two timeout values when run with the '-T' argument. The command returns a comma separated list of information lifetime, and web response timeout, in seconds.
 
−
 
−
<pre>
 
−
#./bbccurrentxml.pl -T
 
−
7200,30
 
−
</pre>
 
−
 
  
 
== The Field List Command (-t) ==
 
== The Field List Command (-t) ==
  
−
All grabber scripts must return a list of available data fields, one per line, when run with the '-t' argument.  
+
MythWeather will next pull a supported field list for all new or updated grabbers. This list is used to determine which screen types the grabber can pull information for. When called, the command must return all supported data fields, one per line.
  
 
<pre>
 
<pre>
Line 115: Line 117:
 
</pre>
 
</pre>
  
 +
== The Timeout Command (-T) ==
 +
 +
MythWeather will next pull a supported field list for all new or updated grabbers. The command returns a comma separated list of information lifetime (minutes), and web response timeout(seconds). These specify how long MythWeather will cache the received data, and how long it will wait before erroring.
 +
 +
<pre>
 +
#./bbccurrentxml.pl -T
 +
7200,30
 +
</pre>
  
 
== The Location Search Command (-l <location>) ==
 
== The Location Search Command (-l <location>) ==
  
−
All grabber scripts must return a list of possible location matches, one per line, when run with the '-l' argument. The matches are an identifying string to be used with the data string, and a description, separated by a double colon.
+
After information about the grabber is populated by the previous three commands, users will search for locations for a screen, and MythWeather will pass those searches on to one or more grabbers using the '-l' argument. The responses are an identifying string ("id") to be used with the data string, and a description, separated by a double colon, one per line.
  
 
<pre>
 
<pre>
Line 126: Line 136:
 
</pre>
 
</pre>
  
 +
The id is limited by the weathersourcesettings:sourceid field length, currently 64 characters.
  
 
== The Data Command (-u <unit system> -d <folder> <location string>) ==
 
== The Data Command (-u <unit system> -d <folder> <location string>) ==
  
−
The data command includes a mandatory unit system, and provides a directory path with full read/write access. The location will be that provided by the '-l' command, and the unit system will be one of 'SI' or 'ENG'. The directory can be used to store temporary data or cache results, or can be silently ignored. Data is returned, one value per line, separated from the identifying string by a double colon.
+
After a screen with location has been set up, MythWeather will poll the grabber for data. MythWeather will provide the unit system the information should be returned in, and a directory path will full read/write access, which can be used by the script for cache or temporary data. The location string provided by the '-l' command will be the last argument in the call. The unit system will be one of 'SI' or 'ENG'. Only the information should be changed; no units should be provided. The temp directory can be used or ignored, as needed by the script. Data is returned, one value per line, separated from the identifying string by a double colon.
  
 
<pre>
 
<pre>
Line 148: Line 159:
 
</pre>
 
</pre>
  
−
== Valid Data Types ==
+
If necessary, some fields are allowed to span multiple lines.  The same data type must be prepended at the beginning of each new line.
 +
 
 +
<pre>
 +
#./nws-alert.pl -u ENG 21015
 +
alerts::SHORT TERM FORECAST
 +
alerts::NATIONAL WEATHER SERVICE WILMINGTON OH
 +
alerts::117 PM EDT SUN MAR 28 2010
 +
alerts::INZ066-073>075-080-KYZ089>096-OHZ070>072-077-078-281902-
 +
alerts::BOONE-BUTLER-CAMPBELL-CARROLL-CLERMONT-CLINTON-DEARBORN-FRANKLIN IN-
 +
alerts::GALLATIN-GRANT-HAMILTON-KENTON-OHIO-OWEN-PENDLETON-RIPLEY-
 +
alerts::SWITZERLAND-WARREN-
 +
alerts::117 PM EDT SUN MAR 28 2010
 +
alerts::.NOW...
 +
alerts::SCATTERED LIGHT SHOWERS WILL CONTINUE TO MOVE TO THE NORTHEAST AND
 +
alerts::ACROSS THE LISTENING AREA THROUGH 3 PM. RAINFALL AMOUNTS WILL BE UP
 +
alerts::ONE TENTH OF AN INCH.
 +
swlocation::Boone,KY
 +
updatetime::Last Updated on Mar 28, 01:27 PM EDT
 +
copyright::NOAA,National Weather Service
 +
</pre>
 +
 
 +
= Type Descriptions =
  
 
{| cellpadding="4" border="1"
 
{| cellpadding="4" border="1"
 
| style="background:silver" | '''cclocation'''
 
| style="background:silver" | '''cclocation'''
 
| Descriptive name of location
 
| Descriptive name of location
−
| Text
+
| Data Type
 
|-  
 
|-  
 
| style="background:silver" | '''relative_humidity'''
 
| style="background:silver" | '''relative_humidity'''
Line 165: Line 197:
 
| style="background:silver" | '''wind_spdgst'''  
 
| style="background:silver" | '''wind_spdgst'''  
 
| Wing speed (gust)
 
| Wing speed (gust)
−
| Integer
+
| float
 
|-
 
|-
 
| style="background:silver" | '''wind_dir'''  
 
| style="background:silver" | '''wind_dir'''  
 
| Wind direction
 
| Wind direction
−
| Cardinal
+
| Cardinal, a string like "NNW" or "S"
 
|-
 
|-
 
| style="background:silver" | '''visibility'''  
 
| style="background:silver" | '''visibility'''  
−
|
+
|  
−
| Integer/Range
+
| Integer/Range e. g. "10", "1" or "1-4"
 
|-
 
|-
 
| style="background:silver" | '''appt'''  
 
| style="background:silver" | '''appt'''  
−
|
+
| Apparent temperature, heat index and windchill combo
−
|
+
| Temperature
 
|-
 
|-
 
| style="background:silver" | '''temp'''  
 
| style="background:silver" | '''temp'''  
−
|
+
| Current Temperature
−
|
+
| Integer Degrees
 
|-
 
|-
 
| style="background:silver" | '''weather'''  
 
| style="background:silver" | '''weather'''  
−
|
+
| Weather conditions, free text
−
|
+
| String
 
|-
 
|-
 
| style="background:silver" | '''weather_icon'''  
 
| style="background:silver" | '''weather_icon'''  
−
|
+
| Weather image to show
−
|
+
| filename, as used in the file weather_types.
 
|-
 
|-
 
| style="background:silver" | '''observation_time'''  
 
| style="background:silver" | '''observation_time'''  
−
|
+
| Time of last data update
−
|
+
| String
 
|-
 
|-
 
| style="background:silver" | '''copyright'''  
 
| style="background:silver" | '''copyright'''  
−
|
+
| Copyright information needed for ToS compliance
−
|
+
| String
 
|-
 
|-
 
| style="background:silver" | '''3dlocation'''  
 
| style="background:silver" | '''3dlocation'''  
−
|
+
| Location of forecast
−
|
+
| String
 
|-
 
|-
 
| style="background:silver" | '''6dlocation'''  
 
| style="background:silver" | '''6dlocation'''  
−
|
+
| Location of forecast
−
|
+
| String
 
|-
 
|-
 
| style="background:silver" | '''date-<n>'''  
 
| style="background:silver" | '''date-<n>'''  
−
|
+
| Week day number
−
|
+
| Integer, Sunday=0 .. Friday=6
 
|-
 
|-
 
| style="background:silver" | '''icon-<n>'''  
 
| style="background:silver" | '''icon-<n>'''  
−
|
+
| Weather image to show for date-<n>
−
|
+
| filename, as used in the file weather_types.
 
|-
 
|-
 
| style="background:silver" | '''low-<n>'''  
 
| style="background:silver" | '''low-<n>'''  
−
|
+
| Low temperature forecast for date-<n>
−
|
+
| degrees
 
|-
 
|-
 
| style="background:silver" | '''high-<n>'''  
 
| style="background:silver" | '''high-<n>'''  
−
|
+
| High temperature forecast for date-<n>
−
|
+
| degrees
 
|-
 
|-
 
| style="background:silver" | '''updatetime'''  
 
| style="background:silver" | '''updatetime'''  
−
|
+
| Time of last data update
−
|
+
| String
 +
|-
 +
| style="background:silver" | '''time-<n>'''
 +
| Current hour of forecast
 +
| String
 
|-
 
|-
 
| style="background:silver" | '''18icon-<n>'''  
 
| style="background:silver" | '''18icon-<n>'''  
−
|
+
| Weather image to show for time-<n>
−
|
+
| filename
 
|-
 
|-
 
| style="background:silver" | '''temp-<n>'''  
 
| style="background:silver" | '''temp-<n>'''  
−
|
+
| Temperature forecast for time-<n>
−
|
+
| Integer
 
|-
 
|-
 
| style="background:silver" | '''pop-<n>'''  
 
| style="background:silver" | '''pop-<n>'''  
−
|
+
| Precipitation likelihood for time-<n>
−
|
+
| float (percent)
 
|-
 
|-
 
| style="background:silver" | '''swlocation'''  
 
| style="background:silver" | '''swlocation'''  
−
|
+
| Descriptive name of location, for weather alerts
−
|
+
| String
 
|-
 
|-
 
| style="background:silver" | '''alerts'''  
 
| style="background:silver" | '''alerts'''  
−
| can have multiple lines
+
| Weather alert, can span multiple lines
−
|
+
| String
−
|-
 
−
| style="background:silver" | '''forecastdate'''
 
−
|
 
−
|
 
−
|-
 
−
| style="background:silver" | '''tempforecast'''
 
−
|
 
−
|
 
 
|-
 
|-
−
| style="background:silver" | '''condforecast'''  
+
| style="background:silver" | '''amdesc'''
−
|
+
| Map Description
−
|
+
| String
 
|-
 
|-
−
| style="background:silver" | '''todaypic'''  
+
| style="background:silver" | '''animatedimage'''  
−
|
+
| Animated Map Location
−
|
+
| See [[MythWeather Grabber Script Format#Animated Map]]
 
|-
 
|-
−
| style="background:silver" | '''location'''  
+
| style="background:silver" | '''map'''  
−
|
+
| Static Map Location
−
|
+
| See [[MythWeather Grabber Script Format#Static Map]]
−
}
+
|}
  
−
[[Category:Developer Documentation]]
+
[[Category:Grabber Documentation]]

Latest revision as of 05:32, 13 July 2014

MythWeather grabber scripts are small executable perl, python, or binary applications which query online sources of weather and return it in a format parseable by MythWeather. This page documents the current format required of the grabber scripts to function.

Data Types

MythWeather has six different types of pages. Grabbers are categorized into these types by the data they specify as capable of providing. Grabbers can seamlessly provide data for multiple pages by making sure to meet all the requirements for each.

Current Conditions

  • cclocation
  • relative_humidity
  • pressure
  • wind_spdgst
  • wind_dir
  • visibility
  • appt
  • temp
  • weather
  • weather_icon
  • observation_time
  • copyright

Three Day Forecast

  • 3dlocation
  • date-0 through date-2
  • icon-0 through icon-2
  • low-0 through low-2
  • high-0 through high-2
  • updatetime

Six Day Forecast

  • 6dlocation
  • date-0 through date-5
  • icon-0 through icon-5
  • high-0 through high-5
  • low-0 through low-5

Static Map

A static map is an image, which is downloaded to a local file by the grabber. The map is a string like /dir1/dir2/filename.png. This represents a local file /dir1/dir2/filename.png.

Data provided:

  • smdesc
  • updatetime
  • map
  • copyright

Animated Map

A animated map is an animated gif image, which is downloaded to a local file by the grabber. The animatedimage is a string like /dir1/dir2/filename.gif. This represents a local file /dir1/dir2/filename.gif

Data provided:

  • amdesc
  • updatetime
  • animatedimage
  • copyright

Severe Weather Alerts

  • swlocation
  • alerts

18 Hour Forecast

  • 18hrlocation
  • time-0 through time-5
  • 18icon-0 through 18icon-5
  • temp-0 through temp-5
  • pop-0 through pop-5
  • updatetime


Commands

The below commands are ordered by sequence of being called by MythWeather.

The Version Command (-v)

This command is called when MythWeather enters the Screen Setup page. It is used to populate a list of available grabbers, for which the user can subsequently create screens. The command returns a comma separated list of the script name, script version, author, and author's email, and output must end with a newline character. If the script version changes from that stored in the database, MythWeather will repopulate the field list and timeouts as detailed below. 

#./bbccurrentxml.pl -v
BBC-Current-XML,0.2,Stuart Morgan,stuart@tase.co.uk

The Field List Command (-t)

MythWeather will next pull a supported field list for all new or updated grabbers. This list is used to determine which screen types the grabber can pull information for. When called, the command must return all supported data fields, one per line. 

#./bbccurrentxml.pl -t
cclocation
station_id
copyright
observation_time
weather
temp
relative_humidity
wind_dir
pressure
visibility
weather_icon
appt
wind_spdgst

The Timeout Command (-T)

MythWeather will next pull a supported field list for all new or updated grabbers. The command returns a comma separated list of information lifetime (minutes), and web response timeout(seconds). These specify how long MythWeather will cache the received data, and how long it will wait before erroring. 

#./bbccurrentxml.pl -T
7200,30

The Location Search Command (-l <location>)

After information about the grabber is populated by the previous three commands, users will search for locations for a screen, and MythWeather will pass those searches on to one or more grabbers using the '-l' argument. The responses are an identifying string ("id") to be used with the data string, and a description, separated by a double colon, one per line. 

#./bbccurrentxml.pl -l Cincinnati
407::Cincinnati, Ohio
3231::Cincinnati/Northern Kentucky International, Kentucky

The id is limited by the weathersourcesettings:sourceid field length, currently 64 characters.

The Data Command (-u <unit system> -d <folder> <location string>)

After a screen with location has been set up, MythWeather will poll the grabber for data. MythWeather will provide the unit system the information should be returned in, and a directory path will full read/write access, which can be used by the script for cache or temporary data. The location string provided by the '-l' command will be the last argument in the call. The unit system will be one of 'SI' or 'ENG'. Only the information should be changed; no units should be provided. The temp directory can be used or ignored, as needed by the script. Data is returned, one value per line, separated from the identifying string by a double colon. 

#./bbccurentxml.pl -u ENG 407
appt::NA
copyright::From bbc.co.uk
station_id::407
cclocation::Cincinnati, United States of America
observation_time::Thursday at 13:00 EST
weather::Grey cloud
weather_icon::cloudy.png
temp::43
wind_dir::E
wind_spdgst::9 (NA)
relative_humidity::65
pressure::30.5321117
visibility::10-20

If necessary, some fields are allowed to span multiple lines. The same data type must be prepended at the beginning of each new line. 

#./nws-alert.pl -u ENG 21015
alerts::SHORT TERM FORECAST
alerts::NATIONAL WEATHER SERVICE WILMINGTON OH
alerts::117 PM EDT SUN MAR 28 2010
alerts::INZ066-073>075-080-KYZ089>096-OHZ070>072-077-078-281902-
alerts::BOONE-BUTLER-CAMPBELL-CARROLL-CLERMONT-CLINTON-DEARBORN-FRANKLIN IN-
alerts::GALLATIN-GRANT-HAMILTON-KENTON-OHIO-OWEN-PENDLETON-RIPLEY-
alerts::SWITZERLAND-WARREN-
alerts::117 PM EDT SUN MAR 28 2010
alerts::.NOW...
alerts::SCATTERED LIGHT SHOWERS WILL CONTINUE TO MOVE TO THE NORTHEAST AND
alerts::ACROSS THE LISTENING AREA THROUGH 3 PM. RAINFALL AMOUNTS WILL BE UP
alerts::ONE TENTH OF AN INCH.
swlocation::Boone,KY
updatetime::Last Updated on Mar 28, 01:27 PM EDT
copyright::NOAA,National Weather Service

Type Descriptions

cclocation Descriptive name of location Data Type
relative_humidity Percent humidity Integer
pressure Barometric pressure Float
wind_spdgst Wing speed (gust) float
wind_dir Wind direction Cardinal, a string like "NNW" or "S"
visibility Integer/Range e. g. "10", "1" or "1-4"
appt Apparent temperature, heat index and windchill combo Temperature
temp Current Temperature Integer Degrees
weather Weather conditions, free text String
weather_icon Weather image to show filename, as used in the file weather_types.
observation_time Time of last data update String
copyright Copyright information needed for ToS compliance String
3dlocation Location of forecast String
6dlocation Location of forecast String
date-<n> Week day number Integer, Sunday=0 .. Friday=6
icon-<n> Weather image to show for date-<n> filename, as used in the file weather_types.
low-<n> Low temperature forecast for date-<n> degrees
high-<n> High temperature forecast for date-<n> degrees
updatetime Time of last data update String
time-<n> Current hour of forecast String
18icon-<n> Weather image to show for time-<n> filename
temp-<n> Temperature forecast for time-<n> Integer
pop-<n> Precipitation likelihood for time-<n> float (percent)
swlocation Descriptive name of location, for weather alerts String
alerts Weather alert, can span multiple lines String
amdesc Map Description String
animatedimage Animated Map Location See MythWeather Grabber Script Format#Animated Map
map Static Map Location See MythWeather Grabber Script Format#Static Map
Retrieved from "http://www.mythtv.org/wiki?title=MythWeather_Grabber_Script_Format&oldid=60667"