diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md index dd12f00..0ce9bb1 100644 --- a/docs/HARDWARE.md +++ b/docs/HARDWARE.md @@ -73,8 +73,34 @@ Nooelec NESDR SMArt v5 RTL2832U + R820T, USB ID 0bda:2838, serial 33999948 ``` -Quirk (EXPERIMENTALLY VERIFIED): the R820T PLL can wedge ("PLL not -locked"), after which captures contain gain-independent white noise on any -frequency. A USB reset (`usbreset 0bda:2838`) recovers it. The HIL runner -resets the dongle before each session. Suspected trigger: `rtl_test -t`'s -direct-sampling probe. Avoid `rtl_test -t` in automation. +### Observer reliability (EXPERIMENTALLY VERIFIED) + +This dongle is not a stable instrument and every measurement must record +its state. Three distinct failure modes were observed and characterised: + +1. **Sensitivity drift.** Within minutes of continuous streaming the tuner + loses roughly 17 dB. Measured with `hil/sdr_health.py`: fresh after + replug ~ +22 dB mean power at 42.1 dB gain and ~51 dB spectrum span; + after a few minutes ~ +5 dB and ~19 dB span. Captures at "the same + gain" taken minutes apart are therefore NOT comparable. +2. **Tuner death mid-stream.** `r82xx_write: i2c wr failed` appears and the + receiver goes deaf, but `rtl_sdr` does NOT exit -- it keeps producing + nothing. A naive long capture silently returns "no traffic". Observed at + ~192 s into a 1800 s capture. Mitigation: bounded capture segments with + `-n` plus `usbreset` between them (`hil/capture_both.sh`). +3. **Descriptor / enumeration faults.** The device can enumerate with empty + descriptor strings (`rtl_test` prints `0: , , SN: `) or disappear from + the bus entirely, in which case `usbreset` reports "No such device + found" and only a physical replug recovers it. Discovery therefore + identifies the dongle by USB VID:PID 0bda:2838, not descriptor text. + +`usbreset 0bda:2838` recovers modes 1-3 as long as the device is still +enumerated. Kernel `over_current_count` stayed 0 throughout, so the port +never tripped protection; the dongle's own controller hangs. + +Note: "[R82XX] PLL not locked!" printed while tuning is BENIGN -- it is +emitted while `rtl_sdr` probes and disables direct-sampling mode, and +appears on both rtl-sdr-blog and osmocom builds. An earlier revision of +this document blamed `rtl_test -t` for wedging the tuner; that was +DISPROVEN. The real symptom of a deaf receiver is railed, gain-independent +noise, which is what `hil/sdr_health.py` tests for. diff --git a/tools/discover_devices.sh b/tools/discover_devices.sh index c4081a3..7549b25 100755 --- a/tools/discover_devices.sh +++ b/tools/discover_devices.sh @@ -22,15 +22,38 @@ fi DUT_PORT="${dut_candidates[0]}" [ -e "$DUT_PORT" ] || fail "DUT path vanished: $DUT_PORT" -# --- SDR: Nooelec NESDR SMArt v5 (RTL2832U) --- -# rtl_test -t enumerates devices without streaming. +# --- SDR: Nooelec NESDR SMArt v5 (RTL2832U, USB 0bda:2838) --- +# Identity is established by USB VID:PID, because this dongle sometimes +# enumerates with empty descriptor strings after a fault (rtl_test then +# prints "0: , , SN: "). A usbreset restores them, but discovery must not +# fail on it. Ambiguity (more than one RTL dongle) is still fatal. +if command -v lsusb >/dev/null 2>&1; then + usb_count=$(lsusb 2>/dev/null | grep -c '0bda:2838' || true) +else + # sysfs fallback: works without usbutils + usb_count=0 + for v in /sys/bus/usb/devices/*/idVendor; do + [ -r "$v" ] || continue + p="${v%idVendor}idProduct" + [ "$(cat "$v" 2>/dev/null)" = "0bda" ] && + [ "$(cat "$p" 2>/dev/null)" = "2838" ] && + usb_count=$((usb_count + 1)) + done +fi +[ "${usb_count:-0}" -eq 0 ] && fail "no RTL2832U (0bda:2838) on the USB bus" +[ "${usb_count:-0}" -gt 1 ] && fail "ambiguous SDR: $usb_count RTL2832U devices present" + sdr_list=$(timeout 10 rtl_test -t 2>&1 | grep -E '^\s+[0-9]+:' || true) -[ -z "$sdr_list" ] && fail "no RTL-SDR device found (rtl_test)" -sdr_matches=$(echo "$sdr_list" | grep -i "Nooelec" || true) -[ -z "$sdr_matches" ] && fail "RTL-SDR present but not a Nooelec: $sdr_list" -[ "$(echo "$sdr_matches" | wc -l)" -gt 1 ] && fail "ambiguous SDR: $sdr_matches" +[ -z "$sdr_list" ] && fail "RTL2832U on USB but librtlsdr cannot enumerate it" +[ "$(echo "$sdr_list" | wc -l)" -gt 1 ] && fail "ambiguous SDR: $sdr_list" +sdr_matches="$sdr_list" SDR_INDEX=$(echo "$sdr_matches" | sed -E 's/^\s*([0-9]+):.*/\1/') -SDR_SERIAL=$(echo "$sdr_matches" | sed -E 's/.*SN: ([^ ]+).*/\1/') +SDR_SERIAL=$(echo "$sdr_matches" | sed -E 's/.*SN: ([^ ]*).*/\1/') +[ -z "$SDR_SERIAL" ] && SDR_SERIAL="unknown(descriptor_fault)" +if ! echo "$sdr_matches" | grep -qi "Nooelec"; then + echo "DISCOVER_WARN: RTL dongle descriptors unreadable ($sdr_matches);" \ + "identified by VID:PID 0bda:2838" >&2 +fi echo "DUT_PORT=$DUT_PORT" echo "SDR_INDEX=$SDR_INDEX"