ENH: Add Enumeration states to XTCE parser (#783)

This adds the ability to include derived enumeration states from the "States" tab in the spreadsheets.
IMAP-Science-Operations-Center · Aug 30, 2024 · 373f9f3 · 373f9f3
1 parent 2abaa22
commit 373f9f3
Show file tree

Hide file tree

Showing 5 changed files with 295 additions and 13 deletions.
diff --git a/docs/source/code-documentation/tools/xtce-generator.rst b/docs/source/code-documentation/tools/xtce-generator.rst
@@ -124,6 +124,13 @@ the conversion details.
      - ANALOG
      - Apply an analog conversion
      -
+   * - MY_INSTRUMENT_HK
+     - VARIABLE_ENUMERATED
+     - 1
+     - UINT
+     - STATE
+     - Apply an enumeration state
+     -
    * - MY_INSTRUMENT_HK
      - VARIABLE_LENGTH_BINARY_SCIENCE
      - 100
@@ -164,3 +171,26 @@ coefficients defined from ``c0`` to ``c7`` to define the order of the polynomial
      -
      -
      -
+
+States tab (optional)
+~~~~~~~~~~~~~~~~~~~~~
+
+Packet parsing can also apply enumeration/state conversions to the data being read in.
+For example, to change from a raw unsigned integer value to a "VALID" / "INVALID" string.
+The ``States`` tab is used to define these enumerations.
+
+.. list-table:: States
+   :header-rows: 1
+
+   * - packetName
+     - mnemonic
+     - value
+     - state
+   * - MY_INSTRUMENT_HK
+     - VARIABLE_ENUMERATED
+     - 0
+     - INVALID
+   * - MY_INSTRUMENT_HK
+     - VARIABLE_ENUMERATED
+     - 1
+     - VALID
diff --git a/imap_processing/ccsds/excel_to_xtce.py b/imap_processing/ccsds/excel_to_xtce.py
@@ -251,7 +251,6 @@ def _add_parameter(self, row: pd.Series, total_packet_bits: int) -> None:
         # Combine the packet name and mnemonic to create a unique parameter name
         name = f"{row['packetName']}.{row['mnemonic']}"
         parameter.attrib["name"] = name
-        # UINT8, ...
         parameter.attrib["parameterTypeRef"] = name
 
         # Add descriptions if they exist
@@ -329,6 +328,10 @@ def _add_parameter(self, row: pd.Series, total_packet_bits: int) -> None:
             # Go look up the conversion in the AnalogConversions tab
             # and add it to the encoding
             self._add_analog_conversion(row, encoding)
+        elif row["convertAs"] == "STATE":
+            # Go look up the states in the States tab
+            # and add them to the parameter type
+            self._add_state_conversion(row, parameter_type)
 
     def _add_analog_conversion(self, row: pd.Series, encoding: Et.Element) -> None:
         """
@@ -363,6 +366,34 @@ def _add_analog_conversion(self, row: pd.Series, encoding: Et.Element) -> None:
                 term.attrib["coefficient"] = str(conversion[col])
                 term.attrib["exponent"] = str(i)
 
+    def _add_state_conversion(self, row: pd.Series, parameter_type: Et.Element) -> None:
+        """
+        Add a state conversion to the parameter type.
+
+        Changing from an IntegerParameterType to an EnumeratedParameterType. Adding
+        the list of state mappings to the parameter type.
+
+        Parameters
+        ----------
+        row : pandas.Row
+            Row to be added to the XTCE file, containing mnemonic, packetName.
+        parameter_type : Element
+            The parameter type element to add the conversion to.
+        """
+        # It is an EnumeratedParameterType rather than an IntegerParameterType
+        parameter_type.tag = "xtce:EnumeratedParameterType"
+        enumeration_list = Et.SubElement(parameter_type, "xtce:EnumerationList")
+        # Lookup the enumeration states for this parameter from the States sheet
+        state_sheet = self.sheets["States"]
+        state_sheet = state_sheet.loc[
+            (state_sheet["packetName"] == row["packetName"])
+            & (state_sheet["mnemonic"] == row["mnemonic"])
+        ]
+        for _, state_row in state_sheet.iterrows():
+            enumeration = Et.SubElement(enumeration_list, "xtce:Enumeration")
+            enumeration.attrib["value"] = str(state_row["value"])
+            enumeration.attrib["label"] = str(state_row["state"])
+
     def to_xml(self, output_xml_path: Path) -> None:
         """
         Create and output an XTCE file from the Element Tree representation.

diff --git a/imap_processing/tests/ccsds/test_data/excel_to_xtce_test_file.xlsx b/imap_processing/tests/ccsds/test_data/excel_to_xtce_test_file.xlsx
diff --git a/imap_processing/tests/ccsds/test_data/expected_output.xml b/imap_processing/tests/ccsds/test_data/expected_output.xml
@@ -48,7 +48,7 @@
 					<xtce:SizeInBits>
 						<xtce:DynamicValue>
 							<xtce:ParameterInstanceRef parameterRef="PKT_LEN" />
-							<xtce:LinearAdjustment slope="8" intercept="-70" />
+							<xtce:LinearAdjustment slope="8" intercept="-71" />
 						</xtce:DynamicValue>
 					</xtce:SizeInBits>
 				</xtce:BinaryDataEncoding>
@@ -59,6 +59,13 @@
 			<xtce:FloatParameterType name="TEST_PACKET.VAR_FLOAT">
 				<xtce:FloatDataEncoding sizeInBits="32" encoding="IEEE-754" />
 			</xtce:FloatParameterType>
+			<xtce:EnumeratedParameterType name="TEST_PACKET.VAR_STATE" signed="false">
+				<xtce:IntegerDataEncoding sizeInBits="1" encoding="unsigned" />
+				<xtce:EnumerationList>
+					<xtce:Enumeration value="0" label="OFF" />
+					<xtce:Enumeration value="1" label="ON" />
+				</xtce:EnumerationList>
+			</xtce:EnumeratedParameterType>
 			<xtce:IntegerParameterType name="TEST_PACKET2.SHCOARSE" signed="false">
 				<xtce:IntegerDataEncoding sizeInBits="32" encoding="unsigned" />
 			</xtce:IntegerParameterType>
@@ -109,11 +116,14 @@
 			<xtce:Parameter name="TEST_PACKET.VAR_FLOAT" parameterTypeRef="TEST_PACKET.VAR_FLOAT">
 				<xtce:LongDescription>Float data</xtce:LongDescription>
 			</xtce:Parameter>
+			<xtce:Parameter name="TEST_PACKET.VAR_STATE" parameterTypeRef="TEST_PACKET.VAR_STATE">
+				<xtce:LongDescription>State data</xtce:LongDescription>
+			</xtce:Parameter>
 			<xtce:Parameter name="TEST_PACKET2.SHCOARSE" parameterTypeRef="TEST_PACKET2.SHCOARSE">
 				<xtce:LongDescription>Mission elapsed time</xtce:LongDescription>
 			</xtce:Parameter>
-			<xtce:Parameter name="TEST_PACKET2.VAR1" parameterTypeRef="TEST_PACKET2.VAR1" shortDescription="Variable 1 short desc">
-				<xtce:LongDescription>Variable 1 - long desc</xtce:LongDescription>
+			<xtce:Parameter name="TEST_PACKET2.VAR1" parameterTypeRef="TEST_PACKET2.VAR1" shortDescription="Variable 1 short description">
+				<xtce:LongDescription>Variable 1 long description</xtce:LongDescription>
 			</xtce:Parameter>
 		</xtce:ParameterSet>
 		<xtce:ContainerSet>
@@ -142,6 +152,7 @@
 					<xtce:ParameterRefEntry parameterRef="TEST_PACKET.VAR_BYTE" />
 					<xtce:ParameterRefEntry parameterRef="TEST_PACKET.VAR_FILL" />
 					<xtce:ParameterRefEntry parameterRef="TEST_PACKET.VAR_FLOAT" />
+					<xtce:ParameterRefEntry parameterRef="TEST_PACKET.VAR_STATE" />
 				</xtce:EntryList>
 			</xtce:SequenceContainer>
 			<xtce:SequenceContainer name="TEST_PACKET2">