A Quick and Dirty Guide to Using OASIS General ------- There are two ways to talk to OASIS: directly via the user interface serial port (UserIF driver) and via packet radio (Radio driver). Since they share a serial port, only one of these two methods may be active at a time. To display a help screen, type "H ". That's the letter H, followed by a carriage return. For the remainder of this document, stands for carraiage return. The help screen gives a list of the available commands, and a short description. It doesn't tell you what parameters the commands need. If you connect to OASIS via packet radio, unless you're clever in setting the local TNC parameters, the radio won't send anything until you enter a carriage return. That means that, even when sending something that normally wouldn't require a carriage return (e.g., sending a ctrl-B to send a break to ADCP, or ctrl-D to disconnect from an instrument), you need to send the message followed by (ctrl-B , ctrl-D respectively). OASIS commands are case-insensitive. For example, "CON", "con", and "Con" all connect to an instrument. The individual instruments may be case sensitive, however. Bringing Up OASIS After Losing Power ------------------------------------ 1) Hit the reset button. The first time OASIS powers up after reset, it looks for input on the radio first. If you're trying to talk on the UserIF port, you need to wait 30 seconds and hit reset again. Alternatively, you can keep the reset button depressed for 5 seconds. This asserts a hardware reset, after which OASIS will look at the UserIF port. 2) OASIS should prompt with something like: OASIS ver 1.2 OASIS> Reinitialize the system by typing "RESET ALL ". This will reinitalize everything to their default parameters, including: - All drivers and their parameters - All system-wide parameters (those shown via the "Parms" command) - TNC (Packet radio) parameters - Clears the logging memory 3) If the instruments also lost power, they may need to be initialized. In general, you need to read the manual for each instrument in order to initialize it, but here's a set of quick parameters that will at least verify that each instrument is running, or restart it if not. 3a) Type "con adcp " to connect to ADCP. Type ctrl-B to give it a break character to wake it up. It should respond with a wakeup message. Type the following commands (comments in parens) Z (Reset) P00005 (Sets 5 pings/ensemble) Q020 (Sets 20 bins) O125 (Sets earth referenced coordinates) V000100 (Sets 1 sec. between pings) R00150000 (Sets 15 minutes between ensembles) W064 (Sets binary data transfer) 3b) Disconnect from ADCP by typing ctrl-D. In the case of ADCP (only), this also sends the ADCPSTR string in binary mode, which by default is S239 (start sampling). 3c) Type "con ctd " to connect to CTD. Type several carriage returns to wake it up. Verify that it's collecting data by typing "SS ". If it sends a data message, it's OK. This is normally the case, since it has internal batteries. If it's not logging, you need to use the "SI" (sample interval) and "GL" (go-logging) commands to restart it. Disconnect from CTD by typing ctrl-D. 3d) Type "con atlas " to connect to ATLAS. Verify it's collecting data by typing ctrl-T (it will probably take two; the first wakes it up). It should respond with a data message. If not, enter FORTH mode by typing ctrl-C, and then type "DEP ". 3e) The remaining instruments (spectro, GPS) should be OK, but you can connect to them if you wish. 4) When done setting up the instruments, synchronize the data gathering by typing "Sync ". OASIS will then monitor the ADCP continuously until it receives a valid ADCP message (or times out after one entire ADCP interval, 30 minutes by default). When it gets a valid set of ADCP data, it runs all the other drivers to get their data. It also restarts the spectroradiometer. After this happens (usually 15 minutes), data gathering from all instruments should be synchronized. 5) Type "quit " to disconnect from OASIS. You don't need to wait for system synchronization described in (4). "Quit" tells OASIS that you're done using the user interface. If you neglect to do this, the user interface will time out in either 2 minutes (UserIF) or 4 minutes (Radio). Data Logging and Retrieval -------------------------- The intended mode of data collection for OASIS is that a single entity - the data collection task on hp850 - collects the data and keeps the master copy in a single place on hp850. If multiple parties start collecting data and keep it in different places, everyone will lose data. However, due to time constraints and channel congestion, we'll need to collect data manually for a while. Hence this documentation. There are two user commands that retrieve data from OASIS, two modes of data transfer, and three data logging buffers. This section is inteded to clarify this situation. The two user commands are "getdata" and "getlog". "Getdata" is an undocumented command; that is, it doesn't appear in the help screen. This is intentional; it was supposed to be used only by the data gathering task on hp850. "Getdata" keeps track of what data has been sent, and sends only new data. It is convenient, in that the user doesn't need to understand logging buffers and record numbers. It is dangerous, however, because if multiple parties use it, each will only get partial data. Hence my warning in the first paragraph of this section. "Getdata" takes no parameters. "Getlog" takes three parameters: log number, starting record number, and number of records to send. For example: getlog 1, 0, 100 will send 100 records from log 1, starting at record number 0. There are three data logs. Log 0 is the short term log, the place we put data from sensors that don't do their own internal logging. Log 1 is the transmit log, where we put data that needs to be transmitted to shore, but which comes from instruments that do their own logging. Log 2 is the daily average log, where we store daily averages of instruments logging to log 0. Logs 0 logs ATLAS, PARs, GPS, and internal OASIS stuff (can temp, voltage, current, can pressure). Log 1 logs ADCP, Spectroradiometer, and CTD. Log 2 logs daily averages of all log 0 sensors except GPS. Log 0 has enough room at default data rates for 24 days of data. Log 1 has room for 34 hours of data. Log 2 has room for 2 years of daily averages. Each log will log data continuously, discarding as necessary the oldest data to make room for new data. To flush all log data and start logging anew, use the command "reset log ". When asked to send data, OASIS can send it in one of two forms: ASCII or uuencoded binary. ASCII form is directly readable, but takes twice as long to send. Uuencoded is a binary encoding form used extensively in the Unix community. "Getdata" always sends data in uuencoded form. "Getlog" can send either form, depending on the parameter named "ASCII". By default, "getlog" sends ASCII. To make it send uuencoded binary, enter the command "parm ascii 0 ". To change it back to ASCII, enter "parm ascii 1 ". Getting OASIS Data Via Packet Radio ----------------------------------- 1) Make sure that the GPS correction traffic from 160 Central (upstairs, in printer/microwave room) is turned off. 2) Set up a radio, TNC, and your favorite terminal emulation program. 3) Enter "c MBARI-4 v MBARI-2" to connect to the OASIS mooring (via Mt. Toro). OASIS only listens to the radio for 20 seconds each 10 minutes, so you may have to repeatedly try to connect. 4) When the TNC tells you "*** CONNECTED", wait for the OASIS signon & prompt: OASIS ver 1.2 OASIS> 5) IMPORTANT! Turn on file capture on your terminal emulator. Capture the output to a unique file name (e.g. DATA.nnn where nnn is a unique number). 6) Enter "getdata ". Depending on how long it's been since the last data dump (and hence how much data there is), receiving the data may take a few minutes to a half hour or longer. 7) When the data dump is finished, OASIS will re-prompt with "OASIS>". At that point, turn off file capture on your terminal emulator. 8) Enter "quit". OASIS will terminate the connection, and your TNC should display "*** DISCONNECTED". If you run into difficulties, it may be due to a poor radio reception or interference from competing radio traffic. If the TNC disconnects due to exceeding the retry count, you'll need to reconnect and retry later. In this case, it could happen that OASIS thinks it sent more data than you received (due to buffering in OASIS' TNC), and hence won't send all the remaining data when you issue a new "getdata". In that case, you may need to ask for specific record numbers via the "getlog" command. The command "logs" tells you what records exist in the various logs, but you'll need to either look at the data received to determine what's missing, or just ask for all logged data (may take a LONG time) by noting the record numbers reported by "logs" and asking for those. When using "getlog", remember to first enter "parm ascii 0" to put it into binary mode, or the transfer will take even longer. Other Useful OASIS Commands --------------------------- Here are some more commands you may need. The format used below to describe the commands is: "Command parameters", with required parameters in plain text and optional parameters in < > brackets. Command: TIME Function: Gets/Sets time Parameters: Hours, minutes, seconds, year, month, day Examples: "Time" displays the time "Time 12 22 00" sets the time to 12:22:00, leaves date alone. "Time 12 22 00 92 1 9" sets time and date to 12:22:00 on Jan 9, 1992 Command: CON instr-name Function: Connects you to the named instrument Parameters: Name of instrument, one of the following: ADCP, spectro, ATLAS, CTD, GPS, modem Examples: "con adcp" connects you to ADCP. Each instrument also has a function that occurs at time of connect. For example, connecting to ATLAS asserts the wakeup line, and connecting to modem sends a carriage return. Command: GPSINIT Function: Restarts and reinitializes GPS Parameters: Altitude in meters (if none provided, assumes 0) Example: "GPSINIT" does a complete initialization of the GPS board, and puts it into the "I'm lost" mode. This forces an almanac collection, which may take 15 minutes to an hour to complete. In perverse circumstances (e.g., satellites down due to maintenance), it may never complete. This command puts the receiver into 2D mode, in which altitude is fixed. You may supply the value for altitude in meters. Zero is the default. Command: LOGS Function: Displays a list of currently logged records Parameters: None Command: PARM parameter Function: Displays or sets a system parameter Parameters: Parameter name, new value Examples: "PARM tmout 6000" sets the timeout during CONnect to 60 seconds (value is in units of .01 secs). "PARM dischr 5" sets the character that disconnects to ctrl-E "PARM" shows a list of current system parameters. Command: QUIT Function: Disconnects from OASIS Parameters: None If you're connected via packet radio, quit disconnects the radio connection. If you're connected via the serial port, it turns off the user interface. In either case, if OASIS then has no more instruments to collect data from, it will power off. Command: RESET Function: Resets various parts of the OASIS system Parameters: One of "drvr" or "log" or "all". Examples: "RESET drvr" resets all drivers to their default states and parameters. "RESET log" resets logging memory to an initialized (blank) state. "RESET all" resets the entire OASIS system, including the above functions. THIS FUNCTION SHOULD BE USED WITH CAUTION. Command: SYNC Function: Synchronizes time of data collection Parameters: Instrument name, number of seconds until sync. Examples: "SYNC spectro 60" will start the spectroradiometer driver in 60 seconds, at which time it will restart the spectro by sending ctrl-C and "J". "SYNC" starts a global synchronization, in which OASIS first waits for valid ADCP data, and then issues a "SYNC" to all remaining drivers. Command: TNC Function: Sends a command to the TNC (terminal node controller for radio) Parameters: Command to send to TNC Example: "TNC paclen 128" sends the "paclen 128" command to the TNC, which changes maximum packet length to 128 bytes. Any command string is permissible. OASIS responds with the first 256 characters of the TNC response. Note - this command only works if connected to OASIS via radio. Command: TNCINIT Function: Reinitializes TNC, sets default TNC parameters Parameters: None Example: "TNCINIT" sends a "RESET" to the TNC, causing a full initialization and breaking the current connection! It then sends a number of commands setting TNC parameters to the OASIS default. If you send this command while connected via radio, your connection will be terminated. However, OASIS will then listen for a new connection for the radio timeout interval (4 minutes). The suggested use is to send "TNCINIT", followed by ctrl-C to your local TNC, then "disconnect" twice (the first one will try to send a disconnect message to OASIS, which isn't listening; the second one will force the issue), and then reconnect to OASIS (e.g., "c MBARI-4 v MBARI-2). Command: DRVPARM instr-name Function: Sets driver parameters Parameters: Name of instrument driver Example: "DRVPARM radio" allows you to set the radio driver parameters. Following is a sample session: Interval between samples (secs) (600) Tolerance on interval (secs) (60) Serial port (0) Serial setup (2370) Serial relay (16386) A/D port (0) Power ctrl (128) Sample type (0) Timeout (.01 secs) (24000) Extra parameter 0 (20) Extra parameter 1 (10) Extra parameter 2 (0) Time til next wakeup (secs) (512) Sample function 4708 Serial wakeup func 6A22 "Interval between samples" is the number of seconds between successive samples. "Tolerance on interval" is a parameter that is due to the sampling algorithm. In order to maintain synchronization and reduce power, OASIS will sample an instrument if it finds itself awake within plus or minus "tolerance" seconds of the next sample interval. For many instruments, we've allowed a tolerance of 60 seconds. For those instruments (ADCP, spectro) in which the data comes at a predetermined time, the tolerance is zero. "Serial port" specifies the serial port to use. Don't change this parameter! "Serial setup" tells OASIS how to set up the serial relays. Don't change this! "A/D port" tells OASIS which A/D port(s) to read. You normally don't want to change this, either. "Sample type" specifies the "type" field in the logging records, so the data can be decoded when it arrives on shore. Don't change this, either. "Timeout" specifies a time, in units of .01 seconds, that the driver should wait for data before it times out. In the case of instruments such as ADCP, this specifies time to wait for data. In the case of UserIF or Radio, it specifies the time to wait for user input before disconnecting. "Extra parameter (0,1,2)" is documented below. "Time til next wakeup" tells you how long (in seconds) it is until this driver is scheduled to run. You can force any driver to run by setting this value to something less than "tolerance on interval". Zero works too. "Sample function" and "Serial wakeup func" are pointers to software functions. They're here for information only; OASIS doesn't let you change them (here). Extra Parameters (PARM0, PARM1, PARM2) in OASIS ----------------------------------------------- ADCP PARM0: Timeout for bytes past 1st 2 (.01 seconds) PARM1: Number times to retry during "SYNC" Spectro PARM0: Timeout for bytes past 1st 3 (.01 seconds) PARM1: Number times to retry during "SYNC" ATLAS PARM0: Number times to retry CTD PARM0: Number of bytes to get PARM1: Number times to retry OASIS PARM0: Number of analog channels to get PARM1: Number samples to take & average PARM2: Time to wait between samples (.01 seconds) PAR PARM0: Number of analog channels to get PARM1: Number samples to take & average PARM2: Time to wait between samples (.01 seconds) GPS PARM0: Number of position fixes to take and average PARM1: Timeout for first fix (seconds) Modem Not Used UserIF Not Used Radio PARM0: Connection timeout (seconds it listens for connections) PARM1: Disconnection timeout (seconds it waits for disconnect message)