Oww help file
=-=-=-=-=-=-=

Dr. Simon J. Melhuish
http://oww.sourceforge.net/

Please see the Web site for the most up-to-date documentation, especially
this section:


  http://oww.sourceforge.net/docs.html

Monday 8th January, 2001
Version 0.63


Disclaimer 
=-=-=-=-=-

Oww is free software, and is supplied "as is" with no form of guarantee
whatsoever. Use of any of the material in this distribution is entirely at
your own risk.

You should also note that there are risks inherent in attaching an outdoor
device such as the weather station to your computer. In particular, you are
at risk of lightning strikes, which may cause damage to your serial port, or
worse. See the weather station Web site for a discussion of lightning risks
and how to mitigate them.

In particular I make no guarantee that the software will not cause damage to
your 1-wire devices. For example, users should note that according to the data
sheet of the DS1923 "hygrochron", it is in principal possible to put the
device into a locked-up state by incorrect software commands, effectively
destroying it. Whilst I aim not to introduce any such faults, I cannot give
any guarantee that this, or similar problems, will not occur.


Introduction
=-=-=-=-=-=-

Oww provides communication with the Dallas Semiconductor 1-Wire Weather
Station. This measures temperature, wind speed and wind direction. An
optional extra is a tipping-bucket rain gauge.

Oww is now available for both RISC OS and Linux. The non-gui version of oww
(owwnogui) can also be built on cygwin running unding MS Windows.

Information on the weather station may be found on the web at

  http://www.ibutton.com/

Also see my article:

  http://oww.sourceforge.net/oww.html

RISC OS Oww supports interactive help. Run "!Help" (or similar) for tips.
Under Linux, "tooltips" are also available, by pausing the mouse pointer over
items of interest.

See below for instructions on installing and running Oww on either RISC OS or
Linux computers.


The display window 
=-=-=-=-=-=-=-=-=-

The display window presents a pictorial view of the weather station with a
compass rose along side. The view of the weather station may be animated (see
"Setup", below). Above the weather station are displayed the current time and
temperature. Current wind speed is displayed above the compass rose, which
indicates current wind direction.

If a rain gauge is connected, its current reading will be written at the
bottom of the window. Both the current total rainfall and the current
rainfall rate are shown.

For these displays to function the program must first determine the serial
numbers of the weather station devices; see "Devices", below.


Menu
=-=-

The menu is available from both the iconbar icon (RISC OS only) and the
display window. "Info" and "Quit" require no explanation. "Setup.." accesses
the "Setup" dialogue. "Devices.." accesses the "Devices" dialogue.
"Messages..." pops up the "Messages" window, which shows any warning or error
messages logged by Oww.


Setup
=-=-=

In the "Display" section you may select imperial or metric units for wind
speed, temperature, barometer and the rain gauge. Note that the values
broadcast to other applications (RISC OS only) are also in the selected
units. Oww clients taking data from an Oww server do not depend on these
settings on the server, but rather use their own local settings.

"Animate" controls animation of the weather station graphic in the display
window.

"Use Trh" sets whether the thermometer inside the weather station or the
temperature of the humidity sensor (Trh - if available) is used as the
primary temperature reading. This is the value shown in the main window and
used for Web uploads.

The "Update" area sets the time between successive weather station
measurements.

The "Log file" area controls measurement logging. You may select one of three
logging modes:

  None		No logging at all
  
  Daily		Write to log files of the form mmdd in directory yymmdd, in
  		the specified directory location. E.g. if you enter $.logs
		data for 21st March, 2000, will be stored in
		$.logs.0003.000321
		
		[Linux: for '.' read '/']
		
  Single	A single log file is written, at the specified file location.
  
You may select the directory / file name by [RISC OS] dragging the icon to a
directory or [Linux] navigating through a SaveAs dialogue.

"Interval" sets the time between successive log entries.

The "Internet" section governs uploading of data to Web server data
repositories at Dallas Semiconductor and The Weather Underground.

The "Interval" setting controls the frequency of uploads. Enter the number of
seconds between uploads. Selecting "Use times" will make uploading snap to
clock times. For instance, 300 seconds with this snap will upload at 00:00,
00:05, 00:10, ..., 13:00, 13:05, &c. Without this selected, the upload times
will depend on the time at which the program is started.

If you need to go through a proxy for Web access enter its name under "http
proxy". Include "http://" at the start. Also enable the proxy by ticking the
option gadget.

To upload to Dallas, enter the URL of the servlet (currently
http://192.168.1.3/servlet/WeatherServlet) and tick the option. The servlet
distinguishes weather stations by the ID laser-written on the temperature
sensor chip. To replace this with a name on the Dallas Web page you must
contact them with your serial number (see the "T1" entry in your Devices
file). The servlet also uses your station's latitude and longitude to provide
a button to go to a map page. You should enter your latitude and longtitude
in the setup window, using decimal degrees north and east.

To upload to The Weather Underground you must obtain a user name and password
from them. Visit http://www.wunderground.com/weatherstation/ for more
information. These must be entered by "User / Pass". Enter the base URL
(http://www.wunderground.com/weatherstation/updateweatherstation.php) and
enable the upload option. Note that the password is held in plain text in the
setup file, so do not use a "valuable" password when registering.

Note that all text entries require you to hit "return" on completion.

"Reset gauge" allows the gauge reading to be reset to zero. Click
"Reset". You must save the setup for the new starting point and reset date
to apply the next time Oww is run. You may also enable a "Daily" (at 00:00)
reset.

Any changes to setup take immediate effect. However, only clicking "Save"
records these changes for use the next time the program is started. "Close"
closes the setup dialogue.


Devices
=-=-=-=

The devices dialogue is concerned with the determination of 1-wire device
serial numbers. Each device has a unique 64-bit serial number, so that even
though several devices will be connected to the 1-wire bus, only the device
addressed by the correct serial number will communicate with the host. Serial
numbers are determined by a search procedure on the bus.

Before Oww can communicate with the weather station you must lead it through
the search procedure. This must be done before installation of the weather
station outside, as you will need access to the wind vane.

If you are using a rain gauge as well, you should attach it and determine its
serial number also.

Start by clicking "Search", at the top of the dialogue. This should discover
any devices that might belong to weather station equipment, and list them in
the scrolling window below the button. Devices will be assigned automatically
to different functions. However, it is possible the program might not guess
some asignments correctly. For example, it might assign the counter chip in a
rain gauge to the anemometer (does spinning the anemometer increment the rain
reading?). In a case such as this you must click on the raingauge entry in
the list. The text icons below the list will read Counter and Raingauge.
To change the allocation to Anemometer click the button on the right for a
pop-up menu, and select the correct entry. This will update the list, and the
weather station will be restarted.

You may click "Search" any time, to find new devices. Old assignments will be
preserved, and wind vane entries will not be changed.

Below the list is the area controlling the wind vane devices. To determine
wind direction Oww searches for ROM ID chips on the bus, which become active
if the magnet attached at the top of the wind vane shaft closes the
corresponding reed switch. To associate the detect serial numbers with
compass points you must slowly rotate the vane clockwise, starting
(preferably) at north. It is best to set the update time to 1 second for this
procedure. Each time a chip is found the entry to the right of the Vanes
field is incremented, until all eight are known. Check that all is in order
by slowly rotating the vane through another 360°. If two chips were active
when the search was started, they might be in the wrong order. If this is
found to be the case move the vane slightly and start again. If the set
values do not give the correct alignment after installation you may set an
Offset to ±8 compass points. Wipe vanes causes Oww to forget all the wind
vane ROM ID devices, for you to start a fresh wind vane search.

The final item of the devices dialogue is for communications control. 

[RISC OS:

Select the appropriate block driver from the pop-up list. If "!SerialDev"
(version 12, or later, required) has not booted, the program will supply
"Internal" and "InternalPC" drivers. Either driver seems to work with the
RiscPC standard serial port.

The number entry sets the port number for devices that have more than one
port.]

[Linux:

Just select your normal serial port device, appropriate to the serial port
you are using, e.g. /dev/ttyS0]

When all is correct click "Save".

I strongly advise you to take a copy of !Oww.devices after these steps, or at
least lock the file. Once the weather station is installed it will be
inconvenient if this has to be repeated due to a slip up.


External programs
=-=-=-=-=-=-=-=-=

[RISC OS]

External programs may access weather station data by two methods (other than
reading the log files).

On each update Oww sets the "Oww$Logged" system variable. It has the same
format as a log line. This may be read by, for example, a simple cgi program
if the host computer runs a web server.

Oww also broadcasts data as a wimp message, using the same format as the
ThermIIC program. These messages may be read by TherMon, which makes
real-time plots of the values. It also saves data in a form that can be read
by simple cgi programs for live creation of on-line weather plots. See
TherMon and ThermGif for more information:

  http://www.simon.melhuish.net/projects/

[Linux and RISC OS]

I have added the facility to run a command after each update, after a line of
the log is written, or before an http request. The commands are set in the
setup file using these entries:

  postupdate
  postlog
  httpprecom
  httppostcom

[RISC OS] The command is executed with a system() command. This means it
blocks whilst the command executes. Use the taskwindow system command to
pre-emptivley multitask your external program if necessary.

[Linux] postupdate, postlog and httppostcom are forked to child processes,
and should not halt Oww. httpprecom will halt Oww until it finishes. This is
in case you need to execute a program and wait for it to finish, e.g. to
raise your Internet connexion, before proceding with theWeb uploads.



Alternative resource files
=-=-=-=-=-=-=-=-=-=-=-=-=-

[RISC OS only]

The graphics required for animation take a large chunk of memory (~1.2 MB).
You might prefer to do without these graphics, in which case you should
rename the files "!Oww.res" and "!Oww.Sprites", replacing them with the files
in "!Oww.AltRes".


Testing
=-=-=-=

RISC OS	Platform	Proc.	OK?	Comments
3.7	RISC PC		SA	yes	
3.5	RISC PC		ARM610	yes
3.1	A5000		ARM3	yes

Linux
SuSE 8.0

using KDE and Gnome + SawMill

Others? Please let me know.

Note that recent RISC OS versions of Oww require the TextGadget module. This
in turn requires a recent window manager. If your system runs other programs
that use the TextGadget module, such as !Browse, Oww should run.


Compiling
=-=-=-=-=

[Linux only]

The Linux version of Oww is supplied as a source tarball. Un-archive it with

  tar xzf <tarballname>

cd into the resulting directory and follow the generic installation
instructions; viz:

  ./configure
  make
  su -c "make install"

You will need several libraries for a successful build. Ensure that you have
"development" distributions of the following:

gtk (including gdk and glib)
libglade
gdk_pixbuf
libghttp

N.B. I am still devloping the configuration file. In particular it is not
very clever about looking for libghttp, which unlike the other libraries,
does not provide a utility program to tell you where it is installed. If the
make process does not find the header files or the library you might copy
them to more typical locations.

I noticed with my latest linux installation (SuSE 7.1) that libglade, &c, no
longer put their m4 files where aclocal looks by default. So look out for
warnings about missing macros if you run aclocal (e.g. if autogen.sh gets
run). You'll find the macro files somewhere like /opt/gnome/share/aclocal,
and you could just pass this in $ACLOCAL_FLAGS. But it's probably simpler
to link them into the main aclocal macro directory:
  aclocal --print-ac-dir
  
If you are not interested in the full gui version, and so don't want to
install gtk+ and so forth, you can follow this procedure to build just
owwnogui:

  ./configure --disable-gui
  cd src
  make owwnogui

Running
=-=-=-=

RISC OS:

You would usually just double-click the !Oww icon. But if you launch the
application with a command line (e.g. from your !Boot sequence) you may
specify one to three extra arguments. One argument specifies the name of the
file to be read and written to for setup values. If another argument is
given, this specifies the devices file, which holds 1-wire bus serial
numbers, &c. If a thrid argument is given, this specifies the stats file, to
hold rauge offsets, &c.

When the setup / devices / stats files are not specified, Oww tries to read
them from the "choices" directory, usually in your main !Boot directory. If
the files are not found, they are looked for inside the !Oww application
directory. Note that the files will not exist until you save your setup /
devices settings from the relevant dialogue boxes.

You need several relocatable modules. See !Oww.!Run if in doubt. If you do
not have the Acorn URL and HTTP modules (e.g. supplied with !Browse) Web
upload will not work (so turn it off). The rest of Oww should function
correctly, however.


Linux:

Oww will be installed somewhere determined by the "configure" script, e.g.
/usr/local/bin/oww  You should be able to run the program by typing "oww". As
for the RISC OS version (see above) you may override the default setup /
devices / stats file locations by giving one to three extra command-line
arguments. Otherwise Oww will read from ".oww_setup", ".oww_devices" and
".oww_stats" in the current working directory, if they exist. If these do not
exist, Oww will use "setup", "devices" and "stats" from a shared location,
determined by the configure script (e.g. /usr/local/share/). When using these
files, they may only be changed if you have write permission in the shared
directory. If you intend for several users to be able to run Oww, I suggest
you run it first as root, and save your setup and devices settings. Then
running Oww as a normal user will load suitable files from the shared area.
Users may save their own setup files, which will reside in their cwd, and
will load by default in future.


Running without the GUI
=-=-=-=-=-=-=-=-=-=-=-=

In some circumstances you may prefer to run Oww without its graphical user
interface. For instance, you could call it from a CGI program on a web
server, or you might want to use an old, low-spec' PC without an X server.
For this reason I have created an alternative build of Oww that bypasses all
the GUI calls. This is how to obtain it:
	
RISC OS
	The executable file is at !Oww.OwwNoGui
	The convenience obey file !Oww.!RunNoGui runs OwwNoGui 
	  in a fresh task window.
		
Linux
	owwnogui is compiled and installed as a part of the normal build
	  process (or see above)
	

owwnogui finds its setup and devices files according to the normal rules.
Note that since it has no user interface for Setup and Devices, you must
create the files initially using the normal Oww (or create them by hand).
owwnogui sends its output to stdout  i.e. your command line. You might want
to redirect it to a file, or to null:

  OwwNoGui > null:  	[RISC OS]
  owwnogui > /dev/null 	[Linux])

If you want to run owwnogui for a single reading, for example to respond to a
CGI request for current weather data, enter a value of 0 (zero) on the
interval line of setup.


Problems?
=-=-=-=-=

If Oww behaves badly one of the first things to check is the setup file. You
can create a fresh setup file by removing the old one (e.g. rename it),
running Oww, and clicking "Save" under the setup dialogue.


Wind vane
=-=-=-=-=

The design of the wind vane means that it can be difficult to read in
conditions when the vane swings about rapidly. This is because the various
reed switches open and close in rapid succession, and reading of switch IDs
can be interrupted. Oww tries very hard to cope under extreme circumstances,
but you may sometimes notice the read-out not quite keeping up with a rapidly
moving vane. This is a problem with the Dallas Windows software too. There is
a hardware fix, that involves adding some extra resistors on the vane ID
chips. See this message the weather station mailing list:

  http://www.dalsemi.com/mailarchive/weather/200002/msg00243.html

If the very worst conditions (e.g. you take off the vane and spin the shaft
at many rpm by hand!) Oww may have to give up reading the vane from time to
time, and reset the 1-wire bus and the weather station, for a restart ten
seconds later.


To do
=-=-=

Here is a list of some features I am looking at for incorporation into Oww:

  Pressure sensor (barometer)
  
  Build "TherMon" into the Linux version of Oww
  
  Scripts to build plots from the log files for upload to your web site
    (already available for RISC OS version via TherMon)
    

Licence
=-=-=-=

This program is free for non-commercial use. Contact me for permission to
include in CD compilations or similar.


Acknowledgements
=-=-=-=-=-=-=-=-

Oww has been developed with the help of several users. But in particular I
would like to thank the following:

  Dan Awtrey, at Dallas Semiconductor, who donated one of my weather
stations.

  Eric Laird, who donated a humidity sensor kit.

