hamlib-sidecar

Generic, modern Hamlib sidecars: bridge any Hamlib backend's IQ / audio sidechannel to whatever your software wants to consume.

Two sidecars, one shared library, plus a small CLI:

Both sidecars include a built-in software-defined-radio receiver and transmitter (SSB / AM / FM mono+stereo / CW), so they can demodulate IQ → audio (RX) and modulate audio → IQ (TX) for whichever radio backend you point them at.

Status

• RX is well exercised. Hundreds of hours on JS8Call via TCI 2.0, plus verified against KiwiSDR (HF AM/SSB/CW + IQ mode) and RTL-SDR (98.5 MHz WFM stereo, 124.3 MHz airband AM, 162.45 MHz NBFM) with live signals.
• TX is implemented but UNTESTED on real RF. Test into a dummy load + spectrum analyzer before transmitting on an antenna. If you verify TX against a real radio, please report back.

Documentation

30-second quick start (Linux)

Bring up the whole pipeline — rigctld, sidecar, virtual audio, and an optional loopback to a real device — with one command:

# RTL-SDR USB dongle, WFM stereo on 98.5 MHz, routed to a USB headset.
# "C-Media" is any unambiguous substring of a PulseAudio sink name.
./hamlib.sh start --radio rtlsdr \
                  --sink C-Media \
                  --freq 98500 --mode WFM 200000

# KiwiSDR over the network, IQ mode (best audio quality)
./hamlib.sh start --radio kiwisdr --host 10.1.0.18 --stream iq \
                  --sink USB --freq 10000 --mode AM 6000

# ExpertSDR3 / SunSDR over TCI 2.0
./hamlib.sh start --radio tci --host 127.0.0.1 --port 50001 --stream audio

Once it's running, drive the radio with hamctl:

./hamctl tune 124300       # tune to 124.3 MHz; auto-applies AM / 6 kHz /
                           # fast AGC because that's in the air band

./hamctl smeter live       # realtime S-meter bargraph (press q to quit)
./hamctl show              # full radio + DSP + audio routing status
./hamctl save morning_nws  # save the current state as a favorite
./hamctl load morning_nws  # re-apply it later
./hamctl bands             # list the band plan

hamctl --help lists every verb. ./hamlib.sh stop tears everything back down.

For non-Linux, for the portable (GNU Radio / SoapySDR) sidecar, and for direct integration with JS8Call / WSJT-X / fldigi / gqrx, see USERS.md.

Install

pip install -r requirements.txt
sudo apt install pulseaudio-utils       # needed for the linux sidecar

Optional, depending on which user-side backends you want to use:

pip install pyzmq                                           # gnuradio backend
sudo apt install python3-soapysdr soapysdr-module-rtlsdr   # soapysdr backend

For development, just run the scripts directly out of the source tree — no install needed.

Files

hamctl writes its favorites and band plan to $XDG_CONFIG_HOME/hamctl/ (typically ~/.config/hamctl/). The band plan is auto-seeded on first use with sensible defaults for HF amateur, SW broadcast, FM broadcast, airband AM, NOAA weather, marine VHF, 2 m / 70 cm, GMRS, and others; edit bands.json to suit.

License

MIT. See LICENSE.