SNAPPER

simple snapshot/analysis/archive/playback macro for a single ICE card

<card>    Name of card alias in hardware config file
<flags>   List of flags to append to the card's config
<config>  Configuration table, if blank uses a global results SNAPSET

This macro is a GUI to deploy various resources on an ICE card, to snapshot or
continuously acquire to memory or disk, and then to play them back if the card
is configured to do so.  There are also a few simple analysis tools.

The recognized fields in the configuration table and their defaults are:

  port=MODULE1		Data source port name
  format=SB		Data source format
  rate=10		Samplerate in MHz
  clock=N		Clock source
  length=1.0		RAM buffer length in seconds
  dec=512		Tuner decimation
  freq=1		Tuner frequency in MHz
  gain=0		Tuner gain in dB
  nfft=1024		PSD FFT size
  psdr=10		PSD production rate in Hz
  psda=1		PSD averages before plotting
  frame=512		Frame size for time series plots
  afname="archive"	Archive filename 
  afqual=""		Archive filename qualifiers 
  wave=none		Output waveform

The XMidas version of this macro is graphical only and rather limited in functionality.

The remainder of this explain files covers the NeXtMidas version only.

Controls:

  gcontrol label  "FUNC"   "Acquire|Playback"
  gcontrol button "MODE"   ""         "Setup,RTMemory,Snapshot,Exit,RTArchive,Archive"
  gcontrol choice "REPLAY" "Replay"   "One,Cont,Stop,ReStart" "Stop"
  gcontrol choice "WAVE"   "Waveform" 
  gcontrol tval   "TIME"   "TC"     

  gcontrol label  "ARCH"   "Archive"
  gcontrol prompt "AFNAME" "File" 
  gcontrol tval   "ATCT"   "Top" 
  gcontrol tval   "ATCL"   "Len" 
  gcontrol lval   "AUXU"   "Disk" 

  gcontrol label  "CFG"    "Port Config"
  gcontrol prompt "CARD"   "Card  "  card
  gcontrol choice "PORT"   "Port  "  
  gcontrol choice "FORMAT" "Format"  
  gcontrol choice "RATE"   "Rate  "  
  gcontrol choice "LENGTH" "Length"  
  gcontrol choice "CLOCK"  "Clock "  
  gcontrol choice "DEC"    "Dec   "  
  gcontrol dval   "FREQ"   "Freq  "  
  gcontrol lval   "GAIN"   "Gain  "  

  gcontrol label  "DISP"   "Displays" 
  gcontrol choice "FRAME"  "Frame Size" 
  gcontrol choice "NFFT"   "Fft Size  " 
  gcontrol choice "PSDR"   "Disp Rate " 
  gcontrol choice "PSDA"   "Disp Avg  " 

  gcontrol label  "ANAL"   "Analysis" 
  gcontrol button "APLOT"  "Plots  " "TD-Line,TD-Raster,Histogram,FD-Line,FD-Raster,Stats"

  gcontrol label  "OPTS"   "Options" 
  gcontrol prompt "FLAGS"  "Flags String" 
  gcontrol choice "AOVER"  "Overlay" "Ask,Erase,OverWrite,Append,Leave,Abort" "Ask"
  gcontrol choice "ATAG"   "ArchTag" "None,Date,MJS" "None"
  gcontrol choice "HDR"    "Headers" "Attached,Detached" "Det"
  gcontrol choice "APKT"   "Packets" "On,Off" "Off"
  gcontrol lval   "STATS"  "Stats  " 
  gcontrol choice "COMP"   "Compression" "Off,Data,Plot" "Plot"

  gcontrol label  "SYS"    "System" 
  gcontrol choice "AUX0"   "Aux-0 " 
  gcontrol lval   "AUX0U"  "Used-0" 
  gcontrol lval   "FULL"   "FullAt" 
  gcontrol dval   "MAXFS"  "MaxFileSize" 2e9 1e6 8e12 1e6 /units="by"
  gcontrol lval   "CPU"    "Total CPU  " 0 0 100 1 /gauge
  gcontrol lval   "LOST"   "LostBuffers" 0 1 -1 1  /edit=f
  gcontrol lval   "CYCLE"  "CurrCycle" 0 1 -1 1  /edit=f /mon=reg.sp.cycle


These controls can be initialized using the /GC={MODE=xx,...} syntax.

A Midas log file is created by the name <card>_<port>.mlog.  This file can be filtered
for error messages, up/down times, performance metrics, etc.  It can be retrieved via
NFS, FTP, HTTP, MFTP, etc.

In archive mode, the macro creates a report in the form of a table of contents file 
named <archive>_toc.  This is a midas file containing a record for each file archived
to disk.  The file can be filtered by the user for files of interest which can then be
retrieved via NFS, FTP, HTTP or MFTP.  

The /RCVR=alias switch adds widgets for controlling a receiver.  If alias=ICE, the 
receiver is an ICE I/O Module.  Otherwise, the alias must exist in the Hardware Config 
file and have commands for frequency (F=MHz) and attenuation (ATN=dB).

The /SERVER=port switch runs the NeXtMidas macro in server mode.  
It then has a browser interface at http://localhost:<port> .

See the HELP on ICE NETWORK SERVER Protocol syntax.

See the HELP on HTTP for the HTTP or Hyper Text Transfer Protocol syntax.
See the HELP on RMIF for the MFTP or Midas File Transfer Protocol syntax.

Messages:

These are RMIF messages sent in UDP packets.  The results are returned to the calling host:port
in UDP packets with an RMIF header.  See help on RMIF for information on RMIF payload headers.

  GET - Get information from the macro - message is copied back in a RET message

	DOWNLOAD={NAME=localFileName,TIME=start,LENGTH=len}  - Causes client macro to download a piece of the archive file
	  This basically hits the download menu item with the dialog box filled in with these parameters.

	+ all other controls listed above

where n is a channel number, start is in J1950 seconds, and len is in seconds.

  SET   Set information in the macro - message is copied back in an ACK message

	VLAN=address	- sets the VLAN for the input port (do before JOIN)

	JOIN=address	- connect the UDP address to the input port

	LEAVE=address	- disconnect the UDP address from the input port

	INFO=TEXT - text line to be added to the report file (ex. Receiver freq change messages, latches, ...)

	+ all other controls listed above

  DOWNLOAD={NAME=localFileName,TIME=start,LENGTH=len}  - Causes client macro to download a piece of the archive file
        This basically hits the download menu item with the dialog box filled in with these parameters.

Switches:

  /ATL=n    Archive transfer length (in samples) tuned to maximize disk performance
	      (usually 1-2Mby, but less than 1/4 of the RAM buffer length)
  /AAUX=n   Archive auxiliary for single channel archives
  /AAUX1=n  Archive auxiliary for channel 1 in dual channel archives
  /AAUX2=n  Archive auxiliary for channel 2 in dual channel archives

X-Midas Switches:

  /NOX      No plotters
  /SPEED    Add speedometer primitive
  /PS=sz    Pipe size in bytes
  /NM       Runs the NeXtMidas version of snapper from XMidas
  /PKT      Produce additional archive files <archname>.pkt of packet headers
            corresponding to archive buffers with timecode, channel #, etc.

NeXtMidas Switches:

  /PLAY     Use this macro for output or playback mode
  /DUAL     Runs both ports 1|2 to separate files with Master/Slave relationship
  /NORESET  Bypass reset of card so multiple instances can be run at once
  /AUTOEXIT Exit when the SETUP mode is reached
  /AUTOCONF Automatically configure settings to match selected Archive file

  /CLIENT   Run this macro as a client
  /SERVER=p Run this macro as a server on port p
  /REMOTE=h:p The server host and port to feed this client
  /HEADLESS Run this server without graphics

  /RAUX=n   List of auxiliaries for graphical selection of Archive playback files
  /ARCHSF=n Causes each N ICE ram buffers to be archived to separate files.
            Files may be APPENDed to each other to reconstruct larger blocks of data.
            Each filename gets a one-up suffix of the form "_###".
  /AUTOARCHIVE Archive immediately after a ONESHOT
  /AUTOKEY  Add final snapper parameters to archive file keywords

  /TSP      Use Time Series Plots only instead of mixed time/frequency
  /FDP      Use Frequency Domain Plots only instead of mixed time/frequency
  /RPO      Raster Plots Only 
  /NBP      Add Narrowband plot with click tune capability
  /WBP      Add Wideband plot with click tune capability
  /LTYPE=x  Line type for time series plots def=line (see PLOT command)
  /FIXSCALE=x Use fixed scale range of +-x for Time Domain Plots 
  /FIXRANGE=x Use fixed scale range of x dB from max for Freq Domain Plots 
  /FIXMAX=x Use fixed scale max of x dB for Freq Domain Plots 
  /NEWPSD   Use new order for PSDA and PSDR where display averaging is done before the display rate calculation

  /ADLM     Adds A2D Load Monitor widget to monitor signal level
  /CHECKTC  Dumps timecode once per second to dumptcstat and dumptcdata for debug
  /CLICKTUNE Enables tuning of channels by mouse clicks on the wideband frequecy spectra
  /DCSBN    Allow tuning of DC Suppression averaging length (len=2**Bn)
  /EMT=n    Adds Envelope Measure and Track widget to monitor signal level
  /FREQADJ  Adjust marker freq for upfront offset in Hz
  /FREQMOD=n  Modify RFFREQ settings to those exact values possible on an A2DM18 where n=RFDEC.
  /GPS=iom  Specifies IO Module number with GPS module to query for GPS state vector
  /MARKER   Add frequency marker widget to display actual freq of mouse marker
  /MCFL=n   LogFile Max Circular File Length in entries [def=1M]. Zero for unlimited.
  /MODES=list Override the function menu list
  /NETMON=a Add network monitoring of TD plot pipe via an ICE packet stream at the given address=a
  /NIC=addr Use NIC card instead of PIC card to monitor SDDS data
  /OVERLAY=mode Switch form of Archive Overlay mode for inheriting from parent macro
  /OVSR=n   Set oversampling ratio for tuners
  /PBFONLY  PlayBack from File Only.  Even if RTMEMORY is selected will use RTPLAYBACK.
  /PMFFT    Use FFT on processor module to replace PSD decimate on host with PSD maximum
  /RF       Add widgets to control an RF section (LB2D,D2RF,A2DM18,D2AWG)
  /RCVR=alias Add widgets to control a front end receiver frequency and gain
  /SDDS     Add control widgets for SDDS VLAN and Address
  /SDDSMULTI=n Setup archiver for Multi-channel SDDS mode to separate files.
  /TB=N     TunerBank with N channels from 4 to 4K
  /TBM=mode TunerBank mode (FTTM-FastTunerTransform,MULTI-Sourcepic/Multi,MSP-MultipleSourcepic,MCS-MultiCoreStream) 
  /TIVO=len Operates archive in circular mode with disk buffer of <len> seconds.
  /WRAP     ReStart play back at beginning of file when end is reached
  /MTGOOFF  Add control widget to enable setting MTGOOFF flag value from a graphical control

  /GC={}    Table of default parameters for any of the controls.
            This has the form {MODE=RTARCHIVE,HDR=ATTACH,...}