diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 8c72310d5..f345253be 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -40,4 +40,5 @@ A typical development workflow might look like the following: doc-overview release-workflow style-guide/style-guide + tools/index poetry \ No newline at end of file diff --git a/docs/source/development/tools/index.rst b/docs/source/development/tools/index.rst new file mode 100644 index 000000000..5a4e02640 --- /dev/null +++ b/docs/source/development/tools/index.rst @@ -0,0 +1,7 @@ +Tools +===== + +.. toctree:: + :maxdepth: 1 + + xtce_generator \ No newline at end of file diff --git a/docs/source/development/tools/xtce_generator.rst b/docs/source/development/tools/xtce_generator.rst new file mode 100644 index 000000000..452746a8d --- /dev/null +++ b/docs/source/development/tools/xtce_generator.rst @@ -0,0 +1,84 @@ +.. _xtce_generator: + +Generating Telemetry XML with Python Script +=========================================== + +Here is some info on `XTCE `_. This Green +Book introduces the main concepts of XML Telemetric and Command Exchange (XTCE), a +telemetry and telecommand database format for spacecraft monitoring +and control. + +General +------- + +This document provides steps and information on how to use +`xtce_generator_template.py` script as a base for users to generate +telemetry XML files. The script is designed to simplify the process of creating +telemetry definitions for various packet types. + +The script is located in the `tools/xtce_generation` directory. The script is called +`xtce_generator_template.py`. The script is a ``template`` that can be modified to +generate telemetry XML files for different packet types. Your new file should be +called `xtce_generator_yourinstrument.py`. +An example of how to use the script is `xtce_generator_codice.py` which is also +located in the `tools/xtce_generation` directory. + +Before you Start +---------------- + +Generating XTCEs is only done whenever packet definitions get updated, and thus it +is not a part of the main processing package. To use it there are a few extra +dependencies like ``pandas`` that you can install with + +.. code:: + + poetry install --extras tools + +How to Use +---------- + +Define the instrument name in the `main()` function by setting the `instrument_name` +variable to the name of your instrument. + +.. code:: + + instrument_name = "your_instrument_name" + +In the code, file paths are being configured. Make sure to change the file paths to +match your instrument's file structure. + +.. code:: + + current_directory = Path(__file__).parent + module_path = f"{current_directory}/../../imap_processing" + # This is the path of the output directory + packet_definition_path = f"{module_path}/{instrument_name}/packet_definitions" + # This is the path to the excel file that contains the telemetry definitions + path_to_excel_file = f"{current_directory}/your_packet.xlsx" + +Define packet names and `Application Process Identifiers (APIDs) +`_. +The packet names are **case sensitive** meaning the the packet names need to be exactly +what the tabs of the spreadsheet are. APID's must match the names and apIds in the +packet definition file. You can use as many packet names and apIds as you want. +The APID should be an integer (not hexadecimal). +Follow the format below. + +.. code:: + + packets = { + # Define packet names and associated Application IDs (apId) + "your_packet_A": ####, + "your_packet_B": ####, + # ... (other packet definitions) + } + +Generating Telemetry XML Files +------------------------------- + +Once you have your xtce processing file defined, you can run it with the +following command: + +.. code:: + + python xtce_generator_instrument_name.py