ConkyForecast help (en)
From Conky PitStop
Contents |
conkyForecast.py help
| Language | English Français |
Author: Mark Buck (Kaivalagi)
NOTE: Weather.com have removed developer support and as such most will have great difficulty using the service through the conkyForecast script in the future.
Please note however that there is an "alpha" version of the script called conkyForecastWU which is also included in the latest conkyWeather package and is detailed towards the end of this thread which works with wunderground...this is a good alternative but has not been documented for here as yet.
conkyForecast is probably the most popular of his scripts, fighting for first place with ConkyEmail.
Instructions en français: La météo avec conkyForecast
New Link for OpenSuse (coming soon)
Prerequisites
It is expected that the user is already familiar with Conky.
Any conky specific help can be found by either visiting the conky website or alternatively various helpful posts are available on various Linux forums. Check out our Links page for some locations.
If you are not familiar with conky we have a Conky Setup Guide to get you started.
You need to install conkyForecast, pay particular attention to getting your City code. It will be a 4-letter-4number code that is NOT to be confused with your LOCALE (language), it is your DEFAULT_LOCATION!
OK, you have it, you've made the conky file, and template if you chose that route. Everything looks good but it doesn’t work! I’ve seen enough of this to ask: Did you copy /usr/share/conkyforecast/conkyForecast.config to ~/.conkyForecast.config and make the changes necessary?
Another note that is important: When using this script, call for the info with ${execpi}
There is a help file:
conkyForecast -help
... and It is obvious from the questions being repeatedly asked in the forums that people are NOT reading the help file so here it is with minor modifications by me to make it easier to identify the varuous uses of HT and LT for one:
Example Usage
In the /usr/share/conkyforecast/example folder you'll find 2 files, conkyrc and conkyForecast.template
Conky can be run using these example files as follows:
conky -c /usr/share/conkyforecast/example/conkyrc &
By running this you should see some output in a conky dialog, detailing all sorts of weather information. This is a test script for use with new releases.
Command Options
A break down of all the options available are below. The same details can be found by running conkyForecast --help
Usage: conkyForecast [options]
Options:
-h, --help show this help message and exit
-C FILE, --config=FILE
[default: ~/.conkyForecast.config] The path to the
configuration file, allowing multiple config files to
be used.
-l CODE, --location=CODE
location code for weather data [default set in
config]. Use the following url to determine your
location code by city name:
http://xoap.weather.com/search/search?where=Norwich
Change NORWICH for your city name!
-d DATATYPE, --datatype=DATATYPE
[default: HT] The data type options are:
Today: LT – Feels Like Temp – WITHOUT: “–startday=0″ [--datatype LT]
Today: HT – Current Temp – WITHOUT: “–startday=0″ [--datatype HT]
Today: LT – Forcasted Low Temp: – WITH: “–startday=0″ [-- startday=0 --datatype LT]
Today: HT – Forecasted High Temp: – WITH: “–startday=0″ [-- startday=0 --datatype HT]
Forecast: LT – Low Temp – use with –startday=1 to 4 [-- startday=1 --datatype LT]
Forecast: HT – High Temp – use with –startday=1 to 4 [-- startday=1 --datatype HT]
Font commands:
BF (Bearing Font)
BS (Bearing font with Speed)
MF (Moon Font)
WF (Weather Font output)
Images commands (conky v1.7.1 or greater)
- Usage:
BI (Bearing Icon Path)
- ${image [--datatype=BI] -p xx,xx -s yyxyy}
- ${image [--datatype=BI --startday=1] -p xx,xx -s yyxyy}
MI (Moon Icon Path)
- ${image [--datatype=MI] -p xx,xx -s yyxyy}
WI (Weather Icon Path) -
- ${image [--datatype=WI] -p xx,xx -s yyxyy}
- ${image [--datatype=WI --startday=1] -p xx,xx -s yyxyy}
BD (Barometer Description)
BR (Barometer Reading)
CC (Current Conditions)
CN (City Name)
CO (Country)
CT (Conditions Text)
DL (DayLight)
DP (Dew Point)
DW (Day of Week)
HM (Humidity)
LF (Last Fetch from weather.com). Not applicable at command line when using templates.
LU (Last Update at weather.com)
MP (Moon Phase)
OB (Observatory)
PC (Precipitation Chance)
SR (SunRise)
SS (SunSet)
UI (UV Index)
UT (UV Text)
VI (Visibility)
WA (Wind Angle - in degrees)
WD (Wind Direction)
WG (Wind Gusts)
WM (weather map fetch and image path returned)
WS (Wind Speed)
-s NUMBER, --startday=NUMBER
define the starting day number, if omitted current
conditions are output. Not applicable at command line
when using templates.
-e NUMBER, --endday=NUMBER
define the ending day number, if omitted only starting
day data is output. Not applicable at command line
when using templates.
-S NUMBER, --spaces=NUMBER
[default: 1] Define the number of spaces between
ranged output. Not applicable at command line when
using templates.
-t FILE, --template=FILE
define a template file to generate output in one call.
A displayable item in the file is in the form
[--datatype=HT --startday=1].
The following are possible options within each item:
--location
--datatype
--startday
--endday
--night
--shortweekday
--imperial
--beaufort
--metrespersecond
--hideunits
--hidedegreesymbol
--spaces
--minuteshide
Note that the short forms of the options are not
supported! If any of these options is set from the
commandline, it sets the default value of the
option for all template items.
-L LOCALE, --locale=LOCALE
override the system locale for language output
(bg=bulgarian, cs=czech, de=german, es=spanish,
en=english, es=spanish, fj=fijian, fr=french,
it=italian, nl=dutch, pl=polish, ro=romanian,
sk=slovak, more to come)
-i, --imperial request imperial units, if omitted output is in
metric.
-b, --beaufort request beaufort scale for wind speeds, if omitted
output is either metric/imperial.
-M, --metrespersecond
request metres per second for wind speeds, if omitted
output is either metric/imperial.
-n, --night switch output to night data, if omitted day output
will be output. ~/.conkyForecast.config now has: AUTO_NIGHT = True/False Default: False
-w, --shortweekday Shorten the day of week data type to 3 characters.
-u, --hideunits Hide units such as mph or C, degree symbols (°) are
still shown.
-x, --hidedegreesymbol
Hide the degree symbol used with temperature output,
this is only valid if used in conjunction with
--hideunits.
-m NUMBER, --minuteshide=NUMBER
Works only with LU and LF. If present, hides the date
part of the LU or LF timestamp if the day of the
timestamp is today. The time part is also hidden, if
the timestamp is older than minutes specified in this
argument. If set to 0, the time part is always shown.
If set to -1, the value EXPIRY_MINUTES from the config
file is used.
-c WIDTH, --centeredwidth=WIDTH
If used the output will be centered in a string of the
set width, padded out with spaces, if the output width
is greater than the setting it will be truncated
-r, --refetch Fetch data regardless of data expiry.
-v, --verbose Request verbose output, not a good idea when running
through conky!
-V, --version Displays the version of the script.
--errorlogfile=FILE If a filepath is set, the script appends errors to the
filepath.
--infologfile=FILE If a filepath is set, the script appends info to the
filepath.
More useful information:
Fonts
There are several fonts included in the release, these are installed to /usr/share/fonts/truetype/conkyforecast
They should be used as follows:
* ConkyWeather - should be used in conjunction with the WF (weather font) datatype * Arrows - can used in conjunction with the BF (bearing font) datatype, to display a simeple wind direction arrow * ConkyWind, ConkyWindN and ConkyWindNESW - should be used in conjunction with either the BF (bearing font) or BS (bearing font with speed) datatype * Moon Phases - should be used in conjunction with the MF (moon font) datatype
~/.conkyForecast.config Settings
A template config file exists which holds all the settings used by the script, and most importantly, stores the partner id and registration code for the weather.com xoap service.
It can be found here "/usr/share/conkyforecast/conkyForecast.config"
For a working script you NEED to define, in the user specific config file, a partner id and registration code for the weather.com xoap service. For this purpose the config file should be copied to "~/.conkyForecast.config" and setup as required.
To copy and edit the config, using the command line , run the following two commands in a terminal:
cp /usr/share/conkyforecast/conkyForecast.config ~/.conkyForecast.config
and then edit it:
nano ~/.conkyForecast.config
nano can be replaced with any text editor, I use gedit.
More details on the xoap service registration, including how to register to obtain the required keys, is below in the XOAP_PARTNER_ID and XOAP_REGISTRATION_KEY config setting details. Treat your ID and KEY the same way you treat your email passwords!
Below is a breakdown of all the settings and their purpose.
CACHE_FOLDERPATH = /tmp/
This setting dictates where the "pickled" weather data is cached for further use by the script. There will be one pickled file per location with the name .conkyForecast-LOCATION.cache, with LOCATION replace with your used location codes.
Pickling the information retrieved means that it can be reused without needing a round trip to the weather.com XOAP service each time something is displayed through a script call.
The default folder used is /tmp which is fine in most cases. However it should be noted that the /tmp folder is emptied on reboot, so data will not be kept in this case and a will needs refetching from the web again.
In situations where reboots are common, you could change the path to your own home folder if desired, meaning that cached data will never be lost.
I use: ~/Conky/cache
CONNECTION_TIMEOUT = 5
This setting is just that, it defines the timeout period for the connection establishment. This setting probably will not need changing, however with poor connectivity a higher value may be required.
EXPIRY_MINUTES = 30
This setting defines how long the cached weather data remains valid for. When the script is called, if the datetime of the cached files is older than this setting in minutes, the script will refetch the weather data required, and refresh the cache.
TIME_FORMAT = %H:%M
DATE_FORMAT = %Y-%m-%d
These settings define the formatting of both date and datetime output. They follow standard strftime formatting conventions and are listed below.
+=======================================================================+ | Value | Result | |=======================================================================| | %a | Locale's abbreviated weekday name. | ------------------------------------------------------------------------| | %A | Locale's full weekday name. | ------------------------------------------------------------------------| | %b | Locale's abbreviated month name. | |-----------------------------------------------------------------------| | %B | Locale's full month name. | ------------------------------------------------------------------------| | %c | Locale's appropriate date and time representation. | ------------------------------------------------------------------------| | %d | Day of the month as a decimal number [01,31]. | ------------------------------------------------------------------------| | %H | Hour (24-hour clock) as a decimal number [00,23]. | ------------------------------------------------------------------------| | %I | Hour (12-hour clock) as a decimal number [01,12]. | ------------------------------------------------------------------------| | %j | Day of the year as a decimal number [001,366]. | ------------------------------------------------------------------------| | %m | Month as a decimal number [01,12]. | ------------------------------------------------------------------------| | %M | Minute as a decimal number [00,59]. | ------------------------------------------------------------------------| | %p | Locale's equivalent of either AM or PM. | ------------------------------------------------------------------------| | %S | Second as a decimal number [00,61]. | ------------------------------------------------------------------------| | %U | Week number of the year (Sunday as the first day of the week) | | | as a decimal number [00,53]. All days in a new year preceding | | | the first Sunday are considered to be in week 0. | ------------------------------------------------------------------------| | %w | Weekday as a decimal number [0(Sunday),6]. | ------------------------------------------------------------------------| | %W | Week number of the year (Monday as the first day of the week) | | | as a decimal number [00,53]. All days in a new year preceding | | | the first Monday are considered to be in week 0. | ------------------------------------------------------------------------| | %x | Locale's appropriate date representation. | ------------------------------------------------------------------------| | %X | Locale's appropriate time representation. | ------------------------------------------------------------------------| | %y | Year without century as a decimal number [00,99]. | ------------------------------------------------------------------------| | %Y | Year with century as a decimal number. | ------------------------------------------------------------------------| | %Z | Time zone name (no characters if no time zone exists). | ------------------------------------------------------------------------| | %% | A literal "%" character. | +=======================================================================+
For more details, see the section on strftime
LOCALE =
NOTE: this is NOT for your city code you searched for. This concerns the "displayed language" conkyForecast will output to the screen.
This setting defines the locale to use. It is optional as the script will determine your systems locale it is not set. However if you tend to setup English as the default language in your OS but want all your weather output in another language you are best setting the locale here.
You also have the option to define locale via command line arguments, if these are set then this setting is ignored. This allows for output using a variety of languages in multiple script calls for example.
The locales currently supported are listed against the --locale option in the command options help below.
XOAP_PARTNER_ID =
XOAP_LICENCE_KEY =
ID & KEY = THINK: PASSWORDS! Do not publish them on the forums.
These settings are required for a working script, they are used when fetching data from the weather.com XOAP service.
To register and obtain the necessary codes you need to visit the following url and fill out the form.
http://www.weather.com/services/xmloap.html
After successfully completing the form, you will then receive a couple of emails providing you with the necessary codes to update these settings with, along with the software development kit and terms and conditions. It may take up to 24 hiurs to get this email, do not panic
Template Files
A template file is included in the example files and there are also details on the template option in the command options listed above.
Note that you can combine standard font output with weather fonts in a single template by using the execp and execpi commands in conky. The example uses this so to see how this works take a look at the example.
A quick example of template file options and layout:
[--datatype=DW --startday=1 --shortweekday] [--datatype=HT --startday=1 --hideunits]/[--datatype=LT --startday=1 --hideunits]
Anything inside the square brackets are options, anything outside standard text that will be output as conky would normally handle it.
The good thing about temoplates: one line in conky:
${execpi 1800 conkyForecast --location=ARBA0009 --template=~/path/to_your/weather.template}
weather.template can be called anything, ie: myweather.for.city as long as you call it:
${execpi 1800 conkyForecast --location=ARBA0009 --template=~/path/to_your/myweather.for.city}
GOTCHAS
Conky has a default limit of 128 bytes for any text output from a variable. If you are creating large templates with more characters than the default buffer size can handle, the output can get truncated.
If this happens you can override the default behaviour by setting as new buffer size before the TEXT section in your conkyrc file, as follows:
text_buffer_size 1024
Some weather templates typically use:
text_buffer_size 3048 # 256 is minimum
or more!
There is a limit to the maximum range for free forecasts, the startday and endday options cannot be set greater than 4. The following are the options to use to get the maximum forecast of high temps (including forecast data for today)
--datatype=HT --startday=0 --endday=4
For certain characters used in this script, such as degree symbols, it is required that the UTF8 character set is enabled in Conky. If UTF8 is not enabled you can end up seeing something like 66ðF rather than 66°F.
To enable UTF8 the following should be added before the TEXT section in your conkyrc file.
# Force UTF8? note that UTF8 support required XFT override_utf8_locale yes
Further Help
If you have an issue and are not sure, try running the same command in the terminal window and add the option --verbose, you should then see lots of information about what the script is doing, any warnings or errors should also be displayed.
If after doing the above you are still stuck, further help can be found by visiting the Weather Forecast Python Script support thread.
Note that it is best to post --verbose output of your script call, as well as the conkyrc you are using. This way the issue can be understood quickly and easily.
14:33 ~
$ conkyForecast -d HT --verbose
*** INITIAL OPTIONS:
config: ~/.conkyForecast.config
location: None
datatype: HT
start day: None
end day: None
spaces: 1
template: None
locale: None
imperial: False
beaufort: False
metrespersecond: False
night: False
shortweekday: False
hideunits: False
hidedegreesymbol: False
minuteshide: None
centeredwidth: None
refetch: False
verbose: True
errorlogfile: None
infologfile: None
*** CONFIG OPTIONS:
CACHE_FOLDERPATH: /home/IBCold/Conky/cache/
CONNECTION_TIMEOUT: 5
EXPIRY_MINUTES: 30
TIME_FORMAT: %H:%M
DATE_FORMAT: %Y-%m-%d
LOCALE: en
XOAP_PARTNER_ID: MY-ID-NUMBER
XOAP_LICENCE_KEY: MY-KEY-NUMBER
DEFAULT_LOCATION: CAXX0829
MAXIMUM_DAYS_FORECAST: 4
BASE_XOAP_URL: http://xml.weather.com/weather/local/<LOCATION>?cc=*&dayf=10&link=xoap&prod=xoap&par=<XOAP_PARTNER_ID>&key=<XOAP_LICENCE_KEY>&unit=m
INFO: Locale set to en
INFO: Looking for translation file for 'en' under /usr/share/conkyforecast/locale
INFO: Translation file found for 'en'
INFO: Translation installed for 'en'
INFO: Not using a proxy as none is defined
INFO: Loading cache file /home/IBCold/Conky/cache/.conkyForecast-CAXX0829.cache
2°C
14:34 ~
$
ENJOY
