rf_sentinel / hardware / internals
How the external hardware works
What RF Sentinel does with each radio you plug in, down to sample rates, frame formats and thresholds. Every number here is a constant in the public source; file names point at the Kotlin classes under app/src/main/java/com/rfsentinel/app/. Which hardware to buy is on External hardware.
- Ground rules
- SDR basics
- RTL-SDR driver
- HackRF One
- Network SDR (rtl_tcp)
- Modes, turns and the waterfall
- Radio activity sweep
- Cellular uplink
- TETRA bursts
- P25 control channel
- P25 voice (experimental)
- ADS-B aircraft
- USB WiFi monitor mode
- USB Bluetooth
- ESP32 boards over USB
- OUI-Spy over Bluetooth
- V2X emergency vehicles
- Sentinel Link and Meshtastic
- Limits
- Questions
Ground rules
- Receive only. Only the features whose job is to send (Sentinel Link, Meshtastic, and an OUI-SPY board relaying every network, which sends probe requests) transmit. No driver here does: the HackRF's transmitter, amplifier and antenna bias stay off, the rtl_tcp bias-T is set off, the WiFi drivers have every transmit path removed (no injection, no deauth, no handshake or PMKID capture), and USB Bluetooth never advertises or connects.
- No root, no kernel driver. Every USB device is driven from the app through Android's USB host API (
UsbManager, control and bulk transfers). Android asks you once per device for permission. - No decryption. Encrypted P25 calls, WPA traffic and TETRA are never decoded. Radio scanning measures energy, timing and clear signalling only.
- Nothing leaves the phone unless you turn on something that says so (RadioReference lookups, Sentinel Link, Meshtastic).
SDR basics
An SDR (software-defined radio) is a tuner plus an analogue-to-digital converter: it hands the app a stream of I/Q samples, pairs of numbers that describe the amplitude and phase of everything within a slice of spectrum around the tuned frequency. The app does all filtering and decoding in software (sdr/SdrRadio.kt).
| Setting | Value |
|---|---|
| Sample rate | 2.048 MS/s (2 MS/s for ADS-B), so each tune sees about 2 MHz of spectrum |
| Gain | Fixed 29.7 dB for sweeps and P25; 49.6 dB (the tuner's maximum) for ADS-B. No AGC, so levels are comparable over time |
| USB read | 16 KB (8192 complex samples), about 4 ms of signal each; 8 reads per tuned chunk (16 for TETRA, to see whole frames) |
| Stalled stream | After 8 empty chunks the stream is reset, as librtlsdr's reset_buffer does |
| Unplug detection | The device is checked every couple of seconds; a USB SDR plugged in takes over from a network SDR |
Driver messages go into each piece of hardware's own log (Settings › External hardware › Export a hardware log, or Export all hardware logs for one file), without positions.
RTL-SDR driver
sdr/RtlSdr.kt is a Kotlin port of osmocom's librtlsdr (GPL-2.0-or-later) for the RTL2832U demodulator chip with an R820T, R820T2, R860 or R828D tuner.
- Tuner access: the tuner sits behind the RTL2832U on I²C; every register write goes through the RTL2832U's I²C repeater with 3 retries, and the driver keeps shadow copies of the tuner registers so partial writes don't need a read-back.
- Low IF, not zero IF: the R82xx tuners mix the signal to a 3.57 MHz intermediate frequency, which the RTL2832U shifts back to baseband with spectrum inversion. That avoids the DC spike zero-IF tuners put in the middle of the spectrum.
- IF filter chosen to match the sample rate (0.9 to 3.2 MS/s supported).
- RTL-SDR Blog V4: an R828D with a 28.8 MHz crystal and an input band switch; its notch filters are turned off inside the FM and DAB bands as the RTL-SDR Blog code does.
- Gone: after 25 control transfers in a row fail, the dongle is treated as unplugged and released.
HackRF One
sdr/HackRf.kt speaks libhackrf's USB vendor requests, receive only: amplifier off, antenna port power off, sample rate 2 to 20 MS/s. The HackRF sends signed 8-bit I/Q; it is converted to the RTL-SDR's unsigned format so the rest of the code is shared. About 48 KB of samples still in flight after a retune are dropped, so they don't land in the wrong channel.
Network SDR (rtl_tcp)
Settings › RTL-SDR radio › Network SDR reads an RTL-SDR plugged into another device on your WiFi, such as a computer running rtl_tcp (default port 1234 if left out) (sdr/RtlTcp.kt).
- The server first sends a 12-byte header starting with
RTL0(tuner type and gain count). - Each command is 1 byte plus a 32-bit big-endian value:
0x01frequency,0x02sample rate,0x03gain mode,0x04gain,0x08AGC,0x0Ebias-T (always sent as off). - Samples are the same unsigned 8-bit I/Q as over USB, about 5 MB/s of WiFi, so use a fast local network.
- A lost connection is retried every 10 s, and a USB SDR plugged into the phone is used first. rtl_tcp has no password: only run it on a network you trust.
Modes, turns and the waterfall
Settings › RTL-SDR radio has four uses: radio sweep, ADS-B, P25 and pagers. One dongle can only listen to one frequency range at a time, so with more than one ticked the SDR takes turns: 60 s each by default, 30 to 300 s per scan.
The live waterfall (Tools › Radio waterfall, sdr/SdrWaterfall.kt) shows each sweep as one row. Zoom in on a few channels and it switches to a tuned view (4 reads per row, up to about 25 rows per second); the sweep and ADS-B pause while you look. Tune › Listen demodulates the zoomed frequency (AM for aircraft, wide FM for broadcast, narrow FM otherwise) to the media speaker.
Find a remote's frequency hops ten centres where remotes send (300, 303.875, 310, 315, 318, 390, 418, 433.92, 868.35 and 915 MHz), about 60 ms each. A peak counts when it stands 15 dB above the median noise in at least 2 of the look's 15 spectra; peaks within 30 kHz are one signal. The first two rounds, before you press, learn the signals already on the air (sensors, data) and those are never shown. The strongest signal stays on screen for 3 s.
Radio activity sweep
sdr/RadioWatch.kt answers one question: is someone transmitting on a public-safety channel near me? It measures energy only. Nothing is demodulated, unless Play voice transmissions is on: then the first new transmission of a chunk is tuned to (its spectrum peak, not the 12.5 kHz grid) and played, as narrow FM with a squelch, or as P25 voice when the identification listen heard P25. Back to the sweep after 1.5 s of closed squelch (P25: the call's end) or 60 s.
- The tuner steps across each band. Every chunk is cut into 1024-point FFTs with a Hann window, averaged and shifted so 0 Hz is in the middle.
- Only the middle ±800 kHz of each 2 MHz chunk is used (the edges are filtered off), and ±15 kHz around the centre is ignored for DC leakage.
- The spectrum is grouped into 12.5 kHz channels. The noise floor is the median of the chunk; a channel's SNR is its peak above that median.
- A channel at or above the sensitivity (default 30 dB, settable 6 to 50 dB) is a candidate; 12 dB counts as "active" for learning.
- Splatter: a strong transmitter spills into its neighbours, so candidates within 37.5 kHz of each other are merged and only the strongest is kept.
- Busy-channel learning: the last 32 visits of every channel are kept. A channel active on 40 % or more of them (after at least 6 visits) is a busy local channel (a repeater, a paging tower, data) and is never reported. No alerts during the first 6 sweeps, while it learns.
- The same channel alerts again only after 120 s.
| Band | Range | Note |
|---|---|---|
| 700 MHz public safety | 799-805 MHz | Narrowband public-safety channels |
| 800 MHz | 806-813.9 MHz | Mobile and portable transmit side |
| VHF high | 150.8-174 MHz | Shared with business and other users |
| UHF | 450-470 MHz | Shared with business and other users |
Always skipped: MURS, marine VHF, railroad, NOAA weather, FRS / GMRS and paging frequencies, and any range you exclude. Frequencies you add as targets skip the learning and alert straight away. A hit is "a radio transmitted nearby", not "police": VHF and UHF are shared, which is why the default sensitivity is high.
Cellular uplink
Detect cellular transmitters (experimental, off by default). Phones transmit on the uplink half of each LTE band; a sudden crowd of uplink energy around you (many phones, or a vehicle's modem) can be measured without decoding anything. The same sweep looks at about 1.6 MHz slices of the uplink bands 71, 12/17, 13, 14 (FirstNet), 5/26 and part of 4/66, learns each slice's quiet level (a slow average, alpha 0.1) and flags a rise of 8 dB or more. Downlinks (towers) are left out on purpose: they are always on.
TETRA bursts
TETRA (used by police in Europe and elsewhere) is TDMA: a handset transmits in one 14.17 ms slot of a 56.67 ms frame. On the 380-385 MHz handset band (the 390-395 MHz base stations are left out), the app reads 16 USB blocks per tune, measures energy in 2 ms steps and calls a channel TDMA when it is on for runs of 0.5 to 2 slots, quiet at least a third of the time and on no more than 60 %. That rhythm is TETRA's fingerprint; the content is never decoded.
P25 control channel
A P25 trunked system has one control channel that tells radios which voice channel to use for each call. RF Sentinel decodes that signalling (experimental), which shows which talkgroups are active, without listening to calls. The chain follows TIA-102.BAAA and the open-source OP25 project.
- Hunt (
sdr/P25Hunt.kt): sweeps the 769-775 and 851-869 MHz downlinks, tries the strongest channels first and keeps the first one whose messages pass their CRC. No ppm calibration is needed: the demodulator's frequency loop follows the dongle's drift. If nothing is found it tries again after 30 s. - Demodulate (
sdr/P25Demod.kt): mixes the 12.5 kHz channel to 0 Hz, decimates by integrate-and-dump to 48 kS/s, low-pass filters, then an FM discriminator gives the C4FM signal (4 levels, 4800 symbols/s, 2 bits each). The 48-bit frame sync0x5575F5FF77FF(24 symbols) sets symbol timing, the ±3 level and the DC offset. - Frame (
sdr/P25Frame.kt): removes the status symbol after every 35 data symbols, corrects the Network ID with BCH(63,16,23) (up to 11 bit errors), then takes each TSBK block (98 symbols), de-interleaves it, decodes the rate-1/2 trellis code with a Viterbi decoder and checks its CRC. - Messages (
sdr/P25Tsbk.kt): standard (MFID 0) messages only.
| Opcode | Message | Used for |
|---|---|---|
0x00 | Group voice channel grant | A talkgroup got a voice channel: the log entry |
0x02 | Grant update | Calls still running |
0x28 | Group affiliation response | A radio joined a talkgroup |
0x3D, 0x34 | Identifier update | Turns channel numbers into frequencies |
0x3A, 0x3B | RFSS / network status | Site and system identity |
0x3C | Adjacent site | Neighbour sites |
Input check: 400 ms after a grant, at most every 5 s, the app tunes for about 70 ms to the voice channel's input (the frequency the radios transmit on). Energy there means a radio transmitting close to you, not just somewhere on the system.
Talkgroup names (optional, off by default, US only, sdr/RadioReference.kt): with your own RadioReference Premium login and developer key (stored encrypted on the phone), the app looks up the FCC-licensed system around you. It sends a position rounded to about 1 km, at most once a day per area.
P25 voice (experimental)
With Listen to P25 voice (Off, Watched talkgroups or All clear calls), the app follows a clear (unencrypted) call's grant to the voice channel (sdr/P25Follow.kt), one call at a time, and misses control-channel messages meanwhile. It gives up if no voice frame arrives in 1.5 s, ends after 1 s of quiet and stops at 120 s.
- Frames (
sdr/P25Voice.kt): LDU1 / LDU2 frames (840 symbols after the sync) carry nine IMBE codewords each. Each codeword is de-interleaved, error-corrected (Golay(23,12), PN descrambling, Hamming(15,11)) into 88 bits. The algorithm ID must be0x80(clear); any encrypted call is skipped. - Vocoder (
sdr/ImbeDecoder.kt): a Kotlin port of mbelib's IMBE 4400 decoder; each 20 ms frame becomes 160 samples at 8 kHz. A damaged frame repeats the last good one, at most 3 times. - Record P25 voice calls (
sdr/P25Record.kt, for testing): the raw radio signal of a clear call as a 6 s two-channel 16-bit I/Q WAV at 48 kS/s (about 1 MB), at most one every 20 s, the last 20 kept on the phone. Nothing in the file is decoded. - Save played calls (on by default): the decoded speech of each call played, and of each transmission the sweep plays, as a mono 16-bit WAV (8 kHz for P25, the analog audio rate for the rest), named by time and talkgroup or frequency. The last 200 are kept on the phone; P25 talkgroups › Played calls plays and shares them.
Frame layout and tables from DSD and mbelib (ISC). IMBE is a voice coding method of Digital Voice Systems, Inc. Listening to radio voice traffic is illegal in some places: check the law where you are.
ADS-B aircraft
Aircraft broadcast their position on 1090 MHz. sdr/ModeS.kt decodes it at 2 MS/s:
- Finds the 8 µs preamble, then reads 56 or 112 bits of pulse-position modulation (1 µs per bit).
- Checks the 24-bit CRC (polynomial
0xFFF409) and corrects a single bit error in DF17 messages. - Decodes DF11, DF17 and DF18: ICAO address, call sign, altitude, CPR-encoded position and ground speed.
sdr/AdsbTracker.kt turns an even and an odd CPR message into a position, then decodes later ones locally against the aircraft's last position and drops anything beyond 450 km. The aircraft list goes to the police-aircraft check every 2 s, with no internet needed.
USB WiFi monitor mode
In monitor mode an adapter hands over every 802.11 frame it hears, not just its own network's. The app's userspace drivers (usb/, ported from the Linux drivers, Wardrive Go, devourer and mt76; see NOTICE.md) bring the chip up, tune it and read the frames. They follow the Linux drivers' initialisation order.
| Chip | Channels hopped | Dwell per channel |
|---|---|---|
| AR9271 | 2.4 GHz, 1, 6, 11 first | 500 ms |
| RT3070, RTL8187 | 2.4 GHz 1-13 | 350 ms |
| RTL8811AU / 8821AU, RTL8812AU | 1-13, 36-48, 149-165 | 350 ms |
| RTL8814AU | 1-13, 36-48, 149-165 | 125 ms |
| RTL8812BU / 8822BU | 1-13, 36-48, 149-165, DFS 52-144 | 200 ms |
| MT7612U | 1-13, 36-165 including DFS | 125 ms |
| MT7921AU | 2.4 + 5 GHz and the 6 GHz preferred scanning channels (5, 21, 37 ... 229), visited less often unless active | 150 ms |
- Receive loop (
usb/BulkRx.kt): 16 KB asynchronous USB requests (24 queued for RTL88xxAU, 16 for RTL8822BU), with a synchronous fallback, strict frame boundaries and a guard that resets a stream that keeps returning nothing. - Frames read (
usb/MonitorFrames.kt): beacons, probe responses, probe requests and data frames. A beacon's own channel field wins over the tuned channel (adjacent-channel leakage). The beacon timestamp gives "WiFi on since", data bytes are counted, and hidden network names are revealed by probe responses and associations. Results are grouped every 2 s. - Device intel (
usb/ProbeIntel.kt): the WPS block (maker, model, device name, and the UUID-E that links a phone's random addresses), a probe-request fingerprint (order of information elements plus capability fields, 8 hex digits), the FlipDeFlock probe shape and Flock's Wi-Fi Alliance element. - Deauth floods (
usb/DeauthWatch.kt): 25 deauthentication / disassociation frames in 30 s, or a burst in 5 s, spread over at least 3 time slices; protected (802.11w) frames are ignored; one alert per 5 min. - Karma / evil-twin APs (
usb/KarmaWatch.kt): one transmitter answering for 4 or more network names within 60 s; idea from SignalSweep. - Antenna check (
usb/AntennaCheck.kt, after Wardrive Go): holds one reference AP's channel and compares the signal on each antenna chain, with an A / B swap test. It compares received signal, it is not an SWR meter. - Capture (
usb/PcapRecorder.kt): saves frames as a pcap with radiotap headers (link type 127, opens in Wireshark), up to 200 MB. - Firmware: the full build includes the chips' firmware. The F-Droid / FOSS build asks before downloading the non-free files once from linux-firmware (commit e981caea6ed3) and checks each SHA-256. The free ath9k_htc firmware (AR9271) is in both. An MT7612U that says "not calibrated" needs to be unplugged and plugged back in.
USB Bluetooth
A USB Bluetooth dongle, or the Bluetooth side of a MT7921AU / Realtek combo adapter, becomes a second Bluetooth LE scanner (usb/HciUsb.kt), as Linux's btusb drives it: HCI commands as class requests on endpoint 0, events read from the interrupt endpoint. No data (ACL / SCO) channels are opened.
- Realtek (
usb/BtRealtek.kt, after Linux btrtl): reads the chip's LMP subversion and ROM version, then sends the v1 epatch and its config file in 252-byte pieces. The newer RTBTCore chips (RTL8822CU, RTL8852) aren't supported yet. - MediaTek MT7961 (
usb/BtMediatek.kt, after btmtk): WMT patch download and function-on, with a subsystem reset and retry. - Plain CSR or Broadcom dongles need no firmware.
- Scan: passive, duplicates kept, interval 0x60 / window 0x30. Extended scanning on LE 1M and LE Coded (long range) when the controller has it, otherwise the legacy scan. It never connects, pairs or advertises.
ESP32 boards over USB
esp/SerialPort.kt opens the board's USB serial port at 115200 baud, 8N1:
- Native USB (ESP32-S2 / S3 / C3 / C6, FREE-WiLi 2): CDC-ACM, DTR raised.
- CP210x (10C4:EA60): DTR and RTS kept low so the board doesn't reset into its bootloader.
- CH340 / CH341 / CH9102 (1A86:7523, 5523, 55D4).
esp/EspReader.kt then works out which firmware is talking, in this order, and only sends read-only commands:
| Firmware | How it is recognised and read |
|---|---|
| OUI-Spy / Flock You | Streams JSON lines by itself ({"event":"detection",...}, Sky Spy drone lines); the app may ask CMD:VERSION and CMD:DUMP_LIVE |
| V2X2MAP | Its binary ITS5 stream (see V2X) |
| GhostESP | help, then its scan and list commands |
| ESP32 Marauder | help, then sniffbeacon / sniffprobe; also through a Flipper Zero's USB-UART bridge |
| FREE-WiLi 2 | The console's WiFi menu keys and its AP scan only |
OUI-Spy over Bluetooth
The OUI-SPY App-Controlled firmware is driven over Bluetooth GATT (esp/OuiSpyBle.kt): a 128-bit service ending -0a15-4b70-ba00-c010ae1ba01c, MTU 247, reconnect every 8 s if lost. The app turns on the engines it needs (Detector, Flock BLE, Flock WiFi, Sky Spy, survey) and sends DISABLE_ALL (0x0F) when you stop. With relaying on, its survey engine sends standard WiFi probe requests. Detections the board saved while offline arrive as spooled frames (0xFF ... 0xFE). Its attack-style engines (UniPwn, PCAP, Foxhunter) are never used.
V2X emergency vehicles
An ESP32-C5 running V2X2MAP (MIT) listens to 5.9 GHz vehicle-to-everything messages (ETSI ITS-G5). Its USB stream is "ITS5", seconds (u32), microseconds (u32), length (u16), then the raw 802.11 frame, little-endian. esp/V2x.kt finds the GeoNetworking ethertype 0x8947, decodes CAM and DENM messages (ETSI EN 302 637-2 / -3) and lists only emergency vehicles: light bar or siren on, or a DENM warning. The stream has no signal strength, so a nominal −70 dBm is shown.
Sentinel Link and Meshtastic
- Phone to phone (
link/PhoneLink.kt): Bluetooth LE GATT, no system pairing. Phones in a group find each other by a group tag in their advert that changes every 15 min. - Pairing and encryption (
link/LinkCrypto.kt): P-256 ECDH key exchange confirmed by a 6-digit code both screens show (numeric comparison, so a man in the middle shows a different code). Keys come from HKDF-SHA256; each connection uses AES-256-GCM with one key per direction and counter nonces, and replayed messages are refused. - Meshtastic (
link/MeshNode.kt): talks to your Meshtastic node over its phone Bluetooth API and adds a private "RFSentinel" channel keyed from the group key, so only your group can read it. Watchlist matches go first; up to 12 messages wait in the queue, retried every 10 to 120 s. A node serves one app at a time, so close the Meshtastic app. Not yet tested on real hardware.
Limits
- An SDR alert means energy on a channel, not a confirmed police radio. VHF / UHF are shared with businesses, and an encrypted P25 system still shows grants but no voice.
- P25 Phase 2 (TDMA) voice and non-standard (vendor MFID) messages aren't decoded. P25 voice is experimental and untested on many systems.
- One dongle covers about 2 MHz at a time: a band is swept, so a short transmission can be missed while the tuner is elsewhere.
- USB power: an SDR or AC WiFi adapter can draw more than some phones give; use a powered hub or Y-cable if it keeps dropping.
- Monitor-mode WiFi drivers marked experimental (RTL8812AU, AR9271, MT7921AU) may not start on every board revision.
Questions
Does the radio sweep listen to police radio?
Not by default in RF Sentinel. The sweep measures how much energy each 12.5 kHz channel carries. Only the experimental options decode audio: Play voice transmissions (the sweep's new transmissions, analog or unencrypted P25) and Listen to P25 voice (unencrypted trunked calls).
Which SDR should I buy?
For RF Sentinel, an RTL-SDR with an R820T2 or R828D tuner, such as the RTL-SDR Blog V3 or V4. A HackRF One works too but costs more and gives nothing extra here. For ADS-B, a 1090 MHz antenna helps a lot.
Do I need to calibrate the dongle's ppm error?
No. RF Sentinel's sweep works on 12.5 kHz channels wide enough for a dongle's drift, and the P25 demodulator's frequency loop follows the drift itself.
Can I use an SDR that is plugged into my computer?
Yes, RF Sentinel can use one over WiFi: run rtl_tcp -a 0.0.0.0 on the computer and enter its address under Settings › RTL-SDR radio › Network SDR. It needs a fast, trusted local network.
Can the USB WiFi drivers deauth or capture handshakes?
No. In RF Sentinel's USB WiFi drivers every transmit path, and the handshake / PMKID capture of the original drivers, was removed. They only listen.
Sources
- librtlsdr (osmocom, GPL-2.0-or-later): RTL2832U and R82xx tuner driver
- OP25 and TIA-102.BAAA: P25 framing, BCH, trellis and TSBK layout
- DSD and mbelib (ISC): P25 voice frames and the IMBE vocoder
- Linux kernel drivers (rtl8187, rt2x00, ath9k, mt76, btusb, btmtk, btrtl), aircrack-ng rtl8812au, OpenIPC devourer, Network Weather mt76-usb-macos
- Wardrive Go by RocketGod: USB WiFi drivers, FREE-WiLi 2 reader, antenna check idea
- V2X2MAP (MIT), SignalSweep (karma idea), OUI-Spy / Flock You, GhostESP, ESP32 Marauder
Full credits and licences: usb/NOTICE.md and sdr/NOTICE.md.