AVHRR Acquisition System
User's Guide

Dave Lloyd
Computer Services Branch
Software Engineering Department

Aug 20, 2002



Document History

Number Date and Sections            Notes                                                                                        
1 Aug 20, 2002 Document Created
2 Apr 24, 2003 Corrected some errors, added frame sync procedures
3    
4    
5    
6    


Contents

Introduction

The AVHRR Acquisition System is comprised of several components: antenna, Antenna Control Unit (ACU), receiver, bit synchronizer, frame synchronizer and Linux system. These components work together to download raw satellite data and put it in a form suitable for ingest by the AVHRR Production System.

Overview

The system is illustrated in Figure 1. The ACU is responsible for proper positioning of the antenna. The antenna gathers the RF energy transmitted by the satellite and transfers an IF to the receiver. The receiver demodulates the IF and sends the data to the bit synchronizer which converts the demodulated IF into a stream of ones and zeros. The frame synchronizer searches the bit stream for frame sync patterns and packages the data into frames. Each frame consists of portions of the AVHRR minor frame and video data. Each frame is passed along to the Linux system along with time stamp frames and quality frames. The Linux system is the main controller and its duties include: insuring the ACU is tracking; the receiver is tuned to the proper frequency; the frame synchronizer is properly configured and setup to send any data it receives; and to format the data and pass it along to the production system.


Figure 1 -- AVHRR Acquisition System

Purpose

The purpose of this document is to outline the operating procedures for the Linux Acquisition System. Procedures for the other components are documented elsewhere.

Linux Acquisition System

Overview

The Linux Acquisition System (edclxs1) is an Intel based server running a Red Hat Linux OS. Edclxs1 is connected to the ACU and receiver via serial cables and the frame synchronizer via a local ethernet. The connection to the production system is via the EDC LAN/WAN.

The purpose of edclxs1 is to insure that each scheduled acquisition is acquired. Its main interfaces insure the antenna is tracking the correct satellite, the receiver is tuned to the proper frequency and the frame synchronizer is properly configured. Scheduled scenes are determined through the master schedule which is maintained by processes on the production system. The process responsible for keeping everything running properly is the ACQUsition MANager (ACQUMAN).

ACQUMAN controls the ACU tracking and the receiver frequency. It also starts an acquisition process, ACQUIRE, that establishes communication with the frame synchronizer and a time correction process, TIMECORR, that extracts time deltas from the data stream. ACQUMAN also communicates with a moving window display that provides a visual indication that the system is working properly. Data is transferred to the production system by PUSH ACQUisition.

Minimum System Operations

The following must be true for the system to operate properly:

To maintain these minimums ACQUMAN is set to run in the background with nohup in the system init scripts, also the Adapsmonitor (running on the production system) checks its status. The PUSHACQU script is run from cron at 10 minute intervals. Each time the master schedule on the production system is updated a copy is made on edclxs1.

Other Required System Processes

Although scenes will be acquired and transferred to the production system as long as the minimum requirements are met, there are other processes that are required for the system to function. ACQUIRE, TIMECORR, and UPDATE_SCHEDULE are utilized and must be available.

Miscellaneous System Processes

There are several miscellaneous processes that help maintain the acquisition system. Chief among these is SHOw ACQUisition (SHOACQU) a moving window display that gives a visual indication of an in progress acquisition and, the rest of the time, the next acquisition start time. Other processes maintain the log file directories, display warning for important errors or disk utilization problems; and allow operations to easily start, restart or stop the system.

Process Descriptions

Each of the acquisition system processes implemented are described below.

  1. acquman

    The ACQUisition MANager controls the acquisition system. It's duties are as follows:

    1. start acquire to begin an acquisition and tell it the output file it is to save to
    2. keep shoacqu updated as to the next acquisition start time, tell it when to begin displaying a scene and what file to use as input
    3. start the timecorr process and give it the input file name to use
    4. create a schedule update file for each acquisition
    5. tell the receiver what channel to tune to
    6. put the ACU into program auto a few minutes before an acquisition and back in remote after the acquisition

    Acquman is normally run from an init script and must be running continuously. It is designed to run even though users are not logged in. Acquman touches its log at 5 minute intervals and may be monitored using the adapsmonitor. The /sbin/stat wrapper allows the adapsmonitor to check the status of acquman's log file. Acquman is a C executable that is run from either init script or start_acquman.csh.

  2. shoacqu

    SHOw ACQUisition is a moving window display. Its main purpose is to give computer operations personnel a visual indication that the system is performing properly. During an acquisition it displays a subsampled image of the scene being acquired. In between acquisitions it displays either a blank screen, or the last acquisitions sub-sampled image, and the next acquisition time. Shoacqu will not run unless acquman is running. Shoacqu is an X application written in C and is run from start_shoacqu.csh.

  3. acquire

    The acquire process establishes communication with the AVHRR frame synchronizer and saves all data it receives to the file indicated by acquman. Three files are created: the scene data file with an sf2 extension, the time stamp file, extension tstamp, and miscellaneous file, extension misc. The files are created in the ADAPSACQ directory. Acquire is a C executable normally started by acquman. Acquire is a stand alone process and may be independently executed.

  4. timecorr

    The time correction process uses the .tstamp file, created by acquire, to determine a mean time correction value for the scene. The correction is saved in ADAPSTABLES/noaaXX.timcor files where XX is the satellite number. Timecorr also moves the scene and associated files to the ADAPSING directory. Timecorr is a C executable normally started by acquman. Timecorr is a stand alone process and may be independently executed.

  5. pushacqu.csh

    PUSH ACQUisition copies newly acquired scenes from the ADAPSING directory to the production system along with the scedule update file and time correction file. The scene and associated files are then moved to ADAPSARC directories as temporary backups. Pushacqu.csh is a shell script that runs from opsavhrr cron at 10 minute intervals.

  6. cleanup.csh

    Cleanup.csh removes older files from ADAPSARC -- currectly set to files older than 7 days -- and tidies up the log direcories under ADAPSLOG. Cleanup.csh is a shell script that runs from opsavhrr cron just prior to midnight once a day.

  7. start_acquman.csh

    Start_acquman.csh stops the current acquman, if one is running, and starts another instance of acquman followed by shoacqu. Start_acquman.csh may be invoked with no arguments. With no arguments, a stop file is created in ADAPSTABLES so that acquman will terminate normally (This may take up to 5 minutes). It may also be invoked with a parameter 'now' which will immediately kill the acquman process. A side effect of acquman stopping is that shoacqu will also stop. Start_acquman.csh calls start_shoacqu.csh to start shoacqu. Start_acquman.csh is a shell script that is only run when needed for example: to execute a new release of acquman or when acquman is hung.

  8. start_shoacqu.csh

    Start_shoacqu.csh starts a new instance of shoacqu. If an instance of shoacqu already exists it will be terminated first. Start_shoacqu.csh is a shell script that is normally run from opsavhrr login. It is also called from start_acquman.csh.

  9. stop_acquman.csh

    Stop_acquman.csh terminates acquman. As a side effect, since shoacqu must have communication with acquman, shoacqu will terminate as well. If invoked without parameters, a stop file is placed in ADAPSTABLES and acquman will terminate normally (this may take up to 5 minutes). If invoked with the parameter 'now', acquman will be killed immediately. Stop_acquman.csh is a shell script that is run as needed.

  10. update_schedule

    Update_schedule copies a new master schedule over the ADAPSTABLES/master.sch file. File locks are used to prevent updating the file while acquman is reading the file and to prevent acquman from accessing the file while it is being updated. Update_schedule is a C executable that is normally run using secure shell from the production system either by xsched or updatesch. Update_schedule is a stand alone process that may be run as needed.

  11. check_space.csh

    Check_space.csh monitors the disk usage of /avhrr. It's real purpose is to prevent 100% disk usage which will hang the entire acquisition system. If the usage gets to 95% a window is popped up on the monitor with an advisory. The advisory will persist until disk usage drops below 95% or usage increases, in which case a new advisory is issued. If usage gets to 99% the ADAPSARC/sfl directory will be purged of files older than X days, currently X is set at 3. Check_space.csh is a shell script run from opsavhrr cron at 5 minute intervals. The TCL/TK script space.tcl is used to create the advisory window. The file space.txt is used as an interface between the two scripts.

  12. check_conflict.csh

    Check_conflict.csh calls check_conflict, a C executable. Check_conflict uses the conflict report (previously generated by existing ADAPS procedure schedcnflt) and the current time to determine if a conflicting pass is imminent. A conflict is imminent when the current time is within 7 minutes of the scheduled scene start time. If the conflict is imminent, a message is written to conflict.txt and check_conflict returns. The number of minutes to the scene start time is returned. Based on the return value check_conflict.csh will call conflict.tcl to pop up an advisory window on the X-display. Window background colors proceed from green to yellow to red as the scene start time aproaches. Conflict.tcl is a TCL/TK script. Check_conflict.csh is a shell script run from opsavhrr cron at 10 minute intervals.

  13. stat

    Stat is a wrapper that calls /usr/bin/stat and extracts the access time of the file. A symbolic link to the wrapper exists in /sbin directory. This wrapper is used to make the output of /usr/bin/stat compatible with that on other systems that extract the access time using a command line switch not available on the Linux system. Stat is used by the adapsmonitor to determine the last time log files have been accessed.

  14. fs_setup

    Fs_setup is a C executable that checks and displays the status of the 255W frame synchronizer. If the configuration is not ready for reception the attempt is made to correct the setting. The frame synchronizer must be set in remote for this program to actually make corrections to the configuration.

  15. check_acq.csh

    Check_acq.csh is a simple script that looks at the output of a 'ps' command to determine if acquman is running. It also reports whether shoacqu and acquire are running.

  16. Normal Operating Procedures

    No intervention should be necessary for normal operations. Acquman is started from the init scripts and opsavhrr cron jobs will be run automatically. Shoacqu is started from opsavhrr login. And, finally, the adapsmonitor is set by default to check for all required processes and the desireable processes on edcsgs20.

    The following processes are critical and must be in operation:

    • Acquman on edclxs1 in background with nohup specified
    • Pushacqua.csh in edclxs1 opsavhrr crontab at 10 minute intervals
    • Updatesch on edcsgs20

    The following processes are desirable and should be running:

    • Shoacqu on edclxs1
    • Cleanup.csh in edclxs1 opsavhrr crontab once a day prior to midnight, suggested time is 11:53 pm.
    • Check_space.csh in edclxs1 opsavhrr crontab at 10 minute intervals
    • Check_error.csh in edclxs1 opsavhrr crontab at 5 minute intervals
    • Check_conflict.csh in edclxs1 opsavhrr crontab at 5 minute intervals
    • Adapsmonitor on edcsgs20 with edclxs1 enabled
    • Adapsmonitor on edcsgs20 with edclxs1 acquman enabled

    To even out the system load, the crontab entries should not be set so that they are not all using the same minute to execute. For example, choose 1, 6, 11, etc. for one five minute entry 2, 7, 12, etc for the next and 3, 13, 23, etc for a ten minute entry and so on.

    Error Procedures

    The following procedures outline what you should do in case problems occur. Each condition is followed by a suggested action to resolve the situation and may also include a brief description of possible cause. The indicated actions are on lines that appear as:
    /home/opsavhrr [102] user action
    
    The first portion of this line, up to the ], is the normal linux prompt for user opsavhrr when logged in to edclxs1 in the opsavhrr home directory. The user action to be typed on the command line follows the prompt.

    CAUTION: Restarting acquman during an active acquisition will cause a loss of acquired data if the acquire process is running.

    Run the script check_acq.csh to see which, if any, of the three processes: acquman, shoacqu or acquire are running. Eg:

    /home/opsavhrr [102] check_acq.csh
    
    The output will look like:

    PID 11568 acquman is okay
    PID 19588 shoacqu is okay
    acquire is not running
    
    This shows the process ID's of the processes running and/or a message that the process is not running. However this only indicates that the process is listed in the /proc directory and does not mean the process is active since the process could be hung for any number of reasons. Acquman and shoacqu write log messages every five minutes. If the log files, located in ADAPSLOG, are being updated you can be assured that the processes are active. Another way to check acquire is to see if its output file, located in ADAPSACQ extension .sf2, is growing if so it is active. acquire is running

    1. Acquman is not running.

      If acquman is not running run the script start_acquman.csh. Acquman will start in the background and shoacqu should start and display the next acquisition time. The display of the next acquisition time indicates that acquman is running properly. Eg:

      /home/opsavhrr [102] start_acquman.csh
      

    2. Acquman is not writing to its log or not communicating with shoacqu.

      Execute the script start_acquman.csh with now argument. Shoacqu should start and display the next acquisition time. This indicates that acquman is running properly. Eg:

      /home/opsavhrr [102] start_acquman.csh now
      

    3. Shoacqu is not running

      If acquman is running execute start_shoacqu.csh. Shoacqu should start and the next sceduled acquisition time should be updated within fifteen minutes. Eg:

      /home/opsavhrr [102] start_shoacqu.csh
      

    4. Shoacqu window dissapears after a restart using start_shoacqu.csh

      This situation indicates that a connection could not be made with acquman. If acquman has initiated the acquire process a connection may not occur until the conclusion of the acquisition.

      1. Confirm that acquman is running and, if it is, try to reestablish communication by executing shoacqu again using error procedure 3.
      2. If after the second attemp still no connection is made and an acquisition is in progress, delay restarting shoacqu until the acquisition has terminated.
      3. If acquman appears to be running and there is no acquisition in progress, force a restart of acquman using error procedure 2.

    5. Shoacqu display does not display next acquisition time within 5 minutes of start up or displays wrong time.

      Check ADAPSLOG/shoacqu.log for errors in communication with acquman. The log should indicate a poll message from acquman every five minutes. If no poll messages are being received, restart acquman. Check ADAPSLOG/acquman.log for errors in reading the master schedule. If there are errors the master schedule is either corrupt or not being updated by updatesch. Copy the master schedule from edcsgs20 and insure the file permissions are set for read/write by owner, group and world. Eg:
      /home/opsavhrr [102] cd $ADAPSTABLES
      /avhrr/software/env/adaps/tables [103] scp edcsgs20:'$ADAPSTABLES/master.sch' .
      /avhrr/software/env/adaps/tables [104] chmod 666 master.sch
      
    6. Shoacqu displays "Acquiring" but the display is not being updated.

      Several things could cause this: acquire is not running, the /avhrr disk is full, the frame synchronizer is not configured properly. The script check_acq.csh will check and report on these problems.
      /home/opsavhrr [102] check_acq.csh
      
      If acquire is not running it may be started by issuing the command line printed as the last line of output of check_acq.csh. Eg:
      /home/opsavhrr [102] acquire -port 1024 -file $ADAPSACQ/ah16081902175304.sf2
      
      The shoacqu display should start updating. If the output of check_acq.csh lists a file name of $ADAPSACQ/temp.sf2, shoacqu will not update. If this happens an ls of the ADAPSACQ directory should show three temp files that increase in size.

      If acquire is running and disk space is 100%, remove a few of the oldest image files in $ADAPSARC/sfl. The image files have the sf2 extension. Eg:

      /home/opsavhrr [101] cd $ADAPSARC/sfl
      /home/opsavhrr [102] ls -lt
      ... the listing
      -rw-r--r--    1 opsavhrr ops      95109632 Aug 11 10:39 ah17081102152723.sf2
      -rw-r--r--    1 opsavhrr ops      115474432 Aug 11 09:29 ah15081102141527.sf2
      -rw-r--r--    1 opsavhrr ops      95021568 Aug 11 07:48 ah15081102123552.sf2
      -rw-r--r--    1 opsavhrr ops      110851072 Aug 11 04:45 ah16081102093133.sf2
      /home/opsavhrr [103] rm ah16081102093133.sf2 ah15081102123552.sf2 ah15081102141527.sf2
      
      If the display doesn't update acquman may need to be restarted.

      Check that the frame synchronizer is set up for reception by running fs_setup. Fs_setup will attempt to correct any configuration problems and display results. If fs_setup reports that the system is not set for remote, it will have to be put in remote manually. If the frame synchronizer is properly configured if fs_setup reports:

      
      *** System set for remote. ***
      
      Format type, FTP: HRPT
      Data type,   DTP: KLM
      Clock rate,  CRT: Normal 1X
      Input code,  COD: NRZ-L
      Data direct, DIR: Forward
      Input port,  INP: port 1
      Clk polarity,CPL: Normal
      Time stamping enabled
      Video enabled
      
      *** Ready for reception. ***
      
      

      If the frame synchronizer is not in remote it will have to manually set to remote.

      1. Confirm that the display is on Page 0 - Status. If not press the Menu[-] key until Page 0 - Status is displayed.
      2. Press the 1 key to access Page 1 - General Setup.
      3. Press the Menu[+] key once to select Remote Ctrl.
      4. Press the Param[+] key once to change the parameter to remote.
      5. Press the Menu[-] key once to enable the change.