From a8a0c55a2258b976ea32394e457cc905fbc74790 Mon Sep 17 00:00:00 2001 From: Gabriel M Date: Tue, 26 Sep 2023 15:29:03 -0600 Subject: [PATCH 1/5] Rebasing try 2 --- .../source/reference/tools/xtce_generator.rst | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/source/reference/tools/xtce_generator.rst diff --git a/docs/source/reference/tools/xtce_generator.rst b/docs/source/reference/tools/xtce_generator.rst new file mode 100644 index 000000000..a7a75f79e --- /dev/null +++ b/docs/source/reference/tools/xtce_generator.rst @@ -0,0 +1,81 @@ +.. _xtce_generator: + +Generating Telemetry XML with Python Script +=========================================== + +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 using the TelemetryGenerator class. 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. + +Prerequisites +------------- + +Before you begin, ensure you have the following: + +- Python installed (version 3.9 or higher) +- The required Python packages installed: + - pathlib + - tools.xtce_generation.telemetry_generator + +How to Use +---------- + +Define the instrument name in the `main()` function by setting the `instrument_name` +variable to the name of your instrument. + +:: + + 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. + +:: + + 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 apIds. This is case sensitive. The packet names and apIds +must match the names and apIds in the excel file. You can use as many packet names +and apIds as you want. The apId should not be hexagon format. It should be an integer. +Follow the format below. + +:: + + packets = { + # Define packet names and associated Application IDs (apId) + "your_packet_A": ####, + "your_packet_B": ####, + # ... (other packet definitions) + } + + +Generating Telemetry XML Files +------------------------------- + +This code block generates telemetry XML files for the packets defined in the +`packets` dictionary. The telemetry XML files are saved in the directory specified +by the `packet_definition_path` variable. + + + + + + + From 8101a0e67bb1e055fa67b13d00fa449a6cb43598 Mon Sep 17 00:00:00 2001 From: Gabriel M Date: Tue, 26 Sep 2023 15:40:16 -0600 Subject: [PATCH 2/5] updated xtce documentation and toctree --- docs/source/development/index.rst | 1 + docs/source/development/tools/index.rst | 4 ++ .../tools/xtce_generator.rst | 62 ++++++++++--------- 3 files changed, 37 insertions(+), 30 deletions(-) create mode 100644 docs/source/development/tools/index.rst rename docs/source/{reference => development}/tools/xtce_generator.rst (54%) 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..1f00e2bc7 --- /dev/null +++ b/docs/source/development/tools/index.rst @@ -0,0 +1,4 @@ +.. toctree:: + :maxdepth: 1 + + xtce_generator \ No newline at end of file diff --git a/docs/source/reference/tools/xtce_generator.rst b/docs/source/development/tools/xtce_generator.rst similarity index 54% rename from docs/source/reference/tools/xtce_generator.rst rename to docs/source/development/tools/xtce_generator.rst index a7a75f79e..ca7ad2606 100644 --- a/docs/source/reference/tools/xtce_generator.rst +++ b/docs/source/development/tools/xtce_generator.rst @@ -3,10 +3,18 @@ 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 using the TelemetryGenerator class. The script is designed to -simplify the process of creating telemetry definitions for various packet types. +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 @@ -15,15 +23,16 @@ 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. -Prerequisites -------------- +Before you Start +---------------- -Before you begin, ensure you have the following: +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 -- Python installed (version 3.9 or higher) -- The required Python packages installed: - - pathlib - - tools.xtce_generation.telemetry_generator +.. code:: + + poetry install --extras tools How to Use ---------- @@ -31,32 +40,31 @@ How to Use Define the instrument name in the `main()` function by setting the `instrument_name` variable to the name of your instrument. -:: - - instrument_name = "your_instrument_name" +.. 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 apIds. This is case sensitive. The packet names and apIds -must match the names and apIds in the excel file. You can use as many packet names -and apIds as you want. The apId should not be hexagon format. It should be an integer. +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) @@ -64,18 +72,12 @@ Follow the format below. "your_packet_B": ####, # ... (other packet definitions) } - - Generating Telemetry XML Files ------------------------------- -This code block generates telemetry XML files for the packets defined in the -`packets` dictionary. The telemetry XML files are saved in the directory specified -by the `packet_definition_path` variable. - - - - - +Once you have your xtce processing file defined, you can run it with the +following command: +.. code:: + python xtce_generator_instrument_name.py \ No newline at end of file From e55fa1f2caa8b2a15d281b404fa38f176295b15d Mon Sep 17 00:00:00 2001 From: Gabriel M <104743000+GFMoraga@users.noreply.github.com> Date: Tue, 26 Sep 2023 15:50:44 -0600 Subject: [PATCH 3/5] Update docs/source/development/tools/xtce_generator.rst Minor change to reduce warning Co-authored-by: Maxine Hartnett <117409426+maxinelasp@users.noreply.github.com> --- docs/source/development/tools/xtce_generator.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/development/tools/xtce_generator.rst b/docs/source/development/tools/xtce_generator.rst index ca7ad2606..5eb1dd067 100644 --- a/docs/source/development/tools/xtce_generator.rst +++ b/docs/source/development/tools/xtce_generator.rst @@ -72,6 +72,7 @@ Follow the format below. "your_packet_B": ####, # ... (other packet definitions) } + Generating Telemetry XML Files ------------------------------- From b2665f3e82e983fddc672f6c5b9acf45069133f1 Mon Sep 17 00:00:00 2001 From: Gabriel M <104743000+GFMoraga@users.noreply.github.com> Date: Tue, 26 Sep 2023 15:55:55 -0600 Subject: [PATCH 4/5] Update docs/source/development/tools/index.rst Co-authored-by: Greg Lucas --- docs/source/development/tools/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/development/tools/index.rst b/docs/source/development/tools/index.rst index 1f00e2bc7..5a4e02640 100644 --- a/docs/source/development/tools/index.rst +++ b/docs/source/development/tools/index.rst @@ -1,3 +1,6 @@ +Tools +===== + .. toctree:: :maxdepth: 1 From 504c5750a645e5492dd37dd00a4bf3175f557cf1 Mon Sep 17 00:00:00 2001 From: Gabriel M Date: Tue, 26 Sep 2023 16:08:13 -0600 Subject: [PATCH 5/5] used ruff on xtce_generator doc to fix precommit error --- docs/source/development/tools/index.rst | 3 +++ docs/source/development/tools/xtce_generator.rst | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/source/development/tools/index.rst b/docs/source/development/tools/index.rst index 1f00e2bc7..5a4e02640 100644 --- a/docs/source/development/tools/index.rst +++ b/docs/source/development/tools/index.rst @@ -1,3 +1,6 @@ +Tools +===== + .. toctree:: :maxdepth: 1 diff --git a/docs/source/development/tools/xtce_generator.rst b/docs/source/development/tools/xtce_generator.rst index ca7ad2606..9cf130b3d 100644 --- a/docs/source/development/tools/xtce_generator.rst +++ b/docs/source/development/tools/xtce_generator.rst @@ -80,4 +80,4 @@ following command: .. code:: - python xtce_generator_instrument_name.py \ No newline at end of file + python xtce_generator_instrument_name.py