From 8d922cffb563ca1c46496079b95ce55aacddc0a2 Mon Sep 17 00:00:00 2001
From: Greg Lucas <greg.m.lucas@gmail.com>
Date: Mon, 26 Aug 2024 07:08:52 -0600
Subject: [PATCH] ENH: Add Enumeration states to XTCE parser

This adds the ability to include derived enumeration states from
the "States" tab in the spreadsheets.
---
 .../tools/xtce-generator.rst                  | 30 +++++++++++++++++
 imap_processing/ccsds/excel_to_xtce.py        | 33 ++++++++++++++++++-
 2 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/docs/source/code-documentation/tools/xtce-generator.rst b/docs/source/code-documentation/tools/xtce-generator.rst
index cc16f5066..27e386222 100644
--- 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
index d34aa6d3a..e1521dea1 100644
--- 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.