CRaTER -- rtlm

NAME

rtlm -- Receives CCSDS telemetry packets on UDP port and prints contents on STDOUT.

USAGE

    rtlm [-a] [-c] [-d] [-f basename] [-F file_ID] [g size] [-h]
         [-l] [-p port_address] [-r filename] [-s] [-t] [-u] [-v] [-x]

FLAGS

     -a   prints out data in CRaTER "key<TAB>value" ASCII format
     -c   prints out mask data as sets of detector coincidences
     -d   prints out details of CCSDS header; ignores all else
     -F   sets file_ID in LRO standard LO archive header; default is 199
     -f   writes LRO-standard LO archive to given basename --
            sequence number and suffix $BINARY is added to form filename
          NB this function squelches all printing to STDOUT
     -g   sets maximum number of MB in single archive file; default is 10MB
     -h   prints this help message
     -l   prints out a single page of data and exits
     -p   set port address; default $UDPADDR
     -r   reads LRO-standard L0 archived data from given filename
          NB \"-r -\" causes read from STDIN
     -s   processes every spacecraft housekeeping packet;
          default is to process only one out of 16
     -t   prints out time as time-of-day string (ASCII format only)
     -u   prints out time as time-of-day string relative to UTC
     -v   verbose display
     -x   prints out full packet in raw, hex format

MNEMONICS

Header mnemonics

    SeqCount         Packet sequence count
    SerialNumber     Instrument serial number
    TestMode         Instrument in Test Mode
    OneHertz         Observatory 1 Hz clock
    Time             Observatory time in seconds
    EventAmp         Primary science mnemonic

Secondary science mnemonics

    BiasCntrl        Detector bias delayed command
    BiasCmd          Detector bias initial command
    CalLow           Low range detector calibration command
    CalHigh          High range detector calibration command
    ProcD1           Process detector D1
    ProcD2           Process detector D2
    ProcD3           Process detector D3
    ProcD4           Process detector D4
    ProcD5           Process detector D5
    ProcD6           Process detector D6
    LastCmd          Application ID of last command sent
    LastValue        Value of last command sent
    DiscThin         Current Low Level Discriminator command for D1,D3,D5
    DiscThick        Current Low Level Discriminator command for D2,D4,D6
    Mask             Most significant 16 bits of discriminator mask
    Mask2            next 16 bits of discriminator mask
    Mask3            next 16 bits of discriminator mask
    Mask4            Least significant 16 bits of discriminator mask
    Single1          Detector D1 singles rate
    Single2          Detector D2 singles rate
    Single3          Detector D3 singles rate
    Single4          Detector D4 singles rate
    Single5          Detector D5 singles rate
    Single6          Detector D6 singles rate
    Good             Good event rate
    Reject           Rejected event rate
    Total            Total detected event rate

Housekeeping Mnemonics

    V28bus           28VDC input bus voltage
    V5digital        5VDC regulated digital voltage
    V5plus           5VDC regulated analog voltage
    V5neg            -5VDC regulated analog voltage
    I28bus           28VDC input bus current
    BiasCurrentD1    Detector D1 bias current
    BiasCurrentD2    Detector D2 bias current
    BiasCurrentD3    Detector D3 bias current
    BiasCurrentD4    Detector D4 bias current
    BiasCurrentD5    Detector D5 bias current
    BiasCurrentD6    Detector D6 bias current
    BiasVoltThin     Bias Voltage for Detectors D1,D3,D5
    BiasVoltThick    Bias Voltage for Detectors D2,D4,D6
    CalAmp           Detector calibration voltage amplitude
    LLDThin          Low Level Discrimator voltage for D1,D3,D5
    LLDThick         Low Level Discrimator voltage for D2,D4,D6
    Ttelescope       Temperature of telescope assembly
    Tanalog          Temperature of analog board
    Tdigital         Temperature of digital board
    Tpower           Temperature of regulated power supply
    Tref             Temperature of internal bulkhead
    RadHighSens      High Sensitivity radiation counter
    RadMedSens       Medium Sensitivity radiation counter
    RadLowSens       Low Sensitivity radiation counter
    Tprt             Temperature of bulkhead PRT
    Purge            Purge gas flow rate

DESCRIPTION

At it's simplest rtlm reads in CCSDS command or telemetry packets on a specified UDP port and translates that binary information into human-readable form. In its default mode, the contents of each received packet -- minus the initial 48-bit primary header -- is displayed in raw hex. The -d flag allows the user to view the primary header by itself. For ultimate debugging the -x flag is provided to print out the full, unannotated hex dump, one packet per line.

With the -a flag the packet contents are displayed as {mnemonic-key value} pairs. The values are generally given as decimal quantities. One may translate the spacecraft time into wall time by use of the -t flag (or into UTC time by use of the -u flag). The coincidence mask data may be translated by use of the -c flag.

UDP input to rtlm may taken from a particular socket specified with the -p flag. Alternatively the -r flag may be used to read an LRO-standard telemetry file. (NB: The syntax ``-r -'' may be used to read from STDIN.)

Output from rtlm will go to STDOUT unless the -f flag is used in conjunction with a basename to form a series of files formatted in the standard LRO manner -- e.g.: with a 64-byte header. The first file written has the name ``basename.bin'' and the file is typically closed when its size exceeds 10MB. A second file is then opened with the name ``basename-1.bin'' (hopefully without any loss of data) and the process continues. The maximum file size may be chosen explicitly though the use of the -g flag. The LRO-standard header requires an numeric file ID which can be set by use of the -F flag. The spacecraft uses an ID = 200 for ``*.sci'' files (containing AppId 120) and ID = 201 for ``*.hk'' files (containing AppIds 121 and 122). In the typical lab use we put all of our data into a single file, so rtlm defaults to using an ID = 202.

ERROR PROCESSING

When reading from a UDP port, each UDP packet is assumed to contain one and only one CCSDS packet; only the first of multiple packets within a UDP packet will be processed. Packets are discarded if the length field is inconsistent with the received data length.

When reading from a file, each CCSDS packet is checked using the length field to verify that the EOF mark has not been reached prematurely.

Packet lengths are also checked for consistency with the AppIds. Warning messages for these and other internal inconsistencies are only reported if the -v flag is used.

BUGS

The program really tries to do too many things.

The time zone displayed is correct for the current date and location; when replaying data, however, daylight savings time shifting is not compensated to give the right answer for the historical date.

SEE ALSO

High Level programs

CArchive, CCmd, CData, CHouse, CLog, CNooise, CQuery, CStatistics

Low Level programs

bcmd, calcurve, tincan, statistics, verify, command.tcl, house.tcl

AUTHOR

Bob Goeke

RCS Information

$Id: rtlm,v 3.33 2009/04/22 13:32:15 goeke Exp goeke $