OscarWatch-Tracker/help/doppler-pass-insights.html at main · magicbug/OscarWatch-Tracker · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
<!DOCTYPE html>
<html lang="en-GB">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Doppler pass insights — OscarWatch Help</title>
  <link rel="stylesheet" href="styles.css" />
</head>
<body>
  <div class="wrap">
    <header>
      <div class="brand">
        <a href="index.html" class="brand-home" title="Home"><img src="oscarwatch-icon.png" alt="" class="brand-icon" width="56" height="56" /></a>
        <div class="brand-text">
          <h1>Doppler pass insights</h1>
          <p class="tagline">Plain-language tuning advice for Adaptive threshold and Lead Doppler CAT settings</p>
        </div>
      </div>
      <nav aria-label="Help topics">
        <ul>
          <li><a href="quick-start.html">Quick start</a></li>
          <li><a href="map-and-sidebar.html">Map &amp; sidebar</a></li>
          <li><a href="frequencies.html">Frequencies</a></li>
          <li><a href="satellites.html">Satellites &amp; TLEs</a></li>
          <li><a href="passes.html">Pass planning</a></li>
          <li><a href="radio-rotator.html">Radio &amp; rotator</a></li>
          <li><a href="settings.html">Settings</a></li>
          <li><a href="keyboard-shortcuts.html">Shortcuts</a></li>
          <li><a href="troubleshooting.html">Problems?</a></li>
        </ul>
      </nav>
    </header>

    <main>
      <p class="lead">
        The Doppler pass insights tool loads a recorded pass log (CSV) and tells you, in plain language,
        whether your Adaptive threshold and Lead Doppler settings are working well — and what to change if not.
        You can also load a second pass to compare settings before and after a tweak.
      </p>

      <h2>Opening Doppler pass insights</h2>
      <p>
        Go to <strong>Menu → Help → Doppler pass insights</strong> to open the window.
      </p>

      <h2>Loading a pass log</h2>
      <p>
        Click <strong>Open CSV</strong> to browse to any Doppler log file on your computer, or click
        <strong>Load latest</strong> to open the most recent log from your local folder. Each row in the CSV
        records a snapshot or CAT event during the pass.
      </p>
      <p>
        After loading, start on the <strong>Tuning guide</strong> tab — that is where the actionable advice lives.
        The chart and detailed metrics are on other tabs if you want to dig deeper.
      </p>

      <h3>Opening the logs folder</h3>
      <p>
        On the <strong>Files</strong> tab, click <strong>Open log folder</strong> to open your system file browser
        to the Doppler logs directory. On Windows, logs are stored in
        <code>%AppData%\OscarWatch\doppler-logs\</code>.
      </p>

      <h2>Tuning guide tab</h2>
      <p>
        This is the main tab. It is designed for radio amateurs who want a clear answer, not a wall of graphs.
      </p>

      <h3>Pass headline</h3>
      <p>
        Shows the satellite name, pass duration, and peak elevation so you know which pass you are reviewing.
      </p>

      <h3>Verdict</h3>
      <p>
        A short overall assessment, for example:
      </p>
      <ul>
        <li><strong>Tracking looks good</strong> — typical error stayed low; no major changes suggested</li>
        <li><strong>Threshold may be too high</strong> — too many samples were suppressed; the radio was not corrected often enough</li>
        <li><strong>Consider Lead Doppler</strong> — fast Doppler slew but lead was off or rarely used</li>
        <li><strong>CAT may be too aggressive</strong> — write rate very high; tuning may sound choppy</li>
        <li><strong>Manual tuning detected</strong> — interactive or CAT-paused periods during the pass</li>
      </ul>

      <h3>Adaptive threshold card</h3>
      <p>
        Explains whether adaptive threshold helped near TCA, whether the band was too conservative,
        or whether you should enable it. Each card ends with a specific suggested action
        (e.g. lower threshold by 10–20 Hz, or keep adaptive enabled).
      </p>

      <h3>Lead Doppler card</h3>
      <p>
        Explains whether Lead Doppler kept up during fast legs, was too weak, or was not needed.
        Suggests changes to lead time or lead strength in Radio settings when appropriate.
      </p>

      <h3>Settings recorded for this pass</h3>
      <p>
        Pulled from the log file header: linear threshold, CAT delay, adaptive on/off, lead on/off,
        lead time, and lead strength. Use this to confirm which settings were active when the pass was recorded.
      </p>

      <h3>Recommendations</h3>
      <p>
        A bullet list of follow-up items based on the pass data (threshold too high/low, enable lead, try adaptive, etc.).
      </p>

      <h3>Pass breakdown</h3>
      <p>
        The pass is split into stages — AOS (start), rising, TCA vicinity, descending, and LOS (end).
        For each stage you see downlink tracking error (p95), CAT write rate, peak slew, and max elevation.
        Use this to see <em>where</em> in the pass a problem occurred: threshold tuning matters more on the
        approach legs; Lead Doppler matters most near TCA and on the descending leg.
      </p>

      <h2>Chart tab</h2>
      <p>
        The chart is for visual confirmation once you have read the tuning guide. It shows how tracking error
        grew and dropped over the pass:
      </p>
      <ul>
        <li><strong>Blue</strong> — Downlink tracking error (Hz from calculated Doppler target)</li>
        <li><strong>Orange</strong> — Uplink tracking error</li>
        <li><strong>Teal band</strong> — Adaptive threshold zone (effective threshold during fast legs)</li>
        <li><strong>Dashed teal line</strong> — Base threshold (your configured SSB/CW value)</li>
        <li><strong>Purple ticks</strong> — CAT corrections (when OscarWatch commanded the radio)</li>
        <li><strong>Grey strip below</strong> — Satellite elevation over the pass</li>
        <li><strong>Amber dashed line</strong> — TCA (time of closest approach, highest elevation)</li>
      </ul>
      <p>
        Lines break at each CAT write so you see individual “sawteeth” rather than a tangled web.
        Smaller, smoother cycles mean better tracking. The vertical axis is labelled
        <strong>Tracking error (Hz)</strong>; the horizontal axis is elapsed time from pass start.
      </p>

      <h3>Zooming and panning</h3>
      <p>
        Use the zoom buttons above the chart:
      </p>
      <ul>
        <li><strong>+</strong> — Zoom in (up to 16× magnification)</li>
        <li><strong>−</strong> — Zoom out</li>
        <li><strong>Reset</strong> — Return to full-pass view</li>
      </ul>
      <p>
        When zoomed in, scroll horizontally to pan. You can also use Ctrl+scroll wheel to zoom.
        This helps you inspect the steep middle of a pass or the approach and departure legs.
      </p>

      <h2>Analysis tab</h2>
      <p>
        Detailed numbers for operators who want the raw metrics:
      </p>

      <h3>Overview</h3>
      <ul>
        <li><strong>Summary</strong> — Satellite, pass window, row counts, snapshots, CAT writes, offset changes</li>
        <li><strong>Thresholds</strong> — Base and effective threshold, adaptive reduction, suppressed row percentage</li>
        <li><strong>Dynamics</strong> — Average and p95 deltas, peak slew</li>
        <li><strong>Activity</strong> — RX/TX write rates, interactive rows, CAT paused, lead enabled</li>
      </ul>

      <h3>Activity bars</h3>
      <p>
        Progress bars for RX writes, TX writes, suppressed-by-threshold rows, and manual/interactive periods.
      </p>

      <h3>Recent events</h3>
      <p>
        A chronological log of sampled points: UTC time, event type, RX/TX deltas, write flags, threshold status, and notes.
      </p>

      <h2>Comparing two passes</h2>
      <p>
        On the <strong>Files</strong> tab, click <strong>Open compare CSV</strong> and load a second pass log
        (e.g. after changing threshold, adaptive, lead time, or lead strength). OscarWatch will:
      </p>
      <ul>
        <li>Overlay the comparison pass on the chart as dashed lines</li>
        <li>Show both passes' metrics in the Comparison tab</li>
        <li>Calculate a verdict (better, worse, or mixed)</li>
        <li>Suggest the next tuning step</li>
      </ul>
      <p>
        Change <strong>one setting at a time</strong>, record another pass, then compare — otherwise you will not
        know which change helped.
      </p>

      <h3>Understanding the comparison verdict</h3>
      <p>
        The <strong>Comparison</strong> tab appears once you load a second pass:
      </p>
      <ul>
        <li>
          <strong>Tick (✓) Better</strong> — The second pass improved on several metrics: lower p95 deltas
          with stable write rates.
        </li>
        <li>
          <strong>Cross (×) Worse</strong> — The second pass got worse. Consider reverting or trying a different adjustment.
        </li>
        <li>
          <strong>Tilde (~) Mixed</strong> — One metric improved, one got worse. Fine-tune further.
        </li>
      </ul>

      <h3>Next actions</h3>
      <ul>
        <li><strong>Lower threshold or CAT delay slightly</strong> — More aggression would help</li>
        <li><strong>Raise threshold or CAT delay slightly</strong> — Reduce write chatter</li>
        <li><strong>Keep these settings</strong> — Tuning looks solid</li>
        <li><strong>Make a small adjustment and compare again</strong> — Results inconclusive</li>
      </ul>

      <h2>Practical tuning workflow</h2>
      <ol>
        <li>
          <strong>Enable pass logging.</strong> In Settings → Radio, turn on Doppler pass log (CSV).
        </li>
        <li>
          <strong>Record a baseline pass.</strong> Work a satellite with your current Doppler settings.
        </li>
        <li>
          <strong>Open tuning guide.</strong> Menu → Help → Doppler pass insights → Load latest.
          Read the verdict and Adaptive / Lead cards first.
        </li>
        <li>
          <strong>Make one small change.</strong> Adjust threshold by 10–20 Hz, toggle adaptive threshold,
          or tweak lead time or lead strength — try only one change.
        </li>
        <li>
          <strong>Record a second pass</strong> and load both CSVs via Files → Open compare CSV.
        </li>
        <li>
          <strong>Repeat or keep.</strong> If the comparison verdict is better, keep or refine.
          If worse, revert and try a different direction.
        </li>
      </ol>

      <div class="tip">
        <strong>Tip:</strong> Linear transponders (SSB/CW) reveal tuning differences better than FM cubesats.
        Steep, fast passes show Doppler effects more clearly than shallow ones. Archive passes you are happy with
        (rename the CSV) so you can use them as baselines later.
      </div>

      <h2>Chart overlay legend (comparison)</h2>
      <ul>
        <li><strong>Solid lines</strong> — Primary pass (first loaded)</li>
        <li><strong>Dashed lines</strong> — Comparison pass</li>
      </ul>
      <p>
        If dashed lines sit close to solid lines, both passes tracked similarly. Divergence near TCA usually
        means your settings change affected behaviour on the fast leg.
      </p>

      <h2>Exporting and logging</h2>
      <p>
        Doppler pass logs are plain CSV files. You can copy them for archiving, open them in a spreadsheet,
        or delete old logs to save space. Each filename encodes the satellite and UTC start time, for example:
        <code>RS-44-26-06-22-13-46-doppler.csv</code>
      </p>

      <h2>See also</h2>
      <ul>
        <li><a href="radio-doppler-tuning.html">Doppler tuning settings</a> — thresholds, lead, and adaptive mode explained</li>
        <li><a href="radio-rotator.html">Radio &amp; rotator</a> — general CAT setup</li>
        <li><a href="troubleshooting.html">Problems?</a> — if the window does not load or logs are missing</li>
      </ul>
    </main>

    <footer>OscarWatch — help for satellite operators</footer>
  </div>
</body>
</html>