Skip to content

Add the first receiver

RF Sentry identifies a physical RTL-SDR by its programmed USB serial. Never build operational configuration around -d 0, -d 1, or a transient USB bus address.

Resolve duplicate factory serials before expecting deterministic routing.

Discover the hardware

With the intended hub port enabled and the receiver attached:

rtl_eeprom
lsusb
sdr-demandctl status

If more than one RTL-SDR is visible, correlate the new serial using the configured USB hierarchy and serial inventory. Do not infer identity from enumeration order. Program a unique serial before adding configuration if the receiver has a duplicate factory value.

Inventory file

Create /etc/rtl_tcp/SERIAL.conf from a reviewed repository profile. The fields below describe the synthetic aviation receiver in profiles/example. Substitute verified hardware identity, ports and RF policy before use:

SERIAL=90000003
PORT=1236
BACKEND_PORT=11236
BIND=127.0.0.1
ACCESSORIES=
ALIAS=adsb1
DETAIL="adsb1_5dBi_dual-band_1090_978"
  • SERIAL is immutable hardware identity.
  • PORT is the stable public demand-proxy endpoint.
  • BACKEND_PORT is private loopback transport to that receiver's transient rtl_tcp instance.
  • ALIAS is the short operational identity shown to operators.
  • DETAIL describes the antenna/path.
  • ACCESSORIES lists named dependencies such as an upconverter power path.

Route policy

The inventory states what hardware exists. A route states where RF can flow. The corresponding example route refers to the same serial. Verify the range and RF path on your own hardware before setting VERIFIED=yes:

ROUTE_ID=adsb1-direct
SERIAL=90000003
PATH_PROFILE_ID=adsb1-5dbi-dual-band-direct
LABEL="ADSB1 · 5 dBi dual-band 1090/978 · direct"
PURPOSES=manual,scan,decode,monitor
RF_MIN_HZ=30000001
RF_MAX_HZ=1765900000
TUNER_MIN_HZ=24000000
TUNER_MAX_HZ=1766000000
NET_TRANSLATION_HZ=0
PRIORITY=100
POWER_COST=10
RELEASE_MS=10000
HYSTERESIS_HZ=250000
ENABLED=yes
VERIFIED=yes

Translated paths use NET_TRANSLATION_HZ; RF Sentry keeps operator RF, hardware tuner frequency, and displayed/VFO frequency distinct. Mark a route VERIFIED=yes only after the physical path and translation have been tested.

Receiver-specific frequency gaps belong in separate route policies. For example, the synthetic E4000 SATCOM profile exposes 52–1085 MHz and 1249–2173 MHz routes rather than pretending the PLL gap is usable.

Lifecycle

stateDiagram-v2
    [*] --> Sleeping
    Sleeping --> Waking: lane requests public port
    Waking --> Inventory: enable parent/domain/port
    Inventory --> Backend: verify exact serial
    Backend --> Active: start serial-keyed rtl_tcp
    Active --> IdleGrace: last client closes
    IdleGrace --> Active: client returns
    IdleGrace --> Sleeping: clean close and logical disable
    Sleeping --> DeepIdle: all receivers idle

The public proxy holds the client socket while the exact receiver wakes. A serial-aware supervisor kills stale rtl_tcp instances on hot unplug and waits quietly for that same serial to return. One receiver disappearing must not disturb another.

Validate and activate the new receiver

Check the installed demand and gateway configurations first. These commands read the inventory, USB dependencies, routes and spur masks without opening receiver connections:

sudo /usr/local/sbin/sdr-demandd --check-config
sudo /usr/local/sbin/rfsentry-api --config /etc/rfsentry/api.conf --check

The two services read receiver inventory at startup. A systemd unit-file reload alone leaves the running inventory untouched. Schedule a maintenance window: check sdr-demandctl status and sudo rfsentry-jobctl list, let interactive clients disconnect, and account for a gap in enabled jobs. Restarting the gateway also clears its volatile decoded-record buffer.

sudo systemctl stop rfsentry-api.service rfsentry-decoder.service
sudo systemctl restart sdr-demand.service
sudo systemctl start rfsentry-decoder.service rfsentry-api.service
sdr-demandctl status
sudo rfsentry-jobctl list

Reconnect the browser and find the new alias in the receiver inventory. Start a lane on the reviewed route and confirm that the IQ frame count advances at the requested tuning and sample rate. Release the lane and check that an otherwise unused receiver returns to idle after its configured grace period. An enabled job or a second client can legitimately keep acquisition active. Inspect the corresponding backend journal with journalctl -u "rtl_tcp@SERIAL.service", substituting the configured serial.