INTRODUCTION · PROGRAMS · NEWS · HARDWARE · DOCUMENTS · DOWNLOAD · MISCELLANEOUS · LINKS

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.

Oww Log 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.

Since starting owwl I have found it useful as a protocol for serving data from the QUaD radio telescope (part of my day job at Cardiff University). So owwlog has in part been developed in my role as a researcher, on the University's time. A couple of features are therefore rather specific (to cryogenic thermometry), and are indicated like this.

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:

sjm@quest2:~> 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. 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 and GSL 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 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.