View source for 5G OAI End-to-End Reference Architecture with USRP

== Application Note Number and Authors ==

'''AN-598'''

== Authors ==

Bharat Agarwal and Neel Pandeya

==Executive Summary==

This Application Note presents a comprehensive reference design for deploying end-to-end (E2E) 5G NR Stand-Alone (SA) systems using the Eurecom OpenAirInterface (OAI) software stack on the USRP N300, N310, N320, N321, and X410 radios. The USRP B200, B210, B200mini, B206mini, X300, X310 radios can also be used, but with limitations, and are also discussed in this document  The reference design encompasses the base station (gNB), the user equipment (UE), and the Core Network (CN) components of the network, enabling researchers and engineers to build and evaluate full end-to-end deployments.

The reference design offers flexibility in the Core Network deployment. The CN can be installed on the same machine as the gNB, suitable for compact and portable set-ups. Alternatively, the CN can be hosted on a separate machine, allowing for a distributed architecture to facilitate system testing and high-performance operation.

The reference design supports three types of UE.
* The UE implemented using a USRP radio and the OAI UE software stack.
* The UE implemented using a wireless modem module, such as from Quectel or Sierra Wireless.
* The UE implemented using a commercial off-the-shelf (COTS) handset, such as the Google Pixel 9.

The reference design supports operation in Frequency Range 1 (FR1), and a discussion of operation in FR2 (20 to 44 GHz) and FR3 (6 to 20 GHz) will be added at a future date.

This document provides detailed instructions on hardware and software installation, configuration, and execution, alongside expected results, benchmarking methods, performance monitoring, and troubleshooting guidance.

The solution brochure for the OAI Reference Architecture for 5G and 6G Research with the USRP can be downloaded [https://www.ni.com/en/forms/oai-reference-architecture-brochure.html here].

An overview of using OAI Software for 5G and 6G research at this [https://www.ni.com/en/solutions/electronics/5g-6g-wireless-research-prototyping/research-6g-technologies-using-openairinterface-software.html webpage here].

You can learn more about other solutions for 5G and 6G Wireless Research and Prototyping at the [https://www.ni.com/en/solutions/electronics/5g-6g-wireless-research-prototyping.html webpage here].

==Overview of the USRP Hardware==

The Universal Software Radio Peripheral (USRP) devices from NI (an Emerson company) are software-defined radios which are widely used for wireless research, prototyping, and education. The hardware specifications for the various USRP devices are listed elsewhere on this Knowledge Base (KB).

The ideal USRP radios for deploying end-to-end (E2E) 5G systems are the USRP N300, N310, N320, N321, and X410. These radios natively support all the 5G sampling rates used in the 3GPP specifications, and they support all the FR1 channel bandwidths from 5 to 100 MHz.  The 5G systems use standardized sampling rates based on the channel bandwidth and sub-carrier spacing (SCS) (the numerology) to ensure interoperability and efficient signal processing.

For the USRP N300, N320, N321, there should be two 10 Gbps SFP+ Ethernet connections to the host computer, along with one 1 Gbps Ethernet link for the Management Port. On the host computer, a dual-port 10 Gbps Ethernet network card is used to connect to the USRP.

The USRP X410 has two QSFP28 100 Gbps Ethernet ports. There are two options for connectivity to the host computer, depending on what the IQ data rate is (how much bandwidth is needed). The first option is to use a QSFP28-to-4xSFP28 breakout cable on one of the QSFP28 ports. This will provide four 25 Gbps SFP28 Ethernet links. On the host computer, a dual-port SFP28/SFP+ Ethernet network card should be used. The second option is to use one of the two QSFP28 ports directly, with a QSFP28-to-QSFP28 cable, and with a 100 Gbps QSFP28 Ethernet network card on the host computer.

The USRP B200, B210, B200mini, B206mini radios can also be used as the gNB or UE, but with some limitations.  The primary limitation is that you will only be able to operate with a maximum channel bandwidth of 40 MHz.  And even this channel bandwidth may not be possible, depending on what sampling rate is used, and whether the host computer has sufficient resources to support that sampling rate.  The host computer should ideally be able to support the maximum 61.44 Msps, but the sampling rate may be limited to 30.72 Msps, or other non-standard sampling rates such as 42.08 Msps may have to be used as a compromise, and this may correspondingly reduce the channel bandwidth and may cause quirks or problems in the physical layer processing. In addition, the USB interface is not as robust, and incurs more CPU overhead, than an Ethernet interface.

The USRP X300 and X310 radios can also be used as the gNB or UE, but with some limitations. Due to the 184.32 master clock rate (MCR), many of the 5G sampling rates cannot be achieved, or can only be achieved using odd decimations factors, which is undesirable because of the much-higher attenuation. It is likely that other non-standard sampling rates such as 42.08 Msps may have to be used as a compromise, and this may correspondingly reduce the channel bandwidth and may cause quirks or problems in the physical layer processing. The OAI software supports a three-quarter sampling rate for these cases using non-standard sampling rates, which is enabled with the "-E" command line option. This can be used, for example, to select a 46.08 Msps sampling rate instead of the ideal 61.44 Msps sampling rate.

Listed below are links to resources for the relevant USRP devices.
* The KB Hardware Resource page for the USRP B200, B210, B200mini, B206mini can be found [https://kb.ettus.com/B200/B210/B200mini/B205mini/B206mini here].
* The KB Hardware Resource page for the USRP X300 and X310 can be found [https://kb.ettus.com/X300/X310 here].
* The KB Hardware Resource page for the USRP N300 and N310 can be found [https://kb.ettus.com/N300/N310 here].
* The KB Hardware Resource page for the USRP N320 and N321 can be found [https://kb.ettus.com/N320/N321 here].
* The KB Hardware Resource page for the USRP X410 can be found [https://kb.ettus.com/X410 here].

If the UE is implemented using a USRP device, then it is recommended that the gNB USRP and the UE USRP be synchronized with the use of a 10 MHz reference signal and a 1 PPS signal, distributed from a common source. This can be provided by the OctoClock-G (see [https://kb.ettus.com/OctoClock_CDA-2990 here] and [https://uhd.readthedocs.io/en/uhd-4.8/page_octoclock.html here] for more information).

This document focuses on the use of the USRP X410. The usage of the USRP N300, N310, N320 is very similar to that of the X410. Specific discussion of the use of the USRP B200, B210, B200mini, B206mini, X300, X310 will be added in the near future.

Further details of the hardware configuration will be discussed later in this document.

==Overview of the OAI Software Stack==

The OpenAirInterface (OAI) software stack provides a fully open-source and standards-compliant implementation of the 3GPP 5G New Radio (NR) Stand-Alone (SA) protocol stack. It is designed to run in real-time on commodity x86 hardware and interoperate with USRP software-defined radios. Initially developed by Eurecom, a leading research institute in France, the project is now actively maintained by the OpenAirInterface Software Alliance (OSA), which is a non-profit organization that supports open wireless innovation and collaborative research. OAI enables complete 5G system prototyping and research with implementations of the base station (gNB), the user equipment (UE), and the core network (CN). The OAI stack also allows for the use of other third-party core network software, such as Free5GC and Open5GS. This document does not discuss integration with the Free5GC and Open5GS core network softwares. The OAI software stack is designed to operate in real-time with USRP radios, support interoperability with commercial 5G handsets (COTS handsets), and enable academic, experimental, and pre-commercial deployments. The OAI software stack is structured around multiple Git repositories, enabling modularity and collaborative development of the OAI 5G Radio Access Network (RAN) Project and the OAI 5G Core Network (OAI-CN). The OAI source code is made freely available for non-commercial and academic research use, and licensing details can be found on the OAI website.

Links to the relevant Git repositories are listed below.
* [https://gitlab.eurecom.fr/oai/openairinterface5g OAI 5G Radio Access Network (RAN)]
* [https://gitlab.eurecom.fr/oai/cn5g OAI 5G Core Network (OAI-CN)]

==Overview of the Reference Architecture==

This OAI End-to-End Reference Architecture enables researchers, developers, and system integrators to build complete 5G NR SA systems using open-source software and commercial USRP hardware. This section outlines two typical deployment modes of the architecture:

* A compact, single-host configuration for integrated lab setups.
* A modular, distributed configuration for scalable experimentation.

Each mode supports connectivity to a diverse range of UE devices, including Quectel 5G modem modules, USRP-based UEs, and COTS handsets such as the Google Pixel 9.

===Deployment Configuration 1: OAI gNB and CN on the Same Machine===

In this configuration, both the OAI Core Network (CN) and the OAI gNB are hosted on the same physical machine. This is typically used in lab-based research and teaching environments, portable demos and proof-of-concept systems, and quick-start testbeds for 5G protocol stack development.

The configuration of the system architecture is listed below.

* Host Computer: Intel or AMD CPU, with minimum 20 physical cores, such as the [https://www.intel.com/content/www/us/en/products/sku/233416/intel-xeon-w72495x-processor-45m-cache-2-50-ghz/specifications.html Intel Xeon W7-2495X], and with minimum 16 GB memory, and with 10 or 100 Gbps Ethernet card.
* Operating System: Ubuntu 22.04.5, running on-the-metal (no virtual machine (VM))
* Software Stack: OpenAirInterface gNB (monolithic) and 5G Core Network (AMF, SMF, UPF, NRF, etc.)
* UHD Version: 4.8
* USRP X410

Advantages:
* Easy to debug and deploy.
* Lower hardware requirements.
* Simple setup with fewer network dependencies.

Disadvantages:
* Shared CPU and I/O resources may limit performance.
* Less suitable and less scalable for high-throughput traffic testing and when using high sampling rates.

[[File:OAI_E2E_Arch.jpg|thumb|800px|center|Single-machine deployment with both OAI Core Network and gNB on the same host. USRP X410 provides RF connectivity to various UE types, including Quectel module, USRP UE, and Google Pixel 9.]]

===Deployment Configuration 2: OAI gNB and CN on Separate Machines===

This configuration separates the OAI gNB and CN onto two dedicated physical systems connected via an Ethernet switch. It is ideal for research involving modular network slicing, edge cloud integration, or realistic RAN-Core interface behavior, or for scalable testbeds with high-throughput and isolated workloads, or for large MIMO, beamforming or MEC-based deployments.

The configuration of the system architecture is listed below.

* gNB Host Computer: Intel or AMD CPU, with minimum 20 physical cores, such as the [https://www.intel.com/content/www/us/en/products/sku/233416/intel-xeon-w72495x-processor-45m-cache-2-50-ghz/specifications.html Intel Xeon W7-2495X], and with minimum 16 GB memory, and with 10 or 100 Gbps Ethernet card.
• CN Host Computer: Intel i9 CPU or Xeon CPU, with minimum 8 physical performance cores
* Operating System: Both hosts running Ubuntu 22.04.5, running on-the-metal (no virtual machine (VM))
* Software Stack: OpenAirInterface gNB (monolithic) and 5G Core Network (AMF, SMF, UPF, NRF, etc.)
* UHD Version: 4.8 (gNB only)
* USRP X410 (gNB only)

Advantages:
* Higher reliability and scalability.
* Easier to simulate real-world latency, routing, and interface constraints.
* Better performance profiling of CN and gNB independently.

Disadvantages:
* More complicated IP addressing, routing, and DNS configuration.
* More complicated to configure and monitor in real-time.

[[File:OAI_E2E_Arch_Different_Machines.jpg|thumb|800px|center|Multi-machine deployment with OAI Core Network and gNB on separate hosts. The setup uses a high-speed Ethernet switch and supports flexible UE integration over coaxial and OTA interfaces.]]

==Cable and Connectivity Setup==

This section describes the physical connectivity between the USRP hardware and various types of UE. The cabling requirements are independent of whether the gNB and CN are deployed on the same machine or on separate systems.

===Quectel Wireless Module UE Cable Configuration===

The diagram in the figure listed below illustrates the cabling and RF signal routing between the UE system running a Quectel RM520N wireless module and the USRP X410 connected to the OAI gNB. This setup enables direct RF loopback in a controlled lab environment using coaxial cable connections.

* USB Connection: The Quectel RM520N is connected to the UE system via a USB 3.0 interface. The host PC runs Windows and interacts with the module through Qualcomm QMI or MBIM drivers.

* RF Antennas: The module has 4 RF ports (ANT 0–3) which are routed to a 4-way power splitter (Mini-Circuits ZN4PD1-63HP-S+) to combine the signals.

* Attenuation: A fixed 40 dB attenuator is inserted after the splitter to protect the downstream USRP RF front end and ensure signal levels remain within safe operating range.

* Downstream RF Splitting: The combined RF signal is routed to a 2-way splitter (Mini-Circuits ZN2PD2-50-S+) which separates it into TX/RX and RX-only paths.

* USRP Connection: These RF paths are connected to the USRP X410, which is linked to the OAI gNB system over dual SFP+ (10/25G) links for baseband data transfer and synchronization.

[[File:cable_setup_with_COTS_UE.png|thumb|800px|center|Cable and RF splitter and attenuator setup for Quectel Wireless Module UE with USRP X410 and OAI gNB]]

===USRP-Based UE Cable Configuration===

The figure listed below illustrates the RF cabling setup used when both the OAI gNB and OAI UE are implemented using separate USRP X410 devices. This setup enables full bidirectional communication in a lab environment without the need for OTA transmission.

* Dual SFP+ Connection: Each USRP X410 is connected to its respective host computer via dual SFP+ ports (Port 0 and Port 1), providing high-throughput data and synchronization channels.

* SMA Cabling and RF Splitting: RF ports from the USRP gNB are connected via SMA cables to a 2:1 power splitter, enabling simultaneous TX/RX operation.

* 40 dB Attenuator: To ensure RF power levels are safe and within operational range for lab setup, a fixed 40 dB attenuator is inserted before the splitter connecting to the UE-side USRP.

* Bidirectional Lab Setup: This configuration mimics over-the-air conditions by enabling a fully enclosed cable-based signal path between the USRP radios representing the gNB and UE, ensuring interference-free testing.

[[File:cable_setup_with_USRP_UE.png|thumb|800px|center|Cable setup between OAI gNB and OAI NR UE using two USRP X410 devices and RF splitters]]

===Commercial UE Configuration with COTS Handset Over-the-Air (OTA)===

The figure listed below illustrates the setup for using a COTS 5G smartphone (Google Pixel 9) as the UE, in conjunction with the OAI NR gNB running on a USRP X410.

* gNB Host System: The gNB stack (OAI NR Monolithic) runs on an Ubuntu 22.04 server equipped with an Intel Xeon W7-2495X CPU, and interfaces with a USRP X410 via two SFP+ ports.

* OTA Link: The RF connection between the USRP and the Google Pixel 9 is established over the air, eliminating the need for RF splitters or coaxial cabling. The Pixel 9 receives the signal wirelessly from the gNB.

* SIM Card: The Google Pixel 9 uses a programmable Open Cell SIM card provisioned with the correct PLMN and network parameters to allow registration with the OAI core network.

* Use Case: This setup is ideal for validating interoperability with COTS 5G devices and ensuring compatibility with commercially available UEs under real-world radio conditions.

[[File:OAI_With_Google_Pixel_9.jpg|thumb|800px|center|OTA-based connectivity with Google Pixel 9 and Open Cell SIM]]

==Bill of Materials==

The full Bill of Materials (BoM) for the OAI Reference Architecture is listed below. This comprehensive list includes all necessary hardware components required to support a variety of deployment configurations for 5G and 6G research. The design supports multiple flexible system architectures, where the gNB (base station) and UE can each be implemented using any combination of the following USRP Software Defined Radios: N300, N310, N320, N321, or X410.

This BoM covers all shared components (host machines, network interfaces, RF cabling, timing/sync equipment, antennas, attenuators, and splitters) required for various testbed configurations. The system design is modular and scalable—users can choose to co-locate or distribute gNB and Core Network (CN) components, and can switch between different UE types depending on the research focus, such as PHY-level tuning, link testing, or full-stack validation with 3GPP-compliant UEs.

* Two or three desktop computers, with Intel i9 and/or Xeon CPU, of 12th, 13th, or 14th Generation, with clock speed of minimum 4.0 GHz, with minimum 8 (for i9 CPU) or 20 (for Xeon CPU) physical cores, and also with only NVMe disk drives. See further details about this item in the Hardware Requirements section.

* Two 10 Gbps Ethernet networks cards. We recommend the Intel 810-XXVDA2 and the Nvidia/Mellanox ConnectX-6 Lx (MCX623106AN-CDAT) network cards. See further details about this item in the Hardware Requirements section.

* The USRP may be any of USRP N300, N310, N320, N321, X410. There will be one USRP for the gNB, and one USRP for the UE. The USRP devices can be mixed (i.e., the gNB could run with a USRP X410, while the UE runs with a USRP N310).

* One QSFP28-to-SFP28 breakout cable. This is only required when using the USRP X410.
** [https://store.mellanox.com/products/nvidia-mcp7f00-a003r26n-passive-copper-splitter-cable-ethernet-100gbe-to-4x25gbe-qsfp28-to-4xsfp28-3m-colored-26awg-ca-n.html Nvidia MCP7F00-A003R26N] is a passive copper DAC splitter cable, 100GbE to 4x25GbE, 3m, 26 AWG.

** [https://store.mellanox.com/products/nvidia-mcp7f00-a003r30l-passive-copper-splitter-cable-ethernet-100gbe-to-4x25gbe-qsfp28-to-4xsfp28-3m-colored-30awg-ca-l.html Nvidia MCP7F00-A003R30L] is a passive copper DAC splitter cable, 100GbE to 4x25GbE, 3m, 30 AWG.

* One OctoClock-G. This is needed to synchronize the gNB USRP and the UE USRP. Ensure that device used is the "-G" model, which contains an internal GPSDO module. This is only needed when the UE is implemented on a USRP device.

* Four 10 Gbps Ethernet cables with SFP+ terminations: Required when using USRP N300, N310, N320, or N321. Not needed for USRP X410. Available in multiple lengths:

** [https://www.ettus.com/all-products/10gige-dc/ 0.5 meter SFP+ Ethernet cable]

** [https://www.ettus.com/all-products/10gige-1m/ 1.0 meter SFP+ Ethernet cable]

** [https://www.ettus.com/all-products/10gige-3m/ 3.0 meter SFP+ Ethernet cable]

* Four VERT900 and/or VERT2450 antennas: Select based on the frequency bands in use. Third-party antennas are also compatible if they have a 50-ohm impedance and SMA connectors.

** [https://www.ettus.com/all-products/vert900/ VERT900 Antenna]

** [https://www.ettus.com/all-products/vert2450/ VERT2450 Antenna]

* One Quectel RM520-GL 5G wireless modem module: Used as a UE option in the reference architecture. See the Hardware Requirements section for integration and compatibility details.

** [https://www.quectel.com/5g-iot-modules/ Quectel 5G Modules]

** [https://www.quectel.com/product/5g-rm520n-series/ Quectel RM520N Series Overview]

* One Google Pixel 9 5G handset (phone). Used as a commercial off-the-shelf (COTS) UE in the test setup. Ensure that the handset is unlocked for compatibility with test SIM cards.

** [https://www.gsmarena.com/google_pixel_9-13219.php Google Pixel 9]

* Two 5G SIM cards and one USB UICC/SIM card reader/writer.

** [https://open-cells.com/index.php/sim-cards/ Open Cells SIM Cards]

* One Mini-Circuits 4-way DC-Pass SMA Power Splitter (ZN4PD1-63HP-S+), 250 to 6000 MHz, 50 ohms.

** [https://www.minicircuits.com/WebStore/Splitters.html Mini-Circuits Splitters]

** [https://www.minicircuits.com/WebStore/dashboard.html?model=ZN4PD1-63HP-S%2B Model ZN4PD1-63HP-S+ Product Page]

* Two Mini-Circuits 2-way DC-Pass SMA Power Splitters (ZN2PD2-50-S+), 500 to 5000 MHz, 50 ohms.

** [https://www.minicircuits.com/WebStore/Splitters.html Mini-Circuits Splitters]

** [https://www.minicircuits.com/WebStore/dashboard.html?model=ZN2PD2-50-S%2B Model ZN2PD2-50-S+ Product Page]

* Four Mini-Circuits VAT-10+ Attenuators (10 dB, DC to 6000 MHz, 50 ohms, with SMA connectors.

** [https://www.minicircuits.com/WebStore/dashboard.html?model=VAT-10%2B Mini-Circuits Model VAT-10+ Product Page]

* Four Mini-Circuits VAT-20+ Attenuators (20 dB, DC to 6000 MHz, 50 ohms, with SMA connectors.

** [https://www.minicircuits.com/WebStore/dashboard.html?model=VAT-20%2B Mini-Circuits Model VAT-20+ Product Page]

* Four Mini-Circuits VAT-30+ Attenuators (30 dB, DC to 6000 MHz, 50~$\Omega$, with SMA connectors.

** [https://www.minicircuits.com/WebStore/dashboard.html?model=VAT-30%2B Mini-Circuits Model VAT-30+ Product Page]

* Fourteen Mini-Circuits Hand-Flex SMA Coax Cables (086-36SM+, 36-inch, 18 GHz.

** [https://www.minicircuits.com/WebStore/dashboard.html?model=086-36SM%2B Mini-Circuits 086-36SM+ Product Page]

** [https://www.minicircuits.com/pdfs/086-36SM+.pdf Mini-Circuits 086-36SM+ Datasheet]

* One NETGEAR GS108 8-Port Gigabit Ethernet Unmanaged Switch.

** [https://www.netgear.com/business/wired/switches/unmanaged/gs108/ NETGEAR Product Page]

** [https://www.amazon.com/NETGEAR-Ethernet-Unmanaged-Lifetime-Protection/dp/B00MPVR50A/ Amazon Product Listing]

* Three USB 3.0 to 1 Gbps Ethernet Adapters (USB-A or USB-C depending on host ports).

** [https://www.amazon.com/Network-Adapter-CableCreation-Ethernet-Supporting/dp/B013G4C8RE/ CableCreation USB 3.0 to Ethernet Adapter]
** [https://www.amazon.com/Ethernet-Thunderbolt-Gigabit-Network-Compatible/dp/B07XTGKP5M/ USB-C to Gigabit Ethernet Adapter]

==Hardware Requirements==

This section discusses details about each of the hardware components in the system.

===Host Computers===

Two or three host computers are needed, one for the gNB, one for the UE, and optionally one for the Core Network (CN). While the CN host has lower performance requirements, it is recommended that all machines meet the same baseline specifications. Each system should be dedicated to a single role (gNB, UE, or CN). A single host should not run multiple components simultaneously.

Example Host Systems:
* [https://system76.com/desktops/thelio-mira-b2/configure System76 Thelio Mira]
* [https://www.dell.com/en-us/shop/desktop-computers/precision-5860-tower/spd/precision-5860-workstation Dell Precision 5860 Tower Workstation]

===CPU===

* Recommended: Intel Core i9 or Intel Xeon (12th to 14th Generation)
** Minimum clock speed: 4.0 GHz
** Minimum 8 physical cores (for CN) or 20 physical cores (for gNB and UE)
** At least 24 PCIe lanes (for network card, more if GPU is also needed)
** PCIe Gen 4 support
 
Example Processors:
* [https://www.intel.com/content/www/us/en/products/sku/198014/intel-core-i910940x-xseries-processor-19-25m-cache-3-30-ghz/specifications.html Intel Core i9-10940X]  (14 cores at 4.6 GHz)
* [https://ark.intel.com/content/www/us/en/ark/products/134599/intel-core-i912900k-processor-30m-cache-up-to-5-20-ghz.html Intel Core i9-12900K] (16 cores at 5.2 GHz)
* [https://www.intel.com/content/www/us/en/products/sku/233416/intel-xeon-w72495x-processor-45m-cache-2-50-ghz/specifications.html Intel Xeon w7-2495X] (24 cores at 4.8 GHz)
* [https://www.intel.com/content/www/us/en/products/sku/212288/intel-xeon-platinum-8351n-processor-54m-cache-2-40-ghz/specifications.html Intel Xeon Platinum 8351N] (36 cores at 3.5 GHz)
 
===Disk===

* Strongly recommended: '''NVMe SSD''' (PCIe Gen 4)
* Do not use SATA disks, as the throughput is insufficient.
* Recommended models:
** [https://www.samsung.com/us/computing/memory-storage/solid-state-drives/980-pro-pcie-4-0-nvme-ssd-1tb-mz-v8p1t0b-am/ Samsung 980 PRO PCIe 4.0 NVMe SSD]
** [https://www.amazon.com/SAMSUNG-PCIe-Internal-Gaming-MZ-V8P1T0B/dp/B08GLX7TNT/ Amazon Link]
** [https://www.tomshardware.com/reviews/samsung-980-pro-m-2-nvme-ssd-review Tom's Hardware Review]
 
RAID configurations with multiple NVMe drives are optional and should not be required.

===Memory===

* Minimum: 16 GB
* Dual-channel or quad-channel DDR4 or DDR5 memory
* Higher memory is optional unless running virtualized workloads.

===GPU===

* The GPU is not required for UHD or OAI operation.
* Include one only if performing AI/ML workloads.
* The OAI 5G stack currently does not utilize GPU acceleration.

===10 Gbps Ethernet Network Card===

* The gNB and UE each require a dual-port 10/25 GbE NIC.
* The CN does not interface directly with USRPs and can use standard 1 Gbps Ethernet.
* Ensure adequate cooling and PCIe slot space.

Recommended network cards:
* '''Intel E810-XXVDA2''' (25 GbE, backward compatible with 10 GbE)
** [https://www.intel.com/content/www/us/en/products/sku/189042/intel-ethernet-network-adapter-e810xxvda2/specifications.html Product Page (Intel)]
** [https://www.amazon.com/Intel-E810XXVDA2-Ethernet-Network-Adapter/dp/B097M26PXZ/ Amazon Link]

* NVIDIA ConnectX-6 Lx (MCX623106AN-CDAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://docs.nvidia.com/networking/display/connectx6dxen Product Page (NVIDIA)]
** [https://www.fs.com/de/products/119646.html?now_cid=4014 FS Link]

===QSFP28-to-SFP28 Breakout Cable for USRP X410===

The USRP X410 has two QSFP28 (100 GbE) ports. To connect the USRP X410 to the 10 GbE network card on a host computer, use a QSFP28-to-4xSFP28 breakout cable.

Recommended cables:
* [https://store.nvidia.com/en-us/networking/store/product/MCP7F00-A003R26N/nvidiamcp7f00-a003r26ndacsplittercableethernet100gbeto4x25gbe3m/ NVIDIA MCP7F00-A003R26N] – 3 m, 26 AWG  
* [https://store.nvidia.com/en-us/networking/store/product/MCP7F00-A003R30L/nvidiamcp7f00-a003r30ldacsplittercableethernet100gbeto4x25gbe3m/ NVIDIA MCP7F00-A003R30L] – 3 m, 30 AWG  
* [https://store.mellanox.com/products/nvidia-mcp7f00-a001r30n-passive-copper-splitter-cable-ethernet-100gbe-to-4x25gbe-qsfp28-to-4xsfp28-1m-colored-30awg-ca-n.html NVIDIA MCP7F00-A001R30N] – 1 m, 30 AWG  

The USRP X410 can also use its QSFP28 100 Gbps Ethernet Connection. This requires that the host computer have a 100 Gbps QSFP28 Ethernet card.

Recommended network cards:
* [https://store.mellanox.com/products/nvidia-mcx516a-ccat-connectx-5-en-adapter-card-100gbe-dual-port-qsfp28-pcie3-0-x16-tall-bracket-rohs-r6.html Mellanox MCX516A-CCAT (ConnectX-5 EN, PCIe Gen 3)]
* [https://store.mellanox.com/products/nvidia-mcx516a-cdat-connectx-5-ex-en-adapter-card-100gbe-dual-port-qsfp28-pcie4-0-x16-tall-bracket-rohs-r6.html Mellanox MCX516A-CDAT (ConnectX-5 Ex, PCIe Gen 4)]
* [https://store.mellanox.com/products/nvidia-mcp1600-c003e26n-passive-copper-cable-ethernet-100gbe-qsfp28-3m-black-26awg-ca-n.html Mellanox MCP1600-C003E26N (3 m, 26 AWG)]
* [https://store.mellanox.com/products/nvidia-mcp1600-c003e30l-passive-copper-cable-ethernet-100gbe-qsfp28-3m-black-30awg-ca-l.html Mellanox MCP1600-C003E30L (3 m, 30 AWG)]
* [https://ark.intel.com/content/www/us/en/ark/products/series/184846/100gbe-intel-ethernet-network-adapter-e810.html Intel E810 Series (QSFP28/SFP28)]

This reference architecture does not require full 100 GbE links. Dual 10 Gbps SFP+ links are sufficient for 1x1 and 2x2 MIMO operation in FR1.

== USRP Devices ==
Two USRP devices are required, one for the gNB, and one for the UE. Several USRP devices can be used.

* USRP N300 – [https://kb.ettus.com/N300/N310 KB Page] | [https://www.ettus.com/all-products/usrp-n300/ Product Page]
* USRP N310 – [https://kb.ettus.com/N300/N310 KB Page] | [https://www.ettus.com/all-products/usrp-n310/ Product Page]
* USRP N320 – [https://kb.ettus.com/N320/N321 KB Page] | [https://www.ettus.com/all-products/usrp-n320/ Product Page]
* USRP N321 – [https://kb.ettus.com/N320/N321 KB Page] | [https://www.ettus.com/all-products/usrp-n321/ Product Page]
* USRP X410 – [https://kb.ettus.com/X410 KB Page] | [https://www.ettus.com/all-products/usrp-x410/ Product Page]

You can use difference USRP devices for the gNB and UE. The gNB and UE do not need to use the same specific USRP device. For example, the gNB may use a USRP X410, while the UE uses a USRP N310.

The USRP devices support the following channel bandwidths:
* FR1 (Sub-6 GHz): All models support up to 100 MHz.
* FR2 (mmWave):
** USRP N320: 50, 100, 200 MHz supported
** USRP X410: 50, 100, 200, 400 MHz supported

===OctoClock-G===

An OctoClock-G is required to synchronize the gNB and UE USRP radios. This is only necessary when both the gNB and UE are implemented with USRP devices. Ensure you are using the "-G" version, which includes an internal GPSDO (GPS-Disciplined Oscillator).

==Software Requirements==

This section discusses details about each of the software components in the system.

===Operation System===

The recommended operating system for the gNB, UE, and CN systems is Ubuntu 22.04.5. Ensure you download and install the Desktop version, not the Server version.

For the gNB and UE systems, it is optional to install the low-latency kernel to meet real-time performance requirements. The preferred kernel version is 6.8 or later.

The CN system can operate with the default generic kernel and does not require low-latency optimizations.

Do not run Ubuntu in a Virtual Machine (VM)} or any virtualization layer. Install Ubuntu directly on the hardware (on-the-metal).

Alternative Ubuntu flavors such as Kubuntu, Lubuntu, Xubuntu, and Ubuntu MATE may also be used, if preferred.

===UHD===

UHD (USRP Hardware Driver) is the open-source device driver and API for all USRP radios. The required version for this reference architecture is UHD 4.8.0, which includes enhanced support for new hardware platforms and performance improvements over prior releases.

* UHD must be installed on both the gNB and UE systems.

* UHD is not required on the CN system.

* It is strongly recommended to build UHD from source code, rather than installing it from a binary package, or using the OAI "build_oai" script.

* UHD must be installed prior to building OAI. See the Application Note [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux here] for more information.

===OAI===

OAI provides an open-source, 3GPP-compliant implementation of the 5G NR stack, including the gNB, UE, and Core Network (CN) components. This reference design utilizes the latest "develop" branch of the OAI repository for all components.

* The OAI software must be built and installed on the gNB, UE, and CN systems.
* Only the "develop" branch is used for this deployment to ensure access to the latest features and fixes.
* It is recommended to build OAI from source using the provided "build_oai" script.
* Be sure to build and install UHD prior to compiling and installing OAI.

The Git repository for OAI is at the link below.

* [https://gitlab.eurecom.fr/oai/openairinterface5g https://gitlab.eurecom.fr/oai/openairinterface5g]

==Installing and Configuring the UHD Software==

This section explains how to build and install the USRP Hardware Driver (UHD) from source code. UHD is the open-source driver for all USRP radios and is required on both the gNB and UE systems. It is not required on the CN system. We strongly recommend building UHD from source rather than installing from binary packages to ensure compatibility and access to the latest updates. At the time of this writing, we recommend using UHD version 4.8.

Before building UHD, install all the required dependencies using the following command (for Ubuntu 22.04):

    sudo apt update && sudo apt install -y cmake g++ libboost-all-dev libusb-1.0-0-dev libuhd-dev python3 python3-mako python3-numpy python3-requests python3-ruamel.yaml libfftw3-dev libqt5opengl5-dev qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools doxygen

Then, clone the UHD repository and check out the "v4.8.0.0" tag:

    git clone https://github.com/EttusResearch/uhd.git
    cd uhd
    git checkout v4.8.0.0

Then, build and install UHD:

    cd host
    mkdir build
    cd build
    cmake ../
    make -j$(nproc)
    sudo make install
    sudo ldconfig
    export LD_LIBRARY_PATH=/usr/local/lib
    sudo uhd_images_downloader

You can verify the installation by running:

    uhd_usrp_probe
    uhd_find_devices

For more details, see the [https://github.com/EttusResearch/uhd UHD GitHub page].

[[File:uhd_usrp_probe_output.png|thumb|800px|center|uhd_usrp_probe output for USRP B210]]

[[File:uhd_find_devices_output.png|thumb|800px|center|uhd_find_devices output for USRP N310 and X410]]

===Installing and Configuring the USRP Radio===

The USRP N300, N310, N320, N321, and X410 can all be used either as the gNB or as the UE in this reference design.

===USRP N300 and N310===

For setup and configuration, refer to the [https://kb.ettus.com/USRP_N300/N310/N320/N321_Getting_Started_Guide USRP N300/N310 Getting Started Guide].

These devices support all the channel bandwidths in FR1.

===USRP N320 and N321===

For setup and configuration, refer to the [https://kb.ettus.com/USRP_N300/N310/N320/N321_Getting_Started_Guide USRP N320/N321 Getting Started Guide].

These devices support all the channel bandwidths in FR1 and FR2, except the 400 MHz in FR2.

===USRP X410===

For setup and configuration, refer to the [https://kb.ettus.com/USRP_X410/X440_Getting_Started_Guide USRP X410 Getting Started Guide].

The X410 supports all channel bandwidths in both FR1 and FR2.

==Configuring the Ubuntu Linux Operating System==

For optimal system performance, refer to the article [https://kb.ettus.com/USRP_Host_Performance_Tuning_Tips_and_Tricks USRP Host Performance Tuning Tips and Tricks], which outlines specific settings and configuration procedures that are necessary to perform. These include:
 
* Set the CPU governors.
* Enable thread priority scheduling.
* Set the read and write socket buffer sizes.
* Adjust Ethernet MTU values.
* Set the network card ring buffer sizes.
* In the BIOS, disable Hyper-threading and disable P-state controls.

Note that the use of the [https://www.dpdk.org/ Data Plane Development Kit (DPDK)] is not required for running any of the FR1 channel bandwidths. As of this writing, DPDK is not used in this reference architecture. The use of DPDK is necessary for the FR2 channel bandwidths.

==Installing, Configuring, and Running the CN System==

The figure listed below illustrates the deployment architecture of the OAI 5G Core Network. The core network is implemented using several containerized network functions (NFs), each mapped to a specific IP address within the subnet `192.168.70.128/26`.
 
[[File:OAI_Core_Network.jpg|thumb|center|700px|OpenAirInterface (OAI) Core Network Deployment Architecture]]

The following components are included:
 
* OAI-NRF (Network Repository Function) at `192.168.70.130` – Handles service registration and discovery.

* OAI-AMF (Access and Mobility Function) at `192.168.70.132` – Manages UE registration, connection, and mobility.

* OAI-SMF (Session Management Function) at `192.168.70.133` – Manages sessions and IP address allocation.

* OAI-UPF (User Plane Function) at `192.168.70.134` – Routes user data traffic and connects to the external data network via the N3 interface.

* OAI-EXT-DN (External Data Network) at `192.168.70.135` – Provides Internet or service access for UEs.

* OAI-AUSF (Authentication Server Function) at `192.168.70.138` – Handles UE authentication.

* OAI-UDM (Unified Data Management) at`192.168.70.137` and OAI-UDR (Unified Data Repository) at `192.168.70.136` –   Manage subscription and policy data.

* MySQL Server – connected to `192.168.70.132` for database services required by AMF and UDM.

This architecture demonstrates a standard service-based interface (SBI) deployment with N3 and N4 interfaces clearly marked between UPF and SMF.

Each component is deployed in a containerized environment, typically using Docker Compose.

==Core Network (CN) Deployment Scenarios==
 
The OAI CN can be deployed in two different configurations depending on the system requirements and testbed constraints. Both setups follow the same installation process, differing only in whether the CN is hosted on a separate machine or the same machine as the gNB.
 
===Scenario 1: CN and gNB on the Same Machine===
 
This configuration runs both the Core Network and the gNB stack on a single physical machine. It is suitable for development, testing, and lab-scale demonstrations. Follow the installation procedure listed below.

Install the pre-requisites and Docker.

    <syntaxhighlight lang="bash">
    sudo apt install -y git net-tools putty
    sudo apt update
    sudo apt install -y ca-certificates curl
    sudo install -m 0755 -d /etc/apt/keyrings
    sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
    sudo chmod a+r /etc/apt/keyrings/docker.asc
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
    sudo apt update
    sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
    sudo usermod -a -G docker $(whoami)
    reboot
    </syntaxhighlight>
 
Then, download and configure OAI CN.

    <syntaxhighlight lang="bash">
    wget -O ~/oai-cn5g.zip https://gitlab.eurecom.fr/oai/openairinterface5g/-/archive/develop/openairinterface5g-develop.zip?path=doc/tutorial_resources/oai-cn5g
    unzip ~/oai-cn5g.zip
    mv ~/openairinterface5g-develop-doc-tutorial_resources-oai-cn5g/doc/tutorial_resources/oai-cn5g ~/oai-cn5g
    rm -r ~/openairinterface5g-develop-doc-tutorial_resources-oai-cn5g ~/oai-cn5g.zip
    </syntaxhighlight>
 
Then, pull and launch the CN.

    <syntaxhighlight lang="bash">
    cd ~/oai-cn5g
    docker compose pull
    docker compose up -d
    </syntaxhighlight>
 
In order to stop the CN, run the commands listed below.

    <syntaxhighlight lang="bash">
    cd ~/oai-cn5g
    docker compose down
    </syntaxhighlight>
 
===Scenario 2: CN and gNB on Separate Machines===
 
In this setup, the Core Network is deployed on a dedicated host, while the gNB runs on a separate system. This architecture is closer to real-world 5G deployments and helps isolate network functions for performance analysis.

====Hardware Requirements====
* Ubuntu version 22.04.5
* CPU: 8 cores at minimum 3.5 GHz clock speed
* RAM: minimum 16 GB, recommended 32 GB

====Additional Requirements====
* A second physical machine with the same system specifications.
* Proper IP routing between CN and gNB machines, usually through a simple Ethernet switch.

Installation steps are identical to Scenario 1, executed on the second machine allocated for CN.
 
===Core Network Database Configuration===

To configure the OAI CN with a valid UE profile, manually insert subscriber information into the MySQL database by editing the file `oai_db.sql`.
 
    <syntaxhighlight lang="bash">
    cd ~/oai-cn5g/database
    </syntaxhighlight>
 
Open the `oai_db.sql` file, and insert the following under the `AuthenticationSubscription` table:
 
    <syntaxhighlight lang="sql">
    INSERT INTO `AuthenticationSubscription`
    (`ueid`, `authenticationMethod`, `encPermanentKey`, `protectionParameterId`, 
     `sequenceNumber`, `authenticationManagementField`, `algorithmId`, `encOpcKey`, 
     `encTopcKey`, `vectorGenerationInHss`, `n5gcAuthMethod`, `rgAuthenticationInd`, `supi`)
    VALUES
    ('208950000000032', '5G_AKA',
     'fec86ba6eb707ed08905757b1bb44b8f',
     'fec86ba6eb707ed08905757b1bb44b8f',
     '{"sqn": "000000000000", "sqnScheme": "NON_TIME_BASED", "lastIndexes": {"ausf": 0}}',
     '8000',
     'milenage',
     'C42449363BBAD02B66D16BC975D77CC1',
     NULL, NULL, NULL, NULL,
     '001010000000001');
    </syntaxhighlight>

Note that:
* IMSI: The "ueid" and "supi" must match the IMSI used by your UE. In this example, the IMSI is "208950000000032".
* Key: This is the permanent key shared between the UE and the core network. In this example, "fec86ba6eb707ed08905757b1bb44b8f".
* OPC: Operator Code used in milenage authentication. In this example, "C42449363BBAD02B66D16BC975D77CC1"
* Authentication Method: Ensure that "5G_AKA" is used for standard 5G UE authentication.

===Update PLMN Configuration in "config.yaml"===

Edit the configuration file:

    <syntaxhighlight lang="bash">
    cd ~/oai-cn5g/config
    nano config.yaml
    </syntaxhighlight>

Modify the file as shown below:

    <syntaxhighlight lang="yaml">
    plmn:
      mcc: "208"
      mnc: "95"
      tac: 1
      nssai:
        - sst: 1
    </syntaxhighlight>

Restart the CN stack:

    <syntaxhighlight lang="bash">
    cd ~/oai-cn5g
    docker compose down
    docker compose up -d
    </syntaxhighlight>

===Installing Wireshark on Ubuntu===
 
Wireshark is a real-time packet sniffer that used to monitor traffic between CN and gNB.

If not already installed, then install Wireshark, and then launch it.

    <syntaxhighlight lang="bash">
    sudo apt update && sudo apt upgrade -y
    sudo apt install -y wireshark
    sudo dpkg-reconfigure wireshark-common
    sudo usermod -aG wireshark $(whoami)
    sudo wireshark
    </syntaxhighlight>

After launch, select an interface (e.g., `eth0`, `enp1s0`, or `oai-cn`) to capture packets. Select the interface that is connected from the CN system to the gNB system.

===Launch OAI CN Containers===

Once you have configured and deployed the OAI 5G Core Network using Docker Compose, run the following command to launch the Core Network.

    <syntaxhighlight lang="bash">
    sudo docker-compose up -d
    </syntaxhighlight>

The command above should yield output similar to the image listed below, confirming that all necessary containers and services are created and running.

[[File:Start_up_OAI_CN.png|thumb|center|600px|Successful startup of OAI CN5G containers using Docker Compose]]

Each CN function (AMF, SMF, UPF, NRF, AUSF, etc.) runs as a individual Docker container. The message "... done" indicates successful start-up.

===Verification of Running CN Containers===

To verify that all core network components are running correctly, use the following command:

    <syntaxhighlight lang="bash">
    sudo docker ps -a
    </syntaxhighlight>

You should see output similar to the image listed below, showing all containers with "STATUS" as "Up ... (healthy)".

[[File:OAI_CN_Docker_Containers.png|thumb|center|600px|OAI CN containers running successfully]]
 
This confirms the healthy status of all the core network components such as AMF, SMF, UPF, NRF, AUSF, UDM, UDR, MySQL, and EXT-DN. The exposed ports indicate the services are properly bound and ready for communication.

===Wireshark Monitoring of OAI CN===

Wireshark is a powerful tool used to observe packet exchanges within the OAI CN deployment. Below we show the key steps in using Wireshark.

Upon launching Wireshark, the user must select the appropriate interface to begin capturing packets. In our setup, the interface named "oai-cn5g" represents the internal Docker network where all core services are communicating.  Select the interface `oai-cn5g` to capture traffic between CN components, as shown in the figure listed below.

[[File:Wireshark_OAI.png|thumb|center|700px|Selecting the oai-cn5g interface in Wireshark]]

Once the capture starts, Wireshark displays packets exchanged between the core network functions such as AMF, SMF, NRF, AUSF, and others. This is useful for verifying proper message flow and debugging. Reference the figure shown below.

[[File:Wireshark_Capture.png|thumb|center|700px|Live capture showing HTTP2, TCP, and PFCP traffic between CN containers]]

==Installing, Configuring, and Running the gNB System==

To build the OAI gNB on the same machine, or on a separate machine, from the CN machine, follow the steps below. These instructions use the latest "develop" branch of the OAI codebase.

Clone the OAI repository and switch to the "develop" branch.

    <syntaxhighlight lang="bash">
    git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git ~/openairinterface5g
    cd ~/openairinterface5g
    git checkout develop
    </syntaxhighlight>

Navigate to the CMake targets directory, and install all required system and build dependencies.

    <syntaxhighlight lang="bash">
    cd ~/openairinterface5g/cmake_targets
    ./build_oai -I
    </syntaxhighlight>

Install the dependencies required by the "nrscope" tool.

    <syntaxhighlight lang="bash">
    sudo apt install -y libforms-dev libforms-bin
    </syntaxhighlight>

Compile the gNB and the optional nrUE modules with the USRP target. The build uses "ninja" and includes the "nrscope" library.

    <syntaxhighlight lang="bash">
    cd ~/openairinterface5g/cmake_targets
    ./build_oai -w USRP --ninja --nrUE --gNB --build-lib "nrscope" -C
    </syntaxhighlight>

Once built, the binaries "nr-gnb" and (optionally) "nr-ue" will be located in the <code>~/openairinterface5g/cmake_targets/ran_build/build/</code> folder.

===gNB Configuration File Setup for OAI with USRP X410===

The gNB configuration must match your local system and hardware. Configuration files are in the <code>~/openairinterface5g/targets/PROJECTS/GENERIC-NR-5GC/CONF/</code> folder.

Edit the following sections of this file, per the figures shown below.

[[File:MCC_MNC_update.png|center|900px|MCC, MNC, and SST configuration in PLMN section]]

* Set <code>mcc = 208</code>, <code>mnc = 95</code>, and <code>sst = 1</code> to match the Core Network (CN) slice configuration.

* <code>nr_cellid = 12345678L</code> can be any unique value.
 
[[File:AMF_IP_Address.png|center|700px|AMF IP address and gNB network interface settings]]

* <code>amf_ip_address</code>: IP of the AMF container (e.g., <code>192.168.70.132</code>).

* <code>GNB_IPV4_ADDRESS_FOR_NG_AMF</code> and <code>GNB_IPV4_ADDRESS_FOR_NGU</code>: set to the host machine's IP address (e.g., <code>10.88.136.29</code>).
 
[[File:ORU_Update.png|center|900px|Radio Unit (RU) configuration for USRP X410]]
 
* <code>local_rf = "yes"</code> enables local RF.

* <code>bands = [78]</code> selects NR band n78.

* <code>max_rxgain = 75</code>, <code>max_pdschReferenceSignalPower = -27</code> set RF parameters.

* <code>sdr_addrs</code>specifies the device argument list for the USRP X410. For example:
** <code>type=x4xx</code>
** <code>mgmt_addr=192.168.11.2</code>
** <code>addr=192.168.11.2</code>
** <code>clock_source=internal</code>
** <code>time_source=internal</code>

Ensure that the system firewall rules permit relevant IP traffic, and that all IP addresses reflect your physical environment and network configuration.

===Network Configuration for Separate CN Deployment===

When the CN is on a separate machine, configure networking so the gNB can reach CN containers.

====Add Static Route on gNB Machine====

A static route must be added to the gNB machine so it can reach the CN container subnet.

    <syntaxhighlight lang="bash">
    sudo ip route add 192.168.70.128/26 via 10.89.14.119 dev eno1
    </syntaxhighlight>

* <code>192.168.70.128/26</code>: CN Docker bridge subnet.

* <code>10.89.14.119</code>: CN host machine IP.

* <code>eno1</code>: gNB NIC toward CN (e.g., <code>enp1s0</code> on your system).

Note that this route is not persistent across reboots.

=== Enable IP Forwarding and Adjust iptables on CN Machine ===

To allow the CN machine to forward packets between the gNB and the containerized core network functions, the following settings must be configured.

    <syntaxhighlight lang="bash">
    sudo sysctl net.ipv4.conf.all.forwarding=1
    sudo iptables -P FORWARD ACCEPT
    </syntaxhighlight>

These settings are also temporary and will reset after reboot unless added to startup scripts or permanent configuration files. Set <code>/etc/sysctl.conf</code> for IP forwarding, and use the "iptables-persistent" or "systemd" service for IP firewall rules.

If the CN and gNB are on the same host, then this section is not needed.

===Invoking the gNB===

====Copy the Configuration File====

First, copy the edited gNB configuration file to the appropriate directory.

    <syntaxhighlight lang="bash">
    cp openairinterface5g/ci-scripts/conf_files/gnb.sa.band78.fr1.106PRB.2x2.usrpn300.conf openairinterface5g/targets/PROJECTS/GENERIC-NR-5GC/CONF/
    </syntaxhighlight>

====Launch the gNB====

Change into the build directory.

    <syntaxhighlight lang="bash">
    cd ~/openairinterface5g/cmake_targets/ran_build/build
    </syntaxhighlight>

The, run the command listed below.

    <syntaxhighlight lang="bash">
    sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.2x2.usrpn300.conf --gNBs.[0].min_rxtxtime 6 --usrp-tx-thread-config 1
    </syntaxhighlight>

Then open Wireshark, select the interface connected to the CN, and observe the NGAP packets.

* <code>--gNBs.[0].min_rxtxtime 6</code> reduces RX→TX latency.

* <code>--usrp-tx-thread-config 1</code> pins TX thread to a dedicated core.

===Verifying with Wireshark===

Wireshark is used to verify the NGAP signaling between the gNB and the Core Network (CN). The interface to monitor depends on your network configuration. The figure listed below shows a Wireshark capture showing successful NGSetupRequest and NGSetupResponse between gNB and AMF

[[File:Wireshark_OAI_NGAP.png|center|750px|Wireshark capture showing successful NGSetupRequest and NGSetupResponse between gNB and AMF]]
 
====Scenario A: CN and gNB on Separate Machines====

* On the CN machine, select the <code>oai-cn5g</code> interface in Wireshark.

* On the gNB machine, select the Ethernet interface (e.g., <code>eno1</code>) toward the CN.

====Scenario B: CN and gNB on Same Machine====

* Select only the <code>oai-cn5g</code> interface (all internal CN–gNB signaling is visible).

The expected behavior is:
* After startup, the gNB sends an "NGAP Setup Request" to the AMF.
* Then, the AMF responds with NGAP Setup Response" if the MCC, MNC, and TAC parameters match.

Ensure that the MCC, MNC, SST match between gNB config and CN <code>config.yaml</code>.
* Verify that the TAC (Tracking Area Code) matches on both sides.
* Confirm static route and L2/L3 connectivity between gNB and CN.

==Installing, Configuring, and Running the OAI UE System==

There are three types of UE implementations that can be used with the OpenAirInterface (OAI) stack:
* USRP OAI UE: Uses a USRP radio as the UE implementation (e.g., USRP B210). This does not use any SIM card.
* Modem Module UE: A modem module such as from Quectel or Sierra Wireless. This uses a test SIM card.
* COTS UE: Commercial handset, such as a Google Pixel 9. It connects OTA to the OAI gNB using a valid 5G SIM profile. The handset must be unlocked. This uses a test SIM card.

In this subsection, we focus only on the USRP OAI UE.

Clone the OAI UE repository, and checkout a tagged release.

    <syntaxhighlight lang="bash">
    git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git ~/openairinterface5g
    cd ~/openairinterface5g
    git checkout develop
    </syntaxhighlight>

Next, install the OAI UE Dependencies.

    <syntaxhighlight lang="bash">
    cd ~/openairinterface5g/cmake_targets
    ./build_oai -I
    </syntaxhighlight>

Next, build the OAI UE with USRP support.

    <syntaxhighlight lang="bash">
    cd ~/openairinterface5g/cmake_targets
    ./build_oai -w USRP --ninja --nrUE --build-lib nrscope -C
    </syntaxhighlight>

Next, configure the OAI UE parameters.

The following configuration provisions the OAI UE running on a USRP radio. It defines the IMSI, cryptographic keys, and network parameters (DNN, NSSAI). These must match the subscriber entry in the Core Network (AMF/UDM) for successful registration and session setup.

[[File:OAI_UE_Config_file.png|center|700px|OAI UE Configuration Parameters for IMSI 208950000000032]]

Ensure the following values are synchronized between the OAI UE and CN:
* <code>imsi</code>, <code>key</code>, and <code>opc</code> match the subscriber profile in the UDM DB/YAML.
* <code>dnn</code> (e.g., <code>oai</code> or <code>default</code>) matches SMF config.
* <code>nsai</code> (<code>sst</code> and optional <code>sd</code>) matches the network slice.

Next, invoke the OAI UE with the USRP by running from the build directory after configuring parameters.

    <syntaxhighlight lang="bash">
    ~/openairinterface5g/cmake_targets/ran_build/build$ sudo ./nr-uesoftmodem -r 106 --numerology 1 --band 78 -C 3319680000 --ue-fo-compensation -E --uicc0.imsi 208950000000032 --ssb 516 --ue-rxgain 114
    </syntaxhighlight>

The parameters are as follows.
* <code>-r 106</code>: Number of PRBs.
* <code>--numerology 1</code>: 30 KHz SCS.
* <code>--band 78</code>: FR1 band n78.
* <code>-C 3319680000</code>: Center frequency in Hz.
* <code>--ue-fo-compensation</code>: Frequency offset compensation.
* <code>-E</code>: Three-quarter-rate sampling (commonly used on the USRP B200, B210, B200mini, X300, X310).
* <code>--uicc0.imsi 208950000000032</code>: IMSI for 5GC auth.
* <code>--ssb 516</code>: SSB index.
* <code>--ue-rxgain 114</code>: B210 RX gain (dB).

Only use the <code>-E</code> option when running with the USRP B200, B210, B200mini, X300, X310, and omit it when running with the USRP N300, N310, N320, X410.

===Verifying OAI UE IP Assignment===

After successful PDU session setup, verify tunnel interface <code>oaitun_ue1</code>.

    <syntaxhighlight lang="bash">
    ifconfig oaitun_ue1
    </syntaxhighlight>

The desired output should be similar to what is shown below.

    <syntaxhighlight lang="text">
    oaitun_ue1: flags=209<UP,POINTOPOINT,RUNNING,NOARP>  mtu 1500
        inet 10.0.0.5  netmask 255.255.255.0  destination 10.0.0.5
        ...
    </syntaxhighlight>

In this example, the UE IP is <code>10.0.0.5</code>.

===gNB Log Interpretation for OAI UE Attachment and PDU Session Setup===

Listed below are annotated logs from the gNB that demonstrate the successful Random Access, RRC connection setup, NGAP procedures, and PDU session establishment for the UE.

    <syntaxhighlight lang="text">
    [NR_PHY] [RAPROC] Initiating RA procedure with preamble 0 ...
    [NR_MAC] UE RA-RNTI 010f TC-RNTI 55aa: Activating RA process index 0
    [NR_MAC] UE 55aa: Generating RA-Msg2 DCI
    [NR_MAC] Msg3 scheduled ...
    [NR_MAC] Send RAR to RA-RNTI 010f
    [NR_MAC] PUSCH with TC_RNTI 0x55aa received correctly
    [MAC] [RAPROC] Received SDU for CCCH length 6 for UE 55aa
    [RLC] Activated SRB0 and SRB1 for UE 21930
    [NR_MAC] Scheduling Msg4 for TC_RNTI 0x55aa
    [NR_RRC] Create UE context for RNTI 55aa → UE ID 1
    [NR_RRC] Send RRC Setup
    [NR_MAC] UE 55aa: Msg4 Ack received — CBRA procedure succeeded!
    [NR_RRC] RRCSetupComplete received — UE is now RRC_CONNECTED
    [NGAP] UE 1: Chose AMF 'OAI-AMF' (PLMN MCC 208, MNC 95)
    [NR_RRC] Send/Receive DL and UL Information Transfer messages
    [NR_RRC] SecurityModeCommand sent → Ciphering: 0, Integrity: 2
    [NR_RRC] SecurityModeComplete received
    [NR_RRC] UE Capability Enquiry/Response exchanged
    [NGAP] InitialContextSetupResponse sent 
    [PDU SESSION SETUP INITIATED]
    [NR_RRC] PDU Session Setup Request received → ID: 10
    [GTPU] Tunnel Created: TEID: bf57e042 ↔ 192.168.70.134
    [PDCP/RLC/SDAP] DRB 1 created, SRB2 activated
    [RRC] RRCReconfiguration sent (bytes: 327)
    [NR_RRC] RRCReconfigurationComplete received
    [NR_RRC] PDUSESSION_SETUP_RESP sent → TEID: 3210207298, IP: 10.88.136.29
</syntaxhighlight>

Note the following key events from the log file.

* "RA procedure succeeded": UE completed Msg4 ACK.
* "RRC_CONNECTED": RRC established.
* "SecurityModeComplete": Security context OK.
* "InitialContextSetupResponse": AMF context OK.
* "PDU Session Setup": Bearer and GTP-U tunnel created.

===OAI UE Log Interpretation for Initial Access and Registration===

The following annotated logs from the OAI UE show the end-to-end UE attach, synchronization, random access procedure, NAS signaling, and security configuration.

    <syntaxhighlight lang="text">
    [PHY]   SSB position provided
    [NR_PHY]   Starting sync detection
    [PHY]   [UE thread Synch] Running Initial Synch
    [NR_PHY]   Cell search with center freq: 3319680000, bandwidth: 106
    [PHY]   pbch decoded successfully, rsrp: 70 dB/RE
    [PHY]   Initial sync successful, PCI: 0
    [PHY]   UE synchronized! decoded_frame_rx=502 ... trashed_frames=70
    [NR_RRC]   SIB1 decoded → system information received
    [NR_MAC]   TDD Configuration set: 8 DL / 3 UL slots per period
    [MAC]   Initialization of 4-Step CBRA procedure
    [PHY]   PRACH transmitted: Frame 577, Slot 19
    [PHY]   RAR-Msg2 decoded
    [MAC]   TA command received, Msg3 transmitted
    [MAC]   4-Step RA procedure succeeded
    [NR_RRC]   Received NR_RRCSetup on DL-CCCH (SRB0)
    [RLC]   SRB1 added
    [NR_RRC]   UE state set to NR_RRC_CONNECTED
    [NAS]   Initial Registration Request generated
    [NR_RRC]   RRCSetupComplete sent on UL-DCCH (SRB1)
    [NAS]   Authentication Request received
    [NAS]   Security Keys derived: kgnb, kausf, kseaf, kamf
    [NAS]   Security Mode Command received and responded with Security Mode Complete
    [NR_RRC]   Capability Enquiry received and processed
    [NR_RRC]   UECapabilityInformation transmitted
    </syntaxhighlight>

Note the following key events from the log file.

* "Synchronization:" UE synchronizes to gNB SSB with PCI 0 and RSRP of 70 dB/RE.
* "RA Procedure:" PRACH sent, Msg2 received, Msg3 transmitted, Msg4 ACK confirmed.
* "RRC Setup:" UE enters <code>NR_RRC_CONNECTED</code> state after SetupComplete.
* "NAS Authentication:"  UE derives security keys (KgNB, KAMF, etc.).
* "Security Setup:" Ciphering and integrity algorithms selected (nea0, nia2)
* "Capability Exchange:" UE capabilities sent via UECapabilityInformation.

===Verifying UE Attach and Registration via Wireshark===

Wireshark is used to inspect and verify the signaling exchange between the UE, gNB, and Core Network during the 5G attach and registration procedure. The figure listed below captures NGAP and NAS messages exchanged during a successful UE attachment using the OAI UE and gNB connected to the OAI 5G Core.

The process begins with the NGSetupRequest and NGSetupResponse messages to establish the NG interface. This is followed by the UE initiating registration using the InitialUEMessage which encapsulates a NAS Registration Request. The core responds with a sequence of NAS security procedures, including Authentication Request, Authentication Response, Security Mode Command, and Security Mode Complete.

Once NAS security is established, the UE capabilities are exchanged using the UECapabilityInformation message. The AMF then sends the InitialContextSetupRequest, followed by the UE's InitialContextSetupResponse. Finally, a PDU Session Resource Setup Request and corresponding PDU Session Resource Setup Response are exchanged, completing the end-to-end attach and session setup.

This packet trace confirms successful synchronization, NAS registration, and PDU session establishment for end-to-end IP connectivity.

[[File:Wireshark_Packet_Captures.png|center|900px|Wireshark capture showing the NGAP and NAS signaling during UE attach and registration. Key steps: NG Setup, Initial UE Message, Authentication, Security Mode, Capability Exchange, Context Setup, and PDU Session Setup]]

===End-to-End Connectivity Verification via Ping===

To verify that the PDU session was successfully established and that end-to-end IP connectivity exists between the UE and the Data Network (DN), a simple ICMP ping test was performed. The external data network (DN) container within the core system was used to ping the IP address allocated to the UE by the AMF/SMF.

From the CN external DN container, ping the UE's IP address.

    <syntaxhighlight lang="bash">
    sudo docker exec -it oai-ext-dn ping 10.0.0.5
    </syntaxhighlight>

The following response indicates successful packet transmission and reception:

    <syntaxhighlight lang="text">
    64 bytes from 10.0.0.5: icmp_seq=1 ttl=63 time=35.0 ms
    64 bytes from 10.0.0.5: icmp_seq=2 ttl=63 time=34.4 ms
    64 bytes from 10.0.0.5: icmp_seq=3 ttl=63 time=33.1 ms
    ...
    --- 10.0.0.5 ping statistics ---
    7 packets transmitted, 7 received, 0% packet loss
    </syntaxhighlight>

This ping test confirms the following.
* The UE successfully registered and established a PDU session.
* The Core Network (SMF and UPF) correctly forwarded traffic to the UE.
* Routing and tunnel interfaces (e.g., oaitun_ue1) are functioning as expected.

===iPerf Downlink (DL) Testing===

To verify the downlink performance between the 5G Core Network (CN) and the UE (OAI UE using USRP), the iperf tool is used. The following setup is followed.

* The iPerf server was started on the UE.
* The iPerf client was launched on the CN or gNB machine depending on the deployment scenario.

====Step 1: Start iPerf Server on UE====

The UE (with IP address 10.0.0.5) listens for incoming UDP packets using the following command:

    sudo iperf -s -i 1 -u -B 10.0.0.5

This binds the server to the tunnel interface of the UE.

====Step 2: Start iPerf Client on CN/gNB====

The CN or gNB machine runs the following command to generate UDP traffic toward the UE:

    sudo docker exec -it oai-ext-dn iperf -c 10.0.0.5 -u -b 10M --bind 192.168.70.135

* -c 10.0.0.5: Destination IP address of the UE.
* -u: Specifies UDP mode.
* -b 10M: Bandwidth of 10 Mbps.
* --bind 192.168.70.135: Bind the client to the CN IP.

====Result Output====

Example client-side output:

    Client connecting to 10.0.0.5, UDP port 5001
    Sending 1470 byte datagrams
    [  1] 0.0000-10.0018 sec  12.5 MBytes  10.5 Mbits/sec
    [  1] Server Report:
    [  1] 0.0000-10.0005 sec  12.5 MBytes  10.5 Mbits/sec   0.726 ms 0/8920 (0%)

Example server-side output (UE):

    [  1] 0.0000-1.0000 sec  1.25 MBytes  10.5 Mbits/sec   0.703 ms 0/893 (0%)
    [  1] 1.0000-2.0000 sec  1.25 MBytes  10.5 Mbits/sec   0.819 ms 0/892 (0%)
    ...
    [  1] 9.0000-10.0000 sec  1.25 MBytes  10.5 Mbits/sec   0.729 ms 0/893 (0%)
    [  1] 0.0000-10.0005 sec  12.5 MBytes  10.5 Mbits/sec   0.727 ms 0/8920 (0%)

These results confirm the following points.

* The downlink data rate is consistent at 10.5 Mbps.
* No packet loss is observed.
* Jitter remains under 1 ms, indicating a stable connection.

===iPerf Uplink (UL) Testing===

For the uplink test, the iperf client is executed on the UE machine (OAI UE with USRP), and the server is run on the Core Network (CN) side. This allows us to measure the UE's ability to send data to the network.

====Step 1: Start iPerf Server on CN====

Run the following command on the CN machine (inside the "oai-ext-dn" container). This will bind the server to the CN's IP address:

    sudo docker exec -it oai-ext-dn iperf -s -i 1 -u -B 192.168.70.135

where:
* -s: Start as server.
* -i 1: Interval between periodic bandwidth reports.
* -u: Use UDP protocol.
* -B 192.168.70.135: Bind to CN interface IP.

====Step 2: Start iPerf Client on UE====

On the UE side (with tunnel interface IP address such as 10.0.0.5), run the following command to initiate UDP traffic toward the CN.

    iperf -c 192.168.70.135 -u -b 10M --bind 10.0.0.5

where:
* -c 192.168.70.135: Destination IP address of the CN.
* -u: Use UDP protocol.
* -b 10M: Transmit at 10 Mbps.
* --bind 10.0.0.5: Source IP from the UE tunnel interface.

====Expected Output====

On the CN side (server), the output should resemble:

    Server listening on UDP port 5001
    [  1] local 192.168.70.135 port 5001 connected with 10.0.0.5 port 37649
    [ ID] Interval       Transfer     Bandwidth        Jitter   Lost/Total Datagrams
    [  1] 0.0000-1.0000 sec  1.25 MBytes  10.5 Mbits/sec   0.703 ms 0/893 (0%)
    ...
    [  1] 0.0000-10.0000 sec 12.5 MBytes 10.5 Mbits/sec   0.727 ms 0/8920 (0%)

This confirms the following points.
* Stable uplink throughput from the UE to the CN.
* Low jitter and no packet loss.

==Installing, Configuring, and Running the COTS UE System==

===Quectel RM520N — 5G NR Sub-6 GHz Modem Module===

The Quectel RM520N is a compact, industrial-grade 5G modem optimized for IoT and eMBB applications.

Its key features are:
* Supports both 5G Standalone (SA) and Non-Standalone (NSA) modes compliant with 3GPP Release 16.
* Standard M.2 form factor; migration-friendly with RM50xQ, EM06 (LTE-A Cat 6), EM12 (Cat 12), EM160R-GL (Cat 16).
* Ultra-compact size: 30mm × 52mm × 2.3mm.
* Supported data rates:
** SA: up to 2.4 Gbps DL, 900 Mbps UL
** NSA: up to 3.4 Gbps DL, 550–600 Mbps UL
* Multi-mode operation: 5G NR, LTE-A, and 3G/WCDMA.
* Operating Temperature:
** Standard: –30°C to +75°C
** Extended: –40°C to +85°C
* Global carrier support across mainstream operators.

===Configuring the SIM Card===

When using a 5G wireless modem module or a COTS handset, a SIM card is required. (If a USRP runs the OAI UE softmodem, then a SIM card is not required.)

The SIM used in this reference architecture is from [https://open-cells.com/index.php/sim-cards/ Open-Cells], and is shown in the figure listed below. The ADM code is printed directly on the SIM itself.

[[File:Open_Cell_Sim_Card.jpg|center|600px|Open-Cells programmable SIM card (ADM: 0C028785)]]

Insert the nano SIM into the reader/writer and plug it into the UE computer. Use program_uicc from Open-Cells ([https://open-cells.com/index.php/uiccsim-programing/ link]) to read and program the SIM.

    <syntaxhighlight lang="bash">
    sudo ./program_uicc --adm 0C028785
    </syntaxhighlight>

    <syntaxhighlight lang="text">
    Existing values in USIM
    ICCID: 8933006110000000785
    USIM IMSI: 2089201000001785
    PLMN selector: 0x02f8297c
    Operator Control PLMN selector : 0x02f8297c
    Home PLMN selector : 0x02f8297c
    USIM MSISDN: 00000785
    USIM Service Provider Name: OpenCells785
    
    Setting new values
    No Key or not 32 char length key
    No OPc or not 32 char length key
    
    Reading UICC values after uploading new values
    ICCID: 8933006110000000785
    USIM IMSI: 2089201000001785
    PLMN selector: 0x02f8297c
    Operator Control PLMN selector : 0x02f8297c
    Home PLMN selector : 0x02f8297c
    USIM MSISDN: 00000785
    USIM Service Provider Name: open cells
    </syntaxhighlight>


The output listed above shows the process of programming a USIM card using the program_uicc tool with an ADM (Administrative) key.

* Existing values in USIM: The tool first reads the current values from the SIM card:
** ICCID – Integrated Circuit Card Identifier (unique SIM serial number).
** IMSI – International Mobile Subscriber Identity, used for network authentication.
** PLMN selector – Public Land Mobile Network identifiers.
** MSISDN} – Mobile Subscriber Integrated Services Digital Network number (the subscriber's phone number).
** Service Provider Name} – Operator branding.

* Setting new values: The tool attempted to write new authentication values, but the log indicates missing or incorrectly formatted Key and OPc (Operator Code). These must be 32-character (128-bit) hex values.

* Reading values after update: The tool re-reads the SIM data. Since the keys were not provided correctly, the identifiers (ICCID, IMSI, PLMN, MSISDN) remain unchanged, but the service provider name changed slightly (to Open-Cells).

This confirms that while the SIM parameters were read successfully, the authentication keys (K and OPc) were not updated due to incorrect input format.

====Successful UICC Programming and Authentication====

    <syntaxhighlight lang="text">
    sudo ./program_uicc --adm 0C028785 --imsi 001010100001101 --key 0C0A34601D4F07677303652C0462535B --opc 63bfa50ee6523365ff14c1f45f88737d --authenticate --noreadafter
    
    Existing values in USIM
    ICCID: 8933006110000000785
    USIM IMSI: 2089201000001785
    PLMN selector: 0x02f8297c
    Operator Control PLMN selector : 0x02f8297c
    Home PLMN selector : 0x02f8297c
    USIM MSISDN: 00000785
    USIM Service Provider Name: open cells
    
    Setting new values
    Succeeded to authentify with SQN: 64
    Set HSS SQN value as: 96
    
    sudo ./program_uicc --adm 0 C028785
    
    Existing values in USIM
    ICCID: 8933006110000000785
    USIM IMSI: 001010100001101
    PLMN selector: 0x00f1107c
    Operator Control PLMN selector : 0x00f1107c
    Home PLMN selector : 0x00f1107c
    USIM MSISDN: 00000785
    USIM Service Provider Name: open cells
    
    Setting new values
    No Key or not 32 char length key
    No OPc or not 32 char length key
    
    Reading UICC values after uploading new values
    ICCID: 8933006110000000785
    USIM IMSI: 001010100001101
    PLMN selector: 0x00f1107c
    Operator Control PLMN selector : 0x00f1107c
    Home PLMN selector : 0x00f1107c
    USIM MSISDN: 00000785
    USIM Service Provider Name: open cells
    </syntaxhighlight>

The above listing demonstrates the process of reprogramming a programmable SIM card.

* Initial values: The SIM originally contained IMSI 2089201000001785 and PLMN selector 0x02f8297c. The Service Provider Name was shown as "open cells".

* Programming new values: The command provides a new IMSI (001010100001101), along with a valid 128-bit authentication Key and OPc. Authentication succeeded, with the sequence number (SQN) updated from 
    64 to 96, confirming that the SIM accepted the new credentials.

* Verification after update: A subsequent read of the SIM shows the new IMSI and updated PLMN selector (0x00f1107c). Since no Key or OPc values were passed in this second command, the tool reported:

    No Key or not 32 char length key
    No OPc or not 32 char length key

This does not indicate an error.  It only indicates that no new keys were provided for update.
    
* Outcome: The SIM is now reprogrammed with a new IMSI and valid authentication parameters, making it suitable for use in 4G/5G testbeds (e.g., Open5GS, srsRAN, or OAI).

Ensure that the values being programmed into the SIM card match the corresponding values entered in the SQL database on the CN machine. The values of primary importance are listed in the table below.

{| class="wikitable"
|+ Primary Configuration Parameters for UE, gNB, CN
! Parameter !! UE !! gNB !! CN
|-
| IMSI || 001010100001101 || MCC: 208, MNC: 92 || 001010100001101
|-
| MSISDN || 00000101 || — || 00000101
|-
| IMEI || 863305040549338 || — || 863305040549338
|-
| Key (K) || 0C0A34601D4F07677303652C0462535B || — || 0C0A34601D4F07677303652C0462535B
|-
| OPc || 63bfa50ee6523365ff14c1f45f88737d || — || 63bfa50ee6523365ff14c1f45f88737d
|}

====Serial Connection to the Module via Minicom====

Attach all four antennas to the Quectel wireless modem module. Then, mount the Quectel module into the M.2 connector slot on the carrier board. Then, connect the carrier board to the UE computer via a USB 3.0 port.

We will use Minicom to communicate with the Quectel module over a USB serial connection. Run which minicom to verify that Minicom is already installed. If not, then run the command listed below to install it.

    sudo apt-get install minicom

Once the Quectel module is plugged in, the Linux operating system should create several USB serial devices which can be used to communicate with the module. The default device should be /dev/ttyUSB0. Run the command listed below to start a Minicom serial console session with the Quectel device.

    sudo minicom /dev/ttyUSB0

Note that in order to exit Minicom, type Ctrl-A, then "X".

====Switching a Quectel Module to ROW Commercial MBN====

Step 0: Inspect Current MBN Profiles by running:

    AT+QMBNCFG="list"

Some example output is listed below.

    [2025-08-19_10:45:07:370]at+qmbncfg="list"
    [2025-08-19_10:45:07:410]+QMBNCFG: "List",0,1,1,"Volte_OpenMkt-Commercial-CMCC",0x0A012010,202209221
    [2025-08-19_10:45:07:410]+QMBNCFG: "List",1,0,0,"ROW_Commercial",0x0A010809,202401151
    [2025-08-19_10:45:07:410]+QMBNCFG: "List",2,0,0,"ROW_Generic_3GPP_PTCRB_GCF",0x0A01FF09,202203161
    [2025-08-19_10:45:07:410]+QMBNCFG: "List",3,0,0,"TEF_Spain_Commercial",0x0A010C00,202302071
    [2025-08-19_10:45:07:425]+QMBNCFG: "List",4,0,0,"FirstNet",0x0A015300,202206171
    [2025-08-19_10:45:07:425]+QMBNCFG: "List",5,0,0,"Rogers_Canada",0x0A014800,202303141
    [2025-08-19_10:45:07:425]+QMBNCFG: "List",6,0,0,"Bell_Canada",0x0A014700,202111051
    [2025-08-19_10:45:07:425]+QMBNCFG: "List",7,0,0,"Telus_Jasper_Canada",0x0A01F900,202304281
    [2025-08-19_10:45:07:457]+QMBNCFG: "List",8,0,0,"Telus_Consumer_Canada",0x0A01FA00,202304281
    [2025-08-19_10:45:07:457]+QMBNCFG: "List",9,0,0,"Commercial-Sprint",0x0A010204,202111051
    [2025-08-19_10:45:07:457]+QMBNCFG: "List",10,0,0,"Commercial-TMO",0x0A01050F,202402061
    [2025-08-19_10:45:07:457]+QMBNCFG: "List",11,0,0,"VoLTE-ATT",0x0A010335,202206171
    [2025-08-19_10:45:07:472]+QMBNCFG: "List",12,0,0,"CDMAless_Private-Verizon",0x0A01FD28,202304271
    [2025-08-19_10:45:07:472]+QMBNCFG: "List",13,0,0,"CDMAless-Verizon",0x0A010126,202304251
    [2025-08-19_10:45:07:472]+QMBNCFG: "List",14,0,0,"Swiss-Comm",0x0A010411,202304261
    [2025-08-19_10:45:07:472]+QMBNCFG: "List",15,0,0,"Telia_Sweden",0x0A012400,202111051
    [2025-08-19_10:45:07:472]+QMBNCFG: "List",16,0,0,"TIM_Italy_Commercial",0x0A012B00,202111051
    [2025-08-19_10:45:07:472]+QMBNCFG: "List",17,0,0,"France-Commercial-Orange",0x0A010B21,202401081
    [2025-08-19_10:45:07:472]+QMBNCFG: "List",18,0,0,"Commercial-DT-VOLTE",0x0A011F1F,202212061
    [2025-08-19_10:45:07:472]+QMBNCFG: "List",19,0,0,"Germany-VoLTE-Vodafone",0x0A010449,202401201
    [2025-08-19_10:45:07:488]+QMBNCFG: "List",20,0,0,"UK-VoLTE-Vodafone",0x0A010426,202401201
    [2025-08-19_10:45:07:488]+QMBNCFG: "List",21,0,0,"Commercial-EE",0x0A01220B,202111051
    [2025-08-19_10:45:07:488]+QMBNCFG: "List",22,0,0,"Optus_Australia_Commercial",0x0A014400,202111051
    [2025-08-19_10:45:07:488]+QMBNCFG: "List",23,0,0,"Telstra_Australia_Commercial",0x0A010F00,202311071
    [2025-08-19_10:45:07:488]+QMBNCFG: "List",24,0,0,"Commercial-LGU",0x0A012608,202111051
    [2025-08-19_10:45:07:488]+QMBNCFG: "List",25,0,0,"Commercial-KT",0x0A01280B,202308031
    [2025-08-19_10:45:07:488]+QMBNCFG: "List",26,0,0,"Commercial-SKT",0x0A01270A,202111051
    [2025-08-19_10:45:07:488]+QMBNCFG: "List",27,0,0,"Commercial-Reliance",0x0A011B0C,202210211
    [2025-08-19_10:45:07:504]+QMBNCFG: "List",28,0,0,"Commercial-SBM",0x0A011C0B,202401231
    [2025-08-19_10:45:07:504]+QMBNCFG: "List",29,0,0,"Commercial-KDDI",0x0A010709,202401191
    [2025-08-19_10:45:07:504]+QMBNCFG: "List",30,0,0,"Commercial-DCM",0x0A010D0D,202312201
    [2025-08-19_10:45:07:504]+QMBNCFG: "List",31,0,0,"VoLTE-CU",0x0A011561,202310181
    [2025-08-19_10:45:07:519]+QMBNCFG: "List",32,0,0,"VoLTE_OPNMKT_CT",0x0A0113E0,202312141
    [2025-08-19_10:45:07:519]
    [2025-08-19_10:45:07:519]OK

Each line has the structure:

    +QMBNCFG: "List", \#idx, Enabled, Selected, "Name", ConfigID, Version

where:
* #idx: profile index in the list (e.g., 0, 1, 2, ...).
* Enabled: 1 if this MBN is enabled, else 0.
* Selected: 1 if currently selected/active, else 0.
* Name: human-readable profile name, e.g., ROW_Commercial.
* ConfigID: hexadecimal configuration identifier.
* Version: profile build/version stamp.

In your capture, index 0 (Volte_OpenMkt-Commercial-CMCC) shows Enabled=1, Selected=1, meaning it is active. The desired ROW_Commercial (index 1) shows 0,0 which means present but not active.

Step 1--4: Switch to ROW_Commercial.

Execute the following commands in order:

    AT+QMBNCFG="Deactivate"
    AT+QMBNCFG="Autosel",0
    AT+QMBNCFG="Select","ROW_Commercial"

Explanation:
* "Deactivate": cleanly deactivates the currently active MBN.
* "Autosel",0: disables automatic re-selection so your manual choice sticks.
* "Select","ROW_Commercial": explicitly selects the global commercial profile.

Step 5: Verify Selection.

Re-run the list command:

    AT+QMBNCFG="list"

We expect to see the ROW_Commercial line with Enabled=1, Selected=1, as follows:

    +QMBNCFG: "List",1,1,1,"ROW_Commercial",0x0A010809,202401151   <-- active now

Step 6: Reboot/Power-Cycle the Module.

Either physically re-plug the device or issue a software reboot with the command listed below.

    AT+CFUN=1,1

After the reboot, ROW_Commercial} should remain active.

Troubleshooting Tips:
* If Autosel is enabled (AT+QMBNCFG="Autosel",1), the module may override your manual selection; keep it 0 while switching.
* If selection fails, repeat "Deactivate" and then "Select" again, followed by a reboot.
* Ensure SIM/network restrictions do not force a carrier-specific MBN.

One-Line Batch (Optional)

If your terminal supports sending multiple commands with brief delays, you can script:

    AT+QMBNCFG="Deactivate"
    AT+QMBNCFG="Autosel",0
    AT+QMBNCFG="Select","ROW_Commercial"
    AT+QMBNCFG="list"

Quectel Module Configuration via AT Commands

We use {Minicom to issue AT Commands to the 5G modem module.

There are informative articles about AT commands available online. The AT commands listed below are essential to control and configure the Quectel module. Note that AT commands are generally not case-sensitive.

Execute the following commands in order:


    AT+GMR

Displays the current firmware version number.

    AT+CIMI

Displays the IMSI of the (U)SIM.

    AT+GSN

Displays the IMEI of the (U)SIM.

    AT+QMBNCFG="select","ROW\_Commercial"

Unlocks the Quectel module for commercial use.

    AT+QNWPREFCFG="nr5g_band"

Displays the configured 5G NR frequency bands.

    AT+QNWPREFCFG="mode_pref"

Displays the current 5G NR mode.

    AT+QNWPREFCFG="mode\_pref",nr5g

Sets the preferred mode to 5G NR SA (Standalone).

    AT+QNWPREFCFG="nr5g\_disable_mode",0

Enables 5G NR operations.

    AT+CGDCONT=1,"IP","oai","0.0.0.0",0,0

Specifies the PDP context parameters for a specific context ID.
    
    AT+CFUN=0

Sets the module to minimum functionality.

    AT+CFUN=1

Restores the module to full functionality.

====Verifying the Operation with AT Commands====

After configuring the Quectel 5G module, we verify its operational status using Minicom by executing a set of AT commands and analyzing their outputs.

    AT+COPS?

This command checks the current network operator and registration status.

Expected Output:

    +COPS: 0,0,"208 92 open cells",11

Field Descriptions:
* Field 1 (0): Operator availability. 0 indicates unknown.
* Field 2 (0): Operator selection mode. 0 indicates automatic selection.
* Field 3 ("208 92 open cells"): Operator name (MCC 208, MNC 92) indicating Open-Cells as the pre-configured operator.
* Field 4 (11): Access technology. 11 represents 5G NR connected to a 5G Core Network (5GC).

Next run the following command.

    AT+C5GREG?

This command displays the 5G registration status.

Expected Output:
    +C5GREG: 2,1,"1","0",11,16,"01.00007B;00.000000:01.00000C;00.000000"

Field Descriptions:
* Field 1 (2): Mode of reporting. 2 indicates unsolicited mode (updates are pushed automatically).
* Field 2 (1): Registration status. 1 indicates registered on the home network.
* Field 3 ("1"): Tracking Area Code (TAC) in hexadecimal format.
* Field 4 ("0"): Cell ID in hexadecimal format.
* Field 5 (11): Indicates 5G NR access mode connected to a 5G CN.
* Field 6 (16): Length (in octets) of allowed NSSAI information.
* Field 7: 01.00007B;00.000000:01.00000C;00.000000 denotes allowed NSSAI (Network Slice Selection Assistance Information).

The Connectivity testing of the COTS UE with OAI gNB and CN using ping and iperf can be done in the same way as explained in earlier sections.

To evaluate the system performance, we conducted a DL throughput test using the commercial OOKLA Speedtest application on a COTS UE. The measured performance metrics were as follows:

* Downlink Throughput: 126 Mbps
* Uplink Throughput: 16 Mbps
* Latency: Approximately 50 ms

These results indicate successful connectivity and reasonable performance of the 5G system under test.

====Multi-UE 5G Testbed Setup with OAI gNB, OAI UE, and USRP X410====

[[File:multi_ue_connection.png|thumb|800px|center|Multi-UE connection setup using USRP X410, OAI gNB, OAI UE, and COTS UE]]

The figure above illustrates a comprehensive testbed for evaluating 5G NR SA (Standalone) operation with both software-defined and commercial UEs. The key components of the setup are as follows:

* OAI gNB: A monolithic gNB implemented using OAI and running on a high-performance server (Intel Xeon w7-2495X, 24 Cores @ 2.5 GHz) with Ubuntu 22.04 and UHD 4.8. It is connected to a USRP X410 via dual SFP+ interfaces.

* OAI Core Network: The OAI 5G Core (develop branch) runs on the same machine as the OAI gNB, enabling a complete end-to-end standalone deployment.

* USRP X410 (RF Front End): Acts as the shared RF front-end for both the gNB and UEs. It interfaces with both the gNB and the UEs through SFP+ (data) and SMA (RF) connections.

* 6:1 and 2:1 RF Splitters: These allow the RF signal from the gNB (X410) to be distributed to multiple devices. The 6:1 splitter distributes the signal to a COTS UE and to an OAI UE. A 30 dB attenuator is used to prevent RF front-end saturation.

* OAI UE: A monolithic UE running on a separate server with similar compute specifications (Intel Xeon w7-2495X, 24 Cores @ 2.5 GHz, Ubuntu 22.04, UHD 4.8). It connects to the X410 using SFP+ for data and SMA cables for RF.

* COTS UE: A commercial smartphone or module connected via SMA to the RF network. It is monitored using Minicom on a Linux machine for AT command interaction.

This configuration enables concurrent testing of both OAI-based and commercial UE performance in a controlled over-the-cable environment using shared RF and network resources.

====gNB Log Analysis for Dual UE Scenario====

The figure listed below shows the real-time log output from the OAI gNB during a 5G NR standalone test involving two connected UEs. The log output includes MAC and PHY-level statistics relevant to each UE, such as slot synchronization, signal strength, and buffer throughput.

[[File:Double_UE_connection_on_gnb_logs.png|thumb|800px|center|gNB log showing two UEs (RNTI 0x37a3 and 0x5a8c) connected simultaneously]]

The key observations are as follows:

* UE 0x37a3:
** Average RSRP: -98 dBm, SNR: 46.0 dB
** BLER (UL/DL): 0.0%, indicating excellent link quality
** NPRB: 5, Modulation/Coding Scheme (MCS): 7 (Qm = 2)

* UE 0x5a8c:
** Average RSRP: -82 dBm, SNR: ranging from 21.0 dB to 21.5 dB
** BLER: ranges between 0.05 to 0.11, indicating moderate link quality
** NPRB: 104, MCS: 18 (Qm = 6)

* LCID Breakdown:
** LCID 1: Small control data
** LCID 3 and 4: Carrying higher traffic load (e.g., 3773 TX / 6550 RX)
** LCID 5: Primary bearer – over 22 million TX and 31 million RX bytes

This log confirms that both UEs are successfully attached and transmitting data over multiple logical channels. The differences in BLER and NPRB indicate dynamic scheduling by the gNB based on real-time radio conditions.

====Wireshark Trace Analysis: Dual UE Registration and PDU Session Establishment====

The figure listed below presents a Wireshark capture filtered with the NGAP protocol, showcasing the successful registration and session setup of two UEs over a 5G Standalone (SA) network. The trace includes both NGAP and NAS signaling exchanged between the gNB (10.88.136.29) and the 5GC (192.168.70.132).

[[File:double_ue_connection_on_wireshark.png|thumb|800px|center|Wireshark capture showing NGAP procedures for dual UE connection]]

The main stages observed in the trace are as follows:

* NG Setup Procedure:
** NGSetupRequest from gNB to AMF, initiating the connection.
** NGSetupResponse from AMF to gNB, confirming the connection.

* UE Registration Procedures:
** InitialUEMessage, Authentication Request/Response, and Security Mode Command/Complete are exchanged for NAS authentication and security.
** Two separate UEs go through this process, indicating a multi-UE test scenario.

* UE Capability Exchange:
** UECapabilityInfoIndication is sent from the gNB to AMF.

* PDU Session Establishment:
** The AMF initiates PDU Session Resource Setup Request to the gNB.
** The gNB responds with PDU Session Resource Setup Response}.
** PDU Session Establishment Accept is observed in JSON/NAS payloads.

* Error Handling:
** One occurrence of Authentication Failure (Synch failure) is observed and immediately retried.

The trace confirms that both UEs are successfully authenticated and registered with the 5G Core Network, and are able to establish PDU sessions, and are interacting with both control plane (NGAP/NAS) and data plane (JSON PDU content).

==Connecting Google Pixel 9 to OAI gNB==

To validate 5G SA connectivity with OAI, a commercial off-the-shelf (COTS) smartphone — specifically the Google Pixel 9 — is connected to an OAI-powered 5G Standalone (SA) network.

This procedure involves provisioning a test SIM card, configuring the Access Point Name (APN), and verifying successful network registration.

==Step-by-Step Configuration===

# Insert OAI Test SIM  
Insert a custom test SIM card with the following parameters:
* MCC (Mobile Country Code): 001  
* MNC (Mobile Network Code): 01  
* PLMN: 00101 (test network)

# Configure APN Settings on Google Pixel 9  
Navigate through:  
<code>Settings → Network & Internet → Mobile Network → Access Point Names</code>

Then tap "Add APN" and enter:
* Name: <code>oai</code>
* APN: <code>oai</code>
* MCC: <code>001</code>
* MNC: <code>01</code>
* Bearer: Check only NR (5G)
* Save and select the new APN.

# Power on the OAI gNB  
Ensure that:
* The gNB is configured with the same PLMN (001-01)
* The OAI Core Network (CN) is running and reachable.

# Verify Connection Status  
After a few seconds, the Pixel 9 should:
* Display the operator name as <code>00101 - open cells</code>
* Show the 5G NR icon on the status bar

The figure listed below shows an example of the Google Pixel 9 connected to OAI gNB.

[[File:mobile_phone_connectivity.png|center|800px|thumb|Connection stages of Google Pixel 9 to OAI gNB — (Left) No service; (Middle) Registered to test PLMN 00101; (Right) 5G NR icon confirms successful attachment.]]

==Technical Support==

The primary methods of technical support are the mailing lists.

===USRP Mailing List===

The focus of the [https://lists.ettus.com/list/usrp-users.lists.ettus.com usrp-users mailing list] is for questions and discussions about the NI/Ettus USRP hardware as well as the UHD and RFNoC software.

The archives for the usrp-users mailing list can be found [https://lists.ettus.com/empathy/list/usrp-users.lists.ettus.com here].

===OAI Mailing List===

The focus of the [https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/MailingList openair5g-user mailing list] is for questions and discussions from users about the [https://gitlab.eurecom.fr/oai/openairinterface5g OpenAirInterface (OAI) software stack] from [https://openairinterface.org/ Eurecom].

Additional information about the OAI mailing lists can be found [https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/MailingList here] and [https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/AskQuestions here].

The archives for the openair5g-user mailing list can be found [http://lists.eurecom.fr/sympa/arc/openair5g-user here].


[[Category:Application Notes]]