Samoyed
Samoyed is a soundcard modem, software TNC and NET/ROM node for amateur packet radio, written in Go.
It supports AX.25 v2.2, FX.25, IL2P, APRS, 300-9600 bps AFSK, PSK and G3RUH modems, digipeating, IGates, KISS and AGW interfaces, a web dashboard, Prometheus metrics, and more.
Samoyed started as a Go port of Dire Wolf.
Documentation: https://doismellburning.github.io/samoyed/
Status: Port functionally complete, but broad testing needed - consider this pre-release, and likely to contain bugs.
The automated tests run against audio files and loopback rather than real radios, so reports are most useful on:
on-air use with real soundcards and radios;
PTT methods (serial RTS/DTR, CM108, GPIO, hamlib);
macOS;
and interoperability with other TNCs and with KISS/AGW applications.
Please file issues if you encounter problems - or if it works, which is worth knowing too.
Why Samoyed?
Dire Wolf, by John Langner WB2OSZ, is a mature, capable piece of software written in C:
a modern software replacement for hardware TNCs, with outstanding receive performance.
It decodes over 1000 error-free frames from the
WA8LMF TNC Test CD,
outperforming all hardware TNCs and first-generation soundcard modems.
Those are Dire Wolf's results: Samoyed's demodulators are ported from Dire Wolf's, but Samoyed doesn't publish figures of its own yet.
Samoyed started as a near-straight port to Go, and has since moved on: much of the code has been reworked, and it has features of its own. The port was motivated by:
- Better tooling — Go's testing, linting, and static analysis ecosystem, as well as the stdlib
- Simpler builds — no cmake, no preprocessor conditionals for test infrastructure
- Reduced platform scope — dropping old Windows / old CPU complexity makes the codebase easier to extend
- Easier contribution — idiomatic Go and improved test suites should make things more approachable for new contributors
Samoyed aims for broad-strokes compatibility with Dire Wolf to minimise switching costs.
Features
Samoyed inherits Dire Wolf's feature set:
- APRS encoder/decoder — position, objects, messages, telemetry, weather, and more
- Modems — 300 bps AFSK (HF), 1200 bps AFSK (VHF/UHF), 2400 & 4800 bps PSK, 9600 bps GMSK/G3RUH, AIS, EAS SAME
- FX.25 — Forward Error Correction fully compatible with existing AX.25 systems
- IL2P — Improved Layer 2 Protocol with lower overhead FEC
- KISS interface — TCP/IP, serial port, and Bluetooth
- AGW network interface — TCP/IP, compatible with many third-party applications
- Digipeater — APRS and traditional packet radio, with flexible cross-band and filtering options
- Internet Gateway (IGate) — bridging disjoint radio networks via the internet
- GPS tracker beacons — SmartBeaconing support
- APRStt gateway — DTMF tone sequences into the APRS network
- AX.25 v2.2 connected mode — automatic retransmission and in-order delivery
- DTMF decoding and encoding
- Morse code generator
- DNS Service Discovery — network KISS TNC auto-discovery (Linux)
- Concurrent operation with multiple soundcards and radio channels
As well as that, Samoyed also adds:
- IL2P CRC — support for IL2P's Cyclic Redundancy Check for improved packet reconstruction, per the IL2P Specification Draft v0.6
- BPSK — 300 and 1200 bps Binary Phase Shift Keying, compatible with the NinoTNC's BPSK modes for AX.25 and IL2P alike (
MODEM 300 BPSK or MODEM 1200 BPSK, with IL2PTX for IL2P, which sends the CRC by default)
- RTL-SDR input — receive up to two frequencies from one dongle through
rtl_tcp, FM demodulated by Samoyed itself, with no soundcard or rtl_fm (see Receive from an RTL-SDR)
- UDP audio output — stream encoded audio to a remote host via UDP (
ADEVICE default udp:host:port) for testing and experimentation
- YAML configuration — an alternative to the line-at-a-time format, for configuration files named
*.yaml or *.yml
- Config checking —
--config-check reports every problem in a configuration file without starting up
- Web interface — a live dashboard and APRS map in the browser (
WEBPORT)
- Prometheus metrics — a
/metrics endpoint (METRICSPORT), with a starter Grafana dashboard in conf/
- AGW login — require a user name and password on the AGW port (
AGWLOGIN)
- NET/ROM node —
NODES broadcasts, learned routes and multi-hop circuits, optionally behind a node shell that users connect to by callsign or alias (see Run a NET/ROM node)
- AXUDP —
samoyed-axudp bridges a KISS port to remote nodes speaking AX.25 over UDP (RFC 1226)
- KISS ACKMODE — a KISS client can ask for each frame to be acknowledged once it has actually been transmitted, as Winlink Express's
ACKMODE TNC model does
Installation
Pre-built binaries are available on the GitHub Releases page, including tarballs and .deb packages.
The .deb packages are recommended for Debian-based systems (Debian, Ubuntu, Raspberry Pi OS, etc.) and can be installed with:
sudo apt install ./samoyed-binary_*.deb
Quick start
samoyed-direwolf is the modem/TNC itself.
It reads a configuration file — direwolf.conf in the current directory, or whatever --config-file names.
A minimal one for a single 1200 bps channel on Linux, in Samoyed's YAML format (for a file whose name ends in .yaml or .yml):
samoyed:
audioDevices:
# Your soundcard - see `arecord -l`
- input: plughw:1,0
channels:
- channel: 0
# Your callsign
mycall: Q1TEST
modem:
speed: "1200"
agwPort: 8000
kissPorts:
- port: 8001
That is equivalent to this, in Dire Wolf's format, which works too:
# Your soundcard - see `arecord -l`
ADEVICE plughw:1,0
CHANNEL 0
# Your callsign
MYCALL Q1TEST
MODEM 1200
AGWPORT 8000
KISSPORT 8001
Check it, then start it:
samoyed-direwolf --config-file samoyed.yaml --config-check
samoyed-direwolf --config-file samoyed.yaml
Run samoyed-direwolf --help for the full list of options.
Dire Wolf's companion utilities come along too, each prefixed samoyed- (samoyed-atest, samoyed-kissutil and so on), with man pages in the .deb.
For configuration, features and recipes, see the Samoyed documentation, in particular the how-to guides.
Where it doesn't yet cover something, the Dire Wolf documentation should — Samoyed aims for broad compatibility with Dire Wolf.
Switching from Dire Wolf
- Configuration — an existing
direwolf.conf should work as it is; check it with samoyed-direwolf --config-file direwolf.conf --config-check
- Command names — every program is prefixed
samoyed- (direwolf becomes samoyed-direwolf, atest becomes samoyed-atest), so Samoyed can be installed alongside Dire Wolf
- Command-line options — Dire Wolf's single-letter options still work, and each has a long form too (
-c is also --config-file)
- Service setup — the
.deb installs the programs and their man pages only, so bring your own configuration file and systemd unit
Building
Prerequisites
Go, plus a handful of system packages (PortAudio and friends).
Hamlib isn't needed to build - it's loaded at run time, and only CAT PTT needs it installed.
On apt-based Linux and on macOS with Homebrew, make setup installs them for you; otherwise see
dev-setup.sh for the package lists.
Build
git clone https://github.com/doismellburning/samoyed
cd samoyed
make setup # install build/test/lint dependencies
make cmds # build all binaries into dist/
make all # build and test everything
See CONTRIBUTING.md before sending a change.
AGENTS.md - written for people as much as for agents - lists the main make targets, along with general development notes and style guidelines.
Contributing
See CONTRIBUTING.md.
Platform Support
| Platform | Status |
|---|
| x86_64 Linux | Primary target |
| arm64 Linux | Supported |
| macOS | Supported |
| Windows | TBD (depends on demand / testability) |
Further Reading
License
Samoyed as a whole is distributed under the terms of the GNU Affero General Public License, version 3 or later.
Samoyed's own work is AGPL-3.0-or-later.
Code derived from Dire Wolf remains available under Dire Wolf's GPL-2.0-or-later as well, so those files are GPL-2.0-or-later AND AGPL-3.0-or-later;
GPLv3's section 13 is what lets the two be combined.
See LICENSES/ and REUSE.toml for per-file details.
The Samoyed logo is CC-BY-SA-4.0.
The name and logo are also covered by the trademark policy: modified versions should rebrand.
Samoyed is a fork of Dire Wolf — see AUTHORS.md for authorship and attribution.
