UHFODP Decoder/Formatter Software Operator's Manual Operator and User Document For Software Version: 1.0 Issue Date: September 30, 2003 JPL Document No. D -26919 Jet Propulsion Laboratory California Institute of Technology Document Owner: Reviewed by: _____________________________ ___________________________ Sumita Nandi Software Development Engineer Software Operator's Manual UHFODP Decoder/Formatter Table of Contents 1. General Description 1.1 Purpose of Software 1.2 Functional Description 1.3 Operating Environment 2. Processing Components 2.1 Overview 2.2 Decoding Mars Global Surveyor UHF Doppler Data 2.3 Decoding Mars Odyssey UHF Doppler Data 2.3.1 Header decoder 2.3.2 Doppler block decoder 2.4 ASCII Doppler File 2.5 NTDF Formatter 2.5.1 Ancillary Information File Description 2.5.2 Using the NTDF Formatter 2.6 Operating Scripts 3. References 4. Appendices 3.1 HKTM Doppler File Retrieval 3.2 Mars Odyssey APID 35 Retrieval Section 1 General Description 1.1 Purpose of Software This manual describes the operation of the UHFODP software package. The purpose of the software package is to provide capability to unpack UHF Doppler telemetry from both the Mars Global Surveyor Balloon Relay instrument and the Mars Odyssey UHF Recorder and package them into a Navigation Tracking Data File (NTDF) to be used by the Section 312 Orbit Determination Program and/or applicable related programs. The software package was developed to support the Mars Exploration Rovers landed positioning, and this document describes their use in that specific context. 1.2 Functional Description The UHF radios on the two spacecraft MGS and Mars Odyssey both record the relative frequency of a received UHF signal compared to a fixed local oscillator. The data is then recorded in a specified format and is transmitted to Earth during scheduled tracking passes1,2. The UHFODP software is divided into a few components based on functionality. Use of individual routines is simplified via 2 scripts, one to support processing data collected from the MGS Balloon Relay, and one to support processing data collected from the Mars Odyssey UHF radio. Figure 1.4 shows the data flow through UHFODP for each of the two input data types. Initial processing of each data type is accomplished with a specialized routine, and then conversion to the NTDF is accomplished with a common routine through use of an intermediate ASCII file and an accompanying ancillary information file described later in sections 2.4 and 2.5, respectively. ------------ | MGS HKTM | -------------- |Doppler File|---->| HKTM decoder |------------ ------------ -------------- | | -------------- | | Mars Odyssey | --------- | | APID 35 |------->| APID 35 | | | Telemetry | | Decoder |--------- | -------------- --------- | | | | ----------- V V | Ancillary | -------- | Data |----->| NTDF | ----------- | Writer | -------- | | V NTDF File Figure 1.4 Block Diagram of UHFODP for its two input data types 1.3 Operating Environment This software consists of C and Fortran routines driven by Bourne shell scripts. The software was developed on an HP/UX-11 computer with effort made to follow standard C and Fortran in order to facilitate portability. The software, including scripts, has also been tested on a Sun4 workstations using the Solaris operating system. Section 2 Processing Components 2.1 Overview The C routines contained in the package are the two routines used to decode the MO and MGS Doppler telemetry, and a set of subroutines to write and read a free-format ASCII file containing a time series of frequencies and ancillary information required to identify the data set and conditions of the recording from which it derives. The NTDF writer is a Fortran routine relying on routines in the ODP Packers Library (a Fortran library). Finally, the run scripts are Bourne shell scripts used to simplify operation of the other programs and organize output file naming. 2.2 Decoding Mars Global Surveyor UHF Doppler Data The Mars Global Surveyor Balloon Relay is equipped with a UHF radio that records the one-way Doppler on the carrier signal from a Martian lander or rover whenever it receives UHF telemetry from such a vehicle. The receiver records both the time referred to its clock and the Doppler frequency of the signal compared to its local oscillator. The data is recorded as part of the "housekeeping telemetry" during the tracking pass. After transmission to Earth, the housekeeping data becomes available as HKTM files. Ref [1] describes the formats of the various data contained within these files, and specifically it shows the format for the Doppler data stored within the files. The routine UHFODP program "decode_MBR" identifies Doppler data records, unpacks the records and writes them to an ASCII file (described in section 2.4). The telemetry contains a Hamming code which is checked during unpacking, and records for which the checksum fails are not written. Checksum failures will be noted in output to the standard error device or file. The program can be executed at the UNIX command line by typing: decode_MBR [>] [] The program argument is the HKTM file and the ASCII file records are written to the standard output device which may be redirected to a desired file name. 2.3 Decoding Mars Odyssey UHF Doppler Data (APID 35) Mars Odyssey is equipped with a Cincinnati Electronics UHF transceiver and can be commanded to either record one-way Doppler data transmit and record two-way Doppler data. Both one-way and two-way data are recorded in the same format described in ref. [2]. The telemetry record does not indicate the recording mode and the analyst must determine the mode from some other means. The receiver records the time from the start of tracking and the Doppler frequency compared to its local oscillator. It should be noted that this receiver only records the absolute value of the difference between the received frequency and the local oscillator. UHFODP makes no attempt to resolve the sign ambiguity of the data. The data are packaged with header data identified with a telemetry ID of 35 and transmitted to Earth along with other telemetry. The files marked with telemetry ID 35 can be decoded into a time series of time and Doppler shift by the UHFODP routine "read_MO_dopplerblock". 2.3.1 Header Decoder The Doppler records are surrounded by an SFDU header record which contains some identifying information about the ensuing data including a nominal time stamp from the data handling computer. Normally, this timestamp would not be precise enough for radiometric data, however, no absolute time stamp is found in the Doppler data itself for this receiver. Therefore, the program "read_MO_dopplerblock" uses the first timestamp in a data file as a start time for the Doppler data contained within that file. Time stamps for ensuing data are calculated using the more precise relative time stamp information contained within the actual Doppler records. Header record time stamps for later records are checked for data continuity and to verify data type. 2.3.2 Doppler Block Decoder Once the header records have been identified and checked, "read_MO_dopplerblock" unpacks the binary APID 35 data to produce a time series of Doppler frequencies which are written to an ASCII output file. The program can be invoked by typing to the command line: read_MO_dopplerblock [>] [] The argument is the APID35 telemetry file and the ASCII file records are written to the standard output device which may be redirected to a desired file name. 2.4 ASCII Doppler File Due to the disparate binary formats of the Doppler telemetry from MGS and Mars Odyssey, the software package utilizes an ASCII intermediate file prior to producing an NTDF to unify this last step. Both "decode_MBR" and "read_MO_dopplerblock" produce the same format ASCII intermediate file. The ASCII intermediate file may also be used by an analyst to take a quick look at the data prior to producing an end product. The ASCII intermediate file can be produced manually or by an external program in order to make simulated data into an NTDF. The ASCII Doppler File produced within UHFODP is a free format ASCII file with a set of Doppler records listed one to a line with contents such as: 115324992.402 1 0 -2584.858251 The four fields on the line are time, frequency reference flag, data quality flag and frequency. The fields in the data records must be separated by one or more spaces or tabs. Any other information on a data line is ignored, so the space may be used for comments. No comments are permitted on a data line prior to the data fields. The time is a floating point number in seconds past J2000. The frequency reference flag indicates which local oscillator (LO) was used for the recording. The two LOs for the MGS Balloon Relay are indicated with 1 to mean 401527500 Hz and 0 to mean 405625000 Hz. The Mars Odyssey radio has a single receive LO indicated with a 1 to mean 401584625 Hz. The user can produced simulated data with any desired reference frequency by setting the frequency reference flag to 2. The third entry on the line is the data quality flag (0= use, 1=bad). Data may be flagged as "bad" due either to telemetry indicating a bad receiver condition or if telemetry integrity checks failed for the telemetry record Data labeled as bad will not be written to the NTDF in an ensuing invocation of "ascii_to_NTDF". The final field is the Doppler frequency compared to the receiver local oscillator in Hertz. 2.5 NTDF Formatter 2.5.1 Ancillary Information File Description Certain information useful for identifying a data set or required to process Doppler data for spacecraft or lander position are not contained within the UHF telemetry records from either MGS or Mars Odyssey. These data must be provided by the analyst from some external source in order to produce a correct ".NTDF" file. The information is provided to "ascii_to_NTDF" via an ASCII file described in this section. This file is in a "namelist" format, with inputs listed, in any order, between the fields "$input" and "$end" as shown in fig 2. All fields have default values as shown in table 1. |=====================================================================| | Table 1. | | Fields and defaults for ancillary input file to "ascii_to_NTDF" | |=====================================================================| |Field label| Description | Format |Default Value| |===========+===============================+===========+=============| |STIME |Start time of data in out file |dd-MMM-YYYY| long ago | | | | HH:MM:SS | | |-----------+-------------------------------+-----------+-------------| |ETIME |End time of data in out file |dd-MMM-YYYY| far future | | | | HH:MM:SS | | |-----------+-------------------------------+-----------+-------------| |fbias |Known receiver frequency bias |Real number| 0. | |(Hz) | | | |-----------+-------------------------------+-----------+-------------| |tbias |Known receiver timetag bias (s)|Real number| 0. | |-----------+-------------------------------+-----------+-------------| |val_rej |Exclude points with bad data | .true. or | .false. | | |flag | .false. | | |-----------+-------------------------------+-----------+-------------| |DSS |Spacecraft or station ID of | Integer | 0 | | |transmitter or transponder | | | |-----------+-------------------------------+-----------+-------------| |DSS_cent |Planet ID of integration center| Integer | 4 | | |associated with DSS | | | |-----------+-------------------------------+-----------+-------------| |SCID |Receiver spacecraft ID | Integer | 0 | |-----------+-------------------------------+-----------+-------------| |SCID_cent |Planet ID of integration center| Integer | 4 | | |of SCID | | | |-----------+-------------------------------+-----------+-------------| |SCID_U |Original transmitter ID for | Integer | 0 | | |2-way or 3-way data | | | |-----------+-------------------------------+-----------+-------------| |SCID_u_cent|Planet ID of integration center| Integer | 0 | | |of SCID_U | | | |-----------+-------------------------------+-----------+-------------| |fref |Local Oscillator frequency of |Real Number| 0. | | |receiver (Hz) | | | |-----------+-------------------------------+-----------+-------------| |dtype |261 = one-way Doppler | Integer | 262 | | |262 = two-way Doppler | | | |=====================================================================| $input STIME = '28-AUG-2003 00:00:00' ETIME = '28-AUG-2003 23:59:00' fbias = +0. tbias=0 val_rej = .true. DSS = 99 DSS_cent = 3 SCID = 94 SCID_cent = 4 fref = 401500000. dtype = 261 $END Figure 2. An example of an ancillary data file to be input to "ascii_to_NTDF". 2.5.2 Using the NTDF Formatter The NTDF formatter, "ascii_to_NTDF" is invoked at the UNIX command line via the sequence: setenv UHFFILE setenv NMLFILE setenv OBS ascii_to_NTDF.e The first two UNIX logical name definition specify the inputs to "ascii_to_NTDF", while the third specifies the output file name. Using the name of an existing file as an output file name results in a fatal error. The first input is an ASCII Doppler file of the format described in section 2.4. An output file name is an optional input. The program default is to produce and output file with the same name as the input file plus the extension ".NTDF". An existing file with the output file name will be overwritten if the file permission allows it to be. The ".NTDF" file is a NAVIO format file which can be dumped using a tool such as "NIODUMP" to view its contents. 2.6 Operating Scripts Two operating scripts are provided as part of UHFODP, one for each a receiving spacecraft. Both scripts set the logical names noted in section 2.5.2 given appropriate line mode inputs. The syntax for usage is as follows: MGS HKTM files: run_MGS_convert [] [] and for Odyssey APID 35 files: run_ODY_convert [] [] In both cases, the first argument is required and is the name of an existing raw telemetry file, an HKTM file or an APID 35 ".pkt" file. The second argument is an existing ancillary information file of the form described in Section 2.5.1. If this argument is not input at the command line, it defaults to the name of the input raw telemetry file with an extension of ".nml". If the desired ancillary information file has a different name, it should be explicitly entered on the command line. The third argument, the desired output file name, is an optional argument. If not explicitly included on the command line, its default value is the raw telemetry file name with an added extension of ".ntdf". The output file name must not be the name of an existing file. A fatal error occurs if an attemp is made to write output to an existing filename. Section 3 References [1] JPL D-14514 Mars 96 Data Processing of Mars Relay- Interface Manual [2] Cincinnati Electronics Corp. Doc #648855 UHF Transceiver Model C/TT-505 Theory of Operation/User's Manual, 9/30/99. Section 4 Appendices 3.1 HKTM Doppler File Retrieval HKTM data files are delivered to the MGS project by Malin Space Systems and placed on a computer known as a DOM server where it is available to users with proper privilege. The data on the DOM server can be accessed with a GUI, but for a few files, simply copying the files from the server is more straightforward. From a computer with GDS access, the files are kept in the directory "/domops/data/mgs/94/main/hktm_mr". The files are named "HKTMyyyydoynnn.001" or "HKTMyyyydoynnn.002", where "yyyy" is the year of the telemetry record, "doy" is the day of year associated with the telemetry, "nnn" is an additional file label in case there are several files from one day of year and ".001" refers to a file from a preliminary data retrieval, while ".002" refers to the final file version. In most cases, there is little difference between the ".001" and ".002" version of a file, and two file names that are identical save for this extension, represent the same data set. The user can simply copy (or move using a file transfer tool) one or more of these files to a file system and directory at which UHFODP will be used. These files are in the proper format to be converted by the tool. 3.2 Mars Odyssey APID 35 Retrieval 3.2.1 Using the GUI interface Mars Odyssey telemetry data is available via a TDS query from any ground data systems computer behind the DSMS firewall. This appendix describes how to use the "tot" tool in its graphical user interface mode. Step Action 1) Log in to Workstation with appropriate access 2) type UNIX command "unsetenv XUSERFILESEARCHPATH" 3) type UNIX command "setenv XAPPLRESDIR /local/tds/M01tot" 4) type UNIX command "tot"; this initiates the GUI 5) Make sure the "Query Server" box is filled with "M01_MASTER_QueryServer" 6) In the "DataType" portion of the screen using the "pkt" pull down menu, choose "orb_apid_20-51" and select "orb_apid_35" from the secondary pull down menu 7) In the "Outputs" portion of the screen, choose "Unix file" as the output type 8) Use the center mouse button to arrange the items in the originally empty center box to not overlap 9) Use the left mouse button to connect the "orb_apid_36" box to the output file box 10) With the right mouse button on the "UNIX file" box, you may access a pull down menu that allows renaming the output file from its default value. 11) Check mark "NERT" and uncheck "RT"; this indicates that it is not a real time query, just a look at already archived data. 12) Check only "Orb" in the box beside "RT" and "NERT" 13) Fill in begin and end times in the format yyyy-doyThh:mm:ss 14) Use the pull down menus for "Query" and "Order" to select "SCET" for both (and make sure the query times in 13 are SCET times). 15) Push the "Submit Query" button and wait for confirmation of some packets. 16) This should result in a UNIX file of the format to be input into the Mars Odyssey portion of UHFODP. 3.2.2 Using the Line Mode Interface Mars Odyssey telemetry data is available via a TDS query from any ground data systems computer behind the DSMS firewall. This appendix describes how to use the "stot" tool from the UNIX line mode. Using the "stot" tool requires an input file describing which data to obtain from the database. This file is normally labeled with the extension ".pvl". Figure A-3.2.2 shows an example of the ".pvl" file. OBJECT = CANISTER_QUERY; DESCRIPTION = 'CANISTER_DATA_2003153'; REQUESTER_NAME = nandi; MISSION_NAME = Mars_Surveyor_01; SPACECRAFT_NAME = Or1; DATA_FROM = { NERT } ; TIME_RANGE = { 2003/153-20:00:00.00 .. 2003/153-21:00:00.000} SCET; TIME_ORDER = SCET; GROUP = FRAME ; DATA_TYPE = "orb_apid_35"; DSS_ID = ALL ; TELEMETRY_MODE = MERGED ; END_GROUP = FRAME ; END_OBJECT = CANISTER_QUERY; Figure A-3.2.2 An example of a ".pvl" file To obtain UHF Doppler records, the "DATA_TYPE" field must be "orb_apid_35" as shown. Typically the user will simply change the time range of the query in the ".pvl" file prior to submitting the query. The time format is "YYYY/DOY- HH:MM:SS" where "YYYY" is the four digit year, "DOY" is the day of year in three digits, and "HH:MM:SS" is the time of day in 24 time. The user may change the "DESCRIPTION" and "REQUESTER_NAME" field for aesthetic or bookkeeping purposes (they do not affect the query). The other fields that appear in the figure are used and should be retained as they appear. The following steps explain how to obtain Mars Odyssey UHF Doppler data using the line mode tool "stot": Step Action 1) Log in to Workstation with appropriate access 2) Produce a .pvl file with the desired time range and other fields. It is referred to as xxx.pvl in the following step. 3) type: /sfoc/bin/stot M01_MASTER_QueryServer xxx.pvl -f [outfilename] -v The file written to [outfilename] should be a UNIX file of the format to be input into the Mars Odyssey portion of UHFODP. The query tool will indicate how many packets were written. For the typical data pass between either Mars Exploration Rover and Mars Odyssey, all the Doppler data will appear in one packet. Note, older data may be obtained by substituting "M01_CDR_QueryServer" in to step #3 in place of "M01_MASTER_QueryServer"