Repository navigation
Expand file tree
/
Copy pathsettings.html
More file actions
352 lines (327 loc) · 25 KB
/
Copy pathsettings.html
File metadata and controls
352 lines (327 loc) · 25 KB
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
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
<!DOCTYPE html>
<html lang="en-GB">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Settings — 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>Settings</h1>
<p class="tagline">Station, TLE source, tracking, voice, recording, hardware, and integrations</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 & sidebar</a></li>
<li><a href="frequencies.html">Frequencies</a></li>
<li><a href="satellites.html">Satellites & TLEs</a></li>
<li><a href="passes.html">Pass planning</a></li>
<li><a href="radio-rotator.html">Radio & rotator</a></li>
<li><a href="settings.html" aria-current="page">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>Open from the menu: <strong>Settings</strong>. Press <strong>Save</strong> when finished. Settings are stored in <code>%AppData%\OscarWatch\settings.json</code> on Windows, or <code>~/.config/OscarWatch/settings.json</code> on Linux and macOS.</p>
<h2>Station</h2>
<p>Your operating position: display name (for labels in pass tools), latitude, longitude, Maidenhead grid, and height above sea level in metres. The grid square is normalised to uppercase as you type. Accurate height helps slightly with geometry; position is essential for passes and az/el.</p>
<p>
The display name is shown in pass planner, mutual pass, visualisers, and calendar export — for example “Home” or “Portable”.
It is not your on-air callsign. For logging identity, set <strong>My callsign</strong> on each
<a href="qso-logbook.html">OscarWatch Logbook</a> when you create it.
</p>
<p id="station-horizon-mask">
<strong>Horizon mask</strong> (optional) — open <strong>Edit horizon mask…</strong> to draw your local skyline
(trees, buildings, hills) on a polar editor: click to add points, drag to move, right-click to remove, or edit the az/el table.
An empty mask means unused; pass prediction and plots still use <strong>Tracking → Minimum elevation</strong> alone.
When points are set, visibility at each azimuth uses the higher of the mask and that minimum.
The mask does not command the rotator; that is <strong>Rotator → Start tracking at elevation</strong>.
The same mask is stored per station profile (Settings and Pass planner) and is drawn on the sky plot and pass polar plots.
</p>
<h2>TLE</h2>
<p>
Choose where pass times and orbital positions come from. The transponder frequency database is separate — see
<a href="satellites.html#transponder-database">Transponder database</a>.
</p>
<ul>
<li><strong>OscarWatch (tle.oscarwatch.org)</strong> — default AMSAT-oriented JSON GP catalogue (recommended).</li>
<li><strong>AMSAT.org (JSON GP bulletin)</strong> — daily bulletin from <a href="https://newark192.amsat.org/gpdata/current/daily-bulletin.json">newark192.amsat.org</a>.</li>
<li><strong>Custom URL</strong> — any HTTP(S) address that returns JSON GP elements or classic three-line TLE text (for example Celestrak amateur-group TLEs with <code>FORMAT=json</code> or <code>FORMAT=tle</code>).</li>
<li><strong>Local file</strong> — browse to a <code>.json</code>, <code>.txt</code>, or <code>.tle</code> file on your PC; use <strong>Browse…</strong> to pick it.</li>
<li><strong>TLE updates</strong> — when to download fresh data automatically (OscarWatch and custom URLs only). Local files are re-read when you save Settings or use <strong>Satellites → Refresh TLEs</strong>.</li>
</ul>
<p>
Changing the source and pressing <strong>Save</strong> reloads the catalogue. The status bar shows which source is active
(for example “TLE 2 h ago (tle.oscarwatch.org)”).
</p>
<h2>Tracking</h2>
<ul>
<li><strong>Minimum elevation</strong> — passes below this angle are hidden from predictions and from the <a href="map-and-sidebar.html#pass-elevation-timeline">pass elevation timeline</a> below the map. When a <a href="#station-horizon-mask">horizon mask</a> is set, each azimuth uses the higher of the mask and this value.</li>
<li><strong>Prediction hours</strong> — how far ahead to compute passes.</li>
<li><strong>Check for transponder database updates on startup</strong> — downloads <a href="https://tle.oscarwatch.org/satellite_database.json">tle.oscarwatch.org/satellite_database.json</a> when the app opens and offers to merge new satellites/modes (on by default). Use <strong>Satellites → Update transponder database…</strong> to check manually.</li>
</ul>
<h2>Appearance</h2>
<p>Settings are grouped into <strong>Locale & time</strong>, <strong>Map</strong>, <strong>Theme</strong>, and <strong>Updates</strong>.</p>
<h3>Locale & time</h3>
<p><strong>Language</strong> — <strong>English (UK)</strong> is the default UI language (British English spelling and <code>en-GB</code> date/time formatting). Japanese, Portuguese (Brazil), Simplified Chinese, and Spanish are also available. A language change requires restarting OscarWatch.</p>
<p><strong>Clock format</strong> — 12-hour (AM/PM) or 24-hour for times in the app.</p>
<p><strong>Times shown in</strong> — <strong>local time</strong> (your PC time zone) or <strong>UTC</strong> for the main window: status clock, sidebar pass list, pass elevation timeline, hams.at roves, and sunlight prediction. <strong>Pass planner</strong> and <strong>mutual pass</strong> have their own local/UTC control so you can check UTC there without changing this setting. Satellite tracking always uses UTC internally.</p>
<h3>Map</h3>
<p><strong>Show footprint motion arrows</strong> — optional arrows inside satellite footprints on the world map indicating ground-track direction (on by default).</p>
<p><strong>Show day/night greyline on map</strong> — shades the night side of Earth and draws the terminator; footprints stay on top. Follows map time when you scrub.</p>
<p><strong>Show next-orbit ground track</strong> — faded line for the focused satellite's next orbit behind the current track on the world map (on by default).</p>
<p><strong>Map centre longitude</strong> — Greenwich (default mid-Atlantic view), your station gridsquare, or a custom longitude (−180° to 180°). Footprints and tracks wrap at the map edges in all modes.</p>
<h3>Theme</h3>
<p>Light, dark, or follow the OS setting. The sky plot follows the theme; the world map image stays light for readability.</p>
<h3>Updates</h3>
<p><strong>Check for application updates</strong> — compares your version with the latest release on GitHub on startup and daily while running. You can also check manually from <strong>Help</strong>.</p>
<h2>Voice</h2>
<p>Optional spoken alert when a satellite rises above a set elevation (e.g. “Alpha Oscar Zero Seven is rising”). Choose a voice and test it. On Linux, install <code>espeak-ng</code> (recommended) or legacy <code>espeak</code>; <code>speech-dispatcher</code> with <code>spd-say</code> is also supported if eSpeak is not installed.</p>
<h3>Scheduled passes</h3>
<p>
Mark specific passes as <strong>Scheduled</strong> in Upcoming Passes or Pass Planner.
While OscarWatch is running, each scheduled pass can play a ding and show an alert window
a configurable number of minutes before AOS. Use <strong>Test sound</strong> to check the ding.
The ding is the same generated tone on Windows, macOS, and Linux (system player, ffmpeg, or
PortAudio as available). This is separate from voice rising announcements (which follow elevation
for all enabled satellites).
</p>
<h2 id="recording">Recording</h2>
<p>
Optional automatic audio capture from a line-in or USB audio device while you work a pass.
Open <strong>Settings → Recording</strong> to configure it.
</p>
<ul>
<li><strong>Enable automatic pass recording</strong>: turn recording on or off.</li>
<li><strong>Input device</strong>: choose the audio input that carries your radio audio (sound card line-in, USB interface, etc.). The selection is remembered by device name across restarts (USB cards often change PortAudio index after reboot). Press <strong>Refresh</strong> if you plug in hardware after opening Settings; re-select only if the OS renames the device or it is missing from the list.</li>
<li><strong>Sample format</strong>: mono 44.1 kHz is a good default for FM/SSB; stereo if your interface requires it.</li>
<li><strong>File format</strong>: WAV (always works) or MP3. MP3 needs <a href="#ffmpeg"><code>ffmpeg</code> installed</a> so OscarWatch can find it on your PATH. Capture is still WAV first; OscarWatch converts when the pass ends and deletes the intermediate WAV on success. If ffmpeg is missing or conversion fails, the WAV is kept.</li>
<li><strong>Start / stop elevation</strong>: recording begins when the <strong>focused</strong> satellite rises through the start elevation, and stops when it falls below the stop elevation. Keep stop at or below start to avoid flapping near the threshold.</li>
<li><strong>Output folder</strong>: leave blank to use the default (<code>%APPDATA%\OscarWatch\recordings</code> on Windows, <code>~/.config/OscarWatch/recordings</code> on Linux, <code>~/Library/Application Support/OscarWatch/recordings</code> on macOS).
Pass recordings are kept until you delete them; OscarWatch does not auto-prune audio files.
Settings shows the current file count and total size for that folder, with an <strong>Open folder</strong> button.
You can also use <strong>Help → Open recordings folder</strong>.</li>
<li><strong>Test recording (5 s)</strong>: saves a short clip so you can confirm levels and device selection before a pass.</li>
</ul>
<p>
Other Settings tabs open immediately. The <strong>Recording</strong> tab loads audio devices when you select it.
On some FlexRadio setups with <strong>DAX</strong> virtual audio devices, PortAudio can hang or fail while
<strong>SmartSDR for Windows</strong> is running (OscarWatch itself talks to the radio over the API, not via that GUI).
OscarWatch checks audio in a separate probe process first so a DAX failure does not close the main application.
If the Recording tab reports that audio is unavailable, configure recording with SmartSDR for Windows closed, or use <strong>Refresh</strong> on the Recording tab after closing DAX streams you do not need.
</p>
<p>
Files are named in UTC: <code>{satellite-name}-{yy-MM-dd-HH-mm}.wav</code> or <code>.mp3</code>
(for example <code>so-50-26-05-24-14-30.wav</code>).
Only the satellite you have <strong>selected</strong> on the map or pass list is recorded.
If you switch to another satellite that is already above the start elevation, recording begins straight away.
While recording, a red <strong>REC</strong> badge appears on that pass in the sidebar.
</p>
<p>WAV files are uncompressed (~5 MB per minute mono at 44.1 kHz). MP3 is much smaller when ffmpeg is available.</p>
<h3 id="ffmpeg">Installing ffmpeg for MP3 recordings</h3>
<p>
OscarWatch does not bundle ffmpeg. You only need it if you choose <strong>File format → MP3</strong>.
After installing, close and reopen OscarWatch (or reopen Settings → Recording) so it can see ffmpeg on your PATH.
The Recording tab should say that ffmpeg was found.
</p>
<p>
Check that it worked by opening a terminal and running <code>ffmpeg -version</code>.
You should see version text, not “command not found”.
</p>
<h4>Windows</h4>
<ol>
<li>Open <strong>Windows PowerShell</strong> (Start menu → type <code>PowerShell</code> → Open).</li>
<li>Run:
<pre><code>winget install ffmpeg</code></pre>
</li>
<li>If winget asks you to agree to source or package terms, accept them.</li>
<li>Close PowerShell, then fully quit and restart OscarWatch.</li>
<li>Optional check: in a <strong>new</strong> PowerShell window, run <code>ffmpeg -version</code>.</li>
</ol>
<p>
If <code>winget</code> is not available on older Windows builds, install
<a href="https://apps.microsoft.com/detail/9nblggh4nns1">App Installer</a> from the Microsoft Store,
or use <a href="https://chocolatey.org/">Chocolatey</a> with <code>choco install ffmpeg</code>.
</p>
<h4>macOS</h4>
<ol>
<li>Install <a href="https://brew.sh/">Homebrew</a> if you do not already have it (the brew.sh site shows the one-line install command).</li>
<li>Open <strong>Terminal</strong> and run:
<pre><code>brew install ffmpeg</code></pre>
</li>
<li>Quit and restart OscarWatch, then open Settings → Recording and confirm ffmpeg is found.</li>
<li>Optional check: run <code>ffmpeg -version</code> in Terminal.</li>
</ol>
<h4>Linux</h4>
<p>Use your distribution’s package manager (examples):</p>
<ul>
<li><strong>Debian / Ubuntu / Mint</strong>:
<pre><code>sudo apt update
sudo apt install ffmpeg</code></pre>
</li>
<li><strong>Fedora</strong>:
<pre><code>sudo dnf install ffmpeg</code></pre>
</li>
<li><strong>Arch</strong>:
<pre><code>sudo pacman -S ffmpeg</code></pre>
</li>
</ul>
<p>
Then restart OscarWatch and confirm Settings → Recording reports that ffmpeg was found.
Optional check: <code>ffmpeg -version</code> in a terminal.
</p>
<h2>Rotator & Radio</h2>
<p>
See <a href="radio-rotator.html">Radio & rotator overview</a> for rig type and wiring;
<a href="linux-serial.html">Linux serial ports</a> if <code>ttyUSB</code> numbers change after reboot;
<a href="radio-doppler-tuning.html#doppler-cat-thresholds">Doppler thresholds</a> (FM vs SSB/CW ballpark values),
<a href="radio-doppler-tuning.html#passband-knob">resume CAT after you spin the dial</a>,
<a href="radio-doppler-tuning.html">adaptive and lead</a>, and
<a href="rotators.html">rotator options</a>.
</p>
<p>
<strong>Serial port</strong> — on Windows, pick the COM port from Device Manager. On Linux and macOS, pick or
type the device path (for example <code>/dev/serial/by-id/…</code> or a udev alias such as
<code>/dev/USB821H</code> or <code>/dev/ttyICR9K</code>). Press <strong>Refresh</strong> after plugging in USB. Each radio, rotator, and
serial GPS must use a <strong>different</strong> port.
</p>
<p>
Under <strong>Radio</strong>, <strong>Linear CW: keep receive in USB/LSB (transmit CW only)</strong> controls how CAT and Cloudlog
set modes when the frequency panel is on <strong>CW</strong> for linear SSB satellites (see <a href="frequencies.html">Frequencies</a>).
</p>
<h2>Integrations</h2>
<p>
The <strong>Integrations</strong> tab groups optional hardware and external services:
<strong>GPS</strong>, <strong>hams.at</strong> Upcoming Roves,
<strong>OscarWatch</strong>, <strong>Cloudlog</strong>, <strong>QRZ</strong>, <strong>HamQTH</strong>, and
<strong>Satellite link</strong>.
Pick a section from the list on the left.
</p>
<h3 id="gps">GPS</h3>
<p>
Choose <strong>Serial (COM port)</strong> for a USB or serial GPS on its own port (not shared with the radio or rotator),
or <strong>gpsd (network)</strong> when a <a href="https://gpsd.io/" target="_blank" rel="noopener">gpsd</a> daemon on your LAN
(for example on a Raspberry Pi) already manages the receiver.
</p>
<ul>
<li><strong>Enable GPS</strong> — turn GPS integration on or off.</li>
<li><strong>Connection</strong> — <strong>Serial</strong> reads NMEA <strong>GGA</strong> / <strong>RMC</strong> sentences; <strong>gpsd</strong> uses the JSON watch stream on TCP port <strong>2947</strong> (host + port configurable).</li>
<li><strong>Serial port / baud rate</strong> — when using serial, match the GPS (often <strong>4800</strong> or <strong>9600</strong> 8N1). Press <strong>Refresh</strong> if the port list is stale. On Linux, prefer a stable <code>by-id</code> or udev path — see <a href="linux-serial.html">Linux serial ports</a>.</li>
<li><strong>gpsd host / port</strong> — hostname or IP of the machine running gpsd (often <code>127.0.0.1</code> on the same PC, or your Pi’s LAN address).</li>
<li><strong>Refresh status</strong> — shows connected / waiting for fix / fix with lat/lon and satellite count.</li>
<li><strong>Apply fix to station</strong> — copies the current fix into <strong>Settings → Station</strong> (latitude, longitude, grid, and optionally altitude).</li>
<li><strong>Automatically update station position from GPS fix</strong> — keeps your QTH in sync while roving (saves periodically).</li>
<li><strong>Update altitude from GGA</strong> — when auto-update is on, applies height from the GGA sentence.</li>
<li><strong>Use GPS UTC for satellite tracking</strong> — pass predictions and live tracking use GPS time instead of the PC clock. Does <strong>not</strong> change the Windows system clock.</li>
<li><strong>Use GPS time for FT4 slot timing</strong> (on by default): while the GPS has a fix, FT4 compares
GPS time with the PC clock. If the PC is more than a quarter of a second out, the
<a href="ft4.html#clock-source">FT4 window</a> times its slots from GPS instead. Useful in the field with no
internet time sync. Does <strong>not</strong> change the Windows system clock.</li>
<li><strong>Minimum satellites for fix</strong> — ignore fixes with fewer satellites in view (default 3).</li>
</ul>
<p>
With GPS enabled, the <a href="map-and-sidebar.html#status-bar">status bar</a> shows
<strong>GPS</strong> in <strong>green</strong> when a fix is active and <strong>red</strong> when GPS is on but there is no fix.
If <strong>Use GPS UTC</strong> is checked, <strong>GPS Time</strong> appears the same way (green when tracking is using GPS UTC).
</p>
<h3>hams.at</h3>
<p>
Enable the integration, paste your hams.at API key (Bearer token), and set how often roves refresh.
Your key is stored locally in <code>settings.json</code> like other credentials. Use
<strong>Test connection</strong> to verify the key. Set your observer location on
<a href="https://hams.at/location" target="_blank" rel="noopener">hams.at</a> so
<code>is_workable</code> alerts match your station.
</p>
<h3>OscarWatch</h3>
<p>
Enable reporting, set the base URL (default <code>https://oscarwatch.org</code>), and paste an API token
from <a href="https://oscarwatch.org" target="_blank" rel="noopener">oscarwatch.org</a>
<strong>Settings → API tokens</strong>. Your website profile must include a
<strong>callsign</strong> and <strong>gridsquare</strong> before reports are accepted.
Use <strong>Test connection</strong> to call <code>GET /api/v1/me</code>.
When enabled, the frequency overlay shows a <strong>Report</strong> button so you can submit
On / Off / Telemetry only for the focused satellite and selected mode.
Optionally enable <strong>Automatically report On when logging a QSO</strong>: each new live QSO
posts an On report using the QSO time and the focused satellite’s catalogue mode
(edits do not re-report). Manual and automatic reports require elevation of at least
<strong>−1°</strong>.
When the integration is enabled, OscarWatch also fetches public community status
(no API token required for reading): a chip on the frequency overlay for the selected mode,
and a colour dot on Upcoming Passes rows (tooltip lists each mode). Offline or failed fetches
hide those indicators without blocking tracking.
OscarWatch FT4 can send decode spots with this same API token. The OscarWatch tick on the FT4 settings Reporting page stays unavailable until the token is saved. Spot sending does not need satellite status reporting to be turned on.
</p>
<h3>Cloudlog</h3>
<p>
If you use <a href="https://github.com/magicbug/Cloudlog">Cloudlog</a>, enter your server URL and API key.
Click <strong>Test connection</strong> after both fields are filled — OscarWatch loads your available
logbooks (logbooks must have a <strong>public slug</strong> in Cloudlog) and shows a
<strong>Logbook</strong> dropdown. Pick the logbook to use for grid lookups on hams.at roves.
</p>
<p>
While tracking, OscarWatch posts current satellite uplink/downlink frequencies to the
Radio API when they <strong>change</strong>, and repeats the same state on a
<strong>keepalive interval</strong> (default 10 minutes). Configure
<strong>Radio name</strong> and keepalive below the logbook.
Use <strong>Test connection</strong> before relying on live updates in the field.
</p>
<p>
<strong>Highlight grids I still need on hams.at roves</strong> (shown when a logbook is selected)
checks each rove grid against that logbook using Cloudlog’s <code>logbook_check_grid</code> API with
<code>band: SAT</code>, so only satellite QSOs count. Grid badges on rove rows are described in
<a href="map-and-sidebar.html#rove-grid-badges">Map & sidebar → Rove grid badges</a>.
</p>
<h3>QRZ</h3>
<p>
Optional callbook lookup for <a href="qso-logbook.html">OscarWatch Logbook</a>.
Enable it, enter your QRZ username and password, then use <strong>Test connection</strong>.
Credentials are stored locally in <code>settings.json</code> like other API keys.
Filling first names from QRZ uses the
<a href="https://www.qrz.com/page/xml_data.html">QRZ XML Data</a> service, which needs a QRZ
XML subscription. Lookups run after you type a complete callsign; they do not overwrite a name
you already typed or one recalled from a previous QSO in that logbook. Timeouts and missing
records fail quietly so logging stays fast.
</p>
<p>
The same username, password, and enable switch are also on
<strong>OscarWatch Logbook → Settings → QRZ</strong>.
</p>
<h3>HamQTH</h3>
<p>
Optional fallback callbook for OscarWatch Logbook. A free
<a href="https://www.hamqth.com/developers.php">HamQTH XML</a> account is enough
(no paid subscription). Enable it, enter your HamQTH username and password, then use
<strong>Test connection</strong>. When QRZ is off, misses a call, or is not configured,
OscarWatch asks HamQTH for the operator’s first name or on-air nickname, and, if Grid is empty, their locator.
The same fields are on <strong>OscarWatch Logbook → Settings → HamQTH</strong>.
</p>
<h3 id="satellite-link">Satellite link</h3>
<p>
Broadcast focused satellite name, frequencies, modes, and tracking data to logging applications over a local WebSocket.
This replaces the legacy SatPC32 DDE interface for third-party software.
Full operator and developer documentation is in <a href="satellite-link.html">Satellite link</a>.
</p>
<ul>
<li><strong>Enable</strong> — starts the WebSocket server (default port <strong>7373</strong>).</li>
<li><strong>Allow connections from local network</strong> — off = this PC only; on = any LAN client. On Windows, allow OscarWatch when the system firewall prompt appears.</li>
<li><strong>Only broadcast when satellite is above horizon</strong> — sends <code>** NO SATELLITE **</code> when elevation ≤ 0°.</li>
<li><strong>Update interval</strong> — throttle for unchanged payloads (default 1 s); focus/mode changes are immediate.</li>
</ul>
<p>
The <a href="map-and-sidebar.html#status-bar">status bar</a> shows <strong>Sat link</strong> when enabled
(waiting, client count, or error).
</p>
</main>
<footer><a href="index.html">Back to help home</a></footer>
</div>
</body>
</html>