Owwlog
======

Data collected by Oww may be made available to clients using my owwl
protocol. I have made available a C library for clients (or servers).
There is full Doxygen documentation available.

I have written one such client program for logging readout data in csv
format. This is owwlog. The source code is available from the Oww CVS
repository on sourceforge.


Owwlog features
===============

Oww Log is a command line (or daemon) program for recording data read
from Oww servers thorugh the owwl protocol. It was developed from Owwl
as a part of the QUaD project at Cardiff University, Astronomy 
Instrumentation Group. Owwlog now supports full weather data streams from 
Oww.

You may download the source from Sourceforge Build and install in the usual 
way, and enter "owwlog -?" for usage information.


Command Line
============

To get the list of possible commands for your version of owwlog you
should type:

owwlog --help

You should then see something like this:

owwlog --help
Usage: owwlog [OPTION...]
  -B, --Broadcaster                    Run as a re-broadcasting server
  -b, --broadcast=port number          Port number to run a re-broadcasting
                                       server
  -C, --Calibration=directory path     Use files in this directory for
                                       calibration
  -D, --Directory=directory path       Log to files in this directory
  -d, --daemon                         Run in daemon mode
  -e, --execute=file                   Execute file after log updates
  -I, --ISO                            Print ISO 8601 time values
  -i, --Ignore=stream list             Ignore data streams
  -L, --Live=file                      Log live updates to this file
  -l, --Log=log path                   Log to this file
  -p, --port=port number               Port number to connect on
  -q, --quiet                          Don't print messages after startup
  -r, --rrdfile=file                   Update this RRD database
  -S, --Snap                           Snap log times
  -s, --server=server                  Server to contact
  -t, --time=time in seconds           Log interval
  -u, --unix                           Print Unix time values
  -v, --version                        Print version information

Help options:
  -?, --help                           Show this help message
  --usage                              Display brief usage message

There follows a more verbose explanation of each of these options:

-B, --Broadcaster
    Run as a re-broadcasting server
    Enable this option if you want the data received from the server
    re-broadcast, i.e. owwlog will itself act as a server. This can be
    useful if generating calibrated data, or to act as a proxy, for
    situations where a client has access blocked through the usual port.
-b, --broadcast=port number
    Port number to run a re-broadcasting server
    If the defaults port number, 8899, is not suitable, enter a
    different value with this option.
-C, --Calibration=directory path
    Use files in this directory for calibration
    For a stream such as "Diode 1", if a calibration directory argument
    is given, owwlog will try to read from the file "Diode_1" in this
    directory. If the file can be opened, calibration of incoming data
    will take place.
-D, --Directory=directory path
    Log to files in this directory
    A fresh comma-separated value file of logged data will be generated
    starting at midnight for each day that owwlog is run. These files
    will be stored in a sub-directory for each month, in the given
    directory. The format for the name of the monthly sub-directory is
    YYMM. The format for daily log files is YYMMDD.txt
-d, --daemon
    Run in daemon mode
    This is only available for Linux versions. The process will
    disassociate itself from its controlling terminal and become a
    daemon. This means the process won't die when you log off.
-e, --execute=file
    Execute file after log updates
    This provides for execution, e.g. of a script, after each time a log
    line is output to the log file. The could be used to recreate plot
    graphics, &c.
-I, --ISO
    Print ISO 8601 time values
    ISO 8601 look like this: 2004-06-03 17:50:32. This saves confusion
    between U.K. / U.S. / Continental formats.
-i, --Ignore=stream list
    Ignore data streams
    This allows for data streams selectively to be ignored by an
    instance of owwlog. Since you can run more than one instance of
    owwlog at a time, logging to different log files / directories, you
    can use this facility to filter some streams to one file, and others
    to another file.
    The stream list has to be a single command line argument, so you'll
    have to use quotes around it, or it will be split at the spaces. The
    names in the list should be excatly as they appear in the log
    headers, separated by commas. You may use * and # as wildcards for
    multiple and single characters respectively. For example: |"Diode
    5,Diode 1#,Grt 4*"| This will turn off Diode 5, Diodes 10, 11, &c,
    and all three Grt 4 channels (V, Vq and I).
-L, --Live=file
    Log live updates to this file
    A live file consists of a single line (no header) giving the latest
    set of readout results, i.e. from a single reading - not integrated.
-l, --Log=log path
    Log to this file
    As an alternative to the daily log file mechanism you may log
    continuously to a single log file. This may make more sense for
    individual lab tests.
-p, --port=port number
    Port number to connect on
    This is the port number owwlog connects to. You shouldn't need to
    alter it from the default.
-q, --quiet
    Don't print messages after startup
    With this option set, messages other than the startup messages will
    not be output. So this blocks the logging messages, etc. This is
    useful if owwlog is running in the background, logging warnings and
    errors to a log file.
-r, --rrdfile=file
    Update this RRD database
    All data streams that are not set to be ignored are output to a
    round-robin database file, using rrdtool. The RRD has first to be
    created using "rrdtool create". Logged data may be plotted with
    "rrdtool graph".
-S, --Snap
    Snap log times
    With snap enabled, owwlog would write logs at 17:32:00, 17:32:10,
    17:32:20, &c, if set to 10-s logging, rather than, for example,
    17:32:03, 17:32:130, 17:32:23
-s, --server=server
    Server to contact
    This is the network name or number of the server - the TINI.
    Currently this is |sec-tini02.stanford.edu|
-t, --time=time in seconds
    Log interval
    This is the logging interval, or integration time in seconds.
-u, --unix
    Print Unix time values
    You may choose to write Unix times to the log file. The Unix time is
    the number of seconds since the 1970-01-01. Anybody who understands
    Unix time without the aid of a computer, should be considered dangerous.
-v, --version
    Print version information
    Prints the version string. Please cite this number when reporting
    any problems.
Help options:
-?, --help
    Show this help message
    Use this option to get the current set of possible command line
    arguments
--usage
    Display brief usage message
    Get a short usage description, like this:

    Usage: owwlog [-dISu?] [-D|--Directory directory path] [-d|--daemon]
            [-e|--execute file] [-I|--ISO] [-i|--Ignore stream list]
            [-L|--Live file] [-l|--Log log path] [-p|--port port number] [-S|--Snap]
            [-s|--server server] [-t|--time time in seconds] [-u|--unix] [-?|--help]
            [--usage]


Download
========

owwlog may be down-loaded from the project download page on Sourceforge. 
For Linux fetch the .tar.gz or .rpm file, and for Windows fetch the .exe file.


Owwlog Linux Installation
=========================

On Linux Owwlog conforms to use usual autotools practices, and so should
be familiar to anyone used to installing Linux applications from source.
So, having obtained a source distribution run the configure script,
and then make.

./configure
make
su -c "make install"

CVS users may have to regernerate the configure script first, by
running the autogen.sh script.

Owwlog depends on the popt and gsl libraries - you'll have to get these
if you haven't got them already. If installing from RPMs, make sure you
have the "development" versions, necessary for compiling programs
against the libraries.


Owwlog Windows Installation
===========================

For my "port" to MS Windows I have built owwlog using MinGW (a build of
the gcc C compiler suite with libraries to tie-in with Windows), using
MinGW Developer Studio <http://www.parinya.ca/>. The project file for
this is on CVS.

I have now made a Windows installer for owwlog, available from the
download area. To install owwlog, simply run the installer!

You'll need to install Popt and GSL first, with the GnuWin32 popt
<http://gnuwin32.sourceforge.net/downlinks/popt-bin.php> and GSL
<http://gnuwin32.sourceforge.net/downlinks/gsl.php> installers.

This will create an owwlog program group, and a desktop icon ? owwlog.
This is set up with some (hopefully) suitable command line arguments. It
will connect to host and log every 5 seconds to logdir in your "My
Documents" folder. Of course you can change the arguments (e.g. replace
host with the real host name) from the shortcut properties.


Running Owwlog
==============

You will need to add some command line arguments to do anything at all
with owwlog. Refer to the section above <#args> for argument
descriptions. You could of course run owwlog by hand, from a command
shell, adding the necessary arguments each time. But it is more sensible
to enter them into a script file.

On my work machine I have a script at /etc/init.d/owwlog. If you have 
taken a look at that - don't panic! This script is way over-complicated, 
because it's an init script. This is the system Linux uses to get everything 
going in the right sequence at start up. I suggest you use a script consisting 
of just one line - the line you'd use in your shell (but you might need to 
add a line to change directory). However, my init script will serve as an 
example of the owwlog arguments I use.

If you're trying to use owwlog on Windows, perhaps the easiest way to
make a "script" is to create a shortcut to owwlog.exe. Then the
right-button-click -> properties dialogue will permit the addition of
command line arguments after the target name.

Windows users can now use the Desktop icon created by the installer.
Change its parameters with the Properties dialogue if necessary.


RRDTool
=======

As noted above, owwlog may update a round-robin database, named with the
-r, --rrdfile=file option. With this option set, after each update
owwlog will generate a command line calling rrdtool, which it then
executes. This command is as follows:

rrdtool update filename rrd_template unixtime:

rrd_template is generated from the data stream names (as listed in the
header line of any log file), replacing all non-alpha-numeric characters
with underscore ('_'). For example, "Wind 1 Bearing" becomes
"Wind_1_Bearing". Therefore you must also use these names when
generating the database with rrdtool create.
