From 652570a86fdb76a8e3dc52d5d90542c1fd67d414 Mon Sep 17 00:00:00 2001
From: Mike McCann <MBARIMike@gmail.com>
Date: Thu, 1 May 2025 11:54:48 -0700
Subject: [PATCH] Initial commit of a troubleshooting guide.

---
 .vscode/launch.json |  6 ++++--
 TROUBLESHOOTING.md  | 19 +++++++++++++++++++
 2 files changed, 23 insertions(+), 2 deletions(-)
 create mode 100644 TROUBLESHOOTING.md

diff --git a/.vscode/launch.json b/.vscode/launch.json
index 8e337122..c953e08f 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -139,7 +139,8 @@
             //"args": ["--auv_name", "dorado", "--mission", "2021.102.02", "-v", "1", "--flash_threshold", "1.5e10"],
             //"args": ["--auv_name", "dorado", "--mission", "2024.317.01", "-v", "1"],
             //"args": ["--auv_name", "dorado", "--mission", "2010.341.00", "-v", "1", "--plot", "--plot_seconds", "82000"],
-            "args": ["--auv_name", "dorado", "--mission", "2020.337.00", "-v", "1"],
+            //"args": ["--auv_name", "dorado", "--mission", "2020.337.00", "-v", "1"],
+            "args": ["--auv_name", "dorado", "--mission", "2023.123.00",],
         },
         {
             "name": "5.0 - archive.py",
@@ -226,7 +227,7 @@
             //"args": ["-v", "1", "--last_n_days", "30", "--start_year", "2022", "--end_year", "2022", "--resample", "--noinput"]
             //"args": ["-v", "1", "--last_n_days", "30", "--start_year", "2022", "--end_year", "2022", "--archive", "--noinput"]
             //"args": ["-v", "1", "--start_year", "2021", "--end_year", "2022",  "--noinput"]
-            "args": ["-v", "1", "--mission", "2022.201.00", "--clobber", "--noinput", "--no_cleanup"]
+            //"args": ["-v", "1", "--mission", "2022.201.00", "--clobber", "--noinput", "--no_cleanup"]
             //"args": ["-v", "1", "--mission", "2009.084.00",  "--clobber", "--noinput"]
             //"args": ["-v", "1", "--mission", "2022.243.00",  "--calibrate", "--clobber", "--noinput"]
             //"args": ["-v", "1", "--start_year", "2004",  "--end_year", "2004", "--start_yd", "168", "--use_portal", "--clobber", "--noinput"]
@@ -266,6 +267,7 @@
             //"args": ["-v", "1", "--noinput", "--no_cleanup",  "--mission", "2011.256.02", "--clobber"]
             //"args": ["-v", "1", "--noinput", "--no_cleanup",  "--mission", "2010.341.00", "--download_process", "--local"]
             //"args": ["-v", "1", "--noinput", "--no_cleanup",  "--mission", "2020.337.00", "--local"]
+            "args": ["-v", "1", "--mission", "2023.123.00", "--noinput", "--no_cleanup"]
         },
     ]
 }
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 00000000..40bbc171
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,19 @@
+# Troubleshooting auv-python
+
+These instructions describe how to work with this project in VS Code.
+
+## Process a mission and have intermediate files available for local debugging
+
+1. Add an entry for the desired mission to `.vscode/launch.json` in either "process_dorado" or "process_i2map" section. Omitting the `--clobber` option prevents the final files from being copied to the archive. The `--no_cleanup` option does not remove the local work files after processing is finished, `--noinput` bypasses any questions that `process_dorado.py` may ask. For example, add this mission in the "process_dorado" of `.vscode/launch.json`:
+```
+"args": ["-v", "1", "--mission", "2023.123.00", "--noinput", "--no_cleanup"]
+```
+and make sure that it's the only entry in "process_dorado" that is uncommented.
+
+2. From VS Code's Run and Debug panel select "process_dorado" and click the green Start Debugging play button. For data to be copied from the archive the smb://atlas.shore.mbari.org/AUVCTD share must be mounted on your computer. Primary development is done in MacOS where the local mount point is /Volumes. Archive volumes are hard-coded as literals in [src/data/process_dorado.py](https://github.com/mbari-org/auv-python/blob/fc3b58613761b295ab47907993c4d0eb0bceb197/src/data/process_dorado.py) and [src/data/process_i2map.py](https://github.com/mbari-org/auv-python/blob/fc3b58613761b295ab47907993c4d0eb0bceb197/src/data/process_i2map.py). These should be changed if you mount these volumes at a different location.
+
+3. Mission log data will copied to your `auv-python/data/auv_data/` directory into subdirectories organized by vehicle name, mission, and processing step. Data will be processed as described in [WORKFLOW.md](WORKFLOW.md). A typical mission takes about 10 minutes to process.
+
+4. After all of the intermediate files are created any step of the workflow may be executed and debugged in VS Code. The `.vscode\launch.json` file has several example entries that can be modified for specific debugging purposes via the menu in the Run and Debug panel.
+
+5. For example to test bioluminesence proxy corrections a breakpoint can be set in the resample.py file and `4.0 - resample.py` can be debugged for the appropriate mission entered into that section of `.vscode\launch.json`. BTW, I prefer not to have that .json file formatted, so I disable the `json.format.enable` setting in VS Code, or save the file with Cmd-K S. This makes it easier to comment out and enable specific processing to be done.