What's this?
------------

This directory contains interface programs to retrieve data from a
Davis Instruments weather station. The architecture is sufficiently
generic to acommodate other weather stations as well, but as I don't
have access to other hardware, no interface code is included.

The home of the meteo tools is at http://meteo.othello.ch, where 
you will always find the current release. For sample installations
see http://www.othello.ch/meteo and http://grossalp.othello.ch/meteo.
There is also a mailing list, you subscribe to it by sending a message
containing nothing but the line

	subscribe meteo

to majordomo@lists.othello.ch.

Please also read other documentation available with the package:

SETUP   a quick guide to setting up a Davis weather station with a
        Unix system

INSTALL provides some help for compiling and installing the package, also
        contains some FAQ regarding build and install.

html/meteo-install.html
        contributed document, guides through the installation

doc/uds10
	how to connect a Vantage Pro station via a Lantronix UDS10
	device server

doc/graphing
	how to use meteo to graph data that does not come directly from
	a weather station

What can it be used for
-----------------------

Have a look at the gallery on the meteo web site, there are many
intereesting around the world.  Please fill in the gallery_template.xml
and send it to andreas.mueller@othello.ch so that your station can
be included in the gallery as well.

There are other appliations:

- Bruce Bennet usese meteo to provide the weather data for xastir, which
  is th Amateur Radio "APRS" (Automatic Position Reporting System) for
  Linux. Have a look at his site http://wx.findu.com/kb8rop for current
  data. His software is at

	http://cvs.sourceforge.net/viewcvs.py/xastir/xastir/src/Davis

Weather Stations supported
--------------------------

The following stations have been reported to work with meteo:

	Station			first release supporting the station

	WeatherMonitorII	all releases
	Vantage Pro		all releases
	Perception		Lajeado release 0.9.0
	Wizzard			Lajeado release 0.9.0
	GroWeather		release 0.9.10


Prerequisites
-------------

Meteo compiles and works with gcc 2.95.3 and gcc 3.x, but I've only tested
some gcc 3.x versions, and no non-GNU compilers. Since the code is usually
quite straight forward, and does not use any real GNUisms, it may also work
with other compilers. On Solaris, gcc must be compiled to use GNU ld and
GNU as, otherwise the meteopoll binary will crash when invalid data is
read from the station, this is a Sun assembler or linker bug.

Meteo requires quite a few packages that still do not come with all the
modern operating systems it is known to run on. Linux users have a
distinct advantage here, the usually don't have to do anything to get
these packages:

GD	To compile this package, you will need a complete installation of
	Tom Boutell's GD2 library, which you can get from www.boutell.com.
	Note that the meteo programs expect to be able to create PNG images,
	so zlib and libpng must also be installed. Some installations with
	GD already installed may also need the freetype libraries, as GD
	may be built with freetype support.

	Starting with 0.8.2 it is no longer possible to use gd1, as the
	alpha support only present in gd2 is now used.

	(SuSE 8.2: add gdlib-devel)

MySQL	The meteo programs write the data retrieved from the weather 
	station into a MySQL database. To build the programs, you therefore
	need the MySQL client libraries. Visit www.mysql.com for details
	on how to get MySQL for your plattform.

	(SuSE 8.2: add mysql-devel)

gettext	The meteo package expects the GNU gettext to be present on
	the system. As only the optional meteo browser is affected by
	gettext, the configure script does not check for the presence of
	gettext.

	(SuSE 8.2: add gettext)

libxml2	libxml2 is the XML parser of the Gnome project. It's main advantage
	is that it is quite portable, written in C, full featured and
	well documented. Since 0.5.0, libxml2 is required, as the
	configuration file now is in XML format. Check http://www.libxml.org
	for current version.

	(SuSE 8.2: add libxml2-devel)

libxslt	(optional) if you want to rebuild the HTML pages, you will need
	libxslt, since the HTML pages are transformed from XML sources

	(SuSE 9.0: add libxslt) 

If you plan to use the weather underground interface scripts contributed
by Walter Poxon, you will need additional packages: perl and some perl
modules related to database access. Read Walter Poxons howto in 
meteo-install.html for details. These scripts are currently not up to date,
but work by some meteo mailing list members is underway to get them
working for the current meteo release.


Weather Station URLs
--------------------

These programs use a URL type description of the weather-station
to talk to and the parameters necessary to connect. There are basically 
two methods to connect to a weather station: 

 1. through a direct serial connection, indicated by an URL of the
    form 

	file:///dev/ttyS0

    this form allows for things that are not really devices like pipes
    to other processes that themselves get the data from a `real'
    device. It even allows for Unix domain sockets.

 2. through a TCP connection to a terminal server that has the weather
    station connected to one of its serial ports, indicated by a 
    URL of the form

	tcp://hostname:port

There are also special URLs for logging, see the meteo(1) manual page
for these.


Architecture
------------

The meteo programs use separate processes to retrieve the data from the
weather station, to compute averages over intervals of 5min, 30min, 2h
and a day, and to draw graphs suitable for a web page. A full installation
will have three processes permanently running:

meteopoll	collect data from the station and write a record to
		the message queue used to decouple database operations
		from weather station communication. Can also maintain
		a file containing current values for real time display.

meteodequeue	pulls update messages of the message queue and sends
		them to the database. By handling database updates outside
		the process that communicates with the weather station,
		long queries blocking the stationdata table will not
		cause weather data to be lost.

meteoavg	compute averages over longer intervals than one minute.
		As these averaging operations can be quite time
		consuming, moving them outside the meteopoll program
		again improves reliablity.

To produce the graphs, the separate programm meteodraw is called, usually
from a cron job, or from within the meteobrowser PHP script. More architectural
detail can be found in the doc/architecture file.


Installation
------------

Read the INSTALL for installation instructions. Please also check the end
of that file for plattform specific instructions. meteo has been tested on
Solaris 2.9 and on Linux 2.4, which are the plattforms of the two sample
installations. It also works on Mac OS X (large parts of the development
are actually done on a Powerbook) and there are users using it on FreeBSD.

There is a README in the db directory that explains how to set up the
MySQL tables.

Special installation instructions for the meteo browser (meteobrowser.php)
can be found in the file README.browser.


Thanks
------

Over time, many people have contributed to meteo by asking questions (thus
pointing out deficiencies in code and/or documentation), providing bug
reports or fixes. I hope I've recorded all of them in the AUTHORS file.
Thanks to all those who have helped.

The most substantial contribution came from the university Univates
(http://www.univates.br) in Lajeado, Rio Grande do Sul, Brazil. The
university has sponsored the development of the 0.9.0 release. I would
like to express my gratitude towards Univates for their generous help.


Directions for Contributors
---------------------------

If possible, please send diffs against the most recent version of meteo.
This can save me a lot of time and improves the probability that Your
contribution gets included in the release. If you add something completely
new, it may be more convenient to put it in a separate file. In this case
send all new files, and diffs for the files that have changed. In any
event, try to change as little as possible of the existing code, since
extensive changes make for very large patches, that are difficult to read.
If there is no other way, please contact me first, so that we can team up.

--
$Id: README.tmpl,v 1.19 2006/05/07 19:51:18 afm Exp $