Meteo Setup Quick Guide
=======================

This quick guide is intended as a short introduction into what you have
to do to set up a Davis weather station with a Unix system. It does not
provide many details, but lots of pointers to other documentation.

The short story
---------------

Here are the main steps in setting up meteo:

- install the hardware, get a connection between the computer and the
  weather station
- install the software: configure, make, make install
- configure:
  * add entries to the station and sensor tables in the database to
    describe your station
  * modify meteo.xml so as to describe your setup (database, connection,
    sensors, graphs)
- start the processes, make sure the are automatically restarted on boot
- configure your web server if you want to use the meteo browser
- configure current.cgi/current.xsl for current data display
- find and report bugs

Hardware
--------

Presently, only the Vantage Pro and Weather Monitor II stations are
supported. It would be fairly simple to add Davis other stations, as they
all use the same LOOP command (see doc/vtechref.txt) to retrieve
sensor images, which all have a similar structure (offsets are different,
see doc/Techref.txt and doc/vtechref.txt).

Make sure you have a working connection between the station and
your computer. If you connect directly to a serial port, the cables
and connectors provided by Davis will work. UDS serial dongles for
linux will also work. If you are using a device server like the
Lantronix UDS-10, you'll need a null modem connector. See doc/uds10
for details on using a Lantronix UDS-10.

To test the connection to a Vantage Pro, you can use the TEST command
(see doc/vtechref.txt), send the string TEST followed by a \r, the
station should echo TEST.


Install
-------

To build the software, some prerequisite packages are required, consult
the README for details. Install these first.

The package configuration only has two nonstandard options which are
both described in the second half of the INSTALL file, both are related
to the meteo browser. INSTALL also gives some platform specific
guidance (near the end), and FAQ.


Configure
---------

The configuration is contained in a single configuration XML file
called meteo.xml, usually in /usr/local/etc/meteo.xml, but varying
according to your configuration options. There is also a sample
meteo-60.xml, which shows how 60 second interval graphs can be
produced.

The configuration file is described in the manual page meteo.xml(5).
There is also a sample configuration file included in the conf
directory.

There also is a DTD in the conf directory of the distribution,
checking your configuration file against the DTD can help pinpoint
problems. Use the command 

    xmllint --validurl file:///path/to/meteo.dtd /path/to/meteo.xml

to validate the configuration file.

Starting with meteo-0.9.0, some information about station and available
sensors needs to put in the database (similar to the examples already
in db/meteo.sql). For details, read the meteo.sql(5) man page.


Run
---

The README explains the process structure of meteo. Note that only
the programs that collect data from the station (meteopoll), store the data
in the database (meteodequeuer) and compute long term averages (meteoavg)
are constantly running. To produce graphs to display in your webserver,
you need to add a cron job, meteojob can serve as a first approximation
for your station.

If you plan to use the meteobrowser, you'll find more info in
browser/README.browser.


Upgrade
-------

If you are upgrading from a very old version, you should convert the
database timestamps to the new GMT format (the old format used local
time, causing headaches when time switch to daylight saving time). The
migration is described in support/How_to_migrate. If your database
structure does not match the current format (see db/meteo.sql), you
should first alter your tables so that it fits. See the MySQL manual
for details.

Upgrading to 0.9.0 or from an earlier release requires that you update
the database structure and migrate the existing data to the new format.
The new structure is defined in db/meteo.sql, and the meteodbmigrate
program in the support directory can be used to migrate the database
to the new format. Note that you can do this after you have started
the new meteopoll, the old tables are preserved. However, you will
probably want to rebuild the averages table using the -a option to
meteoavg, since some averages may have been computed by the new meteoavg
with incomplete data (old data not yet converted).

--
$Id: SETUP,v 1.7 2006/05/16 11:19:54 afm Exp $