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:
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"
SERIALis immutable hardware identity.PORTis the stable public demand-proxy endpoint.BACKEND_PORTis private loopback transport to that receiver's transientrtl_tcpinstance.ALIASis the short operational identity shown to operators.DETAILdescribes the antenna/path.ACCESSORIESlists 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.