Table of Contents

Changelog
Email Announcements
Vote for Weather Plotter
Why Weather Plotter was built
How it works
Requirements
Download and Install
Upgrade from v2.0-2.0.7 to 2.1.2
Weather Plotter License
Weather Plotter Credits

Changes in v2.1.2

  1. Fixed problem in schema creation involving notnull columns in MySQL

Changes in v2.1.1

  1. Fixed problem in HOWTO that referred to deprecated get_forecast.php script.
  2. Fixed bugs in generate-weather-facts.php that occured in new installation.

Changes in v2.1.0

  1. Introduced new year-vs-year comparison graphs.
  2. Vastly improved speed for visualizing annual statistics.
  3. Completely revamped user interface.

Changes in v2.0.7

  1. Removed dependency on 'wget' command line utiltiy in favor of built-in PHP 'fopen'.
  2. Fixed bug in site-name.inc.php related to location IDs not being set properly.

Changes in v2.0.6

  1. Upgrade to ADOdb v3.6.0. This was done to take advantage of the new data dictionary features.
  2. New install procedure makes use of ADOdb data dictionary (table manipulation) features. Allows one install script to serve all supported ADOdb database (postgres, mysql, oracle, mslsql, etc.).
  3. Eliminated the forecast data gathering feature and related statistics report. Yahoo! has been actively trying to prevent screen-scraping of forecast data, so I decided to just remove the feature.
  4. Fixed a javascript bug on the combo graph page that prevented users from specifying custom date ranges.

Changes in v2.0.5

Primarily a bugfix for properly retrieveing 24- and 48-hour forecast temperatures. Also includes updates to the included JpGraph and ADODB packages.

Changes in v2.0.4

The included versions of JpGraph and ADODB were upgraded to the latest versions (JpGraph v1.7, ADODB v2.3.0). A bug related to the display of the x-axis label was fixed, and the x-axis label now only displays every other label when the axis has more than 15 entries. This helps increase readability of the axis labels.

Changes in v2.0.3

Some minor bugfixes to correct for situations where the fist location in the database does not have a location ID of zero. Fix contributed by Park Hayes (park.e.hays@lmco.com).

Changes in v2.0.2

This release includes updates of the graphics engine, jpgraph, to version 1.6.1, and the database connectivity component, adodb, to version 1.9.0. There were also a few minor bugfixes for betting handling of negative values and missing data. There were no database schema changes. Becuase there were no database schema changes, the upgrade is a simple matter of replaceing files. See the upgrade instructions for details.

Changes in v2.0.1

There was a problem handling negative dewpoints. Fixed.

The admin UI was not persisting the wget command. Fixed.

If you're upgrading from 2.0, you only need to copy the 'get_temp.php', 'globals.php' and 'save_globals.php' files from the new v2.0.1 tarball into your existing 2.0 directory. Thanks to Len Hardy for finding the problems.

Changes in v2.0

In the quest for an even simpler installation process, there is now an official install/upgrade script. Written in perl, the script can be used to either (1) perform a new Weather Plotter installation, or (2) upgrade one or more existing Weather Plotter sites. I've automated as much as possible, and the script should directly support both Postgres and MySQL users.

Weather Plotter now features full multi-city support. You no longer have to setup multiple weather plotter installations in order to track weather at more than one city. And in order to make this multi-city support even easier, all configuration can now be performed through a password-protected web-based application. This means no more editing of text files! The features are mostly self-explanatory. To access the Admin applications point your browser to the login.php file after you complete the installation. Remeber the password you specified during the installation step.

This version also includes a new XMLRPC-based directory-server integration mechanism. This is implemented as a set of two new cron jobs that will: (1) Make sure all of your weather plotter cities are registered and kept up-to-date in the official Weather Plotter Network listing page (http://www.buberel.org/wp-network/). (2) Periodically download the list of all other Weather Plotter sites (from the WP-Network server) to your local database to allow you and your visitors to compare local cities (hosted on your server) to the weather data hosted on any other Weather Plotter Server on the WP-Network. The actual weather data is not transferred in this process, only enough information about other Weather Plotter sites in order to perform city-vs-city weather data comparisons.

Weather Plotter also now has the ability to visually compare weather data between any two cities on the Weather Plotter Network (described above). This means you can compare any of the seven weather data series over any arbitrary time range between any two cities. Hours of fun!

Changes in v1.1

The major feature addition in the release is the Combo graph. This graph lets the user choose the start/end date, the group-by function (hour, day, month, or year), and which data series they want plotted (temp, humidity, dewpoint, pressure, wind speed, wind chill, and heat index). This gives the user a complete control over the visualization of the data set. There are also some new statistics on the extended stats page: 48-hour forecast analysis, plus average and median humidity stats.

In this version, we are switching to the use of Cascading Style Sheets (CSS) to make the Weather-Plotter UI more customizable. The style sheet template is part of the 'site-meta.inc.php.template' file. People who are upgrading from a previous version will have to manually update their 'site-meta.inc.php' file to include the new style information.

There have also been some database changes (changing some data fields from small (2-byte) integers to regular 4-byte integers to make the aggregate functions work properly. There are two database upgrade scripts included, one for Postgres and one for MySQL. See the upgrade section for more information on how to apply the upgrade.

Changes in v1.0.1

A fix for a typo in stats.php that resulted in the daily stats being shown in the monthly row.

Changes in v1.0

A new variable added to site.inc.php: $timezone_offset is used to adjust temperature time readings in get_temp.php if the server is in a different timezone than the city being monitored. You will either have to re-generate the configuration files, or hand-edit site.inc.php to include this variable.

A slight change in site-name.inc.php: The name of the city can be enclosed in an HREF to link users back to ./index.php. See site-name.inc.php.template for details. This makes navigation much easier in certain situations.

Four new database fields have been added to the weather_data2 table. The fields are hat_index, wind_chill, wind_direction and wind_speed. You'll need to use the script db-upgrade-0.5-1.0.sql to add the fields before running get_temp.php to collect data again.

To take advantage of the new database fields, the weekly/monthly/yearly high-low temperature graph now includes overlays of max heat index and min wind chill for each day plotted. There is also a new set of graphs specifically for viewing wind speed and direction data in a drill-down fashion from year->month->day->hour.

Changes in v0.5

This release adds news graphs that include not only temperature and humidity, but dewpoint and barometric pressure too! There is also a new extended statistics page that will tell you, on a month by month basis, how accurate the weather forecast has been in your area. Some of these new features do require a database schema upgrade (script provided). Dewpoint and barometric pressure graphs supplied by Chris Danis (danish@debian.org). The MySQL support has also been greatly improved thanks to Michael Blandford ( mikey@blandford.net).

Changes in v0.4

This release adds the ability to plot not only the actual temperatures, but also the 24-hour and 48-hour forecasts. You can now finally see how accurate the weather office really is on its temperatures.

Also new is the separation of site customizations from the rest of the sources. You will need to first copy each site*.inc.php.template file to the individual site*.inc.php file, and then edit these to reflect your own preferences. (This is described in greater detail in the Installation section below. If you fail to make the copies, weather-plotter won't run. If you copy the files but don't edit them, you'll get weather from a location close to one of the developers. Don't forget that there are 2 separate URLs for getting the data - one for the actuals, and one for the forecasts.

Changes in v0.3

This is mainly a bug-fix release. Thanks to several downloaders (Ed Wilts and Michael Blandford), I have done some further cleanup to several pieces that should make installation more fool-proof. This includes using relative pathnames in the jpgraph.php module, as well as removing the last (I hope) references to the local filesystem where I do development.

There were a few typos in the table-creation sql script that caused the indices to not be created properly. If you have accumulated data using the v0.2 sql script. you might want to take a look inside the script and manually run the 'create index' lines on your existing database to make sure they were created correctly.

I have put one new feature into the get_temp.php scipt: a retries mechanism. Just in case the NOAA server is inaccessible for a short period, the script will retry a configurable number of times (using a configurable interval between retries) before it gives up. If it does give up, it will let you know by sending a mail messags to you instead of dying silently.

One thing to note is that the NOAA webserver is now periodically sending out redirection headers, which are not handled well (at all) by PHP's built-in file() command. As a fix, I have changed the 'get_temp.php' script to use the external 'wget' command to fetch the weather data. wget is much more robust about handling redirection and other HTTP silliness and should be more reliable. You should check the top section of the 'get_temp.php' script to make sure the variable $wget_command uses the correct path to the installation of wget on your system. I am using wget v1.6. Other versions will probably work.

Changes in v0.2

The major change since the last release is the move to using ADODB for PHP. ADODB is a database-neutral data connectivity layer for PHP. As a results of this, Weather Plotter will now run on Postgres, MySql, Oracle, MSSQL and other database. You only need to modify one file to switch between database servers. In addition, I spent some time cleaning up the php code and the HTML to make everything a bit more modular and easier to distribute. I have also decided to just include the two external packages into one download file to make things easier (JPGraph v1.2.2 from http://www.aditus.nu/jpgraph/ and ADODB v1.12 from http://php.weblogs.com/ADODB).

Email announcements...

If you would like to receive e-mail announcements regarding new releases of Weather Plotter, please use the freshmeat project subscription feature at: http://freshmeat.net/projects/weatherplotter/.

Vote for Weather Plotter

If you use and enjoy Weather Plotter, go ahead and comment/rate the project at Freshmeat: http://freshmeat.net/projects/weatherplotter/.

Why Weather Plotter was built...

The motivation for doing this was simple: How hot was it yesterday? What about the day before? How cold did it get last week? If you've ever asked yourself these questions, you probably also noticed that it was impossible to find this type of information on the internet. At the same time, purchasing and configuring a weather gathering device is beyond the means of most people. Looking around, we found that the National Weather Service makes its weather statistics available on-line in plain HTML form. With that information publicly available, it was possible to build the Weather Plotter.

How it works...

The basic theory of operation goes like this: A cron job periodically goes out and fetches the Nation Weather Service HTML page containing the weather data for the city you are interested in (The example uses http://iwin.nws.noaa.gov /iwin/ca/hourly.html). This cron script then parses out the temperature, humidity and dewpoint from the response.

A second cron job, executed once a day, gathers the forcast high and low temperatures for today (24-hour forecast) and tomorrow (48-hour forecast). The data is then inserted into the the database. There is then another set of PHP pages that, when invoked, will query this database, pull out the data of interest, and then graph it. Sounds simple, right?

Requirements

To begin, here is a list of the prerequisites you'll need in order to make this work using the source code provided (links below):

A web server running the mod_php module, fully configured. Everything you see here was developed using version: php-4.0.4pl1-3 on Redhat 7.1/Linux 2.4.4 with Apache 1.3.19. This may work with other versions, but YMMV.

A configured and working database server supported by ADODB (http://php.weblogs.com/ADODB). The primary testing platform for Weather Plotter is Postgres7, but ADODB also suports MySQL, Oracle, MSSQL and others.

The GNU wget utility, version 1.6 or later. This is used to fetch the web pages that contain the weather data. This can be found at http://www.gnu.org/softwar e/wget/wget.html.

Installation (See Upgrade section below for upgrading from 2.0.x)

First, download the weather-plotter-2.1.2.tgz file to somewhere convenient, like your home directory. Next, copy the .tgz file into your web server's docroot. If you don't know where the docroot is, check your apache configuration (your docroot might be something like /var/www/htdocs).

> cd /your/www/docroot/
> tar zxf weather-plotter-2.1.2.tgz

At this point, you should have a weather-plotter-2.1.2 directory in your docroot dir. 'cd' into that directory. Once inside that directory, you will need to make sure that the files are owned by, and can be read and executed by the web server. On my Debian system, the web server runs as user 'www-data'. On RedHat systems, this web server usually runs as user 'apache'.

> cd weather-plotter-2.1.2
> chown -R apache.daemon * > chmod -R ug+rx * > chmod -R u+w *

The next step in the install is to manually configure several of the important Weather Plotter script files. Use your favorite text editor on the following files:

  1. site.inc.php: This file contains generic variables for operation of the Weather Plotter software. The file contains comments that explain each variable and what it should be set to.
  2. site-db-connect.inc.php: This file contains the variables that Weather Plotter will use to connect to the database. Without correct settings for these values, nothing will work.

Next, you will need to create the database in which the weather plotter data will be stored. The specific commands for doing this depend on the type of database server you are using. These commands should normally be executed as the same user that the web server is running as (something like: 'www-data' on Debian Linux, or 'apache' on RedHat and Mandrake). This will ensure that the web server has permissions to create the actual database tables and insert data into them.

The important part in this step is to use the exact same database name that you configured in the 'site-db-connect.inc.php' file. The name 'weather' is a good choice.

For postgres, you issue the create database command from the psql prompt:

> psql template1
psql> create database weather;

For mysql, you issue the create database command from mysql prompt:

> mysql
mysql> create database weather;

Once you have created the database successfully, you need to complete the remaining installation and configuration steps using your browser. So point a browser at http://locahost/weather-plotter-2.1.2/db-install.php. You may have to adjust the URL, depending on the server location and folder name that your Weather Plotter files are stored in. This page will create the database tables inside your specified database. Once that process has completed, press the link at the bottom of the page to proceed to the next step.

On the next page, there will be two password fields. Choose a new password, and enter it into both fields, and submit the form. Assuming you typed the same password twice, you will be asked to login. Enter the password once again, and you will be taken to tha main admin page.

On the main admin page, you should first click on 'Global Settings'. Verify that the settings here are correct, and press save. You should then go ahead and start to add Weather Plotter sites to your server. Click the 'Add Location' link, fill in all the fields, and submit the form. Setup as many sites as you like.

Once you've completed the initial WP Site setup, click the 'Grab Data Now' button to force Weather Plotter to fetch the first data sample. You'll see some diagnostic output on the page. Just click 'Back' to get back to the Admin page. You should also probably click the 'Register Local Sites' and 'Download Remote Site List' now. These will enable the 'Compare To...' features allowing to compare local weather data with other Weather Plotter sites. You should also click on the 'Regenerate all Weather Stastics' link, which will prepare the data for the Yearly Comparison graphs.

You're almost done. The last step is to configure your server to automatically fetch new data samples, and to periodically refresh the list of remote weather plotter sites. You can also use programs like 'wget' to execute your weather-plotter related cronjobs over HTTP (remember to adjust the URLs to match your server name and the directory name for the weather plotter scripts). Also note that you if you have a command line php interpreter ('php') you can also use that to execute these cron jobs:

# Get the temperature data at 25 minutes after each hour.
25 * * * * /usr/bin/wget http://localhost/weather/get_temp.php -O - >/dev/null

# Once daily, generate weather statistics for the current year, month and day
12 3 * * * /usr/bin/wget http://localhost/weather/generate-weather-facts.php -O - >/dev/null

# Get all WP Network sites at 1AM on sundays
0 1 * * 0 /usr/bin/wget http://localhost/weather/get_wpn_sites.php -O - >/dev/null

# Update your information in the WPN server every sunday at 2 AM.
0 2 * * 0 /usr/bin/wget http://localhost/weather/register_local_sites.php -O - >/dev/null

Remember, to reach the admin login page using 'http://localhost/weather/login.php'. You will be asked for the password that you specified earlier.

Need to upgrade?

From 2.1.0 or 2.1.1:If you are upgrading from version 2.1.0 or 2.1.1 of Weather Plotter, simply replace your existing weather plotter files with the files the tar archive. The only two files from your existing installation that you should make backup copies of are 'site.inc.php' and 'site-db-connect.inc.php'. They contain important information that you won't want to re-enter. Make copies of these files in a safe location. Then untar the tar archive (tar zxf weather-plotter-2.1.2.tgz). This will untar into a folder named 'weather-plotter-2.1.2'. You can then copy your backup versions of 'site.inc.php' and 'site-db-connect.inc.php' into this new folder. Once done, you can then replace your existing weather-plotter folder with the new one.

As a last step, you will also need to install a nightly cron job for the 'generate-weather-facts.php' script:

# Once daily, generate weather statistics for the current year, month and day
12 3 * * * /usr/bin/wget http://localhost/weather/generate-weather-facts.php -O - >/dev/null

From 2.0.x: If you are upgrading from version 2.0.x of Weather Plotter, follow the instructions below:

The first step in the upgrade procedure is to simply replace your existing weather plotter files with the files the tar archive. The only two files from your existing installation that you should make backup copies of are 'site.inc.php' and 'site-db-connect.inc.php'. They contain important information that you won't want to re-enter. Make copies of these files in a safe location. Then untar the tar archive (tar zxf weather-plotter-2.1.2.tgz). This will untar into a folder named 'weather-plotter-2.1.2'. You can then copy your backup versions of 'site.inc.php' and 'site-db-connect.inc.php' into this new folder. Once done, you can then replace your existing weather-plotter folder with the new one.

Version 2.1.2 of Weather Plotter also includes some additions to the database schema. So assuming you have completed the first step (verify that the basic graphs and data displays still work before you proceed), you can then invoke the following URL to upgrade the database: http://locahost/weather-plotter-2.1.2/db-upgrade.php. This step will only work if the user your web server connects to the database as (typically 'apache' or 'www-data') has the ability to create tables. Try adjusting databse privileges if you get any errors in this step.

Once this completes, you should probably log into the admin page (http;//localhost/weather-plotter-2.1.2/login.php), and click the 'Regenerate All Weather Statistics' link. This will take a few minutes (depening on the amount of weather data you have collected), but is required for the new Yearly Comparison graphs to work the first time. While you're in the Admin app, you should probably verify your Global Settings to make sure everything is correct.

It is probably a very good idea to ensure the permissions on all files in your weather plotter directory can be read and executed by the web server (something like chown apache.daemon -R weather-plotter-2.1.2 and chmod -R a+rx weather-plotter-2.1.2/).

As a last step, you will also need to install a nightly cron job for the 'generate-weather-facts.php' script:

# Once daily, generate weather statistics for the current year, month and day
12 3 * * * /usr/bin/wget http://localhost/weather/generate-weather-facts.php -O - >/dev/null

License

All of this is licensed under the GPL. See the LICENSE file for details.

Credits

Weather Plotter was originally developed by Jason L. Buberel. Other fixes and features have been contributed by Ed Wilts and Chris Danis.