-----------------------------------------------------------------
DESCRIPTION
-----------------------------------------------------------------
remote33       Suite  of  programs to manage the  Ashtech 
               Reference Stations

Version:       0.4     Apr 24 2001

Author:        Magellan Coropration/Ashtech Precision Products 

Contact:       Sergei Podshivalov serg@ashtech.com

-----------------------------------------------------------------
QUICK INTRODUCTION
-----------------------------------------------------------------
Remote33 is the small collection of the utilities and 
PERL scripts that allow some basic operations with the Ashtech 
Reference Stations receivers.

The following functionalities are implemented in remote33:

1. Connecting to a remote or local receiver.
2. Program the data recording sessions and other parameters.
3. Download the recorded data from the receiver external memory.
4. Log the real time output from the receiver.
5. Convert the downloaded data to the RINEX format
6. Email the download report.

The  backbone of remote33 are the utilities:
rx/rz   - Download data from the receiver via XMODEM/ZMODEM
convert - Convert the R, U or L  Ashtech files to B,E,S files
teqc    - Convert B,E,S Ashtech formats to RINEX

All these utilities are glued togethet by remote33.pl PERL script.
This scrit can be customized to fit particular user needs.

-----------------------------------------------------------------
WHAT YOU HAVE (ARCHIVE CONTENTS)
-----------------------------------------------------------------
COPYING        GNU General Public License
README         This file
TODO           List of things to do.
sample.cfg     Sample configuration file
exec.pl        PERL script which does nothing but execute remote33.pl
log.pl         PERL script to log the real time data from the 
               receiver
remote33.pl    PERL script to dial to the receiver, download data,
               convert it to RINEX, send e-mail report.
z12dld.pl      PERL library with Z-12 specific  routines
uzdld.pl       PERL library with Micro Z specific routines
rawdld.pl      PERL library to mimic the external memory
               download while doing data logging
ash-lib.pl     PERL library with some routines common to Ashtech
               receivers
mdm-lib.pl     PERL library with some routines to talk to modem
em1000.pl      PERL script to establish TCP/IP connection to the 
               receiver via ethernet modem

convert/       Utility to convert R- or U- files to B,E and S files       
zmodem/        Public Domain versions of Omen rx/rz/sx/sz  utilities
teqc/          UNAVCO teqc utility

-----------------------------------------------------------------
COMPILING AND INSTALLING FILES
-----------------------------------------------------------------
To compile convert simply switch to the directory  convert/ 
and issue the command:

     make

To compile rx simply switch to the directory  zmodem/ 
and issue the command:
    gcc -o rx -DZ12_PATCH  rz.c

To compile rz simply switch to the directory  zmodem/ 
and issue the command:
    gcc -o rz rz.c

-----------------------------------------------------------------
ABOUT THE SERIAL PORT
-----------------------------------------------------------------
On  Linux  systems, serial ports are addressed via /dev/ttyS* de-
vices. Old /dev/cua* are obsolete and should not be used anymore.
Most  systems  make  a  symlink  /dev/modem pointing to the ttyS,
purists don't like it.  See Linux Serial HOWTO for some hints.

-----------------------------------------------------------------
Configuration File
-----------------------------------------------------------------
The script is 100% non interactive. It's driven by the configuration 
file described below.

Title             = [string] Title of the generated report

ScriptName        = [string] Name of script to be executed 
                             Always remote33.pl

ScriptDir         = [string] Directory where script is located

DataDir           = [string] Directory where downloaded and logged 
                             data will be stored

URLbase           = [string] The URL of the data directory, in order 
                             to be able to have the data accessible 
                             via HTTP of FTP

MailList          = [string] List of email addresses separated with spaces
                             where the report will be sent

DataSource        = [string] Specifies how the data is obtained from receiver:
	                     stream - log  raw data from the serial port 
                             download  - download data from the external memory

Connection        = [string] Specifies connection type
                             direct - direct connection via serial port
                             modem  - connection via dial up modem
                             tcp    - connection via TCP/IP

Port              = [string] In case of  direct connection, it is the PC port
                             conected to the reciver
                             In case of  modem connection, it is the  PC port
                             connected to the modem
                             In case of  TCP/IP connection, this parameter 
                             is ignored.

ReceiverRate       = [5-9]   Baud rate index of the receiver port connected 
	                     to the PC or to modem. Valid values are:
                             5 - 9600, 6 - 19200, 7 - 38400, 8 - 57600,
                             9 -115200

HostName           = [string] IP address or the host name of the Ethernet modem
                              connected to the receiver

PhoneNumber        = [string] Number to dial to  connect to the receiver 
			      modem, in case of  modem connection
                    
ConnectionRate     = [string] Baud rate of the PC port in case of modem 
	                      connection. It can be different from the 
                              baud rate on the receiver side
                    
PCModemInitString  = [string] Initialization string of the modem connected 
                                 to the PC

Configure          = [yes|no] Configure, or do not configure, the receiver
                              modem setting.
                              The receiver modem setting can also be configured
                              if the receiver is directly connected to one 
                              of the PC ports.

ConfigPort         = [string] For modem connection, it is the PC port
                              connected to the receiver. For direct connection,
                              it is not used. 

RcvrMdmPort        = [A|B|C|D] Receiver port connected to the modem

RcvrMdmInitString     = [string]  Initialization string of modem connected
                                  to the receiver

RcvrMdmDefaultConfStr = [string]  Modem command to set factory defaults

RcvrMdmEscapeStr      = [string]  Modem command to switch from data to command
                                  mode

RcvrMdmCmdToDataStr   = [string]  Modem command to switch from command to data
                                  mode 

RcvrModemName         = [string]  Modem name of modem connected to receiver.
 
(For  more details on the above modem parameters, consult the 
 receiver manual, command $PASHS,MDM ) 

SessDuration          = [number] Recording session duration. Upon expiration 
                                 of that time, the current file is closed and
                                 a new is opened. 
                                 This field applies for DataSource = stream. For 
                                 DataSource = download mode, only is applies only 
                                 when DoSessionProg is set to "yes".

SiteName              = XXXX     Four letter site name

MinSvNum              = [number] Minimum number of satelites required to
                                 record or log data 

ElevationMask         = [number] Elevation mask

RecInt         	      = [number] Recording/Logging interval

DoSessionProg         = [yes|no] Aplicable for download mode only. If "yes",
  		                 script performs the receiver session 
                                 programming. If "no", script simply closes 
                                 the current opened file, and then 
                                 downloads all closed file from the receiver.
                                 In that mode, the duration of the file depends
                                 on how often the  receiver is downloaded.
                                 
MultiPathMode         = [0|1|2]  Multipath mitigation mode
                                   0 - disabled
                                   1 - carrier
                                   2 - code 

GPSSyncMode           = [Y|N]   GPS Syncronisation mode   

-----------------------------------------------------------------
RUNNING remote33
-----------------------------------------------------------------
First the configuration file must be edited. See section 
"Configuration File" for guidelines.

The script can be run from the command line or by crontab. 
Crontab provides you with the option of running the script 
on some regular basis. If you want to download data only 
once, run the script from the command line. 

The format of crontab control file line should look like this:
0 0-23/8 * * * perl -I $S_DIR  $S_DIR/exec.pl  $S_DIR/sample.cfg 2>&1

This line tells crontab to run the script every eight hours. Note 
that the full path name to the script name and configuration file needs
to be specified. Also, the -I option needs to be specified to indicate 
where all included files are located.

a) Download data from receiver external memory
   If you want to download data from the external memory you specify
   only one parameter to the exec.pl script. That parameter is the 
   configuration file name :

   ./exec.pl sample.cfg	
   
b) Log data
   To log data, two scripts are required

   log.pl      - This script copies the data being output through the serial port
                 to the log file in some specific directory.
                 It creates the new file every time the duration of current file
                 is longer than the value specified in the SessDuration field in the
                 configuration file. 

   remote33.pl - reads the data from the log file and do the same data 
                 manipulation as for data downloaded from the external 
	         memory ( conversion to E,B, RINEX, running QC, mail report) 

   To run the log.pl, issue the command 	
   ./exec.pl sample.cfg log.pl &
   This command will start log.pl and run it in the background. Data will be logged
   until this task is killed.

   For remote33.pl, you have the same options as for download:
   To run it from the command line, type:
   ./exec.pl sample.cfg 
   If not, inlcude it in the crontab file.
   0 0-23/8 * * * perl -I $S_DIR  $S_DIR/exec.pl  $S_DIR/sample.cfg 2>&1

   NB: The configuration file must be the same for these two scripts. 

   Every time remote33.pl runs in the "stream mode", it will 
   check the directory created by log.pl for valid log file names 
   ( /^L.......\.\d\d\d$/ ) and convert them to B,E and RINEX.


-----------------------------------------------------------------
INTERNALS
-----------------------------------------------------------------

exec.pl
  The exec.pl is a common shell for remote33.pl and log.pl
  It creates the new sub directory in the data directory,
  makes it current. 
  Then it starts the specified script redirectcting its STDIN and 
  STDOUT to the specified port. Thus, the rest of the applications, talk 
  to STDIN and STDOUT. The STDERR is redirected to the logfile, which then
  will be attached to the email.
  Upon the completition of the script, exec.pl runs mail to send the 
  report and log files.

remote33.pl
  At the very beginning, depending on the connection type, remote33.pl 
  establishes the connection to the receiver. In stream mode, no 
  connection is made. Instead remote33.pl reads the ID file created by 
  log.pl. That ID file contains the name of the directory where the log 
  files are being recorded.

  In download mode, remote33.pl downloads the files (U or R) 
  from the receiver and stores them to the PC. 

  Then for every downloaded file, or for every file in the logging 
  directory that matches name criteria /^L.......\.\d\d\d$/ 
  remote33.pl executes convert. The convert converts these data to 
  the B,E,S,D files. Then, teqc is executed to convert B,E files
  to RINEX

  As soon as the RINEX files are ready, remote33.pl executes teqc in QC 
  mode to generate the report.

log.pl
 Depending on the connection type, first log.pl establishes  
 communication with the receiver. Then it sets the recording data 
 parameters and enables the PBN,MPC and SNV messages. Then it goes to 
 ininite loop and reads the data from the STDIN and writes it
 to the .temp.log file. At the same time, it checks the PBN message 
 time tag. As soon as the time tag reaches a value that matches the session
 duration criteria, log.pl closes .temp.log, renames it to LxxxxNnn.NNN
 and opens a new .tem.log

-----------------------------------------------------------------
GETTING NEW VERSIONS
-----------------------------------------------------------------
The latest version can be obtained from the Ashtech FTP site
ftp://ftp.ashtech.com/pub/software/remote33


-----------------------------------------------------------------
HISTORY
-----------------------------------------------------------------
Version:       0.1     Nov 9 1999 
     First public release.

Version:       0.2     Dec 10 1999
     Z-12 type 3 support has been added
     Logging of the streaming raw data was added
     TCP/IP support has been added
     Bug fixes
     Added new parameters to the configuration file

Version:       0.3     Jan 05 2000
     Y2K bug was fixed

Version:       0.4     Apr 24 2001
     D file bug (missing CR/LF) was fixed





















