oasisnt HOWTO

Table of Contents

Introduction
Hardware Requirements
Software Components
Overview
Installation

Copying files to the PC
Installing software packages

Cygwin
VC++

Setting up the environment variables

Hardware Setup
Running oasisnt
Troubleshooting
OASIS Commands
TNC Commands
Modifying Configuration
Known Bugs
Resources

Introduction

This HOWTO covers the installation of oasisnt, a Windows NT port of the OASIS
data collection and processing software. oasisnt provides the software infrastructure for
real time scheduled data downloads from drifters and tethered moorings.

Hardware Requirements

• PC (P166, 32MB RAM, Serial Port, CDROM, Ethernet Adapter, 90 MB HDD space,
  Windows NT (must have administrator privledges), Winzip, Hyperterminal)
• Pac Comm TNC
• Radio
• Radio antenna (dummy load OK for bench test)
• Radio power supply
• OASIS controller with radio, packet antenna installed
• OASIS Power Supply (14VDC 8A)
• Cables:

• OASIS power
• OASIS console
• Radio power
• TNC power
• TNC data (DB 9 M/F)
• Radio antenna

Optional:

• If PC does not have 2 available serial ports, a second PC
  is useful to use as a terminal for the OASIS can.
• A terminal emulator (for communicating with the OASIS can)
• Connection to Internet (for downloading updated third-party software)

Software Components

oasisnt consists of the following major software components:

• oasisnt - Download scripts and executables
• Cygwin - Windows port of UNIX shell commands
• tcl - TCL interpreter for data monitor scripts (optional, part of the Cygwin package)
• MS Visual C++ - (v4.0+) May be installed and uninstalled to provide DLL support for getoasis

Overview

The structure of oasisnt leverages the original UNIX-based data download infrastructure used to service fixed-position moorings. There are software components to replicate the UNIX environment in Windows, modified versions of the data download scripts, and some added scripts to satisfy the need view data (GPS, e.g.) in real time in a drifter context.

When oasisnt is installed, a cron task invokes the main OASIS download script (/oasis/bin/download) at an interval specified in the crontab file. The download script calls individual download scripts (e.g., get<mooring>) to download from potentially several drifters in turn. The individual download scripts call several scripts:

• getoasis (shell script to download raw data via packet radio)
• extract (shell script to extract data from the raw data)
• oasisc.tcl (TCL script to invoke the data monitor, oasiss.tcl)
• decode (called by oasiss.tcl to display data as it is processed)

download also calls process, a shell script that updates the headers on the extracted data using a combination of awk scripts and shell commands.

The cron task is sometimes configured to archive (tar) data on a daily basis, depending on the duration of the deployment.

Installation

The installation procedure consists of these steps:

1. Copying files to the PC
2. Setting up the environment variables
3. Installing software packages ( cygwin, tcl etc.)

Copying Files to the PC

All of the necessary files (except for VC++) are contained in the oasisnt directory. Copy the directory to drive C: on the PC used for deployment (other drives may be used, the download scripts should not be affected as long as the oasisnt directory is placed in the top level directory on the installation drive).

1. (Optional) Copy the folder \oasisnt\desktop to the PC desktop (any name is OK).
   

Setting Up Environment Variables

Several environment variables need to be set to allow the oasisnt DOS batch files to work correctly.

1. Open the NT Control Panel and choose the System setup utility.
2. Click the Environment tab.
3. Add the following System (not User) Environment variables:

   OASIS_PATH \oasisnt\oasis\bin;\oasisnt\oasis\raw;\oasisnt\oasis\<mooring name>;
   CYGWIN_PATH /cygwin/usr/bin

4. Modify the PATH system environment variable for all users, adding the environment variables above:
   

   <your path>;%OASIS_PATH%;%CYGWIN_PATH%

5. Reboot the computer (the system path will not update until the computer is rebooted)

Install Software Packages

VC++

Since it is not known exactly what DLLs are required for VC++ programs, it is easiest just to install VC++ and then uninstall it (unless you have it or need it) using the Add/Remove tool from the NT Control Panel. When uninstalling, choose not to remove shared resources when prompted.

Cygwin

The following procedure may be used to set up Cygwin:

1. Run \oasisnt\cygwin\setup.exe.
   
   
2. Choose 'Install From Local Directory' to install from the version included on the oasisnt CD, or 'Install From Internet' to connect to Red Hat and install the latest version.
   
   
3. Select the packages you wish to use and install to \cygwin. It is strongly recommended that you install all packages. The Cygwin installer allows you to install, uninstall and update packages by clicking on the version next to the package name. The part/full button allows you to see a long or short list of available packages; the packages available depend on what is already installed and whether you are installing from the disk or from the internet.
   
   The following packages are required:

   autoconf, automake, bash, binutils, cron, cygrunsvr, cygwin, diff, file, fileutils, findutils, gawk, grep, gzip, inetutils, less, login, make, man, opengl, patch, regex, sed, sh-utils, tar, tcsh, time, unzip, vim, w32api, which, zip

   
   The following packages are optional:
   
   

• tcltk (used for DOS download monitor)
• mutt ( Mail client used to send download failure notices by email)
• ssmtp (MTA used by mutt)
• ncurses (used by the mutt mail client)
• ash (used by ssmtp)
• gettext (used by the mutt mail client)
  
  
4. Add a local oasis user (described in the Cygwin HOWTO)
5. Consult the Cygwin HOWTO for detailed setup information on the cron service

You may wish to conserve disk space by installing only the required packages (Though this is not recommended, since there are many dependencies between packages). Still, the following packages are not strictly required by oasisnt:

bison, byacc, bzip2, clear, cpio, crypt, cvs, expect, flux, gdb, gdbm, gettext, ghostscript, gprep, groff, irc jbigkit, jpeg, libpng, m4, mingw, mt, ncftp, newlibman, openssh, openssl, pcre, perl, popt, postgresql, python, readline, rxwt, squid, termcap, tetexbeta, tiff, wget, xpm-nox

Once Cygwin has been installed, open a Cygwin bash shell (Start>Programs>Cygnus Solutions>Bash Shell 1.1) and create symbolic links to the oasisnt and oasis directories as follows:

ln --symbolic /cygdrive/c/oasisnt /oasisnt
ln --symbolic /cygdrive/c/oasis /oasisnt/oasis

tcltk (optional)

Tcl/tk is an optional Cygwin package. oasisnt uses cygtclsh80 to run a Tcl client-server pair that displays the download results each hour. If you do not want this capability, you may comment it out of get<mooring>, and skip this section.

ssmtp (optional)

ssmtp is an optional Cygwin package. oasisnt uses the ssmtp MTA to send email to a list of users when a download fails. If you do not want this capability, you may comment it out of get<mooring>, and skip this section.

Run config-ssmtp to create the ssmtp configuration file. You will be prompted for the host name, mail name, smtp server host name, and smtp server port. Additional information may be found in the Cygwin HOWTO. Note: The Cygwin ash package must be installed for this script to run,

mutt (optional)

Mutt is an optional Cygwin package. oasisnt uses the mutt mail client to send email to a list of users when a download fails. If you do not want this capability, you may comment it out of get<mooring>, and skip this section. Note: The Cygwin ncurses and gettext packages must be installed for this mutt to run.

• If it is not already installed, install the mutt package from the contrib directory
• Uncomment the "set sendmail =" line in /etc/Muttrc and edit it to read:

set sendmail = "/usr/sbin/ssmtp"

Additional information may be found in the Cygwin HOWTO.

Hardware Setup

*** WARNING ***
Do not apply power to the radio or OASIS can unless an antenna or dummy load is connected to the radio and GPS. Failure to do so could damage the radio or GPS transceiver.
***************

Connections

• Connect the TNC, radio, antenna and power supply.
• Connect the TNC to PC COM1.
• Connect the OASIS console cable to PC COM2.

Basic Setup

• Boot the PC and log in.
• Power on the OASIS can by installing the power jumper plug.
• Use \oasisnt\desktop\oasisdirect.htm to establish a terminal window to the OASIS console.

  **** WARNING: the following will reset the log data memory ****

• Issue a reset all and reestablish the connection with the OASIS can.
• Issue the time command at the OASIS prompt (time should be set to GMT time); reset the time if necessary.

Optional

• Set any driver parameters that differ from the ROM defaults using the dp command.
• Use the con command to connect to and configure or initialize instruments, as needed.
• Check Radio Telemetry:
  • Exit the direct console connection using the quit commant at the OASIS prompt.
  • Use \oasisnt\desktop\oasistnc.htm to establish a terminal window to the TNC.
  • Enable TNC character echo at the TNC prompt:

    cmd:echo on (you won't be able to see what you type in until after this command)

  • Issue the connect command at the TNC prompt:

    cmd: c <mooring name>

It may take some time to connect, depending on how often the OASIS radio driver is configured to run.
The TNC Tx light should flash periodically until the connection is made, at which point, you should be able to hear data transfer begin on the radio speaker. When the connection is made, the OASIS prompt should appear and function normally (though slower than a direct connection).

Running oasisnt

Log in to the PC using an account with administrator privledges.

Starting Data Downloads

Start the Cygwin cron service (see the Cygwin HOWTO) and (as user oasis) create or load a crontab file (e.g., /oasis/bin/oasis.cron).

Stopping Data Downloads

From a Cygwin terminal, use ps -ef to find any running download (getoasis) processes.
If any are running, use kill <PID of getoasis>.
As user oasis, use crontab -r to uninstall the oasis crontab file. If there are other jobs in the crontab file that must continue to run, then use

touch /oasis/bin/download.lock

instead. Remember to delete this file when resuming the downloads again.

Troubleshooting

Symptom

Errors appear during the download script

Try

Review installation instructions to make sure that all files are installed in the correct place and that all files contain correct path information. Check environment variables. Make sure that the DLLs supplied with VC++ are installed.

Symptom

The download process never appears to run

Try

Erase the lockfile, \oasisnt\oasis\bin\download.lock, if it exists.

OASIS Commands

This is a partial list of OASIS commands and TNC control commands. For a complete reference, please consult the OASIS command reference on the oasisnt CDROM and the user's manual provided by the TNC manufacturer.

h,?
Display command summary

dp [driver]
With no arguments, shows driver status list. Called with driver, allows you to set driver parameters.
Carriage return or timeout ends prompt for parameter/value input.

time [hh mm ss yy mm dd]
Get/set date and time

con [driver]
Connect to instrument using driver.

reset all [delay]
Hard reset the can after delay seconds.
WARNING: logged data is lost, log memory pointers reset, driver parameters restored to ROM defaults,
hot patch programs lost.

reset [delay]
Soft reset the can after delay seconds.
Log memory, driver parameters and hot patch data retained.

TNC Commands

C [V <repeater TNC>]
Connect to another TNC (e.g. c 2000D4 v MBARI-2)

D
Disconnect TNC connection

E [on|off]
Echo Enable/Disable (so you can see what you are typing)

B
Bye End TNC session on remote connection

RESTART
Restart TNC using battery backed RAM defaults. Use this to stop and restart the TNC.

RESET
Reset TNC with factory defaults: WARNING--Parameters, heard lists and TNC messages are lost

Modifying Configuration

If there is a need to install any components to directories other than the defaults, modifications to scripts and directories may be required.

Here is a checklist of files and environment variables that may require modification:

\oasisnt\oasis\bin\download
\oasisnt\oasis\bin\get<mooring>
\oasisnt\oasis\bin\process
\oasisnt\oasis\bin\tarraw
\oasisnt\oasis\cfg\<mooring>.cfg
\oasisnt\oasis\cfg\template\<instrument>.hdt

OASIS_PATH

Adding/Changing Moorings

The following is a general guideline for configuring moorings; Specific modifications to files depend on mooring configuration.

To add mooring <moor>:

Create directories...

Copy...

\oasisnt\oasis\cfg\sample.cfg \oasisnt\oasis\cfg\<moor>.cfg
\oasisnt\oasis\bin\sample\getmoor \oasisnt\oasis\bin\get<other moor>

Modify...

\oasisnt\oasis\cfg\<moor>.cfg
\oasisnt\oasis\cfg\template\<instrument>.hdt
\oasisnt\oasis\cfg\get<moor>
\oasisnt\oasis\bin\download
\oasisnt\oasis\bin\process
\oasisnt\oasis\bin\tarraw

Create Headers...

Run header generation script:
tcsh /oasisnt/oasis/bin/util/lmkheaders

Known Bugs

Resources

http://cygwin.com

http://www.scriptics.com

OASIS Command Reference