Oww !Help / README file

Dr. Simon J. Melhuish
http://melhuish.info/simon/projects/oww/
Tuesday 6th August, 2002
Version 0.67

Key

Oww works with three operating system types. Comments specific to one type are indicated according to this key:

• RISC OS
• Linux (and other Unix flavours)
• MS Windows (using Cygwin)

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.

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. It runs without its GUI using Cygwin on MS Windows.

Information on the weather station may be found on the web at http://www.ibutton.com/

Also see my article.

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.

Client and Server, oww and owwnogui

Two versions of Oww are contained in the distribution. The original program, Oww, includes a graphical user interface (GUI). The second version has the GUI removed, and is called owwnogui. Both versions include all the same features (except for the GUI).

Oww is unusual in that it is both a client and a server. This arises mainly from the nature of the RISC OS environment, and because of the common code base, the same structure applies to Oww on Linux. Although there exists an owwnogui for RISC OS there is no advantage in using it, because of the non-pre-emptive multitasking. So the GUI version will commonly have to act as server to external clients. But it may also be desired to use it as a client itself.

On Linux systems it would generally be sensible to run both owwnogui acting as server (perhaps run by a privileged user), and oww acting as a client (run by a normal user).

Installation

RISC OS

On RISC OS, simply copy the application to your preferred location. You may have to update your !System application with extra resources, for example if you have not already installed a Web browser.

Linux

Other Operating Systems

Oww has been successfully built on some other Unix-like operating systems. Fortunately the GNU autotools take care of many of the portability issues, but you may need to set a couple of extra configure options.

Running Oww

RISC OS: Double click the !Oww application, wherever you have put it.

Linux: Execute oww from a shell or for example, the “Run Command” dialogue on KDE

The GUI version of Oww should now be running (I will describe running Owwnogui later).

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 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 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

Data source

Oww can receive data from several types of data source:

• If you have a weather station connected to the local computer you may choose “Local”. Note that you will have to set up various parameters for the local connexion from the Devices dialogue. Here you can set the update interval – the time between readings.
• If your locally-connected weather station has already been set up with a copy of owwnogui running it, or if the weather station is running on another computer, using Oww, select “Oww”, and enter the name of the server host (“localhost” if it is the same machine) and the port number (leave this as the default unless you know otherwise).
• If the weather station is connected to a PC running Arne Henriksen’s WServer program on MS Windows, select “Arne”, and enter the host name and port number.
• Some weather station users upload their readings to a server run by Dallas Semiconductor (Oww can do this too). To download readings first click “List”; this will fetch the current list of contributing stations. Then you can pick one of the stations from the pop-up menu, and select the “Dallas” radio button.

The “Browser” entry chooses the method used for opening map Web pages.

When you have made your choices click “Update”.

Display

In the Display section you may select imperial or metric units for wind speed, temperature, barometric pressure and the rain gauge. Note that the values sent to other applications independent of the selected units.

Animate

controls animation of the weather station graphic in the display window

Log file

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

Interval sets the time between successive log entries. Values are averaged over this period.

Upload

The Upload section governs uploading of data to Web server data repositories at Dallas Semiconductor, Ham Weather and The Weather Underground.

The Interval setting controls the frequency of uploads. Data are averaged over this interval, which can be quite different from the logging interval. 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 one of the 1-wire chips. To replace this with a name on the Dallas Web page you must contact them with your serial number. For users of the original Dallas weather station this is the wind vane switch ID (see the Vane switch entry in the Devices dialogue or vane in the devices file). For the later AAG version 3 unit, use the vane adc ID (see the Vane ADC entry in the Devices dialogue or vaneadc in the 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 longitude 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 their site 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.

Stats

Reset allows the rain gauge and general-purpose counter readings to be reset to zero. Click Reset. You may also enable a Daily (at 00:00) reset.

Any changes to setup (except Data source) take immediate effect. However, only clicking Save records these changes for use the next time the program is started. Close closes the setup dialogue. If you want to run owwnogui with the chosen setup values click SaveNG. This will write the setup to a special setup file, checked by owwnogui at startup.

Devices

Driver

Oww communicates with 1-wire devices through a serial port adaptor. The Driver item of the Devices dialogue is for serial port 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

Search

The rest of 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.

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 assignments 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.

Some devices (e.g. rain gauge, thermometers, barometers) have the facility for changing their calibration. For instance, you might have set your rain gauge to tip every 0.25 mm rather than every 0.01 inches. To change calibration values, select the device from the list, and choose which calibration value to set from the pop-up list, to the left, below the device asignment area. Enter your new value in the icon to the right and hit enter. There is a separate page describing the calibration settings for each device type.

To the bottom of the devices dialogue is the area controlling the wind vane devices. To determine wind direction from an original Dallas or early AAG unit, 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 AAG version 3 unit uses an analogue-to-digital conversion chip, and this procedure is not required. You may still offset the vane readout, to compensate for the direction of hardware installation.

When all is correct click Save.

I strongly advise you to take a copy of the devices file 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.

ini2dev

For users wishing to use Oww having previously set up under Windows, I have written a short utility called ini2dev. This converts the Dallas ini file format to Oww device file format.

Linux

ini2dev will build when you make Oww

RISC OS

ini2dev is pre-compiled

It is <Oww$Dir>.ini2dev

Run the program thus:

ini2dev ini_file dev_file

ini2dev on its own gives examples

External programs

[RISC OS]

External programs may access weather station data by several methods (other than reading the log files). The client / server interfaces are described below, but first there are some simpler choices:

RISC OS: On each update Oww sets the Oww$Update system variable (you can change the variable name from the “updatevar” setup entry). 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. The variable named in “logvar” is updated on each log update.

On Linux “updatevar” and “logvar” may contain file names. These will have a single line recorded in them with the latest readings or log line respectively.

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:

Client interfaces

By connecting through a sockets interface (TCP network socket or Unix socket) client programs may receive data from an Oww server using several protocols.

(More information will follow.)

Oww Client is one such program.

Commands

I have added the facility to run a command after each update, after a line of the log is written, or before / after 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 proceeding with the Web 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

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.

Command line arguments

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 third argument is given, this specifies the stats file, to hold rain gauge 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 file locations by giving one to three extra command-line arguments. Otherwise Oww will read from .oww_setup .oww_devices and .oww_statsin 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.

owwnogui

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 for building owwnogui alone

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.

To run owwnogui as a daemon (i.e. disconnected from the terminal and its parent process) add the ‘-d’ switch to the command line.

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

With the original weather station design it can be difficult to read the wind vane direction in conditions when it 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:

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

I have a big list of things to do on Oww. Feel free to contact me with your own suggestions, but please don't be offended if I ignore them!

Licence

This program is free for non-commercial use. Contact me for permission to include in CD compilations or similar. The Linux version is open source, under the terms of the “Artistic Licence”.

	SUMMARY  · PROJECTS  · SIMON  · MELHUISH.INFO