1. Introduction

Overview

NR-Scope receives signals from the standalone 5G base station and decodes the DCIs, where it decodes master information block (MIB) and system information block 1 (SIB 1) and tracks UEs' RACH procedure to decode the RRC setup message for cell's configuration. After the RACH procedure, it acquires the valid C-RNTI of the UE and decodes both uplink and downlink downlink control information (DCI) with the RNTI. In the meantime, it keeps monitoring new UEs during the session and tries to decode all the SIBs from the cell. Data in NR-Scope will go through the following processings.

• Radio samples reception and synchronization. NR-Scope tunes its antenna to the frequency and bandwidth indicated in the config.yml file, and tries to find the PSS and SSS through correlation according the standards. Resampling will be activated when using better-fidelity Twin-RX USRP daughterboard.

• Master information block (MIB) decoding. After the PSS and SSS are detected, NR-Scope tries to decode the MIB payload which contains initial information about the cell and indicates the time and frequency domain of the SIB 1.

• System information block (SIB) decoding. With the information from MIB, NR-Scope tries to decode the SIB 1 from the cell. MIB and SIB 1 are the minimal information that the UE should get from the cell to start RACH. SIB 1 also contains the information for other SIBs, NR-Scope will keep decoding these SIBs.

• Message 4 (RRC Setup) decoding. When a UE tried to connect to the cell, there will be message 1 (UL, PRACH), 2 (DL, RAR), 3 (UL RRC Setup Request), 4 (DL, RRC Setup), NR-Scope tries to decode message 4 for the RRC Setup message and the valid C-RNTI of the UE.

• Threaded DCI decoding. With RRC Setup and C-RNTIs, NR-Scope can decode all the uplink and downlink DCIs of UEs on a per-TTI basis. Separate threads will spawn for BWPs with id > 1.

• DCI logging. NR-Scope will log DCIs from different USRPs into different files, also we provide an API to push the DCIs to google BigQuery dataset in real time indexed with date time and geographical location (longitude and latitude).

Output Format

NR-Scope will put all the information that DCIs can provide into a .csv file if there are any inside that slot. One example is listed below, followed by a brief explanation.

timestamp	system_frame_index	slot_index	rnti	rnti_type	dci_format	k	mapping	time_start	time_length	frequency_start	frequency_length	nof_dmrs_cdm_groups	beta_dmrs	nof_layers	n_scid	tb_scaling_field	modulation	mcs_index	transport_block_size	code_rate	redundancy_version	new_data_indicator	nof_re	nof_bits	mcs_table	xoverhead	harq_id	downlink_assignment_index	tpc	pucch_resource	harq_feedback	bwp	ports	carrier_index
1726687692.86056	244	13	17921	C-RNTI	0_1	4	A	0	14	4	24	2	1.412538	1	0	0	QPSK	9	4224	0.663086	0	1	3168	6336	64qam	0	0	3	1	0	0	0	0	2

• timestamp: the time that the radio samples are captured for this slot.
• system_frame_index: system frame number of 5G, each contains 10 ms of data.
• slot_index: slot index of 5G, each could be 1 ms (0-9, 15kHz SCS), 0.5 ms (0-19, 30kHz SCS), 0.25 ms (0-39, 60kHz SCS) for FR1 bands.
• rnti: radio network temporary identifier (RNTI) of the user equipments (UEs). RNTI is a temporary identifier allocated to UEs when they connect to the network, which will change each time the UE reconnects.
• rnti_type: type of the received RNTI, now it's mostly C-RNTI, which is used for data communication.
• dci_format: 1_1 or 1_0 for downlink DCI, 0_1 for uplink DCI.
• k: the data should be received/sent after k slots from now, in the example, it's an uplink DCI, scheduling data to be sent 4 slots later.
• mapping: resource mapping type, there are two types of mappings, type A and type B. Please refer to this link for more detailed explanation.
• time_start: starting symbol of the scheduled data within the slot (14 symbols in total for one slot).
• time_length: how many symbols should the data use for sending/receiving.
• frequency_start: starting resource block (RB) of the scheduled data (total number of RBs are defined in SIBs or RRC Setup).
• frequency_length: how many RBs should the data use for sending/receiving, we can calculate the total number of resource elements (REs) and their location with the above four values.
• nof_dmrs_cdm_groups: DeModulation Reference Signal (DMRS) group number, each group of DMRS will take a group of RBs in the PDSCH with different intervals. This value tells how many groups we should expect in the coming data or how should the UE schedule the uplink DMRS in the PUSCH.
• beta_dmrs: DMRS beta value, it's how the DMRS sequence is mapped to the physical resource blocks, please refer to the "Mapping to Physical Resource" in this link.
• nof_layers: number of MIMO layers used for this data transmission.
• n_scid: DMRS scrambling parameter, it's used to calculate the DMRS sequence, please refer to "Sequence Generation" in this link.
• tb_scaling_field: used for transport block scaling when the physical resource is scheduled through DCI 1_0 and P-RNTI, or RA-RNTI. Please refer to Table 5.1.3.2-3 in TS38.214 for detailed description.
• modulation: modulation that this data transmission is used, such as 256QAM, QPSK, etc.
• mcs_index: modulation scheme (MCS) index in the MCS table, usually 0-27/28 the higher the more bits are carried within one RE, meaning the channel condition is better.
• transport_block_size: number of bits that are scheduled for actual packet data.
• code_rate: the code rate from the MCS scheme, equals to nof_bits/transport_block_size.
• redundancy_version: redundancy version used for retransmission. When a transmission (or retransmission) takes place, the original data bits are encoded using a specific Forward Error Correction (FEC) scheme(e.g, LDPC). The encoded bits are then punctured or rate-matched to create a set of output bits for transmission. The redundancy version determines which bits are selected for transmission, and different RVs will result in different sets of bits being sent. Please refer to this link for more detailed description.
• new_data_indicator: one bit of data used to indicate whether this tranmission is a new transmission or a re-transmission of previous lost one. If the new data indicator (NDI) has the same value as the previous one with the same HARQ id, the data tracked by this HARQ id is re-transmitted. If the NDI has different value as the previous one with the same HARD id, the data is new data.
• nof_re: number of resource elements that are scheduled through this DCI.
• nof_bits: number of total bits transmitted over the RBs, including the data and overhead of the physical channel.
• mcs_table: which MCS table is used to map the mcs_index to specific modulation type and code rate.
• xoverhead: overhead of the slot, how many bits are used not for the data, used in transport block calculation (more details here).
• harq_id: Hybrid ARQ index, each HARQ id is to track one transmission, if the transmission is successful, the NDI will flip the next time to mark the success data transmission. Or else the data is re-transmitted.
• downlink_assignment_index: indexes from all of the transmitted (scheduled) downlink data(PDSCH) which is bundled to one HARQ ACK/NAC transmission.
• tpc: transmission power control index, please check this link for how to calculate the actual transmission power with this index.
• pucch_resource: For a DCI scheduling multiple PDSCHs, a single PUCCH resource is indicated by PUCCH resource indicator and corresponding multiple HARQ-ACK bits are multiplexed on the indicated single PUCCH, where HARQ-ACK feedback timing is determined by applying PDSCH-to-HARQ_feedback timing indicator from the last scheduled PDSCH.
• harq_feedback: harq feedback timing, this value indicates when the hard feedback should be sent.
• bwp: bandwidth part (BWP) id that the data is scheduled, 5G has up to 4 BWPs and each time a UE would only use one BWP.
• ports: ports field in DCI field, which is used to calculate the downlink or uplink MIMO configuration, combined with dmrs_type and dmrs_max_length. Please refer to this link for more detail.
• carrier_index: If the UE is configured with carrier aggregation, this index is to identify this cell's carrier index configured to the UE.

RACH Log

NR-Scope will log the detected RACH as a separate .csv file, with the file name being the configured DCI file name + _rach. For example, if the configured DCI file name is a.csv, the RACH log will be a_rach.csv. In this RACH log, each detected RACH behavior will be stored in a row with the timestamp, system_frame_index, slot_index, and rnti.

Features

Current NR-Scope supports the following features:

1. Supports 5G SA cells with 15kHz and 30kHz SCS, tested with 10MHz, 20MHz, 40MHz and 100MHz cell bandwidth.
2. Carrier aggregation decoding, NR-Scope would use one SDR to try to decode both carrier aggregated and not carrier aggregated UEs within the RAN. Tested in commercial T-Mobile 15MHz FDD and 100MHz TDD cells.
3. 5G SA cell search and MIB decoding.
4. SIB 1 and all other SIBs decoding.
5. RRCSetup (MSG 4) decoding for continuously UE attatch detection.
6. Threaded DCI decoding for detected UEs.
7. SIB, RRCSetup and DCI decoding are threaded for performance and independent processing.
8. Can concurrently decode up to 64 UEs (max number we can create with groundtruth) in the same base station. In T-Mobile cell, we can decode up to hundreds of UEs.
9. Accurate DCIs, PRB and bit rate estimation for each UEs.
10. Local logging functions in .csv file and remote google BigQuery uploading function in BigQuery table.
11. Support using multiple USRPs to decode multiple base stations independently, each has its own log.
12. Cell search for all possible frequencies in a separate file and the results are stored in .csv log file.
13. Non-initial (BWP id > 0) and plaintext (configured in SIB 1 or MSG 4) BWPs decoding in separate DCI decoder threads.
14. Threaded resampling function for better-fidelity TwinRX USRP X310 daughterboard (better signal quality but doesn't support 5G sampling rate without resampling).
15. Worker pool function is implemented. Each worker works on the slot data asynchronously. Now the processing doesn't need to keep up with the short slot time, and the throughput is increase through more workers.
16. Band list can be configured for cell scan functions.
17. A circular buffer is used for slot data dispatch among workers, now the CPU/worker number requirement is largely reduced.
18. PCI can be configured in the config.yaml. If configured, NR-Scope will proceed only if the detected cell's PCI matches what is configured.
19. Stay tuned... 😄

Roles

Professor Kyle Jamieson is the supervisor of this project. Haoran Wan implemented the foundation functionalities of this project (from 1 to 11, 15, 17, and 18), and is maintaining the project and reviewing the new pull request code. Xuyang Cao added new features onto the project (12 to 14) and is working on new features, such as hidden (configured in encrypted RRC Reconfiguration) BWP decoding. Thank @johst-source for adding the bandlist support for cell scan functions.

Citation

If you use NR-Scope, please cite:

@inproceedings{10.1145/3680121.3697808,
  author = {Wan, Haoran and Cao, Xuyang and Marder, Alexander and Jamieson, Kyle},
  title = {NR-Scope: A Practical 5G Standalone Telemetry Tool},
  year = {2024},
  isbn = {9798400711084},
  publisher = {Association for Computing Machinery},
  address = {New York, NY, USA},
  url = {https://doi.org/10.1145/3680121.3697808},
  doi = {10.1145/3680121.3697808},
  booktitle = {Proceedings of the 20th International Conference on Emerging Networking EXperiments and Technologies},
  pages = {73–80},
  numpages = {8},
  keywords = {5G network, network measurement, telemetry, wireless network},
  location = {Los Angeles, CA, USA},
  series = {CoNEXT '24}
}

And please reference this DOI link: https://doi.org/10.1145/3680121.3697808 for more detailed 5G PHY and MAC layer logic in NR-Scope.