Linux serial ports

On Linux, USB serial adapters often appear as /dev/ttyUSB0, /dev/ttyUSB1, and so on. After a reboot those numbers can swap. OscarWatch can use stable paths instead — the same approach many operators already use with udev rules.

Prefer a genuine FTDI USB–serial adapter (or the radio’s own USB port). Cheap Prolific clones are a common cause of flaky CAT — see USB serial adapters.

What OscarWatch supports

Under Settings → Radio, Settings → Rotator, and Settings → Integrations → GPS (serial mode), the serial port field lets you:

Select from a refreshed list of ports.
Type a device path directly (for example /dev/USB821H).

On Linux, pressing Refresh also lists:

/dev/serial/by-id/* — stable names from the kernel (recommended if you do not use custom udev rules).
/dev/serial/by-path/* — stable names tied to the USB socket.
Custom udev symlinks under /dev/ that point at a serial device (for example /dev/USB821H or /dev/ttyICR9K).

When several names refer to the same physical port, the list shows one preferred entry (custom alias first, then by-id, then kernel names such as ttyUSB0). 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.

Windows and macOS: use the COM port or /dev/cu.* name as before. You can still type a path if your environment exposes one. This page focuses on Linux because ttyUSB numbering is the usual pain point.

Recommended: pick a stable path in Settings

Plug in the radio, rotator, or GPS.
Open the right Settings tab and press Refresh.
Choose a by-id entry or your udev alias — or type the path — then press Save.
Give each device its own port (radio, rotator, and GPS must not share one).

Settings are stored in ~/.config/OscarWatch/settings.json (or your XDG config directory). The saved value is the literal path string, for example "port": "/dev/USB821H".

Custom udev alias (optional)

If you already use udev rules to create friendly names, OscarWatch works with them. A typical rule might create /dev/USB821H for a specific radio adapter. Example shape (adjust ATTRS{serial} and names for your hardware):

# /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"

After adding or changing rules:

sudo udevadm control --reload-rules
sudo udevadm trigger
ls -l /dev/USB821H

Then in OscarWatch, select or type /dev/USB821H and save.

Permissions (`dialout`)

Your user must be allowed to open the serial device. On Debian, Ubuntu, Raspberry Pi OS, and similar distributions, add yourself to the dialout group, then log out and back in:

sudo usermod -aG dialout $USER

For Arch based distributions, Manjaro, CachyOS, you need to be in the uucp group.

If OscarWatch reports the port is busy or access is denied, check that no other program holds the port (Hamlib, gpsd on the same tty, another CAT app) and that ls -l shows your user or group can read the device.

GPS on Linux

Serial GPS — same stable-path advice as the radio; use by-id or a udev alias on its own port.
gpsd — under Settings → Integrations → GPS, choose gpsd (network) so gpsd owns the receiver and OscarWatch reads fixes over TCP (default port 2947). Useful on a Raspberry Pi or when you already run gpsd for other tools.

Troubleshooting

Port not found after reboot — you probably saved /dev/ttyUSB0 instead of a stable path. Refresh, pick by-id or your alias, save again.
Alias missing from the list — type the full path manually; OscarWatch still saves and uses it. Confirm ls -l /dev/your-alias points at the right ttyUSB or ttyACM device.
Worked yesterday, wrong radio responds — two devices may have swapped ttyUSB numbers; switch to per-device by-id or udev names.