Troubleshooting

Preserve the first concrete error instead of copying only the final log line. Record the launch command, working directory, active BS.yaml / UE.yaml, and USRP model; these details usually separate configuration, environment, and link problems quickly.

Four checks to start with

1. Confirm that the process working directory contains the intended BS.yaml or UE.yaml.
2. Match radio.radio_backend to the scenario: uhd for a real USRP or sim for simulation.
3. Compare the BS and UE sample rate, FFT/CP, frame length, pilots, frequencies, duplex mode, and resource mapping.
4. Temporarily set the relevant logging.modules entry to info or debug, reproduce once, and inspect the first Warn/Error.

Build fails

Reproduce with the standard build first:

cmake -S . -B build
cmake --build build -j$(nproc)

• During CMake configuration, inspect the first missing package: UHD, Boost, FFTW3, yaml-cpp, ZeroMQ, OpenMP, or Aff3ct.
• During compilation, keep the first compiler error; later messages are often cascading failures.
• After changing compilers, CUDA, or dependency paths, configure a new empty build directory instead of reusing stale CMake state.

Runtime cannot find YAML

BS and UE read fixed filenames from the current working directory; they do not automatically load presets from config/.

cp config/BS_X310.yaml build/BS.yaml
cp config/UE_X310.yaml build/UE.yaml
cd build
./BS

The same working-directory rule applies through sudo and launch helpers. Restart the backend after editing YAML.

USRP is not found or cannot initialize

1. Run uhd_find_devices and confirm that UHD discovers the device.
2. Check usrp_device.device_args and any TX/RX-specific device arguments.
3. For X310, check host NIC addressing, routing, and MTU. For B210, check USB 3, cable quality, and power.
4. If an external clock or PPS is configured, verify that the source is physically present; otherwise validate basic connectivity with internal first.

UHD overflow, underflow, or late packets

• X310: inspect link speed, MTU, packet loss, and competing traffic on the NIC.
• B210: use USB 3 directly and avoid hubs or a shared high-throughput controller.
• For either device, check sustained CPU load and YAML CPU assignments. Lower rf_sampling.sample_rate temporarily to test whether the failure is throughput-related.

UE cannot decode the downlink

Follow the signal chain instead of starting with LDPC tuning:

1. Confirm that the UE finds a synchronization peak and remains locked.
2. Check whether CFO/SFO converges or repeatedly triggers reacquisition.
3. Compare ofdm_frame.*, pilot locations, mid-frame pilots, and resource blocks on BS and UE.
4. Inspect channel estimates and constellation quality before LLR and LDPC diagnostics.
5. On RF hardware, check center frequency, gains, and antenna ports for weak or saturated input.

When repeated ZC synchronization is enabled, a strong ZC peak alone does not identify the main synchronization symbol. The UE checks the preceding repeated ZC and, when configured, the following CFO training field before committing the frame boundary. An incomplete startup preamble is rejected and acquisition continues. Keep these settings identical on BS and UE.

During software or hardware tracking, frames with mismatched configured preamble fields are dropped before demodulation and sensing. Consecutive mismatches lasting sync_tracking.reset_hold_s trigger reacquisition through the existing reset cooldown. A valid preamble clears that failure count. Look for Rejected ZC candidate, Dropping frame with mismatched preamble, or RESET Persistent preamble mismatch in the sync log. A constellation on the real/imaginary axes with normal comb pilots can indicate a whole-symbol frame error and incorrect mid-frame pilot references.

Uplink does not work

Set uplink.enabled: true on both BS and UE, and match uplink.duplex_mode, the TDD symbol window, or the FDD center frequency. With ChannelSimulator, also enable simulation.enable_uplink. If samples arrive but decoding fails, inspect timing windows, channel estimation, equalization, and LDPC in that order.

Sensing output is unstable or incorrect

• Establish stable communication/synchronization first; sensing cannot compensate for persistent frame errors or loss of lock.
• Verify alignment, RF-chain delay, channel calibration, FFT dimensions, and frontend parsing settings.
• Check backend warnings for frame-pair queues, sensing-output queues, or ZMQ high-water-mark drops.
• For bistatic sensing, match sensing.sensing_delay_correction_mode to the active LoS-tracking or eRTM configuration.

When the BS restarts and its air-frame symbol counter moves backwards, the UE resets the bistatic sampling cursor, discards partial batches, and clears MTI and micro-Doppler history. Pending controls move to the new timeline; active STRD, MTI, and FFT settings remain in effect. Look for bistatic timeline restarted in the sensing log. Output resumes after one new sensing batch, without waiting for the new counter to catch up with the previous session.

Visualization window does not update

1. Enable the corresponding network_output.*_enabled switch.
2. Match the viewer IP/port to YAML and allow the TCP port through host firewalls.
3. Run ss -ltnp on the backend host and confirm that the expected endpoint is listening.
4. Check that the backend is producing data and is not continuously dropping frames because of full queues or missing subscribers.

The fast sensing viewer detects a lost control connection and automatically requests fresh parameters after reconnection. It then reapplies saved SKIP, MTI, and STRD controls once; the monostatic viewer also reapplies its saved gains. This includes backend restarts at the same IP and port. Ordinary READY heartbeats do not repeatedly apply those controls. MTI suppresses static reflections, so verify its setting when a static bistatic path disappears.

If the problem remains, retain the complete YAML files, launch commands, logs from startup through the first failure, USRP connection details, and host environment information.