| 1 | = Mythweather grabber interface =
|
|---|
| 2 |
|
|---|
| 3 | == General ==
|
|---|
| 4 |
|
|---|
| 5 | 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.
|
|---|
| 6 |
|
|---|
| 7 | The program flows roughly like:
|
|---|
| 8 |
|
|---|
| 9 | * myth scans the script directories for executable files. To each
|
|---|
| 10 | of them myth issues the -v command. The grabber replies with
|
|---|
| 11 | a version number (+ additional info). If the version is
|
|---|
| 12 | unchanged, myth uses already present data in the database.
|
|---|
| 13 | Otherwise:
|
|---|
| 14 | * myth issues -t command. The grabber lists what kind of data it
|
|---|
| 15 | provides. If the list is enough to meet the requirements for one
|
|---|
| 16 | or more pages, myth will use it for these.
|
|---|
| 17 | * myth issues -T command. Grabber replies with
|
|---|
| 18 | data_timeout(min),http timeout(seconds) e. g., '3600,20'.
|
|---|
| 19 | * User sets up a page using the mythfrontend setup tool. Eventually,
|
|---|
| 20 | she has to search for available data for a specific place. When
|
|---|
| 21 | doing so, myth issues -l <search string > command. The grabber
|
|---|
| 22 | replies with a list of possible places matching the user search
|
|---|
| 23 | string.
|
|---|
| 24 | * Myth presents all matches it has got from all grabbers, user
|
|---|
| 25 | selects one of them.
|
|---|
| 26 | * From this point, myth issues -u <units> -d /dir <location> commands
|
|---|
| 27 | to fill the screen. Grabber replies with lines of data.
|
|---|
| 28 |
|
|---|
| 29 | == Commands ==
|
|---|
| 30 |
|
|---|
| 31 | In the examples here, the grabber is named 'grabber'. In reality it has
|
|---|
| 32 | any name. The examples follows the cycle for a map provider. Other
|
|---|
| 33 | providers works in the same way, but with much longer parameter lists.
|
|---|
| 34 |
|
|---|
| 35 | Unless stated otherwise, everything is ascii.
|
|---|
| 36 |
|
|---|
| 37 | === grabber -v ===
|
|---|
| 38 |
|
|---|
| 39 | Example:
|
|---|
| 40 | {{{
|
|---|
| 41 | $ ./grabber -v
|
|---|
| 42 | Wunderground,0.5,Alec Leamas,nowhere@gmail.com
|
|---|
| 43 | }}}
|
|---|
| 44 |
|
|---|
| 45 | The reply is four, ','separated items:id,version,author,email.
|
|---|
| 46 | The id (Wunderground) is used to identify the data source.
|
|---|
| 47 | The version string is tested for equality, as long as it doesn't change myth
|
|---|
| 48 | uses data about grabber already in database. The rest is used for
|
|---|
| 49 | administrative purposes.
|
|---|
| 50 |
|
|---|
| 51 | === grabber -T ===
|
|---|
| 52 |
|
|---|
| 53 | Example:
|
|---|
| 54 | {{{
|
|---|
| 55 | $ ./grabber -T
|
|---|
| 56 | 180,20
|
|---|
| 57 | }}}
|
|---|
| 58 |
|
|---|
| 59 | The reply is data_timeout,http_timeout. The data timeout governs how long
|
|---|
| 60 | it takes for the data provided by this grabber to expire (minutes), and thus
|
|---|
| 61 | needs a reload. The http timout describes how long myth should wait for
|
|---|
| 62 | reply before giving up(seconds,TBD).
|
|---|
| 63 |
|
|---|
| 64 | === grabber -t ===
|
|---|
| 65 |
|
|---|
| 66 | Example:
|
|---|
| 67 | {{{
|
|---|
| 68 | $ ./grabber -t
|
|---|
| 69 | amdesc
|
|---|
| 70 | animatedimage
|
|---|
| 71 | copyright
|
|---|
| 72 | updatetime
|
|---|
| 73 | }}}
|
|---|
| 74 |
|
|---|
| 75 | This command lists the data provided by this grabber.To be meaningful,
|
|---|
| 76 | the reply must list at least all items for one of the screens.
|
|---|
| 77 | Many grabbers lists items for two or more screens e. g., the complete list
|
|---|
| 78 | required for a 3-day and 6-day forecast.
|
|---|
| 79 |
|
|---|
| 80 | === grabber -l <search string> ===
|
|---|
| 81 |
|
|---|
| 82 | Example:
|
|---|
| 83 | {{{
|
|---|
| 84 | $ ./grabber -l norway
|
|---|
| 85 | western_norway::Western Norway radar map animation
|
|---|
| 86 | central_norway::Central Norway radar map animation
|
|---|
| 87 | nordland_troms::Nordland-Troms radar map animation
|
|---|
| 88 | troms_finnmark::Troms-Finnmark radar map animation
|
|---|
| 89 | southwest_norway::Southwest Norway radar map animation
|
|---|
| 90 | }}}
|
|---|
| 91 |
|
|---|
| 92 | The reply is zero or more lines matching the <search string>. Each
|
|---|
| 93 | line is formatted like 'id::label'. The id is used when retrieving data,
|
|---|
| 94 | the label is used in the ui to show the location.
|
|---|
| 95 |
|
|---|
| 96 | The label might contain non-ascii data. The id is ascii.
|
|---|
| 97 |
|
|---|
| 98 | === grabber -u <SI|ENG> -d /somewhere <location id> ===
|
|---|
| 99 |
|
|---|
| 100 | Example:
|
|---|
| 101 | {{{
|
|---|
| 102 | $ ./grabber -u SI -d /tmp western_norway
|
|---|
| 103 | amdesc::Western Norway
|
|---|
| 104 | animatedimage::/tmp/mythweather_yr/anim_dir/animation-%1-9-800x1002
|
|---|
| 105 | copyright::Copyright (C) 2008 The Norwegian Meteorological Institute.
|
|---|
| 106 | updatetime::2010-03-28T10:42:45Z
|
|---|
| 107 | }}}
|
|---|
| 108 |
|
|---|
| 109 | The <location id> is the id provided by -l. The -d command is a writeable
|
|---|
| 110 | directory, always the same. This is typically used for caching. The -u
|
|---|
| 111 | flag determines whether the reply should use SI units or English (well,
|
|---|
| 112 | American) units.
|
|---|
| 113 |
|
|---|
| 114 | The reply is one line for each item listed by -t. Each line is formatted
|
|---|
| 115 | like 'id::value', where <id> is the the id listed by -t, and the value
|
|---|
| 116 | the actual value. Values are in some cases non-ascii. For encoding of value,
|
|---|
| 117 | read on.
|
|---|
| 118 |
|
|---|
| 119 | == Data representation ==
|
|---|
| 120 |
|
|---|
| 121 | All data is printable. General types:
|
|---|
| 122 |
|
|---|
| 123 | float::
|
|---|
| 124 | A numeric value, which could be parsed directly as a float. It
|
|---|
| 125 | should not contain any unit information, just a plain number.
|
|---|
| 126 | A missing or undefined value is represented as 'NA'
|
|---|
| 127 |
|
|---|
| 128 | string::
|
|---|
| 129 | An ascii string, possibly 'NA' representing undefined/non-existing
|
|---|
| 130 | value.
|
|---|
| 131 |
|
|---|
| 132 | i18nstring::
|
|---|
| 133 | String holding non-ascii data, character encoding TBD.
|
|---|
| 134 |
|
|---|
| 135 | date::
|
|---|
| 136 | One of Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday
|
|---|
| 137 |
|
|---|
| 138 | time::
|
|---|
| 139 | Time of day, 12-hour clock e. g., '3 PM'.
|
|---|
| 140 |
|
|---|
| 141 | updatetime::
|
|---|
| 142 | ISO time stamp, like '2010-02-21T12:34:33Z', representing a
|
|---|
| 143 | best-effort date when the data was created.TBD
|
|---|
| 144 |
|
|---|
| 145 | icon::
|
|---|
| 146 | Ascii string naming of a mythtv weather icon, as used in the file
|
|---|
| 147 | weather_types
|
|---|
| 148 |
|
|---|
| 149 | map::
|
|---|
| 150 | A static map is an image, which is downloaded to a local file by the
|
|---|
| 151 | grabber. The map is a string like /dir1/dir2/filename-600x800. This
|
|---|
| 152 | represents a local file /dir1/dir2/filename with an image sized
|
|---|
| 153 | 600x800. The '-600x800' suffix is not mandatory, if missing the image
|
|---|
| 154 | will be expanded to fill the window.
|
|---|
| 155 |
|
|---|
| 156 | animation::
|
|---|
| 157 | An animation is typically downloaded as a single file. The grabber
|
|---|
| 158 | splits it into separate files which are stored locally. These files
|
|---|
| 159 | are represented by a single animation string like
|
|---|
| 160 | /dir1/dir2/filename-%1-6-800x600.
|
|---|
| 161 |
|
|---|
| 162 | The %1 part is replaced with a unique number for each file. So with
|
|---|
| 163 | animation like above there will be files like filename-0,
|
|---|
| 164 | filename-1 etc.
|
|---|
| 165 |
|
|---|
| 166 | The '6' digit is the number of files. For this example, there will be
|
|---|
| 167 | 6 files named filename-0..filename-5
|
|---|
| 168 |
|
|---|
| 169 | The last part is the image size (width x height).
|
|---|
| 170 |
|
|---|
| 171 | Bottom line: an animation like filename-%1-4-800x600 represents an
|
|---|
| 172 | animation with four frames named filename-0..filename-3 sized 800x600.
|
|---|
| 173 |
|
|---|
| 174 | == Valid data types ==
|
|---|
| 175 |
|
|---|
| 176 | In this list, only the SI variant is listed; ENG values are TBD.
|
|---|
| 177 |
|
|---|
| 178 | === Static map screen ===
|
|---|
| 179 |
|
|---|
| 180 | || smdesc || i18nstring || ||
|
|---|
| 181 | || map || map || ||
|
|---|
| 182 | || copyright || i18nstring || Copyright clause for data provider. ||
|
|---|
| 183 | || updatetime || updatetime || ||
|
|---|
| 184 |
|
|---|
| 185 | See: StaticImageScreen::prepareDataItem
|
|---|
| 186 |
|
|---|
| 187 | === Dynamic map screen ===
|
|---|
| 188 |
|
|---|
| 189 | || amdesc || i18nstring || ||
|
|---|
| 190 | || copyright || i18nstring || Copyright clause for data provider. ||
|
|---|
| 191 | || updatetime || updatetime || ||
|
|---|
| 192 | || animatedimage || animation || ||
|
|---|
| 193 |
|
|---|
| 194 | See: AnimatedImageScreen::prepareDataItem
|
|---|
| 195 |
|
|---|
| 196 | === Observation (current conditions) data ===
|
|---|
| 197 |
|
|---|
| 198 | || cclocation || i18nstring || Descriptive string ||
|
|---|
| 199 | || station_id || string || The string given to myth to identify the station. ||
|
|---|
| 200 | || copyright || i18nstring || ||
|
|---|
| 201 | || observation_time || iso date|| ||
|
|---|
| 202 | || weather || string || Weather conditions, free text ||
|
|---|
| 203 | || temp || float || Current temp, Celsius ||
|
|---|
| 204 | || relative_humidity|| float || percent ||
|
|---|
| 205 | || wind_dir || string || string like 'NNW', 'S' etc. ||
|
|---|
| 206 | || wind_degrees || float || wind direction, 0 <= d < 360 ||
|
|---|
| 207 | || pressure || float || mb ||
|
|---|
| 208 | || dewpoint || float || Celsius, x < temp ||
|
|---|
| 209 | || visibility || float || km, typically 1-10, less in fog. ||
|
|---|
| 210 | || weather_icon || icon || ||
|
|---|
| 211 | || wind_speed || float || Average wind speed, m/s ||
|
|---|
| 212 | || wind_gust || float || *Max wind speed. Legacy: wind_spdgst. TBD ||
|
|---|
| 213 | || appt || float || Apparent temperature, heat index and windchill combo ||
|
|---|
| 214 | || windchill || float || Celsius, See TBD ||
|
|---|
| 215 |
|
|---|
| 216 | See: WeatherScreen::formatDataItem
|
|---|
| 217 |
|
|---|
| 218 | === 18 hour forecast data ===
|
|---|
| 219 |
|
|---|
| 220 | The temp, 18icon,time and pop values have suffixes to provide 6 three-hours
|
|---|
| 221 | values: temp-0, temp-2..temp-5, 18icon-0..18icon-5 etc.
|
|---|
| 222 |
|
|---|
| 223 | || 18hrlocation || i18nstring || descriptive string ||
|
|---|
| 224 | || temp || float || Current temp, Celsius ||
|
|---|
| 225 | || 18icon || icon || ||
|
|---|
| 226 | || time || time || ||
|
|---|
| 227 | || precipitation || float || *Anticipated precipitation (mm)TBD ||
|
|---|
| 228 | || pop || float || Probability of precipitation(percent) ||
|
|---|
| 229 | || updatetime || updatetime || Last forecast update, best effort. ||
|
|---|
| 230 |
|
|---|
| 231 | === 3 days forecast ===
|
|---|
| 232 |
|
|---|
| 233 | The high, low, date and icon values have suffixes to provide data for
|
|---|
| 234 | three days: high-0, high-1, high-2, low-0..low-2 etc.
|
|---|
| 235 |
|
|---|
| 236 | || 3dlocation || i18nstring || descriptive string ||
|
|---|
| 237 | || high || float || Max day temp, high-0..high2 ||
|
|---|
| 238 | || low || float || Lowest day temp, low-0..low-2 ||
|
|---|
| 239 | || date || date || Date string, date-0..date-2 ||
|
|---|
| 240 | || icon || icon || Day's icon, icon-0..icon-2 ||
|
|---|
| 241 | || copyright || i18nstring || ||
|
|---|
| 242 | || updatetime || updatetime || last forecast update, best effort. ||
|
|---|
| 243 |
|
|---|
| 244 | === 6 days forecast ===
|
|---|
| 245 |
|
|---|
| 246 | The high, low, date and icon values have suffixes to provide data for
|
|---|
| 247 | six days: high-0, high-5, low-0..low-5 etc.
|
|---|
| 248 |
|
|---|
| 249 | || 6dlocation || i18nstring || Descriptive string ||
|
|---|
| 250 | || high || float || Max day temp, high-0..high-5 ||
|
|---|
| 251 | || low || float || Lowest day temp, low-0..low-5 ||
|
|---|
| 252 | || date || date || Date string, date-0..date-5 ||
|
|---|
| 253 | || icon || icon || Day's icon, icon-0..icon-5 ||
|
|---|
| 254 | || copyright || i18nstring || ||
|
|---|
| 255 | || updatetime || updatetime || Last forecast update, best effort. ||
|
|---|
| 256 |
|
|---|
| 257 | == Known issues ==
|
|---|
| 258 |
|
|---|
| 259 | * Image paths are cut on first '-', even in directory parts like
|
|---|
| 260 | /tmp/spool-al/cache/image.gif. Avoid directories with a '-' FTM.
|
|---|
| 261 | * Unclear character encoding of i18nstring. Practically, I have used latin-1
|
|---|
| 262 | successfully but YMMV.
|
|---|
| 263 | * The ui presents the parameter wind_spdgst as 'wind (gust)'. This is
|
|---|
| 264 | problematic, partly because many stations only provide wind_speed and
|
|---|
| 265 | not wind_gust. Besides, the 'wind_spdgst' is the only parameter which not
|
|---|
| 266 | is used by the weather stations; the use 'wind_gust'.
|
|---|
| 267 | * The ui presents the probablity of precipitation, pop. Many forecasts don't
|
|---|
| 268 | compute pop, but instead provides the anticipated amount of precipitation
|
|---|
| 269 | in mm. It's possible for grabbers to send the precipitation data in the
|
|---|
| 270 | 'pop' data item, but the ui still uses 'pop' and '%' which is plain wrong.
|
|---|
| 271 | * The -d option is not provided to all commands although it really should,
|
|---|
| 272 | both practically and according to the docs.
|
|---|
| 273 |
|
|---|
| 274 | == References ==
|
|---|
| 275 |
|
|---|
| 276 | appt::
|
|---|
| 277 | http://ams.confex.com/ams/pdfpapers/156484.pdf, pg 2-3
|
|---|
| 278 |
|
|---|
| 279 | heat index::
|
|---|
| 280 | http://en.wikipedia.org/wiki/Heat_index
|
|---|
| 281 |
|
|---|
| 282 | windchill::
|
|---|
| 283 | http://en.wikipedia.org/wiki/Windchill
|
|---|
| 284 |
|
|---|
| 285 | wind gust::
|
|---|
| 286 | http://www.erh.noaa.gov/images/afi/windgust.html
|
|---|
| 287 |
|
|---|
| 288 |
|
|---|
| 289 |
|
|---|
| 290 |
|
|---|
| 291 |
|
|---|
| 292 |
|
|---|
| 293 |
|
|---|
