-
-
Notifications
You must be signed in to change notification settings - Fork 7
Expand file tree
/
Copy pathlinux-serial.html
More file actions
147 lines (137 loc) · 7.31 KB
/
Copy pathlinux-serial.html
File metadata and controls
147 lines (137 loc) · 7.31 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
<!DOCTYPE html>
<html lang="en-GB">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Linux serial ports — 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>Linux serial ports</h1>
<p class="tagline">Stable device paths for radio, rotator, and GPS</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">Settings</a></li>
<li><a href="keyboard-shortcuts.html">Shortcuts</a></li>
<li><a href="troubleshooting.html">Problems?</a></li>
</ul>
</nav>
</header>
<nav class="subnav" aria-label="Radio and rotator topics">
<a href="radio-rotator.html">Overview</a> ·
<a href="radio-icom.html">ICOM</a> ·
<a href="radio-yaesu.html">Yaesu</a> ·
<a href="radio-kenwood.html">Kenwood</a> ·
<a href="radio-sdr-dual.html">SDR dual</a> ·
<a href="radio-offsets.html">RX/TX offsets</a> ·
<a href="radio-doppler-tuning.html">Doppler tuning</a> ·
<a href="linux-serial.html" aria-current="page">Linux serial</a> ·
<a href="rotators.html">Rotators</a>
</nav>
<main>
<p class="lead">
On Linux, USB serial adapters often appear as <code>/dev/ttyUSB0</code>, <code>/dev/ttyUSB1</code>, and so on.
After a reboot those numbers can swap. OscarWatch can use <strong>stable paths</strong> instead — the same
approach many operators already use with udev rules.
</p>
<h2>What OscarWatch supports</h2>
<p>
Under <strong>Settings → Radio</strong>, <strong>Settings → Rotator</strong>, and
<strong>Settings → Integrations → GPS</strong> (serial mode), the serial port field lets you:
</p>
<ul>
<li><strong>Select</strong> from a refreshed list of ports.</li>
<li><strong>Type</strong> a device path directly (for example <code>/dev/USB821H</code>).</li>
</ul>
<p>
On Linux, pressing <strong>Refresh</strong> also lists:
</p>
<ul>
<li><code>/dev/serial/by-id/*</code> — stable names from the kernel (recommended if you do not use custom udev rules).</li>
<li><code>/dev/serial/by-path/*</code> — stable names tied to the USB socket.</li>
<li>Custom <strong>udev symlinks</strong> under <code>/dev/</code> that point at a serial device (for example <code>/dev/USB821H</code>).</li>
</ul>
<p>
When several names refer to the same physical port, the list shows one preferred entry (custom alias first,
then <code>by-id</code>, then kernel names such as <code>ttyUSB0</code>). Hover an item in the dropdown to see
the full path. The path you save is what OscarWatch opens — it survives reboots as long as that path still exists.
</p>
<div class="tip">
<strong>Windows and macOS:</strong> use the COM port or <code>/dev/cu.*</code> name as before. You can still
type a path if your environment exposes one. This page focuses on Linux because <code>ttyUSB</code> numbering
is the usual pain point.
</div>
<h2>Recommended: pick a stable path in Settings</h2>
<ol>
<li>Plug in the radio, rotator, or GPS.</li>
<li>Open the right Settings tab and press <strong>Refresh</strong>.</li>
<li>Choose a <code>by-id</code> entry or your udev alias — or type the path — then press <strong>Save</strong>.</li>
<li>Give each device its <strong>own</strong> port (radio, rotator, and GPS must not share one).</li>
</ol>
<p>
Settings are stored in <code>~/.config/OscarWatch/settings.json</code> (or your XDG config directory).
The saved value is the literal path string, for example <code>"port": "/dev/USB821H"</code>.
</p>
<h2>Custom udev alias (optional)</h2>
<p>
If you already use udev rules to create friendly names, OscarWatch works with them. A typical rule might create
<code>/dev/USB821H</code> for a specific radio adapter. Example shape (adjust <code>ATTRS{serial}</code> and
names for your hardware):
</p>
<pre><code># /etc/udev/rules.d/99-oscarwatch-serial.rules
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", \
ATTRS{serial}=="YOUR_SERIAL", SYMLINK+="USB821H", MODE="0660", GROUP="dialout"</code></pre>
<p>After adding or changing rules:</p>
<pre><code>sudo udevadm control --reload-rules
sudo udevadm trigger
ls -l /dev/USB821H</code></pre>
<p>Then in OscarWatch, select or type <code>/dev/USB821H</code> and save.</p>
<h2>Permissions (<code>dialout</code>)</h2>
<p>
Your user must be allowed to open the serial device. On Debian, Ubuntu, Raspberry Pi OS, and similar
distributions, add yourself to the <code>dialout</code> group, then log out and back in:
</p>
<pre><code>sudo usermod -aG dialout $USER</code></pre>
<p>
If OscarWatch reports the port is busy or access is denied, check that no other program holds the port
(Hamlib, <code>gpsd</code> on the same tty, another CAT app) and that <code>ls -l</code> shows your user or
group can read the device.
</p>
<h2>GPS on Linux</h2>
<ul>
<li>
<strong>Serial GPS</strong> — same stable-path advice as the radio; use <code>by-id</code> or a udev alias
on its own port.
</li>
<li>
<strong>gpsd</strong> — under <a href="settings.html#gps">Settings → Integrations → GPS</a>, choose
<strong>gpsd (network)</strong> so <code>gpsd</code> owns the receiver and OscarWatch reads fixes over TCP
(default port <strong>2947</strong>). Useful on a Raspberry Pi or when you already run
<code>gpsd</code> for other tools.
</li>
</ul>
<h2>Troubleshooting</h2>
<ul>
<li><strong>Port not found after reboot</strong> — you probably saved <code>/dev/ttyUSB0</code> instead of a stable path. Refresh, pick <code>by-id</code> or your alias, save again.</li>
<li><strong>Alias missing from the list</strong> — type the full path manually; OscarWatch still saves and uses it. Confirm <code>ls -l /dev/your-alias</code> points at the right <code>ttyUSB</code> or <code>ttyACM</code> device.</li>
<li><strong>Worked yesterday, wrong radio responds</strong> — two devices may have swapped <code>ttyUSB</code> numbers; switch to per-device <code>by-id</code> or udev names.</li>
</ul>
<p>See also <a href="troubleshooting.html#linux-serial">Problems? → Linux serial ports</a>.</p>
</main>
<footer><a href="index.html">Back to help home</a></footer>
</div>
</body>
</html>