01Overview
Rootless Podman pod that shares the RTL-SDR dongle two ways:
┌──────────── rtlsdr pod ────────────┐
RTL-SDR ──USB── rtl_tcp :1234 ──────┤──> sdr-gateway :8073 (WebSocket) │
│ └──────────────────┬─────────────────┘
SDR++ / GQRX / SDR# (LAN only) │ host.containers.internal:8073
│
Internet ─> Cloudflare ─> cloudflared ─> nginx /sdr/ ──┘ (raydynamics-web pod)
nginx / ──> ~/rayshack/html/sdr.html + sdr.js
- rtl_tcp (
:1234) serves raw IQ to desktop SDR apps. It has no authentication, so the firewall only allows it from the LAN (and ZeroTier, whose interfaces are in the trusted zone). - sdr-gateway (
rtlsdr/sdr_gateway.py) connects to rtl_tcp and does all the DSP on the server: one shared 2048-bin waterfall, plus a private WFM, NFM, AM, USB or LSB receiver for each web listener, streamed as 24 kHz mu-law audio. That is about 20 kB/s per viewer and 45 kB/s per listener, which is small enough for the Cloudflare tunnel. - sdr.html in
~/rayshack/htmlis the client (Projects ▸ Amateur Radio ▸ Web SDR).
rtl_tcp only serves one client at a time. The gateway connects only while someone has the web page open (plus 10 s). When nobody does, desktop apps can use rtl_tcp; while a desktop app has it, the web page shows “tuner busy”.
02Files
| File | Purpose |
|---|---|
rtlsdr.pod | Pod; publishes 1234 (rtl_tcp) and 8073 (gateway) |
rtl-tcp.container | rtl_tcp with the USB bus passed in; bound to /dev/rtlsdr0 |
sdr-gateway.container | The gateway; receiver settings live here (ppm, defaults, limits) |
rtlsdr/Containerfile | Image for both containers (localhost/rtlsdr:latest) |
rtlsdr/sdr_gateway.py | Gateway source; the wire protocol is documented at the top |
raydynamics-web-nginx.conf | nginx config with the /sdr/ WebSocket proxy (owned by raydynamics-web) |
install-rtlsdr.sh / uninstall-rtlsdr.sh | Deploy / remove |
03Install
./install-rtlsdr.sh # as your normal user; it asks for sudo when needed
The install script runs these steps:
- Enables linger.
- Builds the image.
- Installs and validates the quadlets.
- Writes
/etc/modprobe.d/rtlsdr-blacklist.confto keep the DVB-T TV driver off the dongle. - Writes
/etc/udev/rules.d/70-rtlsdr.rules. The rule makes your user own the dongle, creates/dev/rtlsdr0, and startsrtl-tcpon plug-in. - Allows 1234/tcp from
10.0.0.0/24. - Starts the pod.
- Updates nginx with the
/sdr/proxy. It runsnginx -tfirst, then asks before restarting the web server.
Re-run it after changing any of these files.
04Design notes
- SELinux: confined containers can't open USB devices. Only
rtl-tcpruns withSecurityLabelDisable=true, which is equivalent to running rtl_tcp as your user. The internet-facing gateway stays confined, and the globalcontainer_use_devicesboolean is left off. - Hot-plug:
rtl-tcp.servicehasBindsTo=dev-rtlsdr0.device. Unplugging stops it. Plugging back in starts it with a fresh container, so it sees the new USB device node. - Why 8073 isn't on 127.0.0.1: with pasta networking,
host.containers.internalfrom the nginx container reaches the host's LAN address, not loopback. - CPU: the gateway uses a shared overlap-save FFT channelizer, so an extra listener costs about 1 ms per 50 ms block. Listeners on the same frequency and mode share one demodulator. On this i3-4010U, 12 SSB listeners take about 20 ms per block; WFM costs more (about 8 ms per listener).
journalctl --user -u sdr-gatewaylogs the DSP time every minute.
05Everyday operations
systemctl --user status rtlsdr-pod sdr-gateway rtl-tcp
journalctl --user -u sdr-gateway -u rtl-tcp -f
curl -s localhost:8073/sdr/status # gateway, direct
curl -s localhost:8080/sdr/status # through nginx
systemctl --user restart sdr-gateway # after editing settings + daemon-reload
Calibrate the frequency error: tune a known signal (a NOAA station or a local repeater) in NFM, note how far its peak sits from the marker, set SDR_PPM in sdr-gateway.container, and re-run the installer. The correction in ppm is offset (Hz) / frequency (MHz).
HF (0.5–24 MHz): SDR_DIRECT_SAMPLING=2 feeds the antenna straight into the RTL2832's ADC (Q branch), bypassing the R820T tuner; no upconverter needed. The gateway switches it on whenever the span centre is below 24 MHz, and turns on the RTL2832 digital AGC with it, because strong AM broadcast stations otherwise clip the samples. The RF gain control has no effect in that mode. Sensitivity is modest; a long wire or HF antenna helps a lot more than on VHF. Desktop apps on rtl_tcp have their own “direct sampling: Q branch” setting.
06Troubleshooting
- “Tuner busy”: a desktop app is connected to rtl_tcp. Close it, and the page reconnects within a few seconds.
- “Offline”: rtl_tcp isn't running. Check
ls -l /dev/rtlsdr0andjournalctl --user -u rtl-tcp.usb_claim_interface error -6means the DVB driver grabbed the dongle; re-plug it, or reboot, with the blacklist in place. - “Unreachable”: nginx can't reach the gateway. Check
sdr-gatewayand that the web server has the/sdr/proxy (curl localhost:8080/sdr/status). - Stopping rtl-tcp takes 3 s: expected. rtl_tcp hangs on exit after serving a client, so
StopTimeout=3kills it.
07Uninstall
./uninstall-rtlsdr.sh
The uninstall script removes the pod, quadlets, udev rule and firewall rule. It asks before removing the driver blacklist and the image. The nginx proxy and sdr.html stay; the page then shows the receiver as offline.