IO-EK-001 29 March 2005 1 of 19 PROJECT CASSINI SOFTWARE INTERFACE SPECIFICATION COVER SHEET SIS Number: IO-EK-001 SIS Revision: Revision C Date: 29 March 2005 SIS NAME: EKernel Files PURPOSE OF INTERFACE: EKernel files containing sequence and science plan data. DATA FLOW: FROM TO DATA OBJECT MEDIUM IO GDSE Binary File Electronic APPLICABLE Documents: Related OIAs: IO-OIA-013 IO-OIA-040 SIS Coordinator: Diane Conner APPROVAL NAME DATE GDSE T. Sesplaukis ____________________________________ NAIF Manager C. Acton ____________________________________ IO Team Manager S. Linick ____________________________________ IO-EK-001 29 March 2005 2 of 19 Document Change Log: Version Change Description Date Initial Initial Release 5 March 2002 Rev A. Reflect design change that eliminates IEB description files. 8 August 2002 Rev B. Reflect design change that eliminates IEB expansion files. Also modified the database schema. Included expanded schema definitions. Updated based upon comments from Chuck Acton. 9 September 2003 Rev C. Added Long_value column to status table Added additional descriptive text. Added filenaming conventions in 4.1. Updated schema diagram. 23 March 2005 IO-EK-001 29 March 2005 3 of 19 1. GENERAL DESCRIPTION ................................................. ........ 4 1.1. Purpose of Document ............................................... .......................................4 1.2. Scope ............................................................. ...................................................4 1.3. Applicable Documents............................................... ......................................4 1.4. Functional Description............................................. ........................................5 1.4.1. Data Source, Destination and Transfer Method .................... ......................6 1.4.2. Pertinent Relationships with Other Interfaces ................... .........................7 1.4.3. Labeling and Identification ..................................... ......................................7 1.4.4. Assumptions and Constraints...................................... ................................7 2. ENVIRONMENT.......................................................... ................ 7 2.1. Hardware Characteristics and Limitations .......................... ...........................7 2.2. Interface Medium and Characteristics .............................. ..............................7 2.3. Input/Output Protocols ............................................ ........................................7 2.4. Failure Protection, Detection and Recovery Features................ ...................7 2.4.1. Backup Requirements.............................................. .....................................8 2.4.2. Security/Integrity Measures...................................... ....................................8 2.5. End-of-File (or Medium) Conventions................................ .............................8 2.6. Utility Programs................................................... .............................................8 3. DATA FLOW CHARACTERISTICS............................................ 9 3.1. Operational Characteristics........................................ .....................................9 3.1.1. Generation Method and Frequency.................................. ............................9 3.1.2. Time Span of Product ............................................ .......................................9 3.2. Data Volume ....................................................... ..............................................9 3.3. Flow Rate ......................................................... .................................................9 4. DETAILED DATA OBJECT DEFINITION................................. 10 4.1. Structure and Organization Overview................................ ...........................10 4.2. Data Format and Definition......................................... ...................................19 IO-EK-001 29 March 2005 4 of 19 1. GENERAL DESCRIPTION 1.1. Purpose of Document The purpose of this document is to describe the format, content, and org anization of SPICE EKernel files specific to the Cassini Project. 1.2. Scope This document describes ESQ (Sequence), ESP (Science Plan), and ENB (notebook) components of Cassini SPICE EKernel files. 1.3. Applicable Documents IO-OIA-040, EKernel IEB and Dictionary Input Files (EKSEQ) IO-OIA-013, EKernel Files Multimission Software Interface Specification (SIS) SPICE Events Kernel, NAIF Document No. 371, Version 1.0, ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/SISs/ SPICE EKernel Tutorials found at ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials or by contacting Chuck Acton of the PDS NAIF node. EKernel Required Reading, NAIF Doc. No. 368, included in the NAIF Toolkit DAS Required Reading, NAIF Doc. No. 367, included in the NAIF Toolkit Cassini Program SPICE Events Kernel System Design Document, D- 22965 IO-EK-001 29 March 2005 5 of 19 1.4. Functional Description The SPICE EKernel is a repository for science plans, instrument and spac ecraft commands, and experimenter's notebook information that can be used by scientists interpreting data returned from spacecraft instruments. The E Kernel will be archived at the NAIF Node of the Planetary Data System (PDS) to preserve the mission science plan and sequence activity information. An overview of the entire EKernel system is provided in SPICE tutorials (Se e applicable documents). The initial Cassini EKernel system design is documented in Cassini Progr am SPICE Events Kernel System Design document, D-22965. Some of the initial design changed after the system design was documented. Changes in the design are reflected in this SIS. Mission operations teams and scientists provide EKernel data. Some EKern el data are in the form of predicts, while others consist of after-the-fact information referred to as "as-flown." The EKernel has three distinct components. Fo r Cassini, as with other projects, the contents of these components are customized. SCIENCE PLAN (ESP) Contains scientific objectives for observations scheduled over a specified period of time. SEQUENCE (ESQ) Contains spacecraft and instrument commands intended to carry out the observation science objectives of the mission (as partly described in the ESP component), command notes, mechanical noise events, and spacecraft and instrument state information. NOTEBOOK (ENB) Contains notes about anomalies, observations, or other after-the-fact event information that may be of interest to other scientists or project personnel. IO-EK-001 29 March 2005 6 of 19 1.4.1. Data Source, Destination and Transfer Method EKernel files are created from a variety of data sources depending upon the component as shown in the table below. A project repository will be used to deliver files to the NAIF provided SPICE Server as described in OIA-IO-013. Input FILE TYPE Input DESCRIPTION EKernel TABLE EKernel Component SIS/OIAs PEF Predicted Events File from the sequence team. This file, along with a command dictionary EK, are used to create a background ESQ EK. CASSINI_CMD CASSINI_STATUS CASSINI_NOTES ESQ OIA SVT-022 (As-flown) OIA SVT-004 (Predict) 3-291 command dictionary XML file. The 3-291 commands XML file from SCO CORE system. CASSINI_CMD_DICT ESQ OIA IO-040 SIS IO-EK-002 Noise events XML files Currently only supplied by ISS. XML file is created by accessing MIPS operational image processing database. CASSINI_NOISE_EVENTS ESQ OIA IO-040 SIS IO-EK-002 Observations and Requests Submitted by all teams through CIMS (Cassini Information Management System) database. Records are extracted from the database containing detailed science requests and high-level observation plans. CASSINI_SP_REQUEST CASSINI_SP_OBSERVATION CASSINI_SP_REQ_OBS ESP OIA IO-054 CIMS DTDs & Toolkit Experimenter Notes Submitted by all teams through CIMS. CASSINI_ENB_REQUEST CASSINI_ENB_OBSERVATION CASSINI_ENB_REQ_OBS ENB OIA IO-054 CIMS DTDs & Toolkit IO-EK-001 29 March 2005 7 of 19 1.4.2. Pertinent Relationships with Other Interfaces A SPICE EKernel file can be accessed using the NAIF toolkit utility INSPEKT and SPICE library subroutines. 1.4.3. Labeling and Identification EK file SFDU K-headers will be created and stored in DOM as detached files with keyword values shown below. The SFDU header will also be included in the EKernel comment area. Keyword Value Type MISSION_NAME = CASSINI SPACECRAFT_NAME = CASSINI DATA_SET_ID = EKERNEL FILENAME = CHARACTER PRODUCT_CREATION_TIME = UTC TIME PRODUCER_ID = CHARACTER SEQ_NUMBER = CHARACTER START_TIME = UTC TIME STOP_TIME = UTC TIME NOTE = CHARACTER 256 1.4.4. Assumptions and Constraints None. 2. ENVIRONMENT 2.1. Hardware Characteristics and Limitations Not applicable. 2.2. Interface Medium and Characteristics File transfer to project file repository 2.3. Input/Output Protocols Not applicable. 2.4. Failure Protection, Detection and Recovery Features Standard file repository procedures. IO-EK-001 29 March 2005 8 of 19 2.4.1. Backup Requirements Standard file repository procedures. Security/Integrity Measures Files will be checked for format integrity using NAIF subroutines. 2.5. End-of-File (or Medium) Conventions See NAIF Document No. 371, Version 1.0 2.6. Utility Programs The NAIF Toolkit utility INSPEKT can be used to access information conta ined within EKernel files. NAIF Toolkit EKernel reader subroutines can also b e utilized in a user's own program to access EKernel data. For user conven ience, an INSPEKT startup file will be created and provided to users. This file will evolve as new queries are developed. A final Cassini INSPEKT startup fil e will be archived with the kernels at PDS. IO-EK-001 29 March 2005 9 of 19 3. DATA FLOW CHARACTERISTICS 3.1. Operational Characteristics 3.1.1. Generation Method and Frequency Described in OIA-IO-013. 3.1.2. Time Span of Product Described in OIA-IO-013. 3.2. Data Volume Described in OIA-IO-013. 3.3. Flow Rate Not applicable. IO-EK-001 29 March 2005 10 of 19 4. DETAILED DATA OBJECT DEFINITION 4.1. Structure and Organization Overview The EKernel is a database stored in a collection of files. One or more t ables may be stored in a single Ekernel file. Tables are logically grouped into files if their data source is the same and if joins can be done between tables. Note that there are joins that can be made between tables that are in different files, i.e. the CASSINI_CMD and CASSINI_ENB_REQ_OBS tables can be joined by REQUEST_ID, and CASSINI_CMD and CASSINI_CMD_DICT tables can be joined by COMMAND, PARAMETER_NAME AND PARAMETER_INDEX. With the exception of the ESQ_COMMAND file type, each file type is creat ed for every sequence. The ESQ_COMMAND file type is created for each command database version delivered to the project. The below table shows the file types, the tables they contain, and their filenaming convention. EKernel File Type Table(s) Filenaming ESQ Commands and Notes CASSINI_CMD CASSINI_NOTE [Sequencenumber]_cmd_[state][v].[ext] Where: [Sequencenumber]: SVT sequence number [state] p: Predicted Events based upon completed sequence f: Flown events with RT changes incorporated [v]: Version letter from a - z [ext]: xes for transfer format bes for IEEE binary format ESQ Subsystem Status CASSINI_STATUS [Sequencenumber]_status_[state][v].[ext] Where: [Sequencenumber]: SVT sequence number [state] p: Predicted Events based upon completed sequence f: Flown events with RT changes incorporated [v]: Version letter from a - z [ext]: xes for transfer format bes for IEEE binary format ESQ Mechanical noise events CASSINI_NOISE_EVENTS [Sequencenumber]_[subsystemid]noise_[v].[ext] Where: [Sequencenumber]: SVT sequence number [subsystemid]: subsystem id (2 digit number) [v]: Version letter from a - z [ext]: xes for transfer format bes for IEEE binary format IO-EK-001 29 March 2005 11 of 19 EKernel File Type Table(s) Filenaming ESQ Command Dictionary CASSINI_CMD_DICT [cmddbVersion].[ext] Where: [cmddbVersion]: command database version [ext]: xbd for transfer format bdb for IEEE binary format ESP Science Plan CASSINI_SP_REQUEST CASSINI_SP_OBSERVATION CASSINI_SP_REQ_OBS [Sequencenumber]_[source][phase][v].[ext] Where: [Sequencenumber]: SVT sequence number [source]: CIMS, or XML file [phase]: Sequence Phase (SSUP is the latest) [v]: Version letter from a - z [ext]: xep for transfer format bep for IEEE binary format ENB Experimenter's Notebook CASSINI_ENB_REQUEST CASSINI_ENB_OBSERVATION CASSINI_ENB_REQ_OBS [Sequencenumber]_[source][phase][v].[ext] Where: [Sequencenumber]: SVT sequence number [source]: CIMS, or XML file [phase]: Sequence Phase (SSUP is the latest) [v]: Version letter from a - z [ext]: xen for transfer format ben for IEEE binary format IO-EK-001 29 March 2005 12 of 19 DICTIONARY_VERSION DESCRIPTION PARAMETER_RANGE PARAMETER_TYPE PARAMETER_INDEX PARAMETER_NAME COMMAND SUBSYSTEM CASSINI_CMD_DICT (ESQ) END_TIME SOURCE_FLAG BEGIN_TIME EVENT COMMAND_EXEC_TIME CASSINI_NOISE_EVENTS (ESQ) SEQUENCE OBSERVATION_TITLE SUBSYSTEM NOTES OBS_DESCRIPTION SCIENCE_OBJECTIVE OBSERVATION_ID CASSINI_SP_OBSERVATION (ESP) DICTIONARY_VERSION REQUEST_ID LONG_VALUE PARAMETER_INDEX ENTRY_ID VALUE_FLAG INT_VALUE DP_VALUE CHR_VALUE PARAMETER_NAME COMMAND TIME CASSINI_CMD (ESQ) SEQUENCE OBSERVATION_ID REQUEST_ID CASSINI_SP_REQ_OBS (ESP) REQUEST_ID LONG_VALUE ATTRIBUTE_INDEX ENTRY_ID CHR_VALUE ATTRIBUTE_NAME TIME CASSINI_NOTE (ESQ) BEGIN_TIME LONG_VALUE PARAMETER_VALUE PARAMETER_NAME SUBSYSTEM CASSINI_STATUS (ESQ) SECONDARY_POINTING BEGIN_TIME END_TIME SEQUENCE REQUEST_TITLE SUBSYSTEM REQ_DESCRIPTION PRIMARY_POINTING POINTING_AGREEMENT REQUEST_ID CASSINI_ SP_REQUEST (ESP) OBSERVATION_TITLE SUBSYSTEM OBS_AS_FLOWN_NOTES SEQUENCE OBSERVATION_ID CASSINI_ENB_OBSERVATION (ENB) SEQUENCE OBSERVATION_ID REQUEST_ID CASSINI_ENB_REQ_OBS (ENB) REQUEST_TITLE SUBSYSTEM REQ_AS_FLOWN_NOTES SEQUENCE REQUEST_ID CASSINI_ENB_REQUEST (ENB) 1:M M:M M:M M:M M:M 1:M 1:M M:1 M:1 M:1 M:1 1:M 1:M END_TIME 1:M IO-EK-001 29 March 2005 13 of 19 Expanded Schema Definition: TABLE COLUMNS TYPE NULLS OK INDEXED DESCRIPTION SUBSYSTEM String of Length 32 N Y Name of subsystem COMMAND String of Length 32 N Y Name of command PARAMETER_NAME String of Length 32 N Y Name of the parameter PARAMETER_INDEX Integer N Y Index of the parameter (Specifies order of parameter_names) CASSINI_CMD_DICT PARAMETER_TYPE String of Length 32 Y N Describes the data type for each parameter. Case sensitive standard values allowed for this element are: Unsigned Integer - an unsigned integer number (abbreviated in the table as Unsign Integer) Signed Integer - a signed integer number String - A string of characters to be translated into binary either directly or via a user hook Hex Hex value Absolute Time - Absolute time in the form yyyydddThh: mm:ss.fff where yyyy = the year ddd = the day of the year (January 1 = 001) hh = hours mm = minutes ss = seconds .fff = fraction of seconds Relative Time (Duration) - Relative time in the form hh:mm:ss.fff where hh = hours mm = minutes ss = seconds IO-EK-001 29 March 2005 14 of 19 TABLE COLUMNS TYPE NULLS OK INDEXED DESCRIPTION .fff = fraction of seconds List The number of items in the list may or may not be a fixed number. The values for parameters of this type are enclosed in braces [ ] in the PEF. Enumerated - these data are typically sets of discrete values. For example, {0,10,100} is an enumerated data set as opposed to {0..100}, which is a set of continuous data. Real Real number. PARAMETER_RANGE Variable array of Strings of length 80. Y N Range of valid values for the parameter. DESCRIPTION Variable array of Strings of length 80. N N Subsystem/Command/Parameter description DICTIONARY_VERSION String of Length 32 N Y Command dictionary version. TIME Time N Y Command time tag from Predicted Events File (PEF). COMMAND Variable Length String N Y Command name. PARAMETER_NAME Variable Length String N Y Parameter name. Parameter names are taken from the command dictionary CHR_VALUE Variable Length String Y Y Value of the parameter as a character string. DP_VALUE Double Y Y Value of the parameter as a double precision number (if character string can be parsed as a double precision number). INT_VALUE Integer Y Y Value of the parameter in integer number (if chara cter string can be parsed as an integer number). CASSINI_CMD VALUE_FLAG Char N Y Single character flag showing which values are prese nt for current parameter. It can be set to ' 'C', 'D','I' or 'A'. These values stand for: 'C' -- only character value is available. 'D' -- character and DP values are available. 'I' -- character, DP and INT values are available. 'A' -- only "long value" is available. IO-EK-001 29 March 2005 15 of 19 TABLE COLUMNS TYPE NULLS OK INDEXED DESCRIPTION ENTRY_ID Variable Length String N Y Character string which has the same value for all EK table records representing a single command record from PEF file. Constructed as :. If string wasn't available from PEF file header, it's replaced with some random string that will be the same for all records from a single PEF file. PARAMETER_INDEX Integer N Y Index of the parameter for a command which s pecifies the order of parameters for a specific command. LONG_VALUE Variable array of Strings of length 80. Y N Values that do not fit into CHR_VALUE field. REQUEST_ID Variable Length String N Y The command request id string from the PEF. DICTIONARY_VERSION String of Length 32 N Y Version of the command dictionary used to create this table. TIME Time N Y Time of the entry from PEF file. ATTRIBUTE_NAME Variable Length String N Y Attribute names are set to some fixed values defined by PEF specification. These values are: PROCESSOR_ID,SEQUENCE_ID, and NOTE_TEXT CHR_VALUE Variable Length String Y Y Value of the attribute in character string. ENTRY_ID Variable Length String N Y Character string which has the same value for all EK table records representing a single command record from PEF file. Constructed as :. If string wasn't available from PEF file header, it's replaced with some random string that will be the same for all records from a single PEF file. ATTRIBUTE_INDEX Integer N Y Index of the attribute in a note record from PEF file. LONG_VALUE Variable array of Strings of length 80. Y N Character string array containing an "80 characters" wrapped long character value that couldn't fit into CHR_VALUE. To get real parameter value from this array all array elements must be concatenated together. CASSINI_NOTE REQUEST_ID Variable Length String N Y The command request id string from the PEF. IO-EK-001 29 March 2005 16 of 19 TABLE COLUMNS TYPE NULLS OK INDEXED DESCRIPTION SUBSYSTEM String of Length 32 N Y Name of subsystem PARAMETER_NAME String of Length 32 N Y Parameter names are taken from corresponding PEF status records. PARAMETER_VALUE Variable Length String N Y Value of the attribute in character string. LONG_VALUE Variable array of Strings of length 80. Y N Values that do not fit into the PARAMETER_VALUE field. BEGIN_TIME Time N Y The time when this parameter obtained the value specified in the PARAMETER_VALUE field. CASSINI_STATUS END_TIME Time N Y The time when this parameter lost the value specified in the PARAMETER_VALUE field. COMMAND_EXEC_TIME Time N Y The execution time of the command that caused a mechanical noise event. EVENT Variable Length String N N Type of mechanical noise event. BEGIN_TIME Time N Y The time when the noise event started to occur. END_TIME Time N Y The time when the noise event ended. CASSINI_NOISE_EV ENTS SOURCE_FLAG Variable Length String N N Indicates whether the source data is predict or actual/asflown data. SUBSYSTEM String of Length 32 N Y Name of subsystem. OBSERVATION_ID Variable Length String N Y An EK unique internal identifier that created by concatenating a sequence and a number. OBSERVATION_TITLE Variable Length String N Y Observation title. SEQUENCE String of Length 32 N Y Sequence identifier string. SCIENCE_OBJECTIVE Variable array of Strings of length 80. Y N Science objectives for this observation. OBS_DESCRIPTION Variable array of Strings of length 80. Y N General description of this observation. CASSINI_SP_OBSE RVATION NOTES Variable array of Strings of length Y N Additional notes for this observation. IO-EK-001 29 March 2005 17 of 19 TABLE COLUMNS TYPE NULLS OK INDEXED DESCRIPTION 80. SUBSYSTEM String of Length 32 N Y Name of subsystem. REQUEST_ID Variable Length String N Y The ID that uniquely identifies the request within the CIMS system. It has the format: ___ REQUEST_TITLE Variable Length String Y Y Title of the request. BEGIN_TIME Time N Y The start time of a request. END_TIME Time N Y The end time of a request. SEQUENCE String of Length 32 N Y Sequence name string. POINTING_AGREEMENT Variable array of Strings of length 80. Y N Spacecraft agreements that were made during the science planning process. PRIMARY_POINTING String of Length 32 Y Y Primary pointing requirement for this request. SECONDARY_POINTING String of Length 32 Y Y Secondary pointing requirement for this request. CASSINI_SP_REQU EST REQ_DESCRIPTION Variable array of Strings of length 80. Y N Request description. REQUEST_ID Variable Length String N Y The request id of the request associated with the observation specified in the OBSERVATION_ID field. OBSERVATION_ID Variable Length String N Y The observation id of the observation associated with the request specified in the REQUEST_ID field. CASSINI_SP_REQ_ OBS SEQUENCE String of Length 32 N Y Sequence name string. SUBSYSTEM String of Length 32 N Y Name of subsystem. OBSERVATION_ID Variable Length String N Y An EK unique internal identifier that is made up of a sequence and a number concatenated together. OBSERVATION_TITLE Variable Length String Y Y Observation title. CASSINI_ENB_OBS ERVATION SEQUENCE String of Length N Y Sequence name string. IO-EK-001 29 March 2005 18 of 19 TABLE COLUMNS TYPE NULLS OK INDEXED DESCRIPTION 32 OBS_AS_FLOWN_NOTES Variable array of Strings of length 80. Y N Information about the execution of the observation onboard the spacecraft (E.g., name of as-flown PEF, indication of change in execution from what was planned, problems with the execution, brief results) SUBSYSTEM String of Length 32 N Y Name of subsystem. REQUEST_ID Variable Length String N Y The ID that uniquely identifies the request within the CIMS system. It has the format: ___ REQUEST_TITLE Variable Length String Y Y Request title. SEQUENCE String of Length 32 N Y Sequence name string. CASSINI_ENB_REQ UEST REQ_AS_FLOWN_NOTES Variable array of Strings of length 80. Y N Information about the execution of the request onboard the spacecraft (e.g., name of as-flown PEF, indication of change in execution from what was planned, problems with the execution, brief results) REQUEST_ID Variable Length String N Y The request id of the request associated with the observation specified in the OBSERVATION_ID field. OBSERVATION_ID Variable Length String N Y The observation id of the observation associated with the request specified in the REQUEST_ID field. CASSINI_ENB_REQ _OBS SEQUENCE String of Length 32 N Y Sequence name string. IO-EK-001 29 March 2005 19 of 19 4.2. Data Format and Definition Please see: Multimission Software Interface Specification (SIS) SPICE Events Kernel, NAIF Document No. 371, Version 1.0,