7. Usage Recommendations and FAQ

NR-Scope can provide lots of valuable information. While the essential DCIs are saved in the a.csv file, outputs to stdout also offer many insights. For example, help you check whether your NR-Scope or test 5G cell setup is correct.

As suggested in README, instead of running ./nrscope alone, you can do something like

./nrscope | tee ./$(date +"%Y-%m-%d_%H:%M:%S").txt | grep -E 'keyword1|keyword2|keyword3|...' 

So the program stdout will not only be displayed on the fly but also saved in a timestamped file. Also, instead of displaying all the output and getting overwhelmed, you specify keywords in grep arguments so you can focus on key things. A few keywords we often include:

• Found (whenever NR-Scope hears critical signals like SSB, MIB, SIB, user-data DCIs, NR-Scope outputs Found something something...)
• sync (to listen to DCIs just like other UEs, NR-Scope needs to downlink-synchronize with the gNB. After the synchronization achieved, sync will be printed)
• Overflow (Overflow in USRP means the driver is not fetching the sampled points fast enough, and hence some measurements get lost. If NR-Scope is synced and overflow occurs, the synchronization is lost/this NR-Scope run from this point on is wasted. It indicates either the IO or CPU is not fast enough)
• adj (whenever AGC adjusts the rx power, the new value will be printed out. Use this keyword to capture that line. For example, if I saw AGC keeps trying the max rx gain, I know the signal is relatively weak)

Therefore, my command flavor:

./nrscope | tee ./$(date +"%Y-%m-%d_%H:%M:%S").txt | grep -E 'Found|sync|Overflow|adj' 

Of course, lots of interesting information will be printed out in NR-Scope along the way. You can check in codes and stdout and add to your grep.

FAQ:

Q: Why NR-Scope can not hear anything?

A: Please check each of the following (sequentially):

• Are you entering the correct SSB frequency in config.yaml? If it's your own cell, you should know it. If you try to listen to a commercial cell, you can obtain the SSB frequency from some UE diagnostic tools like Cellular-Pro or use our nrscan program. nrscan will do SSB detection on all possible SSB frequency points (i.e., all GSCNs).
• If you try NR-Scope on your own cell, does your cell have enough tx gain?
• If you try NR-Scope on some commercial cell, how far is that cell to the USRP antenna? Does the distance and environment look reasonable?
  • The signal detection capability rank, from our experience, is X310 TwinRX > X310 CBX > B210
• https://www.cellmapper.net/map is a good tool to see cells' rough locations.
• To note, commercial cells are much more "sophisticated". For example, its tx power is very dynamic, or its transmission pattern is "skewed" in terms of direction and particular frequency and time areas. What you might hear on some day might seem gone on another day. UE has many proprietary optimizations (e.g., cached cell configurations and hardware-software co-design) and only needs to focus on its assigned resources. In contrast, NR-Scope with USRPs needs to monitor for all detected UEs, where we tried hard to balance between performance and efficiency.
• Did you see Cell Found but no in_sync change to true to stdout for a long time? This means NR-Scope has a difficult time DL-synced with the gNB. Try to use an external clock source like GPSDO for USRP.
• Please include Found|sync|Overflow as keywords in grep as discussed above. Did any Overflow appear after the in_sync change to true stdout print? If so, the downlink synchronization is gone as sampled points are missed. You will no longer hear anything. Please investigate whether the I/O to USRP and CPU support the monitoring.
  • In config.yaml, you can tune nof_workers to specify how many threads will be allocated for slot processing. A slot is 1ms (say 15KHz SCS). When load is high (e.g., need to check for lots of RNTIs/UEs' DCIs), processing a slot can take more than 1ms. Then the next slot processing will be delegated to another worker/thread, if you have spare. However, too many nof_workers means many overheads in main thread and blocks the time-critical USRP points fetching, resulting in overflow. It's a decision between missing some slot processing and thus flawed results vs overflow and wasted NR-Scope run, again if you have constrained resources.
  • Also you can set cpu_affinity in config.yaml. Personally I found out false actually is better, as sometimes the CPU might not have idle cores. Depending on the architecture, true might be better as it preserves data locality.

Q: Why overflow matters?

A: please see the figure: