ArchLinux : Package support is present in the AUR. All my packages can be seen here: http://aur.archlinux.org/packages.php?SeB=m&K=kaivalagi
Ubuntu/Debian : All the script packages have now been copied into the Conky Companions PPA. Any package updates will be provided by the team through this new ppa. The ppa can be found here: https://launchpad.net/~conky-companions/+archive/ppa. To use this ppa first delete the old ppa files using this:
Code:
sudo rm /etc/apt/sources.list.d/m-buck* && sudo rm /etc/apt/sources.list.d/conkyhardcore*
Then follow the modified first post instructions for the scripts
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 against weather underground...this is a good alternative but has not been documented for here as yet.
Intro
I put together this python script to produce various bits of weather data on demand for use in Conky. This sort of thing has been done already by lvleph, a post for his contribution is here.
I wanted to create something, firstly to gain some experience with Python, and secondly so that there was no dependency on the yahoo weather website and it's formatting. This hopefully means that it will have a little longevity.
Some key features
- Compliant with python 2.4 onwards
- Utilises the weather.com XOAP service.
- Caches fetched data to stop unnecessary web calls
- Supports ranged forecast output, up to the next 5 days (cut's down on execi calls )
- Optional spacing settings for ranged input
- Supports imperial / metric / beaufort measurements
- Supports day or night forecasts
- Uses separate config file for key settings
- Provides language support using gettext i18n functionality (English default, optional Spanish, French, Bulgarian, Czech, more if help provided)
- Supports template files for complicated output in a single exec call! (cut's down on execi calls big time )
- Template files can include the various conky variables such as $color, $font, $goto and $offset, and be formatted through the execp/exexpi commands
- Obtainable through apt with a quite addition to your sources.list file
- Uses custom font to display day and night based weather symbols (thanks Stancho!)
There is a README with the install, I suggest you give it atleast a quick once over! It can be found in the installation folder, normally following the path of /usr/share/conky<scriptname>/
Hope some of you find it useful
Any suggestions, please speak up.
Basic Install
Method 1: Using apt
1) Add the repository to your OS install:
Code:
sudo add-apt-repository ppa:conky-companions/ppa
* Note if you are running 9.10 or below then refer to the PPA link at the end of this post for help on installing from the ppa, good guidance can be found on the launchpad site
2) Now that is done simply run the following to update your repo cache and install the script:
Code:
sudo apt-get update && sudo apt-get install conkyforecast
Method 2: Using deb file
Run the .deb file available at the Conky Companions PPA site here: https://launchpad.net/~conky-compani.../ppa/+packages
Warning, this will not ensure you are kept up-to-date. Only method 1 will do that
Method 3: Using tar.gz file
Extract all the contents of the tar.gz file to an appropriate folder, and edit the conkyForecast script to point to the correct location where conkyForecast.py is. The tar.gz file is available at the Conky Companions PPA site here: https://launchpad.net/~conky-compani.../ppa/+packages
Unless you are using a non-Debian based OS I don't suggest this. Users of Debian/Ubuntu flavour OS's should ideally use method 1.
Again you will not receive updates using this method. ONLY method 1 can do this for you
All further details on setup are orientated around the deb package based install, so may differ from what you choose your setup to be, if done using the tarball.
Weather.com XOAP Service Registration
Due to the risk of having the previously registered xoap weather.com account terminated because of high volumes of requests, I have upgraded the script to use a users own registered details. These details need to be entered into the users own config file, details on that are below.
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.
Location Code For Config / Script Calls
To identify the location code for your town/city the following URL should be used, replacing NORWICH with the one you're looking up :
http://xoap.weather.com/search/search?where=NORWICH
The following xml is returned for the above url, from which the correct location code (loc id value) can be picked. Mine was UKXX0103.
Code:
<search ver="2.0">
<loc id="USNY0428" type="1">East Norwich, NY</loc>
<loc id="USNY1036" type="1">North Norwich, NY</loc>
<loc id="USCT0155" type="1">Norwich, CT</loc>
<loc id="UKXX0103" type="1">Norwich, United Kingdom</loc>
<loc id="USKS0428" type="1">Norwich, KS</loc>
<loc id="USND0266" type="1">Norwich, ND</loc>
<loc id="USNY1044" type="1">Norwich, NY</loc>
<loc id="USOH0716" type="1">Norwich, OH</loc>
<loc id="USVT0175" type="1">Norwich, VT</loc>
</search>
Once you know your location code, use it when calling the script with the "--location=" option or set the default location in you ~/.conkyForecast.config based config file.
Note that if you don't see full xml data like above for your search then (presuming results were found) you may need to "view source" to see them as some browsers like to display xml in different ways.
Example Use
In the /usr/share/conkyforecast/example folder you'll find 8 files, providing 3 different examples of font and image based output, the list of files are:
- conkyForecast.fontbased.conkyrc
- conkyForecast.fontbased.sh
- conkyForecast.fontbasedtemplate.conkyrc
- conkyForecast.fontbasedtemplate.sh
- conkyForecast.fontbasedtemplate.template
- conkyForecast.imagebasedtemplate.conkyrc
- conkyForecast.imagebasedtemplate.sh
- conkyForecast.imagebasedtemplate.template
Note that the .sh files when run through a shell will display that particular example. For more on how they work open the files and take a look!
By running this you should see some output at the top right of your screen, detailing all sorts of weather information.
If you wish to use these example files for your own creations it would be best to copy the files to your $HOME location and edit them appropriately.
Testing
In the /usr/share/conkyforecast/test folder you'll find 3 files, providing for test output, these files are:
- conkyForecast.test.conkyrc
- conkyForecast.test.sh
- conkyForecast.test.conkyrc
Note that the .sh file when run through a shell will display the test window. For more on how they work open the files and take a look!
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.
Usage Help
You can get the current help options at any time by running (change the path as necessary):
or
Code:
conkyForecast --help
The usage as output in the console is as follows:
Code:
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
-d DATATYPE, --datatype=DATATYPE
[default: HT] The data type options are: DW (Day of
Week), WF (Weather Font output), WI (Weather Icon
Path), LT (Forecast:Low Temp,Current:Feels Like Temp),
HT (Forecast:High Temp,Current:Current Temp), CC
(Current Conditions), CT (Conditions Text), PC
(Precipitation Chance), HM (Humidity), VI
(Visibility), WD (Wind Direction), WA (Wind Angle - in
degrees), WS (Wind Speed), WG (Wind Gusts), BF
(Bearing Font), BI (Bearing Icon Path), BS (Bearing
font with Speed), CN (City Name), CO (Country), OB
(Observatory), SR (SunRise), SS (SunSet), DL
(DayLight), MP (Moon Phase), MF (Moon Font), MI (Moon
Icon Path), BR (Barometer Reading), BD (Barometer
Description), UI (UV Index), UT (UV Text), DP (Dew
Point), WM (weather map fetch and image path
returned), LU (Last Update at weather.com), LF (Last
Fetch from weather.com). Not applicable at command
line when using templates.
-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.
-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.
Note: For current conditions the temperature is "measured" using the HT datatype and "feels like" using the LT datatype.
Expanded Usage Details
Courtesy of conky pitstop: http://conky.pitstop.free.fr/wiki/in...yForecast_help
-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
-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, options are:
- 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
Hopefully 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.
Notes On The Config File
Creating a Config File
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 at a minimum to define a partner id and registration code for the weather.com xoap service in a user specific config file. For this purpose the config file should be copied to "~/.conkyForecast.config" and setup as required.
To copy and edit the config file, using the command line, run the following two commands in a terminal, one after the other:
Code:
cp /usr/share/conkyforecast/conkyForecast.config ~/.conkyForecast.config
nano ~/.conkyForecast.config
The conkyForecast.config has a few config values worthy of a mention.
The Cache Folder Used
Code:
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.
The Default Connection Timeout
Code:
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.
The Expiry Duration Of Forecast Data
Code:
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.
The Date/Time Formats
Code:
TIME_FORMAT = %H:%M
DATE_FORMAT = %Y-%m-%d
These settings define the formatting of both time and date output.
They follow standard strftime formatting conventions.
For more details, see the section on strftime here: http://docs.python.org/lib/module-time.html
The Locale/Language of Output
This setting defines the locale or language to use. It is optional as the script will determine your systems locale if this is not set. You also have the option to define locale via command line arguments, if these are set then this setting is ignored. The locales currently supported are listed against the --locale option in the command options help below.
Weather.com Required ID and Key
Code:
XOAP_PARTNER_ID = <INSERT ID FROM REGISTRATION HERE>
XOAP_LICENCE_KEY = <INSERT KEY FROM REGISTRATION HERE>
These settings are required for a working script, they are used when
fetching data from the weather.com XOAP service.
As mentioned before above to register and obtain the necessary codes you need to visit this url: http://www.weather.com/services/xmloap.html and fill out the form
The Default Location For Weather Data
As mentioned about above this is the setting that holds the default location to be used by the script if no --location option is given. If all your weather output is derived from one location then using a default like this reduces the amount of setting arguments needed through the conky rc / template files.
The original config file provided that should be copied to a users home folder has Norwich as the default location code as so:
Code:
DEFAULT_LOCATION = UKXX0103
Notes On Fonts
There are several fonts included in the release, these are located in /usr/share/fonts/truetype/conkyforecast
They should be used as follows:
- ConkyWeather font should be used in conjunction with the WF (weather font) datatype.
- Arrows font can used in conjunction with the BF (bearing font) datatype, to display a simple wind direction arrow
- ConkyWind, ConkyWindN and ConkyWindNESW fonts should be used in conjunction with either the BF (bearing font) or BS (bearing font with speed) datatypes.
- Moon Phases font should be used in conjunction with the MF (moon font) datatype
Notes On Images
There are now three datatype options which provide image paths to be used with the new $image parameter in Conky 1.7.1+
The data types are WI (Weather icons), MI (Moon icons) and BI (Bearing icons).
For more help and guidance on the $image parameter needed in conjunction with these datatype options visit the Conky PitStop website, specifically this page: http://conky-pitstop.wikidot.com/kaivalagi#toc7
Notes On Conky Test/Example Files
I recommend using the test files as a templates when creating your own conkyrc file. Note that if the location of the python script is different to the example given, please ensure the conkyrc-test* file, or your own, is amended to point to the correct location.
A quick example of use in conky rc:
Code:
Conditions: ${execi 3600 conkyForecast --location=UKXX0103 --datatype=CC}
${font ConkyWeather:size=36}${execi 3600 conkyForecast --location=UKXX0103 --datatype=WF}${font}
Temp: ${execi 3600 conkyForecast --location=UKXX0103 --datatype=HT}
More conky documentation can be found on the conky sourceforge site, and thanks to Bruce M, in a HOWTO thread in these forums. Links below:
Notes On Template Files
Recently the use of templates was added, so that a single exec call can be made to retrieve a multitude of data.
An example template file is included in the install, and the usage text also explains the options available. Only long versions of the options are supported in a template, i.e. --datatype= and not -d.
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 that.
A quick example of template file options and layout:
Code:
[--datatype=DW --startday=1 --shortweekday]
[--datatype=HT --startday=1 --hideunits]/[--datatype=LT --startday=1 --hideunits]
Anything inside the square brackets are options, outside of the brackets is standard text that will be output as conky would normally handle it.
Gotchas
1) Conky has a default limitation of 128 bytes for any text output from a variable (such as execi). If you are creating large templates with more characters than the default buffer size can handle, the output will 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:
Code:
text_buffer_size 1024
2) There is a limit to the maximum range for forecasts, the startday and endday options cannot be set greater than 4, otherwise the script breaks...the following are the options to use to get the maximum forecast of high temps (including forecast data for today):
Code:
--datatype=HT --startday=0 --endday=4
3) For certain characters used in this script, such as degree symbols, it is required that the UTF8 character set is configured for use in Conky. If UTF8 is not enabled you can end up seeing something like 66ð rather than 66°. To enable UTF8 the following should be added before the TEXT section in your conkyrc file:
Code:
# Force UTF8? note that UTF8 support required XFT
override_utf8_locale yes
4) Make sure you do not have this setting below:
The included fonts which support certain datatypes, are case sensitive so any use of them requires lower case as well as upper case.
Further Help
If you have an issue and are not sure, try running the same conkyForecast 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 relating to conkyForecast can be got on this thread.
Note that it is best to post --verbose (hint on the option to use) output of your script call, as well as the conkyrc you are using. This way the issue can be understood quickly and easily.
The README is attached to this post also, take a look at this is you want to know more. Most of it's contents are here but there is some useful info there.
For any updates you receive you can view the readme file by running this in the terminal:
Code:
gunzip -c /usr/share/doc/conkyforecast/README.gz | less
Development History
Created: 13/04/2008
Noteworthy thanks go, in alphabetical order, to benpaka, Bruce M., El_Belgicano, HippyRandall, jjgomera, Nite, stancho and vasilub1 for their contributions to the script and it's rollouts over the past few months.
Development history going forwards can be seen here https://code.launchpad.net/~conky-companions/+junk/conkyforecast
All packages available from me can be found here: https://launchpad.net/~conky-companions/+archive/ppa
Bookmarks