Ticket #8236: interface.wiki

= Mythweather grabber interface =

== General ==

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. 

The program flows roughly like:

  * myth scans the script directories for executable files. To each
    of them myth issues the -v command. The grabber replies with  
    a version  number (+ additional info). If the version  is 
    unchanged, myth uses already present data in the database. 
    Otherwise:
  * myth issues -t command. The grabber lists what kind of data it 
    provides. If the list is enough to meet the requirements for one 
    or more pages, myth will use it for these.
  * myth issues -T command. Grabber replies with 
    data_timeout(min),http timeout(seconds) e. g., '3600,20'. 
  * User sets up a page using the mythfrontend setup tool. Eventually, 
    she has to search for available data for a specific place. When
    doing so, myth issues -l <search string > command. The grabber 
    replies with a list of possible places matching the user search 
    string.
  * Myth presents all matches it has got from all grabbers, user 
    selects one of them.
  * From this point, myth issues -u <units> -d /dir <location> commands
    to fill the screen. Grabber replies with lines of data.
    
== Commands ==

In the examples here, the grabber is named 'grabber'. In reality it has
any name. The examples follows the cycle for a map provider. Other 
providers works in the same way, but with much longer parameter lists.

Unless stated otherwise, everything is ascii.

=== grabber -v ===

Example:
{{{
$ ./grabber -v
Wunderground,0.5,Alec Leamas,nowhere@gmail.com
}}}

The reply is four, ','separated items:id,version,author,email.
The id (Wunderground) is used to identify the data source.
The version string is tested for equality, as long as it doesn't change myth
uses data about grabber already in database. The rest is used for 
administrative purposes.

=== grabber -T ===

Example:
{{{
$ ./grabber -T
180,20
}}}

The reply is data_timeout,http_timeout. The data timeout governs how long 
it takes for the data provided by this grabber to expire (minutes), and thus
needs a reload. The http timout describes how long myth should wait for 
reply before giving up(seconds,TBD).

=== grabber -t ===

Example:
{{{
$ ./grabber -t
amdesc
animatedimage
copyright
updatetime
}}}

This command lists the data provided by this grabber.To be meaningful, 
the reply must list at least all items for one of the screens.
Many grabbers lists items for two or more screens e. g., the complete list 
required for a 3-day and 6-day forecast.

=== grabber -l <search string> ===

Example:
{{{
$ ./grabber -l norway
western_norway::Western Norway radar map animation
central_norway::Central Norway radar map animation
nordland_troms::Nordland-Troms radar map animation
troms_finnmark::Troms-Finnmark radar map animation
southwest_norway::Southwest Norway radar map animation
}}}

The reply is zero or more lines matching the <search string>. Each
line is formatted like 'id::label'. The id is used when retrieving data,
the label is used in the ui to show the location.

The label might contain non-ascii data. The id is ascii.

=== grabber -u <SI|ENG> -d /somewhere <location id> ===

Example:
{{{
$ ./grabber -u SI -d /tmp western_norway
amdesc::Western Norway
animatedimage::/tmp/mythweather_yr/anim_dir/animation-%1-9-800x1002
copyright::Copyright (C) 2008 The Norwegian Meteorological Institute.
updatetime::2010-03-28T10:42:45Z
}}}

The <location id> is the id provided by -l. The -d command is a writeable
directory, always the same. This is typically used for caching. The -u
flag determines whether the reply should use SI units or English (well, 
American) units.

The reply is one line for each item listed by -t. Each line is formatted
like 'id::value', where <id> is the the id listed by -t, and the value
the actual value. Values are in some cases non-ascii. For encoding of value, 
read on.

== Data representation ==

All data is printable. General types:

float::
    A numeric value, which could be parsed directly as a float. It 
    should not contain any unit information, just a plain number. 
    A missing or undefined value is  represented as 'NA'
    
string::
    An ascii string, possibly 'NA' representing undefined/non-existing 
    value.
    
i18nstring::
    String holding non-ascii data, character encoding TBD.
    
date::
    One of Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday
    
time::
    Time of day, 12-hour clock e. g., '3 PM'.
    
updatetime::
    ISO time stamp, like '2010-02-21T12:34:33Z', representing a 
    best-effort date when the data was created.TBD
    
icon::
    Ascii string  naming  of a mythtv weather icon, as used in the file 
    weather_types
    
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-600x800. This 
    represents a local file  /dir1/dir2/filename with an image sized
    600x800. The '-600x800' suffix is not mandatory, if missing the image
    will be expanded to fill the window.
    
animation::
    An animation is typically downloaded as a single file. The grabber 
    splits it into separate files which are stored locally. These files
    are represented by a single animation string like
    /dir1/dir2/filename-%1-6-800x600. 
    
    The %1 part is replaced with a unique number for each file. So with  
    animation like above there will be files like filename-0, 
    filename-1 etc.
    
    The '6' digit is the number of files. For this example, there will be 
    6 files named filename-0..filename-5
    
    The last part is the image size (width x height).
    
    Bottom line: an animation like filename-%1-4-800x600 represents an 
    animation with four frames named filename-0..filename-3 sized 800x600.
    
== Valid data types ==

In this list, only the SI variant is listed; ENG values are TBD.

=== Static map screen ===

|| smdesc     || i18nstring  ||                                        ||
|| map        || map         ||                                        ||
|| copyright  || i18nstring  || Copyright clause for data provider.    ||
|| updatetime || updatetime  ||                                        ||

See: StaticImageScreen::prepareDataItem

=== Dynamic map screen ===

|| amdesc     || i18nstring    ||                                      ||
|| copyright  || i18nstring    || Copyright clause for data provider.  ||
|| updatetime || updatetime    ||                                      ||
|| animatedimage || animation  ||                                      ||

See: AnimatedImageScreen::prepareDataItem

=== Observation (current conditions) data ===

|| cclocation    || i18nstring || Descriptive string                                   ||
|| station_id    || string     || The string given to myth to identify the station.    ||
|| copyright     || i18nstring ||                                                      ||
|| observation_time || iso date||                                                      ||
|| weather       || string     || Weather conditions, free text                        ||
|| temp          || float      || Current temp, Celsius                                ||
|| relative_humidity|| float   || percent                                              ||
|| wind_dir      || string     || string like 'NNW', 'S' etc.                          ||
|| wind_degrees  || float      || wind direction, 0 <= d < 360                         ||
|| pressure      || float      || mb                                                   ||
|| dewpoint      || float      || Celsius,   x < temp                                  ||
|| visibility    || float      || km, typically 1-10, less in fog.                     ||
|| weather_icon  || icon       ||                                                      ||
|| wind_speed    || float      || Average wind speed, m/s                              ||
|| wind_gust     || float      || *Max wind speed. Legacy: wind_spdgst. TBD            ||
|| appt          || float      || Apparent temperature, heat index and windchill combo ||
|| windchill     || float      || Celsius, See TBD                                     ||

See: WeatherScreen::formatDataItem

=== 18 hour forecast data ===

The temp, 18icon,time and pop values have suffixes to provide 6 three-hours
values: temp-0, temp-2..temp-5, 18icon-0..18icon-5 etc. 

|| 18hrlocation  || i18nstring || descriptive string                    ||
|| temp          || float      || Current temp, Celsius                 ||
|| 18icon        || icon       ||                                       ||
|| time          || time       ||                                       || 
|| precipitation || float      || *Anticipated precipitation (mm)TBD    ||
|| pop           || float      || Probability of precipitation(percent) ||
|| updatetime    || updatetime || Last forecast update, best effort.    ||

=== 3 days forecast ===

The high, low, date and icon values have suffixes to provide data for
three days: high-0, high-1, high-2, low-0..low-2 etc.

|| 3dlocation   || i18nstring  || descriptive string                    ||
|| high         || float       || Max day temp, high-0..high2           ||
|| low          || float       || Lowest day temp, low-0..low-2         ||
|| date         || date        || Date string, date-0..date-2           ||
|| icon         || icon        || Day's icon, icon-0..icon-2            ||
|| copyright    || i18nstring  ||                                       ||
|| updatetime   || updatetime  || last forecast update, best effort.    ||

=== 6 days forecast ===

The high, low, date and icon values have suffixes to provide data for
six days: high-0, high-5,  low-0..low-5 etc.

|| 6dlocation   || i18nstring  || Descriptive string                    ||
|| high         || float       || Max day temp, high-0..high-5          ||
|| low          || float       || Lowest day temp, low-0..low-5         ||
|| date         || date        || Date string, date-0..date-5           ||
|| icon         || icon        || Day's icon, icon-0..icon-5            ||
|| copyright    || i18nstring  ||                                       ||
|| updatetime   || updatetime  || Last forecast update, best effort.    ||

== Known issues ==

* Image paths are cut on first '-', even in directory parts like
  /tmp/spool-al/cache/image.gif. Avoid directories with a '-' FTM.
* Unclear character encoding of i18nstring. Practically, I have used latin-1
  successfully but YMMV.
* The ui presents the parameter wind_spdgst as 'wind (gust)'. This is
  problematic, partly because many stations only provide wind_speed and
  not wind_gust. Besides, the 'wind_spdgst' is the only parameter which not
  is used by the weather stations; the use 'wind_gust'.
* The ui presents the probablity of precipitation, pop. Many forecasts don't
  compute pop, but instead provides the anticipated amount of precipitation
  in mm. It's possible for grabbers to send the precipitation data in the
  'pop' data item, but the ui still uses 'pop' and '%' which is plain wrong.
* The -d option is not provided to all commands although it really should,
  both practically and according to the docs.

== References ==

appt:: 
    http://ams.confex.com/ams/pdfpapers/156484.pdf, pg 2-3

heat index::
    http://en.wikipedia.org/wiki/Heat_index
  
windchill::
    http://en.wikipedia.org/wiki/Windchill
   
wind gust::
    http://www.erh.noaa.gov/images/afi/windgust.html