$Id: README,v 1.4 2010/01/15 01:51:17 grog Exp grog $

This is an early snapshot of my WH-1080 code.  Currently it works on
FreeBSD and NetBSD.  I'm still actively developing it, and numerous
things will change.  Note that many of the programs are buggy and may
crash, but all can be restarted without problem.

At some time in the future, I'll create proper installation stuff for
this software.  Currently I strongly recommend leaving it in the
structure it is.

Greg Lehey, 20 December 2009

This hierarchy contains:

  Top level directory:

     - wh1080, a program that collects data from the station and
       stores it in a MySQL database.  This program frequently runs
       into trouble with the USB connection, at least under FreeBSD.
       When this happens, there appears to be no recovery except for
       restarting the program, so that's what I do.  I haven't been
       able to get it to attach under Linux; freeing the kernel driver
       (necessary under Linux) doesn't work.

    - report, which I think is obsolete, but which I haven't deleted
      yet.

    - xreport, which takes the data from the database at regular
      intervals and sends it to Wunderground
      (http://www.wunderground.com/wundermap)

    - yreport, which creates a header file for the PHP page index.php
      (see below).  This currently frequently crashes, probably
      because of inadequate error checking.

    - dereel-compare, which generates data for plotting comparative
      temperatures between Dereel (where I live) and Ballarat (the
      closest BoM station).

    - wundersend, a script to send data to Wunderground.  Invoked by
      xreport.

   I'm still working on code for a configuration file; in the
   meantime, I enter the configuration manually in config.c.  Most of
   the current entries are still tailored to my specific environment,
   and will definitely need change.

  Directory db

   - mkdb is SQL code to create the tables I'm using, currently
     observations for local observations, remote_observations for
     observations I pull in from Wunderground and the BoM, and
     lastreport to keep track of what has been reported to remote
     stations.

   - Script getremote-today, which pulls in observations fro
     Wunderground and the BoM.  It has a hard-coded list of station
     IDs.

   - insertwunderground and insertBoM, which take the readings from
     the script and insert them into the database.  Currently very
     kludgy.

   - tidyobservations, SQL code which fixes various breakage I've seen
     in the incoming data.

   - Other stuff which I think is no longer needed.

  Directory plots

  - Script doplots, which creates various plots.  Two optional
    parameters, date and enddate.  enddate is the first day not to be
    considered in the plots (i.e. they go from 0:0 on date to 0:0 on
    enddate).  date defaults to today, and enddate defaults to date +
    1.  Currently I'm still working on the multi-day plots, and
    there's nothing to display them.

  - Various gnuplot scripts for the individual plots.  Most won't need
    changing, but clearly plot-Ballarat-Dereel.gnuplot is just an
    example.  Change the list at the top of gnuplots to get rid of it.

  Directory web

  - File index.php, which displays values for today and yesterday.  It
    doesn't access the database, so it can be put on remote web
    servers.  It accesses the file current.php (see config.c
    config.php_header) and the plots created by doplot.

  - File db.php, effectively the same page as index.php, but it gets
    its info directly from the database.  It's also capable of
    creating plots on demand.

  - File comparison.php, which displays comparative graphs of local
    and remote stations, also generated by plots/doplots.

Getting the pig to fly

  - Install MySQL, PHP and gnuplot.
  - Fix config.c to match local conditions.
  - Build the software.
  - Create the web hierarchy.
  - Create the database.  By default the database is called 'weather';
    if you want something else, edit db/mkdb.  Then:

      mysql < db/mkdb

  - Create the configuration.  Edit db/mkconfig and do:

      mysql < db/mkconfig

  - Run:

      while :; do wh1080; done &
      while :; do ./xreport -v -d  ; done &
      while :; do yreport; sleep 20; done &

About the WH-108[01]:

  - I've seen from the comparative readings in my area
    (http://www.lemis.com/grog/weather/comparison.php) that many
    weather stations show very inaccurate barometric pressures.  Mine
    showed pressures that were uniformly about 14 hPa too low.  I've
    compensated for this by adding a correction factor in the config.

  - I still don't trust the rainfall readings.  They are supposed to
    be in units of 0.3 mm.  I forget where this information comes
    from, but it agrees with the information displayed on the unit.
    But I also have a manual rain gauge, and it shows only about 70%
    of the readings of the WH-1080.  I'm still observing this, but it
    looks like I'm due for another correction factor.