TIDE Commanding Software Documentation (revised 12/07/05) NOTE: For information about creating RQLs, see create_rqls.txt. This is documentation of the software used to create the files sent to GSFC for use in commanding TIDE. The command files created by the software are stored in subdirectory named for the filetype (ie: act, mac, mic, rql, rtc, or txt). The local command files should all be lower-case for ease in typing them. The software takes care of converting them to upper-case for use at GSFC. NOTE: All filenames used in command sequences must be in capital letters. The software is written in IDL and C. It is run from IDL on griffin in directory /export/data/tide/command. The command to enter IDL is 'idl'. The software should be run from the tidops account on griffin. All files sent to GSFC for validation MUST be sent from the tidops account. The IDL command to execute the software is @command. The user is prompted for all necessary information. The first prompt determines the type of processing: 0 - stop 1 - create new files 2 - send existing files to GSFC what next => Note: Currently all files created need to be reviewed by at least one other person before the are sent to GSFC, so option 2 is currently not available. The command to manually send a file to GSFC is: mail spofcmd@spof07.nascom.nasa.gov < {filename] Each of the subdirectories where to command files are stored have a script called 'send-mail' that can be edited and used to send more than one file. Never send more than three files at a time. The validation reports may not get transmitted correctly. The second prompt asks for the name of the individual responsible for the file and its content: 0 - stop 1 - P.D.Craven 2 - M.O.Chandler 3 - other observer code => Make sure that either Paul or Mike reviews the file before it is sent GSFC. The next prompt determines the filetype. 0 - stop 1 - instrument request 2 - activity file 3 - macro file 4 - microprocessor request file 5 - real-time command file 6 - principle investigator text file file type => The next prompt asks for the user portion of the filename, which varies depending on the filetype. For Instrument Requests, the user enters the day of year, for microprocessor files the user enters a 7-character description, for all other files, the user enters a 9-character description. If the requested filename already exists, the user will be asked to enter a different one. For filetypes 4 or 5, the user is asked if the request is urgent: Urgent request y/n => All RTC (realtime command requests) are URGENT. If a new MIC files is being sent with the RTC, it must also be URGENT. For most files, the user is asked to enter a short 60-char description of the file: Enter a short (max.60char) file description ---------1---------2---------3---------4---------5---------6 If 60 characters is not enough, the software will let you add more detailed comments to both the header and the command sequence. For mirco processor files, the user is asked if they should be saved at GSFC. Always answer yes. Once the file has been completed, the following three prompts determine if the file is saved locally and if it is e-mailed to GSFC. List completed file? y/n => Save completed file? y/n => If the file is a microprcessor file, it MUST be sent to SwRI for verification on the TIDE engineering unit before it is sent to GSFC. Send the hex dump of the file along with an email message and/or a phone call to Ron Black (ronb@swri.edu 210-522-3562). Once a file has been okayed here and if necessary at SwRI, it has to be emailed to GSFC for validation. To send the file to GSFC, fisrt cd to the appropriate subdirectory (act, mac, mic, ttc, or txt) and either type the mail command: mail spofcmd@spof07.nascom.nasa.gov < [filename] or edit the existing 'send_mail' command file, change the filename(s) and submit the mail commands by typing 'send_mail'. GSFC should email the validation report back within ten minutes. If it takes over 30 minutes, call Chris Raymond (301-286-7864) to see if the file was received and processed. The send_mail script can be used to send more than one file at a time. Never send more than 4 files at a time. You may end up losing a validation report. A list of the file sent to GSFC, the returned validation report, and associated microprocessor text files (the hex dumps, the .swp, and the .mss files) need to be added to the command binder in 377. Use save-a-tree on a Mac to list each file so that the filename appears on the listing. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- Microprocessor Files: --------------------- Two additional prompts for microprocessor files are: save file at GSFC (y/n) => 0 - stop 1 - define a new RAM mass definition table 2 - define a new RAM energy sweep table 3 - define a new set of autosensitivity thresholds 4 - absolute data load, memory patch microprocessor file type => For absolute dataloads, the user is asked for the name of the text file containing the hexidecimal listing of the 40-bit instrument commands that make up the dataload. This file is usually (possibly always) created at SwRI and email here. The software simply reads this file, verifies the data content, converts it to encoded binary, and adds the header. The file sent from SwRI needs to be copied to the mic/dl subdirectory for permanent storage. The prompts to create an energy sweep microprocessor file are: energy sweep table number (5 or 6) => read sweep from text file (1) or calculate it (2) => If the data is in a file the user is asked for the filename. The file format are the 32 RPA voltages, 8f10.5 per line, four lines; followed by the 16 mirror ratio sensitivity levels, 8f10.5 per line, 2 lines; followed by the 32 sensitivity level indexes, 16i4 per line, 2 lines. There are examples of these files in /export/data/command/MIC/data. For calculated sweeps, the user is prompted for: sweep type linear(1) or exponential(2) => Vrpa minimum => Vrpa maximum => The voltages must be greater than zero and less or equal to 300. The resulting 32 voltages are listed. The Vmir/Vrpa ratios can be calculated: linear(1) or exponential(2) => Vmir/Vrpa minimum => Vmir/Vrpa maximum => or the Vmir/Vrpa ratios can be entered one at a time: Vmir/Vrpa 0 : Vmir/Vrpa 1 : Vmir/Vrpa 2 : . . . Vmir/Vrpa 15 : The resulting Vmir/Vrpa ratios are listed at and the user is asked to enter either a constant sensitivity level index or all 32 level indexes, separated by blanks. When creating a mass look-up table microprocessor file, the user receives the following information and prompts: Enter amu/chrg, minimum tof bin, maximum tof bin for all 8 masses, one mass per line, separate values by spaces Enter three 555s to start over, three 999s to stop. mass 8 : mass 9 : mass 10 : mass 11 : mass 12 : mass 13 : mass 14 : mass 15 : If any of the masses have been entered incorrectly, the user can start over by typing 3 555's or stop program execution with 3 999's For autosensitivity threshold microprocessor files, the user is prompted for threshold 0 : threshold 1 : threshold 2 : threshold 3 : threshold 4 : count threshold : All 6 values are added to the file header as a comment. If an error occurs during the creation of a microprocessor file, the user is told why and program execution stops. The most comman cause for an error is when the first two bytes of a command are F0, F1, F2, F3, F4, or F5. These values cannot be sent to the on-board processor. The binary portion of the dataload will have to be modified to get rid of theses commands. Use the hex dump files to locate the commands. If the user requests that a microprocessor file be stored at GSFC, a bried description of the stored file is added to saved.mics. Previous versions of the mass description table are kept as /export/data/tide/command/MIC/old/mass_desc.mmddyy where mmddyy is the data the file was replaced. The current table is always /export/data/tide/command/mass_desc.tbl current.masses contains a list of the 16 masses that are currently defined on-board. If the mass description file has been updated, a warning is displayed. All co-investigators need to be notified that a new table exists: *********** New Mass Description Table ************* If the mass to charge ratio for a new mass is not already in the mass description table, the user is asked to enter the ions actual weight in amu and a character label assigned to the mass, up to 12 characters long. The tof bin number range for a new mass must be different from any previously defined mass. If the range is not unique, the user is given the option to stop or to enter a new range. Previous versions of the energy sweep description table are kept as /export/data/tide/command/MIC/old/eswp_desc.mmddyy where mmddyy is the data the file was replaced. The current table is always /export/data/tide/command/e_sweeps_desc.tbl current.eswps lists the 7 energy sweep tables currently stored on-board TIDE. If the energy sweep description file has been updated, a warning is displayed. ********* New Energy Sweep Description Table ********** The binary portion of the file is encoded and appended to the header file, a command hex dump is created, and text files are created for energy sweeps and mass look-up tables. All microprocessor files MUST be sent to SwRI for verification on the TIDE engineering unit before it is sent to GSFC. Send the hex dump of the file along with an email message and/or a phone call to Ron Black (ronb@swri.edu or 210-522-3562). As a reminder, the software prints the following: NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE All microporcessor files need to be verified on the TIDE engineering unit at SwRI before being sent to GSFC. E-Mail the .hex file to Ron Black (ronb@swri.edu). NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE All microprocessor files start with the following sequence of letters: TIDAL - absolute data loads, software patches, memory changes TIDAT - autosensitivity threshold values TIDCT - calibration mode energy sweep tables TIDET - science mode energy sweep tables TIDMT - mass look-up table descriptions TIDPT - pulser tables ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- Daily Instrument Request List: ------------------------------ SEE /export/data/tide/command/doc/create_rqls.txt FOR CUURENT DOCUMENTATION. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- Instrument Command Sequence Activity and Macro Files: ----------------------------------------------------- In the current sofware, the user provides a file containing the text for both the realtime and principle investigator files. The software then creates and adds the header. A description of each Activity is kept in current.activities and a description of each Macro is kept in current.macros. If the file is an activity, the user is asked for the time offset from the previous command: time (hh:mm:ss) offset for command: => If the command selected is a minor mode command, the user will be prompted for any other data require. Command sequences are built via selections from the following menu: 0 stop 1 spacecraft pulse commands 2 data processing commands 3 mass look-up table commands 4 instrument operations commands 5 power supply commands 6 calibration pulser commands 7 plasma source instrument commands 10 load macro file 11 load microprocessor file 12 execute macro file 13 execute activity file 15 add comment line 20 list command sequence, so far 21 list 16 defined masses and 5 selected masses 22 list current energy sweep table 23 list description of existing macros 24 list description of existing activities 25 list description of saved mircoprocessor files 30 save current command list and add header command type => Option 0 stops execution with no command file created. Option 20 lists the command sequence so far, options 21 - 22 provide the user with information required by some command sequences. This information is also available when required by a request command. Option 30 actually creates the command file. To enter a comment into either the file header or the command list, type a continuous stream of characters with no until the entire comment is entered, the software will break the comment in to separate lines. For options 10 and 11, the available files and a short description of each is provided and the user asked to enter the name of the Macro or Microprocessor file to be up loaded to the instrument. For options 12 and 13, the available files and a short description of each is provided and the user asked to enter the name of the Macro or Activity file to be executed. ------------------------------------------------------------------------------- The following is a list of spacecraft pulse commands. None of them are added to command sequence in this version of the software. 0 return to command menu 1 STID_OFF TIDE Power off 2 STID_ON TIDE Power on 3 STID_PSIOFF PSI Power off 4 STID_PSION PSI Power on 5 STID_15KVARM TIDE 15 kV arm 6 STID_BOOTS1 TIDE bootstrap 1 7 STID_BOOTS2 TIDE bootstrap 2 8 STID_HVMOFF TIDE high voltage master off 9 STID_MCPRM TIDE MCP high voltage arm 10 STID_RPAARM TIDE RPA/MIR high voltage arm 11 STID_RST TIDE 5p reset command => The following is a list of spacecraft pulse commands. None of them are added to command sequence in this version of the software. 0 return to command menu 1 STID_OFF TIDE Power off 2 STID_ON TIDE Power on 3 STID_PSIOFF PSI Power off 4 STID_PSION PSI Power on 5 STID_15KVARM TIDE 15 kV arm 6 STID_BOOTS1 TIDE bootstrap 1 7 STID_BOOTS2 TIDE bootstrap 2 8 STID_HVMOFF TIDE high voltage master off 9 STID_MCPRM TIDE MCP high voltage arm 10 STID_RPAARM TIDE RPA/MIR high voltage arm 11 STID_RST TIDE 5p reset command => For option 2, the data processing commands are: 0 return to command menu 1 DTC_EN Dead Time Correction Enable 2 DTC_DIS Dead Time Correction Disable 3 RICE_EN RICE Compression Enable 4 RICE_DIS RICE Compression Disable 5 COLLAPSE Collapse Option/CAL Mode 6 TRUN_RPRT Truncated Reporting 7 FIXED_ION Complete Report of Fixed Ions 8 PRI_ORDER Priority Ordering 9 ROTAT_ION Complete Rep W/Rotate Ions 10 HTR_EN High Time Res Mode Enable 11 HTR_DIS High Time Res Mode Trigger Dis 12 MOMENT_EN Moments Disable 13 MOMENT_DIS Moments Enable 14 DP_DE0_EN Direct Event Sector 0 enable 15 DP_DE0_DIS Direct Event Sector 0 disable command => For data processing option 5, the user prompt is: collapse option (0-6) => For data processing option 6, the user prompt is: enter 1 if mass reported, 0 if not, separate values with blanks reported masses: For data processing option 7, the user prompts are: for each mass enter its order in a report (0-5) mass 0 order (0-5): mass 1 order (0-5): mass 2 order (0-5): mass 3 order (0-5): mass 4 order (0-5): mass 5 order (0-5): priority ordering scheme (0 or 1) => For data processing option 8, the user prompt is: enter 1 if mass rotated, 0 if not, separate values with blanks you must select 4 masses, the masses not selected are always reported rotated masses: For data processing option 9, the user prompts are: EFI trigger no(0),yes(1) => HYDRA trigger no(0),yes(1) => moments trigger no(0),yes(1) => triggers ANDed(0) or ORed(1) => moments standard deviation threshold (0-15) => number of superspins to dwell in htr (0-15) => For option 3, the mass lookup table commands are: 0 return to command menu 1 LD_P_DFLT Load Power-up Default Table 2 LUT_E_SPEC create new mass definitions 3 LUT_BLD Mass Look-up Table Build 4 LUT_SWAP swap Mass Look-up table command => For mass lookup option 2, the user prompts are: enter mass/charge, tof min, and tof max for each of 8 masses mass 8 : mass 9 : mass 10 : mass 11 : mass 12 : mass 13 : mass 14 : mass 15 : For mass lookup option 3, the user is provided a list of the 16 masses and askes to select five of them: select 5 masses (enter 5 numbers > 15 to stop) => For option 4, instrument operations commands are: 0 return to command menu 1 WATCH_DIS Watchdog Disable 2 WATCH_EN Watchdog Enable 3 SPIN_LOCK S/C Spin Sun Pulse Lock 4 SPIN_FREE S/C Spin Free-Run Mode 5 EXE_SS_CMD Execute Stored SSpin Cmds 6 CNS_PS_EN Const Phase Shifts Offset Ena 7 PS_DIS Phase Shift (Spin Offset) Dis 8 HAR_DIS High Angular Res Mode Disable 9 HAR_EN High Angular Res Mode Enable 10 IMP_DUMP IMP Dump Mode Enable 11 DP_DUMP DP Dump Mode Enable 12 CLR_ER_FLG Clear IMP/DP Error 13 DEF_A_S_EN Default Auto Sens Cntl Enable 14 OPT_A_S_EN Optional Auto Sens Cntl Ena 15 AUTOS_DIS Auto Sensitivity Cntl Disable 16 SCI TIDE Science Mode 17 CON TIDE Contingency Mode 18 MAN TIDE Maneuver Mode 19 ENG TIDE Engineering Mode 20 X1 TIDE 55.65 KBPS TLM Rate 21 SCRESET TIDE S/C Reset Indicator command => For instrument operations option 5, the user prompt is: phase shift (0-255) => For instrument operations option 8, the user prompt is: spins per phase shift (0-31) => For instrument operations option 8, the user prompt is: enter memory dump location in hex => For option 5, the power supply commands are: 0 return to command menu 1 enable high voltage power supplies 2 disable high voltage power supplies 3 update MCP 2.4 kV DAC 4 update MCP 3.6 kV DAC 5 update MCP 15 kV DAC 6 Select Energy Sweep Table 7 Energy Sweep Table fill 8 Energy Sweep Table swap command => For power supply option 3, 4, and 5, the user prompts are: MCP 2.4 kV DAC value (0-255) => MCP 3.6 kV DAC value (0-255) => MCP 15 kV DAC value (0-255) => For power supply option 6, the user prompts are: energy sweep table number (0-6) => execute on superspin(0) or spin(1) boundary => For power supply option 7, the user prompt is: RPA voltage (0.0 - 300.0) => Vmir/Vrpa (0.0 - 1.0) => For option 6, the calibration pulser commands are: 0 return to command menu 1 P_1_CMD_EN Cal Pulser Single Cmd Enable 2 P_M_CMD_EN Cal Pulser Sequence Cmd Enable 3 C_PUL_DIS Cal Pulser Disable command => For calibration pulser option 1, the user prompts are: delay rate (0-7) => rep rate (0-15) => enter TOF sectors, 7 values, 0 or 1, separated by blanks => For option 7, Plasma Source Instrument commands are: 0 no command selected 1 H_PS_OFF Heater Power Supply Off 2 H_PS_ON_L1 Heater Power Supply On Level 1 3 H_PS_ON_L2 Heater Power Supply On Level 2 4 H_PS_ON_L3 Heater Power Supply On Level 3 5 D_PS_OFF Discharge Power Supply Off 6 D_PS_ON_L1 Discharge PS On Level 1 7 D_PS_ON_L2 Discharge PS On Level 2 8 D_PS_ON_L3 Discharge PS On Level 3 9 K_PS_OFF Keeper Power Supply Off 10 K_PS_ON_L1 Keeper Power Supply On Level 1 11 K_PS_ON_L2 Keeper Power Supply On Level 2 12 K_PS_ON_L3 Keeper Power Supply On Level 3 13 VALVE_OFF Valve Off 14 VALVE_ON Valve On 15 BIAS_CTRL 12 Bit Bias Voltage Control command => For PSI option 15, the user prompt is: 12-bit bias voltage control in hex (000-fff) =>